# 组卷台部署交接 · 把胡小群组卷系统上线到服务器

**最后更新：2026-06-30**

> 交接背景：「课程设计机器人 / 胡小群题库」的**组卷台**已在本地（原 Mac）开发完成并验证，现要部署到 DIFrobot 服务器/网站，供所有老师在线使用。本文档是部署方的完整依据。题库本身的项目记忆见飞书《胡小群 L0-L6 题库·项目记忆》`AKK9deJDpodKrlxKcr6cc64cnkh`（部署不需要读全，但需要时在那）。

## 一、这个系统是什么

**组卷台** = 胡小群题库的网页组卷系统，老师按「年级→课程节」选题 → 加入试卷篮 → 预览/打印PDF/下载Word，再加了一个 **AI 讲解助手**（DeepSeek 对话讲解/出答案）。**纯前端胖 + 后端薄**：手动组卷全在客户端，只有 AI 功能需要后端。

## 二、系统构成（两部分，部署关键）

1. **前端 = 单个静态文件** `组卷台.html`（约 7.2 MB）
   - **完全自包含**：1750 道题数据、240 张配图（base64 内嵌）、课程结构都在 HTML 里；外部只依赖两个 CDN（MathJax、docx@9.7.1，公网可达即可）。
   - 纯静态，**直接托管就能用**（手动组卷、打印PDF、下载Word 全部不需要后端）。7.2 MB 首次加载略慢但可接受。
   - 生成器在本地 `gen_组卷台.py`（改题库数据/UI 后重跑生成新 HTML）。部署只需要产物 `组卷台.html` 这一个文件。

2. **原书页图文件夹 = `原书页/`（约 200 MB，「对照原书」功能依赖）**
   - 结构 `原书页/{dnj|jyf}/{1-6}/pNNN.jpg`：动脑筋/举一反三每册原书整页扫描图（压缩JPEG），供老师点题目上的「📖 对照原书」按钮对着原书核验真伪。
   - **部署时必须把这个文件夹和 `组卷台.html` 放在同一层**（HTML 用相对路径 `原书页/...` 引用）。纯静态托管直接一起传即可；不传则「对照原书」按钮点开显示"页图未找到"提示，其余功能不受影响。
   - 页码映射表 `原书页/page_ranges.json` 已在文件夹内（生成器用，部署不必单独处理）。
   - 兜底：`组卷台AI助手.py` 已支持——若 `原书页/` 缺失但仓库 `成果/*/pages/*.png` 在，助手会自动回退渲染（仅本地全仓场景）。胡小群教材暂无原书页（源PDF结构复杂），其题无此按钮。

3. **后端 = AI 代理**（只为「AI 讲解助手」服务）`组卷台AI助手.py`
   - 一个 stdlib http 代理：服务网页 + 暴露 `POST /api/chat`，转发到 DeepSeek，**把 API key 留在服务端**。
   - 前端 AI 面板调用**同源** `/api/chat`。所以部署后端时，`/api/chat` 必须和 `组卷台.html` **同域**（否则要处理 CORS）。
   - `AI_ON = location.protocol.startsWith('http')`：用 file:// 直开时 AI 不可用并提示；只要经 http(s) 访问且 /api/chat 通，AI 就能用。

## 三、部署方案（二选一）

**方案 A · 静态托管 + Serverless 函数（推荐，Vercel / Netlify / Cloudflare Pages）**
- 把 `组卷台.html` 作为静态资源部署。
- 把 `/api/chat` 实现成一个 serverless function（Node 或 Python 都行），逻辑照搬 `组卷台AI助手.py`：取 env 里的 key → 在 messages 前面加 SYS_PROMPT → POST 到 DeepSeek → 回 `{ok,content}`。
- key 放平台的 **环境变量 / Secret**，绝不进代码/git。
- 路由让 `/api/chat` 与页面同域即可（Vercel/Netlify 默认 `/api/*` 即函数）。

