返回下载页安装、启动与恢复
# 北医课程学习助手：固定版本安装说明
## 首次安装
目标平台：Windows x64 与 macOS Apple 芯片。网站只对完成验收的平台开放正式下载。
1. 下载固定版本 ZIP，核对网站上的 SHA-256，然后解压整个文件夹；不要在 ZIP 预览窗口内运行。
2. Windows 双击 `release/Install.cmd`；macOS 打开 `release/Setup.command`。入口下载并校验 uv 0.10.10，准备 Python 3.12.13。无需预装 Node.js。
3. 选择 Core、Blackboard、Video 或 Analysis。Blackboard 以上由安全安装器下载 pku3b 0.16.1。
4. Video/Analysis 需要 FFmpeg 和 ffprobe。安装前可使用现有 FFmpeg；macOS Homebrew 用户可运行 `brew install ffmpeg`，Windows 可按 https://ffmpeg.org/download.html 选择发行版本。重开安装窗口后重试。可在用户配置文件中填写 `FFMPEG_BINARY` 的完整路径；ffprobe 须与它在同一目录。
5. Analysis 额外安装锁定 ASR 依赖与 Paraformer 模型；安装器实际验证模型加载。首次下载耗时取决于网络，不是离线安装包。
6. 在应用“服务设置”中配置 AI/OCR 服务。教学网登录需要符合学校的网络与身份验证要求。
macOS 对未签名下载脚本/启动器可能要求系统确认。请核对来源与校验值，按系统“打开”流程操作；安装器不关闭 Gatekeeper。Windows 可能弹出脚本或 SmartScreen 确认。企业策略不允许运行时，请联系管理员，不修改全局安全策略。
## 日常启动与停止
用户目录：
- Windows：`%LOCALAPPDATA%\BJMUCourseAssistant`
- macOS：`~/Library/Application Support/BJMUCourseAssistant`
使用该目录里的应用启动入口；网页“启动已安装应用”可能需要浏览器确认。浏览器被关闭时服务仍继续运行。
维护命令（`<python>` 是安装目录 `runtimes/<版本>/<能力档>/bin/python`，Windows 为 `Scripts/python.exe`）：
```text
"<python>" "<用户目录>/desktop.py" start
"<python>" "<用户目录>/desktop.py" stop
"<python>" "<用户目录>/desktop.py" status
"<python>" "<用户目录>/desktop.py" backup
"<python>" "<用户目录>/desktop.py" restore "<备份目录>"
```
日常启动不执行依赖同步或模型下载。若依赖缺失，重新打开原发行包的安装入口进行修复；重新下载同一版本包也可修复安装。
默认服务地址 `http://127.0.0.1:8000`，只在本机访问。端口被其他程序占用时不会结束其他程序，请先关闭原服务。日志位于用户目录 `logs/backend.log`，分享日志前检查并隐藏私人内容。
## 数据、升级与恢复
用户目录中的 `data`、`uploads`、`recordings` 和 `config` 独立于 `releases/<版本>`。录像分析产物包括 `recordings/.analyses`，模型保存在 `models`。
新版本运行安装入口后会停止本安装的服务，创建升级前备份，再安装与迁移。保留旧版本目录和旧能力档运行时，不要手动删除。版本目录不得搬走；移动下载的 ZIP 或解压文件夹不会影响已安装应用。
备份包含 SQLite 一致性副本、资料、录像、分析产物及配置；不包含模型、日志或临时教学网会话。配置文件和备份可能包含私人信息，应留在自己的电脑上。系统凭据库中的密钥不导出，换机器需重新配置。
恢复前停止服务，使用 `restore` 恢复到原安装目录。恢复过程保存当前状态的额外备份。跨目录搬迁本阶段不支持，以避免数据库内文件绝对路径失效。
数据库结构升级后不能只切回旧代码；恢复对应升级前备份后才运行其记录的旧版本。重启会中断正在运行的任务，已完成结果保留。
## 下载与发布内容
发行包只含本应用运行代码、前端构建产物、迁移、锁文件、安装启动入口和说明；不含个人配置、课程录像或开发工作区。
Python/uv/PyTorch/模型/pku3b 下载需网络。FFmpeg、教学网、AI/OCR 的连通性需在用户机器上实测，发布站不代理这些业务请求。