chanjs 2.7.4 → 2.7.6

package/utils/ip.js

@@ -1,72 +1,32 @@
-/**
- * 从请求对象中获取客户端真实 IP 地址
- * @param {Object} req - Express 请求对象
- * @param {string} [req.ip] - Express 解析的 IP（已包含代理头部解析）
- * @param {Object} [req.headers] - 请求头对象
- * @param {string} [req.headers.cf-connecting-ip] - Cloudflare 连接 IP
- * @param {string} [req.headers.cf-ray] - Cloudflare 请求追踪 ID
- * @returns {string} 客户端 IP 地址，如果无法获取则返回 "0.0.0.0"
- * @description
- * 从 Express 的 req.ip 获取客户端 IP。
- *
- * 注意：需要在 App.js 中设置 trust proxy：
- * app.set("trust proxy", true);
- *
- * 设置 trust proxy 后，Express 会自动从以下头部解析真实 IP：
- * - X-Forwarded-For（反向代理，如 Nginx）
- * - X-Real-IP
- * - CF-Connecting-IP（Cloudflare CDN）
- *
- * 此方法按优先级从以下来源获取 IP 地址：
- * 1. cf-connecting-ip 请求头（仅当同时存在 cf-ray 时才信任，防止伪造）
- * 2. req.ip（Express 自动解析，已包含代理头部处理）
- * 3. 默认值 "0.0.0.0"
- *
- * 安全改进：
- * - 仅当同时存在 cf-ray 头时才信任 cf-connecting-ip
- * - 避免攻击者直接伪造 cf-connecting-ip 头绕过 IP 限流
- * - Cloudflare CDN 总是会同时下发这两个头
- *
- * @example
- * app.use((req, res, next) => {
- *   const ip = getIp(req);
- *   console.log(`访问 IP: ${ip}`);
- *   next();
- * });
- */
-export function getIp(req) {
-  const headers = req.headers || {};
-
-  // 1. 仅在 CF_ENABLED=true 时信任 cf-* 头部
-  // 单凭 cf-ray 头部仍可被伪造，必须显式声明部署在 Cloudflare 后才信任
-  // 否则攻击者可任意伪造 cf-connecting-ip / cf-ray 绕过 IP 限流
-  if (process.env.CF_ENABLED === 'true' && headers["cf-ray"]) {
-    let cfIp = headers["cf-connecting-ip"];
-    if (cfIp) {
-      cfIp = cfIp.split(',').map(ip => ip.trim())[0];
-      if (cfIp) {
-        return cfIp;
-      }
-    }
-  }
-
-  // 2. 其次使用 Express 解析的 req.ip（已处理代理头部）
-  if (req.ip) {
-    let ip = req.ip;
-
-    // 处理 IPv6 映射的 IPv4 地址（如 ::ffff:192.168.1.1 → 192.168.1.1）
-    if (ip.startsWith('::ffff:')) {
-      ip = ip.substring(7);
-    }
-
-    // 处理本地回环地址（::1 → 127.0.0.1）
-    if (ip === '::1') {
-      ip = '127.0.0.1';
-    }
-
-    return ip;
-  }
-
-  // 3. 无法获取时返回约定的默认值
-  return "0.0.0.0";
+/**
+ * 获取客户端真实 IP（Express 专用）
+ * 前置要求：App 已配置 app.set('trust proxy', <上游代理IP/CIDR列表>)，Express 自动解析真实客户端 IP。
+ *   注意：trust proxy 必须精确声明真实上游代理（如 loopback / 10.0.0.0/8），切勿设为 true，
+ *   否则攻击者可伪造 X-Forwarded-For 伪装成内网 IP 绕过 WAF。
+ * IP 信任优先级（防头部伪造，层级严格限制）：
+ *   1. cf-connecting-ip（仅同时满足 CF_ENABLED=true + 请求携带 cf-ray 请求头，才可信，避免伪造CF头）
+ *   2. Express 内置解析 req.ip（已融合代理链路，最稳妥通用）
+ *   3. 兜底默认值 0.0.0.0
+ * 额外处理：IPv6 映射IPv4、IPv6本地回环统一转为标准IPv4格式
+ * @param {import('express').Request} req Express 请求对象
+ * @returns {string} 客户端IP地址
+ */
+export function getIp(req) {
+  // 1. Cloudflare 源IP（双重校验环境变量+cf-ray头，防止恶意伪造CF头部）
+  if (process.env.CF_ENABLED === 'true' && req?.headers?.['cf-ray']) {
+    const cfIp = req.headers['cf-connecting-ip']
+      ?.split(',')[0]?.trim();
+    if (cfIp) return cfIp;
+  }
+
+  // 2. Express 自动解析后的标准IP
+  if (typeof req?.ip === 'string' && req.ip.trim()) {
+    const ip = req.ip.trim()
+      .replace(/^::ffff:/, '')  // IPv6映射IPv4
+      .replace(/^::1$/, '127.0.0.1');  // IPv6本地回环
+    return ip;
+  }
+
+  // 兜底未知IP
+  return '0.0.0.0';
 }

package/utils/logger.js

@@ -0,0 +1,117 @@
+/**
+ * 统一日志工具
+ * 1. 本地dev：彩色友好打印
+ * 2. 线上prd：JSON单行字符串输出，供日志采集器解析
+ * 3. 日志分级控制 LOG_LEVEL，线上关闭调试日志减少磁盘占用
+ * 4. error/fatal 自动走 stderr
+ * 5. 支持自定义模块标签、本地文件落盘、错误堆栈结构化解析
+ */
+import fs from "fs";
+import path from "path";
+import { parseStack } from "../core/errors.js";
+
+const LOG_LEVELS = Object.freeze({
+  trace: 0, debug: 1, info: 2, warn: 3, error: 4, fatal: 5, silent: 99,
+});
+
+const COLORS = Object.freeze({
+  trace: "\x1b[90m",
+  debug: "\x1b[34m",
+  info: "\x1b[32m",
+  warn: "\x1b[33m",
+  error: "\x1b[31m",
+  fatal: "\x1b[41m\x1b[37m",
+  reset: "\x1b[0m",
+});
+
+const ERROR_LEVELS = new Set(["error", "fatal"]);
+
+const NODE_ENV = (process.env.NODE_ENV || "dev").toLowerCase();
+const IS_PROD = ["prd", "prod", "production"].includes(NODE_ENV);
+const DEFAULT_LOG_LEVEL = IS_PROD ? "info" : "debug";
+const CURRENT_LEVEL = LOG_LEVELS[(process.env.LOG_LEVEL || DEFAULT_LOG_LEVEL).toLowerCase()] ?? LOG_LEVELS.info;
+
+const LOG_FILE = process.env.LOG_FILE || "";
+let writeStream = null;
+
+/** 判断当前级别是否允许输出 */
+const isLevelEnable = level => (LOG_LEVELS[level] ?? 99) >= CURRENT_LEVEL;
+
+/** 格式化毫秒级时间戳 YYYY-MM-DD HH:mm:ss.SSS */
+function getTime() {
+  const now = new Date();
+  const pad = (n, len = 2) => String(n).padStart(len, "0");
+  return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}:${pad(now.getMinutes())}:${pad(now.getSeconds())}.${pad(now.getMilliseconds(), 3)}`;
+}
+
+/** 本地日志文件写入（仅开发环境） */
+function writeFile(line) {
+  if (!LOG_FILE.trim() || IS_PROD) return;
+  try {
+    if (!writeStream) {
+      const dir = path.dirname(LOG_FILE);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      writeStream = fs.createWriteStream(LOG_FILE, { flags: "a" });
+      writeStream.on("error", () => {}); // 静默吞掉流异常，不阻塞业务
+      process.once("exit", () => writeStream?.end());
+    }
+    writeStream.write(`${line}\n`);
+  } catch { /* 写入失败静默 */ }
+}
+
+/** 解析日志入参，分离普通文本与错误堆栈 */
+function parseArgs(args) {
+  let stackInfo = null;
+  const parts = [];
+  for (const arg of args) {
+    if (arg instanceof Error) {
+      const stackData = parseStack(arg.stack);
+      stackInfo = { ...stackData, raw: arg.stack };
+      parts.push(arg.message);
+    } else if (arg !== null && typeof arg === "object") {
+      try { parts.push(JSON.stringify(arg)); }
+      catch { parts.push(String(arg)); }
+    } else {
+      parts.push(arg);
+    }
+  }
+  return { message: parts.join(" "), stackInfo };
+}
+
+/** 日志核心输出 */
+function emit(level, label, args) {
+  if (!isLevelEnable(level)) return;
+
+  const { message, stackInfo } = parseArgs(args);
+  const time = getTime();
+  const isErrLog = ERROR_LEVELS.has(level);
+  const printFn = isErrLog ? console.error : console.log;
+
+  if (IS_PROD) {
+    const logLine = JSON.stringify({ time, env: NODE_ENV, level, label, message, stack: stackInfo, pid: process.pid });
+    printFn(logLine);
+    return;
+  }
+
+  const color = COLORS[level] ?? "";
+  printFn(`${color}[${time}] [${level.toUpperCase()}] [${label}]${COLORS.reset}`, ...args);
+  if (stackInfo) console.error(`${color}>>>> 错误堆栈详情:${COLORS.reset}`, stackInfo);
+  writeFile(`[${time}] [${level.toUpperCase()}] [${label}] ${message}`);
+}
+
+/** 创建带固定业务标签的日志实例 */
+export function createLogger(label = "Chan") {
+  const safeLabel = String(label).trim() || "Chan";
+  const make = level => (...args) => emit(level, safeLabel, args);
+  return {
+    trace: make("trace"),
+    debug: make("debug"),
+    info: make("info"),
+    warn: make("warn"),
+    error: make("error"),
+    fatal: make("fatal"),
+  };
+}
+
+const logger = createLogger("Chan");
+export default logger;

package/utils/pages.js

@@ -0,0 +1,55 @@
+/**
+ * 分页工具函数
+ * 样式采用 Tailwind CSS 原子类，紧凑精致布局
+ */
+const LI_DISABLED = 'inline-flex items-center px-3 py-1.5 text-sm text-slate-400 cursor-not-allowed rounded-md border border-slate-100 bg-slate-50';
+const LI_ELLIPSIS = 'inline-flex items-center px-2 py-1.5 text-sm text-slate-400';
+const LI_CURRENT = 'inline-flex items-center px-3 py-1.5 text-sm font-medium text-white bg-lime-600 border border-lime-600 rounded-md';
+const LI_LINK = 'inline-flex items-center text-sm text-slate-700 bg-white border border-slate-200 rounded-md hover:border-lime-600 hover:text-lime-600 transition-colors';
+const A_LINK = 'block px-3 py-1.5';
+
+/**
+ * 渲染分页HTML
+ * @param {number} current 当前页码
+ * @param {number} total 总记录数
+ * @param {number} pageSize 每页大小
+ * @param {string} href 链接基础路径
+ * @param {string} [query=''] 查询参数字符串
+ * @returns {string}
+ */
+export function pages(current, total, pageSize, href, query = '') {
+  current = Math.max(1, parseInt(current) || 1);
+  total = parseInt(total) || 0;
+  pageSize = parseInt(pageSize) || 10;
+
+  const totalPage = Math.ceil(total / pageSize);
+  if (totalPage <= 1) return '';
+  if (current > totalPage) current = totalPage;
+
+  const pageLink = (i, text) => `<li class="${i === current ? LI_CURRENT : LI_LINK}"><a class="${A_LINK}" href='${href}${i}.html${query}'>${text || i}</a></li>`;
+  const navLink = (i, text) => i ? pageLink(i, text) : `<li class="${LI_DISABLED}">${text}</li>`;
+  const items = [];
+
+  // 上一页
+  items.push(navLink(current - 1, "上一页"));
+
+  // 页码
+  if (totalPage <= 7) {
+    for (let i = 1; i <= totalPage; i++) items.push(pageLink(i));
+  } else if (current <= 4) {
+    for (let i = 1; i <= 5; i++) items.push(pageLink(i));
+    items.push(`<li class="${LI_ELLIPSIS}">...</li>`, pageLink(totalPage));
+  } else if (current >= totalPage - 3) {
+    items.push(pageLink(1), `<li class="${LI_ELLIPSIS}">...</li>`);
+    for (let i = totalPage - 4; i <= totalPage; i++) items.push(pageLink(i));
+  } else {
+    items.push(pageLink(1), `<li class="${LI_ELLIPSIS}">...</li>`);
+    for (let i = current - 1; i <= current + 1; i++) items.push(pageLink(i));
+    items.push(`<li class="${LI_ELLIPSIS}">...</li>`, pageLink(totalPage));
+  }
+
+  // 下一页
+  items.push(navLink(current + 1, "下一页"));
+
+  return items.join("");
+}

package/utils/paths.js

@@ -0,0 +1,18 @@
+import path from "path";
+
+/** 路径配置：项目常用路径访问器（getter 动态计算，避免快照不同步） */
+export const Paths = {
+  rootPath: process.cwd(),
+};
+
+Object.defineProperties(Paths, {
+  appPath:     { get() { return path.join(this.rootPath, "app"); } },
+  configPath:  { get() { return path.join(this.rootPath, "config"); } },
+  publicPath:  { get() { return path.join(this.rootPath, "public"); } },
+  modulesPath: { get() { return path.join(this.appPath, "modules"); } },
+  commonPath:  { get() { return path.join(this.appPath, "common"); } },
+  helperPath:  { get() { return path.join(this.appPath, "helper"); } },
+  extendPath:  { get() { return path.join(this.appPath, "extend"); } },
+});
+
+export default Paths;

package/utils/request.js

@@ -1,172 +1,131 @@
-/**
- * HTTP 请求工具函数
- * 提供统一的请求发送方法
- */
+import logger from "./logger.js";
+import dns from "dns";
+import { promisify } from "util";
 
-/**
- * 默认请求超时时间（毫秒）
- * 防止无超时控制的 fetch 挂起导致连接堆积
- */
+const dnsLookup = promisify(dns.lookup);
 const DEFAULT_TIMEOUT = 10000;
-
-/**
- * 最大响应体大小（10MB）
- * 超过此大小直接拒绝，防止远端返回超大响应导致内存爆炸
- */
 const MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
 
-/**
- * 内网/特殊地址检查（SSRF 防护）
- * 拒绝请求内网 IP 和非 http/https 协议
- * @param {string} urlStr - 待检查的 URL
- * @returns {Promise<boolean>} true 表示不安全（应拒绝）
- * @private
- */
-async function _isPrivateUrl(urlStr) {
-  try {
-    const u = new URL(urlStr);
-    // 仅允许 http/https 协议
-    if (!['http:', 'https:'].includes(u.protocol)) return true;
-    const host = u.hostname;
-    if (!host) return true;
-    // 拒绝 localhost 和内网 IP
-    if (host === 'localhost' || /^(127\.|10\.|192\.168\.|172\.(1[6-9]|2[0-9]|3[01])\.|169\.254\.|0\.)/.test(host)) {
-      return true;
-    }
-    return false;
-  } catch {
-    return true;
-  }
+/** IPv4 私网/回环段 */
+const IPV4_PRIVATE = /^(127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|169\.254\.|0\.0\.0\.0$)/;
+/** IPv6 私网/链路本地前缀 */
+const IPV6_PRIVATE = /^(::1$|fc|fd|fe80:)/i;
+
+/** 判断 IP 是否指向私网/回环（含 IPv4-mapped IPv6） */
+function isPrivateIp(ip) {
+  if (!ip) return true;
+  const v = ip.toLowerCase();
+  if (v === "127.0.0.1" || v === "::1") return true;
+  if (IPV4_PRIVATE.test(v)) return true;
+  const m = v.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (m) return IPV4_PRIVATE.test(m[1]);
+  return IPV6_PRIVATE.test(v);
+}
+
+/** SSRF 防护：协议白名单 + 主机名解析后 IP 二次校验 */
+async function isPrivateUrl(urlStr) {
+  let u;
+  try { u = new URL(urlStr.trim()); }
+  catch { return true; }
+  if (!["http:", "https:"].includes(u.protocol)) return true;
+  const host = u.hostname.toLowerCase();
+  if (!host || host === "localhost") return true;
+  if (/^[\d.:a-f]+$/i.test(host)) return isPrivateIp(host);
+  try { return isPrivateIp((await dnsLookup(host)).address); }
+  catch { return true; }
 }
 
 /**
- * 发送 HTTP 请求
- * @async
- * @param {string} url - 请求 URL
- * @param {Object} [options={}] - 请求选项
- * @param {string} [options.method='GET'] - HTTP 方法
- * @param {Object} [options.headers] - 请求头
- * @param {Object|string} [options.body] - 请求体
- * @param {number} [options.timeout=10000] - 请求超时时间（毫秒），0 表示不超时
- * @param {number} [options.retry=0] - 失败重试次数，默认 0
- * @param {number} [options.maxResponseBytes=10485760] - 最大响应字节数，默认 10MB
- * @returns {Promise<Object|null>} 响应数据，失败时返回 null
- * @description
- * 发送 HTTP 请求并返回 JSON 格式的响应数据
- * - 自动将对象类型的 body 转换为 JSON 字符串
- * - 默认 Content-Type 为 application/json
- * - 内置 AbortController 超时控制，默认 10 秒
- * - SSRF 防护：拒绝请求内网/localhost 地址
- * - 响应大小限制：超过 maxResponseBytes 拒绝
- * - response.ok 校验：HTTP 状态码非 2xx 时返回 null
- * - 失败重试：网络错误时按 retry 次数重试
- * @example
- * const data = await request('https://api.example.com/users', {
- *   method: 'POST',
- *   body: { name: '张三' },
- *   timeout: 5000,
- *   retry: 2
- * });
+ * HTTP 请求封装：超时/重试/SSRF 防护/大小限制
+ * 支持 JSON 和原始数据（Buffer/文本）两种模式
+ * @param {string} url - 请求地址
+ * @param {Object} [options={}] - 请求配置
+ * @param {number} [options.timeout=10000] - 超时时间(ms)
+ * @param {number} [options.retry=0] - 重试次数
+ * @param {boolean} [options.parseJson=true] - 是否 JSON.parse 响应
+ * @param {string} [options.responseType] - "arraybuffer" 返回 Buffer
+ * @param {number} [options.maxResponseBytes] - 最大响应字节数
+ * @returns {Promise<{success:boolean,data:any,error?:string}>}
  */
 export async function request(url, options = {}) {
+  const rawUrl = String(url ?? "").trim();
+  if (!rawUrl) return { success: false, error: "url不能为空" };
+
   const {
     timeout = DEFAULT_TIMEOUT,
     retry = 0,
+    parseJson = true,
+    responseType,
     maxResponseBytes = MAX_RESPONSE_BYTES,
-    ...restOptions
+    ...rest
   } = options;
 
-  // SSRF 防护：拒绝内网/特殊地址
-  if (await _isPrivateUrl(url)) {
-    console.error(`[Request] SSRF 防护：拒绝请求内网/非法地址: ${url}`);
-    return null;
+  // SSRF 防护
+  if (await isPrivateUrl(rawUrl)) {
+    return { success: false, error: `SSRF防护拦截：${rawUrl}` };
   }
 
-  const defaultOptions = {
-    method: 'GET',
-    headers: {
-      'Content-Type': 'application/json',
-    },
+  // 构建 fetch 选项
+  const fetchOpts = {
+    method: "GET",
+    headers: { "Content-Type": "application/json" },
+    ...rest
   };
 
-  const finalOptions = { ...defaultOptions, ...restOptions };
-
-  if (finalOptions.body && typeof finalOptions.body !== 'string') {
-    finalOptions.body = JSON.stringify(finalOptions.body);
+  // body 序列化
+  if (fetchOpts.body && typeof fetchOpts.body !== "string") {
+    try {
+      fetchOpts.body = JSON.stringify(fetchOpts.body);
+    } catch (err) {
+      return { success: false, error: `请求体JSON序列化失败: ${err.message}` };
+    }
   }
 
-  // 重试逻辑
-  let lastError = null;
+  // 重试循环
   for (let attempt = 0; attempt <= retry; attempt++) {
-    // 超时控制：通过 AbortController 在指定时间后中止请求
-    let controller = null;
-    let timer = null;
-    if (timeout > 0) {
-      controller = new AbortController();
-      finalOptions.signal = controller.signal;
-      timer = setTimeout(() => controller.abort(), timeout);
-    }
+    const controller = new AbortController();
+    const timer = timeout > 0 ? setTimeout(() => controller.abort(), timeout) : null;
 
     try {
-      const response = await fetch(url, finalOptions);
-
-      // HTTP 状态码校验：非 2xx 视为失败
-      if (!response.ok) {
-        console.error(`[Request] HTTP ${response.status} ${response.statusText}: ${url}`);
-        return null;
-      }
+      const res = await fetch(rawUrl, { ...fetchOpts, signal: controller.signal });
+      if (timer) clearTimeout(timer);
 
-      // 响应大小校验：content-length 超限直接拒绝
-      const contentLength = parseInt(response.headers.get('content-length') || '0', 10);
-      if (contentLength && contentLength > maxResponseBytes) {
-        console.error(`[Request] 响应体过大 (${contentLength} bytes > ${maxResponseBytes}): ${url}`);
-        return null;
+      if (!res.ok) {
+        return { success: false, error: `HTTP ${res.status} ${res.statusText}` };
       }
 
-      // 流式读取时累计字节数，超过上限中止
-      const reader = response.body?.getReader();
-      if (reader) {
-        const chunks = [];
-        let totalSize = 0;
-        let done = false;
-        while (!done) {
-          const { done: rDone, value } = await reader.read();
-          done = rDone;
-          if (value) {
-            totalSize += value.length;
-            if (totalSize > maxResponseBytes) {
-              console.error(`[Request] 流式响应体超过上限 (${totalSize} > ${maxResponseBytes}): ${url}`);
-              await reader.cancel?.();
-              return null;
-            }
-            chunks.push(value);
-          }
+      // 根据 responseType 决定如何读取响应
+      let data;
+      if (responseType === "arraybuffer") {
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.length > maxResponseBytes) {
+          return { success: false, error: `响应超限 ${buf.length} > ${maxResponseBytes}` };
         }
-        const buf = Buffer.concat(chunks);
-        try {
-          return JSON.parse(buf.toString('utf8'));
-        } catch (e) {
-          console.error('[Request] JSON 解析失败:', e.message);
-          return null;
+        data = buf;
+      } else {
+        const text = await res.text();
+        if (text.length > maxResponseBytes) {
+          return { success: false, error: `响应超限 ${text.length} > ${maxResponseBytes}` };
         }
+        data = parseJson ? JSON.parse(text) : text;
       }
 
-      // 无 body 流的兜底（理论上极少走到）
-      const data = await response.json();
-      return data;
-    } catch (error) {
-      if (error.name === 'AbortError') {
-        console.error(`[Request] 请求超时 (${timeout}ms): ${url}`);
-      } else {
-        console.error(`[Request] 请求失败 (attempt ${attempt + 1}/${retry + 1}):`, error.message);
-      }
-      lastError = error;
-      // 仅网络错误重试，超时不重试（避免雪崩）
-      if (error.name === 'AbortError') break;
-    } finally {
+      return { success: true, data };
+    } catch (err) {
       if (timer) clearTimeout(timer);
+
+      if (err.name === "AbortError") {
+        return { success: false, error: `请求超时 ${timeout}ms` };
+      }
+
+      if (attempt < retry) {
+        logger.warn(`[Request] 第${attempt + 1}次请求失败，剩余重试${retry - attempt}次 msg:${err.message}`);
+        continue;
+      }
+
+      return { success: false, error: err.message };
     }
   }
 
-  return null;
+  return { success: false, error: "请求失败" };
 }

package/utils/signal.js

@@ -0,0 +1,87 @@
+import logger from "./logger.js";
+import { store } from "../storage/index.js";
+import { setApp } from "../core/registry.js";
+import { SHUTDOWN_TIMEOUT } from "../config/index.js";
+
+/**
+ * 优雅停机：统一处理进程信号监听、资源关闭、超时保护
+ * 模块级状态，进程内单例
+ */
+let registered = false;
+let shuttingDown = false;
+
+/** 关闭 HTTP 服务、缓存存储、数据库连接 */
+async function doShutdown(chan) {
+  const { dbManager, server } = chan;
+
+  if (server) {
+    try {
+      await new Promise((resolve, reject) => server.close(err => (err ? reject(err) : resolve())));
+      logger.info("[Chan] HTTP服务已停止接受新连接");
+    } catch (e) {
+      logger.warn(`[Chan] 关闭HTTP服务异常：${e.message}`);
+    }
+  }
+
+  const errors = [];
+
+  try { await store.close(); }
+  catch (e) { errors.push({ type: "store", err: e.message }); }
+
+  if (dbManager) {
+    const results = await dbManager.closeAll();
+    results.filter(item => !item.success).forEach(item => errors.push({ type: `db:${item.name}`, err: item.error }));
+  }
+
+  if (errors.length) logger.warn(`[Chan] 停机存在${errors.length}处资源关闭失败`, errors);
+  setApp(null);
+}
+
+/** 注册进程信号监听 */
+export function register(chan) {
+  if (registered) {
+    logger.warn("[Chan] 优雅停机已注册，跳过重复绑定");
+    return;
+  }
+  registered = true;
+
+  const shutdownTimeout = chan.config?.SHUTDOWN_TIMEOUT ?? SHUTDOWN_TIMEOUT;
+
+  const handleSignal = async (signal) => {
+    if (shuttingDown) {
+      logger.error(`[Chan] 停机中重复接收信号 ${signal}，强制终止`);
+      return process.exit(1);
+    }
+    shuttingDown = true;
+    logger.info(`[Chan] 收到停机信号 ${signal}，开始优雅停机`);
+
+    const exitTimer = setTimeout(() => {
+      logger.error(`[Chan] 停机超时(${shutdownTimeout}ms)，强制退出`);
+      process.exit(1);
+    }, shutdownTimeout);
+
+    try {
+      await doShutdown(chan);
+      logger.info("[Chan] 优雅停机完成");
+      process.exit(0);
+    } catch (err) {
+      logger.error("[Chan] 停机异常", err);
+      process.exit(1);
+    } finally {
+      clearTimeout(exitTimer);
+    }
+  };
+
+  process.on("SIGTERM", () => void handleSignal("SIGTERM"));
+  process.on("SIGINT", () => void handleSignal("SIGINT"));
+  process.on("SIGQUIT", () => void handleSignal("SIGQUIT"));
+}
+
+/** 程序化触发停机（不退出进程） */
+export async function shutdown(chan) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  logger.info("[Chan] 开始程序化停机");
+  await doShutdown(chan);
+  logger.info("[Chan] 程序化停机完成");
+}