kami_apple_exchage/deploy

Apple Gift Card Exchange Platform - 部署指南

本目录包含完整的前后端部署配置文件。

🚀 快速开始

1. 环境要求

• Docker >= 20.10
• Docker Compose >= 2.0
• 至少 4GB 内存
• 至少 10GB 磁盘空间

2. 一键部署

# 开发环境部署
./deploy/deploy.sh dev

# 生产环境部署
./deploy/deploy.sh prod

# 包含监控的生产环境部署
./deploy/deploy.sh monitoring

# 清理并重新部署
./deploy/deploy.sh dev --cleanup

3. 手动部署

# 创建必要目录
mkdir -p deploy/ssl deploy/logs

# 启动开发环境
docker-compose -f deploy/docker-compose.combined.yml up -d

# 启动生产环境（包含 Nginx）
docker-compose -f deploy/docker-compose.combined.yml --profile production up -d

# 启动监控服务
docker-compose -f deploy/docker-compose.combined.yml --profile monitoring up -d

📁 文件结构

deploy/
├── docker-compose.yml          # 后端服务配置
├── docker-compose.combined.yml  # 完整前后端配置
├── Dockerfile                   # 后端 API/Beat/Flower 镜像
├── Dockerfile.worker            # 后端 Worker 镜像
├── Dockerfile.frontend          # 前端 Next.js 镜像
├── nginx.conf                   # Nginx 配置
├── redis.conf                   # Redis 配置
├── docker-entrypoint.sh         # 后端启动脚本
├── run.py                       # 后端运行脚本
├── test_gunicorn.py             # Gunicorn 测试脚本
├── deploy.sh                    # 自动化部署脚本
├── k8s/                         # Kubernetes 配置
├── helm/                        # Helm Charts
└── ssl/                         # SSL 证书目录

🔧 服务配置

前端服务 (Next.js)

• 端口: 3000
• 镜像: 自定义构建
• 环境变量:
  • NEXT_PUBLIC_API_URL: 后端 API 地址
  • NEXT_PUBLIC_ENV: 环境类型
  • NEXT_PUBLIC_TELEMETRY_ENDPOINT: 遥测端点

后端服务 (FastAPI)

• 端口: 8000
• 镜像: 自定义构建
• 服务类型: api, worker, beat, flower
• 数据库: PostgreSQL 17
• 缓存: Redis 7

基础设施

• 数据库: PostgreSQL 17
• 缓存: Redis 7
• 消息队列: Redis (Celery)
• 代理: Nginx (生产环境)

🌐 访问地址

开发环境

• 前端: http://localhost:3000
• 后端 API: http://localhost:8000
• API 文档: http://localhost:8000/docs

生产环境

• 前端: http://localhost
• 后端 API: http://localhost/api
• API 文档: http://localhost/api/docs

监控服务

• Celery Flower: http://localhost:5555

📊 健康检查

# 前端健康检查
curl http://localhost:3000/

# 后端健康检查
curl http://localhost:8000/api/v1/health/liveness

# 数据库检查
docker exec apple-exchange-db pg_isready -U postgres

# Redis 检查
docker exec apple-exchange-redis redis-cli ping

🔍 日志管理

# 查看所有服务日志
docker-compose -f deploy/docker-compose.combined.yml logs -f

# 查看特定服务日志
docker-compose -f deploy/docker-compose.combined.yml logs -f frontend
docker-compose -f deploy/docker-compose.combined.yml logs -f api
docker-compose -f deploy/docker-compose.combined.yml logs -f worker

# 查看错误日志
docker-compose -f deploy/docker-compose.combined.yml logs --tail=100

🛠️ 常用操作

# 停止所有服务
docker-compose -f deploy/docker-compose.combined.yml down

# 重启特定服务
docker-compose -f deploy/docker-compose.combined.yml restart api

# 扩展 Worker 服务
docker-compose -f deploy/docker-compose.combined.yml up -d --scale worker=3

# 清理未使用的资源
docker system prune -f

# 查看资源使用情况
docker stats

🔒 安全配置

SSL 证书

生产环境需要配置 SSL 证书：

# 生成自签名证书（仅用于测试）
openssl req -x509 -newkey rsa:4096 -keyout deploy/ssl/key.pem -out deploy/ssl/cert.pem -days 365 -nodes

# 使用 Let's Encrypt（生产环境）
# 需要配置域名和反向代理

环境变量

创建环境文件：

# 后端环境变量
cp backend/.env.example backend/.env

# 前端环境变量
cp frontend/env.example frontend/.env.local

📈 性能优化

数据库优化

-- 在 PostgreSQL 中执行
CREATE INDEX idx_orders_status ON orders(status);
CREATE INDEX idx_orders_created_at ON orders(created_at);
ANALYZE;

Redis 优化

# 在 redis.conf 中配置
maxmemory 512mb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
save 60 10000

Docker 优化

# 在 docker-compose.yml 中调整资源限制
deploy:
  resources:
    limits:
      cpus: '2.0'
      memory: 2G
    reservations:
      cpus: '1.0'
      memory: 1G

🚨 故障排除

常见问题

1. 端口冲突

   # 检查端口占用
   netstat -tulpn | grep :3000
   netstat -tulpn | grep :8000
   

2. 内存不足

   # 清理 Docker 资源
   docker system prune -a -f
   

3. 数据库连接失败

   # 重启数据库
   docker-compose -f deploy/docker-compose.combined.yml restart db
   

4. Worker 任务堆积

   # 扩展 Worker 数量
   docker-compose -f deploy/docker-compose.combined.yml up -d --scale worker=5
   

日志分析

# 查看错误日志
docker-compose -f deploy/docker-compose.combined.yml logs --tail=100 api | grep ERROR

# 查看慢查询
docker-compose -f deploy/docker-compose.combined.yml logs --tail=100 db | grep SLOW

🔄 更新部署

# 拉取最新代码
git pull origin main

# 重新构建并启动
docker-compose -f deploy/docker-compose.combined.yml build
docker-compose -f deploy/docker-compose.combined.yml up -d

# 数据库迁移（如果需要）
docker-compose -f deploy/docker-compose.combined.yml exec api alembic upgrade head

📞 支持

如果遇到问题，请：

1. 查看日志文件
2. 检查服务状态
3. 查看本项目文档
4. 提交 Issue

---

注意: 生产环境部署前请仔细阅读安全配置和性能优化部分。