rust-user-api/docs/production-deployment.md

生产环境部署指南

概述

本文档提供Rust User API在生产环境中的完整部署指南，包括安全配置、性能优化、监控设置和运维最佳实践。

🏗️ 架构概览

推荐架构

Internet
    ↓
[Load Balancer/CDN]
    ↓
[Reverse Proxy (Nginx/Traefik)]
    ↓
[Rust User API Containers]
    ↓
[SQLite/PostgreSQL Database]

组件说明

• 负载均衡器: 分发流量，提供高可用性
• 反向代理: SSL终止，静态文件服务，安全过滤
• 应用容器: 多实例部署，水平扩展
• 数据库: 持久化存储，支持备份恢复

🔧 生产环境配置

1. 环境变量配置

创建生产环境配置文件：

# .env.production
# 服务器配置
SERVER_HOST=0.0.0.0
SERVER_PORT=3000
RUST_LOG=info

# 数据库配置
DATABASE_URL=sqlite:///app/data/production.db?mode=rwc
# 或使用PostgreSQL
# DATABASE_URL=postgresql://user:password@db:5432/rust_api

# 安全配置
JWT_SECRET=your-super-secure-jwt-secret-key-change-this
SECURITY_RATE_LIMIT_PER_MINUTE=100
SECURITY_BRUTE_FORCE_MAX_ATTEMPTS=5
SECURITY_BAN_DURATION=3600

# 日志配置
LOG_LEVEL=info
LOG_FORMAT=json
LOG_TO_CONSOLE=true
LOG_TO_FILE=true
LOG_FILE_PATH=/app/logs/app.log

# 监控配置
METRICS_ENABLED=true
HEALTH_CHECK_ENABLED=true

2. Docker Compose 生产配置

# docker-compose.prod.yml
version: '3.8'

services:
  rust-user-api:
    build:
      context: .
      dockerfile: Dockerfile
    image: rust-user-api:latest
    container_name: rust-user-api-prod
    restart: always
    ports:
      - "127.0.0.1:3000:3000"  # 仅本地访问
    environment:
      - RUST_LOG=info
      - DATABASE_URL=sqlite:///app/data/production.db?mode=rwc
      - JWT_SECRET=${JWT_SECRET}
      - LOG_FORMAT=json
      - LOG_TO_FILE=true
    volumes:
      - api_data:/app/data
      - api_logs:/app/logs
    networks:
      - api_network
    deploy:
      resources:
        limits:
          cpus: '2.0'
          memory: 1G
        reservations:
          cpus: '0.5'
          memory: 256M
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    logging:
      driver: "json-file"
      options:
        max-size: "100m"
        max-file: "5"

  nginx:
    image: nginx:alpine
    container_name: nginx-proxy
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/ssl:/etc/nginx/ssl:ro
      - api_logs:/var/log/api:ro
    depends_on:
      - rust-user-api
    networks:
      - api_network

volumes:
  api_data:
    driver: local
  api_logs:
    driver: local

networks:
  api_network:
    driver: bridge

3. Nginx 反向代理配置

# nginx/nginx.conf
events {
    worker_connections 1024;
}

http {
    upstream rust_api {
        server rust-user-api:3000;
        # 多实例负载均衡
        # server rust-user-api-2:3000;
        # server rust-user-api-3:3000;
    }

    # 限流配置
    limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
    limit_conn_zone $binary_remote_addr zone=conn_limit_per_ip:10m;

    server {
        listen 80;
        server_name your-domain.com;
        
        # 重定向到HTTPS
        return 301 https://$server_name$request_uri;
    }

    server {
        listen 443 ssl http2;
        server_name your-domain.com;

        # SSL配置
        ssl_certificate /etc/nginx/ssl/cert.pem;
        ssl_certificate_key /etc/nginx/ssl/key.pem;
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers ECDHE-RSA-AES256-GCM-SHA512:DHE-RSA-AES256-GCM-SHA512;
        ssl_prefer_server_ciphers off;

        # 安全头
        add_header X-Frame-Options DENY;
        add_header X-Content-Type-Options nosniff;
        add_header X-XSS-Protection "1; mode=block";
        add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload";

        # 限流
        limit_req zone=api burst=20 nodelay;
        limit_conn conn_limit_per_ip 10;

        # API代理
        location /api/ {
            proxy_pass http://rust_api;
            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;
            
            # 超时配置
            proxy_connect_timeout 30s;
            proxy_send_timeout 30s;
            proxy_read_timeout 30s;
        }

        # 健康检查
        location /health {
            proxy_pass http://rust_api;
            access_log off;
        }

        # 监控端点（限制访问）
        location /monitoring/ {
            allow 10.0.0.0/8;
            allow 172.16.0.0/12;
            allow 192.168.0.0/16;
            deny all;
            
            proxy_pass http://rust_api;
        }
    }
}

