Docker部署指南

概述

本文档提供邮轮穿舱件管理系统后台的Docker部署指南，涵盖镜像构建、容器运行和网络配置等关键环节。

项目架构分析

系统架构图

flowchart TD
    subgraph Docker容器
        A[FastAPI应用] --> B[数据库连接]
        A --> C[文件存储]
        A --> D[微信小程序API]
    end
    
    subgraph 外部依赖
        E[PostgreSQL数据库]
        F[Redis缓存]
        G[文件存储系统]
        H[微信API]
    end
    
    B --> E
    C --> G
    D --> H

核心组件依赖关系

flowchart TD
    subgraph 应用层
        A[app/main.py] --> B[核心模块]
        A --> C[路由模块]
        A --> D[服务模块]
        A --> E[数据模型]
    end
    
    subgraph 配置层
        F[settings.py] --> G[数据库配置]
        F --> H[应用配置]
        F --> I[微信配置]
    end
    
    B --> F
    C --> D
    D --> E

Docker镜像构建

Dockerfile分析

基于项目根目录的Dockerfile，构建过程如下：

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"]

构建步骤说明：

使用Python 3.11 slim基础镜像
设置工作目录为/app
复制依赖文件并安装Python包
复制应用代码到容器
启动FastAPI应用

构建命令

# 构建Docker镜像
docker build -t cruise-component-backend:latest .

# 查看构建的镜像
docker images | grep cruise-component-backend

容器运行配置

环境变量配置

系统使用Pydantic Settings管理配置，支持以下环境变量：

# 应用环境
ENV=development|staging|production

# JWT配置
JWT_SECRET_KEY=your-secret-key
JWT_ALGORITHM=HS256
JWT_ACCESS_EXPIRE_MINUTES=300

# 微信小程序配置
WECHAT_APPID=your-appid
WECHAT_SECRET=your-secret

# CVC API配置
CVC_TARGET_URL=http://localhost:8000
CVC_API_KEY=abc

单容器运行

# 开发环境运行
docker run -d \
  --name cruise-backend \
  -p 8000:8000 \
  -e ENV=development \
  -e JWT_SECRET_KEY=your-secret-key \
  cruise-component-backend:latest

生产环境Docker Compose配置

version: '3.8'

services:
  backend:
    image: cruise-component-backend:latest
    container_name: cruise-backend
    ports:
      - "8000:8000"
    environment:
      - ENV=production
      - JWT_SECRET_KEY=${JWT_SECRET_KEY}
      - WECHAT_APPID=${WECHAT_APPID}
      - WECHAT_SECRET=${WECHAT_SECRET}
    volumes:
      - ./config:/app/.config:ro
      - ./logs:/app/logs
    depends_on:
      - postgres
      - redis
    networks:
      - backend-network

  postgres:
    image: postgres:13
    container_name: cruise-postgres
    environment:
      - POSTGRES_DB=cruise_db
      - POSTGRES_USER=admin
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    networks:
      - backend-network

  redis:
    image: redis:6-alpine
    container_name: cruise-redis
    networks:
      - backend-network

volumes:
  postgres_data:

networks:
  backend-network:
    driver: bridge

网络配置

容器网络架构

flowchart TD
    subgraph Docker网络
        A[后端应用:8000] --> B[PostgreSQL:5432]
        A --> C[Redis:6379]
        D[外部访问] --> A
    end

网络配置示例

# 创建自定义网络
docker network create backend-network

# 运行数据库容器
docker run -d \
  --name postgres \
  --network backend-network \
  -e POSTGRES_DB=cruise_db \
  -e POSTGRES_USER=admin \
  -e POSTGRES_PASSWORD=password \
  postgres:13

# 运行应用容器
docker run -d \
  --name cruise-backend \
  --network backend-network \
  -p 8000:8000 \
  -e ENV=production \
  cruise-component-backend:latest

数据库迁移

迁移流程

根据README.md中的说明，数据库迁移分为两种情况：

空数据库初始化

aerich init-db

模型更新

aerich migrate
aerich upgrade

Docker环境迁移执行

# 进入运行中的容器执行迁移
docker exec -it cruise-backend bash

# 在容器内执行迁移命令
aerich migrate
aerich upgrade

# 或使用单行命令
docker exec cruise-backend aerich migrate
docker exec cruise-backend aerich upgrade

健康检查与监控

健康检查端点

应用提供以下健康检查端点：

GET / - 基础状态检查
GET /info - API状态信息

容器健康检查配置

# docker-compose.yml中的健康检查配置
healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/info"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

配置文件管理

配置目录结构

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

配置文件挂载

# 挂载本地配置目录
docker run -d \
  --name cruise-backend \
  -p 8000:8000 \
  -v $(pwd)/config:/app/.config:ro \
  cruise-component-backend:latest

日志管理

日志配置

应用使用自定义日志系统，日志文件位于：

应用日志：/app/logs/app.log
错误日志：/app/errors.log

日志挂载配置

# 挂载日志目录
docker run -d \
  --name cruise-backend \
  -p 8000:8000 \
  -v $(pwd)/logs:/app/logs \
  cruise-component-backend:latest

安全配置

安全最佳实践

使用非root用户运行

FROM python:3.11-slim

# 创建非root用户
RUN adduser --disabled-password --gecos '' appuser
USER appuser

WORKDIR /app
# ... 其余配置

最小化镜像大小

# 多阶段构建优化
FROM python:3.11-slim as builder
# 构建阶段...

FROM python:3.11-slim
COPY --from=builder /app /app

性能优化

镜像构建优化

# 使用.dockerignore文件排除不必要的文件
.git/
__pycache__/
*.pyc
.venv/

容器资源限制

# docker-compose资源限制
deploy:
  resources:
    limits:
      memory: 512M
      cpus: '1.0'
    reservations:
      memory: 256M
      cpus: '0.5'

故障排除

常见问题解决

数据库连接失败
- 检查数据库容器状态
- 验证网络连接
- 检查数据库配置
迁移执行失败
- 确认aerich配置正确
- 检查数据库权限
- 查看容器日志
应用启动失败
- 检查环境变量配置
- 验证配置文件存在
- 查看应用日志

日志查看命令

# 查看容器日志
docker logs cruise-backend

# 实时查看日志
docker logs -f cruise-backend

# 查看特定时间段的日志
docker logs --since 1h cruise-backend

索引

本文档提供了邮轮穿舱件管理系统后台的完整Docker部署方案，涵盖了从镜像构建到生产环境部署的全流程。通过合理的网络配置、资源管理和监控策略，可以确保应用在Docker环境中的稳定运行。

参考文件：

概述​

项目架构分析​

系统架构图​

核心组件依赖关系​

Docker镜像构建​

Dockerfile分析​

构建命令​

容器运行配置​

环境变量配置​

单容器运行​

生产环境Docker Compose配置​

网络配置​

容器网络架构​

网络配置示例​

数据库迁移​

迁移流程​

Docker环境迁移执行​

健康检查与监控​

健康检查端点​

容器健康检查配置​

配置文件管理​

配置目录结构​

配置文件挂载​

日志管理​

日志配置​

日志挂载配置​

安全配置​

安全最佳实践​

性能优化​

镜像构建优化​

容器资源限制​

故障排除​

常见问题解决​

日志查看命令​

索引​

概述