prompt-optimizer/mkdocs/docs/zh/deployment/docker-basic.md

Docker基础部署

本指南介绍如何使用Docker快速部署 Prompt Optimizer，包括单容器运行和基本环境配置。

🐳 Docker 单容器部署

快速开始

最简运行

只需一条命令即可启动 Prompt Optimizer：

# 最简运行（默认配置）
docker run -d -p 8081:80 --restart unless-stopped --name prompt-optimizer linshen/prompt-optimizer

# 访问应用
open http://localhost:8081

完整运行命令

带环境变量的完整运行配置：

docker run -d -p 8081:80 \
  -e VITE_OPENAI_API_KEY=your_openai_key \
  -e VITE_GEMINI_API_KEY=your_gemini_key \
  -e ACCESS_USERNAME=admin \
  -e ACCESS_PASSWORD=your_secure_password \
  --restart unless-stopped \
  --name prompt-optimizer \
  linshen/prompt-optimizer

镜像说明

官方镜像

Docker Hub：linshen/prompt-optimizer:latest

• ✅ 稳定可靠，自动构建
• ✅ 支持多架构：amd64, arm64
• ✅ 定期更新，跟随项目发布

国内镜像：registry.cn-guangzhou.aliyuncs.com/prompt-optimizer/prompt-optimizer:latest

• 🚀 国内用户访问更快
• 🔄 与Docker Hub镜像同步
• 💡 Docker Hub访问缓慢时推荐使用

版本标签

# 使用最新版本
docker pull linshen/prompt-optimizer:latest

# 使用指定版本
docker pull linshen/prompt-optimizer:v1.2.0

# 使用开发版本（不推荐生产使用）
docker pull linshen/prompt-optimizer:dev

端口和网络配置

端口映射选项

# 标准端口映射
-p 8081:80    # 将容器80端口映射到主机8081端口

# 自定义端口
-p 3000:80    # 映射到主机3000端口
-p 80:80      # 直接映射到主机80端口（需要管理员权限）

网络模式

# 默认bridge网络
docker run -d -p 8081:80 linshen/prompt-optimizer

# 使用host网络（Linux）
docker run -d --network host linshen/prompt-optimizer

# 创建自定义网络
docker network create prompt-net
docker run -d --network prompt-net -p 8081:80 linshen/prompt-optimizer

🔧 环境变量配置

API密钥配置

主流AI服务商

# OpenAI
-e VITE_OPENAI_API_KEY=sk-your-openai-api-key

# Google Gemini
-e VITE_GEMINI_API_KEY=your-gemini-api-key

# DeepSeek
-e VITE_DEEPSEEK_API_KEY=your-deepseek-key

# 智谱AI
-e VITE_ZHIPU_API_KEY=your-zhipu-key

# SiliconFlow
-e VITE_SILICONFLOW_API_KEY=your-siliconflow-key

自定义模型配置

支持配置无限数量的自定义模型：

# Ollama本地模型
-e VITE_CUSTOM_API_KEY_ollama=dummy_key \
-e VITE_CUSTOM_API_BASE_URL_ollama=http://host.docker.internal:11434/v1 \
-e VITE_CUSTOM_API_MODEL_ollama=qwen2.5:7b \
-e 'VITE_CUSTOM_API_PARAMS_ollama={"temperature":0.7}' \

# 其他OpenAI兼容API
-e VITE_CUSTOM_API_KEY_custom1=your-api-key \
-e VITE_CUSTOM_API_BASE_URL_custom1=https://api.example.com/v1 \
-e VITE_CUSTOM_API_MODEL_custom1=custom-model-name \
-e 'VITE_CUSTOM_API_PARAMS_custom1={"temperature":0.6,"top_p":0.95}' \

配置规则：

• 变量名格式：VITE_CUSTOM_API_[TYPE]_[NAME]
• [TYPE]：KEY、BASE_URL、MODEL，以及可选的 PARAMS
• [NAME]：自定义模型名称（只能包含字母、数字、下划线）

自定义模型额外请求参数

如果你的 OpenAI 兼容服务还需要额外请求字段，可以使用：

-e 'VITE_CUSTOM_API_PARAMS_nvidia={"chat_template_kwargs":{"enable_thinking":true},"temperature":0.6,"top_p":0.95,"max_tokens":16384}'

说明：

• VITE_CUSTOM_API_PARAMS_<suffix> 的值必须是 JSON 对象字符串
• 字段会直接注入最终请求体，适合 temperature、top_p、max_tokens 等标准参数
• 也支持供应商特有字段，例如 NVIDIA NIM 的 chat_template_kwargs
• model、messages、stream 属于保留字段，会被系统自动忽略
• 在 docker run 或 docker compose 中书写复杂 JSON 时，建议用单引号包裹整个值

访问控制配置

基础认证

# 启用密码保护
-e ACCESS_USERNAME=admin \
-e ACCESS_PASSWORD=your_secure_password \

配置后访问应用需要输入用户名和密码。

安全建议：

