跳到主要内容

邮轮穿舱件管理系统后台 - 部署与运维指南

概述​

本文档提供邮轮穿舱件管理系统后台的完整部署、监控、维护和故障排除指南。该系统基于FastAPI框架构建，采用MySQL和MongoDB双数据库架构，支持微信小程序集成和图像处理功能。

系统架构​

技术栈​

  • 框架: FastAPI 3.x
  • 数据库: MySQL (主数据库) + MongoDB (文档存储)
  • ORM: Tortoise-ORM (MySQL) + Beanie (MongoDB)
  • 认证: JWT Token
  • 部署: Docker容器化
  • 迁移工具: Aerich

系统架构图​

flowchart TD
    subgraph 前端层
        A[Web前端]
        B[微信小程序]
    end
    
    subgraph API网关层
        C[FastAPI应用]
    end
    
    subgraph 业务服务层
        D[用户管理服务]
        E[角色权限服务]
        F[工件管理服务]
        G[图像处理服务]
        H[工单管理服务]
        I[日志服务]
    end
    
    subgraph 数据层
        J[MySQL数据库]
        K[MongoDB数据库]
    end
    
    A --> C
    B --> C
    C --> D
    C --> E
    C --> F
    C --> G
    C --> H
    C --> I
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> K

部署指南​

环境要求​

  • Python 3.11+
  • MySQL 5.7+
  • MongoDB 4.4+
  • Docker (可选)

1. 环境准备​

数据库配置​

创建MySQL数据库：

CREATE DATABASE c0726p CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

配置文件结构​

系统使用环境特定的配置文件：

.config/
├── development.application.json
├── development.database.json
├── development.wechat.json
├── production.application.json
├── production.database.json
└── production.wechat.json

参考源文件: settings.py

2. 依赖安装​

# 使用清华镜像源加速安装
pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple

参考源文件: Dockerfile

3. 数据库迁移​

空数据库初始化​

aerich init-db

模型更新​

aerich migrate
aerich upgrade

参考源文件: README.md

4. Docker部署​

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
COPY . /app
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

参考源文件: Dockerfile

5. 应用启动​

# 开发环境
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 生产环境
uvicorn app.main:app --host 0.0.0.0 --port 8000

监控与日志​

应用监控​

系统内置完整的异常处理机制：

sequenceDiagram
    participant Client
    participant FastAPI
    participant Middleware
    participant Handler
    
    Client->>FastAPI: HTTP请求
    FastAPI->>Middleware: 请求处理
    Middleware->>Handler: 业务逻辑
    alt 正常处理
        Handler-->>Middleware: 成功响应
        Middleware-->>FastAPI: 返回结果
        FastAPI-->>Client: 200 OK
    else 异常发生
        Handler-->>Middleware: 抛出异常
        Middleware-->>FastAPI: 异常捕获
        FastAPI-->>Client: 错误响应
    end

参考源文件: main.py

日志配置​

  • 应用日志: errors.log
  • 访问日志: MongoDB存储
  • 日志级别: 根据环境配置动态调整

维护操作​

数据库维护​

连接管理​

系统使用连接池管理数据库连接：

stateDiagram-v2
    [*] --> 应用启动
    应用启动 --> 数据库初始化: lifespan启动
    数据库初始化 --> 连接就绪: 连接池建立
    连接就绪 --> 请求处理: 获取连接
    请求处理 --> 连接释放: 处理完成
    连接释放 --> 连接就绪: 返回连接池
    连接就绪 --> 应用关闭: lifespan结束
    应用关闭 --> [*]: 连接关闭

参考源文件: lifespan.py

数据备份​

# MySQL备份
mysqldump -u root -p c0726p > backup_$(date +%Y%m%d).sql

# MongoDB备份
mongodump --db workpiece --out backup_$(date +%Y%m%d)

缓存管理​

系统使用运行时缓存优化性能：

  • 配置信息缓存
  • 用户会话缓存
  • 权限数据缓存

故障排除​

常见问题及解决方案​

1. 数据库连接失败​

症状: 应用启动时报数据库连接错误 解决方案:

  • 检查MySQL服务状态
  • 验证数据库配置参数
  • 确认网络连接

参考源文件: development.database.json

2. 迁移失败​

症状: aerich migrate 命令执行失败 解决方案:

# 检查迁移状态
aerich heads
# 回滚迁移
aerich downgrade

3. JWT认证问题​

症状: Token验证失败 解决方案:

  • 检查JWT_SECRET_KEY配置
  • 验证Token过期时间设置
  • 确认算法一致性

参考源文件: settings.py

4. 微信集成故障​

症状: 微信小程序API调用失败 解决方案:

  • 验证wechat_appid和wechat_secret配置
  • 检查网络连通性
  • 确认微信API权限

参考源文件: settings.py

性能优化建议​

数据库优化​

-- 为常用查询字段添加索引
ALTER TABLE users ADD INDEX idx_email (email);
ALTER TABLE workpieces ADD INDEX idx_status (status);

应用层优化​

  • 启用Gzip压缩
  • 配置CDN加速静态资源
  • 使用Redis缓存热点数据

安全配置​

环境安全​

  • 使用环境变量存储敏感信息
  • 定期更换JWT密钥
  • 配置HTTPS证书

API安全​

  • 实现CORS策略
  • 请求频率限制
  • 输入数据验证

参考源文件: main.py

备份与恢复​

备份策略​

#!/bin/bash
# 每日备份脚本
DATE=$(date +%Y%m%d)
# 备份MySQL
mysqldump -u root -p$DB_PASSWORD c0726p > /backup/mysql_${DATE}.sql
# 备份MongoDB
mongodump --uri="mongodb://localhost:27017" --out=/backup/mongo_${DATE}
# 清理7天前备份
find /backup -name "*.sql" -mtime +7 -delete
find /backup -name "mongo_*" -mtime +7 -exec rm -rf {} \;

恢复流程​

# MySQL恢复
mysql -u root -p c0726p < backup_20250101.sql

# MongoDB恢复
mongorestore --uri="mongodb://localhost:27017" backup/mongo_20250101/

索引​

本系统采用现代化的微服务架构，具有良好的可扩展性和维护性。通过遵循本文档的部署和维护指南，可以确保系统稳定运行并快速响应故障。

关键要点:

  • 使用Aerich进行数据库版本管理
  • 采用双数据库架构分离业务数据和文档数据
  • 实现完整的异常处理和日志记录
  • 支持多环境配置和Docker容器化部署

通过定期执行维护操作和监控系统状态，可以确保邮轮穿舱件管理系统后台的长期稳定运行。

参考源文件汇总: