架构总览
系统架构
CoreFlow 采用分层架构设计,从底层基础设施到顶层业务应用,每一层职责清晰:
┌─────────────────────────────────────────────────────────────┐
│ 客户端(不在本仓) │
│ Web 前端 / 小程序 / 桌面端 / 第三方 —— 任意栈,只见线协议 │
└─────────────────────────┬───────────────────────────────────┘
│ HTTP / WebSocket(Cookie 会话 + 签名头)
▼
┌─────────────────────────────────────────────────────────────┐
│ 请求处理管道 │
│ Cookie → Auth → RateLimit → Firewall → Guard → Handler │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 应用层 │
│ oauth21 (授权) │ user (用户) │ admin (管理) │ firewall │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 框架层 src/framework/ │
│ config │ persistence │ security │ ingress │ lifecycle │ support │
└─────────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 存储层 │
│ MySQL 8.0 │ Redis 7 │
└─────────────────────────────────────────────────────────────┘请求处理链路
一个 HTTP 请求的完整处理流程:
onRequest[0] → @fastify/cookie 解析 cookies
onRequest[1] → monitor 请求耗时 / 慢请求告警(01-monitor,先于 auth 注册)
onRequest[2] → auth Session 验证(sid cookie → Redis → request.state.user)
onRequest[3] → firewall 五层拦截管道 + 限流插件(@fastify/rate-limit 由它在内部注册)
preHandler → guard 三级权限守卫
preHandler → verifySignature H5 签名验证(仅 OAuth21 路由)
handler → 业务路由
onSend → 日志 + 连接释放
onResponse → 扫描陷阱(404/403 检测)模块加载机制
引擎扫描 src/framework/lifecycle/loader/registry/ 目录,按文件名数字前缀顺序加载:
00-globals.js → 装饰 reply.result
01-monitor.js → 请求监控 + 慢请求告警
02-redis.js → Redis 连接 + 健康监控(连不上则 app.redis = null)
03-db.js → Sequelize 连接(已配置但连不上 → 启动失败)
04-auth.js → 认证插件
05-firewall.js → 防火墙
06-models.js → 自动加载模型
07-keys.js → JWT 密钥加载 + 启动自检(KEK / 当前密钥)
08-api.js → 自动加载路由
09-notice.js → SMTP 配置种子数据
10-apps.js → 应用配置 + 权限 + 角色 + OAuth 客户端失败语义:只有 01-monitor / 02-redis / 09-notice 在 OPTIONAL_LOADERS 名单里 (src/framework/lifecycle/loader/engine.js),失败只降级一项附加能力;其余加载器失败即 fail-fast —— 缺认证 / 防火墙 / 模型 / 路由 / 应用的进程能监听端口却处理不了正确请求, "启动成功"是最糟的失败形态。03-db 的判据是"已配置但连不上才失败", 未配置 DB 仍允许本地与测试无库启动。
Redis 的降级边界(容易被写错,实测口径):
- 未配置(
REDIS_ENABLED非true或无REDIS_HOST)→getStore()直接返回进程内MapStore。 - 已配置但启动连不上 →
app.redis = null,此后访问层仍然选 Redis 实现, 操作抛RedisRequiredError(statusCode = 503),不会自动回退内存。 - 运行期不是"降级"而是"503":
redis-store.js明确不复用内存兜底,避免多实例下 计数/限流/会话各算一套而静默失控。需要容灾的短时效数据用getStore(prefix, { backup: true })接备用 Redis,两个都不通仍是 503。
每个 Loader 导出默认函数接收 app 实例。失败按 OPTIONAL_LOADERS 分级: 01-monitor / 02-redis / 09-notice 失败只记警告并计入 getLoaderStatus(); 其余(鉴权 / 防火墙 / 模型 / 密钥 / 路由 / 应用)fail-fast 终止启动 —— 能监听端口却处理不了正确请求的进程比直接退出更难排查。
模型命名空间
模型按领域子目录自动注册为 app.db.<namespace>.<ModelName>:
| 命名空间 | 模型 | 表名 |
|---|---|---|
db.user | User, UserIdentity | user_user, user_identity |
db.iam | Role, UserRole, InlinePolicy, Permission | iam_role, iam_user_role, iam_inline_policy, permissions |
db.oauth21 | OauthClient, OauthCode, OauthToken, OauthApproval, OauthConsent | oauth_clients, oauth_codes, oauth_tokens, oauth_user_approval, oauth_consents |
db.notice | EmailCode, NoticeConfig | notice_email_codes, notice_configs |
db.session | UserSession, SessionToken, SessionLog, AuditLog | session_user_session, session_tokens, session_logs, audit_logs |
目录约定
| 目录 | 职责 | 是否必须 |
|---|---|---|
src/app/{name}/config.js | 应用配置 | ✅ |
src/app/{name}/permission/ | 权限定义 | 可选 |
src/api/{name}/system.json | 路由域配置 | ✅ |
src/api/{name}/v1/*.js | 路由文件 | ✅ |
src/models/{name}/ | 数据模型 | 可选 |