fischer
/
fischer-agentkit
1
0
Fork 0
Code Issues Pull Requests Actions 87 Packages Projects Releases Wiki Activity
fischer-agentkit/docs/brainstorms/2026-06-21-admin-console-re...

8.3 KiB
Raw Blame History

Admin Console — Enterprise Department-Scoped Management

Date: 2026-06-21 Status: Draft (revised 2026-06-21 — SaaS multi-tenant → enterprise department-scoped) Branch: feat/admin-console Author: brainstorm session

Outcome

为 Fischer AgentKit 构建统一的企业管理端，采用"嵌入主应用 /admin 路由组 + 架构预留拆分能力"方案。Web UI 和 CLI 双通道共享同一套 service 层。核心模型是单企业部署 + 部门级权限隔离 + 能力按部门绑定：人事部有人事 skill + 人事系统 DB 权限，研发部有编码 skill，部门间资源隔离、用户可多部门（权限并集）。MVP 覆盖 5 个管理领域：部门与用户、LLM 配置、Skill 与 KB、用量仪表盘与配额。

Background

当前 AgentKit 没有统一管理端：

  • 后端 admin 端点只有 4 个（session 管理），无 user CRUD / LLM 配置 / 用量分用户
  • 前端只有 1 个 admin 页面（/admin/users，仅会话管理）
  • LLM 配置只在 agentkit.yaml，运行时不可改
  • KB/Skill 有 CRUD API 但不是 admin-only，无部门隔离
  • 权限模型有 3 级（member/operator/admin）但实际使用率极低
  • 管理工作流是"零散脚本不成体系"

Actual Usage Scenario (revised)

单企业部署一套 AgentKit，按部门/职能划分权限：

  • 人事部：拥有人事专用 skill + 访问人事系统数据库的权限，无编码能力
  • 研发部：拥有编码 skill + 代码仓库访问权限
  • 财务部：拥有财务分析 skill + 财务系统访问权限
  • 个人用户属于一个或多个部门（权限并集），如 CFO 可兼管财务和运营
  • 管理员按部门分配能力，用户继承所属部门的能力

这不是 SaaS 多租户——不需要租户计费、跨租户数据隔离、租户 CRUD。核心是部门（能力组）+ 用户多部门归属 + 能力按部门绑定。

Primary Actors

  • 超级管理员（企业 IT）：管理所有部门、全局 LLM 配置、跨部门用量监控、用户管理
  • 部门管理员（部门负责人）：管理本部门成员、本部门 Skill/KB、本部门用量
  • 普通用户：属于一个或多个部门，继承部门能力，受部门配额约束
  • 运维自动化：通过 CLI agentkit admin <domain> <action> 执行管理操作，与 Web UI 等价

Scope

MVP（第一期）

  1. 部门与用户管理

    • 部门 CRUD：创建、列表、编辑、禁用/启用、删除（人事/研发/财务等）
    • 部门能力绑定：每个部门可绑定专属 skill、KB、工具权限、LLM 配额
    • 用户 CRUD：创建、列表、编辑、禁用/启用、删除
    • 用户多部门归属：一个用户可属于多个部门（user_departments 多对多表），权限取并集
    • 角色管理：超级管理员 / 部门管理员 / 普通用户
    • 密码重置：管理员重置任意用户密码
    • 当前已有的会话管理（revoke/list）保留并集成
    • 数据隔离：所有资源表（skills、kb_documents、llm_usage 等）加 department_id 列，用户访问时只能看到所属部门的资源（多部门取并集）

  2. LLM 配置管理

    • Provider/Model/API Key CRUD：运行时增删改，不重启服务
    • Fallback 链配置：可视化编辑 provider fallback 顺序
    • 按部门配额：每部门可配置独立的 provider/model 白名单和 token 上限
    • 成本上限：按部门/用户设置日/月成本上限，超限硬拒绝（返回 429）
    • 配置从 agentkit.yaml 迁移到数据库，支持运行时热重载
    • 向后兼容：首次启动时自动从 agentkit.yaml 导入现有配置

  3. Skill 与 KB 管理

    • Skill 启停/编辑/导入：admin 可启用/禁用任意 skill，编辑 skill 配置，YAML 导入
    • Skill 按部门绑定：人事 skill 只对人事部可见，编码 skill 只对研发部可见
    • KB 文档 CRUD/同步/重建索引：admin 可管理所有 KB 文档
    • KB 按部门隔离：每部门有独立的 KB 资源池

  4. 用量仪表盘 + 配额

    • 按部门/用户/时间维度查看 LLM token 用量、成本、调用次数
    • 可视化图表：时间序列、按 provider/model 分桶、按用户排行
    • 报表导出：CSV/JSON
    • 配额上限：按部门/用户设置 token/成本上限，超限硬拒绝（429）
    • 告警：配额达到 80%/100% 时触发（MVP 只做日志告警）

