csp/docs/Docker部署.md

Docker Compose 部署指南

1. 启动

docker compose up -d --build

查看状态：

docker compose ps
docker compose logs --tail=100 backend
docker compose logs --tail=100 frontend

2. 访问地址

• 前端：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. 常用运维命令

docker compose down
docker compose up -d --build
docker compose restart frontend backend

4.1 初始化大规模题库（winterant/oi）

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：

python3 scripts/import_winterant_oi.py --skip-llm --workers 3

前端可通过 /imports 查看导入进度与明细结果。

请在 .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. 检查监听：

ss -ltnp | rg 7888

2. 检查容器端口映射：

docker compose ps

3. 本机探活：

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 代理规则拦截，但可按下列方式确认：

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

{
  "registry-mirrors": ["https://docker.m.daocloud.io"]
}

然后：

systemctl daemon-reload
systemctl restart docker

6. 安全建议

• 生产环境建议在 Nginx/Caddy 前加 TLS。
• 在线编译运行属于高风险能力，建议部署到隔离沙箱执行。