feat: add single-admin application onboarding and token rotation

2026-09-27 10:18:31 +08:00
parent 98ff028228
commit 87aa710013
24 changed files with 1341 additions and 25 deletions
--- a/docs/08-development-plan.md
+++ b/docs/08-development-plan.md
@@ -274,3 +274,11 @@ A04派发已提交而消息尚未到达Worker的精确进程故障已通过[专
 - 提供 orbit-test-services 共享网络与 http://orbit-test:8080 地址，固定可配置子网，解决本机默认 Docker 地址池耗尽的问题。
 - 已验证：真实容器构建/迁移/零外键/权限收紧；浏览器登录协议和未登录跳转；另一容器运行 Worker 完成三项任务及事件 ACK 重报；定时/流程示例；重复部署与 Orbit/MySQL 停止再启动后原任务、身份保持。
 - 接入、账号位置、启动/停止及网络声明见[本地部署手册](../deploy/local/README.md)。这是本地联调环境，不改变平台或 SDK 协议。
+
+### 单管理员应用接入（2026-09-27）
+
+- 新增独立应用接入页：应用/环境分页、队列及凭据详情、选择业务能力新建应用、重新生成 Token、复制/下载 SDK 配置；沿用单管理员，不引入角色系统。
+- 新增 Cookie 专用管理接口，部署显式指定唯一登录名；同事务校验管理员与有效会话，写入要求同源与专用请求头。Token 只在生成时交付，数据库只存摘要。
+- 新建资源/审计/幂等回执同事务，轮换复用现有凭据 ID 与轮换核心。请求不明保留原操作，原样重报；原有任务、订阅和交付身份不变。无新表、无外键、无 SDK 协议修改。
+- 已通过定向 MySQL 并发创建、幂等冲突、重名回滚、轮换/旧 Token 拒绝、退出失效与审计脱敏；真实 HTTP 已验证创建、轮换后原任务和订阅可读。标准/全量集成和页面验收记录见[本批报告](reports/console-applications.md)。
+- [页面使用、HTTP 接口及故障恢复](api/console-applications.md)。
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -66,3 +66,5 @@ P1 业务接口已遵守下述约定，后续接口继续沿用：
 [流程实例筛选分页与权限](workflow-queries.md)已接入，固定筛选沿游标分页，覆盖未执行分支的全部队列权限。

 - [周期归档与作业管理](archive-scheduler.md)
+
+- [控制台应用接入与 Token 管理](console-applications.md)
--- a/docs/api/authentication.md
+++ b/docs/api/authentication.md
@@ -2,6 +2,8 @@

 状态：P1 已实现。业务接口每次在数据库事务内校验凭据摘要、撤销/到期、应用与命名空间启停，以及动作和队列范围。授权与写入使用同一事务；管理变更与已经获得授权锁的请求按事务先后次序生效。

+已提供单管理员[应用接入页面](console-applications.md)：新建应用、查看队列与凭据、重新生成 Token、复制 SDK 配置。下方 CLI 继续用于首次安装及运维。
+
 ## 初始化一个新的接入应用

 前置：专用 MySQL 数据库已经执行 orbit-migrate up，使用持有初始化权限的数据库管理连接。此命令创建新应用、命名空间、队列和凭据，不会覆盖现有同名应用。
@@ -44,7 +46,7 @@ secret-manager read orbit/console-admin-password | \

 ## 轮换与撤销

-凭据轮换和撤销只允许在受保护的数据库管理环境执行，不提供公网管理接口。轮换保留 `credential_id`，因此订阅和 Worker 实例的授权绑定仍指向同一记录；新的 Worker 进程必须按现有进程身份规则重新连接，旧令牌不能再通过任何 API 或 WSS 认证。平台不会批量改写在途任务、交付记录或历史会话证据。
+管理 CLI 在受保护的数据库管理环境执行；控制台也可由部署指定的单管理员轮换凭据，见[应用接入](console-applications.md)。业务 SDK 不开放凭据管理，撤销仍由 CLI 执行。轮换保留 `credential_id`，因此订阅和 Worker 实例的授权绑定仍指向同一记录；新的 Worker 进程必须按现有进程身份规则重新连接，旧令牌不能再通过任何 API 或 WSS 认证。平台不会批量改写在途任务、交付记录或历史会话证据。

 先读取脱敏状态和当前版本：

--- a/docs/api/console-applications.md
+++ b/docs/api/console-applications.md
@@ -0,0 +1,124 @@
+# 控制台应用接入
+
+单管理员在「应用接入」页面创建应用、初始队列与 SDK 凭据，查看环境、队列、权限和有效期，重新生成 Token，复制或下载 `.env` 配置。数据库只保存 Token 摘要：完整 Token 仅在新建或轮换时交付，列表和详情不能反查旧秘密。
+
+## 1. 启用和使用
+
+部署配置指定唯一有跨应用接入管理权限的控制台登录名：
+
+```sh
+export ORBIT_CONSOLE_APPLICATION_ADMIN=admin
+```
+
+该账号必须已经通过 bootstrap 或 console-user create 创建。配置为空时所有应用接入管理请求返回 403，不会自动提升已有账号；多节点使用相同配置。继续使用单管理员，不引入角色管理系统。现有控制台账号与会话的绑定凭据仍须有效；到期前可在本页轮换。轮换 SDK Token 不改变浏览器独立会话秘密。
+
+本地 Compose 已为 `admin` 配置该入口，访问 `http://127.0.0.1:18080/console/#/applications`。
+
+1. 点击「新建应用」，填写应用名称、环境、命名空间、初始队列和操作原因。
+2. 选择 Worker、结果订阅、定时、流程等需要的能力及有效期。基础权限包含任务提交/查询/取消、队列读取/管理。
+3. 创建成功后复制或下载完整 `.env`，交给该应用的服务端配置。默认地址使用当前页面来源，详情中可改为容器地址或部署域名。
+4. 已接入应用可以随时查看元数据和配置模板。模板中的 Token 是占位值，必须替换成已经保存的原 Token。
+5. 「重新生成 Token」保留 application_id、namespace_id、credential_id、队列、任务和订阅；旧 Token 在轮换事务提交后不能再通过业务认证，服务端配置需要同步更新。
+
+环境与命名空间形成隔离边界。不同应用应分别创建；同一应用的多个命名空间在列表中分别展示。页面目前支持新建应用及其初始队列，未提供应用删除、身份迁移、跨应用任务列表或现有应用新增命名空间的表单；已有 CLI 的 `--application-id` 仍可增加命名空间，队列 SDK 可增加同范围队列。接入管理页不会改变其他业务页面的账号默认范围。
+
+## 2. 路由与认证
+
+这些是浏览器管理端接口，不属于业务 SDK。只接受有效的 `orbit_console_session` HttpOnly Cookie，并在数据库事务中重新核验部署指定的管理员账号和会话；即使 SDK 凭据拥有全部业务权限也不能访问。
+
+| 方法与路径 | 用途 |
+| --- | --- |
+| `GET /console/applications?after=<namespace_id>` | 按命名空间 ID 升序读取 50 条接入范围，返回 `items`、可选 `next`；`after` 为排他起点 |
+| `GET /console/applications/{namespace_id}` | 应用/环境详情、最多 100 个队列和 100 张脱敏凭据；超出返回 `truncated=true` |
+| `POST /console/applications/prepare` | 校验意图，生成固定操作 ID、资源 ID、Token、绝对到期时间；不创建资源、不轮换秘密 |
+| `POST /console/applications/apply` | 提交准备结果，原样重报返回原脱敏回执 |
+
+POST 必须有 `Content-Type: application/json` 和 `X-Orbit-Console: 1`；浏览器 Origin 必须匹配当前主机，拒绝跨站 Fetch Metadata，不提供跨域授权。响应禁止缓存，成功信封为 `{"data": ...}`。未知字段、重复 JSON 键、显式 null 和错误类型被拒绝，正文上限 512 KiB。
+
+## 3. 新建应用
+
+prepare 请求：
+
+```json
+{
+  "kind": "CREATE",
+  "application": "order-service",
+  "namespace": "default",
+  "environment": "test",
+  "queue": "orders",
+  "capabilities": ["worker", "events", "schedules", "workflows"],
+  "expected_revision": "0",
+  "valid_days": 30,
+  "reason": "接入订单服务"
+}
+```
+
+名称以字母或数字开头，后续只允许字母、数字、`_ . : -`，environment 最长 32，其余最长 128。valid_days 为 1–365 的整数；reason 非空、最多 1024 个 Unicode 字符，不含换行或 NUL。capabilities 可选 `worker`、`events`、`schedules`、`workflows`、`recovery`、`resources`，不可重复。新建不传 namespace_id / credential_id，expected_revision 省略或为字符串 `"0"`。
+
+prepare 响应 data 为固定操作对象：
+
+```json
+{
+  "input": {"kind":"CREATE","application":"order-service","namespace":"default","environment":"test","queue":"orders","capabilities":["worker","events"],"expected_revision":"0","valid_days":30,"reason":"接入订单服务"},
+  "operation_id": "11111111111111111111111111111111",
+  "application_id": "22222222222222222222222222222222",
+  "namespace_id": "33333333333333333333333333333333",
+  "queue_id": "44444444444444444444444444444444",
+  "credential_id": "55555555555555555555555555555555",
+  "token": "服务端生成的完整 Token",
+  "expires_at": "2026-10-27T02:00:00Z"
+}
+```
+
+以上是结构示意，ID、令牌及时间以服务端返回为准。将 **data 整体原样** POST 到 apply，不包 `data` 外层。应用、额度、命名空间、队列、凭据摘要、审计和幂等回执在同一事务提交。初始队列并发 4、开始速率 10/秒，沿用 bootstrap 默认策略；凭据队列范围为新命名空间的全部队列。重名应用返回 409，不覆盖原资源。
+
+## 4. 重新生成 Token
+
+prepare 请求：
+
+```json
+{
+  "kind": "ROTATE",
+  "namespace_id": "33333333333333333333333333333333",
+  "credential_id": "55555555555555555555555555555555",
+  "expected_revision": "1",
+  "valid_days": 30,
+  "reason": "更新接入凭据"
+}
+```
+
+expected_revision 为读取到的字符串版本。只允许上述轮换字段，不混入新应用名称或能力组。准备对象包含原 application_id / namespace_id / credential_id，没有 queue_id。apply 复用原有凭据轮换事务：替换秘密摘要与到期时间，版本加一，保存脱敏回执及人类账号审计；权限组不改变。已撤销的凭据禁止轮换。
+
+apply 成功 data：
+
+```json
+{
+  "operation_id": "11111111111111111111111111111111",
+  "application_id": "22222222222222222222222222222222",
+  "namespace_id": "33333333333333333333333333333333",
+  "credential_id": "55555555555555555555555555555555",
+  "revision": "2",
+  "deduplicated": false
+}
+```
+
+## 5. 超时、重复和审计
+
+- 页面提交前把整个固定操作保留在当前内存；请求超时或结果未知时，按钮变成「重试确认」，重用同一份内容。不能再次 prepare 来代替核对。
+- 页面允许「保存待核对操作」下载私密 JSON；含真实 Token，应放到受限目录。恢复时登录同一管理员后，向 apply 发送该文件正文。不要把 Cookie 或操作文件提交 Git，也不要放到 URL。
+- 关闭/刷新页面会丢失内存中的 Token，页面会提醒先保存。若新建已经成功、交付内容未保存，可从应用列表重新生成同一凭据的 Token；不要再次创建同名应用。
+- 原操作返回的回执是历史快照，可能已被后续轮换替代。页面会重新读取当前凭据版本后才展示配置。
+- 管理审计主体是 `console:<user_id>`；正文只有权限、资源 ID、到期时间等元数据。列表、审计、幂等回执和业务记录都不保存秘密原文。
+- 当前管理员退出、会话过期或账号停用后不能重放管理操作。SDK Token 撤销/到期与控制台登录资格沿用既有账号绑定约束。
+
+| 错误 | HTTP | 处理 |
+| --- | --- | --- |
+| UNAUTHENTICATED | 401 | 登录有效控制台账号 |
+| PERMISSION_DENIED | 403 | 核对唯一管理员配置、会话及同源请求 |
+| INVALID_ARGUMENT | 400 | 核对字段、能力组、固定身份及有效期 |
+| NOT_FOUND | 404 | 核对命名空间/凭据是否存在 |
+| STATE_CONFLICT | 409 | 应用名称已存在、凭据已撤销或版本已变更；读取当前状态 |
+| IDEMPOTENCY_CONFLICT | 409 | 原操作内容被修改，保留原始操作核对 |
+| 数据库/网络故障 | 5xx / 网络错误 | 不假定失败，保留原操作重报 |
+
+可重复运行的真实 HTTP 场景见 [test-console-applications.py](../../scripts/test-console-applications.py)，标准容器入口 `make console-e2e` 同时验证此链路。基础 SDK 使用方式见 [SDK 接入](../sdk/README.md)。
--- a/docs/console.md
+++ b/docs/console.md
@@ -77,3 +77,7 @@ export ORBIT_CONSOLE_QUEUE_ID='queue_xxx'
 控制台不直接访问数据库，也不绕过业务凭据权限。登录会话只保存令牌摘要，服务端每次请求都会校验账号、会话、命名空间、应用启停和凭据权限。取消和人工重试会使用当前任务版本生成一次性幂等键；网络结果不明时不要重复点击，应使用原始操作身份通过 API/SDK 核对。`NEEDS_REVIEW` 任务仍须使用带证据的核查 API/SDK 完成最终裁决。控制台账号绑定业务凭据，不自动获得跨命名空间权限；不支持跨命名空间聚合，不代替平台的权限与审计 API。

 不能把业务 Token 长期放进浏览器本地存储，也不能让控制台直连 MySQL。计划版本发布、跨命名空间管理身份和其他高风险写操作仍应通过受保护 API/SDK 设计后再接入页面。流程恢复入口只调用已经定义的恢复 API，不自动猜测结果、不替操作者补齐证据，也不把冲突重试成“最新版本”。
+
+## 应用接入
+
+侧栏「应用接入」提供应用创建、队列与凭据查看、Token 重新生成和完整 SDK 配置交付。配置 `ORBIT_CONSOLE_APPLICATION_ADMIN=admin` 指定唯一管理登录名；本地 Compose 已配置。其他业务页面继续使用账号原有默认范围。[功能、接口、权限和恢复说明](api/console-applications.md)。
--- a/docs/reports/console-applications.md
+++ b/docs/reports/console-applications.md
@@ -0,0 +1,27 @@
+# 单管理员应用接入验收（2026-09-27）
+
+## 交付范围
+
+- 独立应用接入页：按应用/环境查看接入范围、队列与凭据，创建应用/命名空间/初始队列，选择业务能力，生成或轮换 Token，复制/下载 SDK 环境配置。
+- 通过 `ORBIT_CONSOLE_APPLICATION_ADMIN` 显式指定唯一管理员，默认关闭；仅登录 Cookie 可访问管理端，业务 Token 不授予跨应用权限。同事务核验账号及会话，写请求额外核验同源与专用请求头。
+- 新建资源、权限、审计、幂等回执同事务；轮换复用原凭据事务与 ID，任务、订阅和交付身份保留。只存秘密摘要，一次性交付明文；提交不明时保留原操作核对。
+- 没有新增数据库表或外键，没有改变业务 SDK 接口，不需要升级 SDK v0.1.1。
+
+## 已完成验证
+
+| 验证 | 结果 |
+| --- | --- |
+| `make test vet build` | 七模块竞态测试、静态检查和构建通过 |
+| `TestIntegrationConsoleApplications` | 真实 MySQL：SDK 身份与错误管理员拒绝、准备未生效、并发创建一次、同键改内容冲突、重名回滚、元数据脱敏、轮换原身份、旧秘密失效、重复回执、版本冲突、退出失效、审计主体及零外键通过 |
+| 管理 HTTP 单元测试 | Cookie 必须、Bearer 单独拒绝、缺少防跨站头/异源/null Origin 拒绝、合法同源请求、未知字段拒绝、响应不可缓存通过 |
+| 准备对象严格 JSON 往返 | CREATE 与 ROTATE 的可选 ID/空能力组原样提交通过；真实 HTTP 发现的空 ID 编码问题已修复并加入回归 |
+| `scripts/test-console-applications.py` | 真实 HTTP 创建/重放/冲突，任务和订阅生成，轮换后旧 Token 401、新 Token 可读取原任务与订阅，订阅暂停收尾、退出会话失效通过 |
+| `make console-e2e` | 全新 MySQL/容器初始化，应用接入新链路、登录/权限、真实 Worker/重试/定时、保留策略、周期归档及离线校验全部通过 |
+| 本地 Compose | 更新现有 18080 环境，复用原管理员、初始业务凭据与数据库卷；新增独立 access-demo 测试应用，轮换只发生于该测试应用 |
+| 浏览器检查 | 实际账号登录，独立页面与应用详情加载、新建表单显示、权限/队列/配置展示；当前 1280×720 视口布局正常，无浏览器错误 |
+
+`make integration` 已完整退出 0：覆盖真实存储、HTTP/WSS、SDK、可运行示例、独立 Inbox/Outbox/HTTP 宿主、Worker 与事件进程故障以及流程多节点暂停恢复。页面布局与表单读取通过浏览器核对；实际创建与轮换的持久化链路通过真实 HTTP 验证，不混称为浏览器点击完成全部流程。文档链接检查覆盖 196 份 Markdown，全部解析通过。
+
+## 边界
+
+接入管理跨应用，其他业务页面仍使用账号原有默认范围。旧 Token 原文不可查看；新 Token 交付丢失时保留原应用并重新轮换。列表每页 50 个命名空间，单个详情队列和凭据各最多 100 项并显式标记截断。当前未增加删除应用、修改权限、凭据转移、复杂角色或多应用任务总览。