opro_demo/DEPLOYMENT.md

Docker 部署指南

本文档说明如何在无外网访问的服务器上部署系统提示词优化工具。

部署方案

本项目提供两种部署方案：

方案 A: All-in-One 镜像（推荐，适用于无外网服务器）

优点：

• 包含所有依赖：应用代码 + Ollama + LLM 模型
• 一个镜像文件，部署简单
• 无需在目标服务器上安装任何额外软件（除了 Docker）

缺点：

• 镜像文件很大（10-20GB）
• 传输时间较长

方案 B: 分离部署（适用于已有 Ollama 的服务器）

优点：

• 镜像文件较小（~500MB）
• 可以复用现有的 Ollama 服务

缺点：

• 需要在目标服务器上单独安装和配置 Ollama
• 需要手动下载模型

---

方案 A: All-in-One 部署（推荐）

前置要求

在开发机器上（有外网访问）

1. Docker 已安装
2. Ollama 已安装并运行
3. 磁盘空间：至少 30GB 可用空间
4. 已下载所需的 Ollama 模型：
   • qwen3:14b (主模型，~8GB)
   • qwen3-embedding:4b (嵌入模型，~2GB)

在目标服务器上（无外网访问）

1. Docker 已安装
2. 磁盘空间：至少 25GB 可用空间

部署步骤

步骤 1: 下载所需的 Ollama 模型

在开发机器上，确保已下载所需模型：

# 下载主模型（约 8GB）
ollama pull qwen3:14b

# 下载嵌入模型（约 2GB）
ollama pull qwen3-embedding:4b

# 验证模型已下载
ollama list

步骤 2: 导出 Ollama 模型

# 运行导出脚本
./export-ollama-models.sh

这将创建 ollama-models/ 目录，包含所有模型文件。

步骤 3: 构建 All-in-One Docker 镜像

# 运行构建脚本（推荐）
./build-allinone.sh

# 或手动构建
docker build -f Dockerfile.allinone -t system-prompt-optimizer:allinone .

注意：构建过程可能需要 10-30 分钟，取决于机器性能。

步骤 4: 导出 Docker 镜像

如果使用 build-allinone.sh，镜像已自动导出。否则手动导出：

# 导出镜像（约 10-20GB）
docker save -o system-prompt-optimizer-allinone.tar system-prompt-optimizer:allinone

# 验证文件大小
ls -lh system-prompt-optimizer-allinone.tar

步骤 5: 传输到目标服务器

使用 scp、U盘或其他方式传输镜像文件：

# 使用 scp（如果网络可达）
scp system-prompt-optimizer-allinone.tar user@server:/path/

# 或使用 rsync（支持断点续传）
rsync -avP --progress system-prompt-optimizer-allinone.tar user@server:/path/

# 或使用 U盘/移动硬盘物理传输

步骤 6: 在目标服务器上加载镜像

# 加载镜像（需要几分钟）
docker load -i system-prompt-optimizer-allinone.tar

# 如果遇到权限错误，使用 sudo
# sudo docker load -i system-prompt-optimizer-allinone.tar

# 验证镜像已加载
docker images | grep system-prompt-optimizer

步骤 7: 启动服务

CPU 模式（默认）:

# 启动容器（推荐：仅暴露 Web 端口）
docker run -d \
  --name system-prompt-optimizer \
  -p 8010:8010 \
  --restart unless-stopped \
  system-prompt-optimizer:allinone

# 查看启动日志
docker logs -f system-prompt-optimizer

GPU 模式（推荐，如果有 NVIDIA GPU）:

# 使用所有可用 GPU（推荐）
docker run -d \
  --name system-prompt-optimizer \
  --gpus all \
  -p 8010:8010 \
  --restart unless-stopped \
  system-prompt-optimizer:allinone

# 或指定特定 GPU
docker run -d \
  --name system-prompt-optimizer \
  --gpus '"device=0"' \
  -p 8010:8010 \
  --restart unless-stopped \
  system-prompt-optimizer:allinone

# 查看启动日志
docker logs -f system-prompt-optimizer

GPU 部署前提条件:

• 已安装 NVIDIA 驱动 (nvidia-smi 可用)
• 已安装 NVIDIA Container Toolkit
• GPU 显存 ≥ 10GB (14b 模型) 或 ≥ 6GB (8b 模型)

详细 GPU 部署指南: 参见 GPU_DEPLOYMENT.md

重要：

• 首次启动需要等待 30-60 秒（CPU）或 10-20 秒（GPU），Ollama 服务需要初始化
• GPU 模式下推理速度提升 5-10 倍
• 端口 11434 (Ollama) 是可选的，仅在需要外部访问 Ollama 时暴露
• 不暴露 11434 更安全，因为 Ollama API 没有身份验证

步骤 8: 验证部署

# 等待服务启动（约 30-60 秒）
sleep 60

# 健康检查
curl http://localhost:8010/health

# 应该返回：
# {"status":"ok","version":"0.1.0"}

# 检查 Ollama 服务
curl http://localhost:11434/api/tags

# 检查可用模型
curl http://localhost:8010/models

# 访问 Web 界面
# 浏览器打开: http://<服务器IP>:8010/ui/opro.html

---

方案 B: 分离部署

前置要求

在目标服务器上

1. Docker 已安装
2. Ollama 服务已安装并运行
3. 已拉取所需的 Ollama 模型：
   • qwen3:14b (主模型)
   • qwen3-embedding:4b (嵌入模型)

