OPC/goauto
2
0
Fork 0
Code Issues 192 Pull Requests Actions Packages Projects Releases Wiki Activity

[Task][T03] 实现设备自注册、令牌认证与吊销接口 #5

New Issue
Closed
opened 2026-08-14 14:24:35 +08:00 by ila · 2 comments
ila commented 2026-08-14 14:24:35 +08:00
Owner
Copy Link
Copy Source

基本信息

要解决的问题

让 Android 客户端无需注册码或人工审核即可完成设备注册，同时防止无凭据客户端覆盖已有设备。

注册流程

  1. Android 首次安装生成 UUID installId 并持久化。
  2. 客户端向 POST /api/agent/v1/register 提交 installId、设备名称、型号、Android/Agent/PDD 版本。
  3. installId 不存在时，服务端直接创建并启用设备，返回 deviceId 和仅展示一次的 deviceToken。
  4. installId 已存在时，只有携带该设备有效 Token 才允许更新信息；没有有效 Token 返回冲突，不签发新 Token。
  5. 管理员可以停用设备和吊销 Token；重新启用或重新签发另建明确管理动作。

明确不做

  • 不实现注册码、注册审批、待审核状态或硬件指纹。
  • 不允许仅凭已知 installId 接管已有设备。

验收标准

  • 首次提交后设备立即处于已注册/启用状态并出现在设备列表。
  • 重复的已认证注册幂等更新设备信息。
  • 相同 installId 无 Token 或错误 Token 不能覆盖或获取新 Token。
  • Token 明文只返回一次，不入库、不进日志。
  • 注册接口具备 HTTPS 部署约束、基础限流和 requestId 幂等测试。

参考文档

  • docs/08-agent-api-contract.md
## 基本信息 - 上级 Epic: #1 - 所属 MVP: #2 - 任务编号: T03 - 前置依赖: #3、#4 - 原始需求确认: 2026-08-14 ## 要解决的问题 让 Android 客户端无需注册码或人工审核即可完成设备注册，同时防止无凭据客户端覆盖已有设备。 ## 注册流程 1. Android 首次安装生成 UUID `installId` 并持久化。 2. 客户端向 `POST /api/agent/v1/register` 提交 `installId`、设备名称、型号、Android/Agent/PDD 版本。 3. `installId` 不存在时，服务端直接创建并启用设备，返回 `deviceId` 和仅展示一次的 `deviceToken`。 4. `installId` 已存在时，只有携带该设备有效 Token 才允许更新信息；没有有效 Token 返回冲突，不签发新 Token。 5. 管理员可以停用设备和吊销 Token；重新启用或重新签发另建明确管理动作。 ## 明确不做 - 不实现注册码、注册审批、待审核状态或硬件指纹。 - 不允许仅凭已知 installId 接管已有设备。 ## 验收标准 - 首次提交后设备立即处于已注册/启用状态并出现在设备列表。 - 重复的已认证注册幂等更新设备信息。 - 相同 installId 无 Token 或错误 Token 不能覆盖或获取新 Token。 - Token 明文只返回一次，不入库、不进日志。 - 注册接口具备 HTTPS 部署约束、基础限流和 requestId 幂等测试。 ## 参考文档 - `docs/08-agent-api-contract.md`
ila changed title from [Task][T03] 实现设备注册、令牌认证与吊销接口 to [Task][T03] 实现设备自注册、令牌认证与吊销接口 2026-08-14 15:52:55 +08:00
ila commented 2026-08-14 16:59:26 +08:00
Author
Owner
Copy Link
Copy Source

T03 实现完成，保持开启等待用户验收。

实现：

  • POST /api/agent/v1/register：新 installId 立即注册并仅首次返回明文 Token。
  • 已有 installId 只有携带有效 Bearer Token 才能更新设备信息；错误、缺失或已吊销 Token 返回 409。
  • 相同 requestId 重放幂等返回设备身份，不重复签发 Token、不覆盖元数据。
  • Token 使用 256 位安全随机值，数据库只保存 SHA-256 摘要，响应设置 Cache-Control: no-store。
  • 管理端新增停用和 Token 吊销动作，复用 go-admin JWT 与角色授权；吊销同时停用。
  • 生产模式 HTTPS 门禁；代理头仅在显式 GOAUTO_TRUST_FORWARDED_PROTO=true 时信任。
  • 注册请求 64 KiB 上限、未知字段拒绝、每直连 IP 30 次/分钟基础限流。
  • 新增设备注册字段兼容迁移并同步共享 API 契约。

验证：

  • 首次注册、一次性 Token、requestId 重放、防 installId 接管、认证更新、停用/吊销、UUID 校验、HTTPS 和限流测试通过。
  • go test -race ./app/goauto/device：通过。
  • go test ./...：通过。
  • go build ./...：通过。

未实现重新启用、重新签发 Token、心跳或设备页面业务。

T03 实现完成，保持开启等待用户验收。 实现： - `POST /api/agent/v1/register`：新 installId 立即注册并仅首次返回明文 Token。 - 已有 installId 只有携带有效 Bearer Token 才能更新设备信息；错误、缺失或已吊销 Token 返回 409。 - 相同 requestId 重放幂等返回设备身份，不重复签发 Token、不覆盖元数据。 - Token 使用 256 位安全随机值，数据库只保存 SHA-256 摘要，响应设置 `Cache-Control: no-store`。 - 管理端新增停用和 Token 吊销动作，复用 go-admin JWT 与角色授权；吊销同时停用。 - 生产模式 HTTPS 门禁；代理头仅在显式 `GOAUTO_TRUST_FORWARDED_PROTO=true` 时信任。 - 注册请求 64 KiB 上限、未知字段拒绝、每直连 IP 30 次/分钟基础限流。 - 新增设备注册字段兼容迁移并同步共享 API 契约。 验证： - 首次注册、一次性 Token、requestId 重放、防 installId 接管、认证更新、停用/吊销、UUID 校验、HTTPS 和限流测试通过。 - `go test -race ./app/goauto/device`：通过。 - `go test ./...`：通过。 - `go build ./...`：通过。 未实现重新启用、重新签发 Token、心跳或设备页面业务。
ila commented 2026-08-15 08:58:25 +08:00
Author
Owner
Copy Link
Copy Source

用户已于 2026-08-15 明确验收通过，现关闭工单。

用户已于 2026-08-15 明确验收通过，现关闭工单。
ila closed this issue 2026-08-15 08:58:26 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/goauto#5