krisolo/boss
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3b51641d9922b55402aa45f817081e4e8d8cb39a
boss/docs/architecture/admin_refine_backoffice_cn.md
AI Bot e1aed590f8 feat: harden enterprise control plane
2026-05-17 02:20:08 +08:00

10 KiB
Raw Blame History

Boss To B 管理后台接入记录

更新时间：2026-04-27

目标

为 Boss To B 场景新增系统管理后台，供平台侧查看和管理不同客户公司的账号、设备、权限和风险状态，重点支持快速发现客户电脑 Codex 节点掉线、主 Agent 任务失败、线程上下文风险和运维故障。

技术选型

  • 使用 @refinedev/core 作为管理后台资源抽象层。
  • 使用 antd 原生组件作为后台 UI 组件库。
  • 不使用 @refinedev/antd，原因是当前版本会传递引入 @ant-design/pro-layout -> path-to-regexp@8.2.0 高危 audit 链。
  • 不直接接入 ant-design-pro 工程，避免把 Umi/Max 路由和权限体系引入现有 Next.js 16 + App Router 主工程。

企业级后台独立化方向

2026-04-30 起，Boss 后台进入独立 PC 管理后台阶段。调研 YunaiV/yudao-cloud 后，当前策略是借鉴它的租户、用户、角色、菜单、日志和工作台信息架构，但不直接接入 YuDao 的 Java 微服务后端，避免把现有 Next.js + 文件状态账本 + local-agent 运行时拆碎。

第一批新增：

  • apps/boss-admin-web：独立 Vue + Vite + Ant Design Vue 后台工程，面向平台侧运营和客户成功人员。
  • /api/v1/admin/backoffice：企业后台 BFF，把 Boss 当前账本聚合成 YuDao 风格的菜单、工作台、租户、账号、角色权限、资源授权、Skill 中心、风险和审计数据。
  • /enterprise-admin：Next 主站内的受保护入口，只允许 highest_admin 访问，并跳转到独立后台静态产物 /admin-web/index.html。
  • admin:web:dev / admin:web:build / admin:web:publish：根工程脚本入口。admin:web:publish 会把 Vue 构建产物写入 public/admin-web，随 Next standalone 的 public 一起发布。

边界：

  • 旧 /admin UI 已删除，/admin 仅保留为跳转到根路径 / 的兼容入口；生产域名 https://admin.boss.hyzq.net/ 直接承载新独立 PC 后台。
  • 独立后台只消费 Admin BFF，不直接读取 boss-state.json。
  • 独立后台当前复用 Boss Cookie 登录态，后续再绑定 admin.boss.hyzq.net 的独立部署。
  • /api/v1/admin/backoffice 仍只允许 highest_admin，并过滤 passwordHash、mfaSecret 和 session token。

当前落地范围

  • /admin 页面收敛为兼容跳转，不再承载旧 Next 管理 UI。
  • 新增 /api/v1/admin/overview 聚合接口。
  • 新增 /api/v1/admin/backoffice 独立企业后台聚合接口。
  • 新增 /api/v1/admin/risks/actions 风险处理动作接口。
  • 新增 /api/v1/admin/notifications/dispatch 风险通知派发接口。
  • 新增 buildAdminOverview(state) 纯函数，负责从当前文件状态聚合后台数据。
  • 新增显式 adminCompanies 租户账本，支持把账号和设备直接绑定到客户公司，不再只能依赖账号邮箱域名推断。

当前页面已在 2026-04-30 升级为 PC To B 总后台结构，不再是简单的 3 个表格页签。新结构包含 4 个一级区：

  • 平台运营驾驶舱：平台全局健康、待处理风险、客户健康、节点健康、最近事件。
  • 客户与账号：客户公司、账号列表、设备归属和客户开通任务流。
  • 授权工作台：复用既有账号 / 设备 / 项目 / Skill 授权能力，但放在更清晰的权限上下文里。
  • 风险与治理：风险战情室、SLA、负责人、修复工单，以及 Skill 生命周期治理。

平台运营驾驶舱

  • 展示今日待处理：客户公司、账号、在线设备、开放风险和风险通知。
  • 展示客户健康排行：按开放风险和设备在线情况优先排列。
  • 展示关键风险队列：只展示最值得处理的风险，完整队列进入风险战情室。
  • 展示节点健康：集中查看客户电脑、Codex GUI / CLI 和最近心跳。
  • 展示最近事件：风险通知和风险时间线，避免平台侧漏跟进。

客户与账号

  • 展示客户公司列表、健康状态、账号数、在线设备、开放风险和客户成功负责人。
  • 展示客户开通任务流：创建客户公司、开通老板账号、绑定客户电脑、分配项目与 Skill 权限。
  • 展示账号列表：账号、角色、公司、状态和最近登录。
  • 展示客户设备：设备状态、GUI / CLI 在线状态、风险数和最近心跳。

授权工作台

  • 继续复用 /api/v1/admin/access。
  • 支持创建 / 更新子账号、公司管理、批量导入、账号归属、设备归属、权限模板、设备 / 项目 / Skill 授权和离职回收。
  • 高危动作继续保留二次确认和审计记录。

风险与治理

  • 风险战情室按严重程度、客户影响、负责人和 SLA 组织风险。
  • 风险处理不再使用浏览器 window.prompt，改成页面内处理面板。
  • 处理面板支持指派负责人、设置 SLA、确认、关闭和创建修复工单。
  • 对暂不支持动作的风险类型保持只读提示，不假装处置成功。
  • Skill 生命周期治理作为同一区域的第二页签，继续复用 /api/v1/admin/skills/requests。

旧版落地范围记录

以下是第一版落地内容，仍保留作为能力来源说明：

