chanjs 2.7.4 → 2.7.5

package/core/bootstrap/error-handler.js

@@ -0,0 +1,104 @@
+import { routeNotFound, serializeError, buildErrorHtml, respondError } from "../../response/index.js";
+import { CODE_NOT_FOUND, CODE_CONFLICT, CODE_BUSINESS_FAIL } from "../../response/code.js";
+import {
+  AppError, isAppError, parseStack, describeError, wrapDbError,
+} from "../errors.js";
+import logger from "../../utils/logger.js";
+
+// 仅这些业务码明确经过了 DB 查询（如查无记录、唯一冲突、业务处理失败），
+// 才推断 DB 已恢复；鉴权(401/403)/参数(422)/限流(429) 等不查库的错误不触发 markUp
+const DB_RECOVERY_CODES = new Set([CODE_NOT_FOUND, CODE_CONFLICT, CODE_BUSINESS_FAIL]);
+
+// 安全开关：是否对外暴露 SQL / 堆栈等详情
+const EXPOSE_ERR_DETAIL = process.env.EXPOSE_ERR_DETAIL === "true";
+const IS_PROD = ["prd", "prod", "production"].includes(process.env.NODE_ENV || "dev");
+
+/**
+ * 注册全局异常兜底中间件（ChanJS底层框架）
+ * @description
+ * 唯一统一错误出口，职责收敛为：日志 / 环境鉴权 / HTTP状态 / 脱敏，全项目所有报错只打印一次。
+ * 1. 404 兜底：路由未匹配时返回标准 404 JSON（须在业务路由之后注册）
+ * 2. 全局异常捕获：DB/底层异常经 wrapDbError 归类为友好 AppError，
+ *    响应层 serializeError 零 DB 感知，换数据库不用改响应代码
+ * 3. 区分浏览器HTML / API JSON：HTML返回框架内置静态错误页，接口返回标准JSON
+ * 4. 双重安全校验：EXPOSE_ERR_DETAIL && (!生产环境 || 携带合法Debug令牌)，生产误开也不泄露堆栈/SQL
+ * @param {object} chan 框架核心实例 { app: Express }
+ */
+export function registerErrorHandler(chan) {
+  const { app, config } = chan;
+
+  // ============ 404 兜底（路由未匹配） ============
+  // 使用 respondError 做 HTML/JSON 分流：页面请求返回框架内置 HTML 错误页，
+  // 接口请求返回标准 JSON；避免浏览器直接访问不存在路径时看到一段 JSON 文本。
+  app.use((req, res) => {
+    const notFound = routeNotFound(req);
+    respondError(res, req, {
+      httpStatus: 404,
+      code: notFound.code,
+      msg: notFound.msg,
+      data: notFound.data,
+    });
+  });
+
+  // ============ 全局异常统一出口 ============
+  app.use((err, req, res, next) => {
+    // 响应头已发送，转交Express默认错误处理
+    if (res.headersSent) return next(err);
+
+    // DB / 底层异常下沉转换：非业务错误先归类为友好 AppError
+    if (!isAppError(err)) err = wrapDbError(err);
+
+    // 连接类故障实时标记：后续未登录请求可直接返回「数据库未连接」，
+    // 而非伪装成 token 缺失（详见 auth 中间件 isDown 短路）
+    const isDbConnection = isAppError(err) && (
+      err.code >= 6000 ||
+      /数据库连接|数据库访问被拒绝|ECONNREFUSED|ETIMEDOUT|连接中断/.test(err.message || "")
+    );
+    if (isDbConnection) {
+      chan.dbManager?.markDown?.();
+    } else if (isAppError(err) && DB_RECOVERY_CODES.has(err.code)) {
+      // 仅明确经过 DB 查询的业务错误（查无记录/唯一冲突/业务失败）才推断 DB 已恢复，
+      // 鉴权/参数/限流等不查库的错误不触发 markUp，避免误标
+      chan.dbManager?.markUp?.();
+    }
+
+    const httpStatus = isAppError(err) ? err.httpStatus : 500;
+    const stackInfo = parseStack(err.stack);
+    // 全链路追踪信息（requestId 需业务/框架注入 req.id 或 x-request-id 头）
+    const requestId = req.headers["x-request-id"] || req.id || "-";
+    const userId = req.user?.id ?? "-";
+
+    // 日志分级：业务错误 4xx → warn，系统错误 5xx → error（唯一打印点，杜绝重复刷屏）
+    const logFn = httpStatus < 500 ? logger.warn : logger.error;
+    logFn(JSON.stringify({
+      type: err.name || "UnknownError",
+      message: describeError(err), // 递归解析 cause 根因，支持 AggregateError
+      file: stackInfo.file,
+      line: stackInfo.line,
+      requestId,
+      method: req.method,
+      url: req.originalUrl,
+      userId,
+    }));
+
+    // 双重安全校验：生产环境即使环境变量开了，也必须携带合法 Debug Token 才暴露堆栈/SQL
+    const exposeDetail = EXPOSE_ERR_DETAIL && (!IS_PROD || req.headers["x-debug-token"] === process.env.DEBUG_TOKEN);
+
+    // 统一判断并返回内置HTML页面（仅浏览器页面访问；API 请求一律 JSON）
+    const sendHtml = (status, message, bizCode) => {
+      if (req.xhr || req.accepts?.(["json", "html"]) === "json") return false;
+      if (!req.accepts?.("html")) return false;
+      res.status(status).type("html").send(buildErrorHtml(status, message, bizCode, req));
+      return true;
+    };
+
+    if (isAppError(err)) {
+      if (sendHtml(httpStatus, err.message, err.code)) return;
+      return res.status(httpStatus).json(serializeError(err, exposeDetail));
+    }
+
+    // 兜底分支（理论上 wrapDbError 已转 AppError，这里防万一）
+    if (sendHtml(500, "服务器内部错误", 500)) return;
+    res.status(500).json(serializeError(err, exposeDetail));
+  });
+}

