Crescendo Lab 文件
正體中文
註冊開始用

部署失敗排除

版本失敗時,先在版本頁看原因。內容被拒收就修正後重新上傳;平台出錯就直接重試。

最後更新

內容被拒收#

你看到的原因怎麼修
無法判斷如何建置這份原始碼zip 最上層沒有 package.json、index.html 或 Dockerfile。從專案資料夾裡面壓縮,或見從原始碼部署。
專案是服務,但上傳的內容被當成一般檔案zip 最上層沒有 Dockerfile 或設定檔(package.json、go.mod、pyproject.toml、requirements.txt、setup.py):程式在子資料夾裡,例如 backend/。到「設定 › 建置設定」把根目錄 Root Directory 設成那個資料夾,再部署一次。失敗訊息會列出可能的資料夾。
找不到 index.html壓縮的是資料夾本身,不是資料夾裡的內容。進到資料夾裡再壓縮,讓 index.html 在最上層。
檔案裡有密鑰上傳的內容裡有像 API 金鑰或權杖的字串。從檔案移除,換一把新的金鑰,改在專案的「設定」輸入,再重新上傳。
映像檔沒有 CMDDockerfile 沒有啟動指令。加上 CMD 或 ENTRYPOINT。
USER 不存在Dockerfile 指定了映像檔裡沒有的使用者。改用數字 uid,或映像檔裡已有的使用者,例如 node。
嚴重漏洞映像檔裡的套件有已知的嚴重漏洞。把套件升級到掃描結果寫的修正版本,或換成已包含該版本的新基底映像檔。

建置執行了但失敗#

失敗代碼是 buildFailed:建置開始了,但其中一個步驟失敗。失敗資訊會顯示失敗的步驟、它印出的內容,以及它結束時的 exit code。在主控台,看版本頁失敗訊息裡的記錄摘錄;透過 MCP,看 sites_deploy_status 的 failure.buildLog。

Exit code原因怎麼修
127建置執行了一個沒有安裝的指令。例如建置會執行 tsc,但 package.json 的 dependencies 和 devDependencies 都沒有 typescript。加上那個套件,或從建置指令拿掉這個指令。

修正專案後再部署一次,也就是重新上傳:重試同一個版本只會以同樣的方式再失敗一次。

版本預覽網址沒有回應#

  • 網頁(靜態網站):版本發佈之前,它的預覽網址會回 404 site not found。
  • 服務:從未上線過的版本不會啟動,所以在它上線之前,預覽網址會回 502 service unavailable,並帶標頭 X-Sites-Refusal: relay-unavailable。這不是建置失敗。

上線後請馬上打開對外網址確認。如果不正常,修正後再部署一次。想在訪客遇到之前就發現問題,可以先在另一個環境(例如 staging)試過版本。

等待確認#

有檢查項目設成「會先問過你」並且找到問題時,版本會停在「等待確認」。看過掃描結果後,你可以決定照樣發佈。高風險漏洞就屬於這一類,修法和嚴重漏洞相同,升級之後提示才會消失。

版本一直沒有就緒#

建置成功、也上線了,但「執行」分頁的執行個體一直沒有就緒,多半是通訊埠的問題:伺服器沒有監聽平台給的通訊埠。

  1. 看版本頁有沒有 imagePortsAmbiguous 提示。
  2. 讓伺服器監聽環境變數 PORT,或到「設定 › 執行設定 › 通訊埠」填伺服器實際監聽的通訊埠。
  3. 按「重新啟動服務」。

啟動後不斷重新啟動#

最常見的原因是程式寫入了 /tmp 以外的路徑,而檔案系統是唯讀的。把寫入位置改到 /tmp,見容器執行合約。

請求回 504,或串流中途停住#

504 帶著 X-AgentLab-Error: platform-timeout,或串流回應每次都在同樣的秒數停住,就是請求碰到了專案的請求最長時間。把時限調長,也不要讓程式自動重送;見請求最長時間。

平台出錯#

失敗原因是平台本身時,不需要修改內容,也不用重新上傳,直接重試同一個版本。

一小時內沒有建置機器接手的版本,會自動在原本的位置重新排隊一次;再過一小時仍沒有接手,才會顯示已過期。在上傳後一天內可以用同樣方式重試;超過一天就要重新上傳。

如果版本是誤送的,或不想等它,趁它還在排隊時取消,見取消排隊中的建置。

還是找不到原因#

  • 到「執行」分頁看執行個體的狀態和最近的記錄。
  • 到版本頁看平台留下的提示。
  • 請已連接 Agent Lab MCP 的 AI 工具讀部署狀態幫你判斷。它讀到的失敗原因和這一頁的代碼相同。