部署步骤

步骤 1: 构建应用镜像

# 在开发机器上构建
docker build -t system-prompt-optimizer:latest .

# 导出镜像
docker save -o system-prompt-optimizer.tar system-prompt-optimizer:latest

步骤 2: 传输并加载

# 传输到目标服务器
scp system-prompt-optimizer.tar user@server:/path/

# 在目标服务器上加载
docker load -i system-prompt-optimizer.tar

步骤 3: 启动服务

# 使用 Docker Compose
docker-compose up -d

# 或使用 Docker 命令
docker run -d \
  --name system-prompt-optimizer \
  -p 8010:8010 \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  -v $(pwd)/outputs:/app/outputs \
  --add-host host.docker.internal:host-gateway \
  --restart unless-stopped \
  system-prompt-optimizer:latest

配置说明

环境变量

在 docker-compose.yml 或 docker run 命令中可以配置以下环境变量：

• OLLAMA_HOST: Ollama 服务地址（默认: http://host.docker.internal:11434）
• PYTHONUNBUFFERED: Python 输出缓冲（默认: 1）

端口映射

• 8010: Web 界面和 API 端口（必需）
• 11434: Ollama API 端口（可选，仅用于调试或外部访问 Ollama）

数据持久化

• ./outputs: 用户反馈日志存储目录（映射到容器内 /app/outputs）

故障排查

0. Docker 守护进程连接错误

问题: 运行 docker 命令时提示 "Cannot connect to the Docker daemon"

症状:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

解决方案:

方法 1: 检查 Docker 服务状态

# 检查 Docker 是否运行
sudo systemctl status docker

# 如果未运行，启动它
sudo systemctl start docker

# 设置开机自启
sudo systemctl enable docker

方法 2: 添加用户到 docker 组（推荐）

# 将当前用户添加到 docker 组
sudo usermod -aG docker $USER

# 应用组变更（需要重新登录或使用 newgrp）
newgrp docker

# 或者直接注销并重新登录

# 验证
docker info

方法 3: 修复 Docker socket 权限

# 检查 socket 权限
ls -l /var/run/docker.sock

# 修复权限
sudo chown root:docker /var/run/docker.sock
sudo chmod 660 /var/run/docker.sock

方法 4: 临时使用 sudo

# 如果上述方法不可行，使用 sudo 运行 Docker 命令
sudo docker load -i system-prompt-optimizer-allinone.tar
sudo docker run -d --name system-prompt-optimizer ...

验证修复:

# 应该能正常显示 Docker 信息
docker info

# 应该能看到当前用户在 docker 组中
groups | grep docker

---

1. 无法连接 Ollama 服务

问题: 容器内无法访问宿主机的 Ollama 服务

解决方案:

# 确保使用了 --add-host 参数
--add-host host.docker.internal:host-gateway

# 或者直接使用宿主机 IP
-e OLLAMA_HOST=http://192.168.1.100:11434

2. 模型不可用（All-in-One 部署）

问题: 容器内模型未正确加载

解决方案:

# 进入容器检查
docker exec -it system-prompt-optimizer bash

# 在容器内检查模型
ollama list

# 如果模型不存在，检查模型目录
ls -la /root/.ollama/models/

# 退出容器
exit

如果模型确实丢失，可能需要重新构建镜像。

3. 模型不可用（分离部署）

问题: Ollama 模型未安装

解决方案:

# 在宿主机上拉取模型
ollama pull qwen3:14b
ollama pull qwen3-embedding:4b

# 验证模型已安装
ollama list

4. 容器启动失败

问题: 端口被占用或权限问题

解决方案:

# 检查端口占用
netstat -tulpn | grep 8010
netstat -tulpn | grep 11434

# 更换端口（All-in-One 需要两个端口）
docker run -p 8011:8010 -p 11435:11434 ...

# 查看容器日志
docker logs system-prompt-optimizer

5. 性能问题

问题: 生成速度慢

解决方案:

• 确保 Ollama 使用 GPU 加速
• 使用更小的模型（如 qwen3:4b）
• 调整 config.py 中的 GENERATION_POOL_SIZE

更新部署

# 1. 在开发机器上重新构建镜像
docker build -t system-prompt-optimizer:latest .

# 2. 导出新镜像
docker save -o system-prompt-optimizer-new.tar system-prompt-optimizer:latest

# 3. 传输到服务器并加载
docker load -i system-prompt-optimizer-new.tar

# 4. 重启服务
docker-compose down
docker-compose up -d

# 或使用 docker 命令
docker stop system-prompt-optimizer
docker rm system-prompt-optimizer
docker run -d ...  # 使用相同的启动命令

安全建议

1. 网络隔离: 如果不需要外部访问，只绑定到 localhost

   -p 127.0.0.1:8010:8010
   

2. 防火墙: 配置防火墙规则限制访问

   # 只允许特定 IP 访问
   iptables -A INPUT -p tcp --dport 8010 -s 192.168.1.0/24 -j ACCEPT
   iptables -A INPUT -p tcp --dport 8010 -j DROP
   

3. 日志管理: 定期清理日志文件

   # 限制 Docker 日志大小
   docker run --log-opt max-size=10m --log-opt max-file=3 ...
   

联系支持

如有问题，请查看：

• 应用日志: docker logs system-prompt-optimizer
• Ollama 日志: journalctl -u ollama -f
• API 文档: http://localhost:8010/docs