安装与启动

准备安装包

选择与系统和 CPU 对应的原生包：macOS Apple Silicon、Linux arm64 / amd64、Windows amd64。不要把 Linux 包或 Windows 包解压到 macOS 后尝试运行。

原生包内置数据库、缓存、MQTT 和运行程序，普通用户无需安装 Docker、Rust 或 Node.js。安装目录需要有读写权限，首次初始化和升级时应有足够磁盘空间。保留原安装包用于回退。

解压到固定目录；避免运行时移动或改名。
macOS / Linux 在安装目录打开终端；Windows 在解压目录打开命令提示符。
执行检查，再启动。

./run.sh doctor
./run.sh start

Windows 对应命令：

bat

run.bat doctor
run.bat start

等待输出中的服务检查完成。
浏览器打开 Login URL。默认是 http://localhost:8081。其他电脑访问时将 localhost 换成服务器局域网地址；不要在另一台电脑上仍填写 localhost。
账号、密码均填写 admin，登录后修改密码。

端口与防火墙

用途	原生包默认端口	说明
管理网页	TCP 8081	`[ui] port`
gRPC / gRPC-Web	TCP 8080	`[chirpstack] api_port`；不是默认管理登录页
MQTT 网关入口	TCP 1883	`[mqtt] gateway_port`；默认 bind_address 为 127.0.0.1
MQTT 集成	TCP 1885	`[mqtt] integration_port`；账号和密码按本机配置
MQTT 双向 TLS	TCP 8883	`[mqtt] tls_port`；需要有效证书
UDP 网关	按 Profile 设置	`cn470_0` 对应 4700；不统一使用 1700

接入局域网 MQTT 网关时，在安装根目录 server.toml 将 [mqtt] bind_address 设置为服务器对外监听地址（例如 0.0.0.0），然后重启。放行实际需要的端口；数据库和缓存不需要作为用户访问入口开放。

配置和数据放在哪里

路径	用途	操作要求
`server.toml`	安装实例的服务和区域配置	修改前留副本，修改后重启
`secrets.toml`	自动生成的内部密码和 API Secret	不发群、不放截图；迁移时安全保管
`runtime/data/`	数据库、缓存、消息服务数据	不手动清空，不用旧目录覆盖正在运行的服务
`runtime/` 下日志与运行配置	状态和诊断	用 logs 命令定位实际文件
`app/`、`components/`、`scripts/`	随版本提供的程序	通过正式升级替换

首次启动生成 server.toml、secrets.toml 和本安装独立证书。修改 server.example.toml 不会代替已经生成的 server.toml。

选择区域与 UDP Profile

在 server.toml 配置后执行 ./run.sh restart（Windows 为 run.bat restart）：

toml

[lorawan]
enabled_regions = ["cn470_0"]

[gateway]
udp_profiles = ["cn470_0"]

如果只接 MQTT 网关，不需要为了在线而启用 UDP。使用多个区域时，UDP Profile 对应的区域也要启用。检查 [gateway.udp_ports] 中端口，避免多个 Profile 配到同一端口；AU915 / US915 部分默认端口相同，不能不核对就一起启用。

确认启动成功

./run.sh status
./run.sh logs chirpstack

确认网页可以登录，状态中没有依赖故障。页面打开只证明网页可达；网关上线和终端上报需继续按接入章节验证。

常驻与开机启动（按需）

macOS / Linux 执行 ./run.sh install-service；Windows 在管理员终端执行 run.bat install-service。不要将“关闭浏览器”当成“停止服务器”。正式停服使用 stop；取消开机启动使用 uninstall-service，保留数据。

旧 Docker 部署维护和迁移请使用对应历史版本迁移工具，不要直接把 PostgreSQL 原始目录复制进新原生实例。

安装与启动 ​

准备安装包 ​

端口与防火墙 ​

配置和数据放在哪里 ​

选择区域与 UDP Profile ​

确认启动成功 ​