team/tyapi-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
39dbeecfe1e8e73a21ca381f7f04e9cc667bd6a4
tyapi-server/docs/开始指南/生产环境部署指南.md

8.5 KiB
Raw Blame History

TYAPI 生产环境部署指南

🎯 部署架构概览

┌─────────────────────────────────────────────────────────────┐
│                        生产环境架构                           │
├─────────────────────────────────────────────────────────────┤
│  Nginx (80/443) ──► TYAPI App (8080) ──► PostgreSQL (5432) │
│       │                    │                     │          │
│       │                    └──► Redis (6379)     │          │
│       │                    └──► Jaeger (4317)    │          │
│       └──► Jaeger UI (16686)                      │          │
└─────────────────────────────────────────────────────────────┘

私有镜像仓库: docker-registry.tianyuanapi.com

📋 部署清单

✅ 已创建的文件

  • Dockerfile - 多阶段构建的生产级镜像
  • docker-compose.prod.yml - 生产环境服务编排
  • .dockerignore - Docker 构建忽略文件
  • deployments/docker/nginx.conf - Nginx 反向代理配置
  • .env.production - 生产环境配置模板
  • scripts/deploy.sh - Linux/macOS 部署脚本
  • scripts/deploy.ps1 - Windows PowerShell 部署脚本
  • Makefile - 新增生产环境相关命令

🛠 服务组件

  1. PostgreSQL - 主数据库 (生产优化配置)
  2. Redis - 缓存和会话存储 (密码保护)
  3. TYAPI App - 主应用程序 (生产模式)
  4. Jaeger - 链路追踪 (生产级配置)
  5. Nginx - 反向代理和负载均衡
  6. Prometheus - 监控数据收集和存储
  7. Grafana - 监控数据可视化仪表盘
  8. MinIO - S3 兼容对象存储服务
  9. pgAdmin - PostgreSQL 数据库管理工具

🚀 快速部署步骤

1️⃣ 环境准备

# 确保服务器已安装
- Docker 20.10+
- Docker Compose 2.0+
- Git (可选)

# 检查版本
docker --version
docker-compose --version

2️⃣ 获取代码

# 克隆项目到服务器
git clone <your-repo-url> tyapi-server
cd tyapi-server

# 或直接上传项目文件

3️⃣ 配置环境变量

# 复制配置模板
cp .env.production .env

# 编辑配置文件
nano .env

必须修改的关键配置：

# 数据库配置
DB_PASSWORD=your_secure_database_password_here

# Redis配置
REDIS_PASSWORD=your_secure_redis_password_here

# JWT密钥 (至少32位)
JWT_SECRET=your_super_secure_jwt_secret_key_for_production_at_least_32_chars

# Grafana管理员配置
GRAFANA_ADMIN_PASSWORD=your_secure_grafana_password_here

# MinIO对象存储配置
MINIO_ROOT_PASSWORD=your_secure_minio_password_here

# pgAdmin数据库管理配置
PGADMIN_PASSWORD=your_secure_pgadmin_password_here

# 短信服务配置
SMS_ACCESS_KEY_ID=your_sms_access_key_id
SMS_ACCESS_KEY_SECRET=your_sms_access_key_secret
SMS_SIGN_NAME=your_sms_sign_name
SMS_TEMPLATE_CODE=your_sms_template_code

4️⃣ 执行部署

Linux/macOS:

# 给脚本执行权限
chmod +x scripts/deploy.sh

# 部署指定版本
./scripts/deploy.sh v1.0.0

# 或部署最新版本
./scripts/deploy.sh

Windows:

# 执行部署脚本
.\scripts\deploy.ps1 -Version "v1.0.0"

# 或使用Makefile
make docker-build-prod
make docker-push-prod
make prod-up

📊 部署脚本功能

🔄 自动化流程

  1. 环境检查 - 验证 Docker、docker-compose 等工具
  2. 配置验证 - 检查关键配置项的安全性
  3. 镜像构建 - 构建生产级 Docker 镜像
  4. 镜像推送 - 推送到私有 Registry
  5. 服务部署 - 启动所有生产服务
  6. 健康检查 - 验证服务运行状态
  7. 信息展示 - 显示访问地址和管理命令

