modelstage 0.0.0-stage → 0.5.28

package/src/server/assets/bundle-probe.mjs

@@ -0,0 +1,94 @@
+// bundle-probe.mjs —— UnityFS 资源包预检（/api/bundle/probe 的数据层）
+//
+// 只做容器级预检（不解码纹理像素），实现与插件共用 tool/lib/bundle-probe-node.mjs（同一份真相）。
+// path 支持目录或文件：给目录时按稳定顺序挑资源包文件，并用 resolvedFile 回报实际用的那个。
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * 定位要预检的资源包文件（目录时按稳定顺序挑一个；挑不出就要求给文件路径，不猜）。
+ * @returns {{ok: true, resolvedFile: string, absFile: string} | {ok: false, status: number, body: object}}
+ */
+export function resolveProbeTarget(abs, rel) {
+  let resolvedFile = path.basename(abs);
+  let absFile = abs;
+  if (fs.statSync(abs).isDirectory()) {
+    const files = fs.readdirSync(abs, { withFileTypes: true })
+      .filter((e) => e.isFile() && !e.name.startsWith('.'))
+      .map((e) => e.name)
+      .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+    if (!files.length) {
+      return { ok: false, status: 404, body: { ok: false, error: '目录里没有文件', path: rel, code: 'ULB_ERR_NO_FILE' } };
+    }
+    const pick = files.length === 1 ? files[0] : files.find((n) => /\.(unity3d|bundle|assetbundle|bytes|ab)$/i.test(n));
+    if (!pick) {
+      return {
+        ok: false,
+        status: 400,
+        body: {
+          ok: false,
+          error: `目录里有 ${files.length} 个文件且无法判定哪个是资源包，请直接给文件路径`,
+          path: rel,
+          candidates: files.slice(0, 20),
+          code: 'ULB_ERR_BAD_ARGS',
+        },
+      };
+    }
+    resolvedFile = pick;
+    absFile = path.join(abs, pick);
+  }
+  if (!fs.existsSync(absFile) || !fs.statSync(absFile).isFile()) {
+    return { ok: false, status: 404, body: { ok: false, error: '资源包文件不存在', path: rel, code: 'ULB_ERR_NO_FILE' } };
+  }
+  return { ok: true, resolvedFile, absFile };
+}
+
+/**
+ * @param {{config: object, probe: object}} deps
+ */
+export function createBundleProbe({ config, probe }) {
+  const { readConfig } = config;
+  const { resolveSafe } = probe;
+
+  /**
+   * @returns {Promise<{status: number, body: object}>}
+   */
+  async function probeBundle(rootId, rel) {
+    const t0 = Date.now();
+    const cfg = readConfig().find((r) => r.id === rootId);
+    if (!cfg) {
+      return { status: 400, body: { ok: false, error: `未找到资源根: ${rootId}`, code: 'ULB_ERR_BAD_ARGS' } };
+    }
+    const abs = resolveSafe(cfg.path, rel);
+    if (!abs) return { status: 403, body: { ok: false, error: '路径越界', code: 'ULB_ERR_BAD_ARGS' } };
+    if (!fs.existsSync(abs)) {
+      return { status: 404, body: { ok: false, error: '路径不存在', path: rel, code: 'ULB_ERR_NO_FILE' } };
+    }
+
+    const target = resolveProbeTarget(abs, rel);
+    if (!target.ok) return { status: target.status, body: target.body };
+
+    let probeBundleBytes;
+    try {
+      // 本文件在 src/server/assets/ ⇒ 到项目根的 tool/lib/ 要退三层（早前写成两层，
+      //   解析成 src/tool/lib/… ⇒ 该诊断端点一直返回「加载预检模块失败: Cannot find module」）。
+      ({ probeBundleBytes } = await import('../../../tool/lib/bundle-probe-node.mjs'));
+    } catch (e) {
+      return {
+        status: 500,
+        body: { ok: false, error: `加载预检模块失败: ${e.message}`, code: 'ULB_ERR_CONTAINER_PARSE', ms: Date.now() - t0 },
+      };
+    }
+
+    let body;
+    try {
+      const bytes = new Uint8Array(fs.readFileSync(target.absFile));
+      body = probeBundleBytes(bytes);
+    } catch (e) {
+      body = { ok: false, error: e.message, code: 'ULB_ERR_CONTAINER_PARSE' };
+    }
+    return { status: 200, body: Object.assign({ resolvedFile: target.resolvedFile }, body, { ms: Date.now() - t0 }) };
+  }
+
+  return { probeBundle };
+}

