@reglow/reglow

ReglowAdmin 通用后台框架 - Node.js (Fastify + TypeScript) 版

基于 Fastify 构建的企业级后台管理系统框架，提供开箱即用的 RBAC 权限管理、通用业务模块及可观测性能力。

技术栈

• 运行时: Node.js >= 18
• 语言: TypeScript
• Web 框架: Fastify 4
• 数据库: Knex（支持 SQLite / MySQL）
• 缓存: Redis（可选，不支持时自动降级）
• 认证: JWT（jsonwebtoken）

快速开始

环境要求

• Node.js >= 18
• （可选）Redis Server
• （可选）MySQL Server

安装

npm install @reglow/reglow

配置

📦 数据库文件与建表 SQL 统一存放在 db/ 目录，初始化步骤见 db/README.md。

复制 .env.example 为 .env，按需修改：

cp .env.example .env

关键配置项：

| 变量 | 说明 | 默认值 | | --------------------------- | -------------------------------- | -------------------------- | | PORT | 服务端口 | 9520 | | DB_DRIVER | 数据库驱动 (sqlite / mysql) | sqlite | | DB_SQLITE_PATH | SQLite 数据库文件路径 | ./db/reglow_admin.db | | REDIS_URL | Redis 连接地址 | redis://localhost:6379/0 | | JWT_SECRET | JWT 签名密钥 | change-me-in-production | | JWT_ACCESS_EXPIRE_MINUTES | Access Token 过期时间（分钟） | 120 | | CORS_ORIGINS | 允许的跨域源（逗号分隔） | http://localhost:5173 | | STORAGE_BACKEND | 存储后端 (local / s3) | local | | LOG_LEVEL | 日志级别 | INFO | | TENANT_GUARD | 多租户错配自检 (enforce/off) | enforce |

启动

# 开发模式（热重载）
npm run dev

# 编译
npm run build

# 生产模式
npm start

启动后访问（默认端口 9520）：

| 服务 | 地址 | | ------------- | ---------------------------------------- | | Swagger UI | http://localhost:9520/docs | | Scalar 调试台 | http://localhost:9520/scalar | | OpenAPI JSON | http://localhost:9520/documentation/json | | 管理端 API | http://localhost:9520/admin/api/v1 | | 用户端 API | http://localhost:9520/api/v1 | | 健康检查 | http://localhost:9520/health | | 指标监控 | http://localhost:9520/metrics |

文档页（docs / scalar）按部署环境自动开关：开发（APP_ENV 未设置或 dev）默认开，生产（APP_ENV=production）默认关； 显式设置 DEBUG 永远优先；scalar 的 OpenAPI 也可经 http://localhost:9520/scalar/openapi.json 获取。

目录结构

