常见问题

本章节收集了 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 :80,3001,3002,3003,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 端口冲突，服务无法绑定端口？

问题场景：启动服务时提示端口已被占用（80, 3001, 3002, 3003, 8000, 10095）。

解决步骤：

bash

# 1. 查找占用端口的进程
lsof -i :80
lsof -i :3001

# 2. 停止占用端口的进程
kill -9 <PID>

# 3. 或修改 CueMate 使用的端口
# 编辑 infra/docker/docker-compose.yml
# 修改 ports 映射（如 80:80 改为 8080:80）

详见：安装问题 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 如何定期备份数据和监控系统健康？

获取帮助

反馈建议