总览

  • 总览统计：公司数、账号数、在线设备、开放风险。
  • 风险通知：展示由 SLA 扫描生成的超时通知，避免平台侧只看到风险列表、漏掉需要主动跟进的客户事项。
  • 风险时间线：展示风险通知生成、派发、确认、关闭、负责人和 SLA 调整等最近事件。
  • 关键风险：展示最高优先级风险。
  • 风险表：离线设备、未关闭运维故障、线程上下文告警、失败主 Agent 任务。
  • 风险动作：ops_fault 支持指派负责人、设置 SLA、确认、关闭和创建修复工单；thread_context_alert 支持指派负责人、设置 SLA、确认和关闭；暂不支持的风险类型会显式失败，不假成功。
  • 设备表：设备在线状态、CLI/GUI 连接状态、最近心跳和风险数量。
  • 公司表：优先使用显式 adminCompanies，账号和设备未绑定公司时才回退到账号域名或默认公司。
  • 公司表补齐 To B 运营字段：套餐等级、合同到期时间、客户负责人和客户成功负责人。
  • 账号表：展示账号、角色、公司、状态、创建/更新时间，不暴露 passwordHash。

账号与授权

  • 复用 /api/v1/admin/access，支持创建 / 更新 member 或 admin 子账号。
  • 支持查看账号状态，并对非主账号执行启用 / 停用；停用账号会同步撤销该账号当前活跃会话。
  • 支持公司管理、账号归属、设备归属和公司列表。
  • 支持按公司批量导入成员账号，并支持先预览新增 / 更新 / 异常数量，预览不会写入状态账本。
  • 支持 CSV 文件导入账号清单，表头为 account,displayName,role,password。
  • 支持对子账号开启 / 关闭 MFA；后台 GET 不返回 mfaSecret，仅开启时在本次响应返回一次 mfaSetupSecret 供初始化。
  • 支持最高管理员重置子账号密码；重置后会撤销该账号所有活跃会话，响应不暴露 passwordHash。
  • 支持停用 / 启用客户公司；停用公司会同步禁用该租户下的普通子账号并撤销活跃会话，不会波及平台最高管理员。
  • 支持离职回收：停用账号、撤销活跃会话，并清理设备 / 项目 / Skill 授权。
  • 公司停用 / 授权撤销 / 密码重置 / 离职回收等高危动作均在 PC 后台做二次确认。
  • 支持套用内置权限模板。
  • 支持设备、项目、Skill 三类授权。
  • 支持撤销单条授权。
  • 支持查看最近权限审计记录。

Skill 治理

  • 复用 /api/v1/admin/skills/requests，支持创建 install / update / uninstall / rollback / version_lock 请求。
  • 设备端仍由 local-agent 按既有 lifecycle 链路认领和完成。
  • 管理后台只负责下发治理请求与查看请求状态，不绕过设备端 allowlist、checksum、备份和回滚约束。
  • 2026-04-30 起，PC 总后台的 Skill 治理入口改为 Skill 中心：先展示 Skill 目录、详情、授权对象和执行轨迹，再通过右侧安装向导创建生命周期请求。
  • Skill 中心 会优先使用 /api/v1/admin/access 返回的 skillCatalog，没有聚合目录时再由设备 Skill 清单前端兜底聚合，避免最高管理员必须记住每台电脑的原始 skillId。
  • 创建请求仍提交到 /api/v1/admin/skills/requests，只是把 sourceUrl / trustedSourceId / checksum 等字段放入向导步骤中，降低误操作和填表成本。

权限边界

  • /admin 页面直接跳转根路径 /，生产根路径由 admin.boss.hyzq.net 站点内部 rewrite 到独立后台静态入口。
  • 非 highest_admin 访问 /enterprise-admin 时只看到“仅最高管理员可用”提示。
  • /api/v1/admin/overview 未登录返回 401，非最高管理员返回 403。
  • /api/v1/admin/risks/actions 未登录返回 401，非最高管理员返回 403。
  • /api/v1/admin/risks/scan 未登录返回 401，非最高管理员返回 403。
  • /api/v1/admin/notifications/dispatch 未登录返回 401，非最高管理员返回 403。
  • 后台 mutation 路由和认证 mutation 路由会拒绝显式跨站浏览器请求；原生 APP 请求通过 x-boss-native-app: 1 豁免浏览器 CSRF 检查。
  • 后台 mutation 路由会把 x-forwarded-for / x-real-ip / user-agent / x-request-id 写入 permissionAuditLogs；高危动作会额外写入安全化 beforeJson / afterJson 快照，便于企业客户追责和回放。

数据来源

  • authAccounts：账号与角色。
  • adminCompanies：客户公司 / 租户实体。
  • devices：电脑与 Codex CLI/GUI 能力状态。
  • projects：项目与设备关联。
  • opsFaults：未关闭运维故障。
  • threadContextAlerts：未解决线程上下文告警。
  • masterAgentTasks：失败任务。
  • accountDeviceGrants、accountProjectGrants、accountSkillGrants：授权汇总和过期授权统计。
  • adminNotifications：风险 SLA 超时通知账本，由 /api/v1/admin/risks/scan 幂等生成，并由 /api/v1/admin/notifications/dispatch 派发。
  • adminRiskTimeline：风险处理时间线，记录通知生成、派发和人工处置动作。

后续扩展

  • 下一期应接入企业微信 / 飞书 / 短信等更多通知渠道；当前 BOSS_ADMIN_NOTIFICATION_MODE=email 可走服务器 sendmail，默认 disabled 只记录派发状态。
  • PostgreSQL 切换仍建议先用 scripts/boss-state-store-maintenance.mjs 做备份、dry-run 迁移和回滚演练，再设置 BOSS_STATE_STORE=postgres。