ChirpStack v4 完整部署文档
一、环境要求
1.1 服务器要求
操作系统：Ubuntu 20.04/22.04 或 Debian 11/12
CPU：2核及以上
内存：4GB及以上
磁盘：20GB及以上
网络：公网IP，开放端口 8080、1700、3001、8090、1883
1.2 软件要求
Docker 20.10+
Docker Compose 2.0+
Git
二、基础环境安装
2.1 安装 Docker
curl -fsSL https://get.docker.com | sh systemctl enable docker && systemctl start docker
警告: 直接执行远程脚本，来源不可控
▶ 执行到当前终端
复制
2.2 安装 Docker Compose
curl -L “https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname-s)-$(uname -m)” -o /usr/local/bin/docker-compose chmod +x /usr/local/bin/docker-compose docker-compose --version
▶ 执行到当前终端
复制
2.3 安装 Git
apt update && apt install -y git
▶ 执行到当前终端
复制
三、拉取 ChirpStack Docker 源码
cd /software git clone https://github.com/chirpstack/chirpstack-docker.git cd chirpstack-docker
▶ 执行到当前终端
复制
四、修改 docker-compose.yml 配置
4.1 修改频段配置（默认使用 cn470_0）

修改 Gateway Bridge 频段为 cn470_0 sed -i ‘s/eu868/cn470_0/g’ docker-compose.yml

▶ 执行到当前终端
复制
4.2 验证 docker-compose.yml 配置
cat docker-compose.yml
▶ 执行到当前终端
复制
关键配置项：

chirpstack：核心服务，端口 8080
chirpstack-gateway-bridge：网关桥接，UDP 1700
chirpstack-gateway-bridge-basicstation：BasicStation，端口 3001
chirpstack-rest-api：REST API，端口 8090
postgres：数据库
redis：缓存
mosquitto：内部 MQTT
五、修改区域配置
5.1 修改 cn470_0 区域配置
cd /software/chirpstack/chirpstack-docker/configuration/chirpstack/
▶ 执行到当前终端
复制

5.1.1 修改 RX2 频率为 505300000

sed -i ‘s/rx2_frequency=.*/rx2_frequency=505300000/’ region_cn470_0.toml
▶ 执行到当前终端
复制

5.1.2 修改 RX2 数据速率为 0

sed -i ‘s/rx2_dr=.*/rx2_dr=0/’ region_cn470_0.toml
▶ 执行到当前终端
复制

5.1.3 验证修改

grep -n “rx1_dr_offset|rx2_frequency|rx2_dr” region_cn470_0.toml
▶ 执行到当前终端
复制
预期输出：

