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 模型

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

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

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

# 验证模型已下载
ollama list
```

#### 步骤 2: 导出 Ollama 模型

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

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

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

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

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

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

#### 步骤 4: 导出 Docker 镜像

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

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

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

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

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

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

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

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

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

```bash
# 加载镜像（需要几分钟）
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 模式（默认）:**

```bash
# 启动容器（推荐：仅暴露 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）:**

```bash
# 使用所有可用 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](GPU_DEPLOYMENT.md)

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

#### 步骤 8: 验证部署

```bash
# 等待服务启动（约 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: 构建应用镜像

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

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

#### 步骤 2: 传输并加载

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

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

#### 步骤 3: 启动服务

```bash
# 使用 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 服务状态**
```bash
# 检查 Docker 是否运行
sudo systemctl status docker

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

# 设置开机自启
sudo systemctl enable docker
```

**方法 2: 添加用户到 docker 组（推荐）**
```bash
# 将当前用户添加到 docker 组
sudo usermod -aG docker $USER

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

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

# 验证
docker info
```

**方法 3: 修复 Docker socket 权限**
```bash
# 检查 socket 权限
ls -l /var/run/docker.sock

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

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

**验证修复**:
```bash
# 应该能正常显示 Docker 信息
docker info

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

---

### 1. 无法连接 Ollama 服务

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

**解决方案**:
```bash
# 确保使用了 --add-host 参数
--add-host host.docker.internal:host-gateway

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

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

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

**解决方案**:
```bash
# 进入容器检查
docker exec -it system-prompt-optimizer bash

# 在容器内检查模型
ollama list

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

# 退出容器
exit
```

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

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

**问题**: Ollama 模型未安装

**解决方案**:
```bash
# 在宿主机上拉取模型
ollama pull qwen3:14b
ollama pull qwen3-embedding:4b

# 验证模型已安装
ollama list
```

### 4. 容器启动失败

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

**解决方案**:
```bash
# 检查端口占用
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`

## 更新部署

```bash
# 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
   ```bash
   -p 127.0.0.1:8010:8010
   ```

2. **防火墙**: 配置防火墙规则限制访问
   ```bash
   # 只允许特定 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. **日志管理**: 定期清理日志文件
   ```bash
   # 限制 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