From a922244a258a7bb6e0cf0a1b836ffb6ea0107d73 Mon Sep 17 00:00:00 2001 From: vvbbnn00 Date: Sun, 11 Oct 2026 18:21:40 +0800 Subject: [PATCH 1/4] perf(web): subset Chinese fonts in production builds Collect panel text and backend messages while preserving variable font weights, layout features and licensing metadata. Keep complete fonts for development in a separate directory and retain the existing system fallback for dynamic characters. Cover Unicode source collection and development/production coexistence. --- .gitignore | 1 + docs/WEBUI.md | 1 + web/build/fonts.test.ts | 68 +++++++++++++++++++++++++ web/build/fonts.ts | 98 ++++++++++++++++++++++++++++++++++++ web/package-lock.json | 109 ++++++++++++++++++++++++++++++++++++++++ web/package.json | 2 + web/src/styles.css | 2 +- web/src/test/setup.ts | 12 +++-- web/vite.config.ts | 18 +++++-- 9 files changed, 301 insertions(+), 10 deletions(-) create mode 100644 web/build/fonts.test.ts create mode 100644 web/build/fonts.ts diff --git a/.gitignore b/.gitignore index b197b07..b02706d 100644 --- a/.gitignore +++ b/.gitignore @@ -17,5 +17,6 @@ # frontend web/node_modules/ +web/.generated/ internal/webui/dist/* !internal/webui/dist/.gitkeep diff --git a/docs/WEBUI.md b/docs/WEBUI.md index 5c548be..478c2ae 100644 --- a/docs/WEBUI.md +++ b/docs/WEBUI.md @@ -508,6 +508,7 @@ web/ `vite.config.ts`: - `build.outDir = '../internal/webui/dist'`,`build.emptyOutDir = true`。 +- 发布构建自动从前端源码和 Go 后端消息收集固定字符,裁剪 Noto Sans SC 字形,保留可变字重、hinting 和排版特性。Geist 与 Geist Mono 保留完整字库;动态内容中未内置的字形使用现有系统字体回退。开发模式保留完整 Noto Sans SC 字库,新增文案不需要手动维护字符清单。开发与发布构建分别使用 `web/.generated/fonts-dev` 和 `web/.generated/fonts`,避免互相覆盖。 - dev 代理必须兼容 §8 的 Host/Origin 校验(字符串简写会保留 5173 的 Host 与 Origin,导致全部请求 403): ```ts diff --git a/web/build/fonts.test.ts b/web/build/fonts.test.ts new file mode 100644 index 0000000..93680ac --- /dev/null +++ b/web/build/fonts.test.ts @@ -0,0 +1,68 @@ +// @vitest-environment node + +import { mkdtemp, mkdir, writeFile, readFile, realpath, cp, rm } from "node:fs/promises"; +import os from "node:os"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { expect, test } from "vitest"; +import { build, createServer } from "vite"; +import { collectFontText, panelFonts } from "./fonts"; + +test("new frontend and backend text, escaped Unicode and HTML entities enter the font subset", async () => { + const directory = await mkdtemp(path.join(os.tmpdir(), "panel-font-text-")); + try { + const root = path.join(directory, "web"); + for (const name of ["web/src/test", "internal/messages", "cmd/panel"]) { + await mkdir(path.join(directory, name), { recursive: true }); + } + await writeFile(path.join(root, "src/Panel.tsx"), 'export const label = "新界面\\u9a8c\\u{20bb7}";'); + await writeFile(path.join(root, "src/message.js"), 'export const label = "脚";'); + await writeFile(path.join(root, "src/messages.json"), '{"label":"翻译\\u8bed"}'); + await writeFile(path.join(directory, "internal/messages/message.go"), 'const message = "服务端"'); + await writeFile(path.join(root, "index.html"), "状态"); + await writeFile(path.join(root, "src/Panel.test.tsx"), "测试专用"); + await writeFile(path.join(root, "src/test/setup.ts"), "测试专用"); + await writeFile(path.join(directory, "internal/messages/message_test.go"), "测试专用"); + const text = await collectFontText(root); + expect(new Set(text)).toEqual(new Set("新界面验𠮷服务端状态脚翻译语")); + } finally { + await rm(directory, { recursive: true, force: true }); + } +}); + +test("a production build leaves the development font stylesheet and files intact", async () => { + const directory = await realpath(await mkdtemp(path.join(os.tmpdir(), "panel-font-modes-"))); + const root = path.join(directory, "web"); + const devCSS = path.join(root, ".generated/fonts-dev/noto-sans-sc.css"); + let server: Awaited> | undefined; + try { + for (const name of ["web/src", "internal", "cmd"]) { + await mkdir(path.join(directory, name), { recursive: true }); + } + await cp(fileURLToPath(new URL("../node_modules/@fontsource-variable/noto-sans-sc", import.meta.url)), + path.join(root, "node_modules/@fontsource-variable/noto-sans-sc"), { recursive: true }); + await writeFile(path.join(root, "index.html"), ''); + await writeFile(path.join(root, "src/main.ts"), 'import "./styles.css"; document.body.textContent = "新界面";'); + await writeFile(path.join(root, "src/styles.css"), '@import "@panel-fonts";'); + server = await createServer({ + root, configFile: false, logLevel: "silent", plugins: [panelFonts()], + resolve: { alias: { "@panel-fonts": devCSS } }, + server: { middlewareMode: true, hmr: false, watch: null }, + }); + const before = await server.transformRequest("/src/styles.css"); + expect(before?.code).toContain("Noto Sans SC Variable"); + const fullCSS = await readFile(devCSS, "utf8"); + await build({ + root, configFile: false, logLevel: "silent", plugins: [panelFonts()], + resolve: { alias: { "@panel-fonts": path.join(root, ".generated/fonts/noto-sans-sc.css") } }, + }); + expect(await readFile(devCSS, "utf8")).toBe(fullCSS); + expect((await server.transformRequest("/src/styles.css"))?.code).toBe(before?.code); + const subsetCSS = await readFile(path.join(root, ".generated/fonts/noto-sans-sc.css"), "utf8"); + expect(subsetCSS).toContain("@font-face"); + expect(subsetCSS.match(/@font-face/g)!.length).toBeLessThan(fullCSS.match(/@font-face/g)!.length); + } finally { + await server?.close(); + await rm(directory, { recursive: true, force: true }); + } +}, 15000); diff --git a/web/build/fonts.ts b/web/build/fonts.ts new file mode 100644 index 0000000..172ac4e --- /dev/null +++ b/web/build/fonts.ts @@ -0,0 +1,98 @@ +import { readFile, readdir, mkdir, rm, writeFile } from "node:fs/promises"; +import path from "node:path"; +import subsetFont from "subset-font"; +import type { Plugin, ResolvedConfig } from "vite"; + +// Include backend messages as well as panel text. Unknown dynamic characters +// continue through the existing CSS system-font fallback. +export async function collectFontText(root: string): Promise { + const characters = new Set(); + async function collect(file: string): Promise { + const source = await readFile(file, "utf8"); + const decoded = source.replace( + /\\u\{([\da-f]+)\}|\\u([\da-f]{4})|&#x([\da-f]+);|&#(\d+);/gi, + (match, braced, escaped, hex, decimal) => { + const point = parseInt(braced ?? escaped ?? hex ?? decimal, decimal ? 10 : 16); + return point <= 0x10ffff ? String.fromCodePoint(point) : match; + }, + ); + for (const character of decoded) { + // Geist already supplies Latin; do not duplicate it in Noto Sans SC. + if (character.codePointAt(0)! > 0xff) characters.add(character); + } + } + async function walk(directory: string): Promise { + for (const entry of await readdir(directory, { withFileTypes: true })) { + const file = path.join(directory, entry.name); + if (entry.isDirectory()) { + if (entry.name !== "test" && entry.name !== "dist") await walk(file); + } else if (/\.(?:[jt]sx?|css|html|json|svg|go)$/.test(entry.name) && + !/(?:\.test\.|_test\.go$)/.test(entry.name)) { + await collect(file); + } + } + } + await walk(path.join(root, "src")); + await walk(path.join(root, "..", "internal")); + await walk(path.join(root, "..", "cmd")); + await collect(path.join(root, "index.html")); + return [...characters].sort((a, b) => a.codePointAt(0)! - b.codePointAt(0)!).join(""); +} + +function withinRange(character: string, range: string): boolean { + const point = character.codePointAt(0)!; + return range.split(",").some((part) => { + const match = /^U\+([\da-f?]+)(?:-([\da-f]+))?$/i.exec(part.trim()); + if (!match) throw new Error(`Unsupported font unicode-range: ${part}`); + const low = parseInt(match[1].replace(/\?/g, "0"), 16); + const high = parseInt((match[2] ?? match[1]).replace(/\?/g, "f"), 16); + return point >= low && point <= high; + }); +} + +export function panelFonts(): Plugin { + let config: ResolvedConfig; + return { + name: "panel-font-subsets", + configResolved(resolved) { config = resolved; }, + async buildStart() { + const packageRoot = path.join(config.root, "node_modules/@fontsource-variable/noto-sans-sc"); + const generated = path.join(config.root, ".generated", config.command === "serve" ? "fonts-dev" : "fonts"); + const source = await readFile(path.join(packageRoot, "index.css"), "utf8"); + await rm(generated, { recursive: true, force: true }); + await mkdir(generated, { recursive: true }); + let css: string; + if (config.command === "serve") { + // Development keeps the complete font so newly typed text also works + // before the next production build, including during hot reload. + css = source.replaceAll("./files/", "../../node_modules/@fontsource-variable/noto-sans-sc/files/"); + } else { + const text = await collectFontText(config.root); + const faces: string[] = []; + let bytes = 0; + for (const match of source.matchAll(/@font-face\s*\{[^}]+\}/g)) { + const face = match[0]; + const range = /unicode-range:\s*([^;]+);/.exec(face)?.[1]; + const url = /url\(([^)]+)\)/.exec(face)?.[1]; + if (!range || !url) throw new Error("Noto Sans SC font face is missing its source or unicode-range"); + const selected = [...text].filter((character) => withinRange(character, range)); + if (!selected.length) continue; + const filename = path.basename(url); + const font = await subsetFont(await readFile(path.join(packageRoot, url)), selected.join(""), { + targetFormat: "woff2", + // Preserve copyright and OFL licensing alongside names and weight + // axes. Hinting and every layout feature are retained by default. + preserveNameIds: [0, 7, 13, 14], + }); + await writeFile(path.join(generated, filename), font); + bytes += font.length; + const unicodeRange = selected.map((character) => `U+${character.codePointAt(0)!.toString(16)}`).join(","); + faces.push(face.replace(url, `./${filename}`).replace(range, unicodeRange)); + } + css = faces.join("\n"); + config.logger.info(`[fonts] Noto Sans SC: ${[...text].length} source characters, ${faces.length} subsets, ${(bytes / 1000).toFixed(1)} kB`); + } + await writeFile(path.join(generated, "noto-sans-sc.css"), css); + }, + }; +} diff --git a/web/package-lock.json b/web/package-lock.json index a5f2ce0..0e3c542 100644 --- a/web/package-lock.json +++ b/web/package-lock.json @@ -26,8 +26,10 @@ "@types/node": "^22.10.2", "@types/react": "^18.3.12", "@types/react-dom": "^18.3.1", + "@types/subset-font": "2.3.0", "@vitejs/plugin-react": "^4.7.0", "jsdom": "^30.1.2", + "subset-font": "2.9.0", "tailwindcss": "^4.3.3", "typescript": "^5.6.3", "vite": "^6.4.3", @@ -3401,6 +3403,16 @@ "@types/react": "^18.0.0" } }, + "node_modules/@types/subset-font": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/@types/subset-font/-/subset-font-2.3.0.tgz", + "integrity": "sha512-+u2CzLEE7ZReuBP0Mfz0tBydVZvWESmZpBbL7sc+J+qB9ImNp1QmOptMe28uXj2aRPDoQhQF3dubXMgwo56gIg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/node": "*" + } + }, "node_modules/@vitejs/plugin-react": { "version": "4.7.0", "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-4.7.0.tgz", @@ -3495,6 +3507,13 @@ "url": "https://github.com/chalk/ansi-styles?sponsor=1" } }, + "node_modules/argparse": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", + "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==", + "dev": true, + "license": "Python-2.0" + }, "node_modules/aria-hidden": { "version": "1.2.6", "resolved": "https://registry.npmjs.org/aria-hidden/-/aria-hidden-1.2.6.tgz", @@ -3882,6 +3901,17 @@ } } }, + "node_modules/fontverter": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/fontverter/-/fontverter-2.0.0.tgz", + "integrity": "sha512-DFVX5hvXuhi1Jven1tbpebYTCT9XYnvx6/Z+HFUPb7ZRMCW+pj2clU9VMhoTPgWKPhAs7JJDSk3CW1jNUvKCZQ==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "wawoff2": "^2.0.0", + "woff2sfnt-sfnt2woff": "^1.0.0" + } + }, "node_modules/fsevents": { "version": "2.3.3", "resolved": "https://mirrors.huaweicloud.com/repository/npm/fsevents/-/fsevents-2.3.3.tgz", @@ -3923,6 +3953,13 @@ "dev": true, "license": "ISC" }, + "node_modules/harfbuzzjs": { + "version": "1.6.3", + "resolved": "https://registry.npmjs.org/harfbuzzjs/-/harfbuzzjs-1.6.3.tgz", + "integrity": "sha512-R5Mfo1UUvQmZJmtScP7fBLKYKnYu82ZdtFT7WbQYeGb3Ut5PR3xfFCJ5/FjbcW5SAfb9cqCSny/KNjp+NJBx0w==", + "dev": true, + "license": "MIT" + }, "node_modules/html-encoding-sniffer": { "version": "7.0.0", "resolved": "https://registry.npmjs.org/html-encoding-sniffer/-/html-encoding-sniffer-7.0.0.tgz", @@ -4421,6 +4458,29 @@ "node": ">=12.20.0" } }, + "node_modules/p-limit": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/p-limit/-/p-limit-3.1.0.tgz", + "integrity": "sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "yocto-queue": "^0.1.0" + }, + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/pako": { + "version": "1.0.11", + "resolved": "https://registry.npmjs.org/pako/-/pako-1.0.11.tgz", + "integrity": "sha512-4hLB8Py4zZce5s4yd9XzopqwVv/yGNhV1Bl8NTmCq1763HeK2+EwVTv+leGeL13Dnh2wfbqowVPXCIO0z4taYw==", + "dev": true, + "license": "(MIT AND Zlib)" + }, "node_modules/parse5": { "version": "8.0.1", "resolved": "https://registry.npmjs.org/parse5/-/parse5-8.0.1.tgz", @@ -4802,6 +4862,18 @@ "dev": true, "license": "MIT" }, + "node_modules/subset-font": { + "version": "2.9.0", + "resolved": "https://registry.npmjs.org/subset-font/-/subset-font-2.9.0.tgz", + "integrity": "sha512-WJulQeFwbewrXIGcLJbSZFWI44fHW8gNRuPzLywfDL8w38IPRbN1JFxwG76aoohw9kcFdvjVIn2QmID1iy119A==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "fontverter": "^2.0.0", + "harfbuzzjs": "^1.6.1", + "p-limit": "^3.1.0" + } + }, "node_modules/tailwindcss": { "version": "4.3.3", "resolved": "https://registry.npmjs.org/tailwindcss/-/tailwindcss-4.3.3.tgz", @@ -5207,6 +5279,20 @@ "node": "^22.22.2 || ^24.15.0 || >=26.0.0" } }, + "node_modules/wawoff2": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/wawoff2/-/wawoff2-2.0.1.tgz", + "integrity": "sha512-r0CEmvpH63r4T15ebFqeOjGqU4+EgTx4I510NtK35EMciSdcTxCw3Byy3JnBonz7iyIFZ0AbVo0bbFpEVuhCYA==", + "dev": true, + "license": "MIT", + "dependencies": { + "argparse": "^2.0.1" + }, + "bin": { + "woff2_compress.js": "bin/woff2_compress.js", + "woff2_decompress.js": "bin/woff2_decompress.js" + } + }, "node_modules/webidl-conversions": { "version": "8.0.1", "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-8.0.1.tgz", @@ -5255,6 +5341,16 @@ "node": ">=20.11" } }, + "node_modules/woff2sfnt-sfnt2woff": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/woff2sfnt-sfnt2woff/-/woff2sfnt-sfnt2woff-1.0.0.tgz", + "integrity": "sha512-edK4COc1c1EpRfMqCZO1xJOvdUtM5dbVb9iz97rScvnTevqEB3GllnLWCmMVp1MfQBdF1DFg/11I0rSyAdS4qQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "pako": "^1.0.7" + } + }, "node_modules/xml-name-validator": { "version": "5.0.0", "resolved": "https://registry.npmjs.org/xml-name-validator/-/xml-name-validator-5.0.0.tgz", @@ -5278,6 +5374,19 @@ "integrity": "sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==", "dev": true, "license": "ISC" + }, + "node_modules/yocto-queue": { + "version": "0.1.0", + "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz", + "integrity": "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=10" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } } } } diff --git a/web/package.json b/web/package.json index e2de1ec..36eec91 100644 --- a/web/package.json +++ b/web/package.json @@ -28,8 +28,10 @@ "@types/node": "^22.10.2", "@types/react": "^18.3.12", "@types/react-dom": "^18.3.1", + "@types/subset-font": "2.3.0", "@vitejs/plugin-react": "^4.7.0", "jsdom": "^30.1.2", + "subset-font": "2.9.0", "tailwindcss": "^4.3.3", "typescript": "^5.6.3", "vite": "^6.4.3", diff --git a/web/src/styles.css b/web/src/styles.css index 2bf33ec..fbb3631 100644 --- a/web/src/styles.css +++ b/web/src/styles.css @@ -3,7 +3,7 @@ @import "./shadcn.css"; @import "@fontsource-variable/geist"; @import "@fontsource-variable/geist-mono"; -@import "@fontsource-variable/noto-sans-sc"; +@import "@panel-fonts"; @custom-variant dark (&:is(.dark *)); @theme inline { diff --git a/web/src/test/setup.ts b/web/src/test/setup.ts index 3e3cddc..cb5ceb1 100644 --- a/web/src/test/setup.ts +++ b/web/src/test/setup.ts @@ -3,8 +3,10 @@ import { cleanup } from "@testing-library/react"; afterEach(() => { cleanup(); vi.restoreAllMocks(); }); class ResizeObserverStub { observe() {} unobserve() {} disconnect() {} } vi.stubGlobal("ResizeObserver", ResizeObserverStub); -Element.prototype.scrollIntoView = () => {}; -Element.prototype.hasPointerCapture = () => false; -Element.prototype.setPointerCapture = () => {}; -Element.prototype.releasePointerCapture = () => {}; -document.elementFromPoint = () => null; +if (typeof document !== "undefined") { + Element.prototype.scrollIntoView = () => {}; + Element.prototype.hasPointerCapture = () => false; + Element.prototype.setPointerCapture = () => {}; + Element.prototype.releasePointerCapture = () => {}; + document.elementFromPoint = () => null; +} diff --git a/web/vite.config.ts b/web/vite.config.ts index a2a606d..c39648f 100644 --- a/web/vite.config.ts +++ b/web/vite.config.ts @@ -2,13 +2,23 @@ import { defineConfig } from "vite"; import react from "@vitejs/plugin-react"; import tailwindcss from "@tailwindcss/vite"; import { fileURLToPath, URL } from "node:url"; +import { panelFonts } from "./build/fonts"; -export default defineConfig({ - plugins: [react(), tailwindcss()], - resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } }, +export default defineConfig(({ command }) => ({ + plugins: [panelFonts(), react(), tailwindcss()], + resolve: { + alias: { + "@": fileURLToPath(new URL("./src", import.meta.url)), + "@panel-fonts": fileURLToPath(new URL( + `./.generated/${command === "serve" ? "fonts-dev" : "fonts"}/noto-sans-sc.css`, + import.meta.url, + )), + }, + }, build: { outDir: "../internal/webui/dist", emptyOutDir: true, + assetsInlineLimit: 0, }, server: { proxy: { @@ -26,4 +36,4 @@ export default defineConfig({ }, }, }, -}); +})); From a56782b29bab4bbb22e187ac8a02fd71e4395b34 Mon Sep 17 00:00:00 2001 From: vvbbnn00 Date: Sun, 11 Oct 2026 18:25:14 +0800 Subject: [PATCH 2/4] perf(webui): compress embedded web assets Store text assets as gzip and restore their original bytes for HTTP serving. Decode immutable assets once and give each request its own reader, preserving MIME types, HEAD, Range and cache behavior. Keep raw Vite output for preview, preserve the checkout marker and existing gzip sidecars, and test packing round trips and concurrent reads. --- .gitignore | 1 + Makefile | 2 +- docs/WEBUI.md | 6 +- internal/webui/assets.go | 94 ++++++++++++++++++++++ internal/webui/assets_test.go | 142 ++++++++++++++++++++++++++++++++++ internal/webui/server.go | 4 +- web/build/embed.test.ts | 50 ++++++++++++ web/build/embed.ts | 44 +++++++++++ web/vite.config.ts | 5 +- 9 files changed, 340 insertions(+), 8 deletions(-) create mode 100644 internal/webui/assets.go create mode 100644 internal/webui/assets_test.go create mode 100644 web/build/embed.test.ts create mode 100644 web/build/embed.ts diff --git a/.gitignore b/.gitignore index b02706d..cf8c749 100644 --- a/.gitignore +++ b/.gitignore @@ -18,5 +18,6 @@ # frontend web/node_modules/ web/.generated/ +web/dist/ internal/webui/dist/* !internal/webui/dist/.gitkeep diff --git a/Makefile b/Makefile index 5980532..50d2a88 100644 --- a/Makefile +++ b/Makefile @@ -1,6 +1,6 @@ .PHONY: web build -# Build the frontend into internal/webui/dist (requires Node 20+). +# Build into web/dist and copy packed assets into internal/webui/dist (requires Node 20+). # The postbuild npm script restores dist/.gitkeep so plain `go build` # keeps working on clean checkouts. web: diff --git a/docs/WEBUI.md b/docs/WEBUI.md index 478c2ae..7a533ac 100644 --- a/docs/WEBUI.md +++ b/docs/WEBUI.md @@ -507,7 +507,7 @@ web/ `vite.config.ts`: -- `build.outDir = '../internal/webui/dist'`,`build.emptyOutDir = true`。 +- `build.outDir = 'dist'`,`build.emptyOutDir = true`。`web/dist` 保留原始资源供 Vite preview 使用;构建插件将资源复制到 `internal/webui/dist`,其中 HTML、JS、CSS 等文本按 gzip 压缩存储,字体保持 WOFF2。Go 的 `assetFS` 每个资源仅解压一次,每次打开提供独立读取位置,保留 MIME、HEAD、Range 和缓存行为。 - 发布构建自动从前端源码和 Go 后端消息收集固定字符,裁剪 Noto Sans SC 字形,保留可变字重、hinting 和排版特性。Geist 与 Geist Mono 保留完整字库;动态内容中未内置的字形使用现有系统字体回退。开发模式保留完整 Noto Sans SC 字库,新增文案不需要手动维护字符清单。开发与发布构建分别使用 `web/.generated/fonts-dev` 和 `web/.generated/fonts`,避免互相覆盖。 - dev 代理必须兼容 §8 的 Host/Origin 校验(字符串简写会保留 5173 的 Host 与 Origin,导致全部请求 403): @@ -537,7 +537,7 @@ build: web go build -o geektrust ./cmd/geektrust ``` -`.gitkeep` 保全(关键):Vite `emptyOutDir=true` 会删除被跟踪的 `dist/.gitkeep`;只靠 Makefile 的 touch 步骤无法约束直接执行 `npm run build` 的门槛,删除一旦被提交,干净检出的 `go build` 会因 embed 无匹配文件而失败。因此由 `web/package.json` 的 `postbuild` 脚本负责重建(npm 在 build 后自动执行,跨平台 Node 实现,不依赖 shell): +`.gitkeep` 保全:嵌入资源复制步骤保留既有的 `internal/webui/dist/.gitkeep`,缺失时创建,保证干净检出的 `go build` 有匹配的 embed 文件;`web/package.json` 的 `postbuild` 脚本也保留该文件(npm 在 build 后自动执行,跨平台 Node 实现,不依赖 shell): ```json "scripts": { @@ -548,7 +548,7 @@ build: web 前端开发:`go run ./cmd/geektrust run`(终端 1)+ `npm --prefix web run dev`(终端 2,Vite 5173 端口)。不做进程编排。 -`internal/webui/dist` embed 规则:`//go:embed all:dist`(`all:` 前缀包含 `.gitkeep` 点文件,已核实可编译);git 中只跟踪 `dist/.gitkeep`。`Server` 启动时检测 `index.html` 缺失则页面路由返回占位页(200,说明"前端未构建,运行 make web"),API 不受影响。`.gitignore` 增加 `web/node_modules/` 与 `internal/webui/dist/*`(`!internal/webui/dist/.gitkeep`)。 +`internal/webui/dist` embed 规则:`//go:embed all:dist`(`all:` 前缀包含 `.gitkeep` 点文件,已核实可编译);git 中只跟踪 `dist/.gitkeep`。`Server` 启动时检测 `index.html` 和 `index.html.gz` 均缺失则页面路由返回占位页(200,说明"前端未构建,运行 make web"),API 不受影响。`.gitignore` 增加 `web/node_modules/`、`web/.generated/`、`web/dist/` 与 `internal/webui/dist/*`(`!internal/webui/dist/.gitkeep`)。 ### 9.3 页面布局 diff --git a/internal/webui/assets.go b/internal/webui/assets.go new file mode 100644 index 0000000..90c4596 --- /dev/null +++ b/internal/webui/assets.go @@ -0,0 +1,94 @@ +package webui + +import ( + "bytes" + "compress/gzip" + "errors" + "io" + "io/fs" + "strings" + "sync" +) + +// assetFS presents gzip-stored build assets as their original files. The +// HTTP file server keeps its existing MIME types, HEAD and Range behavior. +// Plain assets and the clean-checkout placeholder work through the same FS. +type assetFS struct { + fs.FS + mu sync.Mutex + loaded map[string]func() (*assetContent, error) +} + +func (f *assetFS) Open(name string) (fs.File, error) { + file, err := f.FS.Open(name) + if !errors.Is(err, fs.ErrNotExist) || !fs.ValidPath(name) { + return file, err + } + // Embedded assets are immutable. Decode each existing gzip file once; + // Stat, HEAD and subsequent requests still get independent file cursors. + f.mu.Lock() + load := f.loaded[name] + if load == nil { + packed, packedErr := f.FS.Open(name + ".gz") + if packedErr != nil { + f.mu.Unlock() + return nil, err + } + load = sync.OnceValues(func() (*assetContent, error) { return readAsset(packed) }) + if f.loaded == nil { + f.loaded = make(map[string]func() (*assetContent, error)) + } + f.loaded[name] = load + } + f.mu.Unlock() + content, err := load() + if err != nil { + return nil, err + } + return &assetFile{Reader: bytes.NewReader(content.data), info: content.info}, nil +} + +type assetContent struct { + data []byte + info assetInfo +} + +func readAsset(packed fs.File) (*assetContent, error) { + defer packed.Close() + info, err := packed.Stat() + if err != nil { + return nil, err + } + reader, err := gzip.NewReader(packed) + if err != nil { + return nil, err + } + data, readErr := io.ReadAll(reader) + closeErr := reader.Close() + if readErr != nil { + return nil, readErr + } + if closeErr != nil { + return nil, closeErr + } + return &assetContent{ + data: data, + info: assetInfo{FileInfo: info, size: int64(len(data))}, + }, nil +} + +type assetFile struct { + *bytes.Reader + info assetInfo +} + +func (f *assetFile) Stat() (fs.FileInfo, error) { return f.info, nil } +func (f *assetFile) Close() error { return nil } + +type assetInfo struct { + fs.FileInfo + size int64 +} + +func (i assetInfo) Name() string { return strings.TrimSuffix(i.FileInfo.Name(), ".gz") } +func (i assetInfo) Size() int64 { return i.size } diff --git a/internal/webui/assets_test.go b/internal/webui/assets_test.go new file mode 100644 index 0000000..03f4d74 --- /dev/null +++ b/internal/webui/assets_test.go @@ -0,0 +1,142 @@ +package webui + +import ( + "bytes" + "compress/gzip" + "errors" + "fmt" + "io" + "io/fs" + "net/http/httptest" + "strings" + "sync" + "sync/atomic" + "testing" + "testing/fstest" + "time" +) + +func gzipAsset(t *testing.T, data []byte) []byte { + t.Helper() + var packed bytes.Buffer + writer := gzip.NewWriter(&packed) + if _, err := writer.Write(data); err != nil { + t.Fatal(err) + } + if err := writer.Close(); err != nil { + t.Fatal(err) + } + return packed.Bytes() +} + +func TestCompressedAssetsPreserveHTTPBehavior(t *testing.T) { + html := "
" + script := "console.log('the original JavaScript');" + font := []byte("wOF2 unchanged font") + modified := time.Date(2025, 1, 2, 3, 4, 5, 0, time.UTC) + files := fstest.MapFS{ + "index.html.gz": {Data: gzipAsset(t, []byte(html)), ModTime: modified}, + "assets/panel.js.gz": {Data: gzipAsset(t, []byte(script)), ModTime: modified}, + "assets/panel.woff2": {Data: font, ModTime: modified}, + } + server := &Server{dist: &assetFS{FS: files}, hasUI: true} + for _, tc := range []struct { + name, method, path, header, value, body, contentType, cache string + status int + }{ + {"index", "GET", "/", "", "", html, "text/html", "no-cache", 200}, + {"script", "GET", "/assets/panel.js", "", "", script, "text/javascript", "public, max-age=31536000, immutable", 200}, + {"head", "HEAD", "/assets/panel.js", "", "", "", "text/javascript", "public, max-age=31536000, immutable", 200}, + {"range", "GET", "/assets/panel.js", "Range", "bytes=7-12", script[7:13], "text/javascript", "public, max-age=31536000, immutable", 206}, + {"not modified", "GET", "/assets/panel.js", "If-Modified-Since", modified.Format("Mon, 02 Jan 2006 15:04:05 GMT"), "", "", "public, max-age=31536000, immutable", 304}, + {"spa fallback", "GET", "/some/route", "", "", html, "text/html", "no-cache", 200}, + {"font", "GET", "/assets/panel.woff2", "", "", string(font), "", "public, max-age=31536000, immutable", 200}, + } { + t.Run(tc.name, func(t *testing.T) { + request := httptest.NewRequest(tc.method, tc.path, nil) + if tc.header != "" { + request.Header.Set(tc.header, tc.value) + } + response := httptest.NewRecorder() + server.handleStatic(response, request) + if response.Code != tc.status || response.Body.String() != tc.body { + t.Fatalf("response = %d %q, want %d %q", response.Code, response.Body.String(), tc.status, tc.body) + } + if !strings.HasPrefix(response.Header().Get("Content-Type"), tc.contentType) { + t.Errorf("Content-Type = %q", response.Header().Get("Content-Type")) + } + if response.Header().Get("Cache-Control") != tc.cache || response.Header().Get("Content-Encoding") != "" { + t.Errorf("unexpected cache or encoding headers: %v", response.Header()) + } + if tc.method == "HEAD" && response.Header().Get("Content-Length") != fmt.Sprint(len(script)) { + t.Errorf("HEAD length = %q, want %d", response.Header().Get("Content-Length"), len(script)) + } + if tc.name == "range" && response.Header().Get("Content-Range") != fmt.Sprintf("bytes 7-12/%d", len(script)) { + t.Errorf("Content-Range = %q", response.Header().Get("Content-Range")) + } + }) + } + response := httptest.NewRecorder() + server.handleStatic(response, httptest.NewRequest("GET", "/assets/missing.js", nil)) + if response.Code != 404 { + t.Fatalf("missing asset = %d", response.Code) + } +} + +func TestCompressedAssetCorruptionIsRejected(t *testing.T) { + packed := gzipAsset(t, []byte("original bytes")) + packed[len(packed)-8] ^= 1 // invalidate the CRC without damaging the header + files := &assetFS{FS: fstest.MapFS{"index.html.gz": {Data: packed}}} + if _, err := files.Open("index.html"); err == nil { + t.Fatal("accepted a corrupt compressed asset") + } + if _, err := files.Open("../index.html"); err == nil { + t.Fatal("accepted a path outside the embedded filesystem") + } + if _, err := files.Open("missing.js"); !errors.Is(err, fs.ErrNotExist) { + t.Fatalf("missing file: %v", err) + } +} + +type countedAssets struct { + fs.FS + packedOpens atomic.Int32 +} + +func (f *countedAssets) Open(name string) (fs.File, error) { + if strings.HasSuffix(name, ".gz") { + f.packedOpens.Add(1) + } + return f.FS.Open(name) +} + +func TestCompressedAssetLoadsOnceWithIndependentConcurrentReaders(t *testing.T) { + data := strings.Repeat("immutable web asset\n", 100) + base := &countedAssets{FS: fstest.MapFS{"panel.js.gz": {Data: gzipAsset(t, []byte(data))}}} + files := &assetFS{FS: base} + var group sync.WaitGroup + start := make(chan struct{}) + for range 20 { + group.Go(func() { + <-start + file, err := files.Open("panel.js") + if err != nil { + t.Error(err) + return + } + defer file.Close() + got, err := io.ReadAll(file) + if err != nil || string(got) != data { + t.Errorf("read = %q, %v", got, err) + } + }) + } + close(start) + group.Wait() + if info, err := fs.Stat(files, "panel.js"); err != nil || info.Size() != int64(len(data)) { + t.Fatalf("Stat = %v, %v", info, err) + } + if got := base.packedOpens.Load(); got != 1 { + t.Fatalf("gzip file opened %d times, want 1", got) + } +} diff --git a/internal/webui/server.go b/internal/webui/server.go index 263577d..e5f93cc 100644 --- a/internal/webui/server.go +++ b/internal/webui/server.go @@ -63,8 +63,8 @@ func NewServer(hub *Hub, broker *Broker, provider ProviderAPI, cfg *config.Confi ctx, cancel := context.WithCancel(context.Background()) s := &Server{hub: hub, broker: broker, provider: provider, cfg: cfg, lifetime: ctx, cancel: cancel} if sub, err := fs.Sub(distFS, "dist"); err == nil { - s.dist = sub - if f, err := sub.Open("index.html"); err == nil { + s.dist = &assetFS{FS: sub} + if f, err := s.dist.Open("index.html"); err == nil { f.Close() s.hasUI = true } diff --git a/web/build/embed.test.ts b/web/build/embed.test.ts new file mode 100644 index 0000000..87e933b --- /dev/null +++ b/web/build/embed.test.ts @@ -0,0 +1,50 @@ +// @vitest-environment node + +import { mkdtemp, mkdir, writeFile, readFile, readdir, realpath, rm } from "node:fs/promises"; +import { existsSync } from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { gzipSync, gunzipSync } from "node:zlib"; +import { build } from "vite"; +import { expect, test } from "vitest"; +import { embeddedAssets } from "./embed"; + +test("packed assets restore Vite output and preserve the checkout marker and existing gzip sidecars", async () => { + const directory = await realpath(await mkdtemp(path.join(os.tmpdir(), "panel-packed-assets-"))); + const root = path.join(directory, "web"); + const destination = path.join(directory, "internal/webui/dist"); + try { + await mkdir(path.join(root, "public"), { recursive: true }); + await mkdir(destination, { recursive: true }); + await writeFile(path.join(destination, ".gitkeep"), "checkout marker"); + await writeFile(path.join(destination, "stale.js"), "old build"); + await writeFile(path.join(root, "index.html"), ''); + await writeFile(path.join(root, "main.js"), `document.body.textContent = ${JSON.stringify("compressible text ".repeat(100))};`); + const json = JSON.stringify({ message: "current content ".repeat(100) }); + const sidecar = gzipSync(Buffer.from("previous gzip sidecar")); + await writeFile(path.join(root, "public/data.json"), json); + await writeFile(path.join(root, "public/data.json.gz"), sidecar); + await build({ root, configFile: false, logLevel: "silent", plugins: [embeddedAssets()] }); + expect(await readFile(path.join(destination, ".gitkeep"), "utf8")).toBe("checkout marker"); + expect(existsSync(path.join(destination, "stale.js"))).toBe(false); + expect(await readFile(path.join(destination, "data.json"), "utf8")).toBe(json); + expect(await readFile(path.join(destination, "data.json.gz"))).toEqual(sidecar); + let files = 0; + async function compare(relative: string): Promise { + for (const entry of await readdir(path.join(root, "dist", relative), { withFileTypes: true })) { + const name = path.join(relative, entry.name); + if (entry.isDirectory()) await compare(name); + else { + const target = path.join(destination, name); + const restored = existsSync(target) ? await readFile(target) : gunzipSync(await readFile(`${target}.gz`)); + expect(restored).toEqual(await readFile(path.join(root, "dist", name))); + files++; + } + } + } + await compare(""); + expect(files).toBeGreaterThan(2); + } finally { + await rm(directory, { recursive: true, force: true }); + } +}, 15000); diff --git a/web/build/embed.ts b/web/build/embed.ts new file mode 100644 index 0000000..ff144c3 --- /dev/null +++ b/web/build/embed.ts @@ -0,0 +1,44 @@ +import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises"; +import path from "node:path"; +import { gzipSync } from "node:zlib"; +import type { Plugin, ResolvedConfig } from "vite"; + +// Keep Vite's output intact for preview. Only the copy embedded in Go uses +// gzip storage; the Go filesystem restores the original bytes on open. +export function embeddedAssets(): Plugin { + let config: ResolvedConfig; + return { + name: "compressed-embedded-assets", + apply: "build", + configResolved(resolved) { config = resolved; }, + async writeBundle() { + const source = path.resolve(config.root, config.build.outDir); + const destination = path.resolve(config.root, "../internal/webui/dist"); + await mkdir(destination, { recursive: true }); + for (const entry of await readdir(destination)) { + if (entry !== ".gitkeep") await rm(path.join(destination, entry), { recursive: true, force: true }); + } + await writeFile(path.join(destination, ".gitkeep"), "", { flag: "a" }); + async function copy(directory: string): Promise { + const entries = await readdir(directory, { withFileTypes: true }); + const names = new Set(entries.map((entry) => entry.name)); + for (const entry of entries) { + const file = path.join(directory, entry.name); + const output = path.join(destination, path.relative(source, file)); + if (entry.isDirectory()) { + await mkdir(output, { recursive: true }); + await copy(file); + } else { + const data = await readFile(file); + // Do not overwrite an existing public gzip sidecar. + const compress = /\.(?:html|js|css|svg|json)$/.test(file) && !names.has(`${entry.name}.gz`); + const compressed = compress ? gzipSync(data, { level: 9 }) : data; + if (compressed.length < data.length) await writeFile(`${output}.gz`, compressed); + else await writeFile(output, data); + } + } + } + await copy(source); + }, + }; +} diff --git a/web/vite.config.ts b/web/vite.config.ts index c39648f..75b131b 100644 --- a/web/vite.config.ts +++ b/web/vite.config.ts @@ -3,9 +3,10 @@ import react from "@vitejs/plugin-react"; import tailwindcss from "@tailwindcss/vite"; import { fileURLToPath, URL } from "node:url"; import { panelFonts } from "./build/fonts"; +import { embeddedAssets } from "./build/embed"; export default defineConfig(({ command }) => ({ - plugins: [panelFonts(), react(), tailwindcss()], + plugins: [panelFonts(), react(), tailwindcss(), embeddedAssets()], resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)), @@ -16,7 +17,7 @@ export default defineConfig(({ command }) => ({ }, }, build: { - outDir: "../internal/webui/dist", + outDir: "dist", emptyOutDir: true, assetsInlineLimit: 0, }, From a9d22e2e3c3e8cc5112933a1025a729b7e897279 Mon Sep 17 00:00:00 2001 From: vvbbnn00 Date: Sun, 11 Oct 2026 18:26:25 +0800 Subject: [PATCH 3/4] build(release): increase gzip and ZIP compression levels Use gzip level 9 for tar archives and the highest Deflate level for ZIP packages without changing archive formats or package contents. --- scripts/package-release-uv.sh | 2 +- scripts/package-release.sh | 2 +- tools/zipdir/main.go | 4 ++++ 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/scripts/package-release-uv.sh b/scripts/package-release-uv.sh index 7c37cd9..89b7ed7 100755 --- a/scripts/package-release-uv.sh +++ b/scripts/package-release-uv.sh @@ -130,7 +130,7 @@ for target in "${targets[@]}"; do if [[ "$goos" == windows ]]; then go run ./tools/zipdir "$package_dir" "$output_dir/$package_name.zip" else - tar -C "$work_dir" -czf "$output_dir/$package_name.tar.gz" "$package_name" + tar -C "$work_dir" -cf - "$package_name" | gzip -9 > "$output_dir/$package_name.tar.gz" fi done diff --git a/scripts/package-release.sh b/scripts/package-release.sh index ba23eca..e71a2be 100755 --- a/scripts/package-release.sh +++ b/scripts/package-release.sh @@ -56,7 +56,7 @@ for target in "${targets[@]}"; do if [[ "$goos" == windows ]]; then go run ./tools/zipdir "$package_dir" "$archive" else - tar -C "$package_tmp" -czf "$archive" "$package_name" + tar -C "$package_tmp" -cf - "$package_name" | gzip -9 > "$archive" fi done diff --git a/tools/zipdir/main.go b/tools/zipdir/main.go index 06cff0b..a966946 100644 --- a/tools/zipdir/main.go +++ b/tools/zipdir/main.go @@ -4,6 +4,7 @@ package main import ( "archive/zip" + "compress/flate" "fmt" "io" "io/fs" @@ -54,6 +55,9 @@ func zipDir(source, output string) (err error) { }() archive := zip.NewWriter(out) + archive.RegisterCompressor(zip.Deflate, func(writer io.Writer) (io.WriteCloser, error) { + return flate.NewWriter(writer, flate.BestCompression) + }) defer func() { if closeErr := archive.Close(); err == nil { err = closeErr From 1a5e0da2b1df56b830467dc3146cdd99c8e379ad Mon Sep 17 00:00:00 2001 From: vvbbnn00 Date: Sun, 11 Oct 2026 18:48:27 +0800 Subject: [PATCH 4/4] test(webui): respect platform JavaScript MIME types --- internal/webui/assets_test.go | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/internal/webui/assets_test.go b/internal/webui/assets_test.go index 03f4d74..41cb698 100644 --- a/internal/webui/assets_test.go +++ b/internal/webui/assets_test.go @@ -7,6 +7,7 @@ import ( "fmt" "io" "io/fs" + "mime" "net/http/httptest" "strings" "sync" @@ -32,6 +33,8 @@ func gzipAsset(t *testing.T, data []byte) []byte { func TestCompressedAssetsPreserveHTTPBehavior(t *testing.T) { html := "
" script := "console.log('the original JavaScript');" + // Go uses the host MIME database, including the Windows registry. + javascriptType := mime.TypeByExtension(".js") font := []byte("wOF2 unchanged font") modified := time.Date(2025, 1, 2, 3, 4, 5, 0, time.UTC) files := fstest.MapFS{ @@ -45,9 +48,9 @@ func TestCompressedAssetsPreserveHTTPBehavior(t *testing.T) { status int }{ {"index", "GET", "/", "", "", html, "text/html", "no-cache", 200}, - {"script", "GET", "/assets/panel.js", "", "", script, "text/javascript", "public, max-age=31536000, immutable", 200}, - {"head", "HEAD", "/assets/panel.js", "", "", "", "text/javascript", "public, max-age=31536000, immutable", 200}, - {"range", "GET", "/assets/panel.js", "Range", "bytes=7-12", script[7:13], "text/javascript", "public, max-age=31536000, immutable", 206}, + {"script", "GET", "/assets/panel.js", "", "", script, javascriptType, "public, max-age=31536000, immutable", 200}, + {"head", "HEAD", "/assets/panel.js", "", "", "", javascriptType, "public, max-age=31536000, immutable", 200}, + {"range", "GET", "/assets/panel.js", "Range", "bytes=7-12", script[7:13], javascriptType, "public, max-age=31536000, immutable", 206}, {"not modified", "GET", "/assets/panel.js", "If-Modified-Since", modified.Format("Mon, 02 Jan 2006 15:04:05 GMT"), "", "", "public, max-age=31536000, immutable", 304}, {"spa fallback", "GET", "/some/route", "", "", html, "text/html", "no-cache", 200}, {"font", "GET", "/assets/panel.woff2", "", "", string(font), "", "public, max-age=31536000, immutable", 200},