chanjs 2.7.7 → 2.7.10

package/doc/05-/345/267/245/345/205/267/344/270/216/346/240/241/351/252/214.md

@@ -0,0 +1,309 @@
+# 05 · 工具与校验：logger / createLogger / Paths / 文件安全 / validate / utils 工具集
+
+日常开发最常用的小工具。导出方式分两类：
+- **根包直接导出**：`logger`（默认导出）、`createLogger`、`Paths`、`validate`、`validateAll`。
+- **`utils` 命名空间导出**：`import { getIp, request, tree, ... } from "chanjs/utils/index.js"`，
+  或集中用 `import { utils } from "chanjs"` 后 `utils.getIp(...)`。
+
+---
+
+## 一、日志 `logger` / `createLogger`
+
+文件：`utils/logger.js`。统一日志，**dev 彩色控制台、prd JSON 单行**（方便日志采集）。
+
+### 1.1 默认实例 `logger`
+
+```js
+import logger from "chanjs";   // 注意是默认导出
+
+logger.info("服务启动");
+logger.warn("缓存未命中");
+logger.error("数据库连接失败", err);   // 第二个参数传 Error 会自动解析堆栈
+logger.debug("调试信息", { userId: 1 });
+```
+
+| 方法 | 级别 | 说明 |
+|---|---|---|
+| `trace` | 0 | 最细 |
+| `debug` | 1 | 调试（dev 默认开启）|
+| `info` | 2 | 常规信息（prd 默认开启）|
+| `warn` | 3 | 警告 |
+| `error` | 4 | 错误（自动走 stderr）|
+| `fatal` | 5 | 致命 |
+
+**级别控制**：环境变量 `LOG_LEVEL`（dev 默认 `debug`，prd 默认 `info`）。低于该级别的日志不输出。
+**输出目标**：基于 pino，dev 走 pino-pretty 彩色控制台；prd 输出纯 JSON 到 stdout，由 pm2 统一捕获落盘（框架不直接写日志文件）。
+
+### 1.2 自定义标签实例 `createLogger(name)`
+
+框架内部统一用默认 `logger`（标签 `Chan`）。**业务代码建议用 `createLogger` 自建带标签实例**，方便区分来源：
+
+```js
+import { createLogger } from "chanjs";
+
+const log = createLogger("Member");   // 标签 Member
+log.info("用户登录", { userId: 1 });
+// 输出（pino-pretty 彩色）：[2026-08-01 12:00:00.123 INFO]: 用户登录 {"userId":1}
+```
+
+> 📌 约定：框架内部统一 `import logger`，业务侧用 `createLogger("模块名")` 区分来源。dev 环境下 `module` 字段已被 pino-pretty 隐藏以精简输出（prod 仍保留便于聚合）。
+
+### 1.3 传 Error 自动解析
+
+```js
+try { /* ... */ }
+catch (err) {
+  logger.error("操作失败", err);   // 自动输出 message + 堆栈文件:行号
+}
+```
+
+---
+
+## 二、路径 `Paths`
+
+```js
+import { Paths } from "chanjs";
+
+Paths.rootPath;     // 项目根目录（process.cwd()）
+Paths.appPath;      // app
+Paths.configPath;   // config
+Paths.publicPath;   // public
+Paths.modulesPath;  // app/modules
+Paths.commonPath;   // app/common
+Paths.helperPath;   // app/helper
+Paths.extendPath;   // app/extend
+```
+
+> 框架在 `Chan` 构造时已注入 `this.paths = Paths`，业务里通过 `this.app.paths` 访问，避免到处拼相对路径。
+> 各路径均为 getter 动态计算（基于 `rootPath`），改 `rootPath` 会同步生效。
+
+---
+
+## 三、文件安全 `safePath`（防路径穿越）
+
+文件：`utils/file.js`。**仅通过子模块深导入使用**：`import { safePath } from "chanjs/utils/file.js"`。
+（它未挂在 `utils` 命名空间里，需直接指向子模块文件。）
+
+```js
+import { safePath } from "chanjs/utils/file.js";
+
+const safe = safePath(userInputPath);   // 防御目录穿越(../)，合法返回绝对路径，非法返回 null
+```
+
+| 方法 | 说明 |
+|---|---|
+| `safePath(input)` | 以项目根目录为基准规范化路径，阻断 `../` 穿越；合法返回绝对路径，非法（越界/绝对路径）返回 `null` |
+
+> 文件上传/在线编辑（如 ChanCMS 的 `vip` 模块）任何由用户输入拼出来的文件路径，都必须过 `safePath`，
+> 否则用户可读取 `/etc/passwd` 等任意文件。**复用框架提供的安全函数，不要自己拼路径。**
+
+---
+
+## 四、参数校验 `validate` / `validateAll`（基于 zod）
+
+文件：`middleware/validate.js`。用 **zod** 做声明式校验，校验通过的参数统一挂到 `req.validated`。
+（校验失败自动抛 `ValidationError`，由全局错误处理器返回，你**不用手写 if 判断**。）
+
+### 4.1 `validate(schema, source="body")` —— 校验单一来源
+
+```js
+import { validate } from "chanjs";
+import { z } from "zod";
+
+const createRule = z.object({
+  title: z.string().min(1, "标题必填"),
+  content: z.string().min(5, "内容至少5字"),
+  status: z.number().int().optional(),
+});
+
+router.post("/article/create", validate(createRule), ctrl.create.bind(ctrl));
+```
+
+在 Controller 里取校验后的值：
+
+```js
+async create(req, res) {
+  const data = req.validated;   // 已通过校验、且被类型转换过的数据
+}
+```
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `schema` | zod schema | 校验规则 |
+| `source` | `"body"\|"query"\|"params"` | 校验来源，默认 `body` |
+
+> ⚠️ Express 5 的 `req.query` 是只读 getter，框架内部用 `defineProperty` 处理过，
+> 统一用 `req.validated` 最稳（不要用 `req.query` 读校验后的值）。
+
+### 4.2 `validateAll(schemas)` —— 多来源一起校验
+
+```js
+const listRule = {
+  query: z.object({ current: z.coerce.number().int().min(1).default(1),
+                    pageSize: z.coerce.number().int().max(100).default(10) }),
+  params: z.object({ cateId: z.coerce.number() }),
+};
+
+router.get("/cate/:cateId", validateAll(listRule), ctrl.list.bind(ctrl));
+
+// Controller 里：
+async list(req, res) {
+  const { query, params } = req.validated;   // { query:{current,pageSize}, params:{cateId} }
+}
+```
+
+> `validateAll` 会把 `body/query/params` 各自校验后聚合成 `req.validated = { body, query, params }`，
+> **不会用单一来源覆盖其他来源**（旧版有此 bug，已修复）。
+
+### 4.3 常用 zod 写法速查
+
+```js
+import { z } from "zod";
+
+z.string().min(1)                // 非空字符串
+z.string().email()               // 邮箱
+z.number().int().positive()      // 正整数
+z.coerce.number()                // 把字符串"5"转成数字 5（表单常用）
+z.boolean().optional()           // 可选布尔
+z.array(z.string())              // 字符串数组
+z.object({ a: z.string() })      // 嵌套对象
+z.enum(["on","off"])             // 枚举
+```
+
+---
+
+## 五、`utils` 工具集（全部方法）
+
+以下全部可从 `chanjs/utils/index.js` 具名导入，或经 `import { utils } from "chanjs"` 后通过 `utils.xxx` 调用（除 `safePath` 见第三节）。
+
+### 5.1 IP 与网络
+
+| 函数 | 签名 | 返回 | 说明 |
+|---|---|---|---|
+| `getIp` | `getIp(req)` | string | 取客户端真实 IP（Express 专用）。优先 `cf-connecting-ip`（需 `CF_ENABLED=true` 且带 `cf-ray`），其次 `req.ip`（已融合代理链），兜底 `0.0.0.0`。自动处理 IPv6 映射/IPv6 回环 |
+| `request` | `request(url, options?)` | Promise<{success,data,error?}> | 带超时/重试/SSRF 防护/大小限制的 HTTP 请求封装。`options`: `timeout`(默认 10000)、`retry`(默认 0)、`parseJson`(默认 true)、`responseType:"arraybuffer"`、`maxResponseBytes`(默认 10MB)。拦截私网/回环地址（防 SSRF）|
+
+```js
+import { utils } from "chanjs";
+
+const ip = utils.getIp(req);
+const { success, data, error } = await utils.request("https://api.example.com/x", { timeout: 8000, retry: 2 });
+```
+
+### 5.2 时间格式化
+
+| 函数 | 签名 | 返回 | 说明 |
+|---|---|---|---|
+| `formatTime` | `formatTime(timestamp, format="YYYY-MM-DD HH:mm:ss")` | string | 时间戳/日期串/Date 格式化为字符串。非法时间原样返回 |
+| `formatDateFields` | `formatDateFields(data, fields)` | 原类型 | 批量格式化对象/数组里指定日期字段（`fields` 数组）。非日期字段值不改动 |
+
+```js
+import { formatTime, formatDateFields } from "chanjs/utils/index.js";
+
+formatTime(Date.now());                       // "2026-08-13 17:30:00"
+formatDateFields(row, ["created_at","updated_at"]);
+```
+
+### 5.3 树形结构
+
+| 函数 | 签名 | 返回 | 说明 |
+|---|---|---|---|
+| `tree` | `tree(list, rootPid=0, {maxDepth=20,idKey="id",pidKey="pid"})` | Array | 扁平数组转树（预建 Map 优化）；节点自带 `children`/`level`，无孩子则删 `children`。含循环引用/深度保护 |
+| `treeById` | `treeById(targetId, list, {maxDepth=20,idKey="id",pidKey="pid"})` | Array | 按节点 ID 向上追溯完整父级路径 `[根...父...目标]` |
+
+```js
+const treeData = tree(categoryList, 0, { idKey: "id", pidKey: "pid" });
+const path = treeById(25, categoryList);   // [根分类, ..., 目标分类]
+```
+
+### 5.4 数据解析
+
+| 函数 | 签名 | 返回 | 说明 |
+|---|---|---|---|
+| `arrToObj` | `arrToObj(arr, keyField="config_key", valueField="config_value")` | object | 对象数组转键值映射（如配置列表）。入参非数组返回 `{}` |
+| `getChildrenId` | `getChildrenId(py, source)` | `{ cate, id }` | 按拼音/ID 在分类数组中匹配，返回 `{ cate, id }`（找不到 `id` 为 `""`）|
+| `filterFields` | `filterFields(data, fields)` | Array | 从对象数组筛选指定字段，返回全新数组（不改动原数据）。`data` 非数组返回 `[]` |
+
+```js
+const map = arrToObj(configList);                 // { site_name: "xxx", ... }
+const picked = filterFields(rows, ["id","title"]); // 只保留两列
+```
+
+### 5.5 HTML 处理
+
+| 函数 | 签名 | 返回 | 说明 |
+|---|---|---|---|
+| `htmlEncode` | `htmlEncode(str)` | string | 标准 HTML 实体编码（`& < > " '`），适配 art-template `{{ }}` |
+| `htmlDecode` | `htmlDecode(str)` | string | HTML 实体解码（命名/十进制/十六进制）|
+| `escapeScript` | `escapeScript(str)` | string | 危险标签（script/iframe/object/embed/form）二次转义，适配 art-template `{{@ }}` 防 XSS |
+| `filterImgFromStr` | `filterImgFromStr(str)` | string[] | 从 HTML 源码批量提取全部 `img` 的 `src` 列表 |
+
+```js
+import { htmlEncode, escapeScript, filterImgFromStr } from "chanjs/utils/index.js";
+
+const safe = htmlEncode(userInput);
+const imgs = filterImgFromStr(articleHtml);   // ["/uploads/a.jpg", ...]
+```
+
+### 5.6 文件操作（`chanjs/utils/file.js`）
+
+除 `safePath`（第三节）外，文件工具均通过子模块导入：
+
+| 函数 | 签名 | 返回 | 说明 |
+|---|---|---|---|
+| `delImg` | `delImg(filePath)` | boolean | 删除相对根目录的文件（经 `safePath` 防穿越）；不存在返回 `false` |
+| `readFileContent` | `readFileContent(filePath)` | string | 读文本文件内容（utf8）；非法路径/不存在/非文件抛异常 |
+| `saveFileContent` | `saveFileContent(filePath, content)` | void | 写/覆写文件，目录自动递归创建；非法路径抛异常 |
+| `getFolders` | `getFolders(folderPath)` | string[] | 取目录下一级文件夹名（过滤隐藏目录）|
+| `getHtmlFilesSync` | `getHtmlFilesSync(folderPath)` | string[] | 同步取目录下一级全部 `.html` 文件名 |
+
+```js
+import { delImg, readFileContent, saveFileContent, getFolders, getHtmlFilesSync } from "chanjs/utils/file.js";
+
+const htmls = getHtmlFilesSync("public/themes/default");
+saveFileContent("public/x.txt", "hello");   // 自动建目录
+```
+
+### 5.7 分页 HTML `pages`
+
+| 函数 | 签名 | 返回 | 说明 |
+|---|---|---|---|
+| `pages` | `pages(current, total, pageSize, href, query="")` | string | 生成 Tailwind 风格分页 `<li>` 片段（不含外层 `<ul>`）。`totalPage<=1` 返回空串 |
+
+```js
+import { pages } from "chanjs/utils/index.js";
+
+const html = `<ul>${pages(page, total, 10, "/news/", "")}</ul>`;
+// 链接形如 /news/1.html /news/2.html ...
+```
+
+---
+
+## 六、工具模块速查
+
+| 导出 | 类型 | 一句话用途 |
+|---|---|---|
+| `logger`(默认) | 实例 | 框架级日志（标签 Chan）|
+| `createLogger(name)` | 函数 | 业务自建带标签日志 |
+| `Paths` | 对象 | 项目目录常量（root/app/config/public/modules/common/helper/extend）|
+| `safePath` | 函数 | 防路径穿越（深导入 `utils/file.js`）|
+| `validate` | 函数 | 单来源 zod 校验中间件 |
+| `validateAll` | 函数 | 多来源 zod 校验中间件 |
+| `getIp` / `request` | 函数 | 取真实 IP / 防 SSRF 的 HTTP 请求 |
+| `formatTime` / `formatDateFields` | 函数 | 时间格式化 |
+| `tree` / `treeById` | 函数 | 扁平数组转树 / 向上追溯路径 |
+| `arrToObj` / `getChildrenId` / `filterFields` | 函数 | 数据解析 |
+| `htmlEncode` / `htmlDecode` / `escapeScript` / `filterImgFromStr` | 函数 | HTML 编解码/取图 |
+| `delImg` / `readFileContent` / `saveFileContent` / `getFolders` / `getHtmlFilesSync` | 函数 | 文件操作（深导入 `utils/file.js`）|
+| `pages` | 函数 | 分页 HTML 片段 |
+
+---
+
+## 七、常见坑
+
+1. **`logger` 是默认导出**：`import logger from "chanjs"`（无花括号）；`createLogger` 才是具名导出。
+2. **忘了 `await store` 但 `cache` 同步**：`store` 异步要 `await`，`cache` 同步不要 `await`。
+3. **校验后读 `req.body` 而非 `req.validated`**：Express 5 下 `req.query` 只读，框架已用 `req.validated` 统一承载，优先用它。
+4. **zod 数字不 coerce**：表单传来的是字符串，`z.number()` 会失败，记得 `z.coerce.number()`。
+5. **`safePath` 不是根导出也不是 utils 成员**：必须用 `import { safePath } from "chanjs/utils/file.js"` 深导入；任何由用户输入拼出来的文件路径都得过它。
+6. **`utils` 里没有 `pathGuard`**：那是旧文档臆造的，本框架没有该中间件，路径安全请用 `safePath`。

