故障排除

本文件彙總了 CueMate 系統故障的診斷和解決方法。

提示

遇到故障時，建議先檢視日誌管理和容器監控頁面，瞭解具體錯誤資訊。

1. macOS 平臺

1.1 服務無響應

問題描述：某個後端服務無法訪問，或者請求長時間沒有響應。

診斷原則

狀態 → 日誌 → 資源 → 網路

按照這個順序逐步排查，可以快速定位大部分服務問題。

排查步驟：

檢查服務狀態：
- 開啟容器監控頁面
- 檢視所有服務的執行狀態
- 確認問題服務是否正在執行
- 或使用命令：docker compose ps
檢視服務日誌：
- 在容器監控頁面點選服務的"日誌"按鈕
- 檢視最近的錯誤資訊
- 或使用命令：docker compose logs cuemate-web-api
檢查資源佔用：
- 使用命令檢視資源使用情況：docker stats
- 檢查 CPU、記憶體是否超限
- 確認磁碟空間是否充足

快速健康檢查命令

bash

# 一鍵檢查所有服務健康狀態
curl http://localhost:3001/health  # Web API
curl http://localhost:3002/health  # LLM Router
curl http://localhost:3003/health  # RAG Service
curl http://localhost:8000/api/v1/heartbeat  # ChromaDB
wscat -c ws://localhost:10095  # CueMate-ASR (需安裝 wscat)

解決方案：

重啟服務：
- 在容器監控頁面點選"重啟"按鈕
- 或使用命令：docker compose restart cuemate-web-api
- 等待服務重啟完成（約 30 秒）
增加資源限制：
- 開啟 Docker Desktop 設定
- 增加分配給 Docker 的記憶體和 CPU
- 建議：記憶體 8GB+，CPU 4 核+
檢查依賴服務：
- 確認所有依賴服務都正常執行
- 例如：web-api 依賴資料庫，llm-router 依賴外部 API
- 按正確順序啟動服務
檢視詳細錯誤日誌：
- 開啟日誌管理
- 檢視對應服務的 error 級別日誌
- 根據具體錯誤資訊進行排查

1.2 服務頻繁崩潰

問題描述：某個服務反覆自動重啟，或者頻繁停止執行。

服務崩潰常見原因排查順序

最常見：記憶體溢位（OOM）- 70% 的崩潰由此引起
其次：未捕獲的異常 - 20%
少見：磁碟空間不足 - 5%
罕見：死鎖或迴圈依賴 - 5%

根本原因分類：

型別	表現	快速診斷方法
記憶體溢位	容器自動重啟	`docker stats` 檢視記憶體使用率
程式碼異常	日誌有報錯堆疊	檢視 error 級別日誌
磁碟不足	寫入操作失敗	`df -h` 檢視磁碟空間
死鎖	服務假死無響應	檢視程序 CPU 狀態

解決方案：

檢視崩潰日誌：
- 在日誌管理中檢視崩潰前的日誌
- 查詢 "Error"、"Fatal"、"Crash" 等關鍵詞
- 記錄錯誤堆疊資訊
增加記憶體限制：
- 開啟 Docker Desktop，增加記憶體分配
- 編輯 docker-compose.yml 增加容器記憶體限制
- 重啟 Docker 服務使配置生效
更新到最新版本：
- 檢查是否有新版本釋出
- 檢視更新日誌是否修復了相關 Bug
- 按照版本升級文件更新
報告問題：
- 收集完整的錯誤日誌和重現步驟
- 在 GitHub Issues 提交 Bug 報告
- 提供系統環境資訊（OS、Docker 版本等）

1.3 資料庫連線失敗

問題描述：服務啟動時提示"資料庫連線失敗"或"無法訪問 SQLite"。

NOTE

CueMate 使用 SQLite 作為資料庫，資料庫檔案位於： ~/Library/Application Support/cuemate-desktop-client/data/sqlite/

SQLite 無需單獨的資料庫服務，所有資料都儲存在 .db 檔案中。

檢查項：

