网关部署

开发预览

本页依据提交 b1a16cbc 的构建与运行源码及项目部署文档整理，不是生产部署验收报告。Docker 资产真实存在，但默认配置、驱动接线和若干系统接口仍有阻塞（见快速开始）；部署进程不等于采集与控制链路可用。

1. 硬件要求

规格	最低要求	推荐配置
CPU	ARM Cortex-A53（四核 1.0GHz）	ARM Cortex-A72（四核 1.5GHz+）
内存	512MB RAM	1GB RAM
存储	4GB eMMC	8GB eMMC + SD 卡扩展
串口	1× RS485	3× RS485 + 1× RS232
以太网	1× 100M	2× 1000M（WAN + LAN）
WiFi	可选	2.4GHz 802.11n
GPIO	可选	8×DI + 8×DO + 4×AI
USB	1× USB 2.0	2× USB 2.0
指示灯	—	电源/运行/网络/故障
供电	DC 9-36V 宽压	DC 12-24V

支持的硬件平台：

树莓派 4B / 5（开发/测试用）
友善之臂 NanoPi R5S / T4
研华/研祥/触想等 ARM 工业网关
任何运行 Debian 12 ARM64 的 Cortex-A53/A72 设备

2. 软件要求

项目	版本要求
操作系统	Debian 12 (Bookworm) ARM64
内核	Linux 5.10+
systemd	252+
OpenSSL	3.0+
libmodbus	3.1.6+
SQLite3	3.40+

系统依赖包（ARM 目标机）：

bash

sudo apt update
sudo apt install -y \
  build-essential cmake pkg-config \
  libssl-dev libmodbus-dev libsqlite3-dev \
  libgpiod-dev gpiod \
  chrony curl wget jq

3. Docker Compose 部署

适用于快速体验、开发测试环境，提供 Gateway + Mosquitto MQTT Broker 一体化编排。

在源码根目录执行：

bash

docker compose up -d --build
docker compose ps
docker compose logs -f gateway

停止服务：

bash

docker compose down

镜像使用 Alpine 3.19 多阶段构建，运行入口为 ./bin/fastbee-gateway，工作目录为 /opt/fastbee。默认构建关闭测试、GPIO、OPC UA 和 BACnet，构建 Modbus 驱动；这不会让 Stub 协议变成真实驱动。

服务组成：

服务	镜像	端口	说明
`gateway`	自构建（Alpine 3.19）	8080, 8443	FastBee 网关主服务
`mosquitto`	eclipse-mosquitto:2	1883, 8883	MQTT Broker

数据持久化卷：

Volume	容器路径	说明
`gateway-data`	`/opt/fastbee/data`	SQLite 数据库、历史记录
`gateway-logs`	`/opt/fastbee/logs`	日志文件
`gateway-certs`	`/opt/fastbee/certs`	TLS 证书
`mosquitto-data`	`/mosquitto/data`	MQTT 持久化数据

常用操作：

bash

docker compose down                  # 停止服务
docker compose up -d --build         # 代码更新后重建
docker exec -it fastbee-gateway sh   # 进入容器调试
docker stats fastbee-gateway fastbee-mosquitto   # 查看资源占用

3.1 启动前必须处理的配置问题

Broker 不一致：Compose 服务名为 mosquitto，默认 config/gateway.json 却指向 192.168.1.100:1883。按实际网络修改 mqtt.broker、mqtt.port 和凭据。
只读配置：./config:/opt/fastbee/config:ro 会阻止 .secret.key 创建及 MQTT 配置保存。开发环境需在受控副本上明确设计可写配置/秘密目录；生产环境不要把整个配置目录不加区分地开放写入。
密文不可移植：ENC(...) 值依赖对应密钥，解密失败时不能当作有效默认证据。替换占位并独立备份密钥。
空采集配置：默认 drivers 为空且没有设备/Tag；即使补齐 JSON，当前应用仍未完成驱动注册，详见快速开始的当前阻塞。

3.2 端口与协议

端口	当前含义与限制
`8080`	Web UI/API 的明文 HTTP 监听，绑定 `0.0.0.0`；不要直接暴露到不受信任网络
`8443`	Docker/Compose 标注并暴露的端口，但当前没有对应 HTTPS Server，不是可用 HTTPS 入口
`1883`	随附 Mosquitto 的 MQTT 端口，开发配置允许匿名访问
`8883`	Mosquitto 的第二监听器，没有 TLS 证书/选项，不得描述为可用 MQTT TLS
`502`	Modbus TCP 驱动连接目标设备的常见默认端口，不是网关自身必然监听的服务端口
`5020`	Modbus 模拟器示例端口，仅用于受控开发联调

