零宕机部署指南：full-stack-fastapi-template的Docker Swarm实战方案-优快云博客

零宕机部署指南：full-stack-fastapi-template的Docker Swarm实战方案

【免费下载链接】full-stack-fastapi-template 项目地址: https://gitcode.com/gh_mirrors/fu/full-stack-fastapi-template

你是否还在为全栈应用部署时的服务中断烦恼？是否觉得Docker Compose在生产环境中难以应对高可用需求？本文将带你通过Docker Swarm实现full-stack-fastapi-template的无缝部署，全程零停机时间，30分钟即可完成从环境准备到服务上线的全流程。

为什么选择Docker Swarm

Docker Swarm作为Docker原生的容器编排工具，相比Kubernetes更轻量，同时提供了基本的服务发现、负载均衡和滚动更新能力。对于full-stack-fastapi-template这类包含后端API、前端界面和数据库的全栈应用，Swarm提供了恰到好处的编排能力，既避免了单机Docker Compose的单点故障风险，又无需维护复杂的K8s集群。

部署架构概览

full-stack-fastapi-template在Docker Swarm环境中的部署架构包含以下核心组件：

mermaid

这种架构通过docker-compose.yml文件定义，使用Traefik作为入口点处理SSL终止和请求路由，所有服务通过Docker Swarm的overlay网络通信，确保服务间安全可靠的连接。

环境准备与依赖

硬件要求

至少2台运行Linux的服务器（推荐Ubuntu 20.04+）
每台服务器2核CPU、4GB内存、20GB SSD
服务器间网络互通（推荐1Gbps连接）

软件依赖

Docker Engine 20.10+
Docker Compose 2.0+
Git

初始化Swarm集群

在主节点执行：

docker swarm init --advertise-addr 主节点IP

按照输出提示在其他节点执行加入命令，完成Swarm集群初始化。

部署步骤详解

1. 准备Traefik反向代理

Traefik作为Swarm集群的入口点，负责自动发现服务并处理HTTPS。首先创建Traefik配置目录：

mkdir -p /root/code/traefik-public/
cd /root/code/traefik-public/

创建Traefik的Docker Compose文件docker-compose.traefik.yml，关键配置如下：

version: '3.8'

services:
  traefik:
    image: traefik:v2.9
    command:
      - --providers.docker=true
      - --providers.docker.swarmMode=true
      - --providers.docker.exposedbydefault=false
      - --entrypoints.http.address=:80
      - --entrypoints.https.address=:443
      - --certificatesresolvers.le.acme.email=your-email@example.com
      - --certificatesresolvers.le.acme.storage=/letsencrypt/acme.json
      - --certificatesresolvers.le.acme.tlschallenge=true
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - traefik-letsencrypt:/letsencrypt
    deploy:
      placement:
        constraints: [node.role == manager]
      ports:
        - "80:80"
        - "443:443"

volumes:
  traefik-letsencrypt:

启动Traefik服务：

docker stack deploy -c docker-compose.traefik.yml traefik

2. 配置项目环境变量

克隆项目仓库：

git clone https://gitcode.com/gh_mirrors/fu/full-stack-fastapi-template
cd full-stack-fastapi-template

创建环境变量文件.env：

cp .env.example .env

编辑关键环境变量：

# 基础配置
ENVIRONMENT=production
DOMAIN=your-domain.com
STACK_NAME=fastapi-prod

# 安全配置
SECRET_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(32))")
FIRST_SUPERUSER=admin@your-domain.com
FIRST_SUPERUSER_PASSWORD=$(python -c "import secrets; print(secrets.token_urlsafe(16))")

# 数据库配置
POSTGRES_PASSWORD=$(python -c "import secrets; print(secrets.token_urlsafe(16))")
POSTGRES_USER=app
POSTGRES_DB=app

# CORS配置
BACKEND_CORS_ORIGINS=["https://your-domain.com"]

3. 部署应用栈

修改docker-compose.yml适配Swarm部署，主要变更包括：

添加deploy配置指定服务副本数和资源限制
使用Swarm overlay网络替代默认网络
配置数据库卷为Swarm共享存储

关键配置示例：

version: '3.8'

