commit 6e5dd00a11318149f0a8b4dcbfbc8def59005dbc Author: figmar Date: Sat Aug 29 22:41:47 2026 +0800 docs: apes-Arise × Casdoor 融合方案 v0.1 - 三方能力对比（Casdoor / apes-Authon-Server / apes-Authon-Web） - 10 项可增强 Casdoor 的 apes 能力清单（E1-E10） - 解耦架构设计（REST/Webhook/数据/前端四重契约） - 仓库布局（casdoor submodule + apes-Authonkey 扩展层） - 跟随官方更新流程与 CI 门禁 - 实施路线图 P0-P5、风险对策、待决策项 diff --git a/README.md b/README.md new file mode 100644 index 0000000..de6e460 --- /dev/null +++ b/README.md @@ -0,0 +1,7 @@ +# apes-Authonwiki + +账权平台（apes-Arise）方案与文档 Wiki。 + +## 目录 + +- [apes-Arise × Casdoor 融合方案](./apes-Arise-Casdoor融合方案.md) — 以 Casdoor 为底座融合 apes 业务账权能力的总体方案（v0.1） diff --git a/apes-Arise-Casdoor融合方案.md b/apes-Arise-Casdoor融合方案.md new file mode 100644 index 0000000..ced635b --- /dev/null +++ b/apes-Arise-Casdoor融合方案.md @@ -0,0 +1,242 @@ +# apes-Arise × Casdoor 融合方案 + +> **目标**：以 Casdoor 为基础底座，将 apes-Arise 独有的业务化账权能力（套餐/配额、伙伴云、AccessToken、操作日志、AI 配置等）以**相对解耦**的方式叠加其上，形成可长期跟随官方版本迭代的 `apes-Authonkey`。 +> +> 状态：v0.1 方案稿（待评审） +> 日期：2026-08-29 + +--- + +## 0. 摘要（TL;DR） + +| 决策项 | 结论 | +|---|---| +| 技术底座 | 采用 Casdoor（Go + Vue2/web2），**放弃** apes-Authon-Server（Spring Boot）作为运行时底座 | +| apes-Authon-Server 定位 | 降级为**能力参考实现**（业务语义蓝本），代码不直接搬入 Casdoor | +| apes-Authon-Web 定位 | 保留为**页面设计/交互蓝本**；后续页面在 Casdoor web2 内按设计重建 | +| 融合机制 | 采用**方案 C**：Casdoor 原生能力承载通用部分 + Go 扩展包承载业务增量 + **独立 web3 前端**承载 apes 业务页面 | +| 跟随官方更新 | 扩展层不 fork 官方代码目录，只依赖 Casdoor 的**公开 REST API / HTTP 路由**，官方更新时**零 merge 冲突** | +| 仓库布局 | `casdoor`（submodule，官方版本锁点）+ `apes-Authonkey`（扩展层 + 构建/部署编排） | +| 分阶段 | P0 只读同步验证 → P1 独立微服务试点 → P2 Casdoor 扩展包 → P3 前端扩展 → P4 打包分发 | + +--- + +## 1. 三方对比：Casdoor vs apes-Authon-Server vs apes-Authon-Web + +### 1.1 技术栈对比 + +| 维度 | Casdoor | apes-Authon-Server | apes-Authon-Web | +|---|---|---|---| +| 语言/运行时 | Go 1.25 | Java (Spring Boot) | JavaScript (Vue 2.7) | +| 前端 | Vue2 (`web/`) + React/TS web2 (`web2/`) 双栈 | 无（纯后端） | Vue 2.7 + Element UI + Vuex | +| ORM / 存储 | 内置多 DB 抽象（MySQL/PG/SQLite/MariaDB/ClickHouse…） | MyBatis + `dynamic-datasource` 多数据源切换 | — | +| 授权模型 | Casbin（RBAC/ABAC/ACL 等） | 自研权限体系（角色/菜单/权限点） | 前端按权限点显隐 | +| 多租户 | Organization（组织） | `@TenantSource` AOP + 数据源切换 | 按 tenant 维度传参 | +| SSO/OIDC | 内置 OIDC/OAuth2/SAML/CAS/Kerberos + 40+ IdP | 短信+密码+SSO 登录（对接外部 IdP） | 登录页 | +| 协议出口 | OIDC、OAuth2.0、SAML 2.0、CAS、SCIM、Kerberos | 仅 HTTP REST | — | + +### 1.2 能力矩阵（✔ 原生具备 / ◐ 部分具备 / ✘ 无） + +| 能力域 | Casdoor | apes-Arise | 融合动作 | +|---|---|---|---| +| OIDC / OAuth2 / SAML / CAS / Kerberos | ✔ | ✘（仅消费 SSO） | 直接用 Casdoor | +| SCIM 用户目录同步 | ✔ | ✘ | 直接用 Casdoor | +| 外部 IdP 同步（LDAP/AD/DingTalk/WeCom/Okta/AzureAD/GoogleWS/Keycloak…） | ✔（20+ Syncer） | ✘ | 直接用 Casdoor | +| RBAC/ABAC 授权（Casbin） | ✔ | ◐（自研 RBAC） | 用 Casbin 替换自研 | +| MFA（TOTP/SMS/RADIUS/Push） | ✔ | ✘ | 直接用 Casdoor | +| 用户组 / 邀请 / 验证（verification） | ✔ | ✘ | 直接用 Casdoor | +| Webhook / 事件 | ✔ | ✘ | 直接用 Casdoor | +| **套餐（Package/Plan）与订阅** | ◐（内置 Plan/Subscription/Pricing，偏 SaaS 售卖） | ✔（CustomerPackage / SysPackagePlan） | 扩展：映射到业务语义，补"租户套餐"模型 | +| **配额（Quota）** | ✘ | ✔（SysQuota） | **扩展包实现**：配额中心 + 中间件 | +| **伙伴云（Huoban）客户数据同步** | ✘ | ✔（11 个 Huoban DTO + 同步服务） | **扩展包实现**：webhook/syncer 适配 | +| **AccessToken 外部 API 鉴权**（X-Access-Token/Bearer） | ◐（有 API token，但语义不同） | ✔（AccessTokenFilter） | **扩展包实现**：token 服务 + 网关侧 Filter | +| **操作日志（Operation Log）** | ◐（有日志/审计事件，无细粒度业务操作日志） | ✔（SysOperationLog + OperationLogUtil） | **扩展包实现**：AOP 式日志中间件 + 管理页面 | +| **组织架构（SysOrganization）** | ◐（Organization/Group 偏 IT 视角） | ✔（企业级组织树） | 扩展：用 Group/Label 建模或自定义 Org 模型 | +| **AI / LLM / Agent / Skill 配置管理** | ✘ | ✔（前端 11 个页面，后端未提取） | **独立扩展**：作为 apes 业务模块，不进 Casdoor 核心 | +| 用户偏好（UserPreference） | ◐ | ✔ | 扩展：Profile 字段 + 自定义存储 | +| 短信/密码复合登录 | ◐（有 SMS MFA 但非"短信+密码"组合主登录） | ✔ | 扩展：自定义 Provider 或登录页编排 | + +### 1.3 关键结论 + +1. **Casdoor 是"协议与身份"的强底座**，apes-Arise 在协议层没有积累，不应重复造轮子。 +2. **apes-Arise 的差异化价值在"业务账权层"**：套餐、配额、伙伴云、AccessToken、操作日志、AI 配置——这些恰是 Casdoor 的空白或弱项，是 `apes-Authonkey` 的核心增量。 +3. **Spring Boot → Go 是语言跨越**，apes-Authon-Server 的 Java 代码**不可直接复用**，只能作为**业务语义参考**重新实现为 Go 扩展包。这是本方案最重要的工程决策。 +4. 前端：apes-Authon-Web 的 Vue2 页面**不迁移**到 Casdoor（Casdoor 自身是 web/web2 双栈），而是作为**交互蓝本**，在独立 web3 扩展前端中用 Casdoor 的 UI 规范重建。 + +--- + +## 2. 可增强 Casdoor 的 apes-Arise 内容清单 + +> 判定标准：**Casdoor 原生缺失或弱、且 apes-Arise 已有成熟实现语义**的能力。 + +| # | 能力 | apes 来源 | Casdoor 现状 | 增强方式 | 优先级 | +|---|---|---|---|---|---| +| E1 | 配额中心（Quota） | SysQuota + 配额校验逻辑 | 无 | Go 扩展包：配额模型 + 中间件 + 管理 API | P2 高 | +| E2 | 租户套餐（Package） | CustomerPackage / SysPackagePlan | 有 SaaS 售卖型 Plan，语义不同 | Go 扩展包：租户↔套餐映射、套餐能力开关 | P2 高 | +| E3 | 伙伴云同步 | 11 个 Huoban DTO + 同步服务 | 无 | Go 扩展包：基于 Casdoor Webhook 触发 + 伙伴云 OpenAPI 客户端 | P1 中 | +| E4 | AccessToken 外部 API 鉴权 | AccessTokenFilter + X-Access-Token | API token 语义不同 | Go 扩展包：token 签发/校验服务 + 网关 Filter 规范 | P1 高 | +| E5 | 细粒度操作日志 | SysOperationLog + OperationLogUtil | 有审计但粒度粗 | Go 扩展包：注解/中间件式日志采集 + 查询 API + 页面 | P2 中 | +| E6 | 企业组织架构 | SysOrganization | Group/Label 偏 IT | Go 扩展包：Org 树模型（或 Group 增强）+ 页面 | P3 低 | +| E7 | 短信+密码复合登录 | 登录服务 | 非默认组合 | Casdoor 自定义 Provider / 登录页编排 | P3 低 | +| E8 | 用户偏好 | UserPreference | Profile 可扩展 | 扩展包：偏好存储 + API | P3 低 | +| E9 | AI/LLM/Agent/Skill 配置 | 前端 11 页面 + 未提取后端 | 无 | **独立业务模块**（不进 Casdoor 核心），仅复用 Casdoor 认证 | P3 低 | +| E10 | 多租户数据源切换 | `@TenantSource` + dynamic-datasource | Organization 单库 | **架构级**：评估按租户分库/分 schema（远期） | P4 远期 | + +> 说明：E9（AI 配置）本质是 apes 自身业务，与"账权底座"关系弱，建议作为 `apes-Authonkey` 下的独立业务模块存在，**不侵入 Casdoor**。 + +--- + +## 3. 架构设计 + +### 3.1 总体分层 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 接入层 API Gateway / Ingress │ +│ ├─ 路由 /api/* → casdoor-core（官方） │ +│ ├─ 路由 /apes/api/* → apes-extension（扩展 API） │ +│ └─ 静态 /apes-web/* → web3 前端（apes 业务页面） │ +├─────────────────────────────────────────────────────────────┤ +│ 前端层 │ +│ web2（Casdoor 原生管理台） + web3（apes 业务扩展页面） │ +│ web3 通过 Casdoor OIDC 登录，调用 /apes/api 扩展接口 │ +├─────────────────────────────────────────────────────────────┤ +│ 扩展层 apes-extension（Go 进程，apes-Authonkey 核心） │ +│ ├─ E1 配额中心 ├─ E2 租户套餐 ├─ E3 伙伴云同步 │ +│ ├─ E4 AccessToken ├─ E5 操作日志 ├─ E6 组织架构 │ +│ └─ 通过 Casdoor REST API 读写身份/组织/权限数据（零代码耦合） │ +├─────────────────────────────────────────────────────────────┤ +│ 底座层 casdoor-core（官方源码，git submodule，版本锁点） │ +│ ├─ 身份/认证（OIDC/OAuth2/SAML/CAS/MFA/SCIM） │ +│ ├─ 授权（Casbin） ├─ 组织/用户/组 ├─ 同步器 ├─ Webhook │ +│ └─ 前端 web / web2 │ +├─────────────────────────────────────────────────────────────┤ +│ 数据层 PostgreSQL/MySQL（casdoor 库 + apes 扩展表同库） │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 3.2 解耦机制（核心） + +apes-Authonkey 与 casdoor 的边界**只通过契约**建立，不通过代码修改建立： + +1. **REST 契约**：扩展层调用 Casdoor 官方 REST API（`/api/users`、`/api/organizations`、`/api/permissions` 等），不 import casdoor 的 Go 包。Casdoor 升版只需保证 API 兼容（官方语义化版本保证）。 +2. **Webhook 契约**：Casdoor 事件（用户创建/变更/删除）→ Webhook → 扩展层（伙伴云同步、操作日志、配额初始化）。 +3. **数据契约**：扩展表（quota、package、oplog、org_tree…）独立建表、独立 migration，与 casdoor 表**零外键硬依赖**（仅逻辑关联 `owner/org` 字符串）。 +4. **前端契约**：web3 通过 OIDC 登录 + `/apes/api` 前缀访问，与 web2 完全分离。 +5. **不 fork 官方目录**：`casdoor/` 以 git submodule 形式引入，**永不修改其内文件**；所有增量在 `apes-Authonkey/` 内。官方更新 = 更新 submodule 指针 + 跑兼容检查。 + +> 备选：若未来个别能力（如登录页组合）必须改 Casdoor 内部，使用 Casdoor 的**插件/自定义 Provider 扩展点**或**受控 patch 集**（`patches/` 目录，`git apply` 应用），patch 集纳入 CI 校验，升版时自动检测 patch 是否仍可应用。 + +### 3.3 仓库布局（落地） + +在 Gitea `apes-Arise` 组织下新建： + +| 仓库 | 类型 | 内容 | 说明 | +|---|---|---|---| +| `apes-Authonkey` | 主仓库（monorepo） | 见下结构 | 唯一需要人工开发的仓库 | +| `casdoor`（submodule） | 引用官方 | casdoor/casdoor | 版本锁点，跟随官方 tag | + +`apes-Authonkey/` 目录结构： + +``` +apes-Authonkey/ +├── casdoor/ # git submodule → github.com/casdoor/casdoor（只读，锁 tag） +├── extension/ # Go 扩展模块（module: gitea.apescale.com/apes-Arise/apes-Authonkey/extension） +│ ├── cmd/server/ # 扩展服务入口（独立进程，监听 :8090） +│ ├── internal/ +│ │ ├── quota/ # E1 配额中心 +│ │ ├── pkgplan/ # E2 租户套餐 +│ │ ├── huoban/ # E3 伙伴云同步 +│ │ ├── accesstoken/ # E4 AccessToken +│ │ ├── oplog/ # E5 操作日志 +│ │ └── orgtree/ # E6 组织架构 +│ ├── casdoorapi/ # Casdoor REST 客户端（封装官方 API，契约层） +│ ├── models/ # 扩展表模型 +│ └── migrations/ # 独立 migration（golang-migrate / sql） +├── web3/ # apes 业务扩展前端（Vite + Vue3，参考 web2 技术栈） +├── gateway/ # 路由/鉴权编排（nginx/caddy 配置 + AccessToken Filter 规范） +├── deploy/ # docker-compose / k8s 编排，统一拉起 casdoor + extension + web3 +├── patches/ # 受控 patch 集（默认空，仅当必须改官方代码时启用） +├── scripts/ +│ ├── upgrade-casdoor.sh # 升版流程：更新 submodule → 跑兼容检查 → 构建 +│ └── compat-check.sh # 校验：API 契约测试 + patch 可应用性 + 构建 +└── docs/ # 本 wiki 同步的源文档 +``` + +### 3.4 跟随官方版本更新流程 + +``` +官方发版 (v2.x) + │ + ▼ +1. git submodule update --remote（或锁定到指定 tag） + ▼ +2. scripts/compat-check.sh + ├─ 跑 casdoorapi 契约测试（对扩展层用到的 API 逐个打桩/集成） + ├─ 校验 patches/ 是否仍可 git apply（无 patch 则跳过） + └─ 构建 casdoor + extension + web3 + ▼ +3. 部署测试环境 → 回归（登录/授权/配额/日志/伙伴云） + ▼ +4. 生产滚动发布；submodule tag 写入 CHANGELOG +``` + +**冲突面**：因扩展层零修改官方代码，升版冲突只可能来自 **API 不兼容**（契约测试兜底）和 **patch 失效**（patch 可应用性校验兜底），均为**可检测、可阻断**，不会出现 git merge 冲突地狱。 + +--- + +## 4. 实施路线图 + +| 阶段 | 目标 | 关键交付 | 风险 | +|---|---|---|---| +| **P0 验证**（1–2 周） | 跑通 Casdoor 本地部署，验证 OIDC 登录 + 组织/权限模型可承载 apes 语义 | Casdoor docker 部署；OIDC 客户端联调；语义映射表（apes 概念 → Casdoor 对象） | apes 多租户语义与 Organization 的匹配度 | +| **P1 独立微服务试点**（2–4 周） | 选 1–2 个增量（E4 AccessToken、E3 伙伴云）做成**独立 Go 微服务**，先不碰 Casdoor 内部，跑通"契约式集成" | extension 骨架 + casdoorapi 客户端 + E4/E3 最小实现 + 契约测试 | 契约稳定性 | +| **P2 配额/套餐/日志**（4–6 周） | 实现 E1/E2/E5，补全业务账权闭环 | 配额中心 + 租户套餐 + 操作日志（API + 页面） | 配额与 Casbin 权限的边界划分 | +| **P3 前端扩展**（4 周，可与 P2 并行） | web3 搭建，按 apes-Authon-Web 蓝本重建业务页面 | web3 脚手架 + OIDC 登录 + 配额/套餐/日志/伙伴云管理页面 | Vue3 迁移工作量 | +| **P4 打包分发**（2–3 周） | docker-compose/k8s 一键部署；升版脚本 + CI | 部署编排 + upgrade 脚本 + CI 流水线 + 操作手册 | 多组件版本一致性 | +| **P5 远期** | E6 组织树、E7 复合登录、E9 AI 模块、E10 租户分库 | 按需 | 架构级改造需专项论证 | + +--- + +## 5. 风险与对策 + +| 风险 | 等级 | 对策 | +|---|---|---| +| Casdoor API 破坏性变更 | 中 | 契约测试纳入 CI；submodule 锁 tag，不自动跟 latest；升级走 compat-check 门禁 | +| 必须修改 Casdoor 内部代码 | 中 | 优先用扩展点/自定义 Provider；确需修改则进 `patches/` 受控集并加可应用性校验；避免在业务逻辑上依赖 patch | +| Spring Boot → Go 语义偏差 | 中 | apes-Authon-Server 作为**参考实现**逐模块对照；契约测试用 apes 原系统行为做黄金用例 | +| 多租户数据源切换（E10）与 Casdoor 单库模型冲突 | 高 | P5 专项论证；近期用 Organization 逻辑隔离，不做物理分库 | +| 前端双栈（web2/web3）体验割裂 | 低 | web3 复用 web2 设计规范与组件库；OIDC 单点登录保证体验连续 | +| 伙伴云 OpenAPI 变更 | 低 | 适配器隔离在 `internal/huoban`，便于替换 | + +--- + +## 6. 待决策项（Open Questions） + +1. **扩展层形态**：独立微服务（本方案默认）vs 编译进 Casdoor 的扩展包（`go:linkname`/插件）？——建议**独立微服务**，解耦最彻底；若性能/调用链要求高，再评估编译期扩展。 +2. **租户套餐与 Casdoor 内置 Plan/Subscription 的关系**：替换、并存还是包装？——建议**并存**，Casdoor 原生 Plan 服务其 SaaS 售卖场景，apes 的"租户套餐"独立建模。 +3. **AI/LLM 模块（E9）** 是否纳入 apes-Authonkey 范围？——建议纳入但作为独立业务模块，不侵入 Casdoor。 +4. **web3 技术栈**：Vue3 + Vite（对齐 web2）还是沿用 Vue2 + Element UI（对齐 apes-Authon-Web 降低迁移成本）？——建议 **Vue3 + Vite**，与 Casdoor web2 同代。 +5. **数据库**：扩展表与 Casdoor 同库不同表，还是独立库？——建议**同库**（事务一致、运维简单），表前缀 `apes_` 隔离。 +6. **部署形态**：docker-compose（单实例）还是 k8s（多副本）先行？——建议 compose 先行，k8s 跟进。 + +--- + +## 7. 附：apes-Authon-Server 能力 → 融合映射速查 + +| apes 模块 | 融合去向 | +|---|---| +| 用户/角色/菜单/权限 | Casdoor 用户 + Casbin（Casbin model 按 apes 权限点重建） | +| 多租户（@TenantSource） | Casdoor Organization +（E10 远期分库） | +| 套餐/配额 | E1/E2 扩展包 | +| 伙伴云同步 | E3 扩展包（Webhook 触发） | +| AccessToken | E4 扩展包 + 网关 Filter | +| 操作日志 | E5 扩展包 | +| 组织架构 | E6 扩展包 | +| 短信+密码登录 | E7 自定义 Provider | +| 用户偏好 | E8 Profile 扩展 | +| AI/LLM/Agent/Skill | E9 独立业务模块 | + +--- + +*本方案为 v0.1 稿，待评审后定稿。后续每个阶段的详细设计将另文补充于本 wiki。*