@yixinshuke/node-dashboard 0.0.0-stage → 0.1.1

package/src/assets/js/instances.js

@@ -0,0 +1,152 @@
+// ===== node-dashboard 大屏 · 分服务器（instances.js）=====
+// 单台实例卡片渲染（renderCard），由 common.js 的 loadInner 调用，写入 #grid。
+// 依赖 common.js 提供的 $ / ring / bar / sparkline / fmtBytes / fmtUptime / pctColor /
+// stateColor / qpmCell / qpmSection / qpmSnapshotBlock / channelTypeLabel / SPARK_COLORS / sparkPoints 等全局符号。
+
+function renderCard(inst, data, err, isSelf, idx) {
+  const cls = (err ? "card err" : "card") + (isSelf ? " self" : "");
+  let body;
+  if (err) {
+    body = `<div class="cbody full"><div class="kv"><span class="k">错误</span><span class="v">${err}</span></div></div>`;
+  } else {
+    const h = data.host, svc = data.service;
+    const ENV_LABEL = { prod: "生产", test: "测试", dev: "开发" };
+    const envRaw = inst.env || data?.service?.env || "—";
+    const envLabel = ENV_LABEL[envRaw] || envRaw;
+    const envClass = ENV_LABEL[envRaw] ? envRaw : "unknown";
+    const disk = (h.disk?.mounts || []).map((m) => {
+      const p = Number(m.usagePercent) || 0;
+      return `<div class="disk">
+        <div class="disk-head"><span>磁盘 ${m.mount}</span><span>${p.toFixed(1)}%</span></div>
+        <div class="track"><div class="fill" style="width:${Math.min(100, p)}%;background:${pctColor(p)}"></div></div>
+        <div class="disk-meta">总 ${fmtBytes(m.total)} · 已用 ${fmtBytes(m.used)} · 剩 ${fmtBytes(m.free)}</div>
+      </div>`;
+    }).join("");
+    // —— 组件健康（模块为主）：shardorm 分组 + node-lock/node-log/http/breaker + 单 Redis 根因行 ——
+    const cache = data.cache || {};
+    const info = data.shardormInfo || {};
+    const comps = data.components || {};
+    const stCls = (s) => s || "unknown";
+    const bbadge = (text, cls) => `<span class="backend-badge ${cls}">${text}</span>`;
+    const modRow = (name, status, attrs) =>
+      `<div class="comp"><span class="name">${name}</span><span class="dot ${stCls(status)}"></span><span class="mod-attrs">${attrs || ""}</span></div>`;
+
+    // shardorm 分组：缓存/指标后端 + 各实例连接/同步/恢复/连接池
+    const instRows = (info.instances || []).map((inst) => {
+      const conn = inst.connection;
+      const cStatus = conn ? conn.status : (inst.configured ? "unknown" : "skipped");
+      const nodes = (conn && conn.nodes) || [];
+      const down = nodes.filter((n) => n.status === "down").length;
+      const sync = inst.sync || {};
+      const rec = inst.recover || {};
+      const pools = inst.pool || [];
+      const poolStr = pools.length ? pools.map((p) => `${p.active}/${p.limit}`).join(" ") : "—";
+      const syncStr = sync.mode ? `${sync.mode}·差异${sync.structureIssues ?? 0}` : "—";
+      const recStr = `总数${rec.total ?? 0}·恢复${rec.recovered ?? 0}${Array.isArray(rec.dangling) && rec.dangling.length ? "·悬挂" + rec.dangling.length : ""}`;
+      const connStr = nodes.length ? `${nodes.length}节点${down ? " " + down + "异常" : "正常"}` : "—";
+      return `<div class="comp sub"><span class="name">${inst.name}</span><span class="dot ${stCls(cStatus)}"></span><span class="state">连接 ${connStr} ｜ 同步 ${syncStr} ｜ 恢复 ${recStr} ｜ 池 ${poolStr}</span></div>`;
+    }).join("");
+    const shardStatuses = (info.instances || []).map((i) => (i.connection ? i.connection.status : "unknown"));
+    const shardormStatus = shardStatuses.includes("down") ? "down"
+      : shardStatuses.includes("degraded") ? "degraded"
+      : shardStatuses.length ? "ok" : "unknown";
+    const shardormAttrs =
+      bbadge("缓存:" + (cache.shardormCache === "off" ? "关闭" : cache.shardormCache === "redis" ? "Redis" : "内存"), cache.shardormCache === "off" ? "off" : cache.shardormCache === "redis" ? "redis" : "memory") +
+      bbadge("指标:" + (cache.shardormMetrics === "redis" ? "Redis" : "内存"), cache.shardormMetrics === "redis" ? "redis" : "memory");
+    const shardormGroup = `<div class="mod-group">
+      <div class="comp"><span class="name">shardorm</span><span class="dot ${stCls(shardormStatus)}"></span><span class="mod-attrs">${shardormAttrs}</span></div>
+      ${instRows}
+    </div>`;
+
+    // 其它模块 + 单 Redis 根因行
+    const redisComp = comps.redis || {};
+    const redisStatus = redisComp.status || "unknown";
+    const lockAttrs = bbadge("锁后端:" + (cache.logLock === "redis" ? "Redis" : "无锁直写"), cache.logLock === "redis" ? "redis" : "none");
+    const logAttrs = bbadge("缓冲:" + (cache.logBuffer || "内存"), "memory") + bbadge("写锁:" + (cache.logLock === "redis" ? "Redis" : "无锁直写"), cache.logLock === "redis" ? "redis" : "none");
+    const httpStatus = data.http ? "ok" : "unknown";
+    const otherMods = [
+      modRow("node-lock", cache.logLock === "redis" ? redisStatus : "skipped", lockAttrs),
+      modRow("node-log", "ok", logAttrs),
+      modRow("http-client", httpStatus, ""),
+      modRow("breaker", (comps.breaker || {}).status || "unknown", ""),
+    ].join("") + (comps.externalApi ? modRow("外部API", (comps.externalApi || {}).status || "unknown", "") : "");
+    const redisRoot = modRow("Redis (根因)", redisStatus,
+      bbadge(redisStatus === "skipped" ? "未配置" : "连通", redisStatus === "skipped" ? "none" : "redis") +
+      (redisComp.latencyMs != null ? `<span class="state">${redisComp.latencyMs}ms</span>` : ""));
+    const modsHtml = `<div class="comps mods"><div class="comp-head">组件健康</div>${shardormGroup}${otherMods}${redisRoot}</div>`;
+    // 推送中心：node-push 是否加载、累计推送/成功率（来自 data.push.push overview）、按通道明细
+    const push = data.push || {};
+    const pushLoaded = !!push.loaded;
+    const pushStatus = !pushLoaded ? "unknown" : (push.error ? "down" : "ok");
+    const pushOv = push.push || {};
+    const pushByCh = pushOv.byChannel || [];
+    const pushChannels = pushByCh.map((c) => {
+      const lbl = c.typeLabel || channelTypeLabel(c.type);
+      return `<div class="comp sub"><span class="name">${lbl}</span><span class="dot ok"></span><span class="state">${c.count} 次 · 成功 ${c.successRate}</span></div>`;
+    }).join("");
+    const pushStorage = push.backends?.storage?.backend || "—";
+    const pushHtml = `<div class="mod-group">
+      <div class="comp"><span class="name">推送中心</span><span class="dot ${pushStatus}"></span><span class="mod-attrs">${bbadge("node-push:" + (pushLoaded ? "已加载" : "未加载"), pushLoaded ? "redis" : "none")}${bbadge("存储:" + pushStorage, "memory")}${(pushOv.successRate ? bbadge("成功率:" + pushOv.successRate, "ok") : "")}${push.error ? bbadge("异常:" + push.error, "off") : ""}</span></div>
+      <div class="comp sub"><span class="name">累计推送</span><span class="state">${(pushOv.totalTasks ?? 0)} 次 · 失败 ${(pushOv.failedTasks ?? 0)}</span></div>
+      ${pushChannels}
+    </div>`;
+    body = `<div class="cbody">
+      <div class="ctop">
+      <div>
+      <div class="kv">
+        <div class="item"><span class="k">主机</span><span class="v">${h.hostname} (${h.ips?.join(", ") || "—"})</span></div>
+        <div class="item"><span class="k">系统</span><span class="v">${h.os?.type} ${h.os?.release} · ${h.os?.arch}</span></div>
+        <div class="item"><span class="k">Node</span><span class="v">${h.nodeVersion}</span></div>
+        <div class="item"><span class="k">端口</span><span class="v">${inst.port}</span></div>
+        <div class="item"><span class="k">PID</span><span class="v">${svc.pid}</span></div>
+        <div class="item"><span class="k">环境</span><span class="v"><span class="env-badge ${envClass}">${envLabel}</span></span></div>
+        <div class="item"><span class="k">启动</span><span class="v">${new Date(svc.startedAt).toLocaleString()}</span></div>
+        <div class="item"><span class="k">运行时长</span><span class="v">${fmtUptime(svc.uptimeMs)}</span></div>
+        <div class="item"><span class="k">事件环延迟</span><span class="v">${h.process?.eventLoopLagMs ?? "?"} ms</span></div>
+      </div>
+      <div class="rings">
+        <div class="ring-wrap">
+          ${ring(h.cpu?.usage, pctColor(h.cpu?.usage))}
+          <div class="ring-label">CPU</div>
+          <div class="ring-sub">${h.cpu?.model || "—"} · ${h.cpu?.cores}核<br>load ${h.cpu?.loadavg?.map((x) => x.toFixed(2)).join("/") || "-"}</div>
+        </div>
+        <div class="ring-wrap">
+          ${ring(h.memory?.usagePercent, pctColor(h.memory?.usagePercent))}
+          <div class="ring-label">内存</div>
+          <div class="ring-sub">${fmtBytes(h.memory?.used)} / ${fmtBytes(h.memory?.total)}<br>RSS ${fmtBytes(h.process?.rss)}</div>
+        </div>
+      </div>
+      ${disk ? `<div class="bars">${disk}</div>` : ""}
+      </div>
+      <div>
+      ${modsHtml}${pushHtml}
+      </div>
+      </div>
+      <div class="cstats">
+      ${apiChannelCardsHtml("i" + idx)}
+      ${channelPairHtml("i" + idx, "shardorm", "分库分表 · shardorm", "SQL 次数 QPM", "SQL 耗时 ms")}
+      ${channelPairHtml("i" + idx, "http", "出口 HTTP · http-client", "HTTP 次数 QPM", "HTTP 耗时 ms")}
+      ${(() => {
+        // 推送 QPM：数据在 data.push.qpm（PushQpmSnapshot），与 apirouter/shardorm 的 QpmSnapshot 字段不同（无 total/ok/fail/avgMs）
+        const pq = data.push?.qpm;
+        const has = !!pq;
+        const v = (x) => (has ? (x ?? 0) : "—");
+        return qpmSection("推送中心 · node-push",
+          qpmCell("当前QPM", v(pq?.qpmCurrent)) +
+          qpmCell("近1分均值", v(pq?.qpmAvg)) +
+          qpmCell("通道种类", has ? (pq?.byChannel?.length ?? 0) : "—") +
+          qpmCell("主题数", has ? (pq?.byTopic?.length ?? 0) : "—"),
+          `<div class="spark-chart" data-idx="${idx}" data-kind="push"></div>`);
+      })()}
+      </div>
+      </div>
+    </div>`;
+  }
+  const env = inst.env || (data?.service?.env) || "—";
+  return `<div class="${cls}">
+    <div class="chead">
+      <span class="dot ${err ? "down" : "ok"}"></span>
+      ${isSelf ? '<span class="self-badge">本机</span>' : ""}<span class="title">${inst.ip}:${inst.port}</span>
+      <span class="env">${env} · ${inst.instanceId || ""}</span>
+    </div>${body}</div>`;
+}