services:
  db:
    image: postgres:12
    volumes:
      - app-db-data:/var/lib/postgresql/data/pgdata
    env_file:
      - .env
    deploy:
      replicas: 1
      placement:
        constraints: [node.role == manager]
      resources:
        limits:
          cpus: '1'
          memory: 1G

  backend:
    image: ${DOCKER_IMAGE_BACKEND}:${TAG-latest}
    depends_on:
      - db
    env_file:
      - .env
    deploy:
      replicas: 2
      update_config:
        parallelism: 1
        delay: 10s
      restart_policy:
        condition: on-failure
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

  frontend:
    image: ${DOCKER_IMAGE_FRONTEND}:${TAG-latest}
    deploy:
      replicas: 2
      update_config:
        parallelism: 1
        delay: 10s
      resources:
        limits:
          cpus: '0.25'
          memory: 256M

volumes:
  app-db-data:
    driver: local

networks:
  traefik-public:
    external: true

部署应用栈：

docker stack deploy -c docker-compose.yml fastapi

4. 验证部署状态

检查服务状态：

docker stack services fastapi

预期输出类似：

ID             NAME                MODE         REPLICAS   IMAGE                               PORTS
abc123         fastapi_db          replicated   1/1        postgres:12
def456         fastapi_backend     replicated   2/2        fastapi-backend:latest
ghi789         fastapi_frontend    replicated   2/2        fastapi-frontend:latest

管理与监控

访问Traefik Dashboard

Traefik提供了直观的管理界面，通过https://traefik.your-domain.com访问，使用部署时设置的用户名密码登录。

查看应用界面

部署完成后，可通过以下URL访问各服务：

前端应用：https://your-domain.com
API文档：https://your-domain.com/docs
数据库管理：https://adminer.your-domain.com

滚动更新服务

当需要更新应用时，只需构建新镜像并执行：

docker service update --image new-image:tag fastapi_backend

Docker Swarm会自动执行滚动更新，确保服务不中断。

高可用与故障恢复

数据库备份策略

配置定期数据库备份：

#!/bin/bash
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
BACKUP_DIR="/root/backups"
mkdir -p $BACKUP_DIR

docker exec $(docker ps -qf "name=fastapi_db") pg_dump -U app app > $BACKUP_DIR/db_backup_$TIMESTAMP.sql

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

添加到crontab每日执行。

节点故障处理

当工作节点故障时，Swarm会自动在其他健康节点上重启服务。若主节点故障，需提升一个工作节点为新的主节点：

docker swarm join-token manager
# 在新主节点执行输出的命令

性能优化建议

资源调优

根据实际负载调整服务资源限制，可参考以下配置：

deploy:
  resources:
    limits:
      cpus: '0.5'
      memory: 512M
    reservations:
      cpus: '0.25'
      memory: 256M

数据库优化

修改PostgreSQL配置提高性能：

max_connections = 100
shared_buffers = 256MB
effective_cache_size = 768MB
maintenance_work_mem = 64MB
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100
random_page_cost = 1.1
effective_io_concurrency = 200
work_mem = 2621kB
min_wal_size = 1GB
max_wal_size = 4GB

常见问题解决

服务无法访问

检查Traefik日志：docker service logs traefik_traefik
确认服务标签配置正确：docker service inspect fastapi_backend
验证网络连通性：docker run --rm --net traefik-public busybox wget -qO- backend:80

数据库连接失败

检查数据库日志：docker service logs fastapi_db
验证环境变量：docker service inspect fastapi_backend | grep POSTGRES_
确认数据库卷挂载：docker volume inspect fastapi_app-db-data

前端无法连接后端API

检查前端环境变量配置：docker service inspect fastapi_frontend | grep VITE_API_URL

总结与下一步

通过Docker Swarm部署full-stack-fastapi-template，我们实现了：

高可用架构，服务自动恢复
零停机滚动更新
集中化反向代理与SSL管理
资源隔离与限制

下一步建议：

实现CI/CD流水线自动构建部署，可参考GitHub Actions配置
集成Prometheus和Grafana监控系统性能
配置ELK栈集中管理日志
探索Docker Swarm与云服务提供商的集成方案

完整部署文档可参考项目部署指南，代码实现详见docker-compose.yml和后端服务配置。

【免费下载链接】full-stack-fastapi-template 项目地址: https://gitcode.com/gh_mirrors/fu/full-stack-fastapi-template

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考