跳到主要内容

邮轮穿舱件管理系统后台 - 安装与配置指南

概述​

本文档提供邮轮穿舱件管理系统后台的完整安装和配置指南。该系统基于FastAPI框架构建，使用Tortoise ORM进行数据库操作，并通过Aerich工具管理数据库迁移。

环境要求​

系统要求​

  • Python版本: 3.11+
  • 数据库: MySQL 5.7+
  • 操作系统: Linux/Windows/macOS

软件依赖​

  • FastAPI Web框架
  • Tortoise ORM数据库ORM
  • Aerich数据库迁移工具
  • MySQL数据库驱动
  • Pydantic设置管理

项目结构分析​

flowchart TD
    A[项目根目录] --> B[app/]
    A --> C[.config/]
    A --> D[migrations/]
    A --> E[test/]
    A --> F[Dockerfile]
    
    B --> B1[core/]
    B --> B2[models/]
    B --> B3[routers/]
    B --> B4[service/]
    B --> B5[main.py]
    B --> B6[tortoise_config.py]
    
    B1 --> B1a[settings.py]
    B1 --> B1b[lifespan.py]
    B1 --> B1c[middleware.py]
    
    C --> C1[development.database.json]
    C --> C2[development.application.json]
    C --> C3[development.wechat.json]

安装步骤​

1. 克隆项目代码​

git clone <repository_url>
cd c0726-backend-api

2. 创建Python虚拟环境​

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

3. 安装依赖包​

pip install -r requirements.txt

如果requirements.txt文件编码问题，可通过pyproject.toml安装：

pip install .

4. 数据库配置​

创建MySQL数据库​

CREATE DATABASE c0726p CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

配置数据库连接​

编辑 .config/development.database.json 文件：

{
    "connections": {
        "default": {
            "engine": "tortoise.backends.mysql",
            "credentials": {
                "host": "localhost",
                "port": 3306,
                "user": "root",
                "password": "123456",
                "database": "c0726p"
            }
        }
    }
}

5. 应用配置​

创建应用配置文件 .config/development.application.json：

{
    "app_debug": true,
    "app_name": "邮轮穿舱件管理系统",
    "app_version": "1.0.0",
    "app_desc": "邮轮穿舱件管理后台API"
}

创建微信配置 .config/development.wechat.json：

{
    "wechat_appid": "your_appid",
    "wechat_secret": "your_secret"
}

Aerich数据库迁移配置​

配置说明​

系统使用Aerich进行数据库迁移管理，配置位于 pyproject.toml：

[tool.aerich]
tortoise_orm = "app.tortoise_config.AERICH_CONFIG"
location = "./migrations"
src_folder = "./."

数据库迁移操作流程​

flowchart LR
    A[模型变更] --> B[aerich migrate]
    B --> C[生成迁移文件]
    C --> D[aerich upgrade]
    D --> E[应用迁移]
    E --> F[数据库更新完成]

1. 空数据库初始化​

首次部署或需要重新初始化数据库时执行：

aerich init-db

2. 模型更新迁移​

当数据模型发生变化时，执行以下命令：

步骤1: 生成迁移文件

aerich migrate --name "add_new_feature"

步骤2: 应用迁移

aerich upgrade

3. 查看迁移状态​

aerich heads    # 查看最新迁移
aerich history  # 查看迁移历史
aerich downgrade # 回滚迁移

系统架构图​

flowchart TD
    subgraph "FastAPI应用层"
        A[HTTP请求] --> B[中间件]
        B --> C[路由分发]
        C --> D[业务逻辑]
        D --> E[数据访问]
    end
    
    subgraph "数据层"
        E --> F[Tortoise ORM]
        F --> G[MySQL数据库]
    end
    
    subgraph "迁移管理"
        H[Aerich工具] --> I[迁移文件]
        I --> J[版本控制]
    end

启动应用​

开发环境启动​

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

生产环境启动​

uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

Docker部署​

# 构建镜像
docker build -t c0726-backend .

# 运行容器
docker run -d -p 8000:8000 --name c0726-backend c0726-backend

验证安装​

1. 健康检查​

curl http://localhost:8000/

预期响应：{"message": "system works fine"}

2. API文档访问​

打开浏览器访问：http://localhost:8000/docs

故障排除​

常见问题​

  1. 数据库连接失败

    • 检查MySQL服务是否启动
    • 验证数据库配置信息
    • 确认数据库用户权限

  2. 迁移失败

    • 检查迁移文件完整性
    • 确认数据库版本兼容性
    • 查看Aerich日志输出

  3. 依赖安装失败

    • 检查Python版本兼容性
    • 验证网络连接
    • 尝试使用国内镜像源

日志查看​

应用日志输出到 errors.log 文件，可通过以下命令查看：

tail -f errors.log

参考文件​

索引​

本指南详细介绍了邮轮穿舱件管理系统后台的完整安装和配置流程。重点强调了Aerich数据库迁移工具的使用方法，包括空数据库初始化和模型更新迁移两个核心场景。通过遵循本指南，您可以成功部署和配置系统，确保数据库迁移的正确执行。

系统采用模块化设计，配置管理清晰，支持多环境部署。Aerich工具提供了可靠的数据库版本控制机制，确保数据模型变更的安全性和可追溯性。