309 lines
6.8 KiB
Markdown
309 lines
6.8 KiB
Markdown
# 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. ✅ 日志和缓存目录已创建
|