智慧水务管理系统 - 精河县供水工程综合管理平台

生产环境部署指南

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

服务器配置要求

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

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

配置项	要求
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 文件：

cp .env.example .env

必须修改的配置：

# 数据库
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: 执行初始化脚本

# 以 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 公钥

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

步骤 3: 上传代码

# 在服务器执行
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  # 编辑环境变量

应用部署

首次部署

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

更新部署

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 自动部署

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

HTTPS 配置

首次申请证书

# 安装 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 点检查），也可手动执行：

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

手动续期：

sudo certbot renew --dry-run
sudo certbot renew

验证 HTTPS

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

监控告警

部署监控栈

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

浏览器打开 http://your-server-ip:3000（生产环境建议配置 Nginx 反向代理 + HTTPS）
默认账号：admin / admin（首次登录后修改）
数据源已自动配置（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：

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

日志收集

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

cd /opt/water-management

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

组件说明

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

在 Grafana 中查看日志

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

日志保留策略

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

数据库备份策略

备份方式

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

手动备份

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

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

数据库恢复

# 恢复最近备份
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 中配置：

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

运维手册

常用命令

# ===== 服务管理 =====
# 查看所有服务状态
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

扩缩容

# 水平扩展应用实例（需要负载均衡器）
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

证书管理

# 查看证书过期时间
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

故障排查

服务无法启动

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

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

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

数据库连接问题

# 检查 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;"

内存不足

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

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

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

磁盘空间不足

# 查看磁盘使用
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 连接问题

# 检查 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	指标查询（仅本地）

安全建议

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

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

README.md 13KB Vēsture Neapstrādāts

生产环境部署指南

目录

服务器配置要求

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

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

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

前置准备

1. 域名配置

2. 环境变量

3. SSL 证书

服务器初始化

步骤 1: 执行初始化脚本

步骤 2: 配置 SSH 公钥

步骤 3: 上传代码

应用部署

首次部署

更新部署

使用 CI/CD 自动部署

HTTPS 配置

首次申请证书

自动续期

验证 HTTPS

监控告警

部署监控栈

组件说明

访问 Grafana

告警规则

企业微信告警配置

日志收集

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

组件说明

在 Grafana 中查看日志

日志保留策略

数据库备份策略

备份方式

手动备份

数据库恢复

远程备份（MinIO/S3）

运维手册

常用命令

扩缩容

证书管理

故障排查

服务无法启动

数据库连接问题

内存不足

磁盘空间不足

MQTT 连接问题

附录

目录结构

端口清单

安全建议

README.md 13KB

Vēsture Neapstrādāts