IAMMETER 电能表本地 Admin Security：用户指南

Local Admin Security 模块适用于固件 i.91.065.3 及更高版本。

本页目录

• 用途
• 在 Web 界面中配置 Admin Security
• 无需 Basic Authentication 的 API
• API 参考
• 密码恢复的工作原理
• 使用场景
  • 场景 1：设置管理员用户名和密码
  • 场景 2：使用 Basic Authentication 访问受保护 API
  • 场景 3：忘记密码后恢复访问

用途

Local Admin Security 模块保护设备的本地 Web 界面与敏感本地 API，防止未经授权的访问。

启用此功能后，以下操作需要管理员用户名和密码：

• WEM API Test 页面提供的所有 Set API；
• 返回敏感配置数据或执行敏感操作的 GET API；
• 本地 OTA 固件上传与升级操作。

这包括修改网络或上传设置、更新固件、重启设备、恢复出厂设置，以及修改其他敏感配置参数。

该模块提供：

• 可配置的管理员凭据；
• 受保护本地 API 的 HTTP Basic Authentication；
• 通过 Web 界面或 API 修改凭据；
• 忘记管理员密码时，基于 Ed25519 签名的恢复流程。

为兼容早期固件，此功能默认关闭。必须先启用并配置，访问保护才会生效。

当前本地 Web 界面使用 HTTP。HTTP Basic Authentication 只是对凭据编码，并不加密。除非通过额外的安全传输机制访问设备，否则请仅在可信的本地网络中使用此功能。

在 Web 界面中配置 Admin Security

1. 在浏览器中打开设备 IP 地址。
2. 选择 Security 选项卡。
3. 输入管理员用户名。
4. 输入并确认管理员密码。
5. 选择 Enable Admin Security。

用户名和密码必须符合以下规则：

• 长度为 1 至 32 个字符；
• 仅允许可见 ASCII 字符；
• 不允许冒号（:）、双引号（"）或反斜杠（\）。

启用 Admin Security 后，访问受保护页面或 API 时，浏览器会显示认证提示。请输入已配置的管理员用户名和密码。

Security 选项卡还可用于：

• 修改管理员用户名和密码；
• 确认管理员认证是否启用；
• 启用或关闭端口 502 上的 Modbus/TCP 服务；
• 启用或关闭 SSDP 发现；
• 使用当前凭据认证后关闭 Admin Security。

修改 Modbus/TCP 或 SSDP 服务状态后需要重启设备。如果早期固件从未保存过这些设置，两项服务默认开启，以保持向后兼容。

浏览器可能会缓存该设备地址的 Basic Authentication 凭据。修改密码后，浏览器可能先重试旧凭据，再显示新的认证提示。关闭所有浏览器窗口或使用隐私浏览窗口也可以触发重新登录。

无需 Basic Authentication 的 API

以下端点无需 Basic Authentication 请求头即可访问，以便 Web 界面加载基本设备信息，并使签名恢复流程能够运行：

当 Admin Security 当前处于关闭状态时，POST /api/admin/enable 也可以无需 Basic Authentication 调用，因为它用于初始设置。如果 Admin Security 已启用，则必须提供当前有效的管理员凭据，该端点才能修改或关闭安全配置。

静态 Web 界面文件及其他非 /api/ 的 GET 资源不是 API 端点，仍可公开读取。启用 Admin Security 后，其他所有本地 API 端点均视为受保护，包括全部 Set API、敏感 GET API 和 OTA 固件操作。

API 参考

GET /api/admin/status

返回当前 Admin Security 状态，无需认证。

响应示例：

{
  "enabled": 1,
  "hasPassword": 1,
  "recoverySupported": 1,
  "modbusTcpEnabled": 1,
  "ssdpEnabled": 1
}

字段：

• enabled：启用 Admin Security 时为 1，否则为 0。
• hasPassword：已配置管理员凭据时为 1。
• recoverySupported：固件支持管理员签名恢复时为 1。
• modbusTcpEnabled：端口 502 上的 Modbus/TCP 服务启用时为 1。
• ssdpEnabled：SSDP 发现启用时为 1。

POST /api/admin/enable

启用或关闭 Admin Security。

启用 Admin Security：

POST /api/admin/enable
Content-Type: application/json

{
  "enable": 1,
  "username": "admin",
  "password": "ExamplePassword"
}

使用 curl 的示例：

curl -X POST "http://<device-ip>/api/admin/enable" \
  -H "Content-Type: application/json" \
  -d '{"enable":1,"username":"admin","password":"ExamplePassword"}'

关闭 Admin Security：

POST /api/admin/enable
Authorization: Basic <base64-credentials>
Content-Type: application/json

{
  "enable": 0
}

如果 Admin Security 已启用，调用此 API 需要当前有效的 Basic Authentication 凭据。

示例：

curl -X POST "http://<device-ip>/api/admin/enable" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '{"enable":0}'

POST /api/admin/password

修改管理员用户名和密码。启用 Admin Security 后，此 API 受保护。

POST /api/admin/password
Authorization: Basic <current-base64-credentials>
Content-Type: application/json

{
  "username": "newadmin",
  "password": "NewExamplePassword"
}

示例：

curl -X POST "http://<device-ip>/api/admin/password" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '{"username":"newadmin","password":"NewExamplePassword"}'

请求成功后，后续受保护请求应使用新凭据。

GET /api/admin/check

检查提供的 Basic Authentication 凭据是否有效。

curl -u admin:ExamplePassword \
  "http://<device-ip>/api/admin/check"

成功响应：

{
  "successful": 1
}

缺少凭据或凭据无效时，返回 HTTP 401 Unauthorized。

GET /api/admin/recovery_challenge

