thethingsnetwork/lorawan-stack

The Things Stack for LoRaWAN

1. 镜像概述与主要用途

The Things Stack for LoRaWAN 是一款开源的 LoRaWAN 网络栈，适用于大型、全球化、地理分布式的公共网络和私有网络，也支持小型网络部署。其架构遵循 LoRaWAN 网络参考模型，确保标准合规性和互操作性。该项目由 The Things Industries 积极维护。

LoRaWAN 是一种低功耗广域网协议，支持大规模物联网部署场景，使低功耗设备能够通过长距离无线连接与互联网应用高效通信。

2. 核心功能与特性

2.1 LoRaWAN 网络服务器（Network Server）

• 支持 LoRaWAN 1.1 协议
• 支持 LoRaWAN 1.0、1.0.1、1.0.2、1.0.3 协议
• 支持 LoRaWAN 区域参数 1.0、1.0.2 rev B、1.0.3 rev A、1.1 rev A 和 B
• 支持 Class A 设备
• 支持 Class B 设备
• 支持 Class C 设备
• 支持 OTAA（空中激活）设备
• 支持 ABP（人工激活）设备
• 支持 MAC 命令
• 支持自适应数据速率（ADR）
• 实现 LoRaWAN 后端接口 1.0

2.2 LoRaWAN 应用服务器（Application Server）

• 支持知名负载格式的负载转换
• 支持通过自定义 JavaScript 函数进行负载转换
• MQTT 发布/订阅 API
• HTTP Webhooks API
• 实现 LoRaWAN 后端接口 1.0

2.3 LoRaWAN 连接服务器（Join Server）

• 支持 OTAA 会话密钥派生
• 支持外部加密服务
• 实现 LoRaWAN 后端接口 1.0 和 1.1 draft 3

2.4 OAuth 2.0 身份服务器（Identity Server）

• 用户管理
• 实体管理
• 访问控制列表（ACLs）

2.5 其他核心能力

• GRPC APIs
• HTTP APIs
• 命令行界面（CLI）：
  • 创建账户与登录
  • 应用管理与流量监控
  • 终端设备管理、状态与流量监控
  • 网关管理与状态监控
• Web 界面（Console）：
  • 创建账户与登录
  • 应用管理与流量监控
  • 终端设备管理、状态与流量监控
  • 网关管理、状态与流量监控

3. 使用场景与适用范围

3.1 适用场景

• 大规模物联网部署：支持低功耗设备通过长距离无线连接高效通信。
• 公共网络：适用于全球化、地理分布式的公共 LoRaWAN 网络。
• 私有网络：满足企业、组织自建的中小型私有 LoRaWAN 网络需求。
• 低功耗长距离通信场景：如智能表计（水、电、气）、环境监测（温湿度、空气质量）、资产跟踪（物流、仓储）等。

4. 部署与使用指南

4.1 Docker 部署示例

4.1.1 基本 Docker Run 命令

bash
docker run -d \
  --name ttn-stack \
  -p 8080:8080 \  # HTTP API 端口
  -p 1883:1883 \  # MQTT 端口
  -p 8881:8881 \  # Web 控制台端口
  -e TTN_LW_LOG_LEVEL=info \
  -e TTN_LW_HTTP_ADDRESS=0.0.0.0:8080 \
  -v ttn-stack-data:/root/.thethingsstack \
  thethingsnetwork/lorawan-stack

4.1.2 Docker Compose 配置

yaml
version: '3'

services:
  ttn-stack:
    image: thethingsnetwork/lorawan-stack
    container_name: ttn-stack
    restart: always
    ports:
      - "8080:8080"   # HTTP API
      - "1883:1883"   # MQTT
      - "8881:8881"   # Web Console
    environment:
      - TTN_LW_LOG_LEVEL=info
      - TTN_LW_HTTP_ADDRESS=0.0.0.0:8080
      - TTN_LW_MQTT_ADDRESS=0.0.0.0:1883
      - TTN_LW_CONSOLE_UI_ADDRESS=0.0.0.0:8881
      # 更多配置参数请参考官方文档
    volumes:
      - ttn-stack-data:/root/.thethingsstack

volumes:
  ttn-stack-data:

4.2 基本使用步骤

1. 安装部署：通过上述 Docker 命令或 Docker Compose 配置启动服务。
2. 访问控制台：浏览器访问 http://<主机IP>:8881 打开 Web 控制台。
3. 账户管理：通过 CLI 或控制台创建管理员账户并登录：

   bash
   # 创建账户（需在容器内执行或映射 CLI 工具）
   ttn-lw-cli users create admin --email admin@example.com --password <密码>
   # 登录
   ttn-lw-cli login
   

4. 设备与应用管理：通过控制台或 CLI 添加应用、注册设备（OTAA/ABP 模式）、配置负载转换规则等。
5. 数据集成：通过 MQTT 或 HTTP Webhooks 将设备数据集成到应用系统。

4.3 配置说明

核心配置通过环境变量或配置文件（ttn-lw-stack.yml）设置，关键参数包括：

• TTN_LW_LOG_LEVEL：日志级别（debug/info/warn/error）
• TTN_LW_HTTP_ADDRESS：HTTP API 监听地址与端口
• TTN_LW_MQTT_ADDRESS：MQTT 服务监听地址与端口
• TTN_LW_CONSOLE_UI_ADDRESS：Web 控制台地址与端口
• 数据库配置、加密密钥等高级参数需参考官方文档。

5. 版本承诺

为确保开源生态的稳定性与可靠性，项目作出以下承诺：

1. 网关与应用 API 兼容性：在主版本内，不破坏网关与应用的通信接口（包括网关通信方式和应用数据交互逻辑）。
2. 存储升级支持：主版本内支持从旧版本升级存储，确保数据不丢失。
3. CLI 与配置兼容性：主版本内不破坏公共命令行界面（CLI）和配置格式，支持脚本与配置迁移。
4. 组件间 API 稳定性：次版本内不破坏组件间 API 与事件格式，相同次版本的组件相互兼容。

注意：次版本可能新增配置项与默认值，建议升级前阅读 https://github.com/TheThingsNetwork/lorawan-stack/releases%E3%80%82

6. 支持资源

• 论坛：The Things Network 论坛 包含大量资料与搜索支持。
• Slack 社区：通过 #lorawan-stack 频道 实时交流（需通过 ttn.fyi/slack-invite 获取 Slack 账户）。
• 商业支持：The Things Industries 提供托管解决方案、商业支持与咨询服务。