package/core/bootstrap/hook-runner.js

@@ -0,0 +1,64 @@
+import logger from "../../utils/logger.js";
+import { describeError, errorExtraProps } from "../errors.js";
+import { HOOK_TIMEOUT as DEFAULT_HOOK_TIMEOUT } from "../../config/index.js";
+
+/**
+ * 带超时限制执行钩子，超时则 reject 跳过该钩子，不阻塞后续启动
+ * @param {Function} fn 钩子函数
+ * @param {number} timeout 超时毫秒
+ * @param {string} tag 钩子标识，用于日志
+ * @returns {Promise<void>}
+ */
+async function runHookWithTimeout(fn, timeout, tag) {
+  let timer;
+  const timeoutPromise = new Promise((_, reject) => {
+    timer = setTimeout(
+      () => reject(new Error(`钩子 ${tag} 执行超时(${timeout}ms)，已跳过`)),
+      timeout
+    );
+  });
+  try {
+    await Promise.race([fn(), timeoutPromise]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * 串行执行启动钩子，单钩子超时/报错不阻塞整体启动
+ * 仅支持格式：{ name: string, fn: () => Promise<any> }
+ * @param {object} chan 框架实例
+ */
+export async function runHooks(chan) {
+  const { hooks = [], config = {} } = chan;
+  if (!hooks.length) return;
+
+  const hookTimeout = config.HOOK_TIMEOUT ?? DEFAULT_HOOK_TIMEOUT;
+
+  for (let i = 0; i < hooks.length; i++) {
+    const item = hooks[i];
+    const seq = i + 1;
+    // 支持两种格式：{ name, fn } 对象 或 纯函数（App.beforeStart 注册的是纯函数）
+    let name, fn;
+    if (typeof item === "function") {
+      fn = item;
+      name = null;
+    } else if (item && typeof item === "object") {
+      ({ name, fn } = item);
+    }
+    const hookTag = name || `hook#${seq}`;
+
+    // 非法钩子直接跳过
+    if (typeof fn !== "function") {
+      logger.warn(`[ChanHook][${hookTag}] 第${seq}项钩子fn非函数，跳过`);
+      continue;
+    }
+
+    try {
+      await runHookWithTimeout(fn, hookTimeout, hookTag);
+    } catch (err) {
+      const errLog = describeError(err) + errorExtraProps(err);
+      logger.error(`[ChanHook][${hookTag}] 第${seq}个钩子执行异常:\n${errLog}`, err);
+    }
+  }
+}

package/core/bootstrap/middleware.js

@@ -0,0 +1,35 @@
+import {
+  Cors, body, cookie, favicon, header,
+  staticMw, template, waf, wafBody, log,
+} from "../../middleware/index.js";
+import { BODY_LIMIT } from "../../config/index.js";
+
+/**
+ * 注册核心中间件（顺序固化：不可随意调整）
+ * WAF 前置 → Favicon → 静态 → Cookie → Body 解析 → WAF Body 检查 → CORS → 日志 → 模板 → 响应头
+ * @param {object} chan 框架实例
+ */
+export async function registerCoreMiddleware(chan) {
+  const { app, config: cfg } = chan;
+
+  // 1. WAF 前置（IP/封禁/限流/路径与 query 检查，不依赖请求体）
+  await waf(app, cfg.waf ?? { enabled: false });
+  // 2. Favicon
+  favicon(app);
+  // 3. 静态资源
+  staticMw(app, cfg.statics ?? []);
+  // 4. Cookie
+  cookie(app, cfg.cookieKey);
+  // 5. 请求体解析
+  body(app, cfg.BODY_LIMIT ?? BODY_LIMIT);
+  // 5.1 WAF Body 检查（须在 body 解析之后）
+  wafBody(app, cfg.waf ?? { enabled: false });
+  // 6. CORS
+  Cors(app, cfg.cors ?? {});
+  // 7. 请求日志
+  log(app, cfg.logger ?? {});
+  // 8. 模板渲染
+  template(app, { views: cfg.views ?? [], NODE_ENV: cfg.NODE_ENV ?? "dev" });
+  // 9. 响应头
+  header(app, { APP_NAME: cfg.APP_NAME ?? "ChanCMS", APP_VERSION: cfg.APP_VERSION ?? "1.0.0" });
+}

package/core/bootstrap/router-loader.js

@@ -0,0 +1,53 @@
+import fs from "fs";
+import path from "path";
+import { Router } from "express";
+import { loaderSort, importFile } from "../loader.js";
+import logger from "../../utils/logger.js";
+
+/**
+ * 加载路由公共逻辑：导入并执行路由注册函数
+ * @param {string} filePath 路由文件完整路径
+ * @param {object} app Express实例
+ * @param {object} router 顶层路由
+ * @param {object} config 全局配置
+ */
+async function registerRouterFile(filePath, app, router, config) {
+  if (!fs.existsSync(filePath)) return;
+  try {
+    const register = await importFile(filePath);
+    if (typeof register === "function") {
+      await register(app, router, config);
+    }
+  } catch (err) {
+    logger.error(`[RouterLoader] 路由文件加载失败: ${filePath}`, err);
+  }
+}
+
+/**
+ * 加载 modules 业务模块路由，按配置顺序挂载
+ * @param {object} chan 框架实例
+ */
+export async function loadModuleRouter(chan) {
+  const { paths, config, app, router } = chan;
+  const modulesDir = paths.modulesPath;
+  if (!fs.existsSync(modulesDir)) return;
+
+  const moduleNames = loaderSort(config.modules ?? []);
+  for (const name of moduleNames) {
+    const routeFile = path.join(modulesDir, name, "router.js");
+    // 每个模块使用独立的子 Router 实例，防止模块内 router.use(auth()) 等无路径前缀
+    // 的中间件污染全局，导致未匹配路径（如 404）被提前拦截成鉴权错误。
+    const subRouter = Router();
+    await registerRouterFile(routeFile, app, subRouter, config);
+  }
+}
+
+/**
+ * 加载项目根公共路由 router.js
+ * @param {object} chan 框架实例
+ */
+export async function loadCommonRouter(chan) {
+  const { paths, app, router, config } = chan;
+  const commonRouteFile = path.join(paths.appPath, "router.js");
+  await registerRouterFile(commonRouteFile, app, router, config);
+}

package/core/errors.js

@@ -0,0 +1,224 @@
+import {
+  CODE_AUTH_FAILED, CODE_TOKEN_EXPIRED, CODE_FORBIDDEN, CODE_NOT_FOUND,
+  CODE_CONFLICT, CODE_PARAM_INVALID, CODE_PARAM_MISSING, CODE_BUSINESS_FAIL,
+  CODE_RATE_LIMIT, CODE_BLOCKED, CODE_SYSTEM_ERROR, CODE_SERVICE_BUSY,
+  CODE_DB_CONNECTION_ERROR, CODE_DB_ACCESS_DENIED, CODE_DB_OPERATION_TIMEOUT,
+} from "../response/code.js";
+
+/** 全局错误配置中心 */
+const ERROR_CONFIG = {
+  AuthError:         { code: CODE_AUTH_FAILED,           httpStatus: 401, defaultMsg: '认证失败' },
+  TokenExpiredError: { code: CODE_TOKEN_EXPIRED,         httpStatus: 401, defaultMsg: '令牌已过期' },
+  ForbiddenError:    { code: CODE_FORBIDDEN,             httpStatus: 403, defaultMsg: '权限不足' },
+  NotFoundError:     { code: CODE_NOT_FOUND,             httpStatus: 404, defaultMsg: '资源不存在' },
+  ConflictError:     { code: CODE_CONFLICT,              httpStatus: 409, defaultMsg: '资源已存在' },
+  ValidationError:   { code: CODE_PARAM_INVALID,         httpStatus: 422, defaultMsg: '参数无效', extraProps: ['fields'] },
+  ParamMissingError: { code: CODE_PARAM_MISSING,         httpStatus: 400, defaultMsg: '参数缺失' },
+  BusinessError:     { code: CODE_BUSINESS_FAIL,         httpStatus: 400, defaultMsg: '业务处理失败' },
+  RateLimitError:    { code: CODE_RATE_LIMIT,            httpStatus: 429, defaultMsg: '请求过于频繁', extraProps: ['retryAfter'] },
+  BlockedError:      { code: CODE_BLOCKED,               httpStatus: 403, defaultMsg: '访问已被限制', extraProps: ['retryAfter'] },
+  SystemError:       { code: CODE_SYSTEM_ERROR,          httpStatus: 500, defaultMsg: '系统内部错误' },
+  ServiceBusyError:  { code: CODE_SERVICE_BUSY,          httpStatus: 503, defaultMsg: '服务繁忙' },
+  DbConnectionError: { code: CODE_DB_CONNECTION_ERROR,   httpStatus: 503, defaultMsg: '数据库连接失败' },
+  DbAccessDeniedError:{ code: CODE_DB_ACCESS_DENIED,     httpStatus: 503, defaultMsg: '数据库访问被拒绝' },
+  DbTimeoutError:    { code: CODE_DB_OPERATION_TIMEOUT,  httpStatus: 503, defaultMsg: '数据库操作超时' },
+};
+
+const MAX_RECURSIVE_DEPTH = 10;
+
+/**
+ * 业务错误基类
+ */
+export class AppError extends Error {
+  /**
+   * @param {number} code 业务码
+   * @param {string} msg 提示文案
+   * @param {number} httpStatus HTTP状态码
+   * @param {Error|unknown} [cause] 底层原始错误
+   */
+  constructor(code, msg, httpStatus = 400, cause = null) {
+    super(msg, { cause });
+    this.name = 'AppError';
+    this.code = code;
+    this.httpStatus = httpStatus;
+    this.meta = {};
+    if (Error.captureStackTrace) Error.captureStackTrace(this, this.constructor);
+  }
+
+  /** 统一判断是否为业务错误实例 */
+  static isAppError(err) {
+    return err instanceof AppError;
+  }
+
+  /** 自定义序列化 */
+  toJSON() {
+    const json = { name: this.name, message: this.message, code: this.code, httpStatus: this.httpStatus };
+    for (const key of Object.getOwnPropertyNames(this)) {
+      const val = this[key];
+      if (val === undefined || val === null) continue;
+      if (typeof val === 'function' || typeof val === 'symbol') continue;
+      json[key] = val;
+    }
+    return json;
+  }
+}
+
+/** 动态生成业务错误 Class */
+function createErrorClass(className) {
+  const cfg = ERROR_CONFIG[className];
+  if (!cfg) throw new Error(`错误类型[${className}]未在ERROR_CONFIG中配置`);
+
+  return class extends AppError {
+    constructor(msgOrOpts, ...rest) {
+      const opts = (msgOrOpts && typeof msgOrOpts === 'object') ? msgOrOpts : { msg: msgOrOpts, ...Object.fromEntries(cfg.extraProps?.map((k, i) => [k, rest[i]]) ?? []), cause: rest[cfg.extraProps?.length] };
+      super(cfg.code, opts.msg ?? cfg.defaultMsg, cfg.httpStatus, opts.cause ?? null);
+      this.name = className;
+      for (const [k, v] of Object.entries(opts)) {
+        if (k !== 'msg' && k !== 'cause' && v !== undefined) this[k] = v;
+      }
+    }
+  };
+}
+
+// 业务错误类导出
+export const AuthError          = createErrorClass('AuthError');
+export const TokenExpiredError  = createErrorClass('TokenExpiredError');
+export const ForbiddenError     = createErrorClass('ForbiddenError');
+export const NotFoundError      = createErrorClass('NotFoundError');
+export const ConflictError      = createErrorClass('ConflictError');
+export const ValidationError    = createErrorClass('ValidationError');
+export const ParamMissingError  = createErrorClass('ParamMissingError');
+export const BusinessError      = createErrorClass('BusinessError');
+export const RateLimitError     = createErrorClass('RateLimitError');
+export const BlockedError       = createErrorClass('BlockedError');
+export const SystemError        = createErrorClass('SystemError');
+export const ServiceBusyError   = createErrorClass('ServiceBusyError');
+export const DbConnectionError  = createErrorClass('DbConnectionError');
+export const DbAccessDeniedError= createErrorClass('DbAccessDeniedError');
+export const DbTimeoutError     = createErrorClass('DbTimeoutError');
+
+/**
+ * 提取错误自定义附加属性，用于日志打印
+ */
+export function errorExtraProps(err) {
+  if (!err || !(err instanceof Error)) return "";
+  const parts = [];
+  for (const k of Object.getOwnPropertyNames(err)) {
+    if (k === "message" || k === "stack" || k === "name" || k === "cause" || k === "constructor") continue;
+    const val = err[k];
+    if (typeof val === 'function' || typeof val === 'symbol') continue;
+    try {
+      parts.push(`${k}=${typeof val === "string" ? val : JSON.stringify(val)}`);
+    } catch {
+      parts.push(`${k}=[unserializable]`);
+    }
+  }
+  return parts.length ? ` | ${parts.join("; ")}` : "";
+}
+
+/**
+ * 递归解析完整可读错误信息，内置递归深度限制防栈溢出
+ */
+export function describeError(err, depth = 0) {
+  if (!err) return "未知错误";
+  if (depth >= MAX_RECURSIVE_DEPTH) return `[递归深度超限(${MAX_RECURSIVE_DEPTH})，停止解析]`;
+
+  // 聚合错误批量展开子错误
+  if (err instanceof AggregateError && Array.isArray(err.errors) && err.errors.length) {
+    const reasons = err.errors
+      .map((e, i) => `    [${i + 1}] ${describeError(e, depth + 1)}`)
+      .join("\n");
+    return `聚合错误(AggregateError)共${err.errors.length}个原因：\n${reasons}`;
+  }
+
+  const baseMsg = err.message || String(err);
+  let hint = baseMsg;
+
+  // 数据库/网络错误智能提示
+  if (/ECONNREFUSED/.test(baseMsg)) {
+    hint = `数据库连接被拒绝(ECONNREFUSED) — 检查数据库服务、地址端口配置: ${baseMsg}`;
+  } else if (/ENOTFOUND|EAI_AGAIN/.test(baseMsg)) {
+    hint = `数据库域名解析失败 — 检查DB_HOST环境变量: ${baseMsg}`;
+  } else if (/ECONNRESET|PROTOCOL_CONNECTION_LOST|ETIMEDOUT/.test(baseMsg)) {
+    hint = `数据库连接中断/超时 — 检查服务状态、连接池上限: ${baseMsg}`;
+  }
+
+  const causeText = err.cause
+    ? err.cause instanceof Error
+      ? ` | cause: ${describeError(err.cause, depth + 1)}`
+      : ` | cause: ${String(err.cause)}`
+    : "";
+
+  return `${hint}${causeText}${errorExtraProps(err)}`;
+}
+
+/** 全局判断业务错误 */
+export function isAppError(err) {
+  return err instanceof AppError;
+}
+
+/**
+ * 判断是否为数据库连接类错误（code + message 双重检测）
+ */
+const CONNECTION_CODES = new Set([
+  "ECONNREFUSED", "ENOTFOUND", "EAI_AGAIN", "ETIMEDOUT",
+  "ECONNRESET", "PROTOCOL_CONNECTION_LOST", "PROTOCOL_ENQUEUE_AFTER_FATAL_ERROR",
+]);
+const CONNECTION_KEYWORDS = [
+  "econnrefused", "enotfound", "eai_again", "etimedout", "econnreset",
+  "connection lost", "connection closed", "pool is full", "too many connections",
+  "closed unexpectedly", "connect timeout", "handshake timeout",
+];
+
+function isDbConnectionError(err) {
+  if (CONNECTION_CODES.has(err?.code)) return true;
+  const msg = String(err?.message || "").toLowerCase();
+  return CONNECTION_KEYWORDS.some(kw => msg.includes(kw));
+}
+
+/**
+ * DB / 底层异常统一拦截器：转换为框架标准 AppError 子类
+ * @param {Error} err
+ * @returns {AppError}
+ */
+export function wrapDbError(err) {
+  if (isAppError(err)) return err;
+
+  // 聚合错误（mysql2 批量操作）提取首个真实原因
+  let e = err;
+  if (err instanceof AggregateError && Array.isArray(err.errors) && err.errors.length) {
+    e = err.errors.find(x => x instanceof Error) ?? err.errors[0];
+  }
+
+  if (isDbConnectionError(e)) return new DbConnectionError("数据库连接失败，请稍后重试", err);
+
+  const driverCode = e?.code;
+  switch (driverCode) {
+    case "ER_DUP_ENTRY":
+    case "23505":
+      return new ConflictError("数据已存在", err);
+    case "ER_ACCESS_DENIED_ERROR":
+      return new DbAccessDeniedError("数据库访问被拒绝", err);
+    case "ER_NO_SUCH_TABLE":
+      return new SystemError("数据表不存在", err);
+    case "ER_BAD_FIELD_ERROR":
+      return new ParamMissingError("数据库字段错误", err);
+    case "ER_ROW_IS_REFERENCED_2":
+      return new ConflictError("存在关联数据，操作失败", err);
+    default:
+      return new SystemError("数据操作异常", err);
+  }
+}
+
+/** 解析 V8 堆栈，提取报错文件、行号 */
+export function parseStack(stack) {
+  if (!stack || typeof stack !== "string") {
+    return { message: "无堆栈信息", file: "-", line: "-" };
+  }
+  const lines = stack.split("\n").filter(Boolean);
+  const message = lines[0];
+  const traceLine = lines[1] ?? "";
+  const match = traceLine.match(/\(([^:]+):(\d+):\d+\)/) || traceLine.match(/at\s+([^:]+):(\d+):\d+/);
+  if (match) return { message, file: match[1], line: match[2] };
+  return { message, file: traceLine.trim(), line: "-" };
+}

package/core/loader.js

@@ -0,0 +1,89 @@
+import fs from "fs";
+import fsp from "fs/promises";
+import path from "path";
+import { pathToFileURL } from "url";
+import { Paths } from "../utils/paths.js";
+import logger from "../utils/logger.js";
+
+const BOUND_SYMBOL = Symbol("chanjs:bound");
+const JS_SUFFIX = /\.js$/i;
+
+/**
+ * 动态导入文件，捕获常见IO异常
+ * @param {string} filepath
+ * @returns {Promise<any|null>}
+ */
+export async function importFile(filepath) {
+  if (!filepath || typeof filepath !== "string") {
+    logger.error("[Loader] 文件路径非法");
+    return null;
+  }
+  try {
+    await fsp.access(filepath);
+    const mod = await import(pathToFileURL(filepath).href);
+    return mod.default ?? mod;
+  } catch (err) {
+    if (err.code === "ENOENT") logger.error(`[Loader] 文件不存在: ${filepath}`);
+    else if (err.code === "EACCES") logger.error(`[Loader] 无访问权限: ${filepath}`);
+    else logger.error(`[Loader] 导入失败 ${filepath}:`, err.message);
+    return null;
+  }
+}
+
+/**
+ * 模块排序：web模块强制后置
+ * @param {string[]} modules
+ * @returns {string[]}
+ */
+export function loaderSort(modules = []) {
+  const webIdx = modules.indexOf("web");
+  if (webIdx > -1) modules.push(modules.splice(webIdx, 1)[0]);
+  return modules;
+}
+
+/**
+ * 加载根配置 index.js
+ */
+export async function loadConfig() {
+  const cfg = await importFile(path.join(Paths.configPath, "index.js"));
+  return cfg ?? {};
+}
+
+/**
+ * 加载指定模块全部Controller，自动绑定实例方法防this丢失
+ * @param {string} moduleName
+ * @returns {Record<string, any>}
+ */
+export async function loadController(moduleName) {
+  const ctrlDir = path.join(Paths.modulesPath, moduleName, "controller");
+  const ctrlMap = {};
+
+  if (!fs.existsSync(ctrlDir)) {
+    logger.error(`[Loader] 控制器目录不存在: ${ctrlDir}`);
+    return ctrlMap;
+  }
+
+  const jsFiles = fs.readdirSync(ctrlDir).filter(f => JS_SUFFIX.test(f));
+  for (const file of jsFiles) {
+    const filePath = path.join(ctrlDir, file);
+    const ctrlName = file.replace(JS_SUFFIX, "");
+    const inst = await importFile(filePath);
+    if (!inst || typeof inst !== "object") continue;
+
+    // 原型方法批量bind，幂等标记避免重复绑定
+    const proto = Object.getPrototypeOf(inst);
+    if (!proto) continue;
+    Object.getOwnPropertyNames(proto).forEach(key => {
+      const fn = inst[key];
+      if (key === "constructor" || typeof fn !== "function" || fn[BOUND_SYMBOL]) return;
+      const boundFn = fn.bind(inst);
+      Object.defineProperty(boundFn, BOUND_SYMBOL, {
+        value: true, enumerable: false, writable: false, configurable: false
+      });
+      inst[key] = boundFn;
+    });
+
+    ctrlMap[ctrlName] = inst;
+  }
+  return ctrlMap;
+}

package/core/registry.js

@@ -0,0 +1,17 @@
+/**
+ * 全局单应用实例注册表
+ * 全局仅维护单个Chan实例，多实例采用多进程方案
+ */
+let _current = null;
+
+/** 设置全局应用实例 */
+export function setApp(app) {
+  _current = app;
+}
+
+/** 获取全局应用实例，未初始化返回null */
+export function getApp() {
+  return _current;
+}
+
+export default { setApp, getApp };