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、风险对策、待决策项
This commit is contained in:
@@ -0,0 +1,7 @@
|
||||
# apes-Authonwiki
|
||||
|
||||
账权平台（apes-Arise）方案与文档 Wiki。
|
||||
|
||||
## 目录
|
||||
|
||||
- [apes-Arise × Casdoor 融合方案](./apes-Arise-Casdoor融合方案.md) — 以 Casdoor 为底座融合 apes 业务账权能力的总体方案（v0.1）
|
||||
@@ -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。*
|
||||
Reference in New Issue
Block a user