feat(架构): 完善基础架构设计
This commit is contained in:
338
docs/开始指南/生产环境部署指南.md
Normal file
338
docs/开始指南/生产环境部署指南.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# 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️⃣ **环境准备**
|
||||
|
||||
```bash
|
||||
# 确保服务器已安装
|
||||
- Docker 20.10+
|
||||
- Docker Compose 2.0+
|
||||
- Git (可选)
|
||||
|
||||
# 检查版本
|
||||
docker --version
|
||||
docker-compose --version
|
||||
```
|
||||
|
||||
### 2️⃣ **获取代码**
|
||||
|
||||
```bash
|
||||
# 克隆项目到服务器
|
||||
git clone <your-repo-url> tyapi-server
|
||||
cd tyapi-server
|
||||
|
||||
# 或直接上传项目文件
|
||||
```
|
||||
|
||||
### 3️⃣ **配置环境变量**
|
||||
|
||||
```bash
|
||||
# 复制配置模板
|
||||
cp .env.production .env
|
||||
|
||||
# 编辑配置文件
|
||||
nano .env
|
||||
```
|
||||
|
||||
**必须修改的关键配置：**
|
||||
|
||||
```bash
|
||||
# 数据库配置
|
||||
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:**
|
||||
|
||||
```bash
|
||||
# 给脚本执行权限
|
||||
chmod +x scripts/deploy.sh
|
||||
|
||||
# 部署指定版本
|
||||
./scripts/deploy.sh v1.0.0
|
||||
|
||||
# 或部署最新版本
|
||||
./scripts/deploy.sh
|
||||
```
|
||||
|
||||
#### **Windows:**
|
||||
|
||||
```powershell
|
||||
# 执行部署脚本
|
||||
.\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 管理:**
|
||||
|
||||
```bash
|
||||
# 构建生产镜像
|
||||
make docker-build-prod
|
||||
|
||||
# 推送到Registry
|
||||
make docker-push-prod
|
||||
|
||||
# 启动生产服务
|
||||
make prod-up
|
||||
|
||||
# 停止生产服务
|
||||
make prod-down
|
||||
|
||||
# 查看服务状态
|
||||
make prod-status
|
||||
|
||||
# 查看实时日志
|
||||
make prod-logs
|
||||
```
|
||||
|
||||
### **通过 docker-compose 管理:**
|
||||
|
||||
```bash
|
||||
# 启动所有服务
|
||||
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/`
|
||||
|
||||
## 🔍 **监控和故障排除**
|
||||
|
||||
### **查看日志:**
|
||||
|
||||
```bash
|
||||
# 查看应用日志
|
||||
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
|
||||
```
|
||||
|
||||
### **健康检查:**
|
||||
|
||||
```bash
|
||||
# 检查服务状态
|
||||
curl -f http://localhost:8080/health
|
||||
|
||||
# 检查Jaeger
|
||||
curl -f http://localhost:16686
|
||||
|
||||
# 查看容器状态
|
||||
docker ps
|
||||
```
|
||||
|
||||
### **常见问题:**
|
||||
|
||||
1. **镜像拉取失败**
|
||||
|
||||
```bash
|
||||
# 检查Registry连接
|
||||
docker pull docker-registry.tianyuanapi.com/tyapi-server:latest
|
||||
```
|
||||
|
||||
2. **数据库连接失败**
|
||||
|
||||
```bash
|
||||
# 检查数据库配置
|
||||
docker-compose -f docker-compose.prod.yml logs postgres
|
||||
```
|
||||
|
||||
3. **应用启动失败**
|
||||
```bash
|
||||
# 查看应用日志
|
||||
docker-compose -f docker-compose.prod.yml logs tyapi-app
|
||||
```
|
||||
|
||||
## 🔧 **配置优化**
|
||||
|
||||
### **性能调优:**
|
||||
|
||||
1. **数据库优化** - 根据服务器配置调整 PostgreSQL 参数
|
||||
2. **Redis 优化** - 配置内存和持久化策略
|
||||
3. **应用调优** - 调整连接池大小和超时时间
|
||||
4. **Nginx 优化** - 配置缓存和压缩
|
||||
|
||||
### **扩展配置:**
|
||||
|
||||
1. **HTTPS 配置** - 添加 SSL 证书支持
|
||||
2. **域名配置** - 绑定自定义域名
|
||||
3. **备份策略** - 配置数据库自动备份
|
||||
4. **日志收集** - 集成 ELK 或其他日志系统
|
||||
|
||||
## 🔄 **版本更新**
|
||||
|
||||
### **零停机更新:**
|
||||
|
||||
```bash
|
||||
# 构建新版本
|
||||
./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
|
||||
```
|
||||
|
||||
### **回滚操作:**
|
||||
|
||||
```bash
|
||||
# 回滚到指定版本
|
||||
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 访问
|
||||
- ✅ 确认服务器资源充足
|
||||
Reference in New Issue
Block a user