package/src/assets/js/push.js

@@ -0,0 +1,178 @@
+// ===== node-dashboard 大屏 · 推送测试弹窗（push.js）=====
+// 自包含 IIFE：node-push 测试发送弹窗的逻辑（通道配置、服务器选择、发送）。
+// 仅依赖 DOM（#pushModal / #pushTestBtn 等）与 window.__pushInstances（由 common.js 的 loadInner 写入）。
+
+(function () {
+  const byId = (id) => document.getElementById(id);
+  const modal = byId("pushModal");
+  const openBtn = byId("pushTestBtn");
+  if (!modal || !openBtn) return;
+  const esc = (s) => String(s ?? "").replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+
+  // 各通道默认配置（从 /_sys/push/defaults 拉取，含 pushdeer / 邮件 等），用于弹窗自动预填
+  let PUSH_DEFAULTS = {};
+  async function loadPushDefaults() {
+    try {
+      // 该端点返回真实凭证，服务端要求有效 access 令牌：沿用弹窗里的「access token」输入框
+      const token = (byId("ptToken") && byId("ptToken").value || "").trim();
+      const headers = token ? { Authorization: "Bearer " + token } : {};
+      const r = await fetch("/_sys/push/defaults", { method: "GET", headers });
+      const d = await r.json();
+      if (d && d.ok && d.defaults) PUSH_DEFAULTS = d.defaults;
+    } catch (e) {
+      /* 非关键，预填失败不影响手动输入 */
+    }
+  }
+
+  // 每种通道一套字段：fields=表单字段，to=接收人提示（空则隐藏该输入），build=组装 extra
+  const CH_CFG = {
+    webhook: { label: "Webhook", fields: [
+        { k: "url", label: "Webhook URL", ph: "https://example.com/hook" },
+        { k: "allowPrivate", label: "允许内网/回环地址（SSRF 防护，测本机时勾选）", type: "checkbox" },
+      ], build: (v) => ({ url: v.url, allowPrivate: !!v.allowPrivate }) },
+    email: { label: "邮件", fields: [
+        { k: "smtpHost", label: "SMTP 主机" },
+        { k: "smtpPort", label: "SMTP 端口（可选）", ph: "465" },
+        { k: "username", label: "SMTP 账号" },
+        { k: "password", label: "SMTP 密码", type: "password" },
+        { k: "from", label: "发件人（可选）" },
+      ], to: "收件人邮箱，如 a@b.com", build: (v) => { const e = { smtpHost: v.smtpHost, username: v.username, password: v.password }; if (v.smtpPort) e.smtpPort = Number(v.smtpPort); if (v.from) e.from = v.from; return e; } },
+    mqtt: { label: "MQTT", fields: [ { k: "broker", label: "MQTT Broker", ph: "tcp://127.0.0.1:1883" } ], to: "MQTT topic，如 test/push", build: (v) => ({ broker: v.broker }) },
+    // 钉钉安全设置三选一/多选：自定义关键词(keyword) / IP地址段(服务端出口 IP，无需字段) / 加签(secret)
+    dingtalk: { label: "钉钉", fields: [
+        { k: "webhook", label: "钉钉机器人 Webhook" },
+        { k: "secret", label: "加签密钥（安全设置勾选「加签」时填）", type: "password" },
+        { k: "keyword", label: "自定义关键词（安全设置勾选「自定义关键词」时填）", ph: "如 告警" },
+      ], build: (v) => { const e = { webhook: v.webhook }; if (v.secret) e.secret = v.secret; if (v.keyword) e.keyword = v.keyword; return e; } },
+    wecom: { label: "企业微信", fields: [ { k: "webhook", label: "企微机器人 Webhook" } ], build: (v) => ({ webhook: v.webhook }) },
+    // 飞书安全设置三选一/多选：自定义关键词(secret 之下的 keyword) / IP白名单(服务端出口 IP，无需字段) / 签名校验(secret)
+    feishu: { label: "飞书", fields: [
+        { k: "webhook", label: "飞书机器人 Webhook" },
+        { k: "secret", label: "签名校验密钥（安全设置勾选「签名校验」时填）", type: "password" },
+        { k: "keyword", label: "自定义关键词（安全设置勾选「自定义关键词」时填）", ph: "如 告警" },
+      ], build: (v) => { const e = { webhook: v.webhook }; if (v.secret) e.secret = v.secret; if (v.keyword) e.keyword = v.keyword; return e; } },
+    pushdeer: { label: "PushDeer", fields: [ { k: "pushkey", label: "接收人key（PushDeer pushkey）" }, { k: "server", label: "PushDeer 服务器（可选）" } ], build: (v) => { const e = { pushkey: v.pushkey }; if (v.server) e.server = v.server; return e; } },
+    console: { label: "控制台（兜底，无需配置）", fields: [], build: () => ({}) },
+    ntfy: { label: "ntfy", fields: [ { k: "server", label: "ntfy 服务器（可选）", ph: "https://ntfy.sh" }, { k: "priority", label: "优先级 1-5（可选）" } ], to: "ntfy topic，如 mypush", build: (v) => { const e = {}; if (v.server) e.server = v.server; if (v.priority) e.priority = Number(v.priority); return e; } },
+  };
+
+  function renderChannelOptions() {
+    const sel = byId("ptChannel");
+    sel.innerHTML = Object.keys(CH_CFG).map((t) => `<option value="${t}">${esc(CH_CFG[t].label)}（${t}）</option>`).join("");
+    sel.value = "console"; // 默认控制台，零外部依赖必定可测
+  }
+  function renderCfg() {
+    const type = byId("ptChannel").value || "console";
+    const spec = CH_CFG[type] || CH_CFG.console;
+    byId("ptChanCfg").innerHTML = (spec.fields || []).map((f) => f.type === "checkbox"
+      ? `<label style="display:flex;align-items:center;gap:8px;margin-top:10px"><input type="checkbox" id="cfg-${f.k}" style="width:auto" /> ${esc(f.label)}</label>`
+      : `<label>${esc(f.label)}</label><input id="cfg-${f.k}" placeholder="${esc(f.ph || "")}"${f.type === "password" ? ' type="password"' : ""} />`
+    ).join("");
+    // 从 /_sys/push/defaults 自动预填（按字段 k 对齐）：pushdeer 的 pushkey、邮件的 SMTP 等
+    const dv = PUSH_DEFAULTS[type] || {};
+    for (const f of spec.fields || []) {
+      const el = byId("cfg-" + f.k);
+      if (!el || dv[f.k] === undefined) continue;
+      if (f.type === "checkbox") el.checked = !!dv[f.k];
+      else el.value = dv[f.k];
+    }
+    const toWrapOk = !!spec.to;
+    byId("ptTo").style.display = toWrapOk ? "" : "none";
+    byId("ptToLabel").style.display = toWrapOk ? "" : "none";
+    if (toWrapOk) byId("ptTo").placeholder = spec.to;
+  }
+  function readCfg(type) {
+    const spec = CH_CFG[type] || CH_CFG.console;
+    const v = {};
+    for (const f of spec.fields || []) {
+      const el = byId("cfg-" + f.k);
+      v[f.k] = f.type === "checkbox" ? !!(el && el.checked) : (el ? el.value.trim() : "");
+    }
+    return spec.build(v);
+  }
+  function renderServers() {
+    const sel = byId("ptServer");
+    const list = Array.isArray(window.__pushInstances) ? window.__pushInstances : [];
+    if (!list.length) {
+      sel.innerHTML = `<option value="-1">${esc(location.host)} · 本机</option>`;
+      return;
+    }
+    sel.innerHTML = list.map((it, i) => `<option value="${i}">${esc(it.ip + ":" + it.port)} · ${esc(it.env || "?")}${it._self ? " · 本机" : ""}</option>`).join("");
+    let selfIdx = list.findIndex((it) => it._self || (it.ip === location.hostname && Number(it.port) === Number(location.port || 3000)));
+    if (selfIdx < 0) selfIdx = 0;
+    sel.value = String(selfIdx);
+  }
+
+  const close = () => modal.classList.remove("open");
+  openBtn.addEventListener("click", () => {
+    renderServers();
+    modal.classList.add("open");
+    byId("ptResult").textContent = "";
+    loadPushDefaults().then(() => renderCfg()); // 打开即拉取默认配置并预填
+  });
+  byId("ptClose").addEventListener("click", close);
+  modal.addEventListener("click", (e) => { if (e.target === modal) close(); });
+  byId("ptChannel").addEventListener("change", renderCfg);
+  byId("ptModeSeg").addEventListener("click", (e) => {
+    const btn = e.target.closest("button[data-mode]");
+    if (!btn) return;
+    const mode = btn.getAttribute("data-mode");
+    byId("ptMode").value = mode;
+    byId("ptModeSeg").querySelectorAll("button").forEach((b) => b.classList.toggle("active", b === btn));
+    renderModeCfg();
+  });
+  function renderModeCfg() {
+    const showInterval = byId("ptMode").value === "throttle";
+    byId("ptInterval").style.display = showInterval ? "" : "none";
+    byId("ptIntervalLabel").style.display = showInterval ? "" : "none";
+  }
+  loadPushDefaults(); // 预取默认配置（打开弹窗时已缓存）
+  renderChannelOptions();
+  renderCfg();
+  renderModeCfg();
+
+  byId("ptSend").addEventListener("click", async () => {
+    const btn = byId("ptSend");
+    const out = byId("ptResult");
+    const list = Array.isArray(window.__pushInstances) ? window.__pushInstances : [];
+    const sel = byId("ptServer");
+    const inst = sel.value !== "-1" ? list[Number(sel.value)] : null;
+    const base = !inst || inst._self ? "" : `http://${inst.ip}:${inst.port}`;
+    const type = byId("ptChannel").value || "console";
+    const topic = byId("ptTopic").value.trim();
+    const title = byId("ptTitle").value.trim() || "大屏测试推送";
+    const count = Math.max(1, Number(byId("ptCount").value) || 1);
+    const token = byId("ptToken").value.trim();
+    const to = byId("ptTo").value.split(/[,，]/).map((s) => s.trim()).filter(Boolean);
+    const mode = byId("ptMode").value;
+    const throttleIntervalMs = Number(byId("ptInterval").value) || 60000;
+    const extra = readCfg(type);
+    btn.disabled = true;
+    out.textContent = "发送中…";
+    const headers = { "Content-Type": "application/json" };
+    if (token) headers["Authorization"] = "Bearer " + token;
+    let ok = 0, sent = 0, lastErr = "";
+    try {
+      const r = await fetch(`${base}/_sys/push/test`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ topic, title, channelType: type, channel: { extra }, to, count, mode, throttleIntervalMs }),
+      });
+      const txt = await r.text();
+      let data = null;
+      try { data = JSON.parse(txt); } catch { /* 非 JSON */ }
+      if (r.ok && data && data.ok) {
+        ok = 1;
+        sent = data.sent ?? 0;
+      } else {
+        lastErr = data?.error || `HTTP ${r.status} ${txt.slice(0, 200)}`;
+      }
+    } catch (e) {
+      lastErr = String(e && e.message ? e.message : e);
+    }
+    btn.disabled = false;
+    const where = inst ? `${inst.ip}:${inst.port}` : location.host;
+    out.textContent = `已发送 ${sent}/${count} 条 → ${where} · 通道 ${type}\n` + (lastErr ? `错误：${lastErr}\n` : "") + (ok ? (mode === "throttle" && sent === 0 ? "（已被节流缓冲，到点后由定时器真实投递；控制台通道会在目标机控制台打印）" : "（控制台通道会在目标机控制台打印；稍后自动刷新可见）") : "");
+    if (ok && typeof load === "function") load();
+  });
+})();

