feat: rebuild CSP practice workflow, UX and automation

docs/Docker部署.md

@@ -1,24 +1,137 @@
-# Docker Compose 部署
+# Docker Compose 部署指南
 
-## 一键启动
+## 1. 启动
 
 ```bash
 docker compose up -d --build
 ```
 
-## 访问
+查看状态：
 
-- 前端：http://localhost:7888
-- 后端（通过前端反代）：http://localhost:7888/admin139/api/health
-- 后端（注册）：`POST http://localhost:7888/admin139/api/v1/auth/register`
-- 后端（登录）：`POST http://localhost:7888/admin139/api/v1/auth/login`
+```bash
+docker compose ps
+docker compose logs --tail=100 backend
+docker compose logs --tail=100 frontend
+```
 
-## 数据持久化
+## 2. 访问地址
 
-- SQLite 数据库文件：compose volume `csp_data` -> 容器内 `/data/csp.db`
+- 前端：`http://<服务器IP>:7888/`
+- 后端健康检查（反代）：`http://<服务器IP>:7888/admin139/api/health`
 
-## 停止
+示例：
+
+- `http://caddns.pandoras.work:7888/`
+- `http://caddns.pandoras.work:7888/admin139/api/health`
+
+## 3. 端口与持久化
+
+- `7888:3000`（frontend 对外）
+- backend 默认不直接暴露端口（经 frontend 反代）
+- 数据卷：`csp_data` -> `/data/csp.db`
+
+## 4. 常用运维命令
 
 ```bash
 docker compose down
+docker compose up -d --build
+docker compose restart frontend backend
 ```
+
+## 4.1 初始化大规模题库（winterant/oi）
+
+```bash
+set -a; source .env; set +a
+python3 scripts/import_winterant_oi.py \
+  --db-path /var/lib/docker/volumes/csp_csp_data/_data/csp.db \
+  --workers 3 \
+  --clear-all-problems
+```
+
+当前导入流程为：下载 PDF -> LLM 识别 -> 固定 JSON 落库 + 任务状态落库（内置 500/502/503/504 自动重试）。
+
+仅下载导入、跳过 LLM：
+
+```bash
+python3 scripts/import_winterant_oi.py --skip-llm --workers 3
+```
+
+前端可通过 `/imports` 查看导入进度与明细结果。
+
+请在 `.env` 中配置：
+
+```env
+OI_LLM_API_URL=https://one.hao.work/v1/chat/completions
+OI_LLM_API_KEY=<your_key>
+OI_LLM_MODEL=qwen3-max
+OI_LLM_STREAM=true
+OI_LLM_RETRY_MAX=5
+OI_LLM_RETRY_SLEEP_SEC=1.5
+OI_PDF_RETRY_MAX=5
+OI_PDF_RETRY_SLEEP_SEC=1.5
+OI_IMPORT_DIRECT_FALLBACK=true
+OI_IMPORT_PREFER_DIRECT=true
+OI_IMPORT_AUTO_RUN=true
+OI_IMPORT_WORKERS=3
+OI_IMPORT_CLEAR_EXISTING=true
+OI_IMPORT_CLEAR_SOURCE_PREFIX=winterant/oi
+OI_IMPORT_CLEAR_ALL_PROBLEMS=false
+```
+
+## 5. 故障排查
+
+### 5.1 无法访问 7888
+
+1) 检查监听：
+```bash
+ss -ltnp | rg 7888
+```
+
+2) 检查容器端口映射：
+```bash
+docker compose ps
+```
+
+3) 本机探活：
+```bash
+curl -i http://127.0.0.1:7888/
+curl -i http://127.0.0.1:7888/admin139/api/health
+```
+
+### 5.2 检查是否被 Clash 拦截
+
+通常 inbound 到 `7888` 不会被 Clash 代理规则拦截，但可按下列方式确认：
+
+```bash
+ps -ef | rg clash
+cat /opt/clash/runtime.yaml | rg "allow-lan|port|socks-port|redir-port"
+iptables -t nat -S
+nft list ruleset
+```
+
+若你希望 Clash 自身也允许局域网访问（与本项目 7888 端口不是同一件事），可设置：
+
+- `/opt/clash/runtime.yaml` 中 `allow-lan: true`
+- 重启 Clash 服务/进程
+
+### 5.3 Docker 拉取慢/失败
+
+可为 Docker 配置镜像加速，例如：
+
+`/etc/docker/daemon.json`
+```json
+{
+  "registry-mirrors": ["https://docker.m.daocloud.io"]
+}
+```
+
+然后：
+```bash
+systemctl daemon-reload
+systemctl restart docker
+```
+
+## 6. 安全建议
+
+- 生产环境建议在 Nginx/Caddy 前加 TLS。
+- 在线编译运行属于高风险能力，建议部署到隔离沙箱执行。