服务管理
本文档介绍如何通过 CueMate 的 主窗口管理后端服务，包括查看服务状态、重启服务、查看日志等操作。
1. 服务概览
NOTE
CueMate 采用微服务架构，所有后端服务通过 Docker 容器运行。正常情况下，所有 6 个服务应该处于"运行中"状态。
CueMate 包含 6 个后端服务容器，所有服务通过 Docker 容器运行：
| 序号 | 服务名称 | 容器名称 | 端口 | 职责说明 |
|---|---|---|---|---|
| 1 | 主窗口服务 | cuemate-web | 80 | 提供主窗口访问 |
| 2 | 后端 API 服务 | cuemate-web-api | 3001 | 业务逻辑、用户认证、数据管理 |
| 3 | 大模型路由服务 | cuemate-llm-router | 3002 | LLM 请求路由、流式响应处理 |
| 4 | 知识库检索服务 | cuemate-rag-service | 3003 | 向量检索、语义搜索 |
| 5 | 语音识别服务 | cuemate-asr | 10095 | 实时语音转文字 |
| 6 | 向量数据库 | cuemate-chroma | 8000 | 向量数据存储 |
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