常見問題

本章節收集了 CueMate 使用過程中的常見問題和解決方案。所有 FAQ 採用編號格式（1-100），方便跨版本更新和快速定位問題。

1. 快速導航

Windows 版本開發中

當前 FAQ 主要針對 macOS 平臺。Windows 版本正在開發中,相關文件將在後續更新。

1.1 安裝問題 (20 個問題)

涵蓋 CueMate 安裝過程中的所有常見問題，包括：

Docker 安裝與配置 (Q1-Q6)：Docker Desktop 安裝、啟動失敗、資源配置、網路問題
系統許可權配置 (Q7-Q9)：macOS/Windows 許可權、檔案訪問、安全策略
服務部署問題 (Q10-Q15)：埠衝突、映象拉取、服務啟動、健康檢查
桌面應用安裝 (Q16-Q20)：.dmg/.exe 安裝、依賴問題、更新失敗

詳見：完整安裝 FAQ →

1.2 使用問題 (20 個問題)

解答 CueMate 功能使用過程中的常見困惑，包括：

語音識別 (Q1-Q3)：識別準確度、延遲問題、系統音訊捕獲
模型配置 (Q4-Q6)：API Key 設定、模型連線、響應速度最佳化
知識庫功能 (Q7-Q9)：文件上傳、檢索結果、向量化問題
面試訓練 (Q10-Q12)：AI 回答質量、題目匹配、評分系統
其他功能 (Q13-Q20)：資料管理、匯入匯出、裝置識別、服務配置

詳見：完整使用 FAQ →

1.3 故障排除 (20 個問題)

提供系統級問題的診斷和解決方案，包括：

服務問題 (Q1-Q3)：服務無響應、頻繁崩潰、資料庫連線
效能最佳化 (Q4-Q7)：響應緩慢、CPU/記憶體/磁碟佔用
網路問題 (Q8-Q9)：外部 API 連線、WebSocket 通訊
系統配置 (Q10-Q16)：許可權問題、埠占用、映象問題、配置修改
資料管理與監控 (Q17-Q20)：備份指令碼、恢復流程、健康檢查、效能監控

詳見：完整故障排除 FAQ →

2. 熱門問題 TOP 15

平臺說明

以下問題解答主要針對 macOS 平臺。部分問題提到了 Windows 平臺的操作方法,但請注意 Windows 版本目前仍在開發中,這些內容僅供參考。

正式的 Windows 版本文件將在後續更新,敬請期待。如有 Windows 版本相關建議,歡迎透過 GitHub Issues 反饋。

2.1 Docker Desktop 無法啟動或安裝失敗？

問題場景：下載安裝 Docker Desktop 後無法啟動，或啟動後狀態異常。

快速解決：

macOS：

bash

# 檢查虛擬化是否啟用
sysctl kern.hv_support

# 重置 Docker Desktop
rm -rf ~/Library/Group\ Containers/group.com.docker
rm -rf ~/Library/Containers/com.docker.docker

Windows：

powershell

# 確保 WSL 2 已安裝
wsl --install
wsl --set-default-version 2

詳見：安裝問題 Q1 | Q2

2.2 語音識別不準確，識別結果有錯誤？

問題場景：使用語音識別功能時，轉錄文字與實際說話內容不符。

快速最佳化：

選擇安靜環境，避免背景噪音
檢查麥克風許可權（系統偏好設定 > 安全性與隱私 > 麥克風）
調整麥克風距離（15-30cm 為佳）
新增專業術語到自定義詞庫
調整 CueMate-ASR 模型引數（熱詞權重、VAD 靈敏度）

詳見：使用問題 Q1 | 語音測試功能

2.3 API Key 配置後無法使用或報錯？

問題場景：在設定中配置了 API Key，但呼叫 AI 模型時失敗或無響應。

排查步驟：

bash

# 1. 檢查 LLM Router 服務日誌
docker logs cuemate-llm-router

# 2. 測試 API 連線
curl -X POST http://localhost:3002/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4","messages":[{"role":"user","content":"test"}]}'

# 3. 檢查 API Key 有效性（以 OpenAI 為例）
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

詳見：使用問題 Q4 | Q5

2.4 服務啟動失敗，Docker 容器無法執行？

問題場景：執行 bash private/start.sh 後服務無法正常啟動。

診斷命令：

bash

# 檢查所有容器狀態
docker ps -a

# 檢視失敗容器日誌
docker logs cuemate-web-api
docker logs cuemate-llm-router

# 檢查埠占用
lsof -i :3001,3002,3003,3004,8000,10095

# 檢查 Docker 資源
docker system df

詳見：安裝問題 Q12 | Q13

2.5 系統資源佔用過高（CPU/記憶體）？

問題場景：CueMate 執行後 CPU 或記憶體佔用率持續過高，影響系統效能。

最佳化方案：

bash

# 1. 調整 Docker 資源限制（macOS）
# Docker Desktop > Settings > Resources
# CPU: 4 核 → 2 核
# Memory: 8GB → 4GB

