113 lines
11 KiB
Markdown
113 lines
11 KiB
Markdown
# Orbit Console · 星轨控制台
|
||
|
||
Orbit 内置了一个不依赖 Node.js、外部 CDN 或额外文件挂载的管理控制台。静态资源编译进 Orbit 二进制，入口为：
|
||
|
||
```text
|
||
http://127.0.0.1:8080/console/
|
||
```
|
||
|
||
## 当前能力
|
||
|
||
- 读取 `/health/ready` 和 `/version` 展示服务就绪状态及版本；数据库未就绪时明确提示不可用。
|
||
- 通过数据库中的控制台账号登录；服务端使用 HttpOnly 会话 Cookie 调用现有授权 API，普通业务页面无需业务 Token；应用接入页仅在管理员明确查看时读取当前 Token。
|
||
- 总览展示各类最近 20 条记录的快照：任务成功占比、状态分布、启用计划、待核查流程和待确认结果，并提供异常入口与最近任务。已取消单独统计，不算失败；快照不是全库累计。
|
||
- 页顶选择应用、环境与队列；任务、计划、流程、订阅、归档列表和详情显示应用归属。应用和队列范围保存在 URL，重新打开、复制链接及后退可恢复；列表条件和页码在当前页面会话内保持。
|
||
- 点击任务查看任务详情、执行尝试时间线、最终结果和操作审计摘要。
|
||
- 在具备对应权限时提交任务取消和安全重试，沿用服务端的版本校验、幂等键、队列范围和审计规则。
|
||
- 点击定时计划查看当前版本、规则、下一次触发和触发记录；在具备 `schedules:manage` 权限时可暂停或恢复计划。
|
||
- 点击流程实例查看当前权威状态、固定版本、步骤状态和事件时间线；步骤读取沿用 `workflows:read`，事件时间线没有 `workflows:audit:read` 时会明确显示权限提示。
|
||
- 点击结果订阅查看冻结配置、游标、积压窗口和最近交付历史；页面不展示租约秘密，也不绕过 `events:read` / `events:manage` 权限。
|
||
- 在具备 `workflows:control` 权限时，流程详情可以暂停、恢复或取消；操作原因、`control_revision` 和幂等键交给服务端做最终校验。
|
||
- `NEEDS_REVIEW` 流程会显示按步骤类型划分的人工恢复入口：任务核查、步骤结论、继续、步骤重试、PENDING 接续和等待重建；每次提交都要求当前修订、证据引用和显式确认，服务端恢复 API 负责最终门控。
|
||
- 在具备 `events:manage` 权限时，订阅详情可以启停订阅，并对 `EXPIRED` 交付追加次数预算后重试；原交付身份、已用次数和事件不会被页面重置。
|
||
- 工作台固定导航和页头，内容区独立滚动；切换模块回到内容顶部。应用详情相同快照不重建，后台刷新会避让正在滚动、编辑或展开详情的操作。
|
||
- 左侧八个模块是独立视图：总览、任务、计划、流程、订阅、保留策略、归档作业和应用接入。
|
||
- “保留策略”只允许单管理员查看和修改命名空间级窗口；修改需要版本号、幂等键和原因并留下审计。预览和只读导出不会删除源数据，未确认交付、未知效果和未结束流程不会成为候选。
|
||
- 当前视图按 10 秒自动刷新，可在页顶暂停；输入、打开详情或操作弹窗时不自动重载。页面只调用服务端授权接口，不把账号密码或业务凭据上传到独立服务，也不读取数据库。
|
||
- 普通账号沿用绑定凭据范围；部署指定管理员可显式选择应用环境管理。读取失败显示错误，避免当作空列表。
|
||
|
||
## 本地打开
|
||
|
||
启动 Orbit 后访问 `/console/`。未登录时，任何控制台业务页面都会跳转到 `/console/login`；登录成功后进入控制台，登录会话过期或服务端返回 401 时也会重新跳转。使用 `scripts/orbit-local.py up` 部署的持久本地联调入口（通用 Compose 默认端口仍为 8080）：
|
||
|
||
```text
|
||
http://127.0.0.1:18080/console/
|
||
```
|
||
|
||
首次使用可以在 `orbit-admin bootstrap` 时一起创建控制台管理员。这样业务资源、业务凭据和管理员账号在同一个初始化事务中提交：
|
||
|
||
```sh
|
||
secret-manager read orbit/console-admin-password | \
|
||
./bin/orbit-admin bootstrap \
|
||
--application sample-app \
|
||
--namespace default \
|
||
--environment production \
|
||
--queue files \
|
||
--console-username admin \
|
||
--console-display-name 'Orbit 管理员' \
|
||
--console-password-stdin \
|
||
--output .local/production.credentials.json
|
||
```
|
||
|
||
密码不会进入命令参数、日志或 JSON 文件，初始化失败时资源和账号一起回滚。已经完成业务初始化的环境，也可以由数据库管理员单独创建控制台账号。账号绑定一个已有的命名空间凭据，未指定为应用管理员的账号沿用该凭据权限；这不会轮换或输出业务 Token。推荐从私有凭据文件读取命名空间和凭据标识，并从标准输入交付密码：
|
||
|
||
```sh
|
||
./bin/orbit-admin console-user create \
|
||
--credential-file .local/local.credentials.json \
|
||
--username operator \
|
||
--display-name 'Orbit 管理员' \
|
||
--password-stdin
|
||
```
|
||
|
||
命令会把密码写成 bcrypt 哈希，只输出账号的脱敏信息。生产环境应通过受保护的密钥管道提供标准输入；不要把密码写进命令历史、镜像或仓库。账号创建后直接打开控制台，用账号密码登录。
|
||
|
||
页面的 API 地址默认自动取当前访问地址的 origin，不需要手填。部署到域名后，直接访问 `https://orbit.example.com/console/`，页面会自动请求同一域名下的服务端接口；生产建议用反向代理让控制台和 API 保持同源。页面不再要求填写队列 ID、Bearer Token，也不再选择凭据 JSON。
|
||
|
||
如果未来把前端静态资源和服务端拆成不同域名，需要额外设计 API 基地址、CORS、Cookie `SameSite`/Domain 和 CSRF 防护，不能只替换一个 URL。当前内置控制台优先保证同源部署的安全边界。
|
||
|
||
`ORBIT_CONSOLE_QUEUE_ID` 只作为单一默认队列的展示和查询范围配置：
|
||
|
||
```sh
|
||
export ORBIT_CONSOLE_QUEUE_ID='queue_xxx'
|
||
```
|
||
|
||
`GET /console/config` 只对已登录会话返回这个非敏感的默认队列 ID。健康检查和版本探针保持公开，业务 API、控制台 HTML、配置和所有业务模块均受登录会话与原有权限双重保护。
|
||
|
||
## 安全边界
|
||
|
||
当前登录接口尚未实现连续密码错误计数、临时锁定或账号/IP 登录限流。错误统一返回 401，密码使用 bcrypt 存储；这些措施不能替代防暴力尝试封控。此项是待补能力，不能视为已具备。
|
||
|
||
控制台通过服务端授权访问数据库。登录会话只保存令牌摘要，服务端每次请求都会校验账号、会话、命名空间、应用启停和凭据权限。取消和人工重试会使用当前任务版本生成一次性幂等键；网络结果不明时不要重复点击，应使用原始操作身份通过 API/SDK 核对。`NEEDS_REVIEW` 任务仍须使用带证据的核查 API/SDK 完成最终裁决。普通账号不自动获得跨命名空间权限；部署指定的单管理员可显式选择应用范围，每个业务事务重新核验原会话及目标应用。各应用分别展示，SDK 权限不变。
|
||
|
||
不能把业务 Token 长期放进浏览器本地存储，也不能让控制台直连 MySQL。计划版本发布、跨命名空间管理身份和其他高风险写操作仍应通过受保护 API/SDK 设计后再接入页面。流程恢复入口只调用已经定义的恢复 API，不自动猜测结果、不替操作者补齐证据，也不把冲突重试成“最新版本”。
|
||
|
||
## 应用接入
|
||
|
||
侧栏「应用接入」提供应用创建、队列与凭据查看、Token 重新生成和完整 SDK 配置交付。配置 `ORBIT_CONSOLE_APPLICATION_ADMIN=admin` 指定唯一管理登录名，并配置 `ORBIT_CREDENTIAL_KEY_FILE` 保管密钥；本地 Compose 自动配置。可随时查看、复制当前完整接入信息。业务页面支持该管理员选择应用范围，订阅原 SDK 凭据绑定不变。[功能、接口、权限和恢复说明](api/console-applications.md)。
|
||
|
||
## 按应用查看数据
|
||
|
||
页顶「应用 / 环境」选择已创建的应用，再选择队列。两处下拉菜单支持搜索已加载的选项，应用名称和环境分行展示；支持方向键、Enter 选择及 Escape 关闭。任务、定时计划和结果订阅按队列读取；流程、保留策略和归档按应用环境所属命名空间读取，页面有范围提示。应用每页 50 项、队列每页 100 项，选择「加载更多…」获取下一页。没有队列的应用仍能查看流程和归档。
|
||
|
||
切换采用完整导航，隔离旧请求和详情；有未保存策略、未确认操作或打开的详情时需先处理完。URL 只保存非敏感 ID。无效范围显示错误，不降级读取默认应用。总览仍是最近查询窗口的统计，不是全库累计。
|
||
|
||
只有部署指定管理员可以切换应用；其他账号只展示自己的应用和授权队列。后台停用应用、撤销绑定凭据或退出账号后，原页面范围不能继续授予权限。[范围接口及授权规则](api/console-scope.md)。
|
||
|
||
## 资源退役与明确接入目标
|
||
|
||
应用接入页按命名空间记忆所选队列；多队列且没有记忆时要求明确选择，不根据名称猜测业务用途。下拉框显示暂停/退役状态，已退役队列不能导出成新接入配置；凭据无该队列权限时直接提示，不自动换目标。
|
||
|
||
结果订阅详情和应用接入页分别提供订阅、队列退役；每次提交需要原因和当前版本，网络不明确时保留原键重报。活动订阅名额包含暂停订阅，退役后释放，历史仍可查询；阻塞原因明确显示。未补存当前 Token 时，预览入口与过渡提示都要求先补存，避免误认为已有可复制的新配置。
|
||
|
||
## 查询与日常操作
|
||
|
||
1. 在页顶选择应用环境；任务、计划、订阅再选择队列。
|
||
2. 任务与流程可组合状态、完整业务键和创建时间查询。业务键精确匹配，保留大小写、特殊字符和尾部空格；时间输入按浏览器时区换算，开始包含、结束不包含。
|
||
3. 四个资源列表默认每页 10 条，可选择 10 / 20 / 50 / 100 条、下一页、上一页和回到最新。请求服务端游标，不在前端截取全部数据。自动刷新和手动「刷新数据」保留当前条件及页码；改变条件或页大小回到第一页。分页期间数据可能继续变化，不承诺固定快照。
|
||
4. 在页面右上输入完整 32 位资源 ID 可直接定位；详情可复制完整 ID。读取失败保留筛选并提示原因，迟到的旧查询不会覆盖新查询。详情打开后焦点留在抽屉内，Escape 关闭后回到原入口。
|
||
5. 应用接入页可搜索本页应用，先选择接入队列，再查看或复制完整配置。应用标识、权限、有效期调整、退役等低频信息折叠展示；查看与换证沿用原有身份、权限和审计规则。
|
||
|
||
全站采用浅色工作台和统一表格。窄屏导航可横向滑动，宽表格在自身容器中滚动；登录页与控制台使用相同视觉样式。
|
||
|
||
前端校验运行 `make console-check`（开发机需要 Node.js，运行服务无需 Node.js）；真实 MySQL、登录保护、任务执行与控制台接口链路运行 `make console-e2e`。本批范围与浏览器验收见[管理端改版记录](reports/console-refresh.md)。
|