• 使用强密码（至少8位，包含字母、数字、特殊字符）
• 定期更换访问密码
• 不要在命令行历史中保留密码

高级安全配置

# JWT密钥（可选，用于增强安全性）
-e JWT_SECRET=your-random-jwt-secret

# 会话超时设置（秒，默认3600秒/1小时）
-e SESSION_TIMEOUT=3600

# IP白名单（逗号分隔，支持CIDR格式）
-e ALLOWED_IPS=192.168.1.0/24,10.0.0.0/8

MCP服务器配置

Docker部署自动包含MCP（Model Context Protocol）服务器功能：

# MCP服务器配置
-e MCP_DEFAULT_MODEL_PROVIDER=openai \
-e MCP_LOG_LEVEL=info \

# MCP端点访问地址
# http://localhost:8081/mcp

MCP功能：

• 提供标准化的AI模型访问接口
• 支持多种模型提供商
• 内置日志记录和监控

📦 Docker Compose 基础配置

简单配置

创建 docker-compose.yml 文件：

version: '3.8'

services:
  prompt-optimizer:
    image: linshen/prompt-optimizer:latest
    # 或使用国内镜像
    # image: registry.cn-guangzhou.aliyuncs.com/prompt-optimizer/prompt-optimizer:latest
    
    container_name: prompt-optimizer
    restart: unless-stopped
    
    ports:
      - "8081:80"
    
    environment:
      # API密钥配置
      - VITE_OPENAI_API_KEY=${OPENAI_API_KEY}
      - VITE_GEMINI_API_KEY=${GEMINI_API_KEY}
      
      # 访问控制
      - ACCESS_USERNAME=${ACCESS_USERNAME:-admin}
      - ACCESS_PASSWORD=${ACCESS_PASSWORD}
      
      # MCP配置
      - MCP_DEFAULT_MODEL_PROVIDER=${MCP_PROVIDER:-openai}
      - MCP_LOG_LEVEL=${MCP_LOG_LEVEL:-info}
    
    # 健康检查
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

环境变量文件

创建 .env 文件（重要：不要提交到版本控制）：

# API Keys
OPENAI_API_KEY=sk-your-openai-api-key
GEMINI_API_KEY=your-gemini-api-key
DEEPSEEK_API_KEY=your-deepseek-key

# Access Control
ACCESS_USERNAME=admin
ACCESS_PASSWORD=your_secure_password

# MCP Configuration
MCP_PROVIDER=openai
MCP_LOG_LEVEL=info

# Custom Models (example)
VITE_CUSTOM_API_KEY_ollama=dummy_key
VITE_CUSTOM_API_BASE_URL_ollama=http://host.docker.internal:11434/v1
VITE_CUSTOM_API_MODEL_ollama=qwen2.5:7b
VITE_CUSTOM_API_PARAMS_ollama={"temperature":0.7}

基本操作命令

# 启动服务
docker compose up -d

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f

# 重启服务
docker compose restart

# 停止服务
docker compose down

# 更新镜像并重启
docker compose pull && docker compose up -d

🎯 部署验证

功能测试

1. 基础访问测试

# 测试应用是否正常启动
curl -I http://localhost:8081

# 期望返回：HTTP/1.1 200 OK

2. 健康检查测试

# 测试健康检查端点
curl http://localhost:8081/health

# 期望返回：{"status":"ok","timestamp":"..."}

3. MCP服务测试

# 测试MCP端点
curl http://localhost:8081/mcp

# 期望返回MCP服务信息

常见部署问题

端口被占用

# 检查端口占用
netstat -tulpn | grep :8081

# 解决方案：更换端口或停止占用进程
docker run -d -p 3000:80 linshen/prompt-optimizer

镜像拉取失败

# 使用国内镜像源
docker pull registry.cn-guangzhou.aliyuncs.com/prompt-optimizer/prompt-optimizer:latest

# 或配置Docker镜像加速器

容器无法启动

# 查看详细错误日志
docker logs prompt-optimizer

# 检查环境变量配置
docker exec prompt-optimizer env | grep VITE_

💡 部署建议

生产环境建议

1. 资源配置

   • 最低要求：1GB RAM，1 CPU核心
   • 推荐配置：2GB RAM，2 CPU核心
   • 存储空间：至少500MB可用空间

2. 安全配置

   • 始终启用访问密码保护
   • 使用HTTPS（参见高级配置）
   • 定期更新镜像版本

3. 监控配置

   • 启用健康检查
   • 配置日志轮转
   • 监控资源使用情况

开发环境建议

1. 快速启动

   docker run -d -p 8081:80 --name prompt-optimizer-dev linshen/prompt-optimizer
   

2. 开发模式

   docker run -d -p 8081:80 \
     -e NODE_ENV=development \
     -e DEBUG=true \
     --name prompt-optimizer-dev \
     linshen/prompt-optimizer
   

---

相关链接：

• 高级配置 - Docker Compose高级配置和安全设置
• 故障排除 - 常见问题解决和性能优化