資料庫檔案是否存在：
- 檢查路徑：~/Library/Application Support/cuemate-desktop-client/data/sqlite/
- 確認 .db 檔案存在且可讀
- 檢查檔案許可權是否正確
資料庫服務是否執行：
- 對於 SQLite，無需單獨的資料庫服務
- 檢查檔案是否被其他程序鎖定
- 確認應用有讀寫許可權
連線字串是否正確：
- 檢查資料庫檔案路徑配置
- 確認路徑使用絕對路徑
- 驗證路徑中沒有特殊字元
檔案是否損壞：
- 嘗試使用 SQLite 工具開啟資料庫
- 檢查資料庫完整性
- 如果損壞，從備份恢復

解決方案：

檢查檔案許可權：

bash

# 檢視檔案許可權
ls -la ~/Library/Application\ Support/cuemate-desktop-client/data/sqlite/

# 修復許可權
chmod 644 ~/Library/Application\ Support/cuemate-desktop-client/data/sqlite/*.db

從備份恢復：
- 如果有備份，從備份恢復資料庫
- 參考問題 17 的備份恢復方法
重建資料庫：
- 刪除損壞的資料庫檔案（先備份）
- 重啟應用，會自動建立新資料庫
- 重新匯入資料

1.4 系統響應慢

問題描述：應用響應速度很慢，操作需要等待很長時間。

最佳化方法：

增加 Docker 資源分配：
- 開啟 Docker Desktop > Settings > Resources
- 增加 CPU 核心數（建議 4 核+）
- 增加記憶體（建議 8GB+）
- 點選 Apply & Restart
使用更快的模型：
- 在模型設定中更換模型
- 使用 GPT-3.5-turbo 代替 GPT-4
- 使用國產模型（智譜 AI、Kimi、DeepSeek）
- 降低 max_tokens 引數
啟用快取（如果支援）：
- 某些模型支援快取相同請求
- 在模型配置中啟用快取
- 清理過期快取釋放空間
最佳化資料庫查詢：
- 定期清理舊資料
- 刪除不需要的歷史記錄
- 在 AI 對話記錄中批次刪除
清理日誌和臨時檔案：
- 在日誌管理中清理舊日誌
- 刪除臨時檔案和快取
- 釋放磁碟空間

1.5 CPU 佔用高

問題描述：檢視活動監視器時，CueMate 或 Docker 佔用大量 CPU 資源。

TIP

正常 CPU 佔用率：

空閒狀態：5-10%
語音識別中：20-40%
AI 生成回答：10-20%
超過 60%：可能存在效能問題

解決方案：

限制併發請求數：
- 避免同時發起多個 AI 請求
- 等待上一個請求完成再發起新請求
- 關閉不使用的功能視窗
降低語音識別精度：
- 在語音設定中調整識別引數
- 降低取樣率可減少 CPU 佔用
- 關閉實時識別，改用按需識別
使用更小的模型：
- 避免使用超大引數模型
- 本地模型比雲端模型佔用更多 CPU
- 優先使用雲端 API 模型
最佳化程式碼邏輯：
- 更新到最新版本
- 最新版本通常有效能最佳化
- 檢視更新日誌瞭解改進
關閉後臺服務：
- 暫時停止不使用的服務
- 在容器監控頁面停止服務
- 需要時再重新啟動

1.6 記憶體佔用高

問題描述：系統記憶體佔用持續增長，或者提示記憶體不足。

最佳化措施：

清理快取：
- 在系統設定中清理應用快取
- 清理瀏覽器快取（如果使用 Web 介面）
- 重啟 Docker 清理容器快取
減少併發處理：
- 避免同時開啟多個功能視窗
- 減少同時執行的服務數量
- 限制每個服務的併發連線數
限制模型大小：
- 避免載入過大的本地模型
- 使用雲端 API 代替本地模型
- 減少模型上下文長度（max_tokens）
定期重啟服務：
- 長時間執行可能導致記憶體洩漏
- 定期重啟可釋放記憶體
- 建議每週重啟一次 Docker 服務
升級硬體：
- 如果記憶體經常不足，考慮升級記憶體
- 建議至少 16GB 記憶體
- 關閉其他佔用記憶體的應用

1.7 磁碟空間不足

問題描述：系統提示磁碟空間不足，或者應用無法儲存資料。

清理方法：

清理 Docker 資源：

bash

# 清理未使用的映象、容器、網路、卷
docker system prune -a

# 僅清理懸空映象和停止的容器
docker system prune

# 清理所有卷（謹慎使用）
docker volume prune

清理應用日誌：

開啟日誌管理
選擇日期範圍批次刪除舊日誌
或使用命令：

bash

# 刪除 7 天前的日誌
find ~/Library/Application\ Support/cuemate-desktop-client/data/logs -mtime +7 -delete

清理臨時檔案：

bash

# 清理系統臨時檔案
rm -rf /tmp/cuemate

# 清理下載的臨時檔案
rm -rf ~/Downloads/cuemate-temp

清理備份檔案：

bash

# 刪除 30 天前的備份
find ~/backup/cuemate -mtime +30 -delete

# 或手動刪除舊備份
rm -rf ~/backup/cuemate/backup_20260101*

壓縮大檔案：
- 壓縮知識庫文件
- 清理不需要的向量資料
- 刪除重複的面試記錄

1.8 無法連線外部 API

問題描述：配置模型後，測試連線提示"無法連線"或"網路錯誤"。

檢查項：

網路連線是否正常：
- 檢查網路連線狀態
- 嘗試訪問其他網站
- 使用 ping 測試網路連通性
防火牆是否阻止：
- 檢查系統防火牆設定
- 確認允許 CueMate 訪問網路
- 檢查防火牆規則
代理設定是否正確：
- 如果使用代理，檢查代理配置
- 確認代理地址和埠正確
- 測試代理是否可用
DNS 解析是否正常：
- 使用 nslookup 測試域名解析
- 嘗試更換 DNS 伺服器（如 8.8.8.8）
- 檢查 hosts 檔案是否有錯誤配置

解決方案：

配置代理：
- 在系統設定或環境變數中配置代理
- 設定 HTTP_PROXY 和 HTTPS_PROXY
- 重啟應用使配置生效
更換 DNS：
- 開啟系統網路設定
- 更換 DNS 伺服器為 8.8.8.8 或 1.1.1.1
- 清除 DNS 快取
使用國內模型：
- 如果無法訪問國外 API
- 使用國內大模型服務（智譜 AI、Kimi、DeepSeek）
- 無需科學上網即可使用

1.9 WebSocket 連線失敗

問題描述：語音識別時提示"WebSocket 連線失敗"或"無法連線語音服務"。

解決方案：

檢查防火牆規則：
- 確認防火牆允許 WebSocket 連線
- 允許埠 10095（cuemate-asr）
- 新增應用到防火牆白名單

驗證埠開放：

bash

# 檢查埠是否監聽
lsof -i :10095

# 測試埠連通性
telnet localhost 10095

檢查服務狀態：
- 開啟容器監控
- 確認 cuemate-asr 服務正在執行
- 檢視服務日誌排查錯誤
重啟語音服務：
- 在容器監控頁面重啟 cuemate-asr
- 等待服務重啟完成
- 重新測試 WebSocket 連線

1.10 許可權被拒絕

問題描述：提示"許可權不足"或"訪問被拒絕"。

解決方案：

檢查檔案許可權：

bash

# 檢視檔案許可權
ls -la ~/Library/Application\ Support/cuemate-desktop-client/

# 修復許可權
chmod -R 755 ~/Library/Application\ Support/cuemate-desktop-client/

檢查系統許可權：
- 開啟"系統設定" > "隱私與安全性"
- 檢查麥克風許可權
- 檢查錄屏與系統錄音許可權
- 檢查檔案和資料夾許可權
以管理員身份執行：
- 某些操作需要管理員許可權
- macOS：使用 sudo 命令
- 謹慎使用，避免安全風險

1.11 埠衝突

問題描述：服務啟動失敗，提示"埠已被佔用"。

解決方案：

查詢佔用埠的程式：

bash

# 檢視埠占用
lsof -i :3001
lsof -i :10095

# 檢視所有監聽埠
lsof -i -P | grep LISTEN

關閉佔用埠的程式：

bash

# 根據 PID 關閉程序
kill -9 <PID>

# 或使用活動監視器手動關閉

更改 CueMate 埠（不推薦）：
- 編輯 docker-compose.yml 檔案
- 修改埠對映配置
- 重啟服務使配置生效
重啟系統：
- 如果無法找到佔用程式
- 重啟 Mac 可釋放所有埠
- 重啟後再次啟動 CueMate

1.12 Docker 映象損壞

問題描述：服務無法啟動，提示"映象損壞"或"無法載入映象"。

解決方案：

刪除損壞的映象：

bash

# 檢視所有映象
docker images

# 刪除指定映象
docker rmi <IMAGE_ID>

# 刪除所有懸空映象
docker image prune

重新載入映象：
- 如果是離線安裝包，重新載入映象
- 或從映象倉庫拉取最新映象
- 參考安裝指南

重建容器：

bash

# 停止所有容器
docker compose down

# 刪除容器和映象
docker compose down --rmi all

# 重新構建
docker compose up -d

1.13 配置檔案丟失或損壞

問題描述：應用啟動失敗，提示"配置檔案不存在"或"配置格式錯誤"。

解決方案：

檢查配置檔案位置：

bash

# 配置檔案路徑
~/Library/Application Support/cuemate-desktop-client/config/

# 檢視配置檔案
ls -la ~/Library/Application\ Support/cuemate-desktop-client/config/

恢復預設配置：
- 刪除損壞的配置檔案
- 重啟應用，會自動建立預設配置
- 重新配置模型和設定
從備份恢復：
- 如果有配置檔案備份
- 複製備份檔案到配置目錄
- 重啟應用
手動修復配置檔案：
- 使用文字編輯器開啟配置檔案
- 檢查 JSON 格式是否正確
- 修復語法錯誤或缺失欄位

1.14 證書過期或無效

問題描述：訪問某些服務時提示"證書無效"或"SSL 錯誤"。

解決方案：

更新系統證書：
- 更新 macOS 系統到最新版本
- 系統會自動更新根證書
忽略證書驗證（不推薦）：
- 僅用於測試環境
- 生產環境不建議關閉證書驗證
使用 HTTP 代替 HTTPS：
- 如果是內網服務
- 可以使用 HTTP 協議
- 修改 API URL 為 HTTP

1.15 日誌檢視困難

問題描述：日誌檔案太大，或者找不到需要的錯誤資訊。

解決方案：

使用日誌管理頁面：
- 開啟日誌管理
- 使用日期和級別過濾
- 搜尋關鍵詞定位錯誤

使用命令列工具過濾：

bash

# 檢視最近 100 行（以 web-api 為例）
tail -n 100 ~/Library/Application\ Support/cuemate-desktop-client/data/logs/web-api/2026-01-15/error.log

# 實時檢視日誌
tail -f ~/Library/Application\ Support/cuemate-desktop-client/data/logs/web-api/2026-01-15/error.log

# 搜尋關鍵詞
grep "Error" ~/Library/Application\ Support/cuemate-desktop-client/data/logs/web-api/2026-01-15/error.log

# 統計錯誤次數
grep -c "Error" ~/Library/Application\ Support/cuemate-desktop-client/data/logs/web-api/2026-01-15/error.log

匯出日誌到檔案：
- 在日誌管理頁面匯出日誌
- 使用文字編輯器檢視
- 分享給技術支援分析

1.16 應用崩潰無法啟動

問題描述：應用啟動後立即崩潰，或者無法正常啟動。

解決方案：

檢視崩潰報告：
- macOS："控制檯" > "使用者報告" > "應用崩潰"
- 找到 CueMate 的崩潰報告
- 記錄錯誤資訊
清理快取和配置：

資料安全警告

執行以下命令前，強烈建議先備份資料！刪除操作不可恢復。

務必先執行備份命令，再執行刪除命令。

bash

# 1. 先備份配置和資料（重要！）
cp -r ~/Library/Application\ Support/cuemate-desktop-client ~/backup/

# 2. 然後才能刪除快取
rm -rf ~/Library/Caches/cuemate-desktop-client

# 3. 刪除臨時檔案
rm -rf /tmp/cuemate

重新安裝應用：
- 完全解除安裝 CueMate
- 重新下載最新版本安裝包
- 重新安裝
- 詳見解除安裝指南
檢查系統相容性：
- 確認 macOS 版本符合要求（>= 13.0）
- 檢查硬體配置是否滿足需求
- 更新系統到最新版本

1.17 資料備份失敗

問題描述：執行備份操作時失敗，或者備份檔案無法使用。

備份資料的正確方法：

bash

#!/bin/bash
# CueMate 資料備份指令碼

BACKUP_DIR=~/backup/cuemate
DATE=$(date +%Y%m%d_%H%M%S)
DATA_DIR=~/Library/Application\ Support/cuemate-desktop-client/data

echo "開始備份 CueMate 資料..."

# 建立備份目錄
mkdir -p $BACKUP_DIR

# 備份 SQLite 資料庫
if [ -d "$DATA_DIR/sqlite" ]; then
    echo "備份資料庫..."
    cp -r "$DATA_DIR/sqlite" "$BACKUP_DIR/sqlite_$DATE"
fi

# 備份向量資料庫
if [ -d "$DATA_DIR/chroma" ]; then
    echo "備份向量資料..."
    cp -r "$DATA_DIR/chroma" "$BACKUP_DIR/chroma_$DATE"
fi

# 備份配置檔案
if [ -d ~/Library/Application\ Support/cuemate-desktop-client/config ]; then
    echo "備份配置檔案..."
    cp -r ~/Library/Application\ Support/cuemate-desktop-client/config "$BACKUP_DIR/config_$DATE"
fi

# 打包壓縮
echo "壓縮備份檔案..."
cd $BACKUP_DIR
tar -czf "cuemate_backup_$DATE.tar.gz" \
    "sqlite_$DATE" \
    "chroma_$DATE" \
    "config_$DATE" 2>/dev/null

# 清理臨時檔案
rm -rf "sqlite_$DATE" "chroma_$DATE" "config_$DATE"

echo "備份完成: $BACKUP_DIR/cuemate_backup_$DATE.tar.gz"

驗證備份檔案：

bash

# 檢視備份檔案大小
ls -lh ~/backup/cuemate/

# 解壓測試
tar -tzf ~/backup/cuemate/cuemate_backup_20260115.tar.gz

# 完整性檢查
tar -xzf ~/backup/cuemate/cuemate_backup_20260115.tar.gz -O > /dev/null

1.18 資料恢復失敗

問題描述：嘗試從備份恢復資料時失敗。

恢復資料的正確方法：

bash

#!/bin/bash
# CueMate 資料恢復指令碼

BACKUP_FILE=$1
DATA_DIR=~/Library/Application\ Support/cuemate-desktop-client/data

if [ -z "$BACKUP_FILE" ]; then
    echo "用法: ./restore.sh <備份檔案路徑>"
    exit 1
fi

echo "開始恢復 CueMate 資料..."
echo "備份檔案: $BACKUP_FILE"

# 停止服務
echo "停止 Docker 服務..."
cd ~/Library/Application\ Support/cuemate-desktop-client
docker compose stop

# 解壓備份檔案
echo "解壓備份檔案..."
TEMP_DIR=$(mktemp -d)
tar -xzf "$BACKUP_FILE" -C "$TEMP_DIR"

# 恢復資料庫
if [ -d "$TEMP_DIR/sqlite_"* ]; then
    echo "恢復資料庫..."
    rm -rf "$DATA_DIR/sqlite"
    cp -r "$TEMP_DIR"/sqlite_* "$DATA_DIR/sqlite"
fi

# 恢復向量資料
if [ -d "$TEMP_DIR/chroma_"* ]; then
    echo "恢復向量資料..."
    rm -rf "$DATA_DIR/chroma"
    cp -r "$TEMP_DIR"/chroma_* "$DATA_DIR/chroma"
fi

# 恢復配置檔案
if [ -d "$TEMP_DIR/config_"* ]; then
    echo "恢復配置檔案..."
    rm -rf ~/Library/Application\ Support/cuemate-desktop-client/config
    cp -r "$TEMP_DIR"/config_* ~/Library/Application\ Support/cuemate-desktop-client/config
fi

# 清理臨時檔案
rm -rf "$TEMP_DIR"

# 啟動服務
echo "啟動 Docker 服務..."
docker compose start

echo "恢復完成！"
echo "請等待服務啟動（約 30 秒），然後重新開啟應用。"

使用方法：

bash

# 賦予指令碼執行許可權
chmod +x restore.sh

# 執行恢復
./restore.sh ~/backup/cuemate/cuemate_backup_20260115.tar.gz

1.19 健康檢查指令碼

問題描述：不知道如何快速檢查系統整體狀態。

健康檢查指令碼：

bash

#!/bin/bash
# CueMate 健康檢查指令碼

echo "=========================================="
echo "  CueMate 系統健康檢查"
echo "=========================================="
echo ""

# 檢查 Docker
echo "[ 1/6 ] 檢查 Docker..."
if docker ps &>/dev/null; then
    echo "  ✓ Docker 執行正常"
else
    echo "  ✗ Docker 未執行或無許可權"
fi
echo ""

# 檢查服務
echo "[ 2/6 ] 檢查服務狀態..."
services=("web" "web-api" "llm-router" "rag-service" "asr" "chroma")
for service in "${services[@]}"; do
    if docker ps | grep -q "cuemate-$service"; then
        echo "  ✓ cuemate-$service 執行正常"
    else
        echo "  ✗ cuemate-$service 未執行"
    fi
done
echo ""

# 檢查埠
echo "[ 3/6 ] 檢查埠監聽..."
ports=(3001 3002 3003 3004 8000 10095)
port_names=("Web-API" "LLM-Router" "RAG-Service" "Web" "ChromaDB" "ASR")
for i in "${!ports[@]}"; do
    port=${ports[$i]}
    name=${port_names[$i]}
    if lsof -i :$port &>/dev/null; then
        echo "  ✓ 埠 $port ($name) 正在監聽"
    else
        echo "  ✗ 埠 $port ($name) 未監聽"
    fi
done
echo ""

# 檢查磁碟空間
echo "[ 4/6 ] 檢查磁碟空間..."
available=$(df -h ~/ | awk 'NR==2 {print $4}')
echo "  可用空間: $available"
echo ""

# 檢查記憶體使用
echo "[ 5/6 ] 檢查 Docker 資源使用..."
docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}" | head -n 7
echo ""

# 測試服務健康
echo "[ 6/6 ] 測試服務健康檢查..."
endpoints=(
    "http://localhost:3001/health:Web-API"
    "http://localhost:3002/health:LLM-Router"
    "http://localhost:3003/health:RAG-Service"
)
for endpoint in "${endpoints[@]}"; do
    url="${endpoint%%:*}"
    name="${endpoint##*:}"
    if curl -s -f "$url" > /dev/null 2>&1; then
        echo "  ✓ $name 健康檢查透過"
    else
        echo "  ✗ $name 健康檢查失敗"
    fi
done

echo ""
echo "=========================================="
echo "  檢查完成"
echo "=========================================="

使用方法：

bash

# 儲存為 health-check.sh
chmod +x health-check.sh
./health-check.sh

1.20 效能監控和分析

問題描述：想要持續監控系統效能，發現潛在問題。

監控指令碼：

bash

#!/bin/bash
# CueMate 效能監控指令碼

LOG_FILE=~/cuemate-monitor.log
INTERVAL=60  # 監控間隔（秒）

echo "開始監控 CueMate 效能（每 $INTERVAL 秒）"
echo "日誌檔案: $LOG_FILE"
echo "按 Ctrl+C 停止監控"
echo ""

while true; do
    echo "==================== $(date) ====================" >> $LOG_FILE

    # 記錄 Docker 容器資源使用
    docker stats --no-stream --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.NetIO}}\t{{.BlockIO}}" >> $LOG_FILE

    # 記錄磁碟空間
    echo "" >> $LOG_FILE
    echo "磁碟空間:" >> $LOG_FILE
    df -h ~/ | grep -v Filesystem >> $LOG_FILE

    # 記錄服務狀態
    echo "" >> $LOG_FILE
    echo "服務狀態:" >> $LOG_FILE
    docker compose ps >> $LOG_FILE

    echo "" >> $LOG_FILE

    # 在終端顯示簡要資訊
    echo "[$(date +%H:%M:%S)] 監控資料已記錄"

    sleep $INTERVAL
done

分析日誌：

bash

# 檢視最近的監控資料
tail -n 50 ~/cuemate-monitor.log

# 統計 CPU 使用率
grep "cuemate-web-api" ~/cuemate-monitor.log | awk '{print $2}'

# 檢視記憶體趨勢
grep "cuemate-" ~/cuemate-monitor.log | awk '{print $1, $3}'

2. Windows 平臺

Windows 平臺的故障排除與 macOS 類似，以下列出 Windows 特有的問題和解決方案。

2.1 WSL 2 啟動失敗

問題描述：Docker Desktop 無法啟動，提示 WSL 2 相關錯誤。

解決方案：

啟用虛擬化：
- 重新啟動電腦進入 BIOS
- 啟用 Intel VT-x 或 AMD-V 虛擬化
- 啟用 Hyper-V（Windows 功能）

重新安裝 WSL 2：

powershell

# 以系統管理員身份執行
wsl --unregister Ubuntu
wsl --install -d Ubuntu
wsl --set-version Ubuntu 2

更新 WSL 核心：
- 下載 WSL2 Linux 核心更新套件
- 執行安裝程式

2.2 Docker 容器無法啟動

問題描述：服務容器啟動失敗或頻繁重新啟動。

排查步驟：

powershell

# 檢視容器狀態
docker ps -a

# 檢視容器日誌
docker logs cuemate-web-api

# 檢查 Docker 資源使用
docker stats --no-stream

解決方案：

增加 Docker 資源：
- 開啟 Docker Desktop > Settings > Resources
- WSL 2 模式下，編輯 %USERPROFILE%\.wslconfig：
ini
```
[wsl2]
memory=8GB
processors=4
```
重新啟動 Docker：
- 在工作列右鍵點選 Docker 圖示
- 選擇 Restart

2.3 埠被佔用

問題描述：啟動服務時提示埠被佔用。

解決方案：

powershell

# 檢視埠佔用
netstat -ano | findstr :3001
netstat -ano | findstr :10095

# 根據 PID 結束程序
taskkill /PID <PID> /F

2.4 磁碟空間不足

問題描述：C 碟空間不足，Docker 映象佔用大量空間。

解決方案：

清理 Docker 資源：
powershell
```
docker system prune -a --volumes
```
移動 Docker 資料：
- 開啟 Docker Desktop > Settings > Resources > Advanced
- 修改 Disk image location 到其他碟符

移動 WSL 資料：

powershell

# 匯出 WSL 發行版
wsl --export Ubuntu D:\wsl\ubuntu.tar
# 登出原發行版
wsl --unregister Ubuntu
# 匯入到新位置
wsl --import Ubuntu D:\wsl\Ubuntu D:\wsl\ubuntu.tar

2.5 健康檢查命令

Windows 健康檢查指令碼（PowerShell）：

powershell

# 檢查 Docker 狀態
docker ps

# 檢查埠監聽
netstat -ano | findstr "3001 3002 3003 3004 8000 10095"

# 測試服務健康
Invoke-RestMethod -Uri "http://localhost:3001/health"
Invoke-RestMethod -Uri "http://localhost:3002/health"
Invoke-RestMethod -Uri "http://localhost:3003/health"

2.6 日誌檔案位置

Windows 日誌路徑：

桌面客戶端日誌：%APPDATA%\cuemate-desktop-client\data\logs\
Docker 容器日誌：docker logs <container_name>

檢視日誌：

powershell

# 檢視最新日誌
Get-Content "$env:APPDATA\cuemate-desktop-client\data\logs\desktop-client\*\error.log" -Tail 100

# 實時檢視日誌
Get-Content "$env:APPDATA\cuemate-desktop-client\data\logs\desktop-client\*\info.log" -Wait

獲取更多幫助

如果以上方法都無法解決你的問題，可以透過以下方式獲取幫助：

準備資訊

在聯絡技術支援前，請準備以下資訊：

系統環境：
- macOS 版本號（如 macOS 15.0）
- 晶片型別（Apple Silicon 或 Intel）
- CueMate 版本號
完整錯誤日誌：
- 從日誌管理匯出相關日誌
- 包含錯誤發生的時間和上下文
- 截圖或文字形式
問題重現步驟：
- 詳細描述如何重現問題
- 列出具體的操作步驟
- 說明預期結果和實際結果
已嘗試的解決方法：
- 列出已經嘗試的解決方案
- 說明嘗試結果
- 避免重複建議

聯絡方式

GitHub Issues：https://github.com/cuemate-chat/cuemate/issues
郵箱：nuneatonhydroplane@gmail.com

故障排除 ​

1. macOS 平臺 ​

1.1 服務無響應 ​

1.2 服務頻繁崩潰 ​

1.3 資料庫連線失敗 ​

1.4 系統響應慢 ​

1.5 CPU 佔用高 ​

1.6 記憶體佔用高 ​

1.7 磁碟空間不足 ​

1.8 無法連線外部 API ​

1.9 WebSocket 連線失敗 ​

1.10 許可權被拒絕 ​

1.11 埠衝突 ​

1.12 Docker 映象損壞 ​

1.13 配置檔案丟失或損壞 ​

1.14 證書過期或無效 ​

1.15 日誌檢視困難 ​

1.16 應用崩潰無法啟動 ​

1.17 資料備份失敗 ​

1.18 資料恢復失敗 ​

1.19 健康檢查指令碼 ​

1.20 效能監控和分析 ​

2. Windows 平臺 ​

2.1 WSL 2 啟動失敗 ​

2.2 Docker 容器無法啟動 ​

2.3 埠被佔用 ​

2.4 磁碟空間不足 ​

2.5 健康檢查命令 ​

2.6 日誌檔案位置 ​

獲取更多幫助 ​

準備資訊 ​

聯絡方式 ​

相關文件 ​

故障排除

1. macOS 平臺

1.1 服務無響應

1.2 服務頻繁崩潰

1.3 資料庫連線失敗

1.4 系統響應慢

1.5 CPU 佔用高

1.6 記憶體佔用高

1.7 磁碟空間不足

1.8 無法連線外部 API

1.9 WebSocket 連線失敗

1.10 許可權被拒絕

1.11 埠衝突

1.12 Docker 映象損壞

1.13 配置檔案丟失或損壞

1.14 證書過期或無效

1.15 日誌檢視困難

1.16 應用崩潰無法啟動

1.17 資料備份失敗

1.18 資料恢復失敗

1.19 健康檢查指令碼

1.20 效能監控和分析

2. Windows 平臺

2.1 WSL 2 啟動失敗

2.2 Docker 容器無法啟動

2.3 埠被佔用

2.4 磁碟空間不足

2.5 健康檢查命令

2.6 日誌檔案位置

獲取更多幫助

準備資訊

聯絡方式

相關文件