Edge 部署

nexiot-edge 内置 Node-RED 和 Edge Agent。现在默认支持零参数启动：先把容器跑起来，再到 Node-RED 的 NexIoT 面板配置云端地址、部署码、远程管理和 MQTT。

默认值

配置	默认值
服务端口	18880
监听地址	0.0.0.0
数据目录	/app/data
Node-RED 编辑器	/red
Node-RED HTTP 节点入口	/api/nodered
Edge ID	edge-{hostname}

警告

生产环境建议挂载 /app/data，否则删除容器后 Node-RED 流程、Edge Token、manifest 缓存都会丢失。

Docker Run

mkdir -p /opt/nexiot-edge/data

docker run -d \
  --name nexiot-edge \
  --restart unless-stopped \
  -v /opt/nexiot-edge/data:/app/data \
  -p 18880:18880 \
  nexiot-edge:latest

访问：

http://设备IP:18880/red

健康检查：

curl http://127.0.0.1:18880/api/health

Docker Compose

docker-compose.yml：

services:
  nexiot-edge:
    image: nexiot-edge:latest
    container_name: nexiot-edge
    restart: unless-stopped
    ports:
      - "18880:18880"
    volumes:
      - ./data:/app/data

启动：

mkdir -p ./data
docker compose up -d
docker compose logs -f

停止：

docker compose down

首次配置

打开 http://设备IP:18880/red，进入右侧 NexIoT 面板。

按顺序配置：

1. 设置本地管理员账号密码。
2. 填写 Edge 名称。
3. 填写云端地址，例如 http://iot.example.com/api。
4. 填写部署码，或直接填写 Edge Token。
5. 选择远程管理模式。
6. 保存并应用。

保存后，Edge 会尝试使用部署码 claim 云端。成功后会把长期 token、MQTT 参数等保存到：

/app/data/config.json

后续重启不需要再填写部署码。

提示

如果云端 WebSocket 不是默认路径，在面板里单独填写 WebSocket URL。常见值是 ws://域名/ws/node-red/edge 或 ws://域名/api/ws/node-red/edge，以实际 Nginx 配置为准。

可选启动参数

零参数可以启动。只有需要固定身份或限制访问范围时，再加环境变量。

固定 Edge ID：

docker run -d \
  --name nexiot-edge \
  --restart unless-stopped \
  -e EDGE_ID=edge-site-001 \
  -v /opt/nexiot-edge/data:/app/data \
  -p 18880:18880 \
  nexiot-edge:latest

只允许本机访问：

docker run -d \
  --name nexiot-edge \
  --restart unless-stopped \
  -v /opt/nexiot-edge/data:/app/data \
  -p 127.0.0.1:18880:18880 \
  nexiot-edge:latest

验证

查看容器：

docker ps

查看日志：

docker logs -f nexiot-edge

查看健康状态：

curl http://127.0.0.1:18880/api/health

检查 token 是否已保存：

docker exec nexiot-edge node -e "const c=require('/app/data/config.json'); console.log({edgeId:c.edgeId, hasToken:!!(c.cloud&&c.cloud.token)})"

常见问题

访问不到 Node-RED

确认端口映射：

docker ps

Node-RED 地址是：

http://设备IP:18880/red

不是 1880。

重启后配置丢失

原因通常是没有挂载数据目录。必须保留：

-v /opt/nexiot-edge/data:/app/data

云端没有看到 Edge

检查：

1. 云端地址是否正确，通常要包含 /api。
2. 部署码是否有效。
3. /app/data/config.json 里是否已有 token。
4. curl http://127.0.0.1:18880/api/health 的 lastError。

手动设置 Edge ID 时不要用中文

EDGE_ID 会进入 HTTP Header，只使用英文、数字、短横线、下划线或点。

正确示例：

edge-site-001
edge_warehouse_01
edge.shanghai.01

中文名称放在 Edge 名称里，不要放在 Edge ID 里。

最小检查清单

1. 容器 Up。
2. /app/data 已挂载。
3. http://设备IP:18880/red 能打开。
4. NexIoT 面板已保存云端地址和部署码。
5. 健康接口 status=running。
6. config.json 已保存 token。