版本升级
本文档介绍如何将 CueMate 升级到新版本。
1. 概述
CueMate 提供两种升级方式：通过版本管理功能在线更新和重新安装。推荐使用版本管理功能，操作简单且自动化程度高。
核心要点：
- 版本管理功能支持一键在线更新
- 更新过程会自动备份数据和回滚保护
- 所有面试记录、岗位信息、模型配置都会保留
- 查看 更新日志 了解新版本变更
2. macOS 升级
2.1 方法一：使用版本管理功能更新（推荐）
这是最简单快捷的升级方式，通过主应用窗口的版本管理功能一键完成更新。
2.1.1 进入 License 管理
- 打开 CueMate 主应用窗口
- 点击顶部下拉列表菜单
- 选择「License 管理」进入 License 管理页面
- 点击页面右上角的「版本管理」按钮
版本管理按钮说明：
- 无更新时：仅显示按钮文字和图标
- 有更新时：右上角显示红色数字徽章，提示可更新版本数量
2.1.2 查看版本列表
点击「版本管理」按钮后，从右侧弹出版本列表抽屉：
列表内容：
- 版本号（如 v0.2.0、v0.1.0）
- 发布日期（YYYY/MM/DD）
- 版本类型标签（当前版本 / 历史版本）
- 版本简介（一句话描述）
版本排序规则：
- 最新版本排在顶部
- 按版本号降序排列
- 当前使用的版本会标注「当前版本」标签
2.1.3 查看版本详情
点击版本列表中的某个版本，查看详细信息：
详情页面包含：
版本基本信息：
- 版本号：如 v0.2.0
- 发布时间：精确到秒
- 版本状态：当前版本 / 历史版本 / 最新版本
更新日志（Markdown 格式）：
- 新增功能列表
- 功能改进说明
- Bug 修复记录
- 已知问题说明
- 升级注意事项
操作按钮：
- 返回按钮：返回版本列表
- 更新到此版本：执行版本更新
2.1.4 执行版本更新
在版本详情页面，点击「更新到此版本」按钮执行更新：
更新流程：
1. 点击更新按钮
- 位置：版本详情页面底部
- 按钮文字：「更新到此版本 vX.X.X」
- 颜色：蓝色主题色
2. 确认更新
- 弹出确认对话框
- 提示：是否确认更新到 vX.X.X 版本
- 警告：更新过程中请勿关闭应用
3. 下载更新包
- 显示下载进度条
- 显示下载速度和剩余时间
- 支持断点续传
4. 安装更新
- 自动解压更新包
- 备份当前版本
- 替换应用文件
- 更新数据库结构（如需要）
5. 重启应用
- 提示：更新完成，准备重启
- 倒计时：5 秒后自动重启
- 也可手动点击「立即重启」
更新注意事项：
- 更新前会自动备份当前版本
- 更新失败会自动回滚到原版本
- 重要数据会在更新前自动备份
- 建议在非高峰期执行更新
2.2 方法二：重新安装
如果版本管理功能无法使用或遇到问题，可以通过重新安装的方式升级。
2.2.1 卸载当前版本
按照 完全卸载指南 卸载当前版本：
重要：卸载时选择 保留数据文件（不要删除 cuemate-desktop-client 文件夹）
卸载步骤：
- 退出 CueMate 应用（点击菜单栏图标 > 退出）
- 打开"应用程序"文件夹，将 CueMate.app 拖到废纸篓
- 不要删除
~/Library/Application Support/cuemate-desktop-client文件夹 - 清空废纸篓
2.2.2 安装新版本
按照 macOS 安装指南 下载并安装新版本：
- 下载最新版本的 DMG 安装包
- 双击 DMG 文件，运行安装向导
- 按照向导提示完成安装
- 登录系统（使用原来的账户 admin/cuemate）
- 所有数据会自动恢复（因为保留了 cuemate-desktop-client 文件夹）
2.2.3 验证升级
安装完成后，确认：
- 版本号已更新（在版本管理中查看）
- 所有数据和配置都已保留
- 后端服务正常运行
3. Windows 升级
开发中
Windows 版本正在开发中，预计在下一个版本发布。当前版本仅支持 macOS 平台。
如果你是 Windows 用户，建议：
- 关注 更新日志 了解 Windows 版本发布进度
- 加入社区群组获取最新开发动态
- 或者在 Windows 上安装 WSL 2，使用 Linux 版本（需要一定技术基础）
Windows 版本的升级步骤将在正式发布后更新。
4. 升级前准备
4.1 备份数据（可选）
虽然版本管理功能会自动备份数据，但建议在升级前手动备份重要数据：
# 创建备份目录
mkdir -p ~/Desktop/cuemate-backup-$(date +%Y%m%d)
# 备份整个 cuemate-desktop-client 文件夹
cp -r ~/Library/Application\ Support/cuemate-desktop-client ~/Desktop/cuemate-backup-$(date +%Y%m%d)/4.2 查看更新日志
在版本详情页面查看更新日志，了解：
- 新增了哪些功能
- 修复了哪些问题
- 是否有破坏性变更
- 升级注意事项
4.3 确认网络连接
版本更新需要下载更新包，确保：
- 网络连接稳定
- 有足够的下载速度
- 磁盘空间充足
5. 验证升级
5.1 检查版本号
升级完成后，进入版本管理查看当前版本是否已更新。
5.2 测试核心功能
建议测试以下功能确保升级成功：
- [ ] 登录系统
- [ ] 查看岗位列表（确认数据完整）
- [ ] 查看面试押题（确认数据完整）
- [ ] 测试语音识别功能
- [ ] 测试 AI 提问功能
- [ ] 查看模型配置（确认配置保留）
5.3 检查服务状态
进入 容器监控 页面，确认所有 6 个后端服务容器正常运行：
- cuemate-web - 主窗口服务
- cuemate-web-api - 后端 API 服务
- cuemate-llm-router - 大模型路由服务
- cuemate-rag-service - 知识库检索服务
- cuemate-asr - 语音识别服务
- cuemate-chroma - 向量数据库
所有容器的运行状态应该显示为"运行中"（绿色标签）。如果有容器状态异常，请参考 容器监控 页面的故障排查说明。
6. 常见问题
6.1 版本管理按钮没有显示更新提示
问题：版本管理按钮上没有显示红色数字徽章
可能原因：
- 已经是最新版本
- 网络连接问题，无法获取版本信息
- License 未激活
解决方法：
- 检查网络连接
- 确认 License 已上传并激活
- 手动进入版本管理查看版本列表
- 刷新页面重新检查
6.2 下载更新包失败
问题：更新过程中提示下载失败
可能原因：
- 网络连接不稳定
- 下载服务器繁忙
- 磁盘空间不足
解决方法：
- 检查网络连接是否稳定
- 确认磁盘有足够空间（至少 10GB）
- 稍后重试
- 使用重新安装的方式升级
6.3 更新后无法启动
问题：更新完成重启后应用无法启动
解决方法：
系统会自动回滚到更新前的版本，如果自动回滚失败：
# 强制退出应用
killall CueMate
# 检查备份是否存在
ls -la ~/Library/Application\ Support/cuemate-desktop-client/backups/
# 手动恢复备份（如果需要）
# 联系技术支持获取帮助6.4 更新后数据丢失
问题：更新后找不到之前的数据
可能原因：
- 数据备份未正确恢复
- 数据库迁移失败
解决方法：
- 检查
~/Library/Application Support/cuemate-desktop-client文件夹是否完整 - 检查备份文件夹中是否有数据备份
- 从手动备份恢复数据
- 联系技术支持
7. 回滚到旧版本
如果更新后遇到严重问题，可以回滚到旧版本。
7.1 使用版本管理回滚
- 打开版本管理
- 在版本列表中选择之前的版本
- 点击「更新到此版本」
- 确认回滚操作
- 等待回滚完成并重启
7.2 从备份恢复
如果版本管理功能无法使用：
# 停止 CueMate 应用
killall CueMate
# 恢复数据备份
cp -r ~/Desktop/cuemate-backup-20260113/cuemate-desktop-client ~/Library/Application\ Support/
# 重新安装旧版本
# 下载旧版本 DMG 并运行安装向导8. 反馈与支持
如果你在升级过程中遇到问题：
- 查看 常见问题
- 访问 GitHub Issues
- 发送邮件至：nuneatonhydroplane@gmail.com
相关页面
- License 管理 - 管理 License 和版本
- 更新日志 - 查看版本变更历史
- 完全卸载 - 完全卸载 CueMate
- macOS 安装 - 安装指南