DOCKER.md

OCR Agent Docker 部署

快速开始

前置要求

• Docker 20.10+
• Docker Compose 2.0+
• 4GB+ 内存
• 2GB+ 磁盘空间

使用 Docker Compose 启动（推荐）

# 1. 克隆项目
git clone https://github.com/your-repo/ocr-agent.git
cd ocr-agent

# 2. 构建镜像
docker-compose build

# 3. 启动服务
docker-compose up -d

# 4. 查看日志
docker-compose logs -f ocr-agent

# 5. 访问 API
# 健康检查: http://localhost:8000/api/v1/health
# API 文档: http://localhost:8000/docs

使用 Docker 命令启动

# 构建镜像
docker build -t ocr-agent:latest .

# 运行容器
docker run -d \
  --name ocr-agent \
  -p 8000:8000 \
  -v $(pwd)/uploads:/app/uploads \
  -v $(pwd)/outputs:/app/outputs \
  ocr-agent:latest

# 查看日志
docker logs -f ocr-agent

文件说明

文件	说明
Dockerfile	多阶段构建配置，优化镜像大小
docker-compose.yml	完整的服务编排配置
.dockerignore	Docker 构建时忽略的文件
nginx.conf	Nginx 反向代理配置
docs/DOCKER_DEPLOYMENT.md	详细部署指南

镜像特性

✅ 多阶段构建 - 减小镜像大小
✅ 健康检查 - 自动监控服务状态
✅ 卷挂载 - 持久化上传和输出文件
✅ 环境变量 - 灵活配置
✅ Nginx 反向代理 - 生产级部署

常用命令

# 查看容器状态
docker-compose ps

# 查看实时日志
docker-compose logs -f

# 进入容器
docker-compose exec ocr-agent bash

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

# 查看容器资源使用
docker stats ocr-agent

API 使用示例

上传文件处理

curl -X POST http://localhost:8000/api/v1/jobs \
  -F "file=@image.png" \
  -F "format=docx" \
  -F "format=json"

查询处理状态

curl http://localhost:8000/api/v1/jobs/{job_id}

下载结果

curl http://localhost:8000/api/v1/jobs/{job_id}/results/output.docx \
  -o output.docx

性能配置

内存限制

services:
  ocr-agent:
    mem_limit: 4g
    memswap_limit: 4g

CPU 限制

services:
  ocr-agent:
    cpus: '2'
    cpu_shares: 1024

生产部署

使用 Nginx 反向代理

docker-compose up -d
# Nginx 会自动启动并代理请求到 OCR Agent

启用 HTTPS

1. 生成 SSL 证书
2. 更新 nginx.conf 中的 HTTPS 配置
3. 挂载证书到容器

详见 docs/DOCKER_DEPLOYMENT.md

故障排查

容器无法启动

docker-compose logs ocr-agent
docker-compose build --no-cache

内存不足

docker update -m 8g ocr-agent
docker-compose restart

文件权限问题

chmod 777 uploads outputs

更多信息

• 详细部署指南: docs/DOCKER_DEPLOYMENT.md
• 使用文档: docs/USER_GUIDE.md
• 项目进度: PROGRESS.md

---

最后更新: 2026-05-21