服務管理
本文件介紹如何透過 CueMate 的 主視窗管理後端服務，包括檢視服務狀態、重啟服務、檢視日誌等操作。
1. 服務概覽
NOTE
CueMate 採用微服務架構，所有後端服務透過 Docker 容器執行。正常情況下，所有 6 個服務應該處於"執行中"狀態。
CueMate 包含 6 個後端服務容器，所有服務透過 Docker 容器執行：
| 序號 | 服務名稱 | 容器名稱 | 埠 | 職責說明 |
|---|---|---|---|---|
| 1 | 後端 API 服務 | cuemate-web-api | 3001 | 業務邏輯、使用者認證、資料管理 |
| 2 | 大模型路由服務 | cuemate-llm-router | 3002 | LLM 請求路由、流式響應處理 |
| 3 | 知識庫檢索服務 | cuemate-rag-service | 3003 | 向量檢索、語義搜尋 |
| 4 | 主視窗服務 | cuemate-web | 3004 | 提供主視窗訪問 |
| 5 | 向量資料庫 | cuemate-chroma | 8000 | 向量資料儲存 |
| 6 | 語音識別服務 | cuemate-asr | 10095 | 實時語音轉文字 |
IMPORTANT
服務依賴關係：
- 主視窗依賴 API 服務
- API 服務依賴 LLM 路由服務和知識庫檢索服務
- 知識庫檢索服務依賴向量資料庫
- 桌面客戶端依賴語音識別服務
重啟服務時需要注意依賴順序，被依賴的服務應該先啟動。
2. 檢視服務狀態
2.1 進入容器監控頁面
點選頂部下拉選單選單的「容器監控」，進入服務狀態檢視頁面。
2.2 檢視服務統計
頁面頂部顯示服務執行概況：
- 總容器數：系統中所有服務容器總數
- 執行中：當前正常執行的服務數量（綠色）
- 已停止：已停止或異常退出的服務數量（橙色）
正常狀態： 所有 6 個服務都應該顯示為"執行中"。
2.3 檢視服務列表
服務列表展示每個容器的詳細資訊：
| 序號 | 欄位 | 說明 |
|---|---|---|
| 1 | 容器名稱 | 服務容器的名稱，如 cuemate-web-api |
| 2 | 映象 | 使用的 Docker 映象版本 |
| 3 | 執行狀態 | 執行中（綠色）/ 已停止（橙色）/ 已退出（紅色） |
| 4 | 埠 | 服務的埠對映資訊 |
| 5 | 大小 | 容器佔用的磁碟空間 |
| 6 | 操作 | 重啟、檢視日誌等操作按鈕 |
3. 重啟服務
3.1 重啟單個服務
當某個服務出現異常時，可以透過重啟恢復：
重啟步驟：
- 在容器列表中找到需要重啟的服務
- 點選該服務行的「重啟」按鈕
- 在確認對話方塊中點選「確定」
- 等待重啟完成（通常需要幾秒到幾十秒）
- 檢視服務狀態是否恢復為"執行中"
注意事項：
- 重啟服務會導致該服務短暫中斷
- 重啟後配置和資料不會丟失
- 如果服務重啟後仍然異常，請檢視服務日誌排查問題
常見重啟場景：
- 服務狀態顯示為"已退出"或"已停止"
- 服務響應緩慢或無響應
- 配置更新後需要重啟生效
- 系統提示需要重啟服務
4. 檢視服務日誌
4.1 檢視容器日誌
點選服務列表中的「日誌」按鈕，開啟日誌檢視器：
日誌檢視器功能：
- 顯示服務的實時執行日誌
- 檢視錯誤和異常資訊
- 複製日誌內容用於分析
- 重新整理獲取最新日誌
日誌操作：
- 重新整理：獲取最新的日誌內容
- 複製：複製日誌到剪貼簿
- 檢視詳情：檢視完整的容器資訊
4.2 檢視系統日誌
進入 日誌管理 頁面，檢視更詳細的系統日誌：
點選頂部下拉選單選單的「日誌管理」，可以檢視：
- 按服務分類的日誌檔案
- 按級別篩選（DEBUG、INFO、WARN、ERROR）
- 按日期檢視歷史日誌
- 清理和匯出日誌檔案
詳細使用方法請參考 日誌管理 頁面。
5. 服務故障排查
5.1 服務無法啟動
問題現象：
- 服務狀態顯示為"已退出"或"已停止"
- 重啟後立即再次停止
排查步驟：
- 進入 容器監控 頁面
- 點選異常服務的「日誌」按鈕
- 檢視日誌中的錯誤資訊
- 根據錯誤資訊定位問題原因
常見原因：
- 埠被佔用：日誌會提示 "Address already in use"
- 依賴服務未啟動：日誌會提示連線失敗
- 配置錯誤：日誌會提示配置檔案錯誤
- 資源不足：日誌會提示記憶體或磁碟空間不足
5.2 服務響應緩慢
問題現象：
- 主視窗載入慢
- API 請求超時
- 操作響應延遲
排查步驟：
- 進入 容器監控 頁面
- 檢視所有服務是否都在執行
- 重啟響應慢的服務
- 檢視日誌是否有異常報錯
常見原因：
- 記憶體不足導致服務卡頓
- 資料庫查詢慢
- 網路連線問題
- 併發請求過多
5.3 服務頻繁重啟
問題現象：
- 服務狀態反覆變化
- 剛啟動就停止
排查步驟：
- 檢視服務日誌，定位崩潰原因
- 檢查系統資源是否充足
- 檢查依賴服務是否正常
常見原因：
- 記憶體洩漏導致服務崩潰
- 健康檢查配置不當
- 依賴服務連線失敗
- 程式碼存在未捕獲的異常
6. 系統配置
6.1 基礎設定
進入 系統設定 頁面，配置系統引數：
點選頂部下拉選單選單的「系統設定」，可以配置：
- 系統語言和時區
- 介面主題（淺色/深色）
- 預設大模型選擇
- 賬戶資訊
詳細配置方法請參考 系統設定 頁面。
6.2 模型配置
進入 模型設定 頁面，配置 AI 模型：
- 新增和管理 LLM 模型
- 配置 API Key
- 測試模型連線
- 設定預設模型
6.3 語音設定
進入 語音設定 頁面，配置語音識別：
- 選擇麥克風裝置
- 選擇揚聲器裝置
- 測試語音識別效果
7. 資料備份與恢復
7.1 資料儲存位置
CueMate 的資料儲存在以下位置：
macOS 系統：
~/Library/Application Support/cuemate-desktop-client/data/
├── sqlite/ # SQLite 資料庫
├── chroma/ # 向量資料庫
└── logs/ # 日誌檔案7.2 備份資料
重要資料包括：
- SQLite 資料庫：崗位資訊、面試記錄、使用者資料
- 向量資料庫：面試押題、知識庫資料
- 配置檔案：模型配置、系統設定
備份建議：
- 定期備份
cuemate-desktop-client/data資料夾 - 升級前務必備份資料
- 使用 Time Machine 或其他備份工具自動備份
7.3 恢復資料
如果資料丟失或損壞，可以從備份恢復：
- 退出 CueMate 應用
- 將備份的
data資料夾複製回原位置 - 重新啟動 CueMate 應用
- 登入後資料會自動恢復
8. 版本更新
8.1 線上更新
使用 License 管理 頁面的版本管理功能更新：
- 進入 License 管理頁面
- 點選右上角「版本管理」按鈕
- 檢視可用版本列表
- 選擇目標版本檢視更新日誌
- 點選「更新到此版本」執行更新
詳細更新流程請參考 版本升級 文件。
8.2 更新注意事項
- 更新前會自動備份資料
- 更新過程中請勿關閉應用
- 更新失敗會自動回滾
- 建議在非工作時間更新
9. 常見問題
9.1 如何檢視當前版本？
進入 系統設定 頁面，在「軟體版本」欄位檢視當前使用的版本號。
9.2 服務異常如何處理？
9.3 如何清理日誌檔案？
進入 日誌管理 頁面：
- 選擇要清理的日誌檔案
- 點選「清理」按鈕清空日誌內容
- 或使用「清理今日日誌」批次清理
9.4 資料儲存在哪裡？
所有資料儲存在 ~/Library/Application Support/cuemate-desktop-client/data/ 目錄：
- 解除安裝應用時可以選擇是否保留此資料夾
- 建議定期備份此資料夾
- 重新安裝後會自動識別此資料夾中的資料
10. 獲取幫助
如果遇到無法解決的問題：
- 檢視 常見問題 文件
- 檢視 故障排查 指南
- 訪問 GitHub Issues
- 傳送郵件至：nuneatonhydroplane@gmail.com