疑難排解
常見問題與解決方法。
開始之前：請先查看 KamuiDash 服務狀態，確認問題是否出在我們這邊。進行中的事件與預定維護都會公告在那裡。
部署相關問題
建置失敗
症狀：部署後狀態顯示為「error」
確認方式： 1. 開啟應用程式詳細畫面的「Deploy History」分頁 2. 選擇失敗的部署並檢查記錄
常見原因與解決方法：
| 原因 | 解決方法 |
|---|---|
| 安裝相依套件時發生錯誤 | 檢查 package.json、go.mod 等相依套件檔案 |
| 建置指令錯誤 | 檢查啟動前指令，並確認在本機可以正常執行 |
| Node.js 版本不符 | 在 package.json 的 engines 欄位指定版本 |
| 記憶體不足 | 升級規格（可用的規格請見規格與費用） |
Node.js 範例：
{
"engines": {
"node": ">=18.0.0"
}
}
健康檢查失敗
症狀：建置成功，但應用程式沒有變成「running」
確認方式： 1. 確認健康檢查端點是否正確 2. 檢查應用程式記錄中是否有錯誤
常見原因與解決方法：
| 原因 | 解決方法 |
|---|---|
| 端點不存在 | 實作一個 /health 端點 |
| 連接埠錯誤 | 監聽 PORT 環境變數指定的連接埠 |
| 啟動速度太慢 | 最佳化啟動流程 |
範例（Node.js）：
const PORT = process.env.PORT || 3000;
app.get('/health', (req, res) => {
res.status(200).json({ status: 'ok' });
});
app.listen(PORT, '0.0.0.0', () => {
console.log(`Server running on port ${PORT}`);
});
範例（Go）：
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusOK)
w.Write([]byte(`{"status":"ok"}`))
})
http.ListenAndServe("0.0.0.0:"+port, nil)
重新部署後變更沒有生效
請確認：
- 你是否 push 到了正確的分支？
- 建置是否成功？（請查看部署歷史）
- 清除瀏覽器快取
資料庫相關問題
無法連接資料庫
確認方式： 1. 確認資料庫狀態是否為「running」 2. 確認連線資訊（URL、主機、連接埠等）是否正確
常見原因與解決方法：
| 原因 | 解決方法 |
|---|---|
| 沒有設定環境變數 | 在應用程式設定中連接資料庫 |
| 資料庫正在啟動中 | 等待幾分鐘後再試 |
| 已達連線數上限 | 使用連線池並限制連線數 |
連線逾時
原因：閒置的連線在長時間沒有活動後會被逾時中斷
解決方法： - 使用連線池 - 設定連線的 keep-alive - 實作重試機制
const pool = new Pool({
host: process.env.DB_HOST,
port: parseInt(process.env.DB_PORT),
database: process.env.DB_NAME,
user: process.env.DB_USER,
password: process.env.DB_PASSWORD,
max: 10,
idleTimeoutMillis: 30000,
connectionTimeoutMillis: 2000,
});
CLI 相關問題
出現「not logged in」錯誤
原因：尚未驗證，或權杖已過期
解決方法：
kamui login
出現「session expired」錯誤
解決方法：
kamui logout
kamui login
瀏覽器沒有自動開啟
解決方法：請手動複製終端機顯示的網址，貼到瀏覽器中開啟
出現「project not found」錯誤
請確認：
1. 專案名稱或 ID 是否正確？
2. 用 kamui projects list 確認
靜態網站相關問題
出現「index.html not found」錯誤
原因：指定的目錄中沒有 index.html
解決方法：
- 確認建置輸出目錄（dist、build 等）
- 在本機執行建置並確認輸出結果
SPA 重新整理後出現 404
原因：沒有設定伺服器端的路由
解決方法：KamuiDash 會自動為 SPA 回退到 index.html。
效能相關問題
應用程式很慢
請確認： 1. 規格（CPU、記憶體）是否足夠？ 2. 資料庫查詢是否已最佳化？ 3. 外部 API 呼叫是否造成瓶頸？
解決方法： - 升級規格 - 為資料庫加上索引 - 導入快取機制
記憶體不足（OOM）
症狀：應用程式突然停止、不斷重新啟動
解決方法： 1. 升級規格 2. 檢查是否有記憶體洩漏 3. 減少一次處理的資料量
其他
問題仍未解決時
- 查看記錄：檢視應用程式記錄與部署記錄，取得詳細的錯誤資訊
- 檢查儀表板：重新確認狀態與設定
- 重新部署：若是暫時性問題，重新部署可能就會解決