**方案 B · 自有服务器 / VPS 跑 Python**
- 直接跑 `组卷台AI助手.py`（默认监听 127.0.0.1:8848，部署时改成 0.0.0.0 或放 nginx 后面；建议 gunicorn/uvicorn 包一层或用 systemd 守护）。
- nginx 同时把 `组卷台.html` 和 `/api/chat` 反代到同一域名。
- key 用服务器环境变量注入（代理已支持回退读 `DEEPSEEK_API_KEY` env；本地是从 `~/.deepseek_pro_key` 读）。

## 四、DeepSeek 配置（/api/chat 契约）

- **endpoint**：`https://api.deepseek.com/chat/completions`（OpenAI 兼容）
- **模型**：`deepseek-v4-pro`（供应商也支持 `deepseek-v4-flash`；注意 `deepseek-chat`/`deepseek-reasoner` 都会映射到 flash，要 pro 必须传 `deepseek-v4-pro`）
- **请求**：代理收前端的 `{messages:[{role,content},...]}` → 在最前面插一条 system（解题老师 prompt，见 `组卷台AI助手.py` 的 `SYS_PROMPT`）→ 调 DeepSeek（`temperature 0.3, max_tokens 1600, stream false`）
- **返回**：`{ok:true, content:"...", usage:{...}}` 或 `{ok:false, error:"..."}`（前端据 ok 渲染或报错）
- **认证**：HTTP header `Authorization: Bearer <KEY>`

## 五、🔴 安全红线（必须遵守）

1. **API key 绝不进代码、前端、git、日志**。key 当前值在原 Mac 的 `~/.deepseek_pro_key`（600 权限）；部署时从那里取或问用户，**作为服务器环境变量/Secret 注入**。本文档不写 key 明文。
2. **公开后 /api/chat 会被任何人调用 → 可能刷爆 DeepSeek 额度**。上线前**务必加防滥用**：最简可加 referer/origin 校验（只允许本站来源）+ 简单速率限制；更稳可加一个轻口令或登录。**这条要明确告诉用户、由用户拍板防护级别**。
3. **题库零答案红线**：题库本身不含答案；AI 生成的讲解/答案只在前端展示、已标「⚠AI生成·请核对」，**不写回题库**。部署不改变这点。

## 六、当前功能状态

- ✅ 手动组卷（年级→课程节选题、讲义+课后合并、例/练习分区、打印PDF、下载原生.docx、配图进Word、表格题真表格）——**纯前端，部署即用**。
- ✅ AI 功能 A：讲解/出答案（DeepSeek v4-pro，需后端 /api/chat）。
- ⬜ 未做：AI 功能 B 出类似题、C 联网搜索（部署不依赖，后续再加）。

## 七、本地文件（原 Mac，路径）

- 前端产物：`~/Desktop/AI workspace/课程设计机器人/成果/胡小群题库/组卷台.html`（部署就用它）
- 后端参考实现：`~/Desktop/AI workspace/课程设计机器人/成果/胡小群题库/组卷台AI助手.py`
- 本地启动器（参考用法）：`同目录/启动组卷台AI助手.command`
- 生成器（改数据/UI 重跑）：`同目录/gen_组卷台.py`
- key：`~/.deepseek_pro_key`

## 八、给部署方的建议步骤

1. 决定方案 A（serverless，省运维，推荐）还是 B（VPS）。问用户服务器/托管平台是什么（Vercel/Netlify/Cloudflare/自有 VPS/宝塔等）。
2. 先把 `组卷台.html` 静态部署上去，验证手动组卷/打印/下载 Word 正常（这步不需要 key）。
3. 再实现 `/api/chat`（照搬 `组卷台AI助手.py` 逻辑），key 进环境变量，验证 AI 讲解能用。
4. **加防滥用**（origin 校验 + 限流），再正式公开。
5. 公开发布属红线，**上线前与用户确认域名、防护级别、是否需要登录门槛**。

## 变更日志

- **2026-06-30** 建立部署交接文档，交接给部署 session 上线组卷台。