安装问题
本文档汇总了 CueMate 安装过程中的常见问题和解决方案。
提示
如果你是第一次安装 CueMate，建议先阅读 macOS 安装指南 了解完整的安装流程。
1. macOS 平台
1.1 如何确定我的 Mac 芯片类型？
问题描述：不知道自己的 Mac 是 Apple Silicon 还是 Intel 芯片，不确定下载哪个版本。
解决方法：
点击屏幕左上角的 Apple 菜单 → 关于本机，查看 芯片 或 处理器 信息：
- 如果看到 "Apple M1"、"Apple M2" 或 "Apple M3"，下载 Apple Silicon 版本（arm64）
- 如果看到 "Intel"，下载 Intel 版本（x64）
1.2 我的 Mac 符合系统要求吗？
问题描述：不确定自己的 Mac 是否满足 CueMate 的安装要求。
系统要求
CueMate 需要：
- 操作系统：macOS 13.0 (Ventura) 或更高版本
- 处理器：Apple Silicon (M1/M2/M3) 或 Intel 芯片
- 内存：>= 8GB RAM
- 磁盘空间：>= 10GB 可用空间
- 网络连接：稳定的互联网连接
检查方法：
- 点击 Apple 菜单 → 关于本机
- 查看 macOS 版本、芯片类型、内存大小
- 查看存储空间是否充足
1.3 下载速度太慢怎么办？
问题描述：下载 CueMate 安装包速度很慢，或者下载中断。
选择下载渠道建议
- 国内用户：优先使用百度网盘（速度快、稳定）
- 海外用户：使用 GitHub Releases（全球 CDN）
下载渠道对比：
| 序号 | 渠道 | 适用地区 | 下载速度 | 优势 | 劣势 |
|---|---|---|---|---|---|
| 1 | 百度网盘 | 中国大陆 | 极快 | 无需科学上网 | 需要百度账号 |
| 2 | GitHub Releases | 全球 | 快 | 官方更新快 | 国内可能较慢 |
百度网盘下载：
GitHub Releases 下载：
1.4 安装向导无法打开
问题描述：双击安装向导图标后没有反应，或提示"无法打开 CueMate 安装向导，因为它来自身份不明的开发者"。
macOS 安全机制
这是 macOS 的 Gatekeeper 安全机制。CueMate 安装向导是安全的，但因未经过 Apple 公证，首次打开需要手动授权。
解决方法：
方式一：系统设置中允许（推荐）
- 打开 系统设置（或 系统偏好设置）
- 进入 隐私与安全性
- 向下滚动，找到提示信息"CueMate 安装向导已被阻止"
- 点击 仍要打开 按钮
方式二：右键打开
- 右键点击（或按住 Control 键点击）安装向导图标
- 选择"打开"
- 在弹出的对话框中点击"打开"按钮
最佳实践
如果仍然无法打开：
- 重新下载安装包（可能文件损坏）
- 检查下载的文件是否完整（文件大小应该约 5GB）
- 尝试使用终端命令移除隔离属性：
sudo xattr -rd com.apple.quarantine /Applications/CueMate\ 安装向导.app
1.5 磁盘空间不足
问题描述：安装向导提示"磁盘空间不足，无法继续安装"。
IMPORTANT
CueMate 安装需要至少 10GB 可用磁盘空间，包括：
- 应用本身：约 2GB
- Docker 镜像：约 6GB
- 运行数据和日志：约 2GB
解决方法：
清理磁盘：
- 删除不需要的文件和应用
- 清空"下载"文件夹
- 清空废纸篓
- 使用 macOS 自带的"存储空间管理"工具
查看磁盘空间：
- 点击 Apple 菜单 → 关于本机 → 存储空间
- 确保至少有 10GB 可用空间
更换安装位置：
- 在安装向导的"安装位置"步骤
- 点击"选择其他位置"
- 选择空间充足的其他磁盘
清理后重新检测：
- 返回安装向导
- 点击"重新检测"按钮
1.6 Docker Desktop 未安装
问题描述：安装向导提示"Docker Desktop 未安装"。
解决方法：
方式一：通过安装向导自动安装（推荐）
- 点击安装向导中的 自动安装 按钮
- 安装向导会打开 Docker Desktop 官方下载页面
- 下载并安装 Docker Desktop：
- 双击下载的
.dmg文件 - 拖拽 Docker 图标到"应用程序"文件夹
- 打开 Docker Desktop，完成初始化设置
- 双击下载的
- 返回 CueMate 安装向导，点击 重新检测
方式二：手动下载安装
- 访问 Docker 官网：https://www.docker.com/products/docker-desktop/
- 根据你的芯片类型选择对应版本下载
- 安装完成后，启动 Docker Desktop
- 等待 Docker 启动完成（底部状态栏显示 "Docker Desktop is running"）
- 返回 CueMate 安装向导，点击 重新检测
1.7 Docker Desktop 无法启动
问题描述：Docker Desktop 已安装，但安装向导提示"Docker 服务未运行"。
NOTE
Docker Desktop 是 CueMate 运行的核心依赖，所有后端服务都运行在 Docker 容器中。如果 Docker 无法启动，CueMate 将无法正常工作。
可能原因：
- macOS 版本过低（需要 macOS 13.0 (Ventura) 或更高）
- 系统虚拟化功能未启用
- Docker Desktop 安装不完整
- 其他虚拟化软件冲突（如 VirtualBox、VMware）
解决方法：
手动启动 Docker：
- 打开"应用程序"文件夹
- 双击启动 Docker Desktop
- 等待启动完成（约 10-30 秒）
- 返回安装向导，点击"重新检测"
检查 macOS 版本：
- 点击 Apple 菜单 → 关于本机
- 确认版本号 >= macOS 13.0 (Ventura)
重新安装 Docker Desktop：
- 卸载当前 Docker Desktop
- 重新下载最新版本
- 重新安装
重启 Mac：
- 完全关机后重新启动
- 启动后先打开 Docker Desktop
- 再运行 CueMate 安装向导
检查虚拟化冲突：
- 卸载其他虚拟化软件（VirtualBox、VMware 等）
- 或暂时退出这些软件
- 重新启动 Docker
1.8 端口被占用
问题描述：安装向导提示"端口被占用，无法启动服务"。
CueMate 使用的端口
请确保以下端口未被其他程序占用：
| 端口 | 服务 | 说明 |
|---|---|---|
80 | Nginx | Web 前端服务 |
3001 | web-api | 业务 API 服务 |
3002 | llm-router | LLM 路由服务 |
3003 | rag-service | 知识库检索服务 |
8000 | ChromaDB | 向量数据库 |
10095 | CueMate-ASR | 语音识别服务 |
解决方法：
方式一：使用安装向导自动解决（推荐）
- 安装向导会显示占用端口的程序名称
- 点击 自动解决 按钮
- 安装向导会尝试关闭占用端口的程序
- 自动重新检测端口状态
方式二：手动关闭占用程序
- 打开"活动监视器"（应用程序 > 实用工具）
- 在搜索框中输入端口号或程序名称
- 找到占用端口的程序
- 选中程序，点击左上角的"×"按钮强制退出
- 返回安装向导，点击 重新检测
方式三：使用终端命令查找并关闭（高级用户）
# 查看端口占用情况
lsof -i :80
lsof -i :3001
# 强制关闭占用进程（替换 <PID> 为实际进程 ID）
kill -9 <PID>WARNING
使用 kill -9 强制结束进程前，请确认该进程不是系统关键服务！强制结束系统服务可能导致 macOS 运行异常。
如果无法关闭占用程序：
- 检查是否为系统关键服务
- 重启 Mac 后再次尝试安装
- 或更换其他端口（需要修改 CueMate 配置文件，不推荐新手操作）
1.9 镜像加载失败
问题描述：安装向导在"镜像加载"步骤失败，提示"镜像加载失败，请重试"。
可能原因：
- 网络连接中断
- Docker 服务异常
- 磁盘空间不足
- 安装包损坏
解决方法：
检查网络连接：
- 确认网络连接正常
- 尝试访问其他网站测试网络
- 如果使用 Wi-Fi，尝试切换到有线网络
检查 Docker 状态：
- 打开 Docker Desktop
- 确认底部状态栏显示 "Docker Desktop is running"
- 如果 Docker 异常，重启 Docker Desktop
检查磁盘空间：
- 确认至少有 10GB 可用空间
- Docker 镜像会占用约 3-5GB 空间
- 清理磁盘后点击"重试"
重试加载：
- 点击安装向导中的 重试 按钮
- 等待重新加载（可能需要 3-5 分钟）
重新下载安装包：
- 如果多次重试失败，可能是安装包损坏
- 重新下载安装包
- 确认下载完整（文件大小约 5GB）
查看详细日志：
- 点击安装向导中的"查看日志"按钮
- 记录错误信息
- 联系技术支持
1.10 镜像加载时间过长
问题描述：镜像加载步骤等待时间超过 10 分钟。
TIP
镜像加载时间因设备配置而异：
- 高配 Mac（M1/M2/M3 + SSD）：3-5 分钟
- 低配 Mac 或机械硬盘：5-10 分钟
- 超过 15 分钟：可能出现问题，建议重试
原因：
- 首次加载需要从安装包中解压并加载约 3GB 的 Docker 镜像
- 低配置 Mac 或使用机械硬盘会较慢
- Docker 服务响应缓慢
解决方法：
耐心等待：
- 正常情况下需要 3-5 分钟
- 低配置设备可能需要 5-10 分钟
- 不要关闭安装向导
检查进度指示：
- 安装向导会显示当前加载的镜像名称
- 显示百分比进度
- 如果进度长时间不变（超过 5 分钟），可能出现问题
优化 Docker 性能：
- 打开 Docker Desktop 设置
- 增加分配给 Docker 的内存和 CPU
- 建议：内存 4GB+，CPU 2 核+
使用 SSD 硬盘：
- 机械硬盘加载速度会很慢
- 建议将 CueMate 安装到 SSD 上
1.11 安装完成但无法启动应用
问题描述：安装向导显示"安装完成"，但点击"完成"后应用无法启动。
解决方法：
手动启动应用：
- 打开"应用程序"文件夹
- 找到 CueMate.app
- 双击启动
检查服务状态：
- 打开 Docker Desktop
- 查看容器列表
- 确认 CueMate 相关容器是否在运行
- 如果容器未运行，详见 服务管理
查看应用日志：
- 打开"终端"应用
- 运行命令查看日志：bash
tail -f ~/Library/Application\ Support/cuemate-desktop-client/data/logs/*/$(date +%Y-%m-%d)/error.log
重新安装：
- 如果以上方法都无效
- 先卸载 CueMate（详见 卸载指南）
- 重新运行安装向导
1.12 麦克风权限未授予
问题描述：使用语音识别功能时，提示"麦克风权限未授予"或"无法访问麦克风"。
解决方法：
授予权限（首次使用）：
- 使用麦克风功能时会自动弹出授权提示
- 点击 好 按钮授予权限
手动检查权限设置：
- 打开 系统设置 > 隐私与安全性
- 在左侧菜单中找到并点击 麦克风
- 在右侧应用列表中找到 CueMate
- 勾选其右侧的开关
重启应用：
- 完全退出 CueMate（菜单栏图标 > 退出）
- 重新启动 CueMate
- 再次测试语音功能
1.13 录屏与系统录音权限未授予
问题描述：无法使用面试官语音识别功能，提示"需要录屏与系统录音权限"。
NOTE
为什么需要这个权限？
- CueMate 使用"录屏与系统录音"权限来捕获系统音频
- 仅用于音频捕获，不会录制屏幕画面
- 用于识别面试软件（如腾讯会议、钉钉等）播放的面试官语音
解决方法：
首次使用扬声器测试功能时，系统会自动弹出授权提示框，请点击 允许 按钮授予 CueMate 访问系统音频的权限。
如果误点了"不允许"或意外关闭了授权窗口：
- 打开 系统设置 > 隐私与安全性
- 在左侧菜单中找到并点击 录屏与系统录音
- 在右侧应用列表中找到 CueMate，勾选其右侧的开关以启用系统音频捕获权限
- 如果列表中没有 CueMate，可以点击列表底部的 "+" 按钮手动添加
- 授权后无需重启应用，直接返回 CueMate 即可使用
1.14 授予权限后仍无法使用
问题描述：已经授予了麦克风或录屏权限，但功能仍然不工作。
解决方法：
完全重启 CueMate：
- 点击菜单栏的 CueMate 图标
- 选择 退出 CueMate（确保完全退出，不是最小化）
- 重新从"应用程序"文件夹启动 CueMate
检查权限设置：
- 进入 系统设置 > 隐私与安全性
- 分别检查 麦克风 和 录屏与系统录音
- 确认 CueMate 已被勾选
重置权限：
- 在系统设置中取消勾选 CueMate
- 完全退出 CueMate
- 重新启动 CueMate
- 使用相关功能时会再次弹出授权提示
- 重新授权
检查设备连接：
- 确认麦克风设备已正确连接
- 打开"系统设置" > "声音"
- 确认输入设备选择正确
- 对着麦克风说话，观察输入电平是否有变化
重启 Mac：
- 如果以上方法都无效
- 尝试重启 Mac
- 重启后重新测试
1.15 无法登录系统
问题描述：输入账户信息后提示"用户名或密码错误"。
解决方法：
使用内置账户：
- 用户名：
admin - 密码：
cuemate - 注意：密码区分大小写，全部小写
- 用户名：
检查输入：
- 确认没有多余的空格
- 确认没有开启大写锁定
- 尝试复制粘贴账户信息
检查服务状态：
- 点击菜单栏的 CueMate 图标
- 选择"容器监控"
- 确认
cuemate-web-api服务正在运行 - 如果服务未运行，点击"重启"按钮
清除缓存重试：
- 完全退出 CueMate
- 清除浏览器缓存（如果使用的是 Web 界面）
- 重新启动 CueMate
1.16 主应用窗口无法打开
问题描述：点击控制窗口的"主应用窗口"按钮后无反应。
可能原因：
- 后端服务未启动
- 端口被占用
- 网络连接问题
解决方法：
检查服务状态：
- 点击菜单栏的 CueMate 图标
- 选择"容器监控"
- 确认所有 6 个服务都显示为"运行中"（绿色标签）
- 重点检查
cuemate-web和cuemate-web-api服务
重启服务：
- 在容器监控页面
- 点击异常服务的"重启"按钮
- 等待服务重启完成（约 30 秒）
- 再次尝试打开主应用窗口
检查端口：
- 打开"终端"应用
- 运行命令检查端口：bash
lsof -i :80 - 确认端口未被其他程序占用
使用浏览器直接访问：
- 打开浏览器
- 访问：http://localhost
- 如果能正常打开，说明服务正常
- 问题可能在桌面应用本身
重启 CueMate：
- 完全退出 CueMate
- 重新启动
- 再次尝试
1.17 服务启动失败
问题描述：在"容器监控"页面看到某些服务状态为"已停止"或"错误"。
解决方法：
详见 服务管理 - 服务启动失败。
1.18 安装包文件损坏
问题描述：提示"安装包文件损坏或不完整"。
解决方法：
- 删除已下载的安装包
- 重新下载完整的安装包
- 确认文件大小正确（约 5GB）
- 使用 MD5 或 SHA256 验证文件完整性（如果提供了校验值）
1.19 安装过程中断
问题描述：安装过程中意外退出或中断。
解决方法：
- 重新运行安装向导
- 安装向导会自动检测已完成的步骤
- 从中断的位置继续安装
- 如果无法继续，先卸载已安装的部分，重新开始
1.20 卸载后重新安装
问题描述：卸载 CueMate 后重新安装出现问题。
解决方法：
完全清理残留文件：
bash# 删除应用数据 rm -rf ~/Library/Application\ Support/cuemate-desktop-client # 删除 Docker 容器和镜像 docker compose -f ~/Library/Application\ Support/cuemate-desktop-client/docker-compose.yml down docker system prune -a重启 Mac：
- 清理完成后重启 Mac
- 重启后重新运行安装向导
使用全新安装包：
- 删除旧的安装包
- 下载最新版本的安装包
- 使用新的安装包进行安装
详见 卸载指南。
2. Windows 平台
开发中
Windows 版本正在开发中，敬请期待。
如果你对 Windows 版本有任何建议或需求，欢迎通过以下方式反馈：
- GitHub Issues：https://github.com/cuemate-chat/cuemate/issues
- 邮箱：nuneatonhydroplane@gmail.com
获取更多帮助
如果以上方法都无法解决你的问题，可以通过以下方式获取帮助：
查看文档
- macOS 安装指南 - 完整的安装步骤说明
- 快速开始 - 快速安装流程
- 服务管理 - 服务状态和日志查看
- 常见问题汇总 - 更多常见问题解答
联系技术支持
- GitHub Issues：https://github.com/cuemate-chat/cuemate/issues
- 邮箱：nuneatonhydroplane@gmail.com
提交问题时，请提供：
- macOS 版本号和芯片类型
- CueMate 版本号
- 详细的错误信息和截图
- 已尝试的解决方法