# Docker Compose 部署指南

## 1. 启动

```bash
docker compose up -d --build
```

查看状态：

```bash
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. 常用运维命令

```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。
- 在线编译运行属于高风险能力，建议部署到隔离沙箱执行。