系统部署环境要求.md
18 KB
HaHRCS 系统部署环境要求文档
文档版本: 1.0 生成日期: 2026-01-19 系统名称: HaHRCS (华航机器人控制系统) 系统版本: 3.1.0
一、系统概述
HaHRCS 是一套企业级 AGV/AMR 机器人调度控制系统，采用前后端分离架构，支持 VDA5050 工业标准协议，实现多机器人协同调度、任务管理、地图管理等核心功能。
技术架构
- 后端: .NET 8.0 / ASP.NET Core Web API
- 前端: Vue 3.5.8 + Vite 5.4.9 + TypeScript 5.2.2
- 架构模式: DDD (领域驱动设计) + 清洁架构 + CQRS
- 部署方式: Docker Compose 容器化编排
二、硬件环境要求
2.1 最低配置要求
| 项目 | 要求 |
|---|---|
| CPU | 4 核心 (推荐 Intel i5 或同等性能) |
| 内存 | 8 GB RAM (推荐 16 GB) |
| 硬盘 | 50 GB 可用空间 (SSD 推荐) |
| 网络 | 千兆以太网 (1000 Mbps) |
2.2 推荐配置
| 项目 | 要求 |
|---|---|
| CPU | 8 核心或以上 (Intel i7/Xeon 或同等性能) |
| 内存 | 16 GB RAM 或以上 |
| 硬盘 | 100 GB 可用空间 (NVMe SSD) |
| 网络 | 千兆以太网 + 备用网卡 |
2.3 存储空间分配
| 组件 | 预估空间 |
|---|---|
| Docker 镜像 | ~2 GB |
| 数据库 (PostgreSQL) | 10-50 GB (根据业务量) |
| 日志文件 | 5-10 GB |
| 地图资源文件 | 1-5 GB |
| 系统预留 | 10 GB |
三、操作系统要求
3.1 支持的操作系统
Windows 平台
- Windows 10 专业版/企业版 (64位) - 版本 1903 或更高
- Windows 11 专业版/企业版 (64位)
- Windows Server 2019/2022 (推荐用于生产环境)
Linux 平台 (可选)
- Ubuntu 20.04 LTS / 22.04 LTS
- CentOS 7.9 / 8.x
- Debian 10/11
3.2 系统组件要求
| 组件 | 版本要求 | 说明 |
|---|---|---|
| Docker Desktop | 4.0 或以上 | Windows 环境必需 |
| Docker Engine | 20.10 或以上 | Linux 环境必需 |
| Docker Compose | 2.0 或以上 | 容器编排工具 |
| .NET Runtime | 8.0 | 非容器部署时需要 |
| Node.js | 20.x | 仅开发环境需要 |
四、网络环境要求
4.1 端口占用清单
系统运行需要以下端口，部署前请确保端口未被占用：
| 端口 | 服务 | 协议 | 说明 | 是否对外开放 |
|---|---|---|---|---|
| 5000 | 后端 API | HTTP | RESTful API 服务 | 是 |
| 8080 | 前端 Nginx | HTTP | Web 前端访问 | 是 |
| 5432 | PostgreSQL | TCP | 数据库服务 | 否 (内网) |
| 7379 | Redis | TCP | 缓存服务 | 否 (内网) |
| 5672 | RabbitMQ | AMQP | 消息队列 | 否 (内网) |
| 15672 | RabbitMQ 管理 | HTTP | 管理控制台 | 可选 |
| 1883 | EMQX MQTT | MQTT | 机器人通信 | 是 |
| 8083 | EMQX WebSocket | WS | WebSocket 连接 | 是 |
| 18083 | EMQX Dashboard | HTTP | MQTT 管理控制台 | 可选 |
4.2 网络连通性要求
内网通信
- 所有容器服务之间需要能够互相访问 (通过 Docker 内部网络)
- 后端 API 需要访问所有中间件服务 (PostgreSQL、Redis、RabbitMQ、EMQX)
外网通信
- 机器人设备: 需要通过 MQTT (端口 1883) 连接到 EMQX 服务
- 客户端浏览器: 需要访问前端 (端口 8080) 和后端 API (端口 5000)
- 第三方系统集成: 蓝印系统 WebSocket 连接 (ws://172.16.41.30:9990)
防火墙规则
入站规则 (需要开放):
允许 TCP 5000 (后端 API)
允许 TCP 8080 (前端 Web)
允许 TCP 1883 (MQTT)
允许 TCP 8083 (MQTT WebSocket)出站规则:
允许所有出站连接 (用于访问外部服务)4.3 网络带宽要求
| 场景 | 带宽要求 |
|---|---|
| 单机器人实时通信 | ~10 Kbps |
| 10 台机器人并发 | ~100 Kbps |
| 50 台机器人并发 | ~500 Kbps |
| 前端用户访问 | ~1 Mbps/用户 |
| 推荐总带宽 | 10 Mbps 或以上 |
五、中间件服务要求
5.1 PostgreSQL 数据库
| 配置项 | 要求 |
|---|---|
| 版本 | PostgreSQL 15 |
| 字符集 | UTF-8 |
| 扩展 | PostGIS (地理空间数据支持) |
| 最大连接数 | 100 (默认) |
| 内存分配 | 建议 2-4 GB |
| 数据库名称 | hah_rcs |
| 默认用户 | sa_user |
| 默认密码 | hu@Heng_! |
性能调优参数 (生产环境建议):
shared_buffers = 2GB
effective_cache_size = 6GB
maintenance_work_mem = 512MB
checkpoint_completion_target = 0.9
wal_buffers = 16MB
default_statistics_target = 100
random_page_cost = 1.1
effective_io_concurrency = 200
work_mem = 10MB
min_wal_size = 1GB
max_wal_size = 4GB5.2 Redis 缓存
| 配置项 | 要求 |
|---|---|
| 版本 | Redis 7.2 |
| 内存分配 | 建议 1-2 GB |
| 持久化 | RDB + AOF (推荐) |
| 最大内存策略 | allkeys-lru |
| 默认密码 | hu@Heng_! |
配置参数:
maxmemory 2gb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
save 60 10000
appendonly yes
appendfsync everysec5.3 RabbitMQ 消息队列
| 配置项 | 要求 |
|---|---|
| 版本 | RabbitMQ 4.1.3 (with MassTransit) |
| 内存分配 | 建议 1 GB |
| 磁盘空间 | 5 GB |
| 虚拟主机 | / (默认) |
| 默认用户 | guest |
| 默认密码 | guest |
性能参数:
vm_memory_high_watermark.relative = 0.6
disk_free_limit.absolute = 2GB
heartbeat = 60
channel_max = 20475.4 EMQX MQTT Broker
| 配置项 | 要求 |
|---|---|
| 版本 | EMQX 5.5 |
| 内存分配 | 建议 1 GB |
| 最大连接数 | 10000 (可调整) |
| 默认用户 | hahrcs |
| 默认密码 | hu@Heng_! |
MQTT 主题订阅:
v2/+/connection
v2/+/state
v2/+/factsheet
v2/+/visualization六、应用程序配置参数
6.1 后端 API 配置
数据库连接
{
"ConnSql": {
"ConnectionString": "Host=localhost;Port=5432;Database=hah_rcs;Username=sa_user;Password=hu@Heng_!"
}
}Redis 配置
{
"Redis": {
"Host": "localhost",
"Port": "7379",
"Password": "hu@Heng_!"
}
}RabbitMQ 配置
{
"RabbitMq": {
"Host": "localhost",
"Port": 5672,
"VirtualHost": "/",
"Username": "guest",
"Password": "guest",
"UseSSL": false,
"Heartbeat": 60,
"PrefetchCount": 16,
"ConcurrentMessageLimit": 32,
"RetryLimit": 3,
"RetryInterval": 5
}
}MQTT 配置
{
"Mqtt": {
"Broker": "localhost",
"Port": 1883,
"ClientId": "hahrcs",
"Username": "hahrcs",
"Password": "hu@Heng_!",
"UseTls": false,
"CleanSession": true,
"KeepAlivePeriodSeconds": 60,
"ReconnectDelaySeconds": 5
}
}CORS 跨域配置
{
"Cors": {
"AllowedOrigins": ["http://localhost:8081"],
"AllowedMethods": ["GET", "POST"],
"AllowedHeaders": ["Content-Type", "Authorization"]
}
}机器人状态同步配置
{
"RobotStatus": {
"RedisTtlSeconds": 60,
"EnableRedisCompression": false,
"DbSyncIntervalMs": 30000,
"DbSyncBatchSize": 100,
"EnableSmartSync": true,
"PositionChangeThreshold": 0.1,
"BatteryChangeThreshold": 1.0,
"EnableRedisPipeline": true,
"PipelineBatchSize": 50,
"PipelineFlushIntervalMs": 50
}
}6.2 前端配置
开发环境
# 开发服务器端口
PORT=8081
HOST=0.0.0.0
# 后端 API 地址
VITE_API_BASE_URL=http://localhost:5000生产环境
- 前端通过 Nginx 反向代理访问后端 API
- 默认访问地址: http://localhost:8080
七、安全要求
7.1 密码策略
默认密码清单 (生产环境必须修改):
| 服务 | 用户名 | 默认密码 | 修改位置 |
|---|---|---|---|
| PostgreSQL | sa_user | hu@Heng_! | appsettings.json |
| Redis | - | hu@Heng_! | appsettings.json |
| RabbitMQ | guest | guest | appsettings.json |
| EMQX | hahrcs | hu@Heng_! | appsettings.json |
7.2 网络安全
-
生产环境建议:
- 使用 HTTPS/TLS 加密通信
- 启用 MQTT TLS 加密 (端口 8883)
- 配置防火墙规则，仅开放必要端口
- 使用 VPN 或专网进行机器人通信
7.3 数据安全
- 数据库备份: 建议每日自动备份
- 日志保留: 建议保留 30 天
- 敏感信息: 使用环境变量或密钥管理服务存储
八、性能与容量规划
8.1 系统容量
| 指标 | 容量 |
|---|---|
| 最大机器人数量 | 100 台 (可扩展) |
| 并发任务数 | 500 个 |
| 地图数量 | 50 个 |
| 并发用户数 | 20 个 |
| MQTT 消息吞吐 | 1000 msg/s |
8.2 性能指标
| 指标 | 目标值 |
|---|---|
| API 响应时间 | < 200ms (P95) |
| MQTT 消息延迟 | < 100ms |
| 数据库查询 | < 50ms (P95) |
| Redis 缓存命中率 | > 90% |
| 系统可用性 | > 99.5% |
8.3 资源监控
建议监控指标:
- CPU 使用率 (< 70%)
- 内存使用率 (< 80%)
- 磁盘使用率 (< 80%)
- 网络带宽使用率
- 数据库连接数
- Redis 内存使用
- RabbitMQ 队列长度
- MQTT 连接数
九、部署环境检查清单
9.1 部署前检查
- 操作系统版本符合要求
- Docker Desktop 已安装并正常运行
- 所需端口未被占用
- 硬盘空间充足 (至少 50 GB)
- 内存充足 (至少 8 GB)
- 网络连通性正常
- 防火墙规则已配置
- 时间同步服务已启用 (NTP)
9.2 配置检查
- 数据库连接字符串已配置
- Redis 连接参数已配置
- RabbitMQ 连接参数已配置
- MQTT Broker 地址已配置
- CORS 跨域配置已设置
- 生产环境密码已修改
- 外部系统集成地址已配置 (如蓝印系统)
9.3 部署后验证
- 所有 Docker 容器正常运行
- 前端页面可正常访问
- 后端 API 健康检查通过
- 数据库连接正常
- Redis 缓存可用
- RabbitMQ 消息队列正常
- MQTT Broker 可连接
- 机器人可正常连接并通信
- 日志输出正常
十、故障排查与日志
10.1 日志位置
| 组件 | 日志位置 |
|---|---|
| 后端 API | docker logs hahrcs-api |
| Nginx | docker logs hahrcs-nginx |
| PostgreSQL | docker logs hahrcs-postgres |
| Redis | docker logs hahrcs-redis |
| RabbitMQ | docker logs hahrcs-rabbitmq |
| EMQX | docker logs hahrcs-emqx |
10.2 常见问题
问题 1: 端口被占用
# 检查端口占用
netstat -ano | findstr :8080
# 解决方案: 修改 docker-compose.yml 中的端口映射问题 2: 数据库连接失败
# 检查 PostgreSQL 容器状态
docker-compose ps postgres
# 查看数据库日志
docker-compose logs postgres
# 解决方案: 确保数据库已完全启动 (约需 10-30 秒)问题 3: 内存不足
# 检查 Docker 内存限制
docker stats
# 解决方案: 增加 Docker Desktop 内存分配 (设置 > Resources > Memory)问题 4: MQTT 连接失败
# 检查 EMQX 状态
docker-compose logs emqx
# 测试 MQTT 连接
# 使用 MQTT 客户端工具连接 localhost:188310.3 性能调优建议
-
数据库优化
- 定期执行 VACUUM 和 ANALYZE
- 为常用查询添加索引
- 调整连接池大小
-
Redis 优化
- 监控内存使用，避免 OOM
- 合理设置 TTL
- 使用 Redis Pipeline 批量操作
-
应用优化
- 启用 Redis 缓存
- 使用异步处理长时间任务
- 优化数据库查询
十一、升级与维护
11.1 版本升级
- 备份数据库和配置文件
- 停止所有服务:
docker-compose down - 更新镜像:
docker load -i hahrcs-images-new.tar - 启动服务:
docker-compose up -d - 验证系统功能
11.2 数据备份
数据库备份:
# 备份数据库
docker exec hahrcs-postgres pg_dump -U sa_user hah_rcs > backup_$(date +%Y%m%d).sql
# 恢复数据库
docker exec -i hahrcs-postgres psql -U sa_user hah_rcs < backup_20260119.sqlRedis 备份:
# 触发 RDB 快照
docker exec hahrcs-redis redis-cli -a "hu@Heng_!" BGSAVE
# 复制 RDB 文件
docker cp hahrcs-redis:/data/dump.rdb ./backup/11.3 定期维护任务
| 任务 | 频率 | 说明 |
|---|---|---|
| 数据库备份 | 每日 | 自动备份并异地存储 |
| 日志清理 | 每周 | 清理 30 天前的日志 |
| 磁盘空间检查 | 每周 | 确保可用空间 > 20% |
| 系统更新 | 每月 | 安全补丁和功能更新 |
| 性能分析 | 每月 | 分析系统瓶颈并优化 |
十二、技术支持
12.1 联系方式
- 项目名称: HaHRCS (华航机器人控制系统)
- 技术栈: .NET 8.0 + Vue 3 + PostgreSQL + Redis + RabbitMQ + EMQX
- 文档版本: 1.0
- 最后更新: 2026-01-19
12.2 相关文档
12.3 开源组件许可
| 组件 | 许可证 |
|---|---|
| .NET 8.0 | MIT |
| Vue 3 | MIT |
| PostgreSQL | PostgreSQL License |
| Redis | BSD 3-Clause |
| RabbitMQ | MPL 2.0 |
| EMQX | Apache 2.0 |
附录 A: Docker Compose 服务清单
services:
- rabbitmq:4.1.3 # 消息队列
- redis:7.2-alpine # 缓存服务
- postgres:15 # 数据库
- emqx:5.5 # MQTT Broker
- hahrcs/api:latest # 后端 API
- nginx:1.25-alpine # 前端 + 反向代理附录 B: 系统架构图
┌─────────────────────────────────────────────────────────────┐
│ 客户端层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Web 浏览器 │ │ 移动设备 │ │ AGV 机器人 │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
└─────────┼──────────────────┼──────────────────┼─────────────┘
│ │ │
│ HTTP:8080 │ HTTP:5000 │ MQTT:1883
│ │ │
┌─────────┼──────────────────┼──────────────────┼─────────────┐
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌─────────────────────────────┐ │
│ │ Nginx │ │ 后端 API (ASP.NET) │ │
│ │ (前端静态) │ │ - REST API │ │
│ └──────────────┘ │ - MQTT Client │ │
│ │ - SignalR Hub │ │
│ └─────────────┬───────────────┘ │
│ │ │
│ 应用层 & 基础设施层 │
└───────────────────────────────────┼─────────────────────────┘
│
┌─────────────────────────┼─────────────────────────┐
│ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │PostgreSQL│ │ Redis │ │ RabbitMQ │ │
│ │ (主库) │ │ (缓存) │ │ (消息队列)│ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ EMQX (MQTT Broker) │ │
│ │ - VDA5050 协议支持 │ │
│ │ - 机器人实时通信 │ │
│ └──────────────────────────────────────┘ │
│ │
│ 中间件层 │
└───────────────────────────────────────────────────┘附录 C: 环境变量配置模板
生产环境配置 (.env):
# 数据库配置
DB_HOST=localhost
DB_PORT=5432
DB_NAME=hah_rcs
DB_USER=sa_user
DB_PASSWORD=your_secure_password_here
# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=7379
REDIS_PASSWORD=your_secure_password_here
# RabbitMQ 配置
RABBITMQ_HOST=localhost
RABBITMQ_PORT=5672
RABBITMQ_USER=admin
RABBITMQ_PASSWORD=your_secure_password_here
# MQTT 配置
MQTT_BROKER=localhost
MQTT_PORT=1883
MQTT_USER=hahrcs
MQTT_PASSWORD=your_secure_password_here
# 应用配置
API_BASE_URL=http://your-server-ip:5000
WEB_BASE_URL=http://your-server-ip:8080文档结束
注意: 本文档基于系统当前配置生成，实际部署时请根据具体环境调整参数。生产环境部署前，请务必修改所有默认密码并进行安全加固。