产品形态

  • Web UI：/admin/* 路由组，独立 AdminLayout + 左侧导航 + 5 个管理页面
  • CLI：agentkit admin <domain> <action> 镜像所有 Web UI 操作
  • 后端：独立 admin_router APIRouter 实例，未来可拆分到独立 FastAPI 应用
  • 认证：共享现有 JWT 认证，admin 端点要求 admin 角色

架构决策

  • 部门隔离：共享数据库 + department_id 列。DepartmentContextMiddleware 在请求级别注入用户所属部门列表，所有 repository 层强制按 department_id IN (...) 过滤（多部门取并集）。
  • 配置存储：LLM 配置从 agentkit.yaml 迁移到数据库（llm_providers / llm_models / llm_api_keys 表），支持运行时热重载。首次启动自动从 YAML 导入。
  • CLI/Web 一致性：CLI 和 Web UI 调用同一套 service 层，避免双份业务逻辑。
  • 预留拆分：admin_router 是独立 APIRouter 实例，AdminLayout 是独立路由树。未来需要独立部署时，把 admin_router 挂到独立 FastAPI 实例，前端 AdminLayout 独立构建即可。

Success Criteria

  • 超级管理员可在 Web UI 或 CLI 完成全部 4 个领域的管理操作，无需手动编辑 YAML 或操作数据库
  • 部门隔离通过安全测试：人事部用户无法访问研发部的 skill/KB/用量数据（除非同时属于两个部门）
  • LLM 配置可在运行时修改并立即生效，无需重启服务
  • 用量仪表盘可按部门/用户/时间维度展示，数据延迟 < 1 分钟
  • 配额超限时系统返回 429，不会超支
  • CLI 与 Web UI 操作结果一致，调用同一 service 层
  • 用户多部门归属正确：CFO 兼管财务和运营时，可访问两个部门的所有资源

Non-Goals

  • SaaS 多租户（外部多客户、租户计费、跨租户物理隔离）——本场景是单企业部署
  • 物理隔离的独立数据库（部门数据隔离靠 department_id 列，不靠物理隔离）
  • 计费系统集成（只做用量采集和配额，不做实际计费/扣款）
  • 审计日志（第二期）
  • SLA 监控（第二期）
  • 独立管理应用部署（架构预留但不实现，MVP 嵌入主应用）
  • SSO/SAML 集成（第二期）

Dependencies / Assumptions

  • 假设：现有 users / auth_sessions 表可平滑加 department_id 列（SQLite ALTER TABLE 支持 ADD COLUMN，NULL 表示未分配部门的全局用户）
  • 假设：LLM 配置从 YAML 迁移到数据库后，agentkit.yaml 仍可作为首次导入源，不破坏现有部署
  • 依赖：现有 JWT 认证 + RBAC 权限模型（3 级）可扩展支持部门管理员角色
  • 依赖：现有 agentkit CLI 框架（Typer）支持新增 admin 命令组
  • 风险：部门隔离 middleware 完整性是关键风险——任何遗漏 department_id 过滤的查询都是数据泄露漏洞。通过 repository 层强制 department_id IN (...) 参数缓解，但需要安全测试覆盖。
  • 风险：LLM 配置热重载需要处理并发修改冲突（乐观锁或版本号）
  • 风险：用户多部门归属的权限并集计算可能产生意外权限提升（如用户从 A 部门调离但未及时移除归属）

Open Questions (Resolved)

  • 租户的粒度是"组织"还是"工作空间"？ → 已明确：单企业部署 + 部门级隔离，不是 SaaS 多租户
  • 跨租户用户的关系如何建模？ → 已明确：user_departments 多对多表，权限取并集
  • 配额超限时的行为：硬拒绝还是软降级？ → 已明确：硬拒绝（429）

Delivery Strategy

MVP 范围较大（4 领域），建议按领域分批交付：

  1. 批次 1：部门与用户管理（部门 CRUD + 用户多部门归属 + 隔离 middleware，其他领域依赖）
  2. 批次 2：LLM 配置管理（含 YAML→DB 迁移）
  3. 批次 3：Skill 与 KB 管理（按部门绑定/隔离）
  4. 批次 4：用量仪表盘 + 配额（依赖前 3 批的 department_id 埋点）

每批次独立可交付、可测试、可合并。