-
Notifications
You must be signed in to change notification settings - Fork 3
Luca edited this page Aug 26, 2026
·
2 revisions
**本文引用的文件**
- [apps/server/config/config.json](https://github.com/voidvec/fulla/blob/master/apps/server/config/config.json)
- [deploy/env/server.env.example](https://github.com/voidvec/fulla/blob/master/deploy/env/server.env.example)
- [deploy/env/docker.env.example](https://github.com/voidvec/fulla/blob/master/deploy/env/docker.env.example)
- [deploy/helm/fulla/values.yaml](https://github.com/voidvec/fulla/blob/master/deploy/helm/fulla/values.yaml)
- [apps/server/openapi.yaml](https://github.com/voidvec/fulla/blob/master/apps/server/openapi.yaml)
- [apps/server/docs/api/openapi.json](https://github.com/voidvec/fulla/blob/master/apps/server/docs/api/openapi.json)
- [docs/backend/configuration-guide.md](https://github.com/voidvec/fulla/blob/master/docs/operate/configuration-guide.md)
- [docs/backend/api-reference.md](https://github.com/voidvec/fulla/blob/master/docs/domains/api-reference.md)
- [conanfile.py](https://github.com/voidvec/fulla/blob/master/conanfile.py)
- [CMakeLists.txt](https://github.com/voidvec/fulla/blob/master/CMakeLists.txt)
- [libs/common/src/error/ErrorCatalog.cc](https://github.com/voidvec/fulla/blob/master/libs/common/src/error/ErrorCatalog.cc)
- [libs/drogon/include/fulla/drogon/error/ErrorHandler.h](https://github.com/voidvec/fulla/blob/master/libs/drogon/include/fulla/drogon/error/ErrorHandler.h)
- [tests/performance/benchmark/PerformanceBenchmark.cc](https://github.com/voidvec/fulla/blob/master/tests/performance/benchmark/PerformanceBenchmark.cc)
- [README.zh-CN.md](https://github.com/voidvec/fulla/blob/master/README.zh-CN.md)
Loading
Loading
Loading
Loading
本附录为 Fulla 的完整参考文档，覆盖配置项、API 规范、术语表、版本兼容与升级路径、第三方依赖与许可证、故障排除案例以及性能基准与优化建议。读者可据此快速完成部署、集成与运维排障。
Fulla 采用分层与模块化组织：后端服务基于 Drogon 框架，OAuth2/OIDC 能力通过插件化方式提供；前端包含用户端与管理后台；部署支持 Docker Compose 与 Helm；测试与基准覆盖单元、集成与性能场景。
graph TB
subgraph "应用层"
A["后端服务<br/>apps/server"]
B["用户前端<br/>frontends/user"]
C["管理后台<br/>frontends/admin"]
end
subgraph "平台与存储"
D["Drogon 框架"]
E["PostgreSQL"]
F["Redis"]
end
subgraph "可观测性"
G["Prometheus 指标"]
end
A --> D
A --> E
A --> F
A --> G
B --> A
C --> A
图表来源
章节来源
- 配置加载与环境变量注入：启动时读取 config.json，并通过环境变量覆盖关键配置（数据库、Redis、监听端口、前端 URL、CORS、迁移开关等）。
- OAuth2/OIDC 插件：负责授权码、令牌签发、发现元数据、JWKS、设备码、刷新令牌等流程。
- 存储适配层：PostgreSQL（持久化）、Redis（缓存与会话）、内存（开发/测试）。
- 管理 API 与用户自助 API：RBAC 保护的管理接口与用户自我服务接口。
- 可观测性：Prometheus 指标导出、审计日志、结构化错误响应。
章节来源
下图展示请求从客户端到后端控制器、OAuth2 插件、存储层的调用链路与数据流。
sequenceDiagram
participant Client as "客户端"
participant Server as "后端服务"
participant Plugin as "OAuth2 插件"
participant DB as "PostgreSQL"
participant Cache as "Redis"
Client->>Server : "GET /oauth2/authorize"
Server->>Plugin : "校验参数/会话/重定向"
Plugin->>DB : "查询客户端/用户/会话"
DB-->>Plugin : "记录"
Plugin->>Cache : "写入授权码/状态"
Cache-->>Plugin : "成功"
Plugin-->>Client : "302 重定向(带 code/state)"
Client->>Server : "POST /oauth2/token"
Server->>Plugin : "验证 client/代码/重定向"
Plugin->>DB : "校验授权码/用户"
Plugin->>Cache : "刷新令牌/访问令牌"
Plugin-->>Client : "返回令牌响应"
图表来源
- 配置文件：位于 apps/server/config/config.json，包含监听器、数据库连接池、Redis 连接、应用运行时选项、插件配置（OAuth2Plugin）与自定义配置（RBAC、CORS、前端 URL、外部认证）。
- 环境变量：通过 server.env.example 与 docker.env.example 提供，优先级高于配置文件，用于注入敏感信息与运行期差异配置。
- Helm 值：values.yaml 提供 Kubernetes 部署时的默认值与密钥注入策略。
章节来源
- apps/server/config/config.json:1-212
- deploy/env/server.env.example:1-70
- deploy/env/docker.env.example:1-89
- deploy/helm/fulla/values.yaml:1-145
- docs/backend/configuration-guide.md:1-58
- OpenAPI 定义：apps/server/openapi.yaml 与 docs/api/openapi.json 描述所有 REST 端点、安全方案与响应模型。
- 统一错误信封：Error 模型包含 category、code、details、message、request_id。
- 应用错误码：按类别划分（网络、数据库、校验、认证、授权、内部），并映射 HTTP 状态码。
- OAuth2 协议错误码：遵循 RFC 6749/7009/8628，返回 error、error_description、error_uri。
flowchart TD
Start(["请求进入"]) --> Validate["参数与鉴权校验"]
Validate --> |通过| Process["业务处理/令牌签发"]
Validate --> |失败| ErrEnvelope["返回 Error 信封"]
Process --> Success["返回 TokenResponse/资源"]
Process --> ErrProtocol["返回 OAuth2 协议错误"]
ErrEnvelope --> End(["结束"])
Success --> End
ErrProtocol --> End
图表来源
- apps/server/openapi.yaml:1-40
- apps/server/docs/api/openapi.json:1-71
- docs/backend/api-reference.md:218-283
章节来源
- apps/server/openapi.yaml:1-800
- apps/server/docs/api/openapi.json:1-800
- docs/backend/api-reference.md:1-312
- libs/common/src/error/ErrorCatalog.cc:212-242
- 错误分类与消息：ErrorCatalog 集中维护应用错误码与 OAuth2 协议错误码，确保前后端一致。
- 异常处理器：ErrorHandler 提供数据库异常、校验异常的标准化处理与日志记录。
章节来源
- libs/common/src/error/ErrorCatalog.cc:212-242
- libs/drogon/include/fulla/drogon/error/ErrorHandler.h:1-32
- Docker Compose：一键拉起后端、前端、管理后台、PostgreSQL、Redis、Prometheus。
- Helm Chart：提供生产级部署模板，支持密钥注入、迁移 Job、Ingress 与资源限制。
- 环境变量注入：在容器内通过 .env 或编排环境注入，覆盖配置文件中的敏感项。
章节来源
- docs/backend/configuration-guide.md:29-58
- deploy/env/docker.env.example:1-89
- deploy/helm/fulla/values.yaml:1-145
- 构建与依赖管理：Conan 统一管理 C++ 依赖，固定 Drogon、OpenSSL、jsoncpp、hiredis、libcurl、brotli、zlib 等版本。
- 模块依赖：Domain 层（oauth2、identity）不依赖框架层（drogon），由 CI 的 arch-guard 强制约束。
- 可选特性：with_identity、with_social、with_webauthn 控制编译范围，收缩依赖面。
graph LR
Server["后端服务"] --> Drogon["Drogon 框架"]
Server --> OAuth2["OAuth2 引擎"]
Server --> Identity["身份与认证"]
Server --> Postgres["PostgreSQL ORM"]
Server --> Redis["Redis 客户端"]
OAuth2 --> Common["共享内核"]
Identity --> Common
图表来源
章节来源
- 基准测试：Subject 生成与解析的性能压测，统计平均延迟与 P95 延迟，确保满足低开销要求。
- 目标性能：在高并发下保持稳定的延迟与吞吐，结合缓存命中率与 Redis 操作时延优化整体性能。
- 优化建议：
- 合理设置连接池大小与超时，避免数据库与 Redis 成为瓶颈。
- 启用压缩与静态资源缓存，降低带宽与 I/O 压力。
- 使用 Prometheus 监控关键指标（QPS、延迟、错误率、缓存命中率）。
章节来源
- 启动失败：检查 FULLA_ENV 与 FULLA_ISSUER 是否匹配（生产模式需 HTTPS Issuer）。
- 数据库连接失败：确认 FULLA_DB_* 环境变量与 PostgreSQL 服务可达。
- Redis 连接失败：确认 FULLA_REDIS_* 环境变量与 Redis 服务可达。
- CORS 与重定向错误：核对 FULLA_CORS_ALLOW_ORIGINS 与 FULLA_VUE_REDIRECT_URI。
- 邮件发送失败：检查 SMTP 相关环境变量，未设置时走控制台模式。
- 权限不足：确认 RBAC 规则与角色分配，必要时重置管理员密码。
章节来源
- deploy/env/server.env.example:1-70
- deploy/env/docker.env.example:1-89
- apps/server/config/config.json:172-210
本附录提供了 Fulla 的配置、API、术语、依赖、部署与排障的完整参考。建议在生产环境中严格使用环境变量管理敏感信息，结合 Helm 与 Docker Compose 进行部署，并通过 Prometheus 与审计日志实现可观测性。
- 监听器：address、port、https
- 数据库客户端：name、rdbms、host、port、dbname、user、passwd、number_of_connections、timeout、auto_batch、connect_options
- Redis 客户端：name、host、port、username、passwd、db、number_of_connections、timeout
- 应用运行时：线程数、会话、静态资源、日志、压缩、连接数、请求体大小等
- 插件配置：OAuth2Plugin 的 storage_type、redis/postgres 客户端名、clients、admin_users、tokens TTL、清理间隔
- 自定义配置：RBAC 规则、CORS、前端 URL、外部认证（GitHub/Google/微信）
章节来源
- 运行模式与 Issuer：FULLA_ENV、FULLA_ISSUER
- JWT 签名密钥：FULLA_JWT_KEY_PATH、FULLA_SIGNING_KEY
- 数据库：FULLA_DB_HOST、FULLA_DB_PORT、FULLA_DB_NAME、FULLA_DB_USER、FULLA_DB_PASSWORD
- Redis：FULLA_REDIS_HOST、FULLA_REDIS_PORT、FULLA_REDIS_PASSWORD
- 服务器：FULLA_LISTEN_PORT
- 前端与 CORS：FULLA_FRONTEND_URL、FULLA_CORS_ALLOW_ORIGINS、FULLA_VUE_REDIRECT_URI、FULLA_GOOGLE_REDIRECT_URI
- 迁移与错误：FULLA_AUTO_MIGRATE、DETAILED_VALIDATION_ERRORS
- Vue 客户端密钥：FULLA_VUE_CLIENT_SECRET
- 邮件 SMTP：FULLA_SMTP_HOST、FULLA_SMTP_PORT、FULLA_SMTP_USER、FULLA_SMTP_PASSWORD、FULLA_SMTP_FROM_NAME、FULLA_SMTP_SSL
- 外部认证：FULLA_GITHUB_CLIENT_ID、FULLA_GITHUB_CLIENT_SECRET、FULLA_GOOGLE_CLIENT_ID、FULLA_GOOGLE_CLIENT_SECRET
章节来源
- 发现与 JWKS：/.well-known/openid-configuration、/.well-known/jwks.json
- 管理 API：/api/admin/*（客户端、角色、作用域、令牌、用户、日志、仪表盘）
- 用户自助：/api/user/*（个人资料、密码修改、会话管理）
- 辅助接口：/api/password-reset、/api/email/verify、/api/mfa、/api/wechat/login、/google/login
- 安全方案：Bearer Token、OAuth2 Client Credentials（Basic 或 POST body）
章节来源
- 应用错误码：NETWORK、DATABASE、VALIDATION、AUTHENTICATION、AUTHORIZATION、INTERNAL，映射 HTTP 状态码
- OAuth2 协议错误码：invalid_request、invalid_client、invalid_grant、unauthorized_client、unsupported_grant_type、invalid_scope、server_error、temporarily_unavailable、access_denied、unsupported_token_type、authorization_pending、slow_down、expired_token
- 响应格式：Error Envelope（category、code、details、message、request_id）；TokenResponse（access_token、token_type、expires_in、refresh_token）
章节来源
- docs/backend/api-reference.md:218-283
- libs/common/src/error/ErrorCatalog.cc:212-242
- apps/server/openapi.yaml:1-40
- OAuth2：开放授权标准，定义授权码、隐式、密码、客户端凭证、刷新令牌等授权类型
- OIDC：基于 OAuth2 的身份层，扩展 id_token、UserInfo、Discovery、JWKS 等
- Access Token：访问资源的短期凭证
- Refresh Token：换取新 Access Token 的长期凭证
- Scope：权限范围，限定令牌可访问的资源与操作
- Client ID/Secret：客户端标识与密钥，用于客户端认证
- JWK/JWKS：JSON Web Key/集合，用于公钥分发与令牌验证
- RBAC：基于角色的访问控制，通过角色与权限管理资源访问
- MFA：多因素认证，增强登录安全性
- Device Code：设备授权流程，适用于无浏览器输入的设备
- Backchannel Logout：服务端发起的登出通知机制
- 数据库迁移：migrations/V*.sql 按序执行，确保 schema 演进一致性
- 环境变量变更：新增或废弃变量需在示例文件中同步更新，并在 Helm values.yaml 中提供默认值
- 依赖升级：通过 Conan 锁定版本，升级前评估兼容性并回归测试
- 前端构建：VITE_* 变量在构建时内联，生产环境不应设置 VITE_API_BASE_URL
章节来源
- 核心依赖：Drogon、OpenSSL、jsoncpp、hiredis、libcurl、brotli、zlib、gtest
- 版本锁定：通过 conan.lock 与 conanfile.py 固定版本，确保跨平台一致性
- 许可证：各依赖遵循其自身许可证，项目应遵守上游许可条款并在发布说明中披露
章节来源
- 基准场景：Subject 生成与解析的高频调用，统计平均与 P95 延迟
- 目标指标：平均延迟 < 10ms，P95 延迟满足高并发需求
- 优化方向：连接池调优、缓存命中提升、压缩与静态资源缓存、监控告警
章节来源
fulla wiki
- 开发指南
- 快速开始
- 附录
-
API参考文档
- API参考文档
- API参考文档 - OAuth2_OIDC协议端点
- API参考文档 - 错误处理与状态码
- 用户自服务API
- 管理API
- 前端应用
- 安全设计
-
扩展开发
- 扩展开发
- 扩展开发 - SDK集成
- 存储扩展
- 插件开发
- 认证扩展
- 数据库设计
- 架构设计
-
核心库模块
- 核心库模块
- Drogon适配器 (fulla__drogon)
- OAuth2引擎 (fulla__oauth2)
- 存储适配器
- 身份认证模块 (fulla__identity)
- 通用库 (fulla__common)
- 测试策略
- 监控与可观测性
-
运维手册
- 运维手册
- 运维手册 - 生产环境配置
- 升级与迁移
- 故障排查指南
- 数据维护
- 日常运维操作
- 部署指南
- 项目概览