# 2. 使用更小的模型
# Web 設定 > AI 模型 > 選擇 gpt-4o-mini（替代 gpt-4）

# 3. 清理 Docker 資源
docker system prune -a --volumes

# 4. 監控資源使用
docker stats

詳見：故障排除 Q5 | Q6

2.6 知識庫檢索無結果或結果不相關？

問題場景：上傳了文件到知識庫，但提問時檢索不到相關內容。

問題排查：

bash

# 1. 檢查 ChromaDB 服務狀態
curl http://localhost:8000/api/v1/heartbeat

# 2. 檢視 RAG Service 日誌
docker logs cuemate-rag-service

# 3. 檢查向量化是否完成
# Web 端 > 知識庫 > 文件列表 > 狀態應為"已完成"

# 4. 測試檢索 API
curl -X POST http://localhost:3003/search \
  -H "Content-Type: application/json" \
  -d '{"query":"測試查詢","top_k":5}'

詳見：使用問題 Q8 | Q9

2.7 埠衝突，服務無法繫結埠？

問題場景：啟動服務時提示埠已被佔用（3001, 3002, 3003, 3004, 8000, 10095）。

解決步驟：

bash

# 1. 查詢佔用埠的程序
lsof -i :3001
lsof -i :3004

# 2. 停止佔用埠的程序
kill -9 <PID>

# 3. 或修改 CueMate 使用的埠
# 編輯 infra/docker/docker-compose.yml
# 修改 ports 對映（如 3004:3004 改為 8080:3004）

詳見：安裝問題 Q10 | 故障排除 Q13

2.8 映象拉取失敗或速度慢？

問題場景：執行 docker compose pull 時報錯或下載速度極慢。

解決方案：

bash