package/src/server/assets/probe.mjs

@@ -0,0 +1,184 @@
+// probe.mjs —— 只读探测工具：版本号、atlas 键、贴图页、路径越界防护、MIME 表
+//
+// 都是纯函数或「只读文件头」的低成本操作，不持有状态、不写盘。
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** JS 系扩展名共用的 MIME：.js/.mjs/.mts/.cjs 四个键映射同一值，只在这里写一次 */
+const MIME_JS = 'text/javascript';
+/** 二进制兜底 MIME：.skel/.moc/.mtn 都是八位字节流 */
+const MIME_OCTET = 'application/octet-stream';
+const MIME = {
+  '.html': 'text/html', '.htm': 'text/html', '.js': MIME_JS, '.mjs': MIME_JS,
+  '.mts': MIME_JS, '.cjs': MIME_JS, '.css': 'text/css', '.png': 'image/png',
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon', '.json': 'application/json', '.webp': 'image/webp', '.woff': 'font/woff',
+  '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.atlas': 'text/plain', '.skel': MIME_OCTET,
+  '.mp3': 'audio/mpeg', '.ogg': 'audio/ogg', '.m4a': 'audio/mp4', '.wav': 'audio/wav',
+  '.txt': 'text/plain', '.map': 'application/json', '.webm': 'video/webm',
+  // Live2D 相关（天命之子资源）：moc 是二进制模型、mtn 是二进制动作，都按八位字节流发
+  '.moc': MIME_OCTET, '.mtn': MIME_OCTET,
+  '.moc3': 'application/octet-stream', '.phy': 'application/json',
+};
+
+const SPINE_EXT = new Set(['.skel', '.atlas', '.png', '.json', '.jpg', '.jpeg', '.webp']);
+
+/** 版本归一到主次版本（照抄 原版实现的 Ew：4.1.24 -> 4.1）。 */
+export function normalizeVersion(v) {
+  const t = String(v).split('.');
+  return t.length >= 2 ? `${t[0]}.${t[1]}` : String(v);
+}
+
+/**
+ * 探测二进制 .skel 的 Spine 版本（**照抄 原版实现的 Mw**）。
+ *
+ * 为什么不能用宽松正则：原版 只认它支持的版本区间
+ *   （2.x / 3.5-3.8 / 4.0-4.3 形式，后接点号与补丁号），
+ *   避免误匹配文件头里 hash 等处的数字。
+ * 探测不到时返回 **"4.0"**（与 原版 默认值一致）——
+ *   此前我返回空串，导致前端 getRuntimeWithFallback("") 选错运行时、渲染与 8801 不一致。
+ */
+export function detectSkelVersion(file) {
+  try {
+    const fd = fs.openSync(file, 'r');
+    const buf = Buffer.alloc(512);
+    const read = fs.readSync(fd, buf, 0, 512, 0);
+    fs.closeSync(fd);
+    if (read <= 0) return '4.0';
+    const s = buf.slice(0, read).toString('latin1')
+      .match(/(2\.\d+|3\.[5-8]|4\.[0-3])\.\d+[\w-]*/);
+    return s ? normalizeVersion(s[0]) : '4.0';
+  } catch {
+    return '4.0';
+  }
+}
+
+/**
+ * 探测 JSON 骨架的 Spine 版本（**照抄 原版实现的 ww**）。
+ *
+ * 此前我只对 .skel 探测，导致 41 个 .json 骨架模型 version 为空串（渲染不一致）。
+ * skeleton.spine 位于文件开头，故只读前 4KB，避免为 MB 级骨架整文件读盘。
+ */
+export function detectJsonVersion(file) {
+  try {
+    const fd = fs.openSync(file, 'r');
+    const buf = Buffer.alloc(4096);
+    const read = fs.readSync(fd, buf, 0, 4096, 0);
+    fs.closeSync(fd);
+    if (read <= 0) return '4.0';
+    const m = buf.slice(0, read).toString('utf8').match(/"spine"\s*:\s*"([^"]+)"/);
+    return m ? normalizeVersion(m[1]) : '4.0';
+  } catch {
+    return '4.0';
+  }
+}
+
+/**
+ * 解析 atlas 的 PMA（预乘 Alpha）声明（**照抄 原版实现的 Tp**）。
+ *
+ * 返回 true / false / **null（未声明 = 未知）**。
+ * 为什么不能硬编码 false：BD2 系 atlas 均未声明 pma，正确语义是"未知"，
+ *   应由前端做像素检测；硬编码 false 等于断言"非预乘"，会污染其判定，
+ *   导致与原始 原版 渲染不一致（实测踩坑）。
+ */
+export function detectAtlasPma(file) {
+  try {
+    const m = fs.readFileSync(file, 'utf8').match(/^pma:\s*(true|false)/m);
+    return m ? m[1] === 'true' : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 探测 Spine 二进制 .skel 文件的版本号（如 "4.1"）。
+ *
+ * 原理：Spine 二进制导出时，文件头区域包含版本字符串。
+ *   实测 BD2 资源前 40 字节可见 "4.1.11"（偏移约 8-14）。
+ *   只读前 64 字节 + 正则提取，成本极低（无需读取整个文件）。
+ *
+ * 返回主次版本（如 "4.1"），供模型对象选择对应运行时；探测失败返回 null，
+ *   由调用方回退到自动识别模式（原版实现的 runtimeMode:"auto"）。
+ *
+ * @param {string} file 绝对路径
+ * @returns {string|null} 如 "4.1"
+ */
+/**
+ * 从 .atlas 内容首行提取资源标识（归一 key 的来源）。
+ *
+ * 为什么从内容取而不是用目录名：
+ *   同一资源的目录命名可能大小写不统一（实测 Char000203_2 与 char000203），
+ *   且不同资源根/不同层级下目录结构各异；而 atlas 首行引用的贴图名是资源内部
+ *   一致的信息，用它做归一 key 更可靠 —— 原版与 Mod 只要贴图名相同即归一。
+ *
+ * 规则（刻意简化，不多此一举）：仅去扩展名 + 转小写。
+ *   保留 cutscene_ 前缀（立绘/技能是真实区分）、保留 _2/_3 形态后缀。
+ *   例：char000206.png -> "char000206"
+ *       CutScene_Char000203_2.png -> "cutscene_char000203_2"
+ *
+ * @param {string} file atlas 绝对路径
+ * @returns {string|null}
+ */
+export function detectAtlasKey(file) {
+  try {
+    const fd = fs.openSync(file, 'r');
+    const buf = Buffer.alloc(256);
+    const read = fs.readSync(fd, buf, 0, 256, 0);
+    fs.closeSync(fd);
+    if (read <= 0) return null;
+    const firstLine = buf.slice(0, read).toString('utf8').split('\n')[0].trim();
+    if (!firstLine) return null;
+    return firstLine.replace(/\.[^.]+$/, '').toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+/** 与前端 local-roots.js 的 buildModel 保持一致的构造逻辑（服务端版）。 */
+/**
+ * 解析 .atlas 内容，取出它引用的贴图页文件名。
+ *
+ * Spine atlas 格式：每个贴图页以「未缩进的图片文件名」开头（多页 atlas 会有多行这样的页头），
+ * 其后是缩进的属性行（size:/filter:/bounds:/rotate: 等）；区域名也可能未缩进，但不带图片扩展名。
+ * 因此判定规则：**未缩进 且 以图片扩展名结尾**的行 = 贴图页头。
+ *
+ * 为什么必须解析 atlas：同一目录可能同时存在多个资源
+ *   （实测 066402/cutscene 下有 cutscene_char066402 与 cutscene_char066402_camera），
+ *   若把「目录里所有图片」都当贴图，会把别的资源的贴图错配进来。
+ */
+export function parseAtlasPages(atlasPath) {
+  try {
+    // 先剥一次 BOM 再按行匹配。原因：JS 的 \s **包含 U+FEFF**，而 AssetStudio 导出的 atlas
+    //   首行是「BOM + 页名」（EF BB BF ...）⇒ 不剥的话首行被 /^[^\s]/ 判成"有前导空白"整行跳过
+    //   ⇒ 多页图集的**第一页页名丢失**（现场：NIKKE 根 247 个模型里 34 份 atlas 带 BOM，均丢第一页 ⇒ 贴图拿不到、画面空白）。
+    // 为什么前端 src/web/engine/textures.js 没这个坑：它**先 trim() 再匹配**，而 trim() 会把 U+FEFF
+    //   当空白吃掉 —— 所以那边页名本来就干净。这里剥 BOM 就是与"先 trim"等价，别删。
+    // 只剥解析用的文本：**不改 atlas 落盘字节、不改页名大小写**（产物必须逐字节不变）。
+    const txt = fs.readFileSync(atlasPath, 'utf8').replace(/^\uFEFF/, '');
+    const pages = [];
+    for (const line of txt.split('\n')) {
+      if (/^[^\s].*\.(png|jpg|jpeg|webp)\s*$/i.test(line)) pages.push(line.trim());
+    }
+    return pages;
+  } catch {
+    return [];
+  }
+}
+
+/** 校验并解析出安全的绝对路径；越界返回 null。 */
+export function resolveSafe(rootBase, relPath) {
+  const rel = String(relPath || '').replace(/^\/+/, '');
+  const abs = path.resolve(rootBase, rel);
+  const base = path.resolve(rootBase);
+  if (abs !== base && !abs.startsWith(base + path.sep)) return null;
+  return abs;
+}
+
+// 逐段编码路径：保留 / 分隔符，其余段各自 encodeURIComponent。
+// 为什么：Live2D 资源目录含中文（皮肤名）与括号等字符，必须编码；
+//   但整体 encodeURIComponent 会把 / 也编掉，破坏路径结构。
+export function encodePath(p) {
+  return String(p).split('/').map(encodeURIComponent).join('/');
+}
+
+export { MIME, SPINE_EXT };

package/src/server/core/config.mjs

@@ -0,0 +1,173 @@
+// config.mjs —— 资源根配置的读写与分组视图（config/resources.json 是唯一权威）
+
+//
+// 写回时保留原文件的注释头，避免系统写一次就把人工写的说明冲掉；
+// 写入走 tmp + rename，避免读到写了一半的内容。
+import fs from 'node:fs';
+import { createLogger } from './log.mjs';
+import path from 'node:path';
+import { parseJsonc } from '../../../tool/parse-jsonc.mjs';
+
+/** 服务端日志（统一形状 {at,level,tag,msg,detail}；error→stderr，其余→stdout） */
+const log = createLogger('config');
+
+/** @param {{root: string, configFile: string}} p */
+export function createConfig(p) {
+  const ROOT = p.root;
+  const CONFIG_FILE = p.configFile;
+
+/**
+ * 读配置（JSONC），返回生效的资源根数组。
+ *
+ * 职责划分（重要）：
+ *   资源根目录列表**只由 config/resources.json 负责**（唯一权威），
+ *   由用户在界面上选择文件夹后自动生成/写入（见 POST /api/roots）。
+ *   env 只负责部署差异类的单值（PORT、SPINE_RUNTIME_DIR 等），
+ *   不用于增删资源根 —— 结构性列表交给 JSON，避免两套真相源。
+ *
+ * @returns {Array<{id:string,name:string,path:string,enabled:boolean}>}
+ */
+function readConfig() {
+  try {
+    const cfg = parseJsonc(fs.readFileSync(CONFIG_FILE, 'utf8'), 'config/resources.json');
+    const roots = Array.isArray(cfg.roots) ? cfg.roots : [];
+    return roots.filter((r) => r && r.id && r.path && r.enabled !== false);
+  } catch (e) {
+    log.error('读取 config/resources.json 失败', { err: e.message });
+    return [];
+  }
+}
+
+/**
+ * 读配置里的**全部**资源根（含 enabled:false 的），供写路径使用。
+ *
+ * 为什么写路径不能复用 readConfig()：
+ *   readConfig() 是「运行时生效视图」，会把 enabled:false 的根过滤掉；
+ *   若拿它的结果写回文件，停用的根就会被静默删除（改一次别的根就丢一条配置）。
+ *   写路径必须基于完整列表做增删改，停用与否只是某个字段的值。
+ *
+ * 只做最小形状校验（id + path 必须存在），其余字段原样保留：
+ *   roots[] 还承载 names / icons / kind / profile 等附加配置，写回时不能丢。
+ *
+ * @returns {Array<object>} 完整资源根数组（保持文件中的顺序）
+ */
+function readConfigRaw() {
+  try {
+    const cfg = parseJsonc(fs.readFileSync(CONFIG_FILE, 'utf8'), 'config/resources.json');
+    const roots = Array.isArray(cfg.roots) ? cfg.roots : [];
+    return roots.filter((r) => r && typeof r === 'object' && r.id && r.path);
+  } catch (e) {
+    // 读不出来时抛出而不是返回空数组：写路径拿空列表写回会把整份配置清空
+    throw new Error(`读取 config/resources.json 失败: ${e.message}`);
+  }
+}
+
+/**
+ * 写回 config/resources.json（保留原文件注释头部）。
+ *
+ * 为什么保留注释头：配置文件带 // 注释（JSONC），若整文件用 JSON.stringify 覆盖，
+ *   注释会被冲掉；而注释是给"人"看的说明，系统自动生成时也应保留。
+ *
+ * 头部怎么取（重要）：只取**文件开头的连续注释/空行块**，不能"截到第一个 '{'"。
+ *   因为注释正文里也可能出现花括号（例如 icons 说明写了 `{ dir: 绝对路径 }`），
+ *   按第一个 { 截断会把注释切成半行、且新 JSON 的首行被并进该注释行 —— 整份文件随即解析失败
+ *   （实测：写入成功但回读报 "Unexpected non-whitespace character after JSON"，配置等于写坏）。
+ *
+ * 原子写入：先写 .tmp 再 rename，避免写到一半中断导致配置损坏。
+ *
+ * @param {Array} roots 资源根数组
+ */
+function writeConfig(roots) {
+  let header = readHeader();
+  if (!header) {
+    header = [
+      '// 本地资源根配置 —— 由界面「添加资源根」自动生成，也可手动编辑',
+      '// 文件格式：JSONC（标准 JSON + // 注释）；注释由 tool/parse-jsonc.mjs 剥离',
+      '// 字段：id(唯一标识) / name(显示名) / path(本机绝对路径) / enabled(默认 true)',
+      '',
+    ].join('\n');
+  }
+
+  const body = JSON.stringify({ roots }, null, 2);
+  fs.mkdirSync(path.dirname(CONFIG_FILE + '.tmp'), { recursive: true });
+  fs.writeFileSync(CONFIG_FILE + '.tmp', header + body + '\n', 'utf8');
+  fs.renameSync(CONFIG_FILE + '.tmp', CONFIG_FILE);
+}
+
+/**
+ * 取配置文件开头的注释块（连续的行首 // 与空行），作为写回时要保留的 header。
+ *
+ * 判据按**行**而不是按字符：从第一行开始，遇到第一行"不是注释也不是空行"就停。
+ *   这样注释里出现的花括号、引号都不会影响截断位置；返回值保证以换行结尾，
+ *   让新 JSON 从独立一行开始。
+ *
+ * @returns {string} 以换行结尾的注释块；文件不存在或无注释块时返回空串
+ */
+function readHeader() {
+  if (!fs.existsSync(CONFIG_FILE)) return '';
+  let old;
+  try {
+    old = fs.readFileSync(CONFIG_FILE, 'utf8');
+  } catch {
+    return '';
+  }
+  const lines = old.split('\n');
+  const keep = [];
+  for (const line of lines) {
+    const t = line.trim();
+    if (t === '' || t.startsWith('//')) keep.push(line);
+    else break;
+  }
+  if (!keep.length) return '';
+  return `${keep.join('\n')}\n`;
+}
+
+/**
+ * 按 name（显示名称 = 归一 key）把资源根归并成组，供前端直接渲染。
+ *
+ * 归一语义：name 相同的多个资源根合并为一个条目。
+ *   例：「棕色尘埃2 原版」与「棕色尘埃2 mod」两个目录若都命名为"棕色尘埃2"，
+ *      界面合并成一个"棕色尘埃2"，其下汇总各 root 的模型（原版 + mod 共存不覆盖）。
+ *
+ * @param {Array} roots 资源根数组
+ * @returns {Array<{name:string, rootCount:number, roots:Array}>}
+ */
+function buildGroups(roots) {
+  const map = new Map();
+  for (const r of roots) {
+    if (!map.has(r.name)) map.set(r.name, { name: r.name, rootCount: 0, roots: [] });
+    const g = map.get(r.name);
+    g.rootCount++;
+    g.roots.push({ id: r.id, path: r.path, exists: fs.existsSync(r.path) && fs.statSync(r.path).isDirectory() });
+  }
+  return [...map.values()].sort((a, b) => a.name.localeCompare(b.name, undefined, { numeric: true }));
+}
+
+/** 可导出/导入的配置文件清单（相对 config/ 的路径）。 */
+function exportableConfigFiles() {
+  const files = ['resources.json'];
+  const namesDir = path.join(ROOT, 'config', 'names');
+  try {
+    for (const n of fs.readdirSync(namesDir)) {
+      if (n.endsWith('.json')) files.push(`names/${n}`);
+    }
+  } catch { /* names 目录不存在则只有 resources.json */ }
+  return files;
+}
+
+/** 读取全部可导出配置的原始文本。 */
+function exportConfigFiles() {
+  const out = {};
+  for (const rel of exportableConfigFiles()) {
+    try {
+      out[rel] = fs.readFileSync(path.join(ROOT, 'config', rel), 'utf8');
+    } catch { /* 读不到就跳过该文件 */ }
+  }
+  return out;
+}
+
+  // readConfig     = 运行时生效视图（已滤掉 enabled:false），只读消费方用它
+  // readConfigRaw  = 完整列表（含停用），写路径必须用它，否则会丢配置
+  return { readConfig, readConfigRaw, writeConfig, buildGroups, exportableConfigFiles, exportConfigFiles, CONFIG_FILE };
+}
+

package/src/server/core/env-num.mjs

@@ -0,0 +1,60 @@
+// core/env-num.mjs —— 数值型 env 的统一读取（含非法值回落 + 告警）
+//
+// 为什么单独成模块：准入/探测这几处调参都要求"非法值回落缺省 + 一条 warn"，
+//   各写一遍就会出现"这处安静回落、那处直接 NaN 传下去"的分歧 ——
+//   而 NaN 传进比较表达式不会报错，只会让判据恒为 false（最隐蔽的一类失效）。
+//
+// 约定（三处调用方一致）：
+//   · 缺省（未设 / 空串）⇒ 直接返回 fallback，**不告警**（这是正常部署形态）
+//   · 设了但非法（NaN / 越界）⇒ 返回 fallback + **warn 一条**（不许静默用错值）
+//   · 合法 ⇒ 返回解析后的数字
+
+/**
+ * 读一个非负数值型 env。
+ * @param {string} name 变量名
+ * @param {number} fallback 缺省值
+ * @param {(level: string, msg: string, detail?: object) => void} [log] 日志函数（缺省 console.warn）
+ * @returns {number}
+ */
+export function readNumericEnv(name, fallback, log) {
+  const raw = (process.env[name] || '').trim();
+  if (!raw) return fallback;
+  const n = Number(raw);
+  if (Number.isFinite(n) && n >= 0) return n;
+  warnOnce(log, name, raw, fallback, '需要非负数字');
+  return fallback;
+}
+
+/**
+ * 读一个"比例"型 env（必须落在 (0, 1] 区间）。
+ * @param {string} name
+ * @param {number} fallback 缺省比例（如 0.85 / 0.5）
+ * @param {(level: string, msg: string, detail?: object) => void} [log]
+ * @returns {number}
+ */
+export function readRatioEnv(name, fallback, log) {
+  const raw = (process.env[name] || '').trim();
+  if (!raw) return fallback;
+  const n = Number(raw);
+  if (Number.isFinite(n) && n > 0 && n <= 1) return n;
+  warnOnce(log, name, raw, fallback, '需要 (0,1] 区间的小数（例如 0.85）');
+  return fallback;
+}
+
+/** 告警（带去重：同一次启动里同一个变量只告一次，避免每请求刷屏） */
+const warned = new Set();
+function warnOnce(log, name, raw, fallback, hint) {
+  if (warned.has(name)) return;
+  warned.add(name);
+  const msg = `环境变量 ${name}=${JSON.stringify(raw)} 非法（${hint}）—— 已回落缺省 ${fallback}`;
+  try {
+    if (typeof log === 'function') log('warn', msg, { name, raw, fallback });
+    else if (log && typeof log.warn === 'function') log.warn(msg, { name, raw, fallback });
+    else if (typeof console !== 'undefined' && console.warn) console.warn(msg);
+  } catch { /* 日志失败也不能影响取值 */ }
+}
+
+/** 测试用：清掉"已告警"记录（同进程多次构造时才能重新告警） */
+export function resetEnvWarnings() {
+  warned.clear();
+}

package/src/server/core/env.mjs

@@ -0,0 +1,49 @@
+// env.mjs —— 项目根 .env 的极简解析（零依赖）
+
+const log = createLogger('brand');
+//
+// 不引入 dotenv：只需要 KEY=VALUE、注释、成对引号剥除这几条规则。
+// 每次调用都重读文件，改完 .env 刷新页面即生效。
+import fs from 'node:fs';
+import { createLogger } from './log.mjs';
+
+/** @param {{dotenvFile: string}} p 由 createPaths() 产出 */
+export function createEnv(p) {
+  const DOTENV_FILE = p.dotenvFile;
+  const ENV_FLAG_TRUE = new Set(['1', 'true', 'on', 'yes']);
+  const ENV_FLAG_FALSE = new Set(['0', 'false', 'off', 'no']);
+
+function readDotEnv() {
+  const out = {};
+  try {
+    if (!fs.existsSync(DOTENV_FILE)) return out;
+    const text = fs.readFileSync(DOTENV_FILE, 'utf8');
+    for (const rawLine of text.split(/\r?\n/)) {
+      const line = rawLine.trim();
+      if (!line || line.startsWith('#')) continue;
+      const eq = line.indexOf('=');
+      if (eq <= 0) continue;
+      const key = line.slice(0, eq).trim();
+      let val = line.slice(eq + 1).trim();
+      if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+        val = val.slice(1, -1);
+      }
+      if (key) out[key] = val;
+    }
+  } catch (e) {
+    log.warn('读取 .env 失败，按内置默认处理', { err: e.message });
+  }
+  return out;
+}
+
+function parseEnvFlag(raw) {
+  const v = String(raw == null ? '' : raw).trim().toLowerCase();
+  if (!v) return null;
+  if (ENV_FLAG_TRUE.has(v)) return true;
+  if (ENV_FLAG_FALSE.has(v)) return false;
+  return null;
+}
+
+  return { readDotEnv, parseEnvFlag, DOTENV_FILE };
+}
+

package/src/server/core/fs-portable.mjs

@@ -0,0 +1,37 @@
+// core/fs-portable.mjs —— 跨文件系统的可移植文件操作
+//
+// 为什么需要这一层：CIFS/SMB 挂载不允许改权限位，而 Node 的 fs.copyFileSync
+//   在 libuv 层复制完字节后会 fchmod 把源权限位套到目标文件 —— 于是在 SMB 上
+//   稳定报 EPERM。对照实验：
+//     fs.copyFileSync(src, dst)              → EPERM
+//     readFileSync + writeFileSync           → OK
+//     openSync('w') + writeSync + close      → OK
+//   所以不是目录不存在、也不是路径拼错，就是复制之后那次改权限。
+
+import fs from 'node:fs';
+
+/**
+ * 复制文件，在不能改权限的文件系统上自动降级。
+ *
+ * 策略：普通盘先走内核复制（大文件明显更快）；只有 EPERM / ENOTSUP 这两种
+ *   "这块文件系统不支持"的错误才降级成纯字节复制。其它错误一律往上抛 ——
+ *   绝不把真问题（源不存在、磁盘满、路径越界）也吞成"复制成功或静默失败"。
+ *
+ * 为什么不是 async：调用点（配置备份、损坏文件留证）都在同步流程里，
+ *   改成 Promise 会把整条写入管道染成异步，收益为零、风险变大。
+ *
+ * @param {string} src 源文件路径
+ * @param {string} dst 目标文件路径（父目录必须已存在，与 fs.copyFileSync 一致）
+ * @returns {void}
+ */
+export function copyFilePortable(src, dst) {
+  try {
+    fs.copyFileSync(src, dst);
+  } catch (e) {
+    // 只对"这块文件系统不支持改权限"的两种错误降级；其它照抛
+    if (e.code !== 'EPERM' && e.code !== 'ENOTSUP') throw e;
+    // 纯字节复制：读全量再写回，不碰权限位，实测在 CIFS/SMB 上可用。
+    //   内存代价 = 文件大小（配置文件都是 KB 级；这里不做流式，避免再引入一条出错路径）
+    fs.writeFileSync(dst, fs.readFileSync(src));
+  }
+}