🔒 安全配置

1. SSL/TLS 证书

# 使用Let's Encrypt获取免费证书
certbot --nginx -d your-domain.com

# 或使用自签名证书（仅测试）
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout nginx/ssl/key.pem \
  -out nginx/ssl/cert.pem

2. 防火墙配置

# UFW配置示例
ufw default deny incoming
ufw default allow outgoing
ufw allow ssh
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

3. 系统安全

# 创建专用用户
useradd -r -s /bin/false -m -d /opt/rust-api apiuser

# 设置文件权限
chown -R apiuser:apiuser /opt/rust-api
chmod 750 /opt/rust-api

📊 监控和日志

1. Prometheus 配置

# monitoring/prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'rust-user-api'
    static_configs:
      - targets: ['rust-user-api:3000']
    metrics_path: '/monitoring/metrics/prometheus'
    scrape_interval: 30s

  - job_name: 'nginx'
    static_configs:
      - targets: ['nginx:9113']

2. Grafana 仪表板

{
  "dashboard": {
    "title": "Rust User API Dashboard",
    "panels": [
      {
        "title": "Request Rate",
        "type": "graph",
        "targets": [
          {
            "expr": "rate(http_requests_total[5m])"
          }
        ]
      },
      {
        "title": "Response Time",
        "type": "graph",
        "targets": [
          {
            "expr": "histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))"
          }
        ]
      }
    ]
  }
}

3. 日志聚合

# docker-compose.logging.yml
version: '3.8'

services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.15.0
    environment:
      - discovery.type=single-node
    volumes:
      - es_data:/usr/share/elasticsearch/data

  logstash:
    image: docker.elastic.co/logstash/logstash:7.15.0
    volumes:
      - ./logstash/pipeline:/usr/share/logstash/pipeline
      - api_logs:/logs

  kibana:
    image: docker.elastic.co/kibana/kibana:7.15.0
    ports:
      - "5601:5601"
    environment:
      - ELASTICSEARCH_HOSTS=http://elasticsearch:9200

volumes:
  es_data:

🚀 部署流程

1. 自动化部署脚本

#!/bin/bash
# deploy.sh

set -e

echo "🚀 开始部署 Rust User API..."

# 1. 拉取最新代码
git pull origin main

# 2. 构建镜像
docker-compose -f docker-compose.prod.yml build --no-cache

# 3. 备份数据库
docker-compose -f docker-compose.prod.yml exec rust-user-api \
  cp /app/data/production.db /app/data/backup-$(date +%Y%m%d-%H%M%S).db

# 4. 停止旧服务
docker-compose -f docker-compose.prod.yml down

# 5. 启动新服务
docker-compose -f docker-compose.prod.yml up -d

# 6. 健康检查
sleep 30
if curl -f http://localhost/health; then
    echo "✅ 部署成功！"
else
    echo "❌ 部署失败，回滚..."
    docker-compose -f docker-compose.prod.yml down
    # 这里可以添加回滚逻辑
    exit 1
fi

echo "🎉 部署完成！"

2. CI/CD 流水线

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Setup Docker
        uses: docker/setup-buildx-action@v1
      
      - name: Build and test
        run: |
          docker build -t rust-user-api:test .
          docker run --rm rust-user-api:test cargo test
      
      - name: Deploy to production
        run: |
          ssh ${{ secrets.PROD_SERVER }} 'cd /opt/rust-api && ./deploy.sh'

