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

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

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

```bash
# 启动容器
docker run -d \
  --name system-prompt-optimizer \
  -p 8010:8010 \
  -p 11434:11434 \
  -v $(pwd)/outputs:/app/outputs \
  --restart unless-stopped \
  system-prompt-optimizer:allinone

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

**重要**：首次启动需要等待 30-60 秒，Ollama 服务需要初始化。

#### 步骤 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 端口

### 数据持久化

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

## 故障排查

### 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