邮轮穿舱件管理系统后台 - 生产环境部署指南

概述

本文档详细说明邮轮穿舱件管理系统后台的生产环境部署流程和最佳实践。该系统基于FastAPI框架构建，采用Tortoise ORM进行数据库操作，支持微信小程序集成和图像处理功能。

系统架构分析

核心组件架构

flowchart TD
    subgraph 前端层
        A[Web客户端]
        B[微信小程序]
    end
    
    subgraph API网关层
        C[Nginx/负载均衡器]
    end
    
    subgraph 应用层
        D[FastAPI应用]
        E[认证中间件]
        F[异常处理中间件]
    end
    
    subgraph 业务逻辑层
        G[用户服务]
        H[工单服务]
        I[图像服务]
        J[角色服务]
        K[工件服务]
    end
    
    subgraph 数据访问层
        L[Tortoise ORM]
        M[数据库连接池]
    end
    
    subgraph 数据存储层
        N[PostgreSQL数据库]
        O[文件存储系统]
    end
    
    A --> C
    B --> C
    C --> D
    D --> E
    E --> F
    F --> G
    F --> H
    F --> I
    F --> J
    F --> K
    G --> L
    H --> L
    I --> L
    J --> L
    K --> L
    L --> M
    M --> N
    I --> O

模块依赖关系

flowchart TD
    subgraph 核心模块
        A[app/main.py]
        B[app/core/settings.py]
        C[app/tortoise_config.py]
    end
    
    subgraph 路由模块
        D[app/routers/]
        E[用户路由]
        F[工单路由]
        G[图像路由]
        H[微信路由]
    end
    
    subgraph 服务模块
        I[app/service/]
        J[用户服务]
        K[工单服务]
        L[图像服务]
    end
    
    subgraph 数据模型
        M[app/models/]
        N[用户模型]
        O[工单模型]
        P[图像模型]
    end
    
    A --> B
    A --> C
    A --> D
    D --> E
    D --> F
    D --> G
    D --> H
    E --> J
    F --> K
    G --> L
    J --> N
    K --> O
    L --> P
    B --> C

生产环境部署流程

1. 环境准备

系统要求

• 操作系统: Ubuntu 20.04+ / CentOS 8+
• Python版本: 3.11+
• 数据库: PostgreSQL 12+
• 内存: 最低4GB，推荐8GB+
• 存储: 根据图像存储需求配置

依赖安装

# 安装系统依赖
sudo apt-get update
sudo apt-get install -y python3-pip python3-venv postgresql postgresql-contrib nginx

# 创建Python虚拟环境
python3 -m venv /opt/c0726-backend/venv
source /opt/c0726-backend/venv/bin/activate

# 安装Python依赖
pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

2. 数据库配置

数据库初始化

# 创建数据库和用户
sudo -u postgres psql -c "CREATE DATABASE c0726_production;"
sudo -u postgres psql -c "CREATE USER c0726_user WITH PASSWORD 'secure_password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE c0726_production TO c0726_user;"

# 执行数据库迁移
aerich init-db

数据库配置文件

创建生产环境数据库配置文件 .config/production.database.json:

{
    "connections": {
        "default": {
            "engine": "tortoise.backends.asyncpg",
            "credentials": {
                "host": "localhost",
                "port": "5432",
                "user": "c0726_user",
                "password": "secure_password",
                "database": "c0726_production",
                "minsize": 1,
                "maxsize": 5
            }
        }
    },
    "apps": {
        "models": {
            "models": ["app.models", "aerich.models"],
            "default_connection": "default"
        }
    }
}

3. 应用配置

环境变量配置

创建 .env 文件:

ENV=production
JWT_SECRET_KEY=your_secure_jwt_secret_key
WECHAT_APPID=your_wechat_appid
WECHAT_SECRET=your_wechat_secret

应用配置文件

创建 .config/production.application.json:

{
    "app_debug": "false",
    "app_name": "邮轮穿舱件管理系统",
    "app_version": "1.0.0",
    "app_desc": "邮轮穿舱件管理系统生产环境API"
}

微信配置

创建 .config/production.wechat.json:

{
    "wechat_appid": "your_production_appid",
    "wechat_secret": "your_production_secret"
}

4. Docker部署（推荐）

Dockerfile优化

基于现有的Dockerfile进行生产环境优化:

FROM python:3.11-slim

# 安装系统依赖
RUN apt-get update && apt-get install -y \
    postgresql-client \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# 复制依赖文件
COPY requirements.txt .

# 安装Python依赖
RUN pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

# 复制应用代码
COPY . /app

# 创建非root用户
RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
USER appuser

# 健康检查
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:8000/info || exit 1

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "4"]

Docker Compose配置

创建 docker-compose.prod.yml:

version: '3.8'

services:
  app:
    build: .
    ports:
      - "8000:8000"
    environment:
      - ENV=production
    depends_on:
      - postgres
    volumes:
      - ./logs:/app/logs
      - ./uploads:/app/uploads
    restart: unless-stopped

  postgres:
    image: postgres:13
    environment:
      POSTGRES_DB: c0726_production
      POSTGRES_USER: c0726_user
      POSTGRES_PASSWORD: secure_password
    volumes:
      - postgres_data:/var/lib/postgresql/data
    restart: unless-stopped

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/nginx/ssl
    depends_on:
      - app
    restart: unless-stopped

