feat: support permanent credentials and overlapping token rotation
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# 控制台应用接入
|
||||
|
||||
单管理员在「应用接入」页面创建应用、初始队列与 SDK 凭据，查看环境、队列、权限和有效期，重新生成 Token，复制或下载 `.env` 配置。数据库只保存 Token 摘要：完整 Token 仅在新建或轮换时交付，列表和详情不能反查旧秘密。
|
||||
单管理员在「应用接入」页面创建应用、初始队列与 SDK 凭据，查看环境、队列、权限和有效期，平滑换证，复制或下载 `.env` 配置。数据库只保存 Token 摘要：完整 Token 仅在新建或轮换时交付，列表和详情不能反查旧秘密。
|
||||
|
||||
## 1. 启用和使用
|
||||
|
||||
@@ -18,7 +18,8 @@ export ORBIT_CONSOLE_APPLICATION_ADMIN=admin
|
||||
2. 选择 Worker、结果订阅、定时、流程等需要的能力及有效期。基础权限包含任务提交/查询/取消、队列读取/管理。
|
||||
3. 创建成功后复制或下载完整 `.env`，交给该应用的服务端配置。默认地址使用当前页面来源，详情中可改为容器地址或部署域名。
|
||||
4. 已接入应用可以随时查看元数据和配置模板。模板中的 Token 是占位值，必须替换成已经保存的原 Token。
|
||||
5. 「重新生成 Token」保留 application_id、namespace_id、credential_id、队列、任务和订阅；旧 Token 在轮换事务提交后不能再通过业务认证，服务端配置需要同步更新。
|
||||
5. 「平滑换证」保留 application_id、namespace_id、credential_id、队列、任务和订阅；新 Token 立即生效，旧 Token 在配置的过渡期内继续使用（页面默认 7 天，支持 1/7/30 天），便于逐台更新配置。详情展示旧 Token 实际截止，全部服务切换后可点「结束过渡」。
|
||||
6. 默认「长期有效」，不需要每月人工换证；已有凭据可点「调整有效期」直接设为长期，原 Token 保持不变。
|
||||
|
||||
环境与命名空间形成隔离边界。不同应用应分别创建；同一应用的多个命名空间在列表中分别展示。页面目前支持新建应用及其初始队列，未提供应用删除、身份迁移、跨应用任务列表或现有应用新增命名空间的表单；已有 CLI 的 `--application-id` 仍可增加命名空间，队列 SDK 可增加同范围队列。接入管理页不会改变其他业务页面的账号默认范围。
|
||||
|
||||
@@ -48,31 +49,31 @@ prepare 请求：
|
||||
"queue": "orders",
|
||||
"capabilities": ["worker", "events", "schedules", "workflows"],
|
||||
"expected_revision": "0",
|
||||
"valid_days": 30,
|
||||
"valid_days": 0,
|
||||
"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"`。
|
||||
名称以字母或数字开头，后续只允许字母、数字、`_ . : -`，environment 最长 32，其余最长 128。valid_days 为 0–365 的整数，默认 0 表示长期有效；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":"接入订单服务"},
|
||||
"version": 2,
|
||||
"input": {"kind":"CREATE","application":"order-service","namespace":"default","environment":"test","queue":"orders","capabilities":["worker","events"],"expected_revision":"0","valid_days":0,"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"
|
||||
"token": "服务端生成的完整 Token"
|
||||
}
|
||||
```
|
||||
|
||||
以上是结构示意，ID、令牌及时间以服务端返回为准。将 **data 整体原样** POST 到 apply，不包 `data` 外层。应用、额度、命名空间、队列、凭据摘要、审计和幂等回执在同一事务提交。初始队列并发 4、开始速率 10/秒，沿用 bootstrap 默认策略；凭据队列范围为新命名空间的全部队列。重名应用返回 409，不覆盖原资源。
|
||||
|
||||
## 4. 重新生成 Token
|
||||
## 4. 平滑换证
|
||||
|
||||
prepare 请求：
|
||||
|
||||
@@ -82,12 +83,13 @@ prepare 请求：
|
||||
"namespace_id": "33333333333333333333333333333333",
|
||||
"credential_id": "55555555555555555555555555555555",
|
||||
"expected_revision": "1",
|
||||
"valid_days": 30,
|
||||
"valid_days": 0,
|
||||
"grace_days": 7,
|
||||
"reason": "更新接入凭据"
|
||||
}
|
||||
```
|
||||
|
||||
expected_revision 为读取到的字符串版本。只允许上述轮换字段，不混入新应用名称或能力组。准备对象包含原 application_id / namespace_id / credential_id，没有 queue_id。apply 复用原有凭据轮换事务：替换秘密摘要与到期时间，版本加一，保存脱敏回执及人类账号审计；权限组不改变。已撤销的凭据禁止轮换。
|
||||
expected_revision 为读取到的字符串版本。只允许上述轮换字段，不混入新应用名称或能力组。准备对象包含原 application_id / namespace_id / credential_id，没有 queue_id。apply 复用原有凭据轮换事务：将原摘要保留到固定过渡截止，替换当前摘要与可选到期时间，版本加一，保存脱敏回执及人类账号审计；权限组不改变。已撤销的凭据禁止变更。ROTATE 的 grace_days 范围 0–30，API 省略/0 保持立即停用旧 Token 的兼容语义，页面显式提交 7；实际截止不超过旧 Token 原到期时间。过渡未结束时再次轮换返回 409。
|
||||
|
||||
apply 成功 data：
|
||||
|
||||
@@ -102,7 +104,28 @@ apply 成功 data：
|
||||
}
|
||||
```
|
||||
|
||||
## 5. 超时、重复和审计
|
||||
## 5. 调整有效期与结束过渡
|
||||
|
||||
prepare 输入示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "SET_EXPIRY",
|
||||
"namespace_id": "33333333333333333333333333333333",
|
||||
"credential_id": "55555555555555555555555555555555",
|
||||
"expected_revision": "2",
|
||||
"valid_days": 0,
|
||||
"reason": "服务凭据设置为长期有效"
|
||||
}
|
||||
```
|
||||
|
||||
SET_EXPIRY 不生成新 Token，只更新当前有效期；valid_days=0 为长期，1–365 为从准备时间计算的天数。FINALIZE 使用相同身份/版本字段，kind 改为 FINALIZE，valid_days 必须为 0，用于提前停用旧 Token。两者均禁止 grace_days 和新建字段，prepare 不返回 token；FINALIZE 也不返回 expires_at。apply 使用完整原对象，具有相同的并发版本、幂等和审计约束。
|
||||
|
||||
新版 prepare 对象带 version=2；expires_at 为空时**省略字段**，不要传显式 null。ROTATE 有过渡期时另外包含固定 previous_valid_until；详情中的 previous_valid_until 是受旧到期时间约束后的实际截止，未设置时省略。详情/回执不会返回旧秘密。历史不带 version 的固定操作仍按原语义重放。
|
||||
|
||||
完整滚动更新及 SDK 客户端生命周期说明见[凭据手册](authentication.md)。更换配置不会自动刷新已创建的客户端，须在过渡截止前完成重建或逐台重启并排空在途任务。
|
||||
|
||||
## 6. 超时、重复和审计
|
||||
|
||||
- 页面提交前把整个固定操作保留在当前内存；请求超时或结果未知时，按钮变成「重试确认」，重用同一份内容。不能再次 prepare 来代替核对。
|
||||
- 页面允许「保存待核对操作」下载私密 JSON；含真实 Token，应放到受限目录。恢复时登录同一管理员后，向 apply 发送该文件正文。不要把 Cookie 或操作文件提交 Git，也不要放到 URL。
|
||||
|
||||
Reference in New Issue
Block a user