mm_os 5.0.2 → 5.0.4

package/lib/os.js

@@ -1,572 +1,855 @@
-const path = require('path');
-const { Mod } = require('mm_mod');
-const { containerAdmin } = require('mm_container');
-const { getLogger } = require('mm_logger');
-const { Loader } = require('mm_loader');
-const { appAdmin } = require('mm_apps');
-const { eventAdmin } = require('mm_event');
-const { Response } = require('mm_response');
-
-/**
- * OS类
- */
-class OS extends Mod {
-  static config = {
-    name: 'os',
-    in_adapters: [{
-      name: 'web',
-      module: 'mm_web_server'
-    }, {
-      name: 'mqtt',
-      module: 'mm_mqtt_server'
-    }, {
-      name: 'socket',
-      module: 'mm_socket_server'
-    }, {
-      name: 'websocket',
-      module: 'mm_websocket_server'
-    }],
-    // 输出适配器
-    out_adapters: [{
-      name: 'redis',
-      module: 'mm_redis'
-    }, {
-      name: 'mongodb',
-      module: 'mm_mongodb'
-    }, {
-      name: 'mysql',
-      module: 'mm_mysql'
-    }, {
-      name: 'sqlite',
-      module: 'mm_sqlite'
-    }, {
-      name: 'jsondb',
-      module: 'mm_jsondb'
-    }, {
-      name: 'file',
-      module: 'mm_files'
-    }],
-    tools: [{
-      name: 'lang',
-      module: 'mm_lang'
-    }, {
-      name: 'tpl',
-      module: 'mm_tpl'
-    }, {
-      name: 'ret',
-      module: 'mm_ret'
-    }],
-    admins: [{
-      name: 'event',
-      module: 'mm_event'
-    }, {
-      name: 'api',
-      module: 'mm_api'
-    }, {
-      name: 'param',
-      module: 'mm_param'
-    }, {
-      name: 'dao',
-      module: 'mm_dao'
-    }, {
-      name: 'service',
-      module: 'mm_service'
-    }, {
-      name: 'template',
-      module: 'mm_template'
-    }, {
-      name: 'pendant',
-      module: 'mm_pendant'
-    }, {
-      name: 'timer',
-      module: 'mm_timer'
-    }, {
-      name: 'static',
-      module: 'mm_statics'
-    }],
-    cache: {
-      type: 'redis'
-    },
-    sql: {
-      type: 'mysql'
-    },
-    web: {
-      port: 8000
-    },
-    mqtt: {
-      port: 1883
-    },
-    socket: {
-      port: 9000
-    },
-    websocket: {
-      port: 9001
-    },
-    jsondb: {
-      dir: './data'
-    },
-    mysql: {
-      host: '127.0.0.1',
-      port: 3306,
-      user: 'root',
-      password: 'Asd159357',
-      database: 'mm'
-    },
-    redis: {
-      host: '127.0.0.1',
-      password: 'asd159357',
-      port: 6379,
-      db: 0
-    },
-    mongodb: {
-      host: '127.0.0.1',
-      port: 27017,
-      user: 'root',
-      password: 'asd123',
-      database: 'mm'
-    },
-    sqlite: {
-      dir: './db',
-      database: 'mm',
-      user: 'root',
-      password: 'asd123'
-    },
-    ret: {
-      type: 'json-rpc'
-    },
-    lang: {
-      type: 'zh_cn'
-    },
-    tpl: {
-      dir: './static/template',
-      ext: '.html'
-    },
-    loader: {
-      dir: ''
-    }
-  }
-
-  /**
-   * OS类构造函数
-   * @param {object} config 配置对象
-   */
-  constructor(config) {
-    super(config);
-    /**
-     * 实例容器（按作用域共享）
-     * @type {object}
-     */
-    this.container = containerAdmin('os', { name: 'os' });
-    this.container.server = this;
-    /**
-     * 初始化阶段创建的全局管理器列表
-     * @type {Array<object>}
-     */
-    this._admin_managers = [];
-    /**
-     * 已启动的全局管理器集合，避免重复启动
-     * @type {Set<object>}
-     */
-    this._started_admins = new Set();
-  }
-
-  /**
-   * 生命周期初始化钩子
-   * @returns {void} 无返回值
-   */
-  async onInit() {
-    this.initConfig();
-    this.initLogger();
-    // 初始化事件总线
-    this.initEventBus();
-    // 存储需先于管理器初始化：mm_dao 等管理器会通过 mm_sql 的 getSql() 复用同名 SQL 实例，
-    // 若管理器先创建，则会以默认（空库名）配置占用实例，导致后续 SQL 报 No database selected
-    await this.initpStorage();
-    await this.initAdmins();
-    await this.initAdapter();
-    await this.initLoader();
-  }
-}
-
-/**
- * 初始化配置管理器
- */
-OS.prototype.initConfig = function () {
-  const { admin } = require('mm_config');
-  admin.setServer(this);
-  admin.get('os', this.config);
-  admin.get('cache', { ...this.config.cache, redis: this.config.redis, mongodb: this.config.mongodb });
-  admin.get('sql', { ...this.config.sql, mysql: this.config.mysql, sqlite: this.config.sqlite, jsondb: this.config.jsondb });
-  admin.get('web', this.config.web);
-  admin.get('mqtt', this.config.mqtt);
-  admin.get('socket', this.config.socket);
-  admin.get('websocket', this.config.websocket);
-  admin.get('jsondb', this.config.jsondb);  
-  admin.get('redis', this.config.redis);
-  admin.get('mongodb', this.config.mongodb);
-  admin.get('sqlite', this.config.sqlite);
-  admin.get('mysql', this.config.mysql);
-  admin.get('ret', this.config.ret);
-  admin.get('lang', this.config.lang);
-  admin.get('tpl', this.config.tpl);
-  admin.get('loader', this.config.loader);
-  this.reg('config', admin);
-};
-
-/**
- * 初始化日志记录器
- */
-OS.prototype.initLogger = function () {
-  this.reg('logger', getLogger(this.config.log || { level: 'info' }));
-};
-
-/**
- * 记录日志
- * @param {string} type 日志类型
- * @param {string} msg 日志消息
- * @param {...*} args 日志参数
- */
-OS.prototype.log = function (type, msg, ...args) {
-  this.container.get('logger')[type](msg, ...args);
-};
-
-/**
- * 注册管理
- * @param {string} name 管理名称
- * @param {object} admin 管理对象
- */
-OS.prototype.reg = function (name, admin) {
-  this.container.set(name, admin);
-};
-
-/**
- * 加载模块
- * @param {string} mod_name 模块名称
- * @returns {object} 模块对象
- */
-OS.prototype.require = function (mod_name) {
-  return require(mod_name);
-};
-
-/**
- * 初始化适配器
- * @returns {void} 无返回值
- */
-OS.prototype.initAdapter = async function () {
-  // 入站适配器
-  let adapters = this.config.in_adapters || [];
-  for (let mod of adapters) {
-    try {
-      let admin = this.require(mod.module).admin;
-      admin.setServer(this);
-      let manager = admin.get('os', this.config[mod.name]);
-      if (typeof manager.init === 'function') {
-        await manager.init();
-      }
-      this.reg(mod.name, manager);
-    } catch (error) {
-      this.log('error', `初始化适配器 ${mod.name} 失败: ${error}`);
-    }
-  }
-
-  // 出站适配器
-  let out_adapters = this.config.out_adapters || [];
-  for (let mod of out_adapters) {
-    try {
-      let admin = this.require(mod.module).admin;
-      admin.setServer(this);
-      let manager = admin.get('os', this.config[mod.name]);
-      if (typeof manager.init === 'function') {
-        await manager.init();
-      }
-      this.reg(mod.name, manager);
-    } catch (error) {
-      this.log('error', `初始化适配器 ${mod.name} 失败: ${error}`);
-    }
-  }
-};
-
-/**
- * 初始化工具
- * @returns {void} 无返回值
- */
-OS.prototype.initTools = async function () {
-  let tools = this.config.tools || [];
-  for (let mod of tools) {
-    try {
-      let admin = this.require(mod.module).admin;
-      admin.setServer(this);
-      let manager = admin.get('os', this.config[mod.name]);
-      if (typeof manager.init === 'function') {
-        await manager.init();
-      }
-      this.reg(mod.name, manager);
-    } catch (error) {
-      this.log('error', `初始化工具 ${mod.name} 失败: ${error}`);
-    }
-  }
-};
-
-/**
- * 初始化管理
- * @returns {void} 无返回值
- */
-OS.prototype.initAdmins = async function () {
-  let admins = this.config.admins || [];
-  for (let mod of admins) {
-    try {
-      let admin = this.require(mod.module).admin;
-      admin.setServer(this);
-      let manager = admin.get('os', this.config[mod.name]);
-      if (typeof manager.init === 'function') {
-        await manager.init();
-      }
-      this.reg(mod.name, manager);
-      this._admin_managers.push(manager);
-    } catch (error) {
-      this.log('error', `初始化管理 ${mod.name} 失败: ${error}`);
-    }
-  }
-};
-
-/**
- * 初始化存储
- * @returns {void} 无返回值
- */
-OS.prototype.initpStorage = async function () {
-  // 初始化缓存存储
-  let cacheAdmin = this.require('mm_cache').admin;
-  this._setAdminServer(cacheAdmin);
-  let cache = cacheAdmin.get('os', Object.assign({}, this.config.cache, { redis: this.config.redis, mongodb: this.config.mongodb, cachebase: this.config.cachebase }));
-  if (typeof cache.init === 'function') {
-    await cache.init();
-  }
-  this.reg('cache', cache);
-
-  // 初始化数据库
-  let sqlAdmin = this.require('mm_sql').admin;
-  this._setAdminServer(sqlAdmin);
-  let sql = sqlAdmin.get('os', Object.assign({}, this.config.sql, { mysql: this.config.mysql, sqlite: this.config.sqlite, jsondb: this.config.jsondb }));
-  if (typeof sql.init === 'function') {
-    await sql.init();
-  }
-  this.reg('sql', sql);
-};
-
-/**
- * 设置管理器服务器：已设置时跳过，避免同一 Admin 实例重复绑定
- * @param {object} admin 管理器工厂实例
- */
-OS.prototype._setAdminServer = function (admin) {
-  if (!admin.getServer()) {
-    admin.setServer(this);
-  }
-};
-
-/**
- * 初始化应用加载器（协调层：只创建加载器与应用管理器，装配逻辑在 mm_apps/mm_plugins）
- * @returns {void} 无返回值
- */
-OS.prototype.initLoader = async function () {
-  // 配置加载器：注入 socket/mqtt 类型，其余类型由 mm_loader 默认提供
-  const loader = new Loader(this.config.loader || {});
-  loader.addType('socket', 'socket.json');
-  loader.addType('mqtt', 'mqtt.json');
-  this.reg('loader', loader);
-
-  // 应用管理器：装配应用由 AppManager.load 负责，插件随 App.onInit 引入
-  const app = appAdmin('os');
-  app.setServer(this);
-  app.setLogger(this.container.get('logger'));
-  this.reg('app', app);
-
-  const dir = this.config.loader.dir || path.join(__dirname, '..', 'example', 'app');
-  await app.load(dir, loader);
-  await app.init();
-
-  // 注入 Web 请求路由
-  this._initWeb();
-};
-
-/**
- * 初始化 Web 适配器：注入跨作用域事件路由与响应写出器
- * @returns {void} 无返回值
- */
-OS.prototype._initWeb = function () {
-  const web = this.container.get('web');
-  if (!web) return;
-  web.setEventManager(this._createEventRouter());
-  new Response().bind(web);
-};
-
-/**
- * 创建跨作用域事件路由：Web 适配器只持有 web 作用域，需转发到各应用作用域
- * @returns {object} 含 run 方法的事件管理器
- */
-OS.prototype._createEventRouter = function () {
-  return {
-    run: (target, params, ctx, options) => this._routeRequest(target, params, ctx, options)
-  };
-};
-
-/**
- * 路由请求：先尝试静态资源，未命中再按应用顺序执行事件
- * @param {string} target 请求路径
- * @param {object} params 请求参数
- * @param {object} ctx 请求上下文
- * @param {object} options 事件运行选项
- * @returns {Promise<*>} 事件执行结果
- */
-OS.prototype._routeRequest = async function (target, params, ctx, options = {}) {
-  const statics = this.container.get('static');
-  if (statics && typeof statics.run === 'function') {
-    // 静态模块为服务式调用：命中即返回 true 并已写出响应，未命中返回 false 继续后续事件
-    const served = await statics.run(params, ctx, options);
-    if (served) {
-      return undefined;
-    }
-  }
-  return await this._runAppEvents(target, params, ctx, options);
-};
-
-/**
- * 按应用排序依次执行事件：命中结果、响应已写出或发生错误时中止
- * @param {string} target 请求路径
- * @param {object} params 请求参数
- * @param {object} ctx 请求上下文
- * @param {object} options 事件运行选项
- * @returns {Promise<*>} 事件执行结果
- */
-OS.prototype._runAppEvents = async function (target, params, ctx, options = {}) {
-  const app = this.container.get('app');
-  if (!app || typeof app.list !== 'function') return undefined;
-
-  const apps = app.list().slice().sort((a, b) => this._getSort(a) - this._getSort(b));
-  for (const item of apps) {
-    if (this._isRequestHandled(ctx) || ctx.error) return undefined;
-    const name = item.config && item.config.name;
-    if (!name) continue;
-    const app_options = {};
-    const result = await eventAdmin(name).run(target, params, ctx, app_options);
-    if (app_options.error) {
-      ctx.error = ctx.error || app_options.error;
-      options.error = options.error || app_options.error;
-      return undefined;
-    }
-    if (result !== undefined && result !== null) return result;
-  }
-  return undefined;
-};
-
-/**
- * 判断请求是否已处理完毕：事件或中间件已写出响应
- * @param {object} ctx 请求上下文
- * @returns {boolean} 响应是否已写出
- */
-OS.prototype._isRequestHandled = function (ctx) {
-  if (!ctx) return false;
-  if (ctx.handled === true) return true;
-  const res = ctx.res;
-  return !!(res && (res.writableEnded || res.headersSent));
-};
-
-/**
- * 获取应用执行顺序
- * @param {object} app 应用驱动实例
- * @returns {number} 排序值，缺省 100
- */
-OS.prototype._getSort = function (app) {
-  const sort = app && app.config ? app.config.sort : undefined;
-  return typeof sort === 'number' ? sort : 100;
-};
-
-/**
- * 初始化事件总线
- * @returns {void} 无返回值
- */
-OS.prototype.initEventBus = function () {
-  let admin = this.require('mm_eventer').admin;
-  admin.setServer(this);
-  this.reg('eventer', admin.get('os'));
-};
-
-/**
- * 启动适配器：按配置中的入站、出站适配器名称从容器取出管理器并启动
- * @returns {void} 无返回值
- */
-OS.prototype._startAdapters = async function () {
-  let mods = this.config.in_adapters;
-  for (let mod of mods) {
-    let manager = this.container.get(mod.name);
-    if (!manager || typeof manager.start !== 'function') continue;
-    try {
-      await manager.start();
-      this._printAddress(mod.name, manager);
-    } catch (error) {
-      this.log('error', `启动适配器 ${mod.name} 失败: ${error}`);
-    }
-  }
-};
-
-/**
- * 启动初始化阶段创建的全局管理器
- * 仅启动一次，避免重复执行管理器生命周期
- * @returns {void} 无返回值
- */
-OS.prototype._startAdmins = async function () {
-  let managers = this._admin_managers || [];
-  for (let manager of managers) {
-    if (!manager || typeof manager.start !== 'function') continue;
-    if (this._started_admins.has(manager)) continue;
-    try {
-      await manager.start();
-      this._started_admins.add(manager);
-    } catch (error) {
-      let name = manager.config && manager.config.name;
-      this.log('error', `启动管理 ${name} 失败: ${error}`);
-    }
-  }
-};
-
-/**
- * 启动
- * @returns {void} 无返回值
- */
-OS.prototype.start = async function () {
-  // 启动适配器
-  await this._startAdapters();
-
-  // 启动缓存存储
-  await this.container.get('cache').start();
-  // 启动数据库
-  await this.container.get('sql').start();
-
-  // 启动应用
-  const app = this.container.get('app');
-  if (app) {
-    await app.start();
-  }
-
-  // 启动初始化阶段创建的全局管理器（含 os 作用域静态资源）
-  await this._startAdmins();
-};
-
-/**
- * 打印适配器监听地址
- * @param {string} name 适配器名称
- * @param {object} manager 适配器管理器实例
- */
-OS.prototype._printAddress = function (name, manager) {
-  let { host, port } = manager.config || {};
-  if (!host || host === '0.0.0.0' || host === '::') {
-    host = 'localhost';
-  }
-  let protocol = { web: 'http', websocket: 'ws', socket: 'tcp', mqtt: 'mqtt' }[name] || name;
-  let address = `${protocol}://${host}`;
-  if (port) {
-    address += `:${port}`;
-  }
-  this.log('info', `适配器 ${name} 已启动: ${address}`);
-};
-
+const path = require('path');
+const { createRequire } = require('module');
+const { Mod } = require('mm_mod');
+const { containerAdmin } = require('mm_container');
+const { getLogger } = require('mm_logger');
+const { Loader } = require('mm_loader');
+const { appAdmin } = require('mm_apps');
+const os_config = require('./config');
+const pkg = require('../package.json');
+
+/**
+ * 实例序号：容器默认按实例隔离（见构造函数），序号保证同一进程内唯一
+ * @type {number}
+ */
+let os_seq = 0;
+
+/**
+ * 需要按 root 解析为绝对路径的配置项（相对路径一律相对 config.root）
+ * @type {Array<Array<string>>}
+ */
+const ROOT_PATHS = [
+  ['jsondb', 'dir'],
+  ['sqlite', 'dir'],
+  ['tpl', 'dir'],
+  ['log', 'dir']
+];
+
+/**
+ * OS类
+ * 系统只负责加载：装载默认配置、初始化各管理器与适配器、加载应用；
+ * 默认配置见 lib/config.js；mm_mqtt 等资源模块由应用管理器按资源清单（mqtt.json 等）
+ * 统一装配，宿主服务由模块自身从服务器实例解析；
+ * Web 请求到事件钩子的调用由适配器 mm_web_server 自身完成
+ */
+class OS extends Mod {
+  static config = os_config;
+
+  /**
+   * OS类构造函数
+   * @param {object} config 配置对象
+   */
+  constructor(config) {
+    super(config);
+    // 容器默认按实例隔离：历史实现按固定字符串 'os' 取单例，
+    // 同进程起第二个 OS（集成测试、双环境共存）时后建实例会覆盖先建实例
+    // 的 server 与全部注册项，故障现象是「A 实例在用 B 实例的库」。
+    // 默认隔离、显式共享：需要共用容器时传入 config.container_scope
+    const scope = this.config.container_scope || `${this.config.name || 'os'}#${++os_seq}`;
+    /**
+     * 实例容器（默认按实例隔离，config.container_scope 可显式共享）
+     * @type {object}
+     */
+    this.container = containerAdmin(scope, { name: scope });
+    this.container.server = this;
+    /**
+     * 管理器作用域：app / static / event / 适配器管理器的注册表命名空间
+     *
+     * 默认 'os' 是历史约定的兼容值——应用层（事件钩子、插件）通过
+     * `appAdmin('os')` 取应用集合，改成实例唯一值会让这些调用全部取空。
+     * 多实例共存时显式配置 `scope`，该值会随之贯穿全链路：
+     * 内核用它建管理器、注入入站适配器配置，适配器再经 `ctx.app_scope`
+     * 下发给事件钩子，应用层据此取到本实例的管理器。
+     * @type {string}
+     */
+    this.scope = this.config.scope || 'os';
+    /**
+     * 初始化阶段创建的全局管理器列表
+     * @type {Array<object>}
+     */
+    this._admin_managers = [];
+    /**
+     * 已启动的全局管理器集合，避免重复启动
+     * @type {Set<object>}
+     */
+    this._started_admins = new Set();
+  }
+
+  /**
+   * 生命周期初始化钩子
+   * @returns {void} 无返回值
+   */
+  async onInit() {
+    // 路径锚定必须先于配置装载：之后所有模块读到的都是绝对路径
+    this._resolveRoot();
+    this.initConfig();
+    this.initLogger();
+    // 对已废弃配置输出告警（out_adapters / tools，见 README）
+    this._warnDeprecated();
+    // 初始化事件总线
+    this.initEventBus();
+    // 初始化模块通道：先于清单装配，清单模块可经通道 cwd 解析（模块可装在宿主目录）
+    await this.initModuleChannel();
+    // 存储需先于管理器初始化：mm_dao 等管理器会通过 mm_sql 的 getSql() 复用同名 SQL 实例，
+    // 若管理器先创建，则会以默认（空库名）配置占用实例，导致后续 SQL 报 No database selected
+    await this.initpStorage();
+    await this.initAdmins();
+    await this.initDaos();
+    await this.initAdapter();
+    await this.initLoader();
+  }
+}
+
+/**
+ * 对已废弃配置输出一次告警（对齐 README：out_adapters 与 tools 已废弃并忽略）
+ * @returns {void} 无返回值
+ */
+OS.prototype._warnDeprecated = function () {
+  const deprecated = [];
+  if (this.config.out_adapters !== undefined) {
+    deprecated.push('out_adapters');
+  }
+  if (this.config.tools !== undefined) {
+    deprecated.push('tools');
+  }
+  if (!deprecated.length) {
+    return;
+  }
+  this.log('warn', `配置项 ${deprecated.join('、')} 已废弃：存储统一走 cache / sql，语言与模板由各模块自行初始化，本次启动将忽略`);
+};
+
+/**
+ * 路径锚定：把所有相对路径配置解析为相对 config.root 的绝对路径
+ * 历史实现里 jsondb/sqlite/tpl/loader 的目录都按 process.cwd 解析，
+ * 于是 systemd 工作目录、PM2 工作目录、IDE 启动各不相同，插件写文件失败却只打一行日志继续跑。
+ * 现在统一以 config.root（默认 process.cwd，宿主可覆盖）为基准，启动目录不再影响行为。
+ * @returns {void} 无返回值
+ */
+OS.prototype._resolveRoot = function () {
+  const root = path.resolve(this.config.root || process.cwd());
+  this.config.root = root;
+  const resolveItem = (item) => {
+    if (item && typeof item.dir === 'string' && item.dir && !path.isAbsolute(item.dir)) {
+      item.dir = path.resolve(root, item.dir);
+    }
+  };
+  for (const [group] of ROOT_PATHS) {
+    resolveItem(this.config[group]);
+  }
+  // 各数据域的 SQLite 目录（如 dao_org 按机构分库）
+  for (const key of Object.keys(this.config)) {
+    if (key.indexOf('dao_') !== 0) continue;
+    const conf = this.config[key];
+    if (conf && conf.sql) {
+      resolveItem(conf.sql.sqlite);
+    }
+  }
+};
+
+/**
+ * 初始化配置管理器
+ */
+OS.prototype.initConfig = function () {
+  const { admin } = require('mm_config');
+  admin.setServer(this);
+  admin.get('os', this.config);
+  admin.get('cache', { ...this.config.cache, redis: this.config.redis, mongodb: this.config.mongodb });
+  admin.get('sql', { ...this.config.sql, mysql: this.config.mysql, sqlite: this.config.sqlite, jsondb: this.config.jsondb });
+  admin.get('web', this.config.web);
+  admin.get('mqtt', this.config.mqtt);
+  admin.get('socket', this.config.socket);
+  admin.get('websocket', this.config.websocket);
+  admin.get('jsondb', this.config.jsondb);  
+  admin.get('redis', this.config.redis);
+  admin.get('mongodb', this.config.mongodb);
+  admin.get('sqlite', this.config.sqlite);
+  admin.get('mysql', this.config.mysql);
+  admin.get('ret', this.config.ret);
+  admin.get('lang', this.config.lang);
+  admin.get('tpl', this.config.tpl);
+  admin.get('loader', this.config.loader);
+  this.reg('config', admin);
+};
+
+/**
+ * 初始化日志记录器
+ */
+OS.prototype.initLogger = function () {
+  this.reg('logger', getLogger(this.config.log || { level: 'info' }));
+};
+
+/**
+ * 记录日志
+ * @param {string} type 日志类型
+ * @param {string} msg 日志消息
+ * @param {...*} args 日志参数
+ */
+OS.prototype.log = function (type, msg, ...args) {
+  this.container.get('logger')[type](msg, ...args);
+};
+
+/**
+ * 注册管理
+ * @param {string} name 管理名称
+ * @param {object} admin 管理对象
+ */
+OS.prototype.reg = function (name, admin) {
+  this.container.set(name, admin);
+};
+
+/**
+ * 加载模块
+ * @param {string} mod_name 模块名称
+ * @returns {object} 模块对象
+ */
+OS.prototype.require = function (mod_name) {
+  return require(mod_name);
+};
+
+/**
+ * 解析清单模块：模块通道启用时优先按通道 cwd 解析（模块可安装在宿主目录
+ * 而非 mm_os 包内，见 D-17），失败时回退默认 require（兼容既有装配与测试桩）。
+ * 回退只针对「通道目录解析不到该模块」；模块已解析但加载失败（如自身依赖缺失）
+ * 必须原样上抛——否则回退到默认路径会得到误导性的「模块未安装」错误
+ * @param {string} mod_name 模块名称
+ * @returns {object} 模块对象
+ */
+OS.prototype._requireModule = function (mod_name) {
+  const channel = this._module_channel;
+  const cwd = channel && channel.config && channel.config.cwd;
+  if (cwd) {
+    const req = createRequire(path.join(cwd, 'package.json'));
+    try {
+      // 先 resolve 不执行：区分「找不到模块」与「模块加载失败」
+      req.resolve(mod_name);
+      return req(mod_name);
+    } catch (error) {
+      if (!(error.code === 'MODULE_NOT_FOUND' && String(error.message).includes(`'${mod_name}'`))) {
+        throw error;
+      }
+      // 通道目录解析不到时回退默认路径
+    }
+  }
+  return this.require(mod_name);
+};
+
+/**
+ * 初始化模块通道（可选，基于 mm_module）
+ * 通道只负责「包」的生命周期：本地清单、npm 安装/卸载/升级、require 缓存管理；
+ * 管理器实例的装配与启停仍由 OS 按清单驱动（moduleAssemble / moduleDisassemble）。
+ * 通道是增强能力：未安装 mm_module 或初始化失败时降级为纯静态装配，不阻断启动
+ * @returns {Promise<void>} 无返回值
+ */
+OS.prototype.initModuleChannel = async function () {
+  const conf = this.config.modules;
+  if (conf === false) {
+    return;
+  }
+  let mod;
+  try {
+    mod = require('mm_module');
+  } catch (error) {
+    this.log('info', '未安装 mm_module，动态模块通道停用（npm install mm_module 启用）');
+    return;
+  }
+  const cfg = Object.assign(
+    { cwd: this.config.root },
+    conf && typeof conf === 'object' ? conf : {}
+  );
+  try {
+    const channel = new mod.ModuleManager(cfg, this);
+    await channel.init();
+    await channel.start();
+    this._module_channel = channel;
+    this.reg('module', channel);
+  } catch (error) {
+    this.log('error', `模块通道初始化失败，已降级为静态装配: ${error.message || error}`, error);
+  }
+};
+
+/**
+ * 收集引用某模块的清单角色（admins / in_adapters 条目）
+ * @param {string} module_name 模块名
+ * @returns {Array<object>} 角色列表，元素含 kind（管理/适配器）与清单条目字段
+ */
+OS.prototype._rolesOf = function (module_name) {
+  const roles = [];
+  for (const m of this.config.admins || []) {
+    if (m && m.module === module_name) {
+      roles.push(Object.assign({ kind: '管理' }, m));
+    }
+  }
+  for (const m of this.config.in_adapters || []) {
+    if (m && m.module === module_name) {
+      roles.push(Object.assign({ kind: '适配器' }, m));
+    }
+  }
+  return roles;
+};
+
+/**
+ * 装配某模块承担的全部角色：按清单段初始化管理器、注册容器并注入作用域/探针；
+ * OS 已处于运行态时（运行期热装）新管理器立即启动
+ * @param {string} module_name 模块名
+ * @returns {Promise<Array<object>>} 本次新创建的管理器列表
+ */
+OS.prototype.moduleAssemble = async function (module_name) {
+  const roles = this._rolesOf(module_name);
+  if (!roles.length) {
+    return [];
+  }
+  const created = [];
+  const before = new Set(this._admin_managers);
+  await this._initModules(roles.filter((r) => r.kind === '管理'), '管理', true);
+  await this._initModules(roles.filter((r) => r.kind === '适配器'), '适配器', false);
+  this._injectAppScope();
+  for (const role of roles) {
+    if (role.kind !== '适配器') continue;
+    const manager = this.container.get(role.name);
+    if (manager) {
+      this._injectProbe(manager);
+    }
+  }
+  for (const manager of this._admin_managers) {
+    if (!before.has(manager)) {
+      created.push(manager);
+    }
+  }
+  if (this._started) {
+    for (const manager of created) {
+      if (typeof manager.start === 'function') {
+        await manager.start();
+      }
+    }
+  }
+  return created;
+};
+
+/**
+ * 拆除某模块承担的全部角色：逆序停止管理器、移出启动列表并摘除容器注册项
+ * @param {string} module_name 模块名
+ * @returns {Promise<Array<string>>} 已拆除的注册名列表
+ */
+OS.prototype.moduleDisassemble = async function (module_name) {
+  const roles = this._rolesOf(module_name).reverse();
+  const removed = [];
+  for (const role of roles) {
+    const manager = this.container.get(role.name);
+    if (!manager) {
+      continue;
+    }
+    if (typeof manager.stop === 'function') {
+      try {
+        await manager.stop();
+      } catch (error) {
+        this.log('error', `停止${role.kind} ${role.name} 失败: ${error.message || error}`, error);
+      }
+    }
+    this._admin_managers = this._admin_managers.filter((m) => m !== manager);
+    this._started_admins.delete(manager);
+    this.container.del(role.name);
+    this.container.del(role.name + '_admin');
+    removed.push(role.name);
+  }
+  return removed;
+};
+
+/**
+ * 动态安装模块：经模块通道 npm 安装 → 装配其清单角色；
+ * OS 运行中时新管理器直接启动。通道登记为幂等，保证后续卸载必清 require 缓存
+ * @param {string} name 模块名
+ * @param {object} [options] 安装选项（透传 ModuleManager.install：force/version/load）
+ * @returns {Promise<Array<object>>} 新装配的管理器列表
+ */
+OS.prototype.moduleInstall = async function (name, options = {}) {
+  const channel = this._module_channel;
+  if (!channel) {
+    throw new Error('模块通道未启用（安装 mm_module 并确认 config.modules 未关闭）');
+  }
+  await channel.install(name, Object.assign({ load: false }, options));
+  const created = await this.moduleAssemble(name);
+  if (!channel.has(name)) {
+    await channel.load([name]);
+  }
+  return created;
+};
+
+/**
+ * 动态卸载模块：先拆除其管理器（stop + 摘注册），再经通道卸载包并清理 require 缓存
+ * @param {string} name 模块名
+ * @returns {Promise<Array<string>>} 已拆除的注册名列表
+ */
+OS.prototype.moduleUnload = async function (name) {
+  const channel = this._module_channel;
+  if (!channel) {
+    throw new Error('模块通道未启用（安装 mm_module 并确认 config.modules 未关闭）');
+  }
+  const removed = await this.moduleDisassemble(name);
+  // init 阶段的静态装配不经过通道登记：补登记以挂上 disposer，
+  // 否则 unload 不清 require 缓存，随后的 reload 会命中旧代码
+  if (!channel.has(name)) {
+    try {
+      await channel.load([name]);
+    } catch (error) {
+      this.log('warn', `模块 ${name} 通道登记失败，按普通卸载处理: ${error.message || error}`);
+    }
+  }
+  await channel.unload(name);
+  return removed;
+};
+
+/**
+ * 热更新模块：卸载（停管理器 + 清 require 缓存）→ 重新 require → 重新装配。
+ * 边界：清缓存只保证「下次 require 拿到新代码」；跨模块单例（configAdmin、
+ * 静态 Admin 注册表、getLogger）不在清理范围；持连接/端口的旧对象以 stop 释放
+ * @param {string} name 模块名
+ * @returns {Promise<Array<object>>} 重装配后的管理器列表
+ */
+OS.prototype.moduleReload = async function (name) {
+  await this.moduleUnload(name);
+  const channel = this._module_channel;
+  await channel.load([name]);
+  return this.moduleAssemble(name);
+};
+
+/**
+ * 按清单初始化模块：加载模块 → 绑定服务器 → 取管理器 → 初始化 → 注册
+ * @param {Array<object>} list 模块清单，元素形如 { name, module, scope }
+ * @param {string} label 日志标签（适配器 / 管理）
+ * @param {boolean} collect 是否计入生命周期启动列表
+ * @returns {Promise<void>} 无返回值
+ */
+OS.prototype._initModules = async function (list, label, collect) {
+  for (let mod of list || []) {
+    // 解析模块：required（默认 true）缺失即 fail-fast 并给出安装指引；
+    // required: false 的可选角色缺失时降级跳过，不阻断启动
+    let mod_obj;
+    try {
+      mod_obj = this._requireModule(mod.module);
+    } catch (error) {
+      const missing = error.code === 'MODULE_NOT_FOUND' && String(error.message).includes(`'${mod.module}'`);
+      if (!missing) {
+        throw error;
+      }
+      if (mod.required === false) {
+        this.log('info', `跳过可选${label} ${mod.name}（${mod.module} 未安装；需要时 npm install ${mod.module} 或 os.moduleInstall('${mod.module}')）`);
+        continue;
+      }
+      throw new Error(
+        `装配失败：${label} ${mod.name} 的模块 ${mod.module} 未安装。` +
+        `安装：npm install ${mod.module}，或运行期 await os.moduleInstall('${mod.module}')；` +
+        `若该角色可选，清单条目加 required: false 跳过`
+      );
+    }
+    try {
+      let admin = mod_obj.admin;
+      this._setAdminServer(admin);
+      let manager = admin.get(mod.scope || this.scope, this.config[mod.name]);
+      if (typeof manager.init === 'function') {
+        await manager.init();
+      }
+      this.reg(mod.name, manager);
+      // 暴露管理器工厂：供 mm_nav、mm_dbs 等模块按作用域解析宿主管理器（如 api_admin）
+      this.reg(mod.name + '_admin', admin);
+      if (collect) {
+        this._admin_managers.push(manager);
+      }
+    } catch (error) {
+      // 第二参传 Error：日志器会完整输出 stack，否则只剩一行 message，50 依赖下无法定位
+      this.log('error', `初始化${label} ${mod.name} 失败: ${error.message || error}`, error);
+    }
+  }
+};
+
+/**
+ * 初始化入站适配器
+ * @returns {void} 无返回值
+ */
+OS.prototype.initAdapter = async function () {
+  await this._initModules(this.config.in_adapters, '适配器', false);
+  this._injectAppScope();
+};
+
+/**
+ * 把实例的管理器作用域下发给入站适配器
+ * 适配器不认识 OS、也不需要认识：它只是把配置里的 app_scope 原样放进 ctx，
+ * 事件钩子据此取到本实例的 appAdmin，而不是撞上进程里另一个实例的注册表
+ * @returns {void} 无返回值
+ */
+OS.prototype._injectAppScope = function () {
+  for (const mod of this.config.in_adapters || []) {
+    const manager = this.container.get(mod.name);
+    if (manager && manager.config && manager.config.app_scope === undefined) {
+      manager.config.app_scope = this.scope;
+    }
+  }
+};
+
+/**
+ * 初始化管理
+ * @returns {void} 无返回值
+ */
+OS.prototype.initAdmins = async function () {
+  await this._initModules(this.config.admins, '管理', true);
+};
+
+/**
+ * 初始化数据域
+ * DAO 层按域组织，域清单由宿主声明（config.daos），此处提前建好各域管理器，
+ * 业务侧直接按域取用；os 域已由 initAdmins 装配，不重复初始化。
+ * DAO 模块经 admins 清单解析（name === 'dao' 的条目），内核不硬编码模块名，
+ * 宿主替换或移除清单中的 dao 时，数据域初始化随之变化。
+ * @returns {Promise<void>} 无返回值
+ */
+OS.prototype.initDaos = async function () {
+  const entry = (this.config.admins || []).find((m) => m && m.name === 'dao');
+  if (!entry || !entry.module) {
+    this.log('info', 'admins 清单未包含 dao，跳过数据域初始化');
+    return;
+  }
+  const mod = this.require(entry.module);
+  this._setAdminServer(mod.admin);
+  const ready = ['os'];
+  for (const name of this.config.daos || []) {
+    if (name === 'os') continue;
+    try {
+      const manager = mod.daoAdmin(name, this.config['dao_' + name]);
+      // 模板域（按机构分库）只登记配置，实例在 daoAdmin(域, { org_id }) 时派生
+      if (!manager) {
+        ready.push(name + '(按机构分库)');
+        continue;
+      }
+      if (typeof manager.init === 'function') {
+        await manager.init();
+      }
+      this.reg('dao:' + name, manager);
+      ready.push(name);
+    } catch (error) {
+      this.log('error', `初始化数据域 dao:${name} 失败: ${error.message || error}`, error);
+    }
+  }
+  this.log('info', `数据域已就绪: ${ready.join('、')}`);
+};
+
+
+/**
+ * 初始化存储
+ * @returns {void} 无返回值
+ */
+OS.prototype.initpStorage = async function () {
+  // 初始化缓存存储
+  let cacheAdmin = this.require('mm_cache').admin;
+  this._setAdminServer(cacheAdmin);
+  let cache = cacheAdmin.get('os', Object.assign({}, this.config.cache, { redis: this.config.redis, mongodb: this.config.mongodb, cachebase: this.config.cachebase }));
+  if (typeof cache.init === 'function') {
+    await cache.init();
+  }
+  this.reg('cache', cache);
+
+  // 初始化数据库
+  let sqlAdmin = this.require('mm_sql').admin;
+  this._setAdminServer(sqlAdmin);
+  let sql = sqlAdmin.get('os', Object.assign({}, this.config.sql, { mysql: this.config.mysql, sqlite: this.config.sqlite, jsondb: this.config.jsondb }));
+  if (typeof sql.init === 'function') {
+    await sql.init();
+  }
+  this.reg('sql', sql);
+};
+
+/**
+ * 设置管理器服务器：已设置时跳过，避免同一 Admin 实例重复绑定
+ * @param {object} admin 管理器工厂实例
+ */
+OS.prototype._setAdminServer = function (admin) {
+  if (!admin.getServer()) {
+    admin.setServer(this);
+  }
+};
+
+/**
+ * 初始化应用加载器（协调层：只创建加载器与应用管理器，装配逻辑在 mm_apps/mm_plugins）
+ * @returns {void} 无返回值
+ */
+OS.prototype.initLoader = async function () {
+  const conf = this.config.loader || {};
+  // loader.dir 必填：历史默认回退到包内 example/app，生产环境会静默加载示例应用
+  // （或者加载一个不存在的空目录），故障表现为「服务起来了但没有任何路由」。
+  // 显式传 false 表示本实例不加载应用（纯 API/网关形态）
+  const dir = conf.dir;
+  if (dir === false) {
+    this.log('info', 'loader.dir=false，跳过应用加载');
+    return;
+  }
+  if (!dir) {
+    throw new Error('未配置 loader.dir：请显式指定应用目录（示例见 example/demo.js）；内核不再回退到包内 example/app');
+  }
+  // 配置加载器：注入 socket/mqtt 类型，其余类型由 mm_loader 默认提供
+  const loader = new Loader(conf);
+  loader.addType('socket', 'socket.json');
+  loader.addType('mqtt', 'mqtt.json');
+  this.reg('loader', loader);
+
+  const app = appAdmin(this.scope);
+  app.setServer(this);
+  app.setLogger(this.container.get('logger'));
+  this.reg('app', app);
+
+  // 路径已由 _resolveRoot 统一锚定 root，绝对路径原样使用
+  await app.load(path.resolve(this.config.root || process.cwd(), dir), loader);
+  await app.init();
+};
+
+/**
+ * 初始化事件总线
+ * @returns {void} 无返回值
+ */
+OS.prototype.initEventBus = function () {
+  let admin = this.require('mm_eventer').admin;
+  admin.setServer(this);
+  this.reg('eventer', admin.get('os'));
+};
+
+/**
+ * 启动适配器：按配置中的入站、出站适配器名称从容器取出管理器并启动
+ * 任一适配器启动失败（含初始化阶段已失败导致管理器缺失）即整体抛错，
+ * 避免「进程存活但端口未监听」的假成功状态（fail-fast，交由宿主决定退出/重启）
+ * @throws {Error} 任一适配器启动失败时抛出，error.causes 携带明细
+ * @returns {Promise<void>} 无返回值
+ */
+OS.prototype._startAdapters = async function () {
+  let mods = this.config.in_adapters;
+  const failed = [];
+  for (let mod of mods) {
+    let manager = this.container.get(mod.name);
+    if (!manager || typeof manager.start !== 'function') {
+      failed.push({ name: mod.name, error: new Error('管理器缺失或不可启动（初始化阶段可能已失败）') });
+      continue;
+    }
+    try {
+      await manager.start();
+      this._printAddress(mod.name, manager);
+      this._injectProbe(manager);
+    } catch (error) {
+      this.log('error', `启动适配器 ${mod.name} 失败: ${error.message || error}`, error);
+      failed.push({ name: mod.name, error });
+    }
+  }
+  if (failed.length) {
+    const names = failed.map((f) => f.name).join('、');
+    const error = new Error(`适配器启动失败: ${names}（端口被占用或配置错误时请检查 config.web / mqtt / socket / websocket）`);
+    error.causes = failed;
+    throw error;
+  }
+};
+
+/**
+ * 启动初始化阶段创建的全局管理器
+ * 仅启动一次，避免重复执行管理器生命周期
+ * @returns {void} 无返回值
+ */
+OS.prototype._startAdmins = async function () {
+  let managers = this._admin_managers || [];
+  for (let manager of managers) {
+    if (!manager || typeof manager.start !== 'function') continue;
+    if (this._started_admins.has(manager)) continue;
+    try {
+      await manager.start();
+      this._started_admins.add(manager);
+    } catch (error) {
+      let name = manager.config && manager.config.name;
+      this.log('error', `启动管理 ${name} 失败: ${error.message || error}`, error);
+    }
+  }
+};
+
+/**
+ * 启动
+ * @throws {Error} 适配器或存储启动失败时抛出
+ * @returns {Promise<void>} 无返回值
+ */
+OS.prototype.start = async function () {
+  // 启动适配器（任一失败即抛错，避免假成功）
+  await this._startAdapters();
+
+  // 启动缓存存储与数据库：初始化失败时容器内无实例，此处必须判空并给出明确原因
+  const cache = this.container.get('cache');
+  const sql = this.container.get('sql');
+  if (!cache || !sql) {
+    throw new Error('缓存或数据库未初始化（initpStorage 阶段失败），无法启动');
+  }
+  await cache.start();
+  await sql.start();
+
+  // 启动应用
+  const app = this.container.get('app');
+  if (app) {
+    await app.start();
+  }
+
+  // 启动初始化阶段创建的全局管理器（含 os 作用域静态资源）
+  await this._startAdmins();
+
+  // 运行态标志：OS.prototype.start 覆盖了基类状态机，不自动推进 state，
+  // 模块通道据此判断「运行期热装的管理器应立即启动」
+  this._started = true;
+};
+
+/**
+ * 是否处于运行态（start 之后、stop 之前）
+ * @returns {boolean} 运行态返回 true
+ */
+OS.prototype.isRunning = function () {
+  return !!this._started;
+};
+
+/**
+ * 停止（生命周期 onStop 钩子，由基类 stop() 调用，状态机会推进到 stopped）
+ * 与 start 逆序：应用 → 全局管理器 → 适配器 → 存储；
+ * 每一步失败仅记录并继续，保证尽量多的资源被释放（连接、WAL、日志缓冲）
+ * @returns {Promise<void>} 无返回值
+ */
+OS.prototype.onStop = async function () {
+  this._started = false;
+  const tryStop = async (label, obj) => {
+    if (!obj || typeof obj.stop !== 'function') {
+      return;
+    }
+    try {
+      await obj.stop();
+    } catch (error) {
+      this.log('error', `停止${label}失败: ${error.message || error}`, error);
+    }
+  };
+
+  // 1. 应用先停：不再产生新业务
+  await tryStop('应用', this.container.get('app'));
+
+  // 2. 全局管理器（定时器、静态资源等）逆序停
+  const managers = [...(this._admin_managers || [])].reverse();
+  for (const manager of managers) {
+    await tryStop('管理', manager);
+  }
+  this._started_admins.clear();
+
+  // 3. 适配器逆序停：关闭监听与存量连接
+  const adapters = [...(this.config.in_adapters || [])].reverse();
+  for (const mod of adapters) {
+    await tryStop('适配器 ' + mod.name, this.container.get(mod.name));
+  }
+
+  // 4. 存储最后停：保证前面的收尾还能落库、刷缓冲
+  await tryStop('缓存存储', this.container.get('cache'));
+  await tryStop('数据库', this.container.get('sql'));
+
+  // 5. 模块通道最后停：逆序触发各模块 disposer（清理 require 缓存）
+  await tryStop('模块通道', this._module_channel);
+};
+
+/**
+ * 标记预热状态：预热期间就绪探针应返回 503，
+ * 让编排层在冷启动渲染完成前不放量（否则第一批用户承担全部冷启动开销）
+ * @param {boolean} warming 是否处于预热中
+ * @returns {void} 无返回值
+ */
+OS.prototype.setWarming = function (warming) {
+  this._warming = !!warming;
+};
+
+/**
+ * 就绪状态快照：所有入站适配器均已启动且不在预热中才算就绪
+ * 供宿主 /readyz 探针、容器编排与发布脚本使用，避免「进程存活但端口未监听」不可见
+ * @returns {Object} { ready: boolean, reason: string, adapters: [{ name, state }] }
+ */
+OS.prototype.getReadiness = function () {
+  const adapters = (this.config.in_adapters || []).map((mod) => {
+    const manager = this.container.get(mod.name);
+    return { name: mod.name, state: manager ? manager.state : 'missing' };
+  });
+  const missing = adapters.filter((a) => a.state === 'missing').map((a) => a.name);
+  const pending = adapters.filter((a) => a.state !== 'started' && a.state !== 'missing')
+    .map((a) => `${a.name}:${a.state}`);
+  const started = adapters.length > 0 && missing.length === 0 && pending.length === 0;
+  const ready = started && !this._warming;
+  let reason = '';
+  if (!adapters.length) {
+    reason = '未配置入站适配器';
+  } else if (missing.length) {
+    reason = `适配器未创建（初始化阶段失败）: ${missing.join('、')}`;
+  } else if (pending.length) {
+    reason = `适配器未就绪: ${pending.join('、')}`;
+  } else if (this._warming) {
+    reason = '预热中（冷启动渲染未完成）';
+  }
+  return { ready, reason, adapters };
+};
+
+/**
+ * 健康快照：进程级存活信息，供 /healthz 探针与监控采集
+ * 与 getReadiness 的区别：健康只看「进程还能不能响应」，就绪看「能不能接流量」
+ * @returns {Object} { status, name, version, uptime, memory, check_at }
+ */
+OS.prototype.getHealth = function () {
+  const mem = process.memoryUsage();
+  return {
+    status: 'ok',
+    name: this.config.name,
+    version: pkg.version,
+    uptime: Math.round(process.uptime()),
+    memory: {
+      rss: Math.round(mem.rss / 1048576),
+      heap_used: Math.round(mem.heapUsed / 1048576)
+    },
+    check_at: new Date().toISOString()
+  };
+};
+
+/**
+ * 向适配器注入探针提供者：适配器据此暴露 /healthz、/readyz
+ * 采用能力探测（duck typing）而不是按模块名判断，新增适配器只要实现 setProbe 即可接入
+ * @param {object} manager 适配器管理器
+ * @returns {void} 无返回值
+ */
+OS.prototype._injectProbe = function (manager) {
+  if (!manager || typeof manager.setProbe !== 'function') {
+    return;
+  }
+  manager.setProbe(() => ({ health: this.getHealth(), readiness: this.getReadiness() }));
+};
+
+/**
+ * 打印适配器监听地址
+ * 协议自描述：取适配器配置中的 protocol（web→http / websocket→ws / socket→tcp / mqtt→mqtt），
+ * 内核不维护名称→协议的映射表，新增适配器无需改内核；
+ * 地址以 manager.getAddress() 的真实绑定结果优先（port:0 时拿到的是系统分配后的端口），
+ * 避免把「已启动」打成一条无法连接的伪装地址
+ * @param {string} name 适配器名称
+ * @param {object} manager 适配器管理器实例
+ */
+OS.prototype._printAddress = function (name, manager) {
+  const cfg = manager.config || {};
+  const protocol = cfg.protocol || name;
+  let host = cfg.host;
+  let port = cfg.port;
+  if (typeof manager.getAddress === 'function') {
+    const addr = manager.getAddress();
+    if (addr && addr.port) {
+      port = addr.port;
+      if (addr.address && addr.address !== '0.0.0.0' && addr.address !== '::') {
+        host = addr.address;
+      }
+    }
+  }
+  if (!host || host === '0.0.0.0' || host === '::') {
+    host = 'localhost';
+  }
+  let address = `${protocol}://${host}`;
+  if (port) {
+    address += `:${port}`;
+    this.log('info', `适配器 ${name} 已启动: ${address}`);
+  } else {
+    // 端口未定（配置缺省或随机分配）：明确说明而不是伪装成可连接地址
+    this.log('info', `适配器 ${name} 已启动: ${address}（未监听固定端口，无法给出可连接地址）`);
+  }
+};
+
 module.exports = OS;