基础架构 · 一站式工作台 / SSO 详细设计文档

版本: v0.1
日期: 2026-07-06
归属: 基础架构 / 一站式工作台 / SSO

1. 模块定位与目标

以飞书为协同入口，以 SSO/RBAC 为权限事实源，为全员提供统一登录、统一权限、统一工作台入口。所有内部系统账号收口到 IdP，禁止各系统独立维护用户表作为权限事实源。

目标	说明
账号统一	入职/转岗/离职同步到所有业务系统，无僵尸账号。
权限可审计	所有授权有 approver、有效期、审计记录，离职 1 小时内回收。
单点登录	内部系统 90%+ 接入 SSO，用户无需记多套密码。
工作台聚合	系统入口、待办、告警、常用链接统一展示，新人 1 小时内上手。

2. 执行计划

阶段	时间	交付物	Owner	工作量
P0 IdP 选型部署	0–14 天	部署 IdP（Casdoor/Keycloak）、接入飞书组织同步	平台后端	1人×2周
P1 SSO 接入核心系统	15–35 天	GitLab/管理后台/监控平台 SSO 接入，OIDC/SAML	平台后端	1人×3周
P2 RBAC 建立	36–55 天	角色定义、菜单权限、临时授权、离职自动回收	平台后端+IT	2人×3周
P3 工作台	56–80 天	工作台 Web UI，聚合系统入口/待办/告警	前端+后端	2人×3周
P4 全量接入	81–120 天	剩余内部系统全部接入 SSO，清理本地账号	各系统 owner	分批并行
P5 审计完善	121–150 天	权限复核周期、异常登录告警、合规报告	安全+IT	1人×3周

3. 困难点与复杂度分析

困难点	复杂度	应对
飞书组织架构与 RBAC 角色映射	高	飞书部门/岗位 → 角色 mapping 表由 IT 维护，变更走飞书审批，自动同步。
各系统协议不统一（OIDC/SAML/LDAP）	中	IdP 统一对外提供 OIDC（主）+SAML（兼容老系统），各系统接 IdP 不直连飞书。
临时授权生命周期管理	中	临时授权设最长 72 小时，到期自动回收，续期需重新审批。
离职账号跨系统及时回收	中	飞书离职 → 触发 Webhook → IdP 禁用账号 → 所有 SSO 会话失效，目标 1 小时内完成。
工作台待办聚合各系统数据	中	v0.1 只聚合飞书审批和告警，各业务系统待办通过标准 Webhook 推送，不做双向同步。

4. 核心流程

flowchart LR
  A["员工入职 / 飞书账号激活"] --> B["组织同步 Webhook"]
  B --> C["IdP 创建账号 + 匹配角色"]
  C --> D["下发工作台入口权限"]
  D --> E["员工 SSO 登录各系统"]
  E --> F["登录审计记录"]
  G["员工离职"] --> H["飞书离职事件"]
  H --> I["IdP 立即禁用"]
  I --> J["所有系统会话失效"]
  J --> K["权限回收审计"]

5. 系统架构

flowchart LR
  FEISHU["飞书 IdP / 组织"] --"Webhook 同步"--> SYNC["Identity Sync Service"]
  SYNC --> IDP["IdP (Casdoor/Keycloak)"]
  IDP --"OIDC"--> GITLAB["GitLab"]
  IDP --"OIDC"--> ADMIN["管理后台"]
  IDP --"OIDC"--> MON["监控平台"]
  IDP --"OIDC/SAML"--> OTHER["其他内部系统"]
  IDP --> RBAC["RBAC Service"]
  RBAC --> PORTAL["工作台 Portal"]
  PORTAL --> TODO["待办聚合"]
  PORTAL --> ALERT["告警聚合"]
  IDP --> AUDIT["登录审计"]

6. 关键技术决策

决策点	选择	理由
IdP	Casdoor（首选）/ Keycloak（备选）	Casdoor 轻量、国内社区活跃、飞书对接有现成方案；Keycloak 功能全但重。
SSO 协议	OIDC (主) + SAML 2.0 (兼容)	OIDC 现代标准，兼容 GitLab/Grafana；老系统 SAML 兼容。
飞书同步	飞书开放平台 Webhook + 定期 Diff	事件驱动为主，每日全量对账兜底，防漏同步。
工作台框架	轻量 React SPA + API 聚合层	v0.1 不做低代码门户，只做入口聚合和待办展示。
MFA	TOTP (飞书验证码)	对接飞书 MFA，减少用户额外操作。

7. 数据模型

模型	关键字段	说明
`IdentityAccount`	`id`、`feishu_user_id`、`email`、`department`、`status`、`synced_at`	统一账号，以飞书 ID 为主键。
`RoleBinding`	`id`、`user_id`、`role`、`scope`、`is_temporary`、`expire_at`、`approver_id`	角色授权，含临时授权标记。
`WorkspaceApp`	`id`、`name`、`url`、`owner`、`sso_protocol`、`risk_level`、`visible_roles`	工作台入口定义。
`LoginEvent`	`id`、`user_id`、`app_id`、`ip`、`user_agent`、`result`、`occurred_at`	登录审计事件。
`PermissionAudit`	`id`、`user_id`、`action`、`role`、`operator_id`、`reason`、`occurred_at`	权限变更审计。

8. 接口设计

接口	方法	说明
`/auth/sso/callback`	GET	OIDC 回调，建立会话。
`/accounts`	GET	账号列表，含状态和角色。
`/accounts/{id}/roles`	GET/POST/DELETE	查询 / 授予 / 回收角色。
`/workspace/apps`	GET	工作台应用入口列表（按当前用户权限过滤）。
`/workspace/todos`	GET	待办聚合（飞书审批 + 告警）。
`/audit/logins`	GET	登录审计查询。

9. 验收点

验收点	量化标准
SSO 覆盖率	核心内部系统（GitLab/管理后台/监控/工作台）100% 接入 SSO。
账号同步时效	飞书入职/离职事件 → IdP 同步完成 ≤ 5 分钟。
离职权限回收	离职账号 1 小时内所有系统会话失效，100% 有回收审计记录。
临时授权到期	临时高权限 100% 有到期时间，到期自动回收，0 例超期未回收。
工作台入口覆盖	研发/运维/运营/售后常用入口 100% 在工作台可见。
异常登录告警	异地 IP/非工作时间登录 30 分钟内推送飞书告警到安全负责人。

10. 风险与应对

风险	应对
IdP 单点故障影响所有系统登录	IdP 高可用部署（2 实例），提供 Break-Glass 紧急账号（离线保存）。
飞书 Webhook 丢失导致账号不同步	每日全量对账，差异自动补偿，异常告警到 IT。
RBAC 权限模型过细导致落地慢	v0.1 先按岗位/系统/菜单三级，数据行级权限后期逐步补齐。
工作台成为大而全门户	v0.1 只做入口聚合和待办，不承载业务事实数据，功能范围由产品 owner 把关。