跳到主要内容

邮轮穿舱件管理系统后台 - 故障排除指南

目录​

系统概述​

邮轮穿舱件管理系统是一个基于FastAPI框架的后台管理系统，采用模块化架构设计，包含用户管理、角色权限、工单管理、图像处理等核心功能模块。

参考文件：

常见问题诊断​

1. 应用启动失败​

症状： 应用无法正常启动，端口被占用或依赖缺失

诊断步骤：

  1. 检查端口占用情况：netstat -tulpn | grep :8001
  2. 验证依赖安装：pip install -r requirements.txt
  3. 检查环境变量配置：.env文件是否存在且格式正确

解决方案：

# 停止占用端口的进程
sudo fuser -k 8001/tcp

# 重新安装依赖
pip install -r requirements.txt

# 启动应用
python app/main.py

2. 数据库连接异常​

症状： 数据库连接失败，ORM操作报错

诊断步骤：

  1. 检查数据库服务状态
  2. 验证数据库配置：.config/{env}.database.json
  3. 检查Tortoise ORM配置

参考文件：

解决方案：

# 检查数据库配置
from app.core.settings import settings
print(settings.tortoise_orm_config_dict)

数据库迁移问题​

1. 空数据库初始化失败​

症状： aerich init-db命令执行失败

诊断步骤：

  1. 检查数据库连接字符串
  2. 验证数据库用户权限
  3. 检查模型定义是否正确

解决方案：

# 重新初始化数据库
aerich init-db

# 如果失败，检查数据库连接
python -c "
from app.core.settings import settings
print('Database config:', settings.tortoise_orm_config_dict)
"

2. 模型更新迁移失败​

症状： aerich migrate或aerich upgrade命令失败

诊断步骤：

  1. 检查模型变更是否兼容
  2. 验证迁移文件是否正确生成
  3. 检查数据库版本一致性

解决方案：

# 查看迁移状态
aerich heads
aerich history

# 强制升级（谨慎使用）
aerich upgrade --force

参考文件：

认证和授权问题​

1. JWT令牌验证失败​

症状： 接口返回401未授权错误

诊断步骤：

  1. 检查JWT密钥配置
  2. 验证令牌过期时间
  3. 检查用户权限范围

参考文件：

解决方案：

# 检查JWT配置
from app.core.settings import settings
print(f"JWT Secret: {settings.JWT_SECRET_KEY}")
print(f"JWT Algorithm: {settings.JWT_ALGORITHM}")
print(f"JWT Expire: {settings.JWT_ACCESS_EXPIRE_MINUTES}分钟")

2. 用户权限不足​

症状： 接口返回403禁止访问错误

诊断步骤：

  1. 检查用户角色配置
  2. 验证权限范围设置
  3. 检查中间件权限验证逻辑

参考文件：

解决方案：

-- 检查用户权限
SELECT * FROM roles WHERE user_id = {用户ID};

异常处理问题​

1. 全局异常未捕获​

症状： 应用崩溃或返回非标准错误格式

诊断步骤：

  1. 检查全局异常中间件配置
  2. 验证异常处理逻辑
  3. 检查日志记录配置

参考文件：

解决方案：

# 检查异常处理中间件
from app.core.middleware import GlobalExceptionMiddleware
print("GlobalExceptionMiddleware已配置")

2. 错误日志记录异常​

症状： 错误信息未正确记录到日志文件

诊断步骤：

  1. 检查日志文件权限
  2. 验证日志配置路径
  3. 检查日志级别设置

解决方案：

# 检查日志配置
import logging
logger = logging.getLogger('app')
logger.setLevel(logging.DEBUG)

配置管理问题​

1. 环境配置加载失败​

症状： 应用无法读取正确的环境配置

诊断步骤：

  1. 检查环境变量ENV设置
  2. 验证配置文件路径和格式
  3. 检查JSON配置文件语法

参考文件：

解决方案：

# 检查当前环境
echo $ENV

# 检查配置文件
ls -la .config/
cat .config/development.application.json

2. 微信小程序配置异常​

症状： 微信相关功能无法正常使用

诊断步骤：

  1. 检查微信AppID和Secret配置
  2. 验证网络连接和API调用权限
  3. 检查微信配置加载逻辑

参考文件：

解决方案：

# 检查微信配置
from app.core.settings import settings
print(f"微信AppID: {settings.wechat_appid}")
print(f"微信Secret: {settings.wechat_secret}")

系统架构图​

flowchart TD
    A[客户端请求] --> B[FastAPI应用]
    B --> C[全局中间件]
    C --> D[路由分发]
    D --> E[认证授权]
    D --> F[用户管理]
    D --> G[工单管理]
    D --> H[图像处理]
    D --> I[日志记录]
    E --> J[数据库操作]
    F --> J
    G --> J
    H --> J
    I --> K[日志文件]
    J --> L[响应返回]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#fff3e0
    style D fill:#e8f5e8

数据流图​

flowchart LR
    A[用户请求] --> B[JWT验证]
    B --> C[权限检查]
    C --> D[业务处理]
    D --> E[数据库操作]
    E --> F[响应构建]
    F --> G[日志记录]
    G --> H[返回结果]
    
    style A fill:#f0f4c3
    style B fill:#ffccbc
    style C fill:#d1c4e9
    style D fill:#c8e6c9

异常处理流程图​

flowchart TD
    A[请求到达] --> B{异常发生?}
    B -->|否| C[正常处理]
    B -->|是| D[异常捕获]
    D --> E{异常类型判断}
    E -->|HTTP异常| F[HTTP错误处理]
    E -->|权限异常| G[权限错误处理]
    E -->|数据库异常| H[数据库错误处理]
    E -->|其他异常| I[通用错误处理]
    F --> J[记录日志]
    G --> J
    H --> J
    I --> J
    J --> K[返回错误响应]
    C --> L[返回成功响应]
    
    style D fill:#ffcdd2
    style J fill:#fff9c4

性能优化建议​

1. 数据库优化​

  • 为常用查询字段添加索引
  • 使用连接池管理数据库连接
  • 定期清理过期数据

2. 缓存策略​

  • 实现Redis缓存层
  • 缓存频繁访问的用户数据
  • 设置合理的缓存过期时间

3. 代码优化​

  • 避免N+1查询问题
  • 使用异步操作提高并发性能
  • 优化图像处理算法

索引​

本故障排除指南涵盖了邮轮穿舱件管理系统后台的常见问题及其解决方案。通过系统化的诊断方法和详细的解决步骤，可以帮助开发人员快速定位和解决问题。

关键要点：

  • 数据库迁移使用Aerich工具管理
  • 认证授权基于JWT令牌机制
  • 全局异常处理确保系统稳定性
  • 环境配置支持多环境部署

下一步行动：

  1. 定期检查系统日志文件
  2. 监控数据库性能指标
  3. 更新依赖包到最新稳定版本
  4. 进行定期的安全审计

参考文件汇总：