56 lines
3.3 KiB
Markdown
56 lines
3.3 KiB
Markdown
# 凭据、权限与初始化
|
||
|
||
状态：P1 已实现。业务接口每次在数据库事务内校验凭据摘要、撤销/到期、应用与命名空间启停，以及动作和队列范围。授权与写入使用同一事务；管理变更与已经获得授权锁的请求按事务先后次序生效。
|
||
|
||
## 初始化一个新的接入应用
|
||
|
||
前置：专用 MySQL 数据库已经执行 orbit-migrate up，使用持有初始化权限的数据库管理连接。此命令创建新应用、命名空间、队列和凭据，不会覆盖现有同名应用。
|
||
|
||
```sh
|
||
mkdir -p .local
|
||
chmod 700 .local
|
||
go run ./cmd/orbit-admin bootstrap \
|
||
--application sample-app \
|
||
--namespace default \
|
||
--environment development \
|
||
--queue files \
|
||
--output .local/development.credentials.json
|
||
```
|
||
|
||
ORBIT_MYSQL_DSN 通过环境注入，命令不读取 .env。所有名称必填，以字母/数字开头，后续允许字母、数字、`_ . : -`；environment 最长 32，其余最长 128。输出文件必须不存在，以 0600 创建；原始凭据不会打印到 stdout/stderr。`.local/` 和 `*.credentials.json` 已被 Git 忽略。
|
||
|
||
输出 JSON 包含 application_id / namespace_id / queue_id / credential_id / token / expires_at。初始凭据有效期为 30 天，权限包括当前命名空间内的五个 P1 动作和全部队列。初始队列 max_concurrency=4、rate_per_second=10；这是开发初始配置，执行限流随 P2–P3 落地。
|
||
|
||
资源、凭据摘要和初始化审计在一个事务中提交。交付文件先写入并同步到磁盘，成功后再提交事务。如果文件写入失败则回滚并移除文件；如果已经交付后提交无法确认，保留文件并报错，应使用其中凭据核对结果，不能直接覆盖或重复创建。
|
||
|
||
初始文件包含真实秘密，应保管在受限目录或导入秘密管理系统。运行账户与迁移/初始化账户分开；生产只通过 HTTPS 使用凭据。凭据管理 HTTP API、轮换与细粒度运维命令在后续阶段实现，当前 bootstrap 主要用于完成独立接入与开发验证。
|
||
|
||
## 凭据格式与作用域
|
||
|
||
```text
|
||
orb1.<namespace_id>.<credential_id>.<32-byte-base64url-secret>
|
||
```
|
||
|
||
服务端仅保存 SHA-256 秘密摘要。ID 不是授权证明，秘密不进入 URL。客户端请求：
|
||
|
||
```text
|
||
Authorization: Bearer <token>
|
||
```
|
||
|
||
权限存储格式如下，当前由受控初始化及管理侧写入，不能通过普通任务请求修改：
|
||
|
||
```json
|
||
{
|
||
"actions":["tasks:submit","tasks:read","tasks:cancel","queues:read","queues:manage"],
|
||
"queues":["*"]
|
||
}
|
||
```
|
||
|
||
actions 不支持通配符；queues 可列出队列 ID，星号仅表示当前命名空间内全部队列。创建队列必须具有 queues:manage 和全部队列范围。请求不接受自定义 namespace_id 来跨越隔离边界。
|
||
|
||
原始秘密错误、凭据撤销/过期、应用或命名空间停用统一返回 401。合法身份缺少动作权限返回 403。读取不在范围内的单个资源返回 404，避免披露资源内容。
|
||
|
||
SDK 使用 `orbit.Options{Token: token}`。健康查询不发送凭据。当前不启用业务权限缓存，撤销校验不依赖缓存过期。
|
||
|
||
P2 增加 workers:connect 和 workers:consume。bootstrap 只有显式提供 --worker-access 时才同时授予这两项开发权限；现有凭据不自动变化。Worker 还需独立的进程恢复秘密和尝试秘密，见 [Worker 契约](worker.md)。
|