如何配置 IAMMETER 电能表的 MQTTS 和 HTTPS 证书验证
使用固件 i.91.065.9 及更高版本的 IAMMETER 电能表，在通过 MQTTS 或 HTTPS 上传数据时可以验证服务器证书。这为安全出站连接增加了证书链和服务器主机名验证。
本文聚焦 TLS 信任配置，不涉及 MQTT 主题、JSON payload 或 Home Assistant 发现配置。关于 MQTT 发布流程，请参阅 MQTT 电能表：将 IAMMETER 数据发布到你的 MQTT Broker。
本页目录
- 选择证书验证模式
- 使用要求与重要边界
- 查看当前 TLS 模式
- 选择 builtin 验证
- 选择 none 进行临时诊断
- 上传并选择自定义 CA
- 删除自定义 CA
- 使用 IAMMETER Swagger UI
- 证书验证故障排查
选择证书验证模式
IAMMETER 的 MQTTS 和 HTTPS 客户端支持三种服务器证书验证模式：
| 模式 | 证书链 | 服务器主机名 | 适用场景 |
|---|---|---|---|
builtin |
使用固件内置根 CA 验证 | 验证 | 推荐用于采用受支持证书链的公共服务 |
custom |
使用用户提供的 PEM 根 CA 验证 | 验证 | 私有 PKI、自签名部署或固件未包含的公共根 CA |
none |
不验证 | 不验证 | 仅用于临时兼容性测试或诊断 |
这些设置适用于 IAMMETER 设备作为 TLS 客户端向 MQTTS Broker 或 HTTPS 服务器上传数据的情况，不会为设备本地 Web 服务器启用 HTTPS。
builtin
builtin 是默认模式。尚未保存 TLS 验证设置时采用此模式；删除 TLS CA 配置或将设备恢复出厂设置后，也会恢复此模式。
固件内置以下根 CA：
- DigiCert Global Root G2
- ISRG Root X1
设备同时验证证书链和服务器主机名。MQTTS Broker 或 HTTPS 服务器必须提供可追溯至上述根 CA 之一的证书，且其 Subject Alternative Name（SAN，使用者备用名称）必须匹配配置的服务器地址。
如果上传地址使用 IP，证书 SAN 必须包含完全相同的 IP 地址。DNS 名称不能匹配 IP 地址，即使两者指向同一服务器也不行。
custom
custom 与 builtin 执行相同的证书链和主机名验证，但信任管理员上传的 PEM CA 证书。以下情况可使用：
- 服务器证书由私有 CA 签发；
- 部署使用自签名服务器证书；或者
- 所需公共根 CA 未包含在固件中。
对于私有 PKI，请上传其根 CA 证书。TLS 服务器仍应在握手时发送所需的中间证书。对于自签名服务器证书，可上传该证书作为信任锚，但 SAN 仍必须匹配配置的主机名或 IP 地址。
none
none 仍建立加密 TLS 连接，但不验证证书链或主机名，类似于不进行服务器身份验证的旧版 TLS 行为。
此模式易受中间人攻击。仅应临时用于兼容性测试或诊断，生产环境优先使用 builtin 或 custom。
使用要求与重要边界
TLS CA 配置 API 要求启用本地 Admin Security。每个请求必须通过 HTTP Basic Authentication 携带已配置的管理员用户名和密码。
运行 curl 或 Swagger UI 的电脑必须能访问设备本地 IP。MQTTS 和 HTTPS 客户端共用一个验证模式和一个自定义 CA，因此修改会作用于设备所使用的安全上传模式。
修改 TLS 配置后请重启设备，使出站客户端根据新设置重新创建。
示例使用以下占位值：
DEVICE_IP="192.168.1.80"
ADMIN_USER="admin"
ADMIN_PASSWORD="ExamplePassword1"
请替换为实际设备地址和管理员凭据。
查看当前 TLS 模式
API:
GET /api/tls/ca/status
示例：
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
响应示例：
{
"successful": 1,
"mode": "builtin",
"customCaValid": 0,
"customCaLength": 0,
"customCaSha256": "",
"restartRequiredAfterChange": 1
}
响应会报告所选模式；如已存储自定义 CA，也会报告其长度和 SHA-256 摘要。
选择 builtin 验证
API:
POST /api/tls/ca/select
示例：
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"builtin"}'
收到成功响应后重启设备。
选择 none 进行临时诊断
API:
POST /api/tls/ca/select
示例：
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"none"}'
响应包含服务器证书验证已关闭的警告。更改模式后重启设备，并在诊断结束后切换回 builtin 或 custom。
上传并选择自定义 CA
上传 CA 与选择 custom 是两个独立操作。上传 CA 不会自动改变当前模式。
自定义 CA 文件要求
上传文件必须满足以下全部要求：
- PEM 证书格式；
- 使用原始请求体，不是 JSON，也不是
multipart/form-data； Content-Type: application/x-pem-file；- 长度为 1 至 3072 字节，包含 PEM 头尾、换行和空白字符；
- 包含
-----BEGIN CERTIFICATE-----和-----END CERTIFICATE-----； - 不包含私钥。
3072 字节上限适用于完整 HTTP 请求体。3072 字节 PEM 文件可接受；3073 字节文件会被拒绝。
上传前检查文件大小：
wc -c root-ca.pem
步骤 1：上传 CA
API:
POST /api/tls/ca/upload
示例：
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/upload" \
-H "Content-Type: application/x-pem-file" \
--data-binary @root-ca.pem
成功响应示例：
{
"successful": 1,
"length": 1939,
"sha256": "64-character SHA-256 digest",
"message": "CA uploaded; select custom mode and restart"
}
设备将 CA 存储在多个 KV 块中，并在标记有效前验证保存长度和 SHA-256 摘要。写入中断不会替换此前有效的 CA。
步骤 2：选择 custom
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/select" \
-H "Content-Type: application/json" \
-d '{"mode":"custom"}'
未存储有效自定义 CA 时，设备会拒绝该请求，不会悄悄回退到 none。
步骤 3：重启并验证
从设备本地 Web 界面重启，或使用受保护的重启 API：
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/restart?reset=false"
设备重新连接后，再次查询状态：
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
"http://$DEVICE_IP/api/tls/ca/status"
确认 mode 为 custom、customCaValid 为 1，且报告的长度和 SHA-256 摘要与上传证书一致。
删除自定义 CA
API:
POST /api/tls/ca/delete
示例：
curl --user "$ADMIN_USER:$ADMIN_PASSWORD" \
-X POST "http://$DEVICE_IP/api/tls/ca/delete"
删除自定义 CA 也会将模式恢复为 builtin。删除后请重启设备。
使用 IAMMETER Swagger UI
无需手写 curl 命令，也能测试同样的 API：
IAMMETER WEM API Test - TLS CA
- 在能够访问设备本地 IP 的电脑上打开 WEM API Test 页面。
- 输入设备地址，例如
192.168.1.80，并选择 Apply。 - 选择 Authorize，输入管理员用户名和密码。
- 打开 TLS CA - Authenticated 分组。
- 使用
GET /api/tls/ca/status查看当前配置。 - 按需执行上传、选择或删除操作。
- 更改模式或证书后重启设备。
Swagger 页面在浏览器中运行，从该电脑直接向 IAMMETER 设备发送请求，不通过 IAMMETER Cloud 代理，因此浏览器必须能直接连接设备 IP。
证书验证故障排查
admin security required
使用 TLS CA API 前请启用 Local Admin Security。这些设置不能匿名修改。
custom CA is missing or invalid
选择 custom 前，先成功上传有效的 PEM CA。查询 /api/tls/ca/status，确认 customCaValid 为 1。
在 builtin 或 custom 模式下 TLS 连接失败
请检查以下各项：
- 配置的主机名或 IP 是否匹配证书 SAN；
- 证书当前是否有效，设备时间是否正确；
- 服务器是否发送所需中间证书；
- 所选根 CA 是否签发或最终信任服务器证书；
- 修改 TLS 配置后是否已重启设备。
TLS 在 none 模式下正常，但在验证模式下失败
这通常表示证书链、主机名、有效期或设备时钟存在问题。一直启用 none 只是隐藏身份验证失败，并未解决问题。请修正证书部署，或上传适当的根 CA 并使用 custom。