reglow/
├── common/                # 公共模块
│   ├── utils/             # 工具函数（日期、字符串、User-Agent 解析）
│   ├── errors.ts          # 统一异常码体系
│   ├── exception_handler.ts  # 全局异常处理
│   ├── i18n.ts            # 国际化
│   ├── middleware.ts      # 中间件（CORS / Trace ID / 安全头 / 操作日志）
│   ├── response.ts        # 统一响应格式 (ApiResponse / PageData)
│   └── serialize.ts       # 序列化工具
├── core/                  # 核心能力
│   ├── auth.ts            # JWT 认证 & 权限校验
│   ├── cache.ts           # 缓存抽象
│   ├── config.ts          # 配置管理（.env 读取）
│   ├── data_scope.ts      # 数据权限范围
│   ├── database.ts        # 数据库连接（Knex）
│   ├── email.ts           # 邮件发送
│   ├── entities.ts        # 实体类型定义
│   ├── fastify.ts         # Fastify 模块增强
│   ├── logging.ts         # 日志系统
│   ├── models.ts          # 表名 & 模型注册
│   ├── observability.ts   # 可观测性（健康检查 / Prometheus 指标）
│   ├── payment.ts         # 支付能力
│   ├── plugin.ts          # 路由自动发现
│   ├── rate_limit.ts      # 接口限流
│   ├── redis.ts           # Redis 连接
│   ├── redis_keys.ts      # Redis Key 命名规范
│   ├── security.ts        # 安全相关（密码加密等）
│   ├── session.ts         # 会话管理
│   ├── sms.ts             # 短信发送
│   └── storage.ts         # 文件存储（本地 / S3）
├── modules/               # 业务模块
│   ├── agreement/         # 用户协议
│   ├── ai/                # AI 能力
│   ├── article/           # 文章管理
│   ├── auth/              # 登录认证
│   ├── config/            # 系统配置
│   ├── customer_service/  # 智能客服（含 WebSocket）
│   ├── dept/              # 部门管理
│   ├── dict/              # 数据字典
│   ├── employee/          # 员工管理（后台用户）
│   ├── log/               # 操作日志 & 登录日志
│   ├── material/          # 素材管理
│   ├── menu/              # 菜单管理
│   ├── message/           # 消息通知
│   ├── notice/            # 系统公告
│   ├── payment/           # 支付订单
│   ├── photo/             # 相册 & 照片
│   ├── post/              # 岗位管理
│   ├── role/              # 角色管理
│   ├── user/              # 用户管理（前端用户）
│   └── video/             # 视频管理
└── scripts/               # 脚本工具
    ├── init-data.ts       # 种子数据初始化
    ├── schema.ts          # 数据库建表
    ├── remove-business-menu.ts    # 移除业务菜单
    └── sync-menu-mysql-to-sqlite.ts  # 菜单同步

API 路由

管理端 API（/admin/api/v1）

| 模块 | 前缀 | 说明 | | ---- | ------------------- | ---------------------- | | 认证 | /auth | 登录、登出、刷新 Token | | 员工 | /employee | 后台用户 CRUD | | 角色 | /role | 角色管理 & 权限分配 | | 菜单 | /menu | 菜单树管理 | | 部门 | /dept | 组织架构 | | 岗位 | /post | 岗位管理 | | 字典 | /dict | 数据字典管理 | | 配置 | /config | 系统参数配置 | | 日志 | /log | 操作日志 & 登录日志 | | 通知 | /notice | 公告管理 | | 消息 | /message | 消息模板 & 消息推送 | | 素材 | /material | 文件上传 & 素材库 | | 相册 | /photo | 相册 & 照片管理 | | 视频 | /video | 视频管理 | | 文章 | /article | 文章 & 分类管理 | | 协议 | /agreement | 用户协议管理 | | 客服 | /customer-service | 智能客服配置 | | AI | /ai | AI 能力接口 | | 支付 | /payment | 支付订单管理 |

用户端 API（/api/v1）

| 模块 | 前缀 | 说明 | | ---- | -------- | ------------------------ | | 用户 | /user | 用户注册、登录、个人信息 | | 相册 | /photo | 公开相册浏览 |

核心特性

统一响应格式

所有 API 返回统一格式：

{
  "code": 0,
  "success": true,
  "msg": "操作成功",
  "data": {}
}

分页数据：

{
  "code": 0,
  "success": true,
  "msg": "操作成功",
  "data": {
    "items": [],
    "total": 100,
    "page": 1,
    "size": 10
  }
}

分页排序（sort_by / sort_order）

所有管理端分页列表接口统一支持服务端多列排序，通过以下两个可选查询参数控制：

| 参数 | 类型 | 默认值 | 取值约束 | | ------------ | ------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | sort_by | string | 无 | 排序字段列表，逗号分隔，最多 3 项（超出 3 项的尾部直接忽略）。每项为 field 或 field:dir（dir = asc | desc，大小写不敏感，:dir 可省略）。字段取该列表项 item DTO 的 snake_case 字段名（即数据库列名风格），精确匹配、大小写敏感；仅接受该表自有列（不含关联/join 列），且排除敏感列 | | sort_order | string | asc | asc | desc，大小写不敏感；作为未显式带 :dir 的项的默认方向 |

生效规则：