package/src/config.ts

@@ -0,0 +1,27 @@
+/**
+ * 大屏配置注入点（替代原 node-server 的 config.env / config.obs）。
+ *
+ * 包不读环境变量，由宿主启动时注入：env（用于 Redis qpm 历史键的分桶）、obsRequireAuth（/_sys 是否鉴权）。
+ */
+
+let env = "dev";
+let obsRequireAuth = false;
+let systemName = "服务";
+
+export function configureDashboard(opts: { env?: "prod" | "test" | "dev"; obsRequireAuth?: boolean; systemName?: string }): void {
+  if (opts.env) env = opts.env;
+  if (opts.obsRequireAuth !== undefined) obsRequireAuth = opts.obsRequireAuth;
+  if (opts.systemName) systemName = opts.systemName;
+}
+
+export const dashboardConfig = {
+  get env() {
+    return env;
+  },
+  get obsRequireAuth() {
+    return obsRequireAuth;
+  },
+  get systemName() {
+    return systemName;
+  },
+};

package/src/dashboard.ts

@@ -0,0 +1,171 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { dashboardConfig } from "./config.js";
+import { histGetAgg, histGetCmd, mergeMemHist } from "./qpm-hist.js";
+
+/**
+ * 服务器监控大屏：聚合 API + 前端托管。
+ *
+ * 包内提供：
+ *   - `mountDashboard(app, opts)`：在 Fastify 上挂大屏静态页（由宿主 www 根提供，本包只暴露数据接口）与 `/_sys/_agg`（聚合快照）；
+ *   - `writeDashboardAssets(dir)`：把 index.html 落到宿主的 www 目录（启动时统一静态根，允许覆盖）；
+ *   - `registerDashboardSources(opts)`：各服务注册「大屏展示哪些数据源」；
+ *   - `registerAggProvider(fn)`：宿主注入实时内存指标（apirouter QosStats / http-client Metrics），与 Redis 历史合并。
+ *
+ * 聚合端点（/_sys/_agg）默认公开；若宿主配置 `obsRequireAuth=true`，则授权由宿主的鉴权中间件兜住。
+ * 注意：聚合路由放在 `/_sys/_agg` 而非 `/api/_agg`，避免与 apirouter 的 `/api/:module` 冲突。
+ */
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+let sources: Record<string, unknown> = {};
+let aggProvider: (() => { qpm?: Record<string, { mem: Array<{ t: number; count: number }> }>; health?: unknown } | null) | null =
+  null;
+
+/** 各服务注册大屏数据源开关（如 { shardorm: true, sqlTrace: false, cards: [...] }） */
+export function registerDashboardSources(opts: Record<string, unknown>): void {
+  sources = { ...sources, ...opts };
+}
+
+/** 宿主注入实时内存指标采集器（与 Redis 历史合并；不注入则只返回 sources 与 Redis 历史） */
+export function registerAggProvider(
+  fn: () => { qpm?: Record<string, { mem: Array<{ t: number; count: number }> }>; health?: unknown } | null,
+): void {
+  aggProvider = fn;
+}
+
+function instanceId(): string {
+  const ip = Object.values(os.networkInterfaces())
+    .flat()
+    .find((i: any) => i && i.family === "IPv4" && !i.internal)?.address ?? "127.0.0.1";
+  return `${ip}:${Number(process.env.PORT ?? 3000)}`;
+}
+
+/** 生成聚合快照（/_agg 返回体） */
+export async function buildAgg(): Promise<Record<string, unknown>> {
+  const provider = aggProvider ? safeCall(aggProvider) : null;
+  const qpm: Record<string, unknown> = {};
+
+  // Redis 历史（无 Redis / 读失败则 null）
+  const svcNames = new Set<string>(Object.keys(provider?.qpm ?? {}));
+  for (const svc of svcNames) {
+    const mem = (provider?.qpm?.[svc]?.mem as Array<{ t: number; count: number }>) ?? [];
+    const hist = await histGetAgg(svc);
+    qpm[svc] = {
+      redis: hist,
+      // 折线序列：Redis 历史（含 avg/max/min 耗时）优先，内存当前分钟补尾
+      perMinute: hist
+        ? mergeMemHist(mem, hist.perMinute.map((b) => ({ t: b.t, count: b.count }))).map((b) => {
+            const h = hist.perMinute.find((x) => x.t === b.t);
+            return { t: b.t, count: b.count, fail: h?.fail ?? 0, avgMs: h?.avgMs ?? 0, maxMs: h?.maxMs ?? 0, minMs: h?.minMs ?? 0 };
+          })
+        : mem,
+    };
+  }
+
+  return {
+    instance: instanceId(),
+    env: dashboardConfig.env,
+    ts: Date.now(),
+    sources,
+    qpm,
+    health: provider?.health ?? null,
+  };
+}
+
+/** 单 cmd 钻取：聚合某 svc 下某 cmd 的逐分钟时序（Redis 历史，重启不丢）。 */
+export async function buildCmdAgg(svc: string, cmd: string): Promise<Record<string, unknown> | null> {
+  const hist = await histGetCmd(svc, cmd);
+  if (!hist) return null;
+  return {
+    svc,
+    cmd,
+    total: hist.total,
+    ok: hist.ok,
+    fail: hist.fail,
+    avgMs: hist.avgMs,
+    maxMs: hist.maxMs,
+    minMs: hist.minMs,
+    perMinute: hist.perMinute,
+  };
+}
+
+function safeCall<T>(fn: () => T): T | null {
+  try {
+    return fn();
+  } catch {
+    return null;
+  }
+}
+
+function readAssetHtml(): string {
+  try {
+    return fs.readFileSync(path.join(__dirname, "assets", "index.html"), "utf8");
+  } catch {
+    return "<!doctype html><meta charset=utf-8><title>dashboard</title><h1>大屏资源缺失</h1>";
+  }
+}
+
+/** 把模板里的 __SYSTEM_NAME__ 占位符替换为配置的系统名称（默认「服务」） */
+function renderHtml(raw: string): string {
+  const name = dashboardConfig.systemName || "服务";
+  return raw.replace(/__SYSTEM_NAME__/g, name);
+}
+
+export interface MountDashboardOptions {
+  /** 聚合 API 路由（默认 /_sys/_agg） */
+  aggRoute?: string;
+}
+
+/**
+ * 在 Fastify 实例上挂载大屏数据接口。
+ * 大屏静态页由宿主把 www/index.html 作为静态根提供（首页即大屏），本函数只挂数据 API。
+ * 宿主需在静态/JSON 路由上自行处理鉴权（obsRequireAuth=true 时）。
+ */
+export function mountDashboard(app: any, opts: MountDashboardOptions = {}): void {
+  const aggRoute = opts.aggRoute ?? "/_sys/_agg";
+  if (app && typeof app.get === "function") {
+    app.get(aggRoute, async (_req: any, reply: any) => {
+      reply.header("content-type", "application/json; charset=utf-8");
+      return buildAgg();
+    });
+    app.get(`${aggRoute}/cmd`, async (req: any, reply: any) => {
+      reply.header("content-type", "application/json; charset=utf-8");
+      const svc = String(req.query?.svc ?? "");
+      const cmd = String(req.query?.cmd ?? "");
+      if (!svc || !cmd) return reply.code(400).send({ error: "svc and cmd required" });
+      const data = await buildCmdAgg(svc, cmd);
+      if (!data) return reply.code(404).send({ error: "no data" });
+      return data;
+    });
+  }
+}
+
+/** 递归拷贝目录（用于把包内 assets 整目录落到宿主 www） */
+function copyDir(src: string, dest: string): void {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const ent of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, ent.name);
+    const d = path.join(dest, ent.name);
+    if (ent.isDirectory()) copyDir(s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+/** 把大屏资源写入宿主 www 目录（统一静态根 / 允许覆盖）。
+ *  包内 assets 含：index.html（壳，含 __SYSTEM_NAME__ 占位）+ js/{common,agg,instances,push}.js。
+ *  整目录拷贝后，再用「系统名称」渲染 index.html 覆盖占位符（js 文件无需替换）。 */
+export function writeDashboardAssets(dir: string): void {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    // 整目录拷贝：index.html + js/*.js 一并落到 www，保证脚本相对路径（js/common.js）可用
+    copyDir(path.join(__dirname, "assets"), dir);
+    // 每次启动都用「包内壳 + 系统名称」重新渲染，覆盖宿主 www/index.html，
+    // 保证各系统（代理商/商户/支付/会员/收银）显示各自的系统名称，且 UI 与包同步。
+    fs.writeFileSync(path.join(dir, "index.html"), renderHtml(readAssetHtml()));
+  } catch (e) {
+    console.warn("[dashboard] 写入大屏资源失败：", (e as Error).message);
+  }
+}

