Operations, development and architecture docs, the reference pages and the component READMEs were rewritten against the code: every documented variable exists, and the settings operators need (runtime image, Git service, listen addresses, Runner targets, single-tenant gateway and provisioner bindings) are documented. Gaps the docs used to present as working are now stated as such: IDE workspaces do not clone the project yet (FR-H2), and in Kubernetes mode dependency installs and image builds have no network path until an egress proxy and builder access exist. The Kubernetes README describes what the provisioner creates, what the Runner needs in a target namespace, and the cluster acceptance that is still outstanding. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.9 KiB
4.9 KiB
管理台设计规范
管理台位于 apps/web,使用 Next.js App Router、React、SWR 与 Lucide 图标。所有列表、状态、预算与操作反馈都来自真实的控制面数据,不内置演示数据或模拟流程。
视觉基线
概念图:apps/web/design/console-concept.png(零数据状态的工作概览)。
- 新增样式使用
globals.css顶部的设计变量(导航--navy、页面背景--bg、表面--surface、主色--teal/--teal-dark、边框--border、正文与次要文字--ink/--muted、警示--amber/--red)。 - 正文与次要文字对白色背景的对比度不低于 4.5:1,焦点环不低于 3:1;最小字号 12 px。
- 桌面端左侧导航 248 px、顶部栏 58 px;760 px 以下使用抽屉导航,抽屉关闭时其中的链接不可聚焦,按 Esc 关闭。
- 所有按钮与表单都有可见焦点、标签和错误反馈,并尊重
prefers-reduced-motion。
页面
| 页面 | 内容 | 主要接口 |
|---|---|---|
工作概览 / |
进行中与待处理的运行数、最近运行、项目准备入口 | GET /v1/dashboard |
项目空间 /projects |
项目列表、创建项目 | GET/POST /v1/projects |
项目详情 /projects/:id |
仓库状态(平台仓库失败可重试)、IDE 工作区、项目运行、项目经验(查看、添加约定、停用、删除)、设置(目标分支、验证命令、安装命令、交付配置、验收配置) | GET/PATCH /v1/projects/:id、POST /repository、/workspaces、/lessons、/v1/lessons/:id |
运行记录 /runs |
运行列表与筛选;提交愿望(不可用的执行器不可选并显示原因) | GET /v1/runs、POST /v1/projects/:id/wishes |
运行详情 /runs/:id |
阶段进度、等待原因与对应操作、最近一次失败(修复轮的输入);标签页:概览、代码变更(检查点按文件的 diff)、阶段事件(Agent 消息、命令、文件变更、计划)、验证证据(命令、退出码、耗时、输出尾部,合入与冲突);交付结果(合入的 commit 或应用地址) | GET /v1/runs/:id、/events/stream、/artifacts、/delivery、POST /commands |
发布与审批 /releases |
发布列表(失败原因);审批对话框展示需求目标与验收标准、项目、环境(是否生产)、验证命令、commit、镜像、审批期限与请求人 | GET /v1/releases、GET /v1/releases/:id/review、POST /v1/approvals/:id/decision |
环境 /environments |
环境列表与创建、应用地址、Runner 注册、部署密钥引用、部署结果未知时「核对后解锁」 | /v1/environments*、POST /v1/environments/:id/unlock |
执行器 /providers |
执行器可用性与能力、保存或撤销 BYOK 凭据 | GET /v1/providers、/v1/provider-connections |
Agent 配置 /agent |
配置版本列表、创建、激活、回滚 | /v1/agent-bundles* |
用量 /usage |
套餐限额与当前用量、本月 token 与按运行明细、CSV 导出 | GET /v1/entitlements、/v1/usage、/v1/usage/export |
等待原因统一由 src/lib/waiting.ts 映射为中文说明和可执行操作(例如「连接执行器」「重试仓库创建」「去审批」「补充需求」),不直接展示后端的原始代码。
身份与代理
/api/*是服务端代理,转发到控制面的/v1/*并附加当前用户的 access token;不存在绕过身份检查的公开 rewrite。- 只有
WF_DEPLOYMENT_MODE=development(且不是 Next 的生产构建)时,服务端才读取WF_DEV_AUTH_TOKEN自动登录;其他情况一律不接受开发令牌。 - OIDC 使用 discovery、授权码 + PKCE(S256)、state 与 nonce,并校验 ID token 的签名、issuer 与 audience。
- 会话保存在加密的 HttpOnly Cookie 中,浏览器脚本无法读取;access token 过期前 1 分钟内由服务端代理使用 refresh token 续期,会话最长 12 小时。身份服务没有签发 refresh token 时,会话随 access token 结束。
- 写请求校验
Origin,代理拒绝上游重定向;界面上的权限控制只用于体验,最终以 API 的角色与成员检查为准。 - 打开 IDE 时,
/ide/:id/launch在服务端调用 API 获取 30 秒一次性启动地址,access token 不出现在 URL 中。
环境变量:WF_DEPLOYMENT_MODE、WF_API_URL、WF_PUBLIC_URL、WF_DEV_AUTH_TOKEN(仅开发)、OIDC_ISSUER、OIDC_CLIENT_ID、OIDC_CLIENT_SECRET(可选)、WF_SESSION_SECRET(至少 32 字符)。
测试
src/lib/auth.test.ts:会话加密与篡改、生产禁用开发令牌、会话过期、返回地址校验、ID token 签名与 nonce、refresh token 续期与轮换。src/lib/patch.test.ts:检查点补丁按文件解析(新增、删除、二进制、看起来像文件头的内容行)。tests/run-lifecycle.test.ts:每个等待原因在waiting.ts中都有中文说明与操作。