docs: reorganize documentation structure

2026-03-05 13:48:13 +08:00
parent 349b0a754f
commit 104fa7e7c8
59 changed files with 22859 additions and 916 deletions
@@ -0,0 +1,861 @@
+# 部署运维文档
+
+> 文档编号: GYM-OPS-DEPLOY-001  
+> 版本: v1.0  
+> 日期: 2026-03-04  
+> 作者: 张翔  
+> 状态: 初稿
+
+---
+
+## 文档修订历史
+
+| 版本 | 日期 | 作者 | 修订内容 |
+| ---- | ---------- | ---- | ------------------ |
+| v1.0 | 2026-03-04 | 张翔 | 创建部署运维文档 |
+
+---
+
+## 参考文档
+
+- 《健身房管理系统技术架构设计文档》 GYM-HLD-TECH-001
+- 《健身房管理系统响应式编程规范文档》 GYM-STD-REACTIVE-001
+- Docker 官方文档
+- Docker Compose 官方文档
+
+---
+
+## 一、部署架构
+
+### 1.1 部署拓扑
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    部署架构拓扑                                    │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                 │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │ 用户层                                                 │   │
+│  ├─────────────────────────────────────────────────────────┤   │
+│  │ • 会员小程序  • 教练端App  • 管理后台PC        │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                              │                                       │
+│                              ▼                                       │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │ 负载均衡层 (Nginx)                                 │   │
+│  ├─────────────────────────────────────────────────────────┤   │
+│  │ • 负载均衡  • SSL 终止  • 静态资源  • 限流    │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                              │                                       │
+│                              ▼                                       │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │ 应用层 (Docker Compose)                             │   │
+│  ├─────────────────────────────────────────────────────────┤   │
+│  │ • gym-manage (应用)  • postgres (数据库)               │   │
+│  │ • redis (缓存)  • rabbitmq (消息队列)                │   │
+│  │ • elasticsearch (搜索引擎)  • prometheus (监控)          │   │
+│  │ • grafana (可视化)  • kibana (日志可视化)             │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                              │                                       │
+│                              ▼                                       │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │ 监控层 (Prometheus + Grafana)                        │   │
+│  ├─────────────────────────────────────────────────────────┤   │
+│  │ • 指标采集  • 告警规则  • 可视化仪表板          │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 1.2 服务器配置
+
+#### 1.2.1 生产环境配置
+
+| 组件 | CPU | 内存 | 磁盘 | 用途 |
+|------|------|------|------|
+| **应用服务器** | 4 核 | 8GB | 100GB | 运行应用 |
+| **数据库服务器** | 8 核 | 16GB | 500GB | PostgreSQL |
+| **缓存服务器** | 2 核 | 4GB | 50GB | Redis |
+| **消息队列服务器** | 2 核 | 4GB | 100GB | RabbitMQ |
+| **搜索服务器** | 4 核 | 8GB | 200GB | Elasticsearch |
+| **监控服务器** | 2 核 | 4GB | 50GB | Prometheus + Grafana |
+
+**推荐配置**：
+- 初期：应用 + 数据库 + 缓存部署在同一台服务器（8 核 16GB）
+- 中期：应用独立部署（4 核 8GB），数据库独立部署（8 核 16GB）
+- 长期：各组件独立部署，提高可用性
+
+#### 1.2.2 开发环境配置
+
+| 组件 | CPU | 内存 | 磁盘 | 用途 |
+|------|------|------|------|
+| **开发服务器** | 4 核 | 8GB | 100GB | 开发测试 |
+
+---
+
+## 二、环境准备
+
+### 2.1 系统要求
+
+#### 2.1.1 操作系统
+
+- **推荐**：Ubuntu 20.04 LTS / 22.04 LTS
+- **兼容**：CentOS 7+ / Debian 10+
+- **内核版本**：>= 4.15
+
+#### 2.1.2 软件依赖
+
+| 软件 | 版本 | 用途 |
+|------|------|------|
+| **Docker** | 24.x+ | 容器化部署 |
+| **Docker Compose** | 2.20.x+ | 容器编排 |
+| **Git** | 2.30+ | 版本控制 |
+| **JDK** | 17+ | 运行环境 |
+| **Maven** | 3.9.x+ | 项目构建 |
+
+### 2.2 环境安装
+
+#### 2.2.1 安装 Docker
+
+```bash
+# Ubuntu/Debian
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+
+# 启动 Docker 服务
+sudo systemctl start docker
+sudo systemctl enable docker
+
+# 验证安装
+docker --version
+docker info
+```
+
+#### 2.2.2 安装 Docker Compose
+
+```bash
+# 下载 Docker Compose
+sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
+
+# 添加执行权限
+sudo chmod +x /usr/local/bin/docker-compose
+
+# 验证安装
+docker-compose --version
+```
+
+#### 2.2.3 安装 JDK
+
+```bash
+# Ubuntu/Debian
+sudo apt update
+sudo apt install -y openjdk-17-jdk
+
+# 验证安装
+java -version
+```
+
+#### 2.2.4 安装 Maven
+
+```bash
+# 下载 Maven
+wget https://dlcdn.apache.org/maven/maven-3/3.9.5/binaries/apache-maven-3.9.5-bin.tar.gz
+
+# 解压
+tar -xzf apache-maven-3.9.5-bin.tar.gz
+
+# 移动到 /opt
+sudo mv apache-maven-3.9.5 /opt/maven
+
+# 配置环境变量
+echo 'export PATH=/opt/maven/bin:$PATH' >> ~/.bashrc
+source ~/.bashrc
+
+# 验证安装
+mvn -version
+```
+
+---
+
+## 三、部署流程
+
+### 3.1 代码部署
+
+#### 3.1.1 克隆代码
+
+```bash
+# 克隆代码仓库
+git clone <repository-url>
+cd gym-manage
+
+# 查看分支
+git branch -a
+
+# 切换到生产分支
+git checkout production
+
+# 拉取最新代码
+git pull origin production
+```
+
+#### 3.1.2 配置环境变量
+
+```bash
+# 复制环境变量模板
+cp .env.example .env
+
+# 编辑环境变量
+vim .env
+```
+
+**.env 文件示例**：
+
+```bash
+# 数据库配置
+DB_USERNAME=postgres
+DB_PASSWORD=your-strong-password
+
+# Redis 配置
+REDIS_PASSWORD=your-strong-password
+
+# RabbitMQ 配置
+MQ_USERNAME=admin
+MQ_PASSWORD=your-strong-password
+
+# Grafana 配置
+GRAFANA_USER=admin
+GRAFANA_PASSWORD=your-strong-password
+
+# Spring 配置
+SPRING_PROFILES_ACTIVE=prod
+
+# JVM 配置 (响应式编程最佳实践)
+JAVA_OPTS=-Xms512m -Xmx1024m -XX:+UseZGC -XX:ZAllocationSpikeTolerance=5 -XX:+UnlockExperimentalVMOptions -XX:+UseTransparentHugePages -XX:+AlwaysPreTouch
+```
+
+#### 3.1.3 构建镜像
+
+```bash
+# 构建应用镜像
+docker-compose build gym-manage
+
+# 查看镜像
+docker images | grep gym-manage
+```
+
+### 3.2 服务部署
+
+#### 3.2.1 启动所有服务
+
+```bash
+# 启动所有服务
+docker-compose up -d
+
+# 查看服务状态
+docker-compose ps
+
+# 查看日志
+docker-compose logs -f gym-manage
+```
+
+#### 3.2.2 启动单个服务
+
+```bash
+# 启动数据库
+docker-compose up -d postgres
+
+# 启动应用
+docker-compose up -d gym-manage
+
+# 查看应用日志
+docker-compose logs -f gym-manage
+```
+
+#### 3.2.3 健康检查
+
+```bash
+# 检查应用健康状态
+curl http://localhost:8080/actuator/health
+
+# 检查数据库连接
+docker-compose exec postgres pg_isready -U postgres
+
+# 检查 Redis 连接
+docker-compose exec redis redis-cli ping
+
+# 检查 RabbitMQ 连接
+curl http://localhost:15672/api/overview -u admin:admin123
+```
+
+### 3.3 数据库初始化
+
+#### 3.3.1 创建数据库
+
+```bash
+# 连接到 PostgreSQL
+docker-compose exec postgres psql -U postgres
+
+# 创建数据库
+CREATE DATABASE gym_manage;
+
+# 创建用户
+CREATE USER gym_manage WITH PASSWORD 'your-password';
+
+# 授权
+GRANT ALL PRIVILEGES ON DATABASE gym_manage TO gym_manage;
+
+# 退出
+\q
+```
+
+#### 3.3.2 执行初始化脚本
+
+```bash
+# 执行初始化脚本
+docker-compose exec -T postgres psql -U postgres -d gym_manage < sql/init.sql
+```
+
+---
+
+## 四、更新部署
+
+### 4.1 代码更新
+
+#### 4.1.1 拉取最新代码
+
+```bash
+# 拉取最新代码
+git pull origin production
+
+# 查看变更
+git log --oneline -5
+```
+
+#### 4.1.2 重新构建
+
+```bash
+# 停止服务
+docker-compose down
+
+# 重新构建镜像
+docker-compose build gym-manage
+
+# 启动服务
+docker-compose up -d
+```
+
+### 4.2 滚动更新
+
+#### 4.2.1 零停机更新
+
+```bash
+# 启动新实例
+docker-compose up -d --scale gym-manage=2
+
+# 等待新实例就绪
+sleep 30
+
+# 停止旧实例
+docker-compose up -d --scale gym-manage=1
+```
+
+### 4.3 回滚部署
+
+#### 4.3.1 快速回滚
+
+```bash
+# 回滚到上一个版本
+git checkout HEAD~1
+
+# 重新构建
+docker-compose build gym-manage
+
+# 启动服务
+docker-compose up -d
+```
+
+#### 4.3.2 使用 Docker 镜像回滚
+
+```bash
+# 查看镜像历史
+docker images | grep gym-manage
+
+# 使用上一个镜像
+docker-compose up -d --no-deps gym-manage
+```
+
+---
+
+## 五、监控运维
+
+### 5.1 监控体系
+
+#### 5.1.1 Prometheus 监控
+
+**访问地址**：http://your-server:9090
+
+**主要功能**：
+- 指标采集
+- 数据存储
+- 告警规则
+- 查询接口
+
+#### 5.1.2 Grafana 可视化
+
+**访问地址**：http://your-server:3000
+
+**默认账号**：
+- 用户名：admin
+- 密码：admin123
+
+**主要功能**：
+- 数据可视化
+- 仪表板配置
+- 告警通知
+- 用户管理
+
+#### 5.1.3 Kibana 日志可视化
+
+**访问地址**：http://your-server:5601
+
+**主要功能**：
+- 日志查询
+- 日志分析
+- 可视化图表
+- 告警配置
+
+### 5.2 日志管理
+
+#### 5.2.1 应用日志
+
+```bash
+# 查看实时日志
+docker-compose logs -f gym-manage
+
+# 查看最近 100 行日志
+docker-compose logs --tail=100 gym-manage
+
+# 查看特定时间的日志
+docker-compose logs --since 2024-01-01T00:00:00 gym-manage
+```
+
+#### 5.2.2 日志文件
+
+```bash
+# 查看日志文件
+tail -f logs/gym-manage.log
+
+# 查看错误日志
+grep ERROR logs/gym-manage.log
+
+# 统计错误数量
+grep -c ERROR logs/gym-manage.log
+```
+
+### 5.3 告警配置
+
+#### 5.3.1 告警规则
+
+**文件位置**：`monitoring/alerts.yml`
+
+**告警类型**：
+- 高错误率
+- 高响应时间
+- 高内存使用率
+- 数据库连接池耗尽
+- 缓存命中率低
+
+#### 5.3.2 告警通知
+
+**通知方式**：
+- 邮件通知
+- 钉钉通知
+- 企业微信通知
+- 短信通知
+
+**配置示例**：
+
+```yaml
+alertmanager:
+  receivers:
+    - name: 'email'
+      email_configs:
+        - to: 'your-email@example.com'
+          from: 'alertmanager@example.com'
+          smarthost: 'smtp.example.com:587'
+          auth_username: 'your-email@example.com'
+          auth_password: 'your-password'
+```
+
+---
+
+## 六、性能优化
+
+### 6.1 应用优化
+
+#### 6.1.1 JVM 参数调优
+
+```bash
+# 生产环境推荐参数 (响应式编程最佳实践)
+JAVA_OPTS=-Xms1024m -Xmx2048m -XX:+UseZGC -XX:ZAllocationSpikeTolerance=5 -XX:+UnlockExperimentalVMOptions -XX:+UseTransparentHugePages -XX:+AlwaysPreTouch -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=/app/logs/heapdump.hprof
+```
+
+**参数说明**：
+- `-Xms`：初始堆内存大小
+- `-Xmx`：最大堆内存大小
+- `-XX:+UseZGC`：使用 ZGC 垃圾回收器（响应式编程推荐）
+- `-XX:ZAllocationSpikeTolerance`：分配峰值容忍度
+- `-XX:+UnlockExperimentalVMOptions`：解锁实验性选项
+- `-XX:+UseTransparentHugePages`：使用透明大页
+- `-XX:+AlwaysPreTouch`：预分配内存
+- `-XX:+HeapDumpOnOutOfMemoryError`：内存溢出时生成堆转储
+- `-XX:HeapDumpPath`：堆转储文件路径
+
+**ZGC 优势**：
+- 低延迟：GC 暂停时间通常 < 10ms
+- 高吞吐量：适合响应式编程的高并发场景
+- 大堆支持：支持 TB 级堆内存
+- 自适应：自动调整 GC 参数
+
+#### 6.1.2 连接池调优
+
+```yaml
+# application-prod.yml (响应式编程最佳实践)
+spring:
+  r2dbc:
+    pool:
+      initial-size: 5          # 初始连接数（响应式编程推荐较少连接）
+      max-size: 20            # 最大连接数（响应式编程推荐较少连接）
+      max-idle-time: 30m      # 最大空闲时间
+      max-life-time: 1h       # 最大生命周期
+      acquire-timeout: 10s     # 获取连接超时时间（响应式编程推荐较长超时）
+      max-create-connection-time: 30s  # 创建连接最大时间
+      max-validation-time: 5s  # 验证连接最大时间
+```
+
+**连接池配置说明**：
+- 响应式编程使用较少的连接数（5-20）即可支持高并发
+- 连接获取超时时间设置为 10s，避免快速失败
+- 使用连接池复用，减少连接创建开销
+
+### 6.2 数据库优化
+
+#### 6.2.1 PostgreSQL 配置（响应式编程优化）
+
+```bash
+# postgresql.conf (响应式编程最佳实践)
+# 内存配置
+shared_buffers = 512MB                    # 共享缓冲区（响应式编程推荐较大值）
+effective_cache_size = 2GB                # 有效缓存大小
+maintenance_work_mem = 128MB              # 维护工作内存
+work_mem = 32MB                          # 工作内存（响应式编程推荐较大值）
+
+# WAL 配置
+wal_buffers = 64MB                       # WAL 缓冲区
+min_wal_size = 2GB                       # 最小 WAL 大小
+max_wal_size = 8GB                       # 最大 WAL 大小
+checkpoint_completion_target = 0.9         # 检查点完成目标
+
+# 并发配置
+max_connections = 200                     # 最大连接数（响应式编程推荐较少连接）
+max_worker_processes = 8                  # 最大工作进程数
+max_parallel_workers_per_gather = 4       # 每个查询的最大并行工作进程数
+max_parallel_workers = 8                  # 最大并行工作进程数
+
+# IO 配置
+random_page_cost = 1.1                   # 随机页面成本（SSD 优化）
+effective_io_concurrency = 300           # 有效 IO 并发数（SSD 优化）
+max_io_concurrency = 200                  # 最大 IO 并发数
+
+# 查询优化
+default_statistics_target = 100           # 默认统计目标
+from_collapse_limit = 8                   # FROM 子句折叠限制
+join_collapse_limit = 8                   # JOIN 子句折叠限制
+
+# 日志配置
+log_min_duration_statement = 1000         # 记录执行时间超过 1s 的语句
+log_line_prefix = '%t [%p]: [%l-1] user=%u,db=%d,app=%a,client=%h '  # 日志前缀
+log_checkpoints = on                      # 记录检查点
+log_connections = on                      # 记录连接
+log_disconnections = on                   # 记录断开连接
+log_lock_waits = on                      # 记录锁等待
+```
+
+#### 6.2.2 索引优化
+
+```sql
+-- 查看索引使用情况
+SELECT schemaname, tablename, attname, n_distinct, correlation
+FROM pg_stats
+WHERE schemaname = 'public'
+ORDER BY correlation DESC;
+
+-- 查看慢查询
+SELECT query, mean_exec_time, calls
+FROM pg_stat_statements
+ORDER BY mean_exec_time DESC
+LIMIT 10;
+```
+
+### 6.3 缓存优化
+
+#### 6.3.1 Redis 配置
+
+```bash
+# redis.conf
+maxmemory 2gb
+maxmemory-policy allkeys-lru
+save 900 1
+save 300 10
+save 60 10000
+```
+
+**参数说明**：
+- `maxmemory`：最大内存使用量
+- `maxmemory-policy`：内存淘汰策略
+- `save`：RDB 持久化策略
+
+---
+
+## 七、故障排查
+
+### 7.1 常见问题
+
+#### 7.1.1 应用启动失败
+
+**症状**：应用无法启动
+
+**排查步骤**：
+
+```bash
+# 查看应用日志
+docker-compose logs gym-manage
+
+# 检查配置文件
+cat application-prod.yml
+
+# 检查环境变量
+docker-compose config
+
+# 检查数据库连接
+docker-compose exec postgres pg_isready -U postgres
+```
+
+**常见原因**：
+- 数据库连接失败
+- 配置文件错误
+- 端口冲突
+- 内存不足
+
+#### 7.1.2 数据库连接失败
+
+**症状**：应用无法连接数据库
+
+**排查步骤**：
+
+```bash
+# 检查数据库状态
+docker-compose ps postgres
+
+# 查看数据库日志
+docker-compose logs postgres
+
+# 测试数据库连接
+docker-compose exec postgres psql -U postgres -d gym_manage -c "SELECT 1;"
+
+# 检查网络连接
+docker-compose exec gym-manage ping postgres
+```
+
+**常见原因**：
+- 数据库未启动
+- 网络不通
+- 用户名密码错误
+- 数据库不存在
+
+#### 7.1.3 性能下降
+
+**症状**：响应时间变长
+
+**排查步骤**：
+
+```bash
+# 查看应用日志
+docker-compose logs gym-manage | grep "Slow query"
+
+# 查看数据库慢查询
+docker-compose exec postgres psql -U postgres -d gym_manage -c "SELECT * FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;"
+
+# 查看系统资源
+top
+htop
+
+# 查看数据库连接数
+docker-compose exec postgres psql -U postgres -d gym_manage -c "SELECT count(*) FROM pg_stat_activity;"
+```
+
+**常见原因**：
+- 慢查询
+- 数据库连接池耗尽
+- 缓存命中率低
+- 系统资源不足
+
+### 7.2 应急处理
+
+#### 7.2.1 重启服务
+
+```bash
+# 重启应用
+docker-compose restart gym-manage
+
+# 重启数据库
+docker-compose restart postgres
+
+# 重启所有服务
+docker-compose restart
+```
+
+#### 7.2.2 回滚版本
+
+```bash
+# 回滚到上一个版本
+git checkout HEAD~1
+
+# 重新构建
+docker-compose build gym-manage
+
+# 启动服务
+docker-compose up -d
+```
+
+#### 7.2.3 扩容
+
+```bash
+# 增加应用实例
+docker-compose up -d --scale gym-manage=2
+
+# 增加数据库资源
+docker-compose up -d --scale postgres=2
+```
+
+---
+
+## 八、备份恢复
+
+### 8.1 数据备份
+
+#### 8.1.1 数据库备份
+
+```bash
+# 备份数据库
+docker-compose exec postgres pg_dump -U postgres gym_manage > backup/gym_manage_$(date +%Y%m%d_%H%M%S).sql
+
+# 压缩备份文件
+gzip backup/gym_manage_$(date +%Y%m%d_%H%M%S).sql
+```
+
+#### 8.1.2 定时备份
+
+```bash
+# 添加 crontab 任务
+crontab -e
+
+# 每天凌晨 2 点备份数据库
+0 2 * * * docker-compose exec -T postgres pg_dump -U postgres gym_manage > backup/gym_manage_$(date +\%Y\%m\%d_\%H\%M\%S).sql
+
+# 每周日凌晨 3 点清理 7 天前的备份
+0 3 * * 0 find backup -name "gym_manage_*.sql" -mtime +7 -delete
+```
+
+### 8.2 数据恢复
+
+#### 8.2.1 数据库恢复
+
+```bash
+# 停止应用
+docker-compose stop gym-manage
+
+# 恢复数据库
+docker-compose exec -T postgres psql -U postgres gym_manage < backup/gym_manage_20240101_020000.sql
+
+# 启动应用
+docker-compose start gym-manage
+```
+
+---
+
+## 九、安全加固
+
+### 9.1 网络安全
+
+#### 9.1.1 防火墙配置
+
+```bash
+# 配置防火墙
+sudo ufw allow 22/tcp    # SSH
+sudo ufw allow 80/tcp    # HTTP
+sudo ufw allow 443/tcp   # HTTPS
+sudo ufw enable
+```
+
+#### 9.1.2 SSL 证书
+
+```bash
+# 使用 Let's Encrypt 获取免费 SSL 证书
+sudo apt install certbot
+sudo certbot certonly --standalone -d your-domain.com
+
+# 配置 Nginx SSL
+vim nginx/nginx.conf
+```
+
+### 9.2 应用安全
+
+#### 9.2.1 敏感数据加密
+
+```bash
+# 配置环境变量
+export DB_PASSWORD=$(openssl rand -base64 32)
+export REDIS_PASSWORD=$(openssl rand -base64 32)
+export MQ_PASSWORD=$(openssl rand -base64 32)
+```
+
+#### 9.2.2 权限控制
+
+```yaml
+# application-prod.yml
+spring:
+  security:
+    user:
+      name: admin
+      password: ${ADMIN_PASSWORD}
+      roles: ADMIN
+```
+
+---
+
+## 十、总结
+
+### 10.1 部署要点
+
+1. ✅ 使用 Docker Compose 一键部署
+2. ✅ 配置健康检查和自动重启
+3. ✅ 完善的监控和告警体系
+4. ✅ 定期备份数据
+5. ✅ 安全加固和权限控制
+
+### 10.2 运维要点
+
+1. ✅ 定期查看日志和监控
+2. ✅ 及时处理告警
+3. ✅ 定期备份数据
+4. ✅ 定期更新系统和依赖
+5. ✅ 定期进行安全审计
+
+### 10.3 持续改进
+
+1. ✅ 性能监控和优化
+2. ✅ 故障复盘和改进
+3. ✅ 文档更新和维护
+4. ✅ 团队培训和知识分享
+5. ✅ 自动化运维工具开发