package/src/http-logger.ts

@@ -0,0 +1,65 @@
+import { GlobalLogger } from "@yixinshuke/node-log";
+import type { Logger, LogFields } from "@yixinshuke/node-http-client";
+
+/** 从 url 字段提取 host（按 host 聚合到同一日志文件）；解析失败回退 "http" */
+function hostOf(url?: unknown): string {
+  if (typeof url !== "string") return "http";
+  try {
+    return new URL(url).host || "http";
+  } catch {
+    return "http";
+  }
+}
+
+/**
+ * node-http-client → node-log 日志桥接。
+ *
+ * http-client 的 `Logger` 端口是「字段式」（info(fields)/error(fields)/warn/debug），
+ * 这里转投 node-log：
+ *   - 全量请求字段（url / method / durationMs / status / kind / 错误信息 …）透传进 `extra`，便于 JSON 检索；
+ *   - 按 host 聚合：落到 `node-server/http/<host>.log`（同一下游一台机器一天一个文件）；
+ *   - 观测是非关键路径：桥接抛错一律吞掉，**绝不阻断 http 主链路**（与 node-log 铁律一致）。
+ *
+ * 用法：把 createHttpClientLogger() 作为 callHttp 的 `logger` 选项传入即可；
+ * 设为 false 仍可在调用处完全关闭日志。
+ */
+export function createHttpClientLogger(): Logger {
+  // 懒加载：不在创建时取 GlobalLogger（模块导入早于 index.ts 的 initLogger()，
+  // 此时取会抛「请先 init」）。首次真正请求时再取并缓存，届时 init 已完成。
+  let logger: GlobalLogger | null = null;
+
+  const emit = (level: "debug" | "info" | "warn" | "error", fields: LogFields): void => {
+    try {
+      if (!logger) logger = GlobalLogger.getInstance();
+      const host = hostOf(fields.url);
+      const msg =
+        typeof fields.msg === "string" && fields.msg ? fields.msg : JSON.stringify(fields);
+      const ctx = {
+        category: "node-server/http",
+        merchantId: 0,
+        storeId: 0,
+        system: "node-server",
+        bizKey: host,
+        extra: fields,
+      };
+      const fn = (
+        {
+          debug: logger.debug.bind(logger),
+          info: logger.info.bind(logger),
+          warn: logger.warn.bind(logger),
+          error: logger.error.bind(logger),
+        } as const
+      )[level];
+      fn(ctx, msg);
+    } catch {
+      /* 观测非关键路径：吞错，绝不阻断 http 主链路 */
+    }
+  };
+
+  return {
+    debug: (f) => emit("debug", f),
+    info: (f) => emit("info", f),
+    warn: (f) => emit("warn", f),
+    error: (f) => emit("error", f),
+  };
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+// 观测采集器
+export * from "./sql-trace.js";
+export * from "./qpm-hist.js";
+export * from "./shardorm-logger.js";
+export * from "./http-logger.js";
+export * from "./panel-token-inject.js";
+// 大屏框架
+export * from "./dashboard.js";
+// 配置注入
+export { configureDashboard, dashboardConfig } from "./config.js";