故障排查

常見問題、原因和解決方法。大多數問題都從同一個地方入手：服務的 日誌，裡面有建置輸出和應用自己的輸出（日誌）。

伺服器

初始化時連線失敗

• 連線逾時或被拒絕：雲端服務供應商的防火牆或安全組沒有開放 SSH 連接埠，或者位址、連接埠填錯了。初始化期間允許任意來源存取 SSH 連接埠，完成後可以關閉（伺服器需求）。
• 認證失敗：檢查 SSH 使用者。雲端映像檔通常禁止 root 登入，請使用 ubuntu、debian 或 ec2-user。金鑰必須是私鑰，不是 .pub 檔案，並且不能有密碼短語（新增伺服器）。
• sudo 要求輸入密碼：使用者需要能免密 sudo，或者改用 root 連線。
• 主機金鑰已變化：伺服器指紋與第一次初始化時不同，Zenavo 會拒絕連線。如果你是有意重灌了機器，請移除伺服器後重新新增；否則先查明原因再繼續。

初始化在安裝過程中失敗

檢視伺服器 狀態 分頁中初始化日誌的最後幾行。常見原因：

• 80 或 443 連接埠被佔用，佔用者是 Docker、Nginx、Apache 或其他 Web 伺服器。伺服器應當專用於 Zenavo；停止並禁用它們，然後點選 重試初始化。
• 記憶體或磁碟不足：至少 2 GB 記憶體和 20 GB 可用磁碟（伺服器需求）。
• 在中國大陸下載逾時：日誌會顯示初始化選擇了哪些安裝源（中國大陸的伺服器）。
• Agent 一直連不上：伺服器需要能出站存取 Zenavo 控制台的 HTTPS（443 連接埠）。

重試時會跳過已經完成的步驟。

伺服器顯示離線

Zenavo 幾分鐘沒有收到伺服器 agent 的訊息。上面的專案會繼續執行，只有部署和即時資料會暫停。檢查機器是否開機、能否出站存取 HTTPS、記憶體或磁碟是否用盡。agent 恢復後，狀態會自動回到 執行中。如果沒有恢復，設定 → 執行初始化 會重新安裝 agent，不影響正在執行的內容（管理伺服器）。

建置

Zenavo 識別錯了語言，或沒有識別出建置計劃

zbpack 根據根目錄中的檔案進行識別。在 monorepo 中，把 根目錄 設為應用所在的資料夾。想完全控制建置，可以新增 Dockerfile，或者設定 zbpack 選項，例如 ZBPACK_BUILD_COMMAND 和 ZBPACK_START_COMMAND（建置方案）。

建置失敗

開啟 日誌 → 建置日誌。最後一條錯誤通常就是原因：缺少依賴、建置指令碼失敗，或者缺少建置需要的值。變數 分頁中的變數不會自動傳給建置：建置需要哪些，就把它們作為建置參數引用。可以在本機用 docker build . 跑一遍同樣的建置，區分是應用的問題還是平台的問題。

建置在排隊或被中止

• 等待建置機：你的方案允許的同時建置數已經用滿，或者共享建置機正忙（建置佇列）。
• 逾時：建置超過方案的單次建置上限後會被中止（用量與帳單）。
• 被拒絕：工作空間本月的建置分鐘數已用完。部署預先建置好的映像檔不受影響。

部署

部署一直不健康

新實例啟動了，但始終沒有透過健康檢查；舊實例會繼續提供服務。通常是因為：

• 應用只監聽 localhost 或固定連接埠。 請監聽 0.0.0.0 和 PORT 變數（框架）。
• 連接埠不對。 服務在 網路 中的連接埠必須是應用實際監聽的連接埠。
• 健康檢查路徑返回 404，或者應用需要更長的啟動時間。修正路徑，或者調大啟動等待時間。

失敗的部署會顯示最後一次檢查的原因和實例最新的日誌。

服務反覆崩潰或被暫停

容器啟動後立刻退出。在 日誌 中檢視錯誤：缺少變數、連不上資料庫，或啟動時崩潰。因記憶體超限被終止的服務也會重啟：請調高它的記憶體限制（服務設定）。重啟次數達到崩潰限制後，Zenavo 會暫停服務；解決原因後恢復服務或重新部署。

因映像檔傳輸被拒絕部署

工作空間達到了消費上限，或者用完了 Free 方案包含的映像檔傳輸。正在執行的服務不受影響。提高上限或升級方案即可（映像檔傳輸與消費上限）。

服務存取不到另一個服務

使用對方的內部主機名稱 <hostname>.zenavo.internal 和它監聽的連接埠，不要用公開網路網域或 localhost。兩個服務必須在同一個專案中。對方服務 網路 分頁的 內部 下顯示了這個位址（內部網路通訊）。

網域與 HTTPS

憑證一直是等待中

Let's Encrypt 還沒能驗證這個網域。把滑鼠懸停在服務 概覽 中的 等待中 上可以看到原因。通常是：

• DNS 記錄還沒有指向這台伺服器。 用 dig +short app.example.com 檢查，輸出應該是伺服器的 IP 位址。新記錄可能需要一段時間才能生效。
• 80 連接埠沒有開放。 Let's Encrypt 透過 HTTP 驗證網域。
• 開啟了 Cloudflare 代理，並且 SSL 設為 Flexible。請改為 Full (strict)，或者在憑證籤發之前關閉代理。

狀態大約每分鐘重新整理一次（網域與 HTTPS）。

網域顯示 404 或錯誤頁面

• 404 page not found：網域已經解析到伺服器，但沒有服務繫結它。在服務的 網路 分頁中繫結。
• Bad gateway 或 Service unavailable：網域已經繫結，但服務沒有執行，或者它監聽的連接埠不是網域路由到的連接埠。

帳號與權限

無法新增伺服器或部署

請先驗證電子郵件：開啟 Zenavo 發給你的郵件中的連結，或者在 帳號設定 中重新傳送（你的帳號）。觀察者（Viewer）不能部署或修改任何內容，請讓團隊管理員把你的角色改為成員（團隊與角色）。

丟失了兩步驟驗證裝置

使用復原碼登入（兩步驟驗證）。如果沒有復原碼，請用帳號電子郵件聯絡 info@zenavo.app。

仍然無法解決？

發郵件到 info@zenavo.app，附上專案或伺服器 ID（在 設定 中複製）、發生的時間，以及日誌中的內容。請不要傳送密碼、金鑰或變數值。