PhysicsCorrection/README_DOCKER.md

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

📦 快速开始

一键部署

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

手动部署

# 构建镜像
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

🧪 测试验证

# 运行测试脚本
./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
  

🔧 常用命令

容器管理

# 查看状态
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 接口

批改接口

请求:

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: 容器无法启动

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

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

问题 2: LLM 调用失败

# 检查环境变量
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 404 错误修复

⚠️ 安全提示

当前 Dockerfile 将 API Key 硬编码在镜像中：

• ✅ 优点：部署简单，无需额外配置
• ❌ 缺点：密钥会暴露在镜像中

安全建议

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

🎯 验证成功标志

部署成功后，应该看到：

# 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