认证与用户管理

FastBee 使用本地账户保护 Web 页面和设备 API。登录成功后，设备通过 HttpOnly Cookie 维持会话；脚本也可在登录请求中声明 API 客户端并读取返回的会话 ID。

基本操作

1. 使用设备登录页输入用户名和密码。
2. 首次部署后立即修改默认管理员密码。
3. 自动化脚本应复用登录响应中的 Cookie，不要并发创建大量会话。
4. 页面出现连续 401 时重新登录；不要把认证失效误判为网络或内存故障。

登录、退出和修改本人密码属于核心认证能力。用户列表、添加用户和账户解锁属于可选的 userAdmin 功能；未编译或未启用时，对应菜单和 API 不可用。

密码与会话

• 新密码使用 PBKDF2-HMAC-SHA256 保存，默认 20,000 次迭代、16 字节随机盐和 32 字节派生密钥。
• 旧格式密码在验证成功后会自动迁移到 PBKDF2 格式。
• 默认密码长度为 6-32 个字符；生产部署建议使用更长且不重复的密码。
• 默认连续登录失败 5 次会锁定账户约 5 分钟，也可由已登录用户通过用户管理页面解锁。
• 默认会话超时为 1 小时，最多保留有限数量的活动会话。
• 默认会话只保存在内存中，设备重启后需要重新登录。

安全策略保存在 /config/auth.json，用户记录保存在 /config/users.json。当前固件没有单独的认证策略 REST 配置路由；不要按旧文档调用不存在的接口。

认证 API

方法	路径	说明
POST	/api/auth/login	登录并设置会话 Cookie
GET	/api/auth/session	查询当前会话；未登录时仍返回 sessionValid: false
POST	/api/auth/logout	注销当前会话并清除 Cookie
POST	/api/auth/change-password	修改当前用户密码，成功后使该用户现有会话失效

登录和修改密码接口使用表单参数：

$session = New-Object Microsoft.PowerShell.Commands.WebRequestSession

Invoke-WebRequest -Uri "http://<device-sta-ip>/api/auth/login" `
  -Method POST -WebSession $session `
  -Body @{ username = "admin"; password = "<current-password>" }

Invoke-WebRequest -Uri "http://<device-sta-ip>/api/auth/change-password" `
  -Method POST -WebSession $session `
  -Body @{ oldPassword = "<current-password>"; newPassword = "<new-password>" }

密码校验由独立任务执行，避免阻塞网络线程。设备资源不足或同时登录过多时可能返回 503 和 Retry-After，客户端应等待后串行重试。

用户管理 API

以下接口需要有效会话，并且 userAdmin 必须处于 active 状态：

方法	路径	说明
GET	/api/users?page=1&limit=20	分页查询用户
GET	/api/users/{username}	查询单个用户
POST	/api/users	新增用户，参数为 username、password，可选 description
POST	/api/users/update	更新密码、启用状态或描述
DELETE	/api/users/{username}	删除用户；不能删除当前登录账户
GET	/api/users/online	查询活动会话
POST	/api/users/reset-password	重置指定用户密码并使其会话失效
POST	/api/users/unlock-account	清除指定用户的登录失败锁定

当前用户模型不提供 admin/operator 角色字段。所有用户管理接口都以“已认证”作为访问条件，部署时应限制设备管理网络的访问范围。

常见问题

现象	判断与处理
登录返回 401	核对用户名、密码和大小写；连续失败后等待锁定解除
登录返回 503	设备内存或登录任务槽繁忙，按 Retry-After 串行重试
API 返回 401	会话 Cookie 缺失或过期，重新登录并复用新 Cookie
修改密码后立即退出	正常行为；密码修改会注销该用户现有会话
用户管理菜单不显示	在功能配置中检查 userAdmin 是否已编译并启用
忘记唯一账户密码	按设备恢复流程执行出厂重置或重新烧录；操作会清除现有配置，先评估数据影响

安全建议

• 不要在文档、公开配置包或 Git 历史中保存真实密码和会话 ID。
• 生产网络应限制设备 Web 管理面的可访问范围。
• HTTP 管理页本身不等同于 HTTPS；MQTTS 只加密 MQTT 链路，不能为 Web 页面提供 TLS。
• 配置导出前检查 auth.json 等敏感文件，公开示例只保留占位信息。

相关文档

• 功能配置
• API 参考
• 稳定性与发布检查清单