• 逐项校验：每一项字段都必须命中该表的可排序列白名单（实体自有列、且排除敏感列）；非法 / 敏感 / 未知字段只跳过该项，其余合法项照常生效，不报错、不返回 400/500；
• 一个合法项都没有（sort_by 缺省 / 空串 / 全部非法或敏感）→ 完全忽略排序参数，接口保持原有默认排序，SQL 与响应与不带该参数时完全一致，不报错、不返回 400；
• 排序生效时：按合法项的书写顺序依次作为主 → 次 → 末排序，末尾再追加该接口原有默认排序链兜底，保证分页稳定、结果确定；
• 旧单列写法 ?sort_by=created_at&sort_order=desc 继续有效（等价于单列，行为、SQL、响应与之前完全一致）；
• 可排序列白名单在各自模块的 repository 中显式声明（如 USER_SORTABLE_COLUMNS），用户输入的每一项都先经白名单解析为真实列名常量再交给 knex，永不直接拼入 ORDER BY。

敏感列（即使存在也禁止排序）：password、password_hash、salt、token、refresh_token、access_token、secret、app_secret、api_key、private_key。

示例：

# 多列：昵称升序为主、创建时间降序为次，末尾追加接口原有默认排序（id desc）兜底
GET /admin/api/v1/users/?page=1&size=20&sort_by=nickname:asc,created_at:desc

# 混合省略方向：两项均未带 :dir，统一使用 sort_order（此处 asc）
GET /admin/api/v1/users/?page=1&size=20&sort_by=nickname,created_at&sort_order=asc

# 旧单列写法：行为、SQL、响应与不带 :dir 的单列完全一致
GET /admin/api/v1/users/?sort_by=created_at&sort_order=desc

# 含敏感列：仅跳过 password_hash，仍按 nickname 降序
GET /admin/api/v1/users/?sort_by=password_hash,nickname:desc

# 方向大小写不敏感
GET /admin/api/v1/dict-types/?page=1&size=10&sort_by=name:DESC

# 超过 3 项：只取前 3 项，尾部忽略
GET /admin/api/v1/users/?sort_by=status:asc,nickname:desc,created_at:asc,id:asc

# 全部非法：忽略排序，回落接口原有默认排序，不报错
GET /admin/api/v1/users/?sort_by=password_hash,not_a_column

异常码体系

按模块分段的统一异常码，覆盖 1000-9999 范围，详见 reglow/common/errors.ts。

认证 & 权限

• JWT 双 Token 机制（Access Token + Refresh Token）
• 装饰器模式：requireAuth / requirePermission / requireClientAuth
• RBAC 角色权限控制
• 数据权限范围（全部 / 本部门 / 本人 等）

数据库

• 默认使用 SQLite，零配置即可启动
• 支持切换到 MySQL
• 通过 Knex 统一查询接口
• 启动时自动建表 & 初始化种子数据

可观测性

• 健康检查端点：GET /health
• Prometheus 指标端点：GET /metrics
• 结构化日志（支持 JSON 格式）

文件存储

• 本地存储（默认）
• S3 兼容存储（MinIO / AWS S3 / 阿里云 OSS 等）
• 支持 CDN 域名配置

作为库使用

import {
  knex,
  getDb,
  settings,
  logger,
  getRedisStore,
  AppException,
  ErrorCode,
  ApiResponse,
  PageData,
  TableNames,
  ModelRegistry,
  discoverRouters,
  discoverClientRouters,
  autoInitDatabase,
  createTables,
} from "@reglow/reglow";

开发

# 安装依赖
npm install

# 开发模式
npm run dev

# 类型检查
npm run type-check

# 单元/契约测试（排序契约）
npm test

# 编译
npm run build

说明：npm test 使用临时 SQLite 数据库运行排序契约测试（tests/sort.test.ts）。 由于 better-sqlite3 为原生模块，请使用与其编译时的 ABI 相匹配的 Node 版本 （本仓库预编译版本对应 Node 20；若 Node 版本不一致，可执行 npm rebuild better-sqlite3）。

License

UNLICENSED