本指南涵盖 Potato 的生产环境部署，包括服务器设置、Docker 部署、云平台和安全配置。

部署选项

方式	最适合	复杂度
本地	开发、测试	低
Docker	可复现的部署	中
云虚拟机	完全控制、自定义设置	中
Docker Compose	多容器设置	中
Kubernetes	大规模部署	高

基本服务器部署

前提条件

bash

# Ubuntu/Debian server
sudo apt update
sudo apt install python3.9 python3-pip nginx certbot python3-certbot-nginx
 
# Create directory structure
mkdir -p /opt/potato/projects
cd /opt/potato

安装

bash

# Create virtual environment
python3 -m venv venv
source venv/bin/activate
 
# Install Potato
pip install potato-annotation
 
# Verify installation
potato --version

使用 Gunicorn 运行

bash

# Install production server
pip install gunicorn
 
# Run with gunicorn
gunicorn -w 4 -b 127.0.0.1:8000 \
  --chdir /opt/potato/projects/my_project \
  "potato.server:create_app(config_path='config.yaml')"

Systemd 服务

创建 /etc/systemd/system/potato.service：

ini

[Unit]
Description=Potato Annotation Server
After=network.target
 
[Service]
Type=simple
User=potato
Group=potato
WorkingDirectory=/opt/potato/projects/my_project
Environment="PATH=/opt/potato/venv/bin"
ExecStart=/opt/potato/venv/bin/gunicorn -w 4 -b 127.0.0.1:8000 \
  "potato.server:create_app(config_path='config.yaml')"
Restart=always
RestartSec=10
 
[Install]
WantedBy=multi-user.target

启用并启动：

bash

sudo systemctl enable potato
sudo systemctl start potato
sudo systemctl status potato

Nginx 配置

基本反向代理

创建 /etc/nginx/sites-available/potato：

nginx

server {
    listen 80;
    server_name annotation.example.com;
 
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
 
        # WebSocket support (if needed)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
 
    # Static files
    location /static/ {
        alias /opt/potato/projects/my_project/static/;
        expires 30d;
        add_header Cache-Control "public, no-transform";
    }
 
    # Upload size limit
    client_max_body_size 100M;
}

启用站点：

bash

sudo ln -s /etc/nginx/sites-available/potato /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

使用 Let's Encrypt 配置 SSL

bash

# Get SSL certificate
sudo certbot --nginx -d annotation.example.com
 
# Auto-renewal
sudo systemctl enable certbot.timer

Docker 部署

Dockerfile

dockerfile

FROM python:3.9-slim
 
WORKDIR /app
 
# Install dependencies
RUN pip install potato-annotation gunicorn
 
# Copy project files
COPY config.yaml .
COPY data/ ./data/
 
# Create directories
RUN mkdir -p annotations logs
 
# Expose port
EXPOSE 8000
 
# Run server
CMD ["gunicorn", "-w", "4", "-b", "0.0.0.0:8000", \
     "potato.server:create_app(config_path='config.yaml')"]

构建和运行

bash

# Build image
docker build -t potato-annotation .
 
# Run container
docker run -d \
  --name potato \
  -p 8000:8000 \
  -v $(pwd)/annotations:/app/annotations \
  -v $(pwd)/logs:/app/logs \
  potato-annotation

Docker Compose

yaml

# docker-compose.yml
version: '3.8'
 
services:
  potato:
    build: .
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data:ro
      - ./annotations:/app/annotations
      - ./logs:/app/logs
    environment:
      - POTATO_ENV=production
    restart: unless-stopped
 
  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./ssl:/etc/nginx/ssl:ro
    depends_on:
      - potato
    restart: unless-stopped

云平台部署

AWS EC2

bash

# Launch EC2 instance (Ubuntu 22.04)
# Configure security group: ports 22, 80, 443
 
# SSH to instance
ssh -i your-key.pem ubuntu@your-instance-ip
 
# Follow basic server deployment steps above
 
# For persistent storage, attach EBS volume
sudo mount /dev/xvdf /opt/potato/data

Google Cloud Platform

bash