📈 性能优化

1. 数据库优化

-- SQLite优化
PRAGMA journal_mode = WAL;
PRAGMA synchronous = NORMAL;
PRAGMA cache_size = 1000000;
PRAGMA temp_store = memory;

2. 应用优化

# Cargo.toml 生产优化
[profile.release]
opt-level = 3
lto = true
codegen-units = 1
panic = 'abort'

3. 容器优化

# 多阶段构建优化
FROM rust:1.88-slim as builder
# ... 构建阶段

FROM debian:bookworm-slim
# 安装运行时依赖
RUN apt-get update && apt-get install -y \
    ca-certificates \
    sqlite3 \
    libssl3 \
    curl \
    && rm -rf /var/lib/apt/lists/* \
    && apt-get clean

🔧 运维管理

1. 备份策略

#!/bin/bash
# backup.sh

BACKUP_DIR="/opt/backups"
DATE=$(date +%Y%m%d-%H%M%S)

# 数据库备份
docker-compose exec rust-user-api \
  sqlite3 /app/data/production.db ".backup /app/data/backup-$DATE.db"

# 压缩备份
tar -czf "$BACKUP_DIR/api-backup-$DATE.tar.gz" \
  -C /opt/rust-api/data backup-$DATE.db

# 清理旧备份（保留30天）
find $BACKUP_DIR -name "api-backup-*.tar.gz" -mtime +30 -delete

2. 监控告警

# alertmanager.yml
groups:
  - name: rust-api-alerts
    rules:
      - alert: HighErrorRate
        expr: rate(http_requests_total{status=~"5.."}[5m]) > 0.1
        for: 5m
        annotations:
          summary: "High error rate detected"
      
      - alert: HighResponseTime
        expr: histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 1
        for: 5m
        annotations:
          summary: "High response time detected"

3. 日常维护

# 系统维护脚本
#!/bin/bash

# 清理Docker资源
docker system prune -f

# 更新系统包
apt update && apt upgrade -y

# 检查磁盘空间
df -h

# 检查服务状态
docker-compose ps
systemctl status docker

🔍 故障排除

1. 常见问题

问题	症状	解决方案
内存不足	容器重启	增加内存限制，优化代码
数据库锁定	请求超时	检查并发连接，优化查询
SSL证书过期	HTTPS错误	更新证书，配置自动续期
磁盘空间不足	写入失败	清理日志，扩展存储

2. 调试工具

# 查看容器日志
docker-compose logs -f rust-user-api

# 进入容器调试
docker-compose exec rust-user-api /bin/bash

# 检查网络连接
docker network ls
docker network inspect rust-server_api_network

# 监控资源使用
docker stats
htop
iotop

📋 检查清单

部署前检查

• 环境变量配置正确
• SSL证书有效
• 防火墙规则配置
• 数据库备份完成
• 监控系统正常
• 负载测试通过

部署后验证

• 健康检查通过
• API端点响应正常
• 日志记录正常
• 监控指标正常
• 安全扫描通过
• 性能测试达标

🎯 最佳实践

1. 安全最佳实践

• 使用强密码和密钥
• 定期更新依赖包
• 启用审计日志
• 实施最小权限原则
• 定期安全扫描

2. 性能最佳实践

• 启用HTTP/2
• 使用CDN加速
• 实施缓存策略
• 优化数据库查询
• 监控关键指标

3. 运维最佳实践

• 自动化部署流程
• 实施蓝绿部署
• 定期备份数据
• 监控系统健康
• 建立应急响应计划

---

📞 支持和维护

联系信息

• 技术支持: tech-support@company.com
• 紧急联系: +86-xxx-xxxx-xxxx
• 文档更新: docs@company.com

更新日志

• v1.0.0: 初始生产环境配置
• v1.1.0: 添加监控和告警
• v1.2.0: 优化性能和安全配置

---

注意: 本文档应根据实际生产环境需求进行调整和定制。定期审查和更新配置以确保最佳的安全性和性能。