# 1. 配置 Docker 映象加速器
# Docker Desktop > Settings > Docker Engine
# 新增以下配置：
{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

# 2. 使用阿里雲映象倉庫
export VERSION=v0.1.0
docker pull registry.cn-beijing.aliyuncs.com/cuemate/cuemate-web:$VERSION

# 3. 手動匯入映象（從本地檔案）
docker load -i cuemate-images.tar

詳見：安裝問題 Q14 | 故障排除 Q12

2.9 資料丟失或資料庫損壞？

問題場景：歷史對話、知識庫文件或配置丟失，或提示資料庫錯誤。

恢復步驟：

bash

# 1. 停止所有服務
cd /Applications/CueMate.app/Contents/Resources/app.asar.unpacked/resources/config
docker compose down

# 2. 檢查資料檔案完整性
ls -lh ~/Library/Application\ Support/cuemate-desktop-client/data/sqlite/
ls -lh ~/Library/Application\ Support/cuemate-desktop-client/data/chroma/

# 3. 從備份恢復
tar -xzf cuemate_backup_20260115.tar.gz
cp -r sqlite_20260115/* ~/Library/Application\ Support/cuemate-desktop-client/data/sqlite/
cp -r chroma_20260115/* ~/Library/Application\ Support/cuemate-desktop-client/data/chroma/

# 4. 重啟服務
docker compose up -d

詳見：故障排除 Q3 | Q17

2.10 AI 回答質量差或答非所問？

問題場景：AI 生成的答案不準確、不相關或質量低。

最佳化建議：

提升模型質量：
- 使用更強大的模型（gpt-4 > gpt-4o-mini > gpt-3.5-turbo）
- 增加知識庫相關文件，提供更多上下文
最佳化提示詞：
- Web 設定 > AI 配置 > System Prompt
- 新增具體的回答要求和格式說明
調整檢索引數：
- 增加檢索文件數量（top_k: 3 → 5）
- 調整相似度閾值（threshold: 0.7 → 0.6）

詳見：使用問題 Q10 | Q11

2.11 桌面應用無法安裝或啟動？

問題場景：macOS/Windows 桌面應用安裝失敗或開啟後閃退。

macOS：

bash

# 1. 允許未簽名應用（臨時）
sudo xattr -rd com.apple.quarantine /Applications/CueMate.app

# 2. 檢查許可權
系統偏好設定 > 安全性與隱私 > 通用 > 允許來自身份不明開發者的應用

# 3. 檢視應用日誌
tail -f ~/Library/Application\ Support/cuemate-desktop-client/data/logs/desktop-client/$(date +%Y-%m-%d)/error.log

Windows：

右鍵 .exe > 屬性 > 相容性 > 以管理員身份執行
關閉 Windows Defender 或新增到白名單

詳見：安裝問題 Q16 | Q17

2.12 WebSocket 連線失敗，實時功能不可用？

問題場景：語音識別、實時訊息等功能無法使用，提示 WebSocket 連線錯誤。

診斷步驟：

bash

# 1. 檢查 CueMate-ASR 服務狀態
docker logs cuemate-asr

# 2. 測試 WebSocket 連線
wscat -c ws://localhost:10095

# 3. 檢查防火牆設定
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

# 4. 檢視網路日誌
docker logs cuemate-web-api | grep WebSocket

詳見：故障排除 Q9 | 使用問題 Q2

2.13 配置檔案修改後不生效？

問題場景：修改了配置檔案（docker-compose.yml, .env 等），但服務行為未改變。

解決方法：

bash

# 1. 重新載入配置並重啟服務
cd /Applications/CueMate.app/Contents/Resources/app.asar.unpacked/resources/config
docker compose down
docker compose up -d

# 2. 強制重新構建映象（生產環境透過應用更新）
# 請下載新版本安裝包重新安裝

# 3. 清除快取
docker system prune -a

# 4. 驗證配置是否生效
docker exec cuemate-web-api env | grep YOUR_CONFIG

詳見：故障排除 Q15 | Q11

2.14 應用更新失敗或版本回退？

問題場景：桌面應用自動更新失敗，或更新後出現問題需要回退。

處理步驟：

bash

# 1. 手動下載最新版本
# 訪問 https://github.com/cuemate-chat/cuemate/releases

# 2. 清理舊版本資料（可選）
rm -rf ~/Library/Application\ Support/cuemate-desktop-client/updates/

# 3. 回退到舊版本
# 從備份恢復舊版本的 CueMate.app
cp -r ~/backup/CueMate.app /Applications/

# 4. 檢視更新日誌
tail -f ~/Library/Application\ Support/cuemate-desktop-client/data/logs/updater/*/info.log

詳見：安裝問題 Q18 | 使用問題 Q15

2.15 如何定期備份資料和監控系統健康？

問題場景：希望定期自動備份資料，並監控系統執行狀態。

自動化指令碼：

備份指令碼 (~/cuemate-backup.sh):

bash

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

mkdir -p $BACKUP_DIR
cd $BACKUP_DIR

# 備份資料庫和配置
cp -r "$DATA_DIR/sqlite" "sqlite_$DATE"
cp -r "$DATA_DIR/chroma" "chroma_$DATE"
cp -r "$DATA_DIR/config" "config_$DATE"

# 壓縮備份
tar -czf "cuemate_backup_$DATE.tar.gz" "sqlite_$DATE" "chroma_$DATE" "config_$DATE"

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

# 保留最近 7 天的備份
find $BACKUP_DIR -name "cuemate_backup_*.tar.gz" -mtime +7 -delete

定時任務 (crontab):

bash

# 每天凌晨 2 點自動備份
0 2 * * * /bin/bash ~/cuemate-backup.sh

詳見：故障排除 Q17 | Q19 | Q20

獲取幫助

如果以上內容無法解決你的問題：

傳送郵件至：nuneatonhydroplane@gmail.com
加入社羣討論：GitHub Discussions
提交 Bug 報告：GitHub Issues
檢視完整文件：CueMate 文件

反饋建議

我們非常重視你的反饋，請透過以下方式告訴我們：

文件改進建議
新功能需求
使用體驗反饋
Bug 報告

常見問題 ​

1. 快速導航 ​

1.1 安裝問題 (20 個問題) ​

1.2 使用問題 (20 個問題) ​

1.3 故障排除 (20 個問題) ​

2. 熱門問題 TOP 15 ​

2.1 Docker Desktop 無法啟動或安裝失敗？ ​

2.2 語音識別不準確，識別結果有錯誤？ ​

2.3 API Key 配置後無法使用或報錯？ ​

2.4 服務啟動失敗，Docker 容器無法執行？ ​

2.5 系統資源佔用過高（CPU/記憶體）？ ​

2.6 知識庫檢索無結果或結果不相關？ ​

2.7 埠衝突，服務無法繫結埠？ ​

2.8 映象拉取失敗或速度慢？ ​

2.9 資料丟失或資料庫損壞？ ​

2.10 AI 回答質量差或答非所問？ ​

2.11 桌面應用無法安裝或啟動？ ​

2.12 WebSocket 連線失敗，實時功能不可用？ ​

2.13 配置檔案修改後不生效？ ​

2.14 應用更新失敗或版本回退？ ​

2.15 如何定期備份資料和監控系統健康？ ​

獲取幫助 ​

反饋建議 ​

常見問題

1. 快速導航

1.1 安裝問題 (20 個問題)

1.2 使用問題 (20 個問題)

1.3 故障排除 (20 個問題)

2. 熱門問題 TOP 15

2.1 Docker Desktop 無法啟動或安裝失敗？

2.2 語音識別不準確，識別結果有錯誤？

2.3 API Key 配置後無法使用或報錯？

2.4 服務啟動失敗，Docker 容器無法執行？

2.5 系統資源佔用過高（CPU/記憶體）？

2.6 知識庫檢索無結果或結果不相關？

2.7 埠衝突，服務無法繫結埠？

2.8 映象拉取失敗或速度慢？

2.9 資料丟失或資料庫損壞？

2.10 AI 回答質量差或答非所問？

2.11 桌面應用無法安裝或啟動？

2.12 WebSocket 連線失敗，實時功能不可用？

2.13 配置檔案修改後不生效？

2.14 應用更新失敗或版本回退？

2.15 如何定期備份資料和監控系統健康？

獲取幫助

反饋建議