# Create VM instance
gcloud compute instances create potato-server \
  --zone=us-central1-a \
  --machine-type=e2-medium \
  --image-family=ubuntu-2204-lts \
  --image-project=ubuntu-os-cloud
 
# Configure firewall
gcloud compute firewall-rules create allow-http \
  --allow tcp:80,tcp:443

DigitalOcean

bash

# Create droplet via CLI
doctl compute droplet create potato-server \
  --size s-2vcpu-4gb \
  --image ubuntu-22-04-x64 \
  --region nyc1

生产环境配置

生产配置

yaml

# config.yaml
annotation_task_name: "Production Annotation Task"
 
# Note: Server settings (host, port, workers) are CLI flags:
#   potato -p 8000 --host 0.0.0.0 config.yaml
# Or use gunicorn for production with multiple workers
 
# Logging
logging:
  level: INFO
  file: logs/potato.log
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
  rotation:
    max_size: 10MB
    backup_count: 5
 
# Data
data_files:
  - items.jsonl
 
item_properties:
  id_key: id
  text_key: text
 
# Output
output_annotation_dir: annotations/
export_annotation_format: jsonl

环境变量

bash

# /opt/potato/.env
POTATO_SECRET_KEY=your-secure-random-key-here
POTATO_ENV=production
OPENAI_API_KEY=sk-...  # If using AI features

在 systemd 中加载：

ini

[Service]
EnvironmentFile=/opt/potato/.env

安全最佳实践

认证

yaml

user_config:
  auth_type: password
 
  # Strong password requirements
  password_policy:
    min_length: 12
    require_uppercase: true
    require_number: true
 
  # Session security
  session:
    secure_cookie: true
    http_only: true
    same_site: strict

HTTPS 配置

nginx

server {
    listen 443 ssl http2;
    server_name annotation.example.com;
 
    ssl_certificate /etc/letsencrypt/live/annotation.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/annotation.example.com/privkey.pem;
 
    # Modern SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
    ssl_prefer_server_ciphers off;
 
    # Security headers
    add_header Strict-Transport-Security "max-age=63072000" always;
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;
    add_header X-XSS-Protection "1; mode=block";
 
    # ... rest of config
}

防火墙

bash

# UFW configuration
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 'Nginx Full'
sudo ufw enable

监控

健康检查端点

bash

# Check server health
curl http://localhost:8000/health
 
# Expected response
{"status": "healthy", "version": "2.0.0"}

日志监控

bash

# View logs
sudo journalctl -u potato -f
 
# Or check log file
tail -f /opt/potato/logs/potato.log

Prometheus 指标（可选）

yaml

# config.yaml
monitoring:
  prometheus:
    enabled: true
    port: 9090

备份策略

自动备份

bash

# backup.sh
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR=/opt/potato/backups
 
# Backup annotations
tar -czf $BACKUP_DIR/annotations_$DATE.tar.gz /opt/potato/projects/*/annotations/
 
# Backup configs
tar -czf $BACKUP_DIR/configs_$DATE.tar.gz /opt/potato/projects/*/config.yaml
 
# Remove old backups (keep 7 days)
find $BACKUP_DIR -mtime +7 -delete
 
# Optional: sync to cloud storage
# aws s3 sync $BACKUP_DIR s3://your-bucket/potato-backups/

添加到 crontab：

bash

# Run daily at 2am
0 2 * * * /opt/potato/backup.sh

扩展

多工作进程

bash

# Increase gunicorn workers based on CPU cores
gunicorn -w $((2 * $(nproc) + 1)) -b 0.0.0.0:8000 ...

负载均衡

nginx

upstream potato_servers {
    server 127.0.0.1:8001;
    server 127.0.0.1:8002;
    server 127.0.0.1:8003;
}
 
server {
    location / {
        proxy_pass http://potato_servers;
    }
}

故障排除

常见问题

端口已被占用：

bash

sudo lsof -i :8000
sudo kill -9 <PID>

权限被拒绝：

bash

sudo chown -R potato:potato /opt/potato

内存不足：

bash

# Add swap space
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

如需更多帮助，请参阅完整文档或 GitHub 讨论区。