tyapi-server/docs/开始指南/生产环境部署指南.md

# 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 访问
-   ✅ 确认服务器资源充足