package/doc/06-/345/272/224/347/224/250/347/224/237/345/221/275/345/221/250/346/234/237.md

@@ -0,0 +1,207 @@
+# 06 · 应用生命周期与启动：Chan 类 / beforeStart / loader / registry / dbManager
+
+想理解"程序从启动到监听端口"全过程，或要写启动钩子、访问全局实例，看这篇。
+
+---
+
+## 一、`Chan` 应用核心类
+
+文件：`core/App.js`。整个应用的入口对象。你的 `app.js` 大致长这样：
+
+```js
+import Chan from "chanjs";          // 默认导出是 Chan 类
+
+const app = new Chan();
+
+app.beforeStart(async () => {        // 启动前钩子
+  console.log("准备就绪");
+});
+
+app.start()   // 异步：自动加载 配置/DB/路由/中间件/错误处理器
+  .then(() => app.run(port => console.log("监听", port)))
+  .catch(err => { console.error(err); process.exit(1); });
+```
+
+### 1.1 构造与实例属性
+
+```js
+const app = new Chan();
+app.app;        // express 实例
+app.router;     // 顶层 express.Router()
+app.dbManager;  // 数据库管理器（多连接，见 1.4）
+app.db;         // 默认数据库连接（knex 实例），#loadDb 成功后赋值
+app.config;     // 配置对象（#loadConfig 后）
+app.paths;      // Paths 实例
+app.hooks;      // 启动钩子数组
+app.server;     // http.Server 实例（run 后）
+app.event;      // 事件总线单例（EventBus，详见 07）
+app.task;       // 定时任务管理器（Task，详见 08）
+app.lang;       // i18n 实例（i18next，详见 09）
+```
+
+### 1.2 关键方法
+
+| 方法 | 签名 | 说明 |
+|---|---|---|
+| `start()` | `async start()` | 完整启动流程（见 1.3）|
+| `run(cb?)` | `run((port)=>void)` | 启动 HTTP 监听，默认端口 `config.PORT \|\| 3000`；监听成功后调用 `cb(port)` |
+| `beforeStart(fn)` | `beforeStart(fn)` | 注册启动前钩子（fn 必须是函数，否则抛 `AppError("PARAM_INVALID")`）|
+| `shutdown()` | `async shutdown()` | 优雅停机：关闭 server → `task.stopAll()` → `store.close()` → `dbManager.closeAll()` → `event.destroy()` → `setApp(null)` |
+
+> ⚠️ `beforeStart(fn)` 的参数**必须是函数**：框架会 `if (typeof fn !== "function") throw new AppError("PARAM_INVALID", "...", 400)`。
+> 写 `app.beforeStart(myInit())`（带括号）会传入"函数执行结果"而非函数本身，触发报错。正确：`app.beforeStart(myInit)`。
+
+### 1.3 `start()` 内部顺序（理解即可）
+
+```mermaid
+graph TD
+  A["start()"] --> B["loadConfig 加载配置"]
+  B --> C["initLang i18n 初始化"]
+  C --> D["initStore 初始化存储 Redis/内存"]
+  D --> E["loadDb 连接数据库 + ping 校验"]
+  E --> F["setApp(this) 注册全局实例"]
+  F --> G["registerCoreMiddleware 核心中间件"]
+  G --> H["setupApp trust proxy 配置"]
+  H --> I["loadModuleRouter + loadCommonRouter 加载路由"]
+  I --> J["mountRouter 挂载顶层 router"]
+  J --> K["registerErrorHandler 全局错误处理器"]
+  K --> L["runHooks 执行 beforeStart 钩子"]
+  L --> M["run() 监听端口"]
+```
+
+> 关键顺序：**先 `setApp` 注册全局实例**，之后业务组件的 `this.app` 才能拿到值。
+> 数据库采用**宽松策略**：连接失败时仅**打印 error 日志并继续启动**（不会中断进程、也不会自动重连），
+> 这样开发期能先起服务。但 `this.db` 可能为 `null`，业务里访问前请用 `if (!this.db)` 兜底或确保配置正确。
+
+---
+
+## 二、`beforeStart` 启动钩子
+
+适合放：建表检测、初始化管理员、预热缓存、外部服务探活等"启动时必须完成"的逻辑。
+
+```js
+app.beforeStart(async () => {
+  // 例：确保默认管理员存在
+  const exist = await adminRepo.exists({ username: "admin" });
+  if (!exist.data.exists) {
+    await adminRepo.insert({ username: "admin", role: "super" });
+  }
+});
+```
+
+- 多个 `beforeStart` 按注册顺序串行执行。
+- 抛错会中断启动（进程退出），所以钩子里要做必要容错。
+
+---
+
+## 三、`loader` —— 配置与组件加载
+
+文件：`core/loader.js`。框架在 `start()` 内部调用，业务一般不直接用，但了解有帮助：
+
+```js
+import { loader } from "chanjs";
+
+const config = await loader.loadConfig();   // 读取 config/index.js 合并成配置对象
+```
+
+`loader` 命名空间提供：
+
+| 方法 | 说明 |
+|---|---|
+| `loadController(name)` | 加载某模块全部 Controller（自动 bind 实例方法防 this 丢失），返回 `{ 控制器名: 实例 }` |
+| `loadConfig()` | 加载合并配置（读 `config/index.js`）|
+| `importFile(filepath)` | 动态导入单个文件（成功返回模块 default 或模块本身，失败/IO 异常返回 `null`）|
+| `loaderSort(modules)` | 模块排序（`web` 强制后置）|
+
+> 多数业务场景你直接 `new MyService()` / `new MyController()` 即可，不必走 loader。
+> loader 主要在框架自动装配或插件化场景使用。
+
+---
+
+## 四、`registry` —— 全局实例注册表
+
+文件：`core/registry.js`。从"多实例注册表"简化为**单例**（模块级 `_current`）。
+
+```js
+import { setApp, getApp } from "chanjs";
+
+setApp(appInstance);     // start() 内部已调用
+const app = getApp();    // 任意地方拿到全局 Chan 实例
+```
+
+`BaseComponent` 的 `this.app` 本质上就是 `getApp()`。所以你在 Service/Repository/Controller 里
+`this.app.db`、`this.app.config` 能直接用，是因为 `start()` 阶段已经 `setApp(this)`。
+
+> 注意：当前为单例实现，不要期望同时持有多个 App 实例。
+
+---
+
+## 五、`dbManager` —— 多数据库连接管理器
+
+文件：`core/Database.js`。`app.dbManager` 是 `DatabaseManager` 实例，统一管理多 Knex 连接、心跳、慢查询监控。
+
+| 方法 | 签名 | 返回 | 说明 |
+|---|---|---|---|
+| `add` | `add(name, config, { isDefault=false })` | Knex | 注册一个连接；首个或非默认但 `isDefault=true` 自动设为默认库 |
+| `get` | `get(name=默认)` | Knex | 取指定连接；不存在**抛异常** |
+| `ping` | `async ping(name=默认)` | boolean | `SELECT 1` 心跳校验，更新健康缓存；启动时及运行时按需调用 |
+| `closeAll` | `async closeAll()` | `Array<{name,success,error?}>` | 批量销毁全部连接，单个失败不阻断其它 |
+| `setSlowThreshold` | `setSlowThreshold(ms)` | void | 运行时调整慢查询阈值（传入 >0 才生效）|
+| `markDown` | `markDown(name=默认)` | void | 运行时主动标记连接不可用（error-handler 捕获 DB 异常时调用）|
+| `markUp` | `markUp(name=默认)` | void | 运行时标记连接恢复可用（error-handler 捕获成功响应时调用）|
+
+**慢查询监控**：默认阈值 `SLOW_THRESHOLD = 200`（ms，来自 `config/index.js`），超过则该条 SQL 记 `warn` 日志（含连接名、耗时、SQL）；查询失败记 `error`（含失败 SQL）。按连接隔离，多库互不影响。
+
+```js
+// 业务里运行时调大阈值（如某库大查询较多，避免误报）
+app.dbManager.setSlowThreshold(500);
+
+// 取指定库连接（对应 Repository 构造第二参 dbName）
+const otherDb = app.dbManager.get("logs");
+```
+
+---
+
+## 六、配置对象 `config` 里有什么
+
+`app.config`（即 `loadConfig()` 的结果）常见字段：
+
+| 字段 | 说明 |
+|---|---|
+| `PORT` | HTTP 监听端口（默认 3000）|
+| `db` | 数据库连接配置数组（支持多库，每项含 `key`/`client`/`connection` 等）|
+| `REDIS_ENABLED` / `REDIS` | Redis 配置 |
+| `JWT_SECRET` | JWT 签名密钥 |
+| `LOCALE` | i18n 默认语言（默认 `zh-CN`）|
+| `LIMIT_MAX` | Repository 单页上限（默认 300）|
+| `SLOW_THRESHOLD` | 数据库慢查询阈值（ms，默认 200），超过记 warn 日志 |
+| `SHUTDOWN_TIMEOUT` | 优雅停机强制退出超时（ms，默认 5000）|
+| `BODY_LIMIT` | 请求体上限（默认 `10mb`）|
+| `HOOK_TIMEOUT` | 单条 beforeStart 钩子超时阈值（ms，默认 10000）|
+| 其它业务自定义项 | 如站点域名、上传方式等 |
+
+```js
+// 在业务里取
+this.config.JWT_SECRET;
+this.config.PORT;
+```
+
+---
+
+## 七、优雅停机
+
+进程收到 `SIGINT` / `SIGTERM` / `SIGQUIT` 时，框架（`utils/signal.js`）自动调用 `shutdown()`：
+停止接收新请求 → `task.stopAll()` 停止定时任务 → `store.close()` 关缓存 → `dbManager.closeAll()` 关库 →
+`event.destroy()` 清监听器 → `setApp(null)`。整个流程带 `SHUTDOWN_TIMEOUT` 超时强退保护。
+你一般无需手动处理，除非有自定义资源（如 WebSocket）要清理，可在 `beforeStart` 里监听信号或注册自己的清理逻辑。
+
+---
+
+## 八、常见坑
+
+1. **`beforeStart` 传了调用结果而非函数**：`app.beforeStart(init())` ❌ → `app.beforeStart(init)` ✅。
+2. **在 `start()` 前用 `this.app.db`**：`db` 在 `#loadDb` 之后才有值，启动钩子/路由处理函数里才安全。
+3. **忘记 `await app.start()`**：`start()` 是异步的，必须 `.then` 或 `await` 后再 `run()`。
+4. **硬编码端口**：用 `config.PORT`，别写死 3000，方便多环境部署。
+5. **以为数据库连不上会中断启动**：框架是"打印错误并继续"，不会自动重连也不会中止；修 `.env` 的 DB 配置即可。
+6. **`dbManager.get(name)` 不存在会抛异常**：取非默认库前确认 `config.db` 里配了该 `key`。