📚 课程目录第3章开发环境搭建与连接配置

3. 开发环境搭建与连接配置

ThingWorx 平台开发的第一步，是把“开发工具—平台服务—设备数据源”三者打通。本节围绕 ThingWorx Composer 的安装与访问、应用密钥（Application Key）的创建与授权、以及与生产设备数据源的初步连接测试展开。完成本节后，你应当能够独立登录 Composer、生成一个可用于外部调用的密钥，并通过 REST 接口或 ThingWorx Edge 通道验证平台与设备侧的数据通路是否可用。

一、ThingWorx Composer 的安装与访问

ThingWorx Composer 是平台自带的 Web 建模与配置工具，通常不需要单独安装客户端，而是随 ThingWorx 平台部署后通过浏览器访问。若采用本地开发环境，常见做法是使用官方提供的 ThingWorx Foundation 安装包（Windows 下为可执行安装程序，Linux 下为 Docker 镜像或压缩包）部署到本机或测试服务器。安装过程中需要关注几个关键参数：平台监听端口（默认 8080）、管理员账号（默认 Administrator）、以及数据库连接（默认使用内置 H2，生产环境建议改为 PostgreSQL 或 MSSQL）。

安装完成后，在浏览器地址栏输入 http://<服务器IP>:8080/Thingworx/Composer，使用管理员账号登录。首次登录后建议立即修改默认密码，并在“系统设置”中确认平台版本与许可证状态。若页面无法打开，优先检查服务是否启动、端口是否被占用、防火墙是否放行 8080 端口。Composer 的界面分为左侧导航树、中间工作区和右侧属性面板，后续所有建模、配置和测试操作都在此完成。

二、应用密钥的创建与授权

应用密钥是外部系统（如设备网关、脚本、第三方平台）调用 ThingWorx REST API 时的身份凭证。它由平台生成，包含一个 Key ID 和一段密钥字符串，调用时需放入请求头 appKey 中。创建路径为：Composer 左侧导航 → Security → Application Keys → New。在新建页面中填写名称（例如 DeviceGatewayKey），选择有效期（开发阶段可设为 1 年），并指定该密钥所属的用户或组织。

密钥创建后，必须为其分配权限，否则调用会被拒绝。权限配置的核心是“最小可用”原则：如果该密钥仅用于读取设备属性，则只授予对应 Thing 的 Service Invoke 或 Property Read 权限；如果需要写入数据，再追加 Property Write。在 Application Keys 详情页的 Permissions 区域，可以按“用户组—资源—权限”的粒度逐条添加。配置完成后点击 Save，平台会生成密钥字符串，务必立即复制保存，因为关闭页面后无法再次查看完整密钥。

开发阶段可以创建一个拥有较宽权限的密钥用于快速验证，但在进入测试或生产环境前，应替换为按设备、按服务细分的专用密钥，并设置合理的过期时间。

三、与生产设备数据源的初步连接测试

连接测试的目标是验证“平台能否通过密钥访问到设备数据”。根据设备接入方式不同，可分为两类：一类是设备支持 REST/HTTP，直接由平台或中间脚本调用；另一类是设备通过 ThingWorx Edge SDK 或 Kepware 等网关接入。本节以最常见的 REST 方式为例，说明测试流程。

首先在 Composer 中创建一个用于测试的 Thing，例如 TestDevice，并为其添加一个属性 Temperature（类型 Number）。保存后，使用任意 HTTP 客户端（如 Postman、curl 或 Python requests）向平台发送请求。以下是一个读取属性的示例命令：

curl -X GET \
  "http://192.168.1.100:8080/Thingworx/Things/TestDevice/Properties/Temperature" \
  -H "appKey: 3f7a9c2e-1b4d-4e8a-9c6f-2d5e8a1b7c30" \
  -H "Accept: application/json"

若返回 {"Temperature": 0} 或类似 JSON，说明密钥有效、Thing 存在、属性可读，平台侧通路正常。若返回 401，检查 appKey 是否正确、是否过期；若返回 404，检查 Thing 名称和属性名称是否拼写一致；若返回 403，说明密钥权限不足，需要回到 Application Keys 中补充权限。

接下来测试写入。向同一属性写入一个模拟值，例如 26.5：

curl -X PUT \
  "http://192.168.1.100:8080/Thingworx/Things/TestDevice/Properties/Temperature" \
  -H "appKey: 3f7a9c2e-1b4d-4e8a-9c6f-2d5e8a1b7c30" \
  -H "Content-Type: application/json" \
  -d "{\"Temperature\": 26.5}"

写入成功后，再次执行读取命令，应返回 {"Temperature": 26.5}。这一读一写构成最小闭环，证明平台与外部数据源之间的双向通道已经建立。如果设备侧是真实 PLC 或传感器，还需要在网关或 Edge 中配置对应的地址映射，使 Temperature 属性与设备寄存器或标签绑定，再重复上述读写测试。

四、常见问题与排查要点

连接测试阶段最容易出现的问题集中在三处：密钥、权限和网络。密钥问题表现为 401，通常是因为复制时遗漏字符、密钥已过期或请求头名称写错（必须是 appKey，大小写敏感）。权限问题表现为 403，需要在 Application Keys 的 Permissions 中确认目标 Thing 和属性是否在授权范围内。网络问题表现为连接超时或拒绝，需检查平台服务是否监听正确网卡、防火墙是否放行、客户端与服务器是否在同一网段。

此外，若使用 HTTPS 访问，需注意证书是否受信任；自签名证书在 curl 中可加 -k 跳过校验，但生产环境应导入正式证书。若设备侧通过 Kepware 接入，还需确认 Channel、Device、Tag 三层配置与 ThingWorx 中的属性映射一致，否则会出现“平台能读但值不变”的情况。

测试用的密钥和示例 IP、端口仅用于教学演示，实际部署时应替换为真实环境参数，并避免将密钥硬编码在脚本或前端代码中。

完成本节后，你已具备一个可用的 ThingWorx 开发环境，并验证了平台与设备数据源之间的基本读写通路。后续的建模、可视化与告警配置都将建立在这条通路之上。