📚 课程目录第3章边缘网关安装与初始化

3. 边缘网关安装与初始化

边缘网关的安装与初始化，是把一台普通工控机或服务器变成“可被 ThingWorx 平台管理的边缘节点”的过程。它包含四件事：在目标操作系统上完成安装、把网关注册为系统服务、填写最小可用的初始配置、与 ThingWorx 平台建立连接并确认在线。本节以 ThingWorx Edge 系列网关（如 Edge MicroServer / Edge SDK 运行环境）的通用安装思路为主线，给出 Windows 与 Linux 两套可复现的操作路径，并说明每一步的观察点与判断依据。

一、安装前的准备与前置条件

在动手安装之前，先确认三件事，否则后续连接失败很难定位。第一是网络方向：边缘网关需要主动向 ThingWorx 平台发起出站连接，默认使用 wss（WebSocket over TLS）到平台的 443 端口，因此网关侧防火墙只需放行出站，不需要平台反向访问网关。第二是身份凭据：平台侧需要预先创建 Application Key 或使用 OAuth 客户端凭据，网关用它完成身份认证。第三是主机名与时间：网关主机名建议固定且唯一，系统时间需与 NTP 同步，因为 TLS 证书校验和平台侧日志时间戳都依赖准确时间。

安装包通常是一个压缩包或安装程序，解压后目录结构大致包含可执行文件、配置模板、证书目录和日志目录。下面给出一个典型的目录约定，后续配置项都基于它：

/opt/thingworx-edge/
├── bin/            # 可执行程序与启动脚本
├── etc/            # 配置文件（config.json、certificates/）
├── logs/           # 运行日志
└── data/           # 本地缓存与持久化数据

二、Windows 环境安装步骤

Windows 上推荐使用管理员权限的 PowerShell 完成安装，避免路径权限问题。假设安装包为 edge-gateway-x64.zip，解压到 C:\Program Files\ThingWorxEdge：

Expand-Archive -Path .\edge-gateway-x64.zip -DestinationPath "C:\Program Files\ThingWorxEdge"
cd "C:\Program Files\ThingWorxEdge\bin"
.\edge-gateway.exe --version

执行 --version 能打印出版本号，说明可执行文件与运行库完整。若提示缺少 VC++ 运行库，需先安装对应的 Microsoft Visual C++ Redistributable。随后把网关注册为 Windows 服务，使其开机自启并在后台运行：

.\edge-gateway.exe install --name ThingWorxEdgeGateway --config "C:\Program Files\ThingWorxEdge\etc\config.json"
sc.exe start ThingWorxEdgeGateway
sc.exe query ThingWorxEdgeGateway

sc query 返回 STATE : 4 RUNNING 表示服务已启动。Windows 下服务日志默认写入 logs\edge-gateway.log，可用 Get-Content -Wait 实时跟踪。

三、Linux 环境安装步骤

Linux 上以 systemd 管理服务最为规范。以 /opt/thingworx-edge 为安装目录，创建专用运行用户 twedge，避免以 root 运行：

sudo useradd -r -s /sbin/nologin twedge
sudo tar -xzf edge-gateway-linux-x64.tar.gz -C /opt
sudo chown -R twedge:twedge /opt/thingworx-edge
sudo -u twedge /opt/thingworx-edge/bin/edge-gateway --version

接着编写 systemd 单元文件 /etc/systemd/system/thingworx-edge.service：

[Unit]
Description=ThingWorx Edge Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=twedge
WorkingDirectory=/opt/thingworx-edge
ExecStart=/opt/thingworx-edge/bin/edge-gateway --config /opt/thingworx-edge/etc/config.json
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

加载并启动：sudo systemctl daemon-reload、sudo systemctl enable --now thingworx-edge，再用 systemctl status thingworx-edge 查看状态。若显示 active (running) 且无反复重启，说明服务注册成功。Linux 下日志可用 journalctl -u thingworx-edge -f 跟踪。

四、初始配置项

网关的核心配置集中在 config.json。最小可用配置需要覆盖平台地址、身份凭据、设备标识和日志级别四类字段。下面是一份示例配置（参数为教学示例，实际值需替换为你的平台信息）：

{
  "platform": {
    "host": "pp-xxxxxx.devportal.ptc.io",
    "port": 443,
    "protocol": "wss",
    "appKey": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  },
  "gateway": {
    "name": "EdgeGateway-Shopfloor-01",
    "reconnectIntervalSec": 10,
    "keepAliveIntervalSec": 30
  },
  "logging": {
    "level": "INFO",
    "file": "/opt/thingworx-edge/logs/edge-gateway.log"
  }
}

几个关键点值得强调：host 必须是平台对外可解析的域名，不要填 IP，否则 TLS 证书校验会因 SAN 不匹配而失败；appKey 属于敏感凭据，Linux 下应把配置文件权限收紧为 chmod 600 并归属 twedge 用户；reconnectIntervalSec 决定断线重连节奏，生产环境不建议低于 5 秒，避免平台侧连接风暴；keepAliveIntervalSec 用于维持长连接，需小于平台侧的空闲超时阈值。

五、连接平台并验证在线状态

配置完成后重启服务，观察日志中是否出现连接建立与订阅成功的记录。典型成功日志会依次出现：加载配置、初始化 TLS、发起 WebSocket 连接、认证通过、绑定网关实体、开始心跳。若在认证阶段失败，日志通常返回 401 或 invalid application key；若在 TLS 阶段失败，则多为证书链或时间不同步问题。

平台侧的验证同样重要。登录 ThingWorx Composer，在 Remote Things 或 Edge Gateway 相关实体列表中，应能看到配置中 gateway.name 对应的网关实体，其 isConnected 属性为 true，且 lastConnectedTime 为最近时间。若实体存在但状态为断开，说明网关进程在运行但连接未建立，应回到日志排查。

六、常见失败点与排查顺序

连接失败时，建议按“网络 → TLS → 认证 → 实体”的顺序排查，而不是反复改配置。先用 Test-NetConnection（Windows）或 nc -vz（Linux）确认到平台 443 端口可达；再用 openssl s_client -connect host:443 检查证书链是否完整、系统时间是否在证书有效期内；随后核对 appKey 是否被禁用或过期；最后确认平台侧网关实体名称与配置一致，避免因重名导致绑定失败。

建议在首次部署时把日志级别临时设为 DEBUG，连接成功并稳定运行 10 分钟后改回 INFO，既能看清握手细节，又不会长期占用磁盘。

不要把 appKey 明文提交到代码仓库或工单系统。生产环境应使用平台下发的独立凭据，并定期轮换；轮换后需重启网关服务使新凭据生效。

完成以上步骤后，网关即处于“已安装、已注册、已配置、已在线”的可用状态。此时平台侧可以看到网关实体在线，后续即可在此基础上添加设备、定义数据采集点并下发远程管理指令。