生成设备专属的一次性恢复 payload。此端点本身不重置凭据，因此无需认证。

响应示例：

{
  "successful": 1,
  "alg": "ed25519",
  "payload": "reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE"
}

需要恢复管理员访问时，须将返回的 payload 提交给 IAMMETER。

请求新的 challenge 会使旧 challenge 失效。成功恢复或设备重启后，challenge 也会失效。

POST /api/admin/recovery

提交恢复 payload 及 IAMMETER 提供的 Ed25519 签名。

POST /api/admin/recovery
Content-Type: application/json

{
  "payload": "reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE",
  "signature": "128-hex-character-ed25519-signature"
}

示例：

curl -X POST "http://<device-ip>/api/admin/recovery" \
  -H "Content-Type: application/json" \
  -d '{"payload":"reset_admin|DEVICE_SN|DEVICE_MAC|ONE_TIME_NONCE","signature":"<signature-from-IAMMETER>"}'

签名验证成功后，设备清除本地管理员凭据并关闭 Admin Security。之后即可配置新的管理员用户名和密码。

如果设备没有足够的空闲内存进行签名验证，API 会返回类似以下的响应：

{
  "successful": 0,
  "message": "low memory, please change to standalone mode",
  "freeMemory": 18000,
  "minFreeRequired": 28000
}

此时，请降低内存占用，并在重试前请求新的恢复 challenge。如果无法提供密码且无法更改工作模式，请重启设备，在 MQTTS 或 HTTPS 连接消耗额外内存之前完成恢复。

密码恢复的工作原理

恢复设计避免添加无需认证的恢复出厂设置命令，以防绕过管理员保护。

该流程使用 Ed25519 公私钥对：

• 设备固件仅包含 IAMMETER 恢复公钥；
• 对应私钥由 IAMMETER 保管，不存储在设备中；
• 设备生成的 payload 包含所请求的操作、设备 SN、设备 MAC 和一次性 nonce；
• IAMMETER 使用恢复私钥对该 payload 原样签名；
• 设备使用内置公钥验证签名；
• 只有针对当前设备及当前 nonce 的有效签名，才能清除管理员配置。

nonce 只存储在 RAM 中。设备重启、请求另一个 challenge 或成功恢复一次后，它都会失效。因此，旧 payload 和签名不能在后续恢复会话中复用。

使用场景

场景 1：设置管理员用户名和密码

最简单的方法是使用 Web 界面：

1. 打开 http://<device-ip>/。
2. 打开 Security 选项卡。
3. 输入新的管理员用户名和密码。
4. 确认密码。
5. 启用 Admin Security。

也可以通过 POST /api/admin/enable 执行相同操作：

curl -X POST "http://<device-ip>/api/admin/enable" \
  -H "Content-Type: application/json" \
  -d '{"enable":1,"username":"admin","password":"ExamplePassword"}'

验证结果：

curl "http://<device-ip>/api/admin/status"

场景 2：使用 Basic Authentication 访问受保护 API

对于后续每个受保护请求，在 HTTP Basic Authentication 请求头中发送管理员用户名和密码。

请求头的值构造如下：

Authorization: Basic Base64(username:password)

例如，先组合凭据 admin:ExamplePassword，然后进行 Base64 编码。大多数 HTTP 客户端会自动完成此操作。

使用 curl：

curl -u admin:ExamplePassword \
  "http://<device-ip>/api/getadv"

显式指定请求头：

TOKEN=$(printf '%s' 'admin:ExamplePassword' | base64)

curl "http://<device-ip>/api/getadv" \
  -H "Authorization: Basic ${TOKEN}"

对于 JSON POST 请求：

curl -X POST "http://<device-ip>/api/setadv" \
  -u admin:ExamplePassword \
  -H "Content-Type: application/json" \
  -d '<setadv-json-body>'

管理员在 Basic Authentication 提示框中输入凭据后，浏览器会自动处理此请求头。

当前 Web 界面通过 POST /api/ota_successful.html 上传固件。旧端点 POST /ota_successful.html 仍可供早期 Web 界面版本与外部工具使用。启用 Admin Security 时，两个端点都需要 Basic Authentication。

关闭认证提示框后，Web 界面各选项卡的行为如下：

• Settings 和 Wi-Fi 无法加载受保护的配置 API，并显示管理员认证提示。
• System 仍可显示 SN、MAC 和固件版本，因为这些值来自公开的 /api/monitor 端点。OTA 上传仍受保护。
• Security 仍可显示基本状态，因为 /api/admin/status 是公开端点。凭据修改与服务开关修改仍受保护。

场景 3：忘记密码后恢复访问

设备没有硬件复位按钮。为避免添加可绕过 Admin Security 的免认证重置功能，设备使用带签名、设备专属的恢复机制。

仅在忘记管理员凭据时使用此流程。如果仍知道当前凭据，请从 Security 选项卡或通过 POST /api/admin/password 修改。

查看完整的 Admin Security 密码恢复分步指南

恢复流程如下：

1. 通过 GET /api/admin/recovery_challenge 生成一次性 payload。
2. 登录 IAMMETER Contributor 系统的 Admin Recovery 应用。服务验证您的账号是否有权管理该设备 SN，并返回针对该 payload 的 Ed25519 签名。
3. 将未修改的 payload 和签名提交至 POST /api/admin/recovery。验证成功后，Admin Security 被关闭，原有本地管理员凭据被清除。

恢复完成前，不要重启设备、刷新 challenge 页面或请求另一个 challenge。上述任一操作都会使当前 nonce 失效，必须用新的 payload 重新开始。

专门的恢复指南包含截图、完整 curl 命令、签名被拒绝时的排查方法，以及低内存情况下的恢复步骤。