rx1_dr_offset=0 rx2_dr=0 rx2_frequency=505300000
▶ 执行到当前终端
复制
5.2 确认所有频段已启用
grep -A 20 “enabled_regions” /software/chirpstack/chirpstack-docker/configuration/chirpstack/chirpstack.toml
▶ 执行到当前终端
复制
预期包含： ```toml enabled_regions=[ “as923”, “as923_2”, “as923_3”, “as923_4”, “au915_0”, “cn470_0”, “cn470_10”, “cn779”, “eu433”, “eu868”, “in865”, “ism2400”, “kr920”, “ru864”, “us915_0”, “us915_1”, ]

六、配置 EMQX 连接 ### 6.1 修改 ChirpStack 主配置连接 EMQX

▶ 执行到当前终端
复制
bash

备份原配置
cp /software/chirpstack/chirpstack-docker/configuration/chirpstack/chirpstack.toml /software/chirpstack/chirpstack-docker/configuration/chirpstack/chirpstack.toml.bak

修改 EMQX 地址（替换为实际 EMQX IP）
sed -i ‘s|server=“tcp://$MQTT_BROKER_HOST:1883/”|server=“tcp://114.55.246.111:1883”|’ /software/chirpstack/chirpstack-docker/configuration/chirpstack/chirpstack.toml

添加用户名和密码
sed -i ‘/[integration.mqtt]/a\ username=“ja123_chirpstack”\n password=“insight2025”’ /software/chirpstack/chirpstack-docker/configuration/chirpstack/chirpstack.toml

6.2 验证配置

▶ 执行到当前终端
复制
bash grep -A 10 “[integration]” /software/chirpstack/chirpstack-docker/configuration/chirpstack/chirpstack.toml

预期输出：
▶ 执行到当前终端
复制
toml [integration] enabled=[“mqtt”]

[integration.mqtt] username=“ja123_chirpstack” password=“insight2025” server=“tcp://114.55.246.111:1883” json=true

七、启动服务 ### 7.1 启动所有容器

▶ 执行到当前终端
复制
bash cd /software/chirpstack/chirpstack-docker docker-compose up -d

7.2 验证容器状态

▶ 执行到当前终端
复制
bash docker-compose ps

预期状态：所有容器 Up 状态 ### 7.3 查看日志确认启动成功
▶ 执行到当前终端
复制
bash docker-compose logs chirpstack | tail -30

确认包含： - Setting up gateway backend for region region_id=cn470_0 - Connecting to MQTT broker server_uri=tcp://114.55.246.111:1883 - Subscribing to command topic ## 八、验证部署 ### 8.1 验证 Web 界面 访问 http://服务器IP:8080 - 默认账号：admin - 默认密码：admin ### 8.2 验证 EMQX 连接 登录 EMQX Dashboard（http://EMQX_IP:18083） - 检查 ChirpStack 客户端是否已连接 - 检查主题 application/+/device/+/event/up 是否有数据 ### 8.3 验证网关连接 在 ChirpStack Web 界面中： 1. 进入 Gateways 页面 2. 确认网关已注册并在线 3. 检查网关状态和上行数据 ## 九、常见问题排查 ### 9.1 容器启动失败
▶ 执行到当前终端
复制
bash

查看错误日志
docker-compose logs chirpstack | tail -50

常见错误：配置格式错误
检查 TOML 配置格式
docker exec chirpstack-docker-chirpstack-1 cat /etc/chirpstack/chirpstack.toml

9.2 端口无法访问

▶ 执行到当前终端
复制
bash

检查端口监听
ss -tlnp | grep -E “8080|1700|3001|8090”

检查防火墙
ufw status

或
iptables -L -n | grep -E “8080|1700|3001|8090”

9.3 EMQX 连接失败

▶ 执行到当前终端
复制
bash

测试 EMQX 端口连通性
timeout 5 bash -c ‘echo > /dev/tcp/114.55.246.111/1883’ && echo “EMQX MQTT port is open” || echo “EMQX MQTT port is closed”

检查 EMQX 认证配置
grep -A 10 “[integration]” /software/chirpstack/chirpstack-docker/configuration/chirpstack/chirpstack.toml

9.4 网关无法连接

▶ 执行到当前终端
复制
bash

检查网关桥接日志
docker-compose logs chirpstack-gateway-bridge | tail -30

检查网关是否注册
docker exec -it chirpstack-docker-postgres-1 psql -U chirpstack -d chirpstack -c “SELECT * FROM gateway;”

十、备份与恢复 ### 10.1 备份配置

▶ 执行到当前终端
复制
bash

备份整个配置目录
cp -r /software/chirpstack/chirpstack-docker/configuration /software/chirpstack/configuration_backup_$(date +%Y%m%d)

10.2 备份数据库

▶ 执行到当前终端
复制
bash

备份 PostgreSQL 数据
docker exec chirpstack-docker-postgres-1 pg_dump -U chirpstack chirpstack > /software/chirpstack_backup_$(date +%Y%m%d).sql

10.3 恢复配置

▶ 执行到当前终端
复制
bash

恢复配置
cp -r /software/chirpstack/configuration_backup_YYYYMMDD/* /software/chirpstack/chirpstack-docker/configuration/

十一、更新升级 ### 11.1 更新 ChirpStack

▶ 执行到当前终端
复制
bash cd /software/chirpstack/chirpstack-docker git pull docker-compose down docker-compose up -d

11.2 更新镜像

▶ 执行到当前终端
复制
bash docker-compose pull docker-compose up -d ```

十二、安全建议
修改默认密码：登录 Web 界面后立即修改 admin 密码
限制端口访问：使用安全组或防火墙限制 8080、8090 端口的访问来源
启用 HTTPS：使用 Nginx 反向代理配置 HTTPS
定期备份：定期备份配置和数据库
监控日志：定期检查 ChirpStack 和 EMQX 日志
十三、关键配置参数说明
参数 值 说明
默认频段 cn470_0 CN470 信道 0-7
RX1 DR Offset 0 RX1 数据速率偏移
RX2 DR 0 RX2 数据速率
RX2 Frequency 505300000 RX2 接收频率 (505.3MHz)
Web 端口 8080 ChirpStack Web 界面
Gateway Bridge UDP 1700 网关数据端口
BasicStation 端口 3001 BasicStation 连接端口
REST API 端口 8090 REST API 接口
MQTT 端口 1883 内部 Mosquitto

文档结束。按照此文档操作即可在新服务器上完整部署 ChirpStack v4。如有问题，请参考第九节的排查指南。