# Docker 部署指南（硬编码 KEY 版本）

## 📋 配置说明

本 Dockerfile 已经将所有 API 配置和密钥硬编码在镜像中：

### 已硬编码的配置

| 配置项 | 值 |
|--------|-----|
| API 端点 | `https://api.coze.cn/v1` ✅（包含 /v1 前缀） |
| COZE_API_KEY | `Bearer eyJhbGci...` ✅ |
| LLM_API_KEY | `Bearer eyJhbGci...` ✅ |
| COZE_WORKSPACE_ID | `7622238752642957347` ✅ |
| LLM_MODEL_NAME | `doubao-seed-2-0-pro-260215` ✅ |

### Workspace ID 来源

从 JWT Token 的 `sub` 字段提取：
```
spiffe://api.coze.cn/workload_identity/id:7622238752642957347
```

## 🚀 快速部署

### 步骤 1：构建镜像

```bash
# 进入项目根目录
cd /workspace/projects

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

### 步骤 2：运行容器

```bash
# 运行容器（简单方式）
docker run -d \
  --name math-grading \
  -p 8000:8000 \
  --restart unless-stopped \
  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
```

### 步骤 3：验证服务

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

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

# 检查健康状态
curl http://localhost:8000/health
```

## 🧪 测试接口

### 测试 LLM 调用

```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://dpcclass.oss-cn-beijing.aliyuncs.com/umsupload/2026/03/18/69baa4f5-4826-4901-00e1-c6e66f02947f.jpg?x-oss-process=image/resize,w_1000"
        ]
      }
    ],
    "answer_doc_url": "",
    "comment_max_length": 50,
    "max_concurrent": 1
  }'
```

### 测试多图片批改

```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://dpcclass.oss-cn-beijing.aliyuncs.com/umsupload/2026/03/18/69baa4f5-4826-4901-00e1-c6e66f02947f.jpg?x-oss-process=image/resize,w_1000",
          "https://dpcclass.oss-cn-beijing.aliyuncs.com/umsupload/2026/03/25/69c344ba-4826-4901-00e1-c6ff235a12b2.jpg?x-oss-process=image/resize,w_1000"
        ]
      }
    ],
    "answer_doc_url": "https://dpcclass.oss-cn-beijing.aliyuncs.com/umsupload/2026/03/25/69c353d0-4826-4901-00e1-c7081bcab988.docx",
    "comment_max_length": 50,
    "max_concurrent": 2
  }'
```

## 🔧 常用命令

### 容器管理

```bash
# 停止容器
docker stop math-grading

# 启动容器
docker start math-grading

# 重启容器
docker restart math-grading

# 删除容器
docker rm -f math-grading

# 删除镜像
docker rmi math-grading:latest
```

### 日志查看

```bash
# 查看实时日志
docker logs -f math-grading

# 查看最近 100 行日志
docker logs --tail 100 math-grading

# 查看错误日志
docker logs math-grading 2>&1 | grep ERROR
```

### 进入容器

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

# 查看环境变量
docker exec math-grading env | grep COZE

# 运行 Python 脚本
docker exec math-grading python assets/check_env.py
```

## 📊 验证配置成功

### 成功标志

1. **容器启动成功**
   ```bash
   docker ps | grep math-grading
   # 应该显示容器运行中（Up status）
   ```

2. **日志无错误**
   ```bash
   docker logs math-grading | grep ERROR
   # 不应该有认证错误（401）或端点错误（404）
   ```

3. **健康检查通过**
   ```bash
   curl http://localhost:8000/health
   # 应该返回 200 OK
   ```

4. **LLM 调用成功**
   ```bash
   # 运行测试请求，日志应该显示：
   # ✅ HTTP Request: POST https://api.coze.cn/v1/chat/completions "HTTP/1.1 200 OK"
   ```

### 错误排查

#### 错误 1：容器无法启动

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

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

#### 错误 2：LLM 调用 401 错误

```bash
# 检查环境变量是否正确设置
docker exec math-grading env | grep COZE_API_KEY

# 应该看到：
# COZE_API_KEY=Bearer eyJhbGci...
```

#### 错误 3：LLM 调用 404 错误

```bash
# 检查 API 端点配置
docker exec math-grading env | grep BASE_URL

# 应该看到：
# COZE_INTEGRATION_BASE_URL=https://api.coze.cn/v1
# 注意要有 /v1 前缀
```

## 🔐 安全说明

### ⚠️ 密钥已硬编码

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

### 安全建议

1. **私有仓库**
   - 使用私有 Docker Registry（如阿里云容器镜像服务）
   - 不要将镜像推送到公共仓库

2. **访问控制**
   - 限制镜像访问权限
   - 使用 RBAC 控制镜像拉取

3. **定期更换密钥**
   - 定期在 Coze 平台更换 API Key
   - 重新构建镜像

4. **生产环境建议**
   - 使用环境变量方式（推荐）
   - 参考 `assets/docker-compose.yml`

## 📝 配置说明

### 环境变量列表

| 变量名 | 说明 | 值 |
|--------|------|-----|
| `COZE_API_KEY` | Coze API 认证密钥 | Bearer eyJhbGci... |
| `LLM_API_KEY` | LLM API 认证密钥 | Bearer eyJhbGci... |
| `COZE_WORKSPACE_ID` | 工作区 ID | 7622238752642957347 |
| `COZE_INTEGRATION_BASE_URL` | API 基础 URL | https://api.coze.cn/v1 |
| `COZE_INTEGRATION_MODEL_BASE_URL` | 模型 API 基础 URL | https://api.coze.cn/v1 |
| `LLM_BASE_URL` | LLM API 基础 URL | https://api.coze.cn/v1 |
| `LLM_MODEL_NAME` | LLM 模型名称 | doubao-seed-2-0-pro-260215 |
| `COZE_INTEGRATION_API_KEY` | 集成 API 密钥 | Bearer eyJhbGci... |

### 端口说明

| 端口 | 说明 |
|------|------|
| 8000 | HTTP 服务端口 |

### 目录说明

| 目录 | 说明 |
|------|------|
| /app | 应用工作目录 |
| /app/work/logs/bypass | 日志目录 |
| /tmp/homework_cache | 缓存目录 |

## 🎯 总结

### 一键部署命令

```bash
# 构建并运行
docker build -t math-grading:latest .
docker run -d --name math-grading -p 8000:8000 --restart unless-stopped math-grading:latest

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

# 测试接口
curl -X POST http://localhost:8000/stream_run \
  -H "Content-Type: application/json" \
  -d '{"student_homework": [{"student_id": 1, "homework_images": ["https://example.com/image.jpg"]}]}'
```

### 预期结果

- ✅ 容器正常运行
- ✅ 日志显示服务启动成功
- ✅ LLM 调用返回 200 OK
- ✅ 批改功能正常工作

### 关键修复点

1. ✅ API 端点包含 `/v1/` 前缀
2. ✅ COZE_WORKSPACE_ID 已配置
3. ✅ API Key 已硬编码
4. ✅ 健康检查已添加
5. ✅ 日志和缓存目录已创建