PWA 适配：可安装到手机主屏幕 (v1.12.0)

lettimepassby · lettimepassby · commit f9cb70fd8d54 · 2026-07-13T04:31:09.000-07:00
- manifest.webmanifest：独立窗口模式、主题色、品牌图标
 （192/512 常规 + 512 maskable + 180 apple-touch-icon）
- 图标零依赖生成：tools/gen-icons.mjs 用 node:zlib 手写 PNG 编码器，
  按品牌 logo（蓝紫渐变+白色折线）光栅化，含抗锯齿
- sw.js：静态资源网络优先 + 缓存回退（Watchtower 自动更新不会被旧缓存
  卡住），断网导航回退应用壳；/api 与跨域请求不拦截，数据保持新鲜
- iOS meta（apple-touch-icon / standalone / 状态栏）任何环境可加主屏幕；
  独立窗口模式适配刘海与底部指示条安全区
- 注：Android Chrome 安装提示与 SW 需 HTTPS（或 localhost）环境
diff --git a/README.md b/README.md
@@ -37,6 +37,9 @@
 - **人民币折算**：每个站点可配置充值汇率（站点 $1 折合 ¥ 多少，如 1:2 充值）；
   余额、消耗、图表等金额主显人民币（未配置按 1:1），站点原始余额作为次要信息展示；
   **余额告警阈值仍按站点余额判断**，不受汇率影响
+- **PWA**：支持添加到手机主屏幕以独立窗口运行（含品牌图标与离线壳缓存）。
+  iOS Safari「添加到主屏幕」任何环境可用；Android Chrome 的安装提示要求 HTTPS 访问。
+  静态资源网络优先（Watchtower 自动更新不受缓存影响），API 不缓存
 - **面板登录**：网页需要账号密码登录（scrypt 哈希 + HMAC 签名会话 Cookie，7 天有效；登录失败限流）；默认账号 `admin / admin123`，登录后请在「设置」中修改
 - **内置演示**：首次启动自动创建演示中转站（数据来自内置 mock，含完整的登录→过期→自动续期链路演示），可直接删除
 
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "relay-monitor",
-  "version": "1.11.2",
+  "version": "1.12.0",
   "private": true,
   "description": "监控 sub2api / new-api 中转站余额的网页面板",
   "type": "module",
