mirror of https://git.oceanpay.cc/danial/kami_apple_exchage.git synced 2025-12-18 21:23:49 +00:00

Files

danial 5c486e34d3 docs(项目): 添加项目文档并进行代码调整

- 新增 CODEBUDDY.md、GEMINI.md、GEMINI_CN.md 等项目文档
- 更新 Dockerfile 和其他配置文件
- 优化部分代码结构，如 orders.py、tasks.py 等
- 新增 .dockerignore 文件

2025-09-12 19:38:24 +08:00

5.9 KiB

Raw Blame History

Docker Swarm 部署指南

概述

本指南说明如何使用 Docker Swarm 部署 Apple Gift Card Exchange Platform。Docker Swarm 是 Docker 原生的容器编排工具，适用于中小规模的生产环境部署。

快速开始

1. 环境准备

确保系统已安装以下软件：

Docker (版本 20.10+)
Docker Compose (版本 1.29+)

2. 初始化 Swarm 集群

Linux/macOS

cd deploy
chmod +x swarm-init.sh
./swarm-init.sh

Windows

cd deploy
swarm-init.bat

3. 配置环境变量

编辑 deploy/.env 文件：

POSTGRES_PASSWORD=your_secure_password_here
LETSENCRYPT_EMAIL=your_email@example.com
FLOWER_AUTH=admin:$(openssl passwd -crypt admin)

详细部署步骤

步骤 1: 初始化 Docker Swarm

如果 Docker Swarm 未激活，运行初始化脚本：

# Linux/macOS
./swarm-init.sh init

# Windows
swarm-init.bat init

步骤 2: 构建镜像

构建所有必要的 Docker 镜像：

# Linux/macOS
./swarm-init.sh build

# Windows
swarm-init.bat build

步骤 3: 部署应用

部署整个应用到 Swarm 集群：

# Linux/macOS
./swarm-init.sh deploy

# Windows
swarm-init.bat deploy

服务管理

查看服务状态

# 查看所有服务
docker stack services apple-exchange

# 查看特定服务
docker service ps apple-exchange_frontend
docker service ps apple-exchange_api
docker service ps apple-exchange_worker

查看日志

# 查看服务日志
docker service logs apple-exchange_api
docker service logs apple-exchange_frontend
docker service logs apple-exchange_worker

# 使用脚本
./swarm-init.sh logs api
./swarm-init.sh logs frontend

扩展服务

# 扩展前端服务
docker service scale apple-exchange_frontend=3

# 扩展 API 服务
docker service scale apple-exchange_api=2

# 扩展 Worker 服务
docker service scale apple-exchange_worker=5

更新服务

# 重新部署所有服务
docker stack deploy -c deploy/docker-compose.swarm.yml apple-exchange

# 更新单个服务
docker service update --image apple-exchange-api:latest apple-exchange_api

移除部署

# 移除整个 stack
docker stack rm apple-exchange

# 使用脚本
./swarm-init.sh remove

服务架构

核心服务

frontend - Next.js 前端应用
- 副本数: 2
- 端口: 8080 (内部)
- 限制: 0.5 CPU, 512MB 内存
api - FastAPI 后端服务
- 副本数: 2
- 端口: 8000 (内部)
- 限制: 1 CPU, 1GB 内存
worker - Celery 工作进程
- 副本数: 3
- 限制: 2 CPU, 2GB 内存
- 部署约束: 仅在 worker 节点运行
beat - Celery 定时任务调度器
- 副本数: 1
- 部署约束: 仅在 manager 节点运行

基础设施服务

db - PostgreSQL 数据库
- 副本数: 1
- 部署约束: 仅在 manager 节点运行
- 数据持久化
redis - Redis 缓存和消息代理
- 副本数: 1
- 部署约束: 仅在 manager 节点运行
- 数据持久化
traefik - 反向代理和负载均衡器
- 副本数: 1
- 部署约束: 仅在 manager 节点运行
- 自动 HTTPS 证书管理

监控服务

flower - Celery 任务监控
- 副本数: 1
- 基本认证保护
- 可选服务

网络和存储

网络配置

app-network: Overlay 网络，用于服务间通信
端口映射:
- 80, 443: Traefik 入口
- 8080: Traefik Dashboard
- 5432: PostgreSQL (可选)
- 6379: Redis (可选)

存储卷

postgres_data: PostgreSQL 数据
redis_data: Redis 数据
shared_storage: 共享存储
playwright_browsers: Playwright 浏览器缓存
logs: 应用日志
data: 应用数据
screenshots: 截图存储
traefik_letsencrypt: Let's Encrypt 证书

访问地址

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

主应用: https://apple-exchange.com
API: https://api.apple-exchange.com
Flower 监控: https://flower.apple-exchange.com
Traefik Dashboard: https://traefik.apple-exchange.com

高级配置

节点标签

为优化部署，可以为节点添加标签：

# 为数据库节点添加标签
docker node update --label-add db=true node-name

# 为缓存节点添加标签
docker node update --label-add redis=true node-name

# 为工作节点添加标签
docker node update --label-add worker=true node-name

资源限制

根据服务器配置调整资源限制：

deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 4G
    reservations:
      cpus: '1.0'
      memory: 2G

健康检查

所有服务都配置了健康检查，确保服务正常运行：

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

故障排除

常见问题

Docker Swarm 未激活
```
docker swarm init
```

镜像构建失败

docker build -t apple-exchange-api:latest ../backend

服务启动失败
```
docker service logs apple-exchange_api
```

网络问题

docker network ls
docker network inspect apple-exchange_app-network

调试命令

# 查看集群状态
docker info

# 查看节点状态
docker node ls

# 查看服务详情
docker service inspect apple-exchange_api

# 进入容器调试
docker exec -it $(docker ps -q -f "name=apple-exchange-api") bash

生产环境建议

安全性

使用强密码和环境变量
启用 HTTPS 和 Let's Encrypt
限制 Traefik Dashboard 访问
定期更新基础镜像

监控

启用 Flower 监控
配置日志收集
设置告警规则
监控资源使用情况

备份

定期备份数据库
备份 Redis 数据
备份配置文件
测试恢复流程

扩展性

水平扩展服务副本
使用多节点集群
配置负载均衡
优化资源使用

5.9 KiB Raw Blame History