随附 Mosquitto 在两个监听器上都设置 allow_anonymous true。在生产或共享网络中必须另行配置认证、TLS 和最小权限访问；默认 admin/admin123 也必须立即修改。

4. PC 开发机部署（x86_64）

适用于功能开发、驱动调试和集成测试场景，无需真实工业网关硬件。推荐 Ubuntu 22.04 或 Windows 11 WSL2 (Ubuntu 22.04)，4 核 CPU、8GB 内存以上。

安装依赖：

bash

sudo apt update
sudo apt install -y \
  build-essential cmake pkg-config \
  libssl-dev libmodbus-dev libsqlite3-dev \
  libgpiod-dev curl wget jq

从源码根目录配置和编译（从源码根目录启动可保证相对路径 web-src 被正确找到）：

bash

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DFASTBEE_BUILD_TESTS=ON
cmake --build build -j"$(nproc)"
./build/bin/fastbee-gateway --config ./config/gateway.json --log-level debug

CMake 会自动检测平台为 x86_64 并定义 FASTBEE_PLATFORM_X86=1 宏；PC 无 GPIO 硬件时使用模拟后端。可选地运行单元测试：

bash

cd build && ctest --output-on-failure

开发调试技巧：

bash

# GDB 调试
gdb ./build/bin/fastbee-gateway
(gdb) run --config ./config/gateway.json

# Valgrind 内存检查
valgrind --leak-check=full ./build/bin/fastbee-gateway --config ./config/gateway.json

# AddressSanitizer 构建
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_CXX_FLAGS="-fsanitize=address -fno-omit-frame-pointer" \
  -DCMAKE_C_FLAGS="-fsanitize=address -fno-omit-frame-pointer"

5. 树莓派部署（ARM64）

树莓派 4B（4GB+）/ 5 是理想的轻量级边缘网关平台，操作系统使用 Raspberry Pi OS (64-bit，基于 Debian 12)。

系统准备：

bash

sudo apt update && sudo apt upgrade -y
sudo apt install -y \
  build-essential cmake pkg-config \
  libssl-dev libmodbus-dev libsqlite3-dev \
  libgpiod-dev gpiod curl wget jq

5.1 方式一：本机编译

bash

git clone https://gitee.com/beecue/fastbee-gateway.git
cd fastbee-gateway

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_INSTALL_PREFIX=/usr \
  -DFASTBEE_ENABLE_GPIO=ON \
  -DFASTBEE_BUILD_TESTS=OFF \
  -DFASTBEE_BUILD_DRIVERS=ON

# 树莓派 4B 约 10-15 分钟，Pi 5 约 3-5 分钟
cmake --build build -j4
sudo cmake --install build

5.2 方式二：交叉编译（PC 上编译，部署到树莓派）

bash

# === 开发 PC (x86_64) ===
sudo apt install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

cmake -S . -B build-rpi \
  -DCMAKE_TOOLCHAIN_FILE=./cmake/aarch64-toolchain.cmake \
  -DCMAKE_BUILD_TYPE=Release \
  -DFASTBEE_ENABLE_GPIO=ON \
  -DFASTBEE_BUILD_TESTS=OFF
cmake --build build-rpi -j"$(nproc)"