diff --git a/public/app.js b/public/app.js
@@ -1970,6 +1970,13 @@ document.addEventListener("visibilitychange", () => {
 // 我的站点页滚动时同步目录高亮
 $("#content").addEventListener("scroll", updateOwnTocActive, { passive: true });
 
+// PWA：注册 Service Worker（需要 HTTPS 或 localhost 环境）
+if ("serviceWorker" in navigator) {
+  window.addEventListener("load", () => {
+    navigator.serviceWorker.register("/sw.js").catch(() => {});
+  });
+}
+
 async function bootData() {
   const meta = await api.meta();
   state.types = meta.types;
diff --git a/public/icons/apple-touch-icon.png b/public/icons/apple-touch-icon.png
diff --git a/public/icons/icon-192.png b/public/icons/icon-192.png
diff --git a/public/icons/icon-512.png b/public/icons/icon-512.png
diff --git a/public/icons/maskable-512.png b/public/icons/maskable-512.png
diff --git a/public/index.html b/public/index.html
@@ -2,8 +2,17 @@
 <html lang="zh-CN" data-theme="light">
 <head>
   <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
   <title>中转站余额监控</title>
+  <link rel="manifest" href="/manifest.webmanifest" />
+  <meta name="theme-color" media="(prefers-color-scheme: light)" content="#F4F5F7" />
+  <meta name="theme-color" media="(prefers-color-scheme: dark)" content="#1C1C1E" />
+  <link rel="icon" href="/icons/icon-192.png" type="image/png" />
+  <link rel="apple-touch-icon" href="/icons/apple-touch-icon.png" />
+  <meta name="apple-mobile-web-app-capable" content="yes" />
+  <meta name="mobile-web-app-capable" content="yes" />
+  <meta name="apple-mobile-web-app-status-bar-style" content="default" />
+  <meta name="apple-mobile-web-app-title" content="中转监控" />
   <link rel="stylesheet" href="styles.css" />
 </head>
 <body>
diff --git a/public/manifest.webmanifest b/public/manifest.webmanifest
@@ -0,0 +1,17 @@
+{
+  "name": "中转站余额监控",
+  "short_name": "中转监控",
+  "description": "sub2api / new-api 中转站余额监控与经营分析面板",
+  "start_url": "/",
+  "scope": "/",
+  "display": "standalone",
+  "orientation": "portrait",
+  "background_color": "#F4F5F7",
+  "theme_color": "#0A84FF",
+  "lang": "zh-CN",
+  "icons": [
+    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png" },
+    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png" },
+    { "src": "/icons/maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
+  ]
+}
diff --git a/public/styles.css b/public/styles.css
@@ -310,6 +310,12 @@ button { font-family: inherit; cursor: pointer; }
   .report-frame { height: 52vh; }
 }
 
+/* PWA 独立窗口模式：避开刘海与底部指示条 */
+@media (display-mode: standalone) {
+  .titlebar { padding-top: calc(env(safe-area-inset-top, 0px)); height: calc(42px + env(safe-area-inset-top, 0px)); }
+  .content { padding-bottom: calc(24px + env(safe-area-inset-bottom, 0px)); }
+}
+
 /* ---- 登录屏 ---- */
 .login-screen {
   position: fixed; inset: 0; background: var(--window-outer-bg); z-index: 100;
diff --git a/public/sw.js b/public/sw.js
@@ -0,0 +1,41 @@
+// PWA Service Worker：静态资源网络优先（面板由 Watchtower 自动更新，
+// 不能让旧版本粘在缓存里），断网时回退缓存壳；API 请求不拦截（数据必须新鲜）。
+const CACHE = "relay-monitor-shell-v1";
+const SHELL = ["/", "/styles.css", "/app.js", "/manifest.webmanifest", "/icons/icon-192.png"];
+
+self.addEventListener("install", (e) => {
+  e.waitUntil(caches.open(CACHE).then((c) => c.addAll(SHELL)).catch(() => {}));
+  self.skipWaiting();
+});
+
+self.addEventListener("activate", (e) => {
+  e.waitUntil((async () => {
+    for (const k of await caches.keys()) if (k !== CACHE) await caches.delete(k);
+    await self.clients.claim();
+  })());
+});
+
+self.addEventListener("fetch", (e) => {
+  const url = new URL(e.request.url);
+  // 只处理同源静态 GET；API 与跨域请求直接走网络
+  if (e.request.method !== "GET" || url.origin !== self.location.origin || url.pathname.startsWith("/api/") || url.pathname.startsWith("/mock/")) return;
+  e.respondWith((async () => {
+    try {
+      const res = await fetch(e.request);
+      if (res.ok) {
+        const cache = await caches.open(CACHE);
+        cache.put(e.request, res.clone()).catch(() => {});
+      }
+      return res;
+    } catch {
+      const hit = await caches.match(e.request);
+      if (hit) return hit;
+      // 离线导航回退到缓存的应用壳
+      if (e.request.mode === "navigate") {
+        const shell = await caches.match("/");
+        if (shell) return shell;
+      }
+      return new Response("离线且无缓存", { status: 503, headers: { "Content-Type": "text/plain; charset=utf-8" } });
+    }
+  })());
+});
diff --git a/tools/gen-icons.mjs b/tools/gen-icons.mjs
@@ -0,0 +1,114 @@
+// PWA 图标生成器：零依赖手写 PNG 编码（node:zlib），按品牌 logo 光栅化
+// 用法：node tools/gen-icons.mjs   → 输出到 public/icons/
+import { deflateSync } from "node:zlib";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const outDir = join(dirname(fileURLToPath(import.meta.url)), "..", "public", "icons");
+mkdirSync(outDir, { recursive: true });
+
+// ---- 最小 PNG 编码器 ----------------------------------------------------------
+const crcTable = (() => {
+  const t = new Int32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c;
+  }
+  return t;
+})();
+const crc32 = (buf) => {
+  let c = -1;
+  for (const b of buf) c = crcTable[(c ^ b) & 0xff] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+};
+const chunk = (type, data) => {
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length);
+  const body = Buffer.concat([Buffer.from(type, "ascii"), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body));
+  return Buffer.concat([len, body, crc]);
+};
+function encodePNG(w, h, rgba) {
+  const raw = Buffer.alloc((w * 4 + 1) * h);
+  for (let y = 0; y < h; y++) {
+    raw[y * (w * 4 + 1)] = 0; // 无滤波
+    rgba.copy(raw, y * (w * 4 + 1) + 1, y * w * 4, (y + 1) * w * 4);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(w, 0);
+  ihdr.writeUInt32BE(h, 4);
+  ihdr[8] = 8; ihdr[9] = 6; // 8bit RGBA
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", ihdr),
+    chunk("IDAT", deflateSync(raw, { level: 9 })),
+    chunk("IEND", Buffer.alloc(0)),
+  ]);
+}
+
+// ---- 绘制 --------------------------------------------------------------------
+// 品牌 logo：蓝紫渐变底 + 白色坐标轴与折线（同 index.html 的 SVG）
+const AXIS = [[3, 3], [3, 21], [21, 21]];
+const LINE = [[7, 15], [11, 10], [14, 13], [19, 6]];
+
+const distToSeg = (px, py, x1, y1, x2, y2) => {
+  const dx = x2 - x1, dy = y2 - y1;
+  const t = Math.max(0, Math.min(1, ((px - x1) * dx + (py - y1) * dy) / (dx * dx + dy * dy || 1)));
+  const cx = x1 + t * dx, cy = y1 + t * dy;
+  return Math.hypot(px - cx, py - cy);
+};
+
+function draw(size, { rounded, pad = 0 }) {
+  const rgba = Buffer.alloc(size * size * 4);
+  const r = rounded ? size * 0.22 : 0;
+  const scale = (size * (1 - 2 * pad)) / 24;
+  const off = size * pad;
+  const lw = size * 0.055; // 线宽的一半
+  const paths = [AXIS, LINE].map((pts) => pts.map(([x, y]) => [off + x * scale, off + y * scale]));
+
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      const i = (y * size + x) * 4;
+      // 圆角矩形裁剪
+      if (r > 0) {
+        const cx = Math.max(r - x, x - (size - 1 - r), 0);
+        const cy = Math.max(r - y, y - (size - 1 - r), 0);
+        if (cx > 0 && cy > 0 && Math.hypot(cx, cy) > r) { rgba[i + 3] = 0; continue; }
+      }
+      // 渐变底（左上蓝 → 右下紫）
+      const t = (x + y) / (2 * size);
+      rgba[i] = Math.round(10 + t * (94 - 10));      // R: 0A → 5E
+      rgba[i + 1] = Math.round(132 + t * (92 - 132)); // G: 84 → 5C
+      rgba[i + 2] = Math.round(255 + t * (230 - 255)); // B: FF → E6
+      rgba[i + 3] = 255;
+      // 白色笔画（带 1px 抗锯齿边）
+      let d = Infinity;
+      for (const pts of paths) {
+        for (let s = 0; s < pts.length - 1; s++) {
+          d = Math.min(d, distToSeg(x, y, pts[s][0], pts[s][1], pts[s + 1][0], pts[s + 1][1]));
+        }
+      }
+      if (d < lw) {
+        const a = d > lw - 1.5 ? (lw - d) / 1.5 : 1; // 边缘抗锯齿
+        rgba[i] = Math.round(rgba[i] * (1 - a) + 255 * a);
+        rgba[i + 1] = Math.round(rgba[i + 1] * (1 - a) + 255 * a);
+        rgba[i + 2] = Math.round(rgba[i + 2] * (1 - a) + 255 * a);
+      }
+    }
+  }
+  return encodePNG(size, size, rgba);
+}
+
+const files = [
+  ["icon-192.png", draw(192, { rounded: true, pad: 0.10 })],
+  ["icon-512.png", draw(512, { rounded: true, pad: 0.10 })],
+  ["maskable-512.png", draw(512, { rounded: false, pad: 0.18 })], // 全出血，内容留安全区
+  ["apple-touch-icon.png", draw(180, { rounded: false, pad: 0.12 })], // iOS 自己做圆角
+];
+for (const [name, buf] of files) {
+  writeFileSync(join(outDir, name), buf);
+  console.log("生成", name, (buf.length / 1024).toFixed(1) + "KB");
+}

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "relay-monitor",`
`3`		`- "version": "1.11.2",`
	`3`	`+ "version": "1.12.0",`
`4`	`4`	`"private": true,`
`5`	`5`	`"description": "监控 sub2api / new-api 中转站余额的网页面板",`
`6`	`6`	`"type": "module",`