# 数学作业批改系统 - Docker 部署

## 📦 快速开始

### 一键部署

```bash
# 运行部署脚本
./deploy.sh
```

### 手动部署

```bash
# 构建镜像
docker build -t math-grading:latest .

# 启动容器
docker run -d \
  --name math-grading \
  -p 8000:8000 \
  -v $(pwd)/logs:/app/work/logs \
  -v $(pwd)/cache:/tmp/homework_cache \
  --restart unless-stopped \
  math-grading:latest
```

## 🧪 测试验证

```bash
# 运行测试脚本
./test.sh
```

## 📝 配置说明

### 已硬编码的配置

| 配置项 | 值 | 说明 |
|--------|-----|------|
| API 端点 | `https://api.coze.cn/v1` | 包含 /v1 前缀 |
| COZE_API_KEY | `Bearer eyJhbGci...` | Coze API 认证密钥 |
| COZE_WORKSPACE_ID | `7622238752642957347` | 工作区 ID |
| LLM_MODEL_NAME | `doubao-seed-2-0-pro-260215` | LLM 模型名称 |

### 配置来源

- **API Key**: 从原始 Dockerfile 中提取
- **Workspace ID**: 从 JWT Token 的 `sub` 字段提取
  ```
  spiffe://api.coze.cn/workload_identity/id:7622238752642957347
  ```

## 🔧 常用命令

### 容器管理

```bash
# 查看状态
docker ps | grep math-grading

# 查看日志
docker logs -f math-grading

# 停止服务
docker stop math-grading

# 启动服务
docker start math-grading

# 重启服务
docker restart math-grading

# 进入容器
docker exec -it math-grading /bin/bash
```

## 📊 API 接口

### 批改接口

**请求**:
```bash
curl -X POST http://localhost:8000/stream_run \
  -H "Content-Type: application/json" \
  -d '{
    "student_homework": [
      {
        "student_id": 1,
        "student_name": "张三",
        "homework_images": [
          "https://example.com/image1.jpg",
          "https://example.com/image2.jpg"
        ]
      }
    ],
    "answer_doc_url": "https://example.com/answers.docx",
    "comment_max_length": 50,
    "max_concurrent": 5
  }'
```

**参数说明**:
- `student_homework`: 学生作业列表
- `answer_doc_url`: 答案文档 URL（可选）
- `comment_max_length`: 评语最大字数（默认 50）
- `max_concurrent`: 并发批改数量（默认 5）

## 📁 目录结构

```
.
├── Dockerfile              # Docker 镜像配置（硬编码 KEY）
├── deploy.sh              # 一键部署脚本
├── test.sh                # 快速测试脚本
├── DOCKER_DEPLOY.md       # 详细部署文档
├── logs/                  # 日志目录
├── cache/                 # 缓存目录
└── src/                   # 源代码
```

## 🔍 故障排查

### 问题 1: 容器无法启动

```bash
# 查看详细日志
docker logs math-grading

# 检查端口占用
netstat -tuln | grep 8000
```

### 问题 2: LLM 调用失败

```bash
# 检查环境变量
docker exec math-grading env | grep COZE

# 应该看到:
# COZE_API_KEY=Bearer eyJhbGci...
# COZE_WORKSPACE_ID=7622238752642957347
# COZE_INTEGRATION_BASE_URL=https://api.coze.cn/v1
```

### 问题 3: 认证错误 (401)

- 确认 COZE_API_KEY 和 COZE_WORKSPACE_ID 都已设置
- 检查 Token 是否有效

### 问题 4: 端点错误 (404)

- 确认 API 端点包含 /v1 前缀
- 检查 COZE_INTEGRATION_BASE_URL 配置

## 📚 详细文档

- [完整部署指南](DOCKER_DEPLOY.md)
- [项目文档](AGENTS.md)
- [Docker 404 错误修复](assets/fix_docker_404.md)

## ⚠️ 安全提示

当前 Dockerfile 将 API Key 硬编码在镜像中：
- ✅ 优点：部署简单，无需额外配置
- ❌ 缺点：密钥会暴露在镜像中

### 安全建议

1. **使用私有仓库**：不要推送到公共 Docker Registry
2. **访问控制**：限制镜像拉取权限
3. **定期更换密钥**：在 Coze 平台定期更换 API Key
4. **生产环境**：考虑使用环境变量方式（参考 docker-compose.yml）

## 🎯 验证成功标志

部署成功后，应该看到：

```bash
# 1. 容器运行中
docker ps | grep math-grading
# Up 5 minutes

# 2. 健康检查通过
curl http://localhost:8000/health
# 200 OK

# 3. 日志无错误
docker logs math-grading | grep ERROR
# （无输出）

# 4. LLM 调用成功
# 日志显示:
# HTTP Request: POST https://api.coze.cn/v1/chat/completions "HTTP/1.1 200 OK"
```

## 📞 支持

如遇问题，请：
1. 查看日志: `docker logs -f math-grading`
2. 运行测试: `./test.sh`
3. 参考文档: `DOCKER_DEPLOY.md`