系统架构
本文介绍 Code Bird Cloud 的整体技术架构、分层设计与核心子系统，帮助开发者理解平台的内部运作方式。
整体架构
Code Bird Cloud 采用前后端分离架构，后端基于 Go 语言（Gin + GORM + PostgreSQL），前端基于 React（UmiJS + Ant Design）。系统通过 RESTful API 进行交互，OIDC 端点完全遵循标准协议。
+---------------------------+
| 客户端应用 |
| (Web / SPA / Mobile / M2M) |
+------------+--------------+
|
OIDC / REST API
|
+------------v--------------+
| Go 后端服务 |
| (Gin HTTP Framework) |
| |
| +---------------------+ |
| | Interface Layer | |
| | (API Handlers, OIDC) | |
| +----------+----------+ |
| | |
| +----------v----------+ |
| | Application Layer | |
| | (DTOs, Constants) | |
| +----------+----------+ |
| | |
| +----------v----------+ |
| | Domain Layer | |
| | (Models, Services, | |
| | Repository IFaces) | |
| +----------+----------+ |
| | |
| +----------v----------+ |
| | Infrastructure Layer | |
| | (DAO, Config, Utils) | |
| +----------+----------+ |
| | |
+-------------+--------------+
|
+------------+------------+
| |
+-----v------+ +------v-----+
| PostgreSQL | | Redis |
| (主库) | | (缓存) |
+------------+ +------------+
+-------------------+ +-------------------+ +-------------------+
| Admin Console | | Platform Admin | | Login Page |
| (UmiJS + AntD) | | (UmiJS + AntD) | | (React + Vite) |
| 租户管理后台 | | 平台管理后台 | | 用户登录页面 |
+-------------------+ +-------------------+ +-------------------+DDD 分层架构
后端采用领域驱动设计（DDD）的四层分层架构，各层职责清晰，依赖关系自上而下。
Interface Layer（接口层）
路径：backend/src/interfaces/
接口层负责处理 HTTP 请求和响应，是系统与外部交互的入口。
- API Handlers -- 处理 RESTful API 请求（Management API、Platform Admin API）
- OIDC Endpoints -- 实现标准 OIDC 协议端点（authorize、token、userinfo 等）
- Middleware -- CORS、认证校验、日志记录、异常处理等中间件链
- Startup -- 服务启动逻辑、路由注册、数据库迁移
Application Layer（应用层）
路径：backend/src/application/
应用层定义数据传输对象和应用级常量，协调领域层完成业务用例。
- DTOs -- 请求和响应的数据传输对象，统一嵌入
helper.BaseRequest - Constants -- 应用级常量定义
- Exceptions -- 业务异常定义
- Templates -- 模板文件
Domain Layer（领域层）
路径：backend/src/domain/
领域层是业务逻辑的核心，包含领域模型、业务规则和仓储接口。
- Models -- 领域模型定义（User、Application、Organization、Role 等）
- Services -- 领域服务，封装业务逻辑，统一返回
*helper.DefaultResult - Repository Interfaces -- 仓储接口定义，基础接口位于
base.go，提供标准 CRUD 操作
Infrastructure Layer（基础设施层）
路径：backend/src/infrastructure/
基础设施层提供技术实现，包括数据库访问、外部服务集成和工具类。
- DAO -- 数据访问对象，实现 Repository 接口，基于 GORM 操作 PostgreSQL
- Config -- 配置文件解析与管理
- Logging -- 多 Logger 架构（SystemLogger、DatabaseLogger、UpgradeLogger）
- Utils -- 通用工具函数
核心子系统
Authentication（认证子系统）
负责用户身份验证，基于 OIDC/OAuth 2.1 标准协议实现。
- 支持 Authorization Code Flow、Authorization Code + PKCE、Client Credentials 三种授权流程
- JWT 令牌体系：Access Token、Refresh Token、ID Token
- OIDC 令牌使用 ES256 签名，Admin 令牌使用 HS256 签名
- 支持用户名密码、邮箱验证码、短信验证码等多种登录方式
- 登录体验（Sign-in Experience）可配置，包括登录方式、注册方式和密码策略
Authorization（授权子系统）
负责访问控制，实现两级 RBAC 模型。
- 系统级 RBAC -- API Resource + Scope + Role + User 四个核心实体，面向全局资源
- 组织级 RBAC -- Organization Role Template + Organization Permission Template，面向组织内资源
- Management API 预定义了
manage:all、manage:users、manage:applications等权限范围 - 权限检查流程：提取 Token -> 验证签名 -> 识别认证类型 -> 查询权限 -> 匹配所需 Scope
Organization（组织子系统）
负责 B2B 多组织架构管理。
- 组织 CRUD 与成员管理
- 组织角色模板和权限模板（租户级别共享定义）
- 组织用户角色分配（每个组织独立分配）
- 组织 M2M 应用角色分配
- 用户可同时属于多个组织
Application（应用子系统）
负责 OAuth2 客户端应用的生命周期管理。
- 支持 Traditional Web、SPA、M2M 三种应用类型
- 每个应用独立管理 Client ID 和 Client Secret
- 支持 Redirect URI 配置和 Client Secret 轮换
- M2M 应用支持绑定 API Resource Scope 权限
Connector（连接器子系统）
负责第三方认证和通知通道的集成。
- 可插拔的连接器体系
- 支持社交登录连接器（微信、GitHub、Google 等）
- 支持邮件连接器和短信连接器
- 连接器配置独立于应用，在租户级别管理
Audit Log（审计日志子系统）
负责记录系统关键操作。
- 按类型、时间范围、操作者等条件查询
- 覆盖管理操作和认证事件
- 支持分页查询和导出
OIDC 协议兼容性
Code Bird Cloud 实现了以下 OIDC/OAuth 2.1 标准端点：
| 端点 | 路径 | 说明 |
|---|---|---|
| Discovery | /.well-known/openid-configuration | 自动发现配置 |
| JWKS | /.well-known/jwks.json | 公钥端点（ES256） |
| Authorization | /oidc/authorize | 授权端点 |
| Token | /oidc/token | 令牌端点 |
| UserInfo | /oidc/userinfo | 用户信息端点 |
| Revocation | /oidc/revoke | 令牌吊销端点 |
| End Session | /oidc/end-session | 会话结束端点 |
签名算法采用 ES256（ECDSA P-256），密钥在系统初始化时自动生成，以 JWK 格式存储在数据库中。每个密钥拥有唯一的 kid（Key ID），通过 JWKS 端点公开发布，客户端可据此验证令牌签名。
多租户数据模型
Code Bird Cloud 采用两级管理体系：
Platform（平台级）
|
+-- Platform Admin（平台管理员）
| 管理所有租户的生命周期
|
+-- Tenant（租户）
|
+-- Tenant Admin（租户管理员）
| 管理租户内的所有资源
|
+-- Users（终端用户）
+-- Applications（OAuth2 应用）
+-- Resources + Scopes（API 资源与权限）
+-- Roles（系统级角色）
+-- Organizations（组织）
| +-- Members（组织成员）
| +-- User Roles（组织用户角色）
+-- Organization Role Templates（组织角色模板）
+-- Organization Permission Templates（组织权限模板）
+-- Connectors（连接器）
+-- Signing Keys（签名密钥）
+-- Sign-in Experience（登录体验）
+-- Logs（审计日志）- 平台管理员通过 Platform Admin Console（
/api/platform/）管理租户和租户管理员 - 租户管理员通过 Admin Console（
/api/admin/和/api/v1/）管理租户内的所有资源 - 所有租户数据通过
tenant_id进行逻辑隔离 - 创建新租户时，系统自动初始化 Management API 资源、M2M 角色、ECDSA 签名密钥和默认登录体验
前端架构
前端包含三个独立的子项目：
| 子项目 | 路径 | 框架 | 用途 |
|---|---|---|---|
| Admin Console | frontend/admin/ | React 19 + UmiJS 4.x + Ant Design 5.x | 租户管理后台 |
| Platform Admin | frontend/platform-admin/ | React 19 + UmiJS 4.x + Ant Design 5.x | 平台管理后台 |
| Login Page | frontend/login/ | React + Vite | 用户登录页面 |
Admin Console 和 Platform Admin 基于 UmiJS 框架，使用 Ant Design Pro Components 构建管理界面。Login Page 基于 Vite 构建，提供用户认证交互界面。
生产环境下，前端静态文件由后端服务统一托管，无需独立部署前端服务器。