🛡 安全特性

  • 非 root 用户运行 - 容器内使用专用用户
  • 资源限制 - CPU 和内存使用限制
  • 健康检查 - 自动重启异常服务
  • 网络隔离 - 独立的 Docker 网络
  • 密码保护 - 数据库和 Redis 强制密码
  • SSL 就绪 - Nginx HTTPS 配置模板

🎛 管理命令

通过 Makefile 管理:

# 构建生产镜像
make docker-build-prod

# 推送到Registry
make docker-push-prod

# 启动生产服务
make prod-up

# 停止生产服务
make prod-down

# 查看服务状态
make prod-status

# 查看实时日志
make prod-logs

通过 docker-compose 管理:

# 启动所有服务
docker-compose -f docker-compose.prod.yml up -d

# 停止所有服务
docker-compose -f docker-compose.prod.yml down

# 查看服务状态
docker-compose -f docker-compose.prod.yml ps

# 查看日志
docker-compose -f docker-compose.prod.yml logs -f

# 重启特定服务
docker-compose -f docker-compose.prod.yml restart tyapi-app

🌐 服务访问地址

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

核心服务

  • API 服务: http://your-server:8080
  • API 文档: http://your-server:8080/swagger/index.html
  • 健康检查: http://your-server:8080/health

监控和追踪

  • Grafana 仪表盘: http://your-server:3000
  • Prometheus 监控: http://your-server:9090
  • Jaeger 链路追踪: http://your-server:16686

管理工具

  • pgAdmin 数据库管理: http://your-server:5050
  • MinIO 对象存储: http://your-server:9000 (API)
  • MinIO 控制台: http://your-server:9001 (管理界面)

通过 Nginx 代理访问

如果启用了 Nginx，也可以通过以下路径访问：

  • 根目录: http://your-server/ → 重定向到 API 文档
  • API 服务: http://your-server/api/
  • Grafana: http://your-server/grafana/
  • Prometheus: http://your-server/prometheus/
  • Jaeger: http://your-server/jaeger/
  • MinIO API: http://your-server/minio/
  • MinIO 控制台: http://your-server/minio-console/
  • pgAdmin: http://your-server/pgadmin/

🔍 监控和故障排除

查看日志:

# 查看应用日志
docker-compose -f docker-compose.prod.yml logs tyapi-app

# 查看数据库日志
docker-compose -f docker-compose.prod.yml logs postgres

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

健康检查:

# 检查服务状态
curl -f http://localhost:8080/health

# 检查Jaeger
curl -f http://localhost:16686

# 查看容器状态
docker ps

常见问题:

  1. 镜像拉取失败

    # 检查Registry连接
docker pull docker-registry.tianyuanapi.com/tyapi-server:latest

  2. 数据库连接失败

    # 检查数据库配置
docker-compose -f docker-compose.prod.yml logs postgres

  3. 应用启动失败

    # 查看应用日志
docker-compose -f docker-compose.prod.yml logs tyapi-app

🔧 配置优化

性能调优:

  1. 数据库优化 - 根据服务器配置调整 PostgreSQL 参数
  2. Redis 优化 - 配置内存和持久化策略
  3. 应用调优 - 调整连接池大小和超时时间
  4. Nginx 优化 - 配置缓存和压缩

扩展配置:

  1. HTTPS 配置 - 添加 SSL 证书支持
  2. 域名配置 - 绑定自定义域名
  3. 备份策略 - 配置数据库自动备份
  4. 日志收集 - 集成 ELK 或其他日志系统

🔄 版本更新

零停机更新:

# 构建新版本
./scripts/deploy.sh v1.1.0

# 或渐进式更新
docker-compose -f docker-compose.prod.yml pull tyapi-app
docker-compose -f docker-compose.prod.yml up -d --no-deps tyapi-app

回滚操作:

# 回滚到指定版本
docker tag docker-registry.tianyuanapi.com/tyapi-server:v1.0.0 \
           docker-registry.tianyuanapi.com/tyapi-server:latest

docker-compose -f docker-compose.prod.yml up -d --no-deps tyapi-app

📞 技术支持

如果在部署过程中遇到问题，请：

  1. 检查本文档的故障排除部分
  2. 查看服务日志定位问题
  3. 确认配置文件的正确性
  4. 验证网络和防火墙设置

部署前请务必:

  • ✅ 测试配置文件
  • ✅ 备份现有数据
  • ✅ 验证 Registry 访问
  • ✅ 确认服务器资源充足