# 生产环境部署指南

> 智慧水务管理系统 - 生产环境完整部署文档

---

## 目录

1. [服务器配置要求](#服务器配置要求)
2. [前置准备](#前置准备)
3. [服务器初始化](#服务器初始化)
4. [应用部署](#应用部署)
5. [HTTPS 配置](#https-配置)
6. [监控告警](#监控告警)
7. [日志收集](#日志收集)
8. [数据库备份策略](#数据库备份策略)
9. [运维手册](#运维手册)
10. [故障排查](#故障排查)

---

## 服务器配置要求

### 最低配置（小规模部署，≤500 设备）

| 配置项 | 要求 |
|--------|------|
| CPU | 4 核 |
| 内存 | 8 GB |
| 系统盘 | 100 GB SSD |
| 数据盘 | 200 GB SSD |
| 网络 | 10 Mbps |
| 系统 | Ubuntu 22.04 LTS / CentOS 8+ |

### 推荐配置（中等规模，500-5000 设备）

| 配置项 | 要求 |
|--------|------|
| CPU | 8 核 |
| 内存 | 16 GB |
| 系统盘 | 100 GB SSD |
| 数据盘 | 500 GB SSD |
| 网络 | 100 Mbps |
| 系统 | Ubuntu 22.04 LTS |

### 高可用配置（大规模，>5000 设备）

| 配置项 | 要求 |
|--------|------|
| 应用服务器 | 2+ 台，8C16G，负载均衡 |
| 数据库 | 主从架构，8C32G |
| Redis | 哨兵/集群模式 |
| Kafka | 3 节点集群 |
| 存储 | MinIO 分布式或云存储 |

---

## 前置准备

### 1. 域名配置

- 准备主域名（如 `water.example.com`）用于 Web 访问
- 准备 MQTT 域名（如 `mqtt.example.com`）用于设备接入
- 配置 DNS A 记录指向服务器 IP

### 2. 环境变量

复制并编辑 `.env` 文件：

```bash
cp .env.example .env
```

**必须修改的配置：**

```bash
# 数据库
POSTGRES_DB=water_management
POSTGRES_USER=water
POSTGRES_PASSWORD=<强密码>

# Redis
REDIS_PASSWORD=<强密码>

# EMQX MQTT
EMQX_ADMIN_USER=admin
EMQX_ADMIN_PASSWORD=<强密码>

# MinIO
MINIO_USER=minioadmin
MINIO_PASSWORD=<强密码>

# 镜像标签
IMAGE_TAG=latest

# 域名
DOMAIN=water.example.com
```

### 3. SSL 证书

准备 Let's Encrypt 证书（服务器初始化后可自动申请）。

---

## 服务器初始化

### 步骤 1: 执行初始化脚本

```bash
# 以 root 或 sudo 执行
sudo chmod +x deploy/production/server-setup.sh
sudo deploy/production/server-setup.sh
```

该脚本将自动完成：
- ✅ 系统包更新
- ✅ Docker & Docker Compose 安装
- ✅ 防火墙配置（仅开放 22/80/443/1883）
- ✅ SSH 安全加固
- ✅ Fail2Ban 防暴力破解
- ✅ 创建部署用户 (`deploy`)
- ✅ 创建目录结构
- ✅ 内核参数优化
- ✅ 定时任务配置

### 步骤 2: 配置 SSH 公钥

```bash
# 在本地机器执行
ssh-copy-id deploy@your-server-ip
```

### 步骤 3: 上传代码

```bash
# 在服务器执行
sudo -u deploy git clone http://git.xayunmei.com/bot_ym/water-management-system.git /opt/water-management
cd /opt/water-management
cp .env.example .env
vim .env  # 编辑环境变量
```

---

## 应用部署

### 首次部署

```bash
cd /opt/water-management

# 构建镜像（如使用远程镜像仓库可跳过）
docker compose build

# 启动所有服务
docker compose \
  -f docker-compose.yml \
  -f deploy/production/docker-compose.override.yml \
  up -d

# 查看服务状态
docker compose -f docker-compose.yml -f deploy/production/docker-compose.override.yml ps

# 查看日志
docker compose logs -f
```

### 更新部署

```bash
cd /opt/water-management

# 拉取最新代码
git pull origin master

# 拉取最新镜像
docker compose -f docker-compose.yml -f deploy/production/docker-compose.override.yml pull

# 滚动更新
docker compose -f docker-compose.yml -f deploy/production/docker-compose.override.yml up -d --remove-orphans

# 清理旧镜像
docker image prune -f
```

### 使用 CI/CD 自动部署

```bash
# 通过 scripts/deploy.sh 脚本
./scripts/deploy.sh \
  --env production \
  --host your-server-ip \
  --user deploy \
  --tag latest
```

---

## HTTPS 配置

### 首次申请证书

```bash
# 安装 certbot
sudo apt install certbot

# 确保 Nginx 已启动且 80 端口可访问
# 申请证书（替换域名和邮箱）
sudo certbot certonly --webroot \
  -w /var/www/certbot \
  -d water.example.com \
  --email admin@example.com \
  --agree-tos \
  --no-eff-email
```

### 自动续期

证书续期脚本已配置为定时任务（每天凌晨 3 点检查），也可手动执行：

```bash
sudo deploy/production/nginx/certbot-renew.sh
```

手动续期：

```bash
sudo certbot renew --dry-run
sudo certbot renew
```

### 验证 HTTPS

```bash
curl -I https://water.example.com
# 应返回 HTTP/2 200 及 HSTS header
```

---

## 监控告警

### 部署监控栈

```bash
cd /opt/water-management

# 启动监控组件
docker compose \
  -f deploy/production/monitoring/docker-compose.monitoring.yml \
  up -d

# 查看状态
docker compose -f deploy/production/monitoring/docker-compose.monitoring.yml ps
```

### 组件说明

| 组件 | 端口 | 用途 |
|------|------|------|
| Prometheus | 9090 | 指标收集与存储 |
| Grafana | 3000 | 可视化仪表盘 |
| Node Exporter | 9100 | 主机指标 |
| cAdvisor | 8880 | 容器指标 |
| AlertManager | 9093 | 告警管理 |
| Postgres Exporter | 9187 | PostgreSQL 指标 |
| Redis Exporter | 9121 | Redis 指标 |

### 访问 Grafana

1. 浏览器打开 `http://your-server-ip:3000`（生产环境建议配置 Nginx 反向代理 + HTTPS）
2. 默认账号：`admin` / `admin`（首次登录后修改）
3. 数据源已自动配置（Prometheus + PostgreSQL）

### 告警规则

已配置以下告警（详见 `monitoring/alert_rules.yml`）：

| 告警名称 | 触发条件 | 严重级别 |
|----------|----------|----------|
| HighCPUUsage | CPU > 80% 持续 5 分钟 | Warning |
| CriticalCPUUsage | CPU > 95% 持续 2 分钟 | Critical |
| HighMemoryUsage | 内存 > 85% 持续 5 分钟 | Warning |
| HighDiskUsage | 磁盘 > 90% 持续 5 分钟 | Critical |
| ServiceDown | 服务宕机 1 分钟 | Critical |
| ServiceSlowResponse | 响应时间 > 5s 持续 5 分钟 | Warning |
| HighErrorRate | 5xx 错误率 > 5% | Critical |
| PostgresHighConnections | 连接数 > 80% | Warning |

### 企业微信告警配置

编辑 `monitoring/alertmanager.yml`，配置 Webhook：

```yaml
receivers:
  - name: 'wecom'
    webhook_configs:
      - url: 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=YOUR_KEY'
```

---

## 日志收集

### 部署日志栈（Loki 轻量方案）

```bash
cd /opt/water-management

docker compose \
  -f deploy/production/logging/docker-compose.logging.yml \
  up -d
```

### 组件说明

| 组件 | 端口 | 用途 |
|------|------|------|
| Loki | 3100 | 日志聚合存储 |
| Promtail | 9080 | 日志收集代理 |

### 在 Grafana 中查看日志

1. 打开 Grafana → Explore
2. 选择 Loki 数据源
3. 使用 LogQL 查询：
   ```
   {container="wm-gateway"} |= "error"
   {service="revenue"} | json | level="ERROR"
   ```

### 日志保留策略

- 日志保留 30 天
- 自动清理过期日志

---

## 数据库备份策略

### 备份方式

| 类型 | 频率 | 保留时间 | 说明 |
|------|------|----------|------|
| 每日备份 | 每天凌晨 2 点 | 7 天 | 全量 pg_dump |
| 每周备份 | 每周日凌晨 | 4 周 | 全量 pg_dump |
| 每月备份 | 每月 1 号 | 12 个月 | 全量 pg_dump |

### 手动备份

```bash
# 执行备份
deploy/production/backup/backup-db.sh

# 列出备份
deploy/production/backup/restore-db.sh --list
```

### 数据库恢复

```bash
# 恢复最近备份
deploy/production/backup/restore-db.sh --latest

# 恢复指定日期
deploy/production/backup/restore-db.sh --date 2026-06-15

# 恢复指定文件
deploy/production/backup/restore-db.sh --file /opt/water-management/backups/daily/wm_water_management_20260615_020000.sql.gz
```

### 远程备份（MinIO/S3）

在 `.env` 中配置：

```bash
S3_ENABLED=true
S3_BUCKET=water-backups
S3_ENDPOINT=http://minio:9000
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=<密码>
```

---

## 运维手册

### 常用命令

```bash
# ===== 服务管理 =====
# 查看所有服务状态
docker compose -f docker-compose.yml -f deploy/production/docker-compose.override.yml ps

# 重启单个服务
docker compose -f docker-compose.yml -f deploy/production/docker-compose.override.yml restart gateway

# 查看服务日志
docker compose logs -f --tail=100 gateway

# 进入容器
docker exec -it wm-gateway bash

# ===== 数据库 =====
# 连接数据库
docker exec -it wm-postgres psql -U water -d water_management

# 查看活跃连接
docker exec -it wm-postgres psql -U water -c "SELECT count(*) FROM pg_stat_activity WHERE state='active';"

# ===== Redis =====
# 查看 Redis 信息
docker exec -it wm-redis redis-cli -a <密码> info

# ===== 资源监控 =====
# 查看容器资源使用
docker stats --no-stream

# 查看磁盘使用
df -h
docker system df
```

### 扩缩容

```bash
# 水平扩展应用实例（需要负载均衡器）
docker compose -f docker-compose.yml -f deploy/production/docker-compose.override.yml up -d --scale gateway=2

# 修改资源限制
# 编辑 deploy/production/docker-compose.override.yml 中的 deploy.resources
```

### 证书管理

```bash
# 查看证书过期时间
sudo openssl x509 -enddate -noout -in /etc/letsencrypt/live/water.example.com/fullchain.pem

# 手动续期
sudo certbot renew

# 重新申请
sudo certbot certonly --webroot -w /var/www/certbot -d water.example.com --force-renewal
```

---

## 故障排查

### 服务无法启动

```bash
# 查看详细日志
docker compose logs --tail=200 <service-name>

# 检查端口冲突
ss -tlnp | grep <port>

# 检查资源
docker stats --no-stream
df -h
free -h
```

### 数据库连接问题

```bash
# 检查 PostgreSQL 是否运行
docker exec -it wm-postgres pg_isready

# 检查连接数
docker exec -it wm-postgres psql -U water -c "SELECT count(*) FROM pg_stat_activity;"

# 检查慢查询
docker exec -it wm-postgres psql -U water -c "SELECT pid, now()-query_start AS duration, query FROM pg_stat_activity WHERE state='active' ORDER BY duration DESC LIMIT 5;"
```

### 内存不足

```bash
# 查看内存使用
docker stats --no-stream --format "table {{.Name}}\t{{.MemUsage}}\t{{.MemPerc}}"

# 清理无用镜像和容器
docker system prune -a --volumes

# 调整 JVM 内存参数
# 编辑 docker-compose.override.yml 中的 JAVA_OPTS
```

### 磁盘空间不足

```bash
# 查看磁盘使用
df -h
du -sh /opt/water-management/*
docker system df -v

# 清理旧备份
find /opt/water-management/backups -name "*.sql.gz" -mtime +30 -delete

# 清理 Docker
docker system prune -f
docker volume prune -f
```

### MQTT 连接问题

```bash
# 检查 EMQX 状态
docker exec -it wm-emqx emqx status

# 查看 EMQX 日志
docker logs wm-emqx

# 测试 MQTT 连接
mosquitto_pub -h localhost -p 1883 -t "test" -m "hello"
```

---

## 附录

### 目录结构

```
/opt/water-management/
├── .env                           # 环境变量
├── docker-compose.yml             # 基础编排
├── deploy/
│   └── production/
│       ├── docker-compose.override.yml  # 生产覆盖配置
│       ├── nginx/
│       │   ├── nginx.conf               # Nginx 配置
│       │   └── certbot-renew.sh         # 证书续期
│       ├── backup/
│       │   ├── backup-db.sh             # 数据库备份
│       │   └── restore-db.sh            # 数据库恢复
│       ├── monitoring/
│       │   ├── docker-compose.monitoring.yml
│       │   ├── prometheus.yml
│       │   ├── alert_rules.yml
│       │   └── grafana/
│       ├── logging/
│       │   ├── docker-compose.logging.yml
│       │   ├── loki-config.yml
│       │   └── promtail-config.yml
│       ├── server-setup.sh              # 服务器初始化
│       └── README.md                    # 本文档
├── backups/                       # 数据库备份
│   ├── daily/
│   ├── weekly/
│   └── monthly/
└── logs/                          # 应用日志
```

### 端口清单

| 服务 | 端口 | 用途 |
|------|------|------|
| Nginx HTTP | 80 | Web 访问（跳转 HTTPS） |
| Nginx HTTPS | 443 | Web 安全访问 |
| MQTT | 1883 | 物联网设备接入 |
| Gateway | 8080 | API 网关（内部） |
| PostgreSQL | 5432 | 数据库（仅本地） |
| Redis | 6379 | 缓存（仅本地） |
| Grafana | 3000 | 监控面板（仅本地） |
| Prometheus | 9090 | 指标查询（仅本地） |

### 安全建议

1. **定期更新**：每月执行系统更新和 Docker 镜像更新
2. **密码管理**：使用强密码，定期轮换
3. **访问控制**：生产环境仅通过 HTTPS 访问，内部端口不对外开放
4. **备份验证**：每月至少恢复一次备份进行验证
5. **日志审计**：定期检查访问日志和错误日志
6. **证书监控**：确保证书自动续期正常

---

*文档版本: 1.0 | 最后更新: 2026-06-16*