# 传输到树莓派
scp build-rpi/bin/fastbee-gateway pi@<树莓派IP>:/tmp/
scp build-rpi/lib/*.so pi@<树莓派IP>:/tmp/
scp -r config/ pi@<树莓派IP>:/tmp/fastbee-config/

# === 树莓派 ===
sudo mv /tmp/fastbee-gateway /usr/bin/
sudo mv /tmp/*.so /usr/lib/
sudo mkdir -p /etc/fastbee-gateway
sudo cp -r /tmp/fastbee-config/* /etc/fastbee-gateway/
sudo chmod +x /usr/bin/fastbee-gateway

5.3 GPIO 验证

启用真实 GPIO 后可用 gpiod 工具验证：

bash

gpiodetect                  # 输出示例: gpiochip0 [pinctrl-bcm2712] (54 lines)
gpioinfo gpiochip0          # 查看引脚
gpioset gpiochip0 17=1      # 设置 GPIO17 高电平
gpioget gpiochip0 18        # 读取 GPIO18 电平

树莓派 GPIO 为 3.3V 逻辑电平，连接 RS485/继电器等外设时需使用电平转换模块。GPIO 通道配置见配置的 gpio.json 一节。

5.4 串口配置（USB-RS485）

bash

ls -l /dev/ttyUSB*                    # 查看转换器设备，通常为 /dev/ttyUSB0
sudo usermod -aG dialout pi           # 串口权限
stty -F /dev/ttyUSB0 9600 cs8 -cstopb -parenb   # 验证串口参数

树莓派 40-pin 上的硬件串口 /dev/ttyAMA0 默认被蓝牙占用，如需使用需在 raspi-config 中调整。

6. 安装方式汇总

6.1 源码编译安装

bash

cmake -S . -B build \
  -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/usr \
  -DFASTBEE_ENABLE_GPIO=ON -DFASTBEE_BUILD_TESTS=OFF
cmake --build build -j"$(nproc)"
sudo cmake --install build

6.2 deb 包安装

项目支持用 CPack 生成 deb 包：

bash

cd build && cpack -G DEB
# 输出: fastbee-gateway-1.0.0-arm64.deb

sudo dpkg -i fastbee-gateway-1.0.0-arm64.deb
sudo apt install -f        # 修复依赖（如有）
fastbee-gateway --version

6.3 交叉编译 + SCP 部署

见第 5.2 节，同一流程适用于任何 ARM 工业网关。

7. systemd 服务管理

项目提供 systemd 服务文件（scripts/systemd/），典型配置：

ini

[Unit]
Description=FastBee Industrial IoT Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/fastbee-gateway --config /etc/fastbee-gateway/gateway.json
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=5
WatchdogSec=30
User=root
WorkingDirectory=/etc/fastbee-gateway
ProtectSystem=strict
ReadWritePaths=/etc/fastbee-gateway /var/log/fastbee-gateway /var/lib/fastbee-gateway
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

常用命令：

bash

sudo systemctl daemon-reload
sudo systemctl enable fastbee-gateway
sudo systemctl start fastbee-gateway
sudo systemctl status fastbee-gateway
sudo journalctl -u fastbee-gateway -f

7.1 systemd/安装脚本的当前差异

不要直接照搬旧安装说明：

scripts/install.sh 查找 web/，实际静态资源目录为 web-src。
随附 systemd unit 预期 /opt/fastbee-gateway/...，CMake 安装与旧文档又使用 /usr 路径。
Web 资源按进程工作目录解析 web-src，服务的工作目录和启动参数必须与最终安装布局一致。

在完成这些路径修正并实际验证前，本页不提供"安装即成功"的 systemd 教程。若已自行修正 unit，可用 journalctl -u fastbee-gateway 检查日志。

8. 首次配置流程

8.1 AP 配网

设计上首次部署时网关自动启动 WiFi AP 热点供配置：

text

SSID:     FastBee-GW-XXXX（后四位为 MAC 地址）
密码:     12345678
IP 地址:  192.168.4.1
管理页面: http://192.168.4.1:8080

用电脑/手机连接该 WiFi 后浏览器访问管理页面，默认管理员账号 admin / admin123。

8.2 配置 WiFi STA / 以太网

在 Web 管理界面 → 网络管理 → WiFi STA：扫描可用 WiFi、选择并输入密码连接，记录分配的 IP（后续用此 IP 访问），AP 热点随后关闭。也可直接用以太网跳过 WiFi 配置。

8.3 配置 MQTT 连接

在 Web 管理界面 → MQTT 配置中填写 Broker 地址、端口、认证凭据、productId/deviceNum 等。MQTT 认证使用 FastBee AES 加密认证方式，密钥在平台侧设备管理中生成。

8.4 添加子设备与 Tag

在 Web 管理界面 → 设备管理中添加子设备（协议、从站地址、串口/网络参数），再在设备详情中添加 Tag 点位（寄存器地址、数据类型、缩放、采集周期）。字段的实际解析行为以配置为准。

9. 网络配置（目标机）

bash

# WAN 口静态 IP
sudo nmcli con add type ethernet con-name wan ifname eth0 \
  ipv4.addresses 192.168.1.100/24 \
  ipv4.gateway 192.168.1.1 \
  ipv4.dns "8.8.8.8,114.114.114.114" \
  ipv4.method manual

# WiFi 连接
sudo nmcli device wifi connect "SSID" password "密码" ifname wlan0

# 防火墙放行 Web 端口
sudo ufw allow 8080/tcp

10. 上线前安全检查

修改默认管理员密码，并认识到当前中间件不能证明所有路由都执行角色授权。
关闭匿名 MQTT，配置真实 TLS；不要把 8883 暴露误认为加密已经完成。
为 8080 增加受控网络边界和正确的 HTTPS 反向代理，而不是使用未实现的 8443 入口。
限制所有调试接口；/api/debug/ping 将输入拼接进系统命令，存在命令注入风险，必须先修复或隔离，不能提供给不可信用户。
不把 Stub 写入成功、OTA 上传回执或恢复出厂成功响应当作物理操作完成证据。
分别验证备份、配置秘密、日志和真实设备联调；当前不得承诺离线补报、配置自动重连、恢复出厂、OTA 或 MQTT 反向控制的生产可用性。

11. 常见部署问题

11.1 编译失败：libmodbus 未找到

bash

sudo apt install libmodbus-dev
# 或使用 stub 模式编译（无真实 Modbus 硬件）
cmake -S . -B build -DLIBMODBUS_FOUND=OFF

11.2 串口无法打开

bash

ls -l /dev/ttyS* /dev/ttyUSB*
sudo chmod 666 /dev/ttyS1      # 或将用户加入 dialout 组
fuser /dev/ttyS1               # 检查是否被其他进程占用

11.3 内存不足（OOM）

bash

free -h
ps aux | grep fastbee-gateway
# 临时增加 swap
sudo fallocate -l 1G /swapfile && sudo chmod 600 /swapfile
sudo mkswap /swapfile && sudo swapon /swapfile

11.4 启动后立即退出

bash

journalctl -u fastbee-gateway --no-pager -n 200
sudo /usr/bin/fastbee-gateway --config /etc/fastbee-gateway/gateway.json --log-level debug
cat /etc/fastbee-gateway/gateway.json | jq .   # 校验 JSON 语法

更多运行期排查场景见运维。

网关部署 ​

1. 硬件要求 ​

2. 软件要求 ​

3. Docker Compose 部署 ​

3.1 启动前必须处理的配置问题 ​

3.2 端口与协议 ​

4. PC 开发机部署（x86_64） ​

5. 树莓派部署（ARM64） ​

5.1 方式一：本机编译 ​

5.2 方式二：交叉编译（PC 上编译，部署到树莓派） ​

5.3 GPIO 验证 ​

5.4 串口配置（USB-RS485） ​

6. 安装方式汇总 ​

6.1 源码编译安装 ​

6.2 deb 包安装 ​

6.3 交叉编译 + SCP 部署 ​

7. systemd 服务管理 ​

7.1 systemd/安装脚本的当前差异 ​

8. 首次配置流程 ​

8.1 AP 配网 ​

8.2 配置 WiFi STA / 以太网 ​

8.3 配置 MQTT 连接 ​

8.4 添加子设备与 Tag ​

9. 网络配置（目标机） ​

10. 上线前安全检查 ​

11. 常见部署问题 ​

11.1 编译失败：libmodbus 未找到 ​

11.2 串口无法打开 ​

11.3 内存不足（OOM） ​

11.4 启动后立即退出 ​

网关部署

1. 硬件要求

2. 软件要求

3. Docker Compose 部署

3.1 启动前必须处理的配置问题

3.2 端口与协议

4. PC 开发机部署（x86_64）

5. 树莓派部署（ARM64）

5.1 方式一：本机编译

5.2 方式二：交叉编译（PC 上编译，部署到树莓派）

5.3 GPIO 验证

5.4 串口配置（USB-RS485）

6. 安装方式汇总

6.1 源码编译安装

6.2 deb 包安装

6.3 交叉编译 + SCP 部署

7. systemd 服务管理

7.1 systemd/安装脚本的当前差异

8. 首次配置流程

8.1 AP 配网

8.2 配置 WiFi STA / 以太网

8.3 配置 MQTT 连接

8.4 添加子设备与 Tag

9. 网络配置（目标机）

10. 上线前安全检查

11. 常见部署问题

11.1 编译失败：libmodbus 未找到

11.2 串口无法打开

11.3 内存不足（OOM）

11.4 启动后立即退出