volumes:
  postgres_data:

5. Nginx配置

创建 nginx.conf:

worker_processes auto;
error_log /var/log/nginx/error.log warn;
pid /var/run/nginx.pid;

events {
    worker_connections 1024;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                    '$status $body_bytes_sent "$http_referer" '
                    '"$http_user_agent" "$http_x_forwarded_for"';

    access_log /var/log/nginx/access.log main;

    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;

    # Gzip压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml;

    upstream backend {
        server app:8000;
    }

    server {
        listen 80;
        server_name api.c0726.qualitysafeguard.com;
        return 301 https://$server_name$request_uri;
    }

    server {
        listen 443 ssl http2;
        server_name api.c0726.qualitysafeguard.com;

        ssl_certificate /etc/nginx/ssl/cert.pem;
        ssl_certificate_key /etc/nginx/ssl/private.key;
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384;

        # 安全头
        add_header X-Frame-Options DENY;
        add_header X-Content-Type-Options nosniff;
        add_header X-XSS-Protection "1; mode=block";

        location / {
            proxy_pass http://backend;
            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 /static/ {
            alias /app/static/;
            expires 1y;
            add_header Cache-Control "public, immutable";
        }

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

部署最佳实践

1. 安全配置

JWT安全

# 生产环境JWT配置
JWT_SECRET_KEY = os.getenv('JWT_SECRET_KEY', '')  # 必须从环境变量读取
JWT_ALGORITHM = "HS256"
JWT_ACCESS_EXPIRE_MINUTES = 30  # 缩短token有效期

CORS配置优化

# 生产环境CORS配置
app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://your-domain.com"],  # 限制具体域名
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["Content-Type", "Authorization"],
)

2. 性能优化

数据库连接池

# 优化数据库连接池配置
"connections": {
    "default": {
        "engine": "tortoise.backends.asyncpg",
        "credentials": {
            "minsize": 3,      # 最小连接数
            "maxsize": 20,     # 最大连接数
            "max_inactive_connection_lifetime": 300.0
        }
    }
}

Uvicorn配置优化

# 生产环境启动命令
uvicorn app.main:app \
    --host 0.0.0.0 \
    --port 8000 \
    --workers 4 \
    --loop uvloop \
    --http httptools \
    --access-logfile /var/log/uvicorn-access.log

3. 监控和日志

结构化日志配置

import structlog

# 配置结构化日志
structlog.configure(
    processors=[
        structlog.stdlib.filter_by_level,
        structlog.stdlib.add_logger_name,
        structlog.stdlib.add_log_level,
        structlog.stdlib.PositionalArgumentsFormatter(),
        structlog.processors.TimeStamper(fmt="iso"),
        structlog.processors.StackInfoRenderer(),
        structlog.processors.format_exc_info,
        structlog.processors.UnicodeDecoder(),
        structlog.processors.JSONRenderer()
    ],
    context_class=dict,
    logger_factory=structlog.stdlib.LoggerFactory(),
    wrapper_class=structlog.stdlib.BoundLogger,
    cache_logger_on_first_use=True,
)

健康检查端点

@app.get("/health")
async def health_check():
    """健康检查端点"""
    return {
        "status": "healthy",
        "timestamp": datetime.utcnow().isoformat(),
        "version": settings.application_version
    }

4. 备份和恢复

数据库备份脚本

#!/bin/bash
# backup_db.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/database"
DB_NAME="c0726_production"

pg_dump -h localhost -U c0726_user $DB_NAME > $BACKUP_DIR/backup_$DATE.sql
gzip $BACKUP_DIR/backup_$DATE.sql

# 保留最近7天的备份
find $BACKUP_DIR -name "*.sql.gz" -mtime +7 -delete

应用数据备份

#!/bin/bash
# backup_app.sh

DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/application"
APP_DIR="/opt/c0726-backend"

tar -czf $BACKUP_DIR/app_backup_$DATE.tar.gz \
    $APP_DIR/uploads \
    $APP_DIR/logs \
    $APP_DIR/.config

# 保留最近7天的备份
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete

故障排除

常见问题解决

1. 数据库连接失败

   • 检查数据库服务状态
   • 验证连接配置参数
   • 检查防火墙设置

2. 应用启动失败

   • 检查环境变量配置
   • 验证依赖包完整性
   • 查看应用日志

3. 性能问题

   • 监控数据库连接池使用情况
   • 检查系统资源使用率
   • 优化数据库查询

监控指标

• 应用层面: 请求响应时间、错误率、并发连接数
• 系统层面: CPU使用率、内存使用率、磁盘IO
• 数据库层面: 查询性能、连接数、锁等待

索引

本文档提供了邮轮穿舱件管理系统后台的完整生产环境部署指南，涵盖了从环境准备到监控维护的全流程。通过遵循这些最佳实践，可以确保系统在生产环境中的稳定性、安全性和高性能。

参考文件:

• app/main.py
• app/core/settings.py
• app/tortoise_config.py
• Dockerfile
• pyproject.toml