@code2rich/jpage 1.5.0

package/lib/crypto.js

@@ -0,0 +1,85 @@
+// Token 明文可逆加密：AES-256-GCM。
+//
+// 用途：API Token 创建时除存 SHA-256 哈希（用于鉴权比对，不可逆）外，
+// 另存一份 AES-256-GCM 密文，使 token 明文可在用户登录后再次查看/复制。
+// 鉴权链路（lib/middleware/auth.js）完全不依赖本模块，仍走哈希比对。
+//
+// 密钥来源（优先级）：
+//   1. 环境变量 TOKEN_ENCRYPTION_KEY（hex；若长度不足 32 字节则用 sha256 派生到 32 字节）
+//   2. 数据目录下的 token-key.key 文件（hex 文本，重启不变）
+//   3. 上述文件不存在 → 生成 32 随机字节写入该文件后再读取
+// 不设置环境变量时也能开箱即用，不破坏现有部署。
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { DATA_DIR } = require('./paths');
+
+const KEY_FILE = path.join(DATA_DIR, 'token-key.key');
+const ALGO = 'aes-256-gcm';
+const IV_LEN = 12; // GCM 推荐 96-bit IV
+
+// 解析为 32 字节密钥：合法 hex(64) 直接用，否则 sha256 派生。
+function deriveKey(raw) {
+  if (!raw) return null;
+  const trimmed = String(raw).trim();
+  if (/^[0-9a-fA-F]{64}$/.test(trimmed)) {
+    return Buffer.from(trimmed, 'hex');
+  }
+  return crypto.createHash('sha256').update(trimmed).digest();
+}
+
+// 读取或生成持久化密钥文件（hex 文本）。
+function loadKeyFile() {
+  try {
+    if (fs.existsSync(KEY_FILE)) {
+      const hex = fs.readFileSync(KEY_FILE, 'utf8').trim();
+      if (/^[0-9a-fA-F]{64}$/.test(hex)) return Buffer.from(hex, 'hex');
+    }
+  } catch (_) { /* 读取失败则走生成路径 */ }
+
+  // 生成并写入（0600，仅属主可读写）
+  const key = crypto.randomBytes(32);
+  try {
+    fs.mkdirSync(DATA_DIR, { recursive: true });
+    fs.writeFileSync(KEY_FILE, key.toString('hex'), { mode: 0o600 });
+  } catch (_) { /* 写入失败时退回内存密钥（重启后旧密文不可解密） */ }
+  return key;
+}
+
+let _key = process.env.TOKEN_ENCRYPTION_KEY ? deriveKey(process.env.TOKEN_ENCRYPTION_KEY) : loadKeyFile();
+
+// 供测试重置密钥（按环境变量/文件重新解析）。
+function reloadKey() {
+  _key = process.env.TOKEN_ENCRYPTION_KEY ? deriveKey(process.env.TOKEN_ENCRYPTION_KEY) : loadKeyFile();
+  return _key;
+}
+
+// 密文格式：base64(iv) : base64(ciphertext) : base64(authTag)
+function encryptToken(plain) {
+  const iv = crypto.randomBytes(IV_LEN);
+  const cipher = crypto.createCipheriv(ALGO, _key, iv);
+  const enc = Buffer.concat([cipher.update(String(plain), 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return [iv.toString('base64'), enc.toString('base64'), tag.toString('base64')].join(':');
+}
+
+// 解密失败抛错（由调用方捕获并转友好提示）。
+function decryptToken(encStr) {
+  const parts = String(encStr || '').split(':');
+  if (parts.length !== 3) throw new Error('invalid ciphertext format');
+  const [ivB, dataB, tagB] = parts;
+  const iv = Buffer.from(ivB, 'base64');
+  const data = Buffer.from(dataB, 'base64');
+  const tag = Buffer.from(tagB, 'base64');
+  const decipher = crypto.createDecipheriv(ALGO, _key, iv);
+  decipher.setAuthTag(tag);
+  const dec = Buffer.concat([decipher.update(data), decipher.final()]);
+  return dec.toString('utf8');
+}
+
+module.exports = {
+  encryptToken,
+  decryptToken,
+  reloadKey,
+};

package/lib/csp.js

@@ -0,0 +1,66 @@
+// 分级 CSP（内容安全策略）策略。
+//
+// 设计：管理界面与用户内容渲染页用不同策略，平衡安全与功能：
+//   - 管理界面（app.js / index.html）：严格策略，只放行同源 + 内联 style（前端大量用 inline style）。
+//   - Markdown 渲染页：较严格，内联脚本靠 nonce 放行（mermaid 初始化）。
+//   - HTML 渲染页（用户原始 HTML，常含合法 script/外链）：宽松，依赖 iframe sandbox 兜底。
+//
+// nonce 方案：每次渲染 Markdown 生成随机 nonce，注入到模板内联 <script> 与响应头，
+// 不依赖具体脚本内容（模板内容变动不会让 CSP 失效）。
+
+const crypto = require('crypto');
+
+// 管理界面：无内联 script（仅一个外链 module + 外链 css），style 需要 unsafe-inline（前端海量 inline style）。
+const APP_CSP = [
+  "default-src 'self'",
+  "script-src 'self'",
+  "style-src 'self' 'unsafe-inline'",
+  "img-src 'self' data: blob:",
+  "font-src 'self'",
+  "connect-src 'self'",
+  "frame-src 'self'",
+  "frame-ancestors 'none'",
+].join('; ');
+
+// Markdown 渲染页：内联 mermaid 初始化脚本靠 nonce 放行，vendor 资源同源。
+function markdownCsp(nonce) {
+  return [
+    "default-src 'self'",
+    `script-src 'self' 'nonce-${nonce}'`,
+    "style-src 'self' 'unsafe-inline'",
+    "img-src 'self' data: blob:",
+    "font-src 'self'",
+    "connect-src 'self'",
+    "frame-ancestors 'none'",
+  ].join('; ');
+}
+
+// HTML 渲染页：用户 HTML 常含合法 script/外链资源，宽松策略 + iframe sandbox 兜底。
+// 放开 https: 让用户的图表库/CDN/图片能加载；sandbox 去掉 allow-same-origin 阻断对父窗口的访问。
+const HTML_CSP = [
+  "default-src 'self'",
+  "script-src 'self' 'unsafe-inline' https:",
+  "style-src 'self' 'unsafe-inline' https:",
+  "img-src 'self' data: blob: https:",
+  "font-src 'self' https: data:",
+  "connect-src 'self' https:",
+  "frame-ancestors 'none'",
+].join('; ');
+
+// 判断请求路径是否为用户内容渲染端点（这些端点由路由内自行 setHeader，中间件跳过）。
+function isRenderPath(reqPath) {
+  return /^\/api\/files\/\d+\/(render|versions\/\d+\/render|asset\/)/.test(reqPath) || /^\/s\//.test(reqPath);
+}
+
+// 生成 nonce（base64，128bit）
+function generateNonce() {
+  return crypto.randomBytes(16).toString('base64');
+}
+
+module.exports = {
+  APP_CSP,
+  HTML_CSP,
+  markdownCsp,
+  isRenderPath,
+  generateNonce,
+};

package/lib/db.js

@@ -0,0 +1,53 @@
+// SQLite 数据库访问层。
+// db 实例由 server.js 创建并通过 setDb() 注入；之后 dbRun/dbGet/dbAll 即可使用。
+// 从 server.js 提取，行为保持不变。
+
+const { dbRun: _dbRun, dbGet: _dbGet, dbAll: _dbAll } = require('../migrations');
+
+let db = null;
+
+function setDb(instance) {
+  db = instance;
+}
+
+function getDb() {
+  return db;
+}
+
+function dbRun(sql, params = []) {
+  return _dbRun(db, sql, params);
+}
+
+function dbGet(sql, params = []) {
+  return _dbGet(db, sql, params);
+}
+
+function dbAll(sql, params = []) {
+  return _dbAll(db, sql, params);
+}
+
+// --- SQLite 性能 PRAGMA ---
+// 在任何查询前应用：WAL 让读写不互斥（并发提升），synchronous=NORMAL 减少每次提交的 fsync，
+// busy_timeout 在写冲突时自动重试，cache_size/temp_store/mmap_size 提升读吞吐。
+function configureDatabase() {
+  return new Promise((resolve, reject) => {
+    db.exec(
+      `PRAGMA journal_mode=WAL;
+       PRAGMA synchronous=NORMAL;
+       PRAGMA busy_timeout=5000;
+       PRAGMA cache_size=-20000;
+       PRAGMA temp_store=MEMORY;
+       PRAGMA mmap_size=268435452;`,
+      (err) => (err ? reject(err) : resolve())
+    );
+  });
+}
+
+module.exports = {
+  setDb,
+  getDb,
+  dbRun,
+  dbGet,
+  dbAll,
+  configureDatabase,
+};

package/lib/dispatch.js

@@ -0,0 +1,103 @@
+// 进程内请求分发：让 MCP tool 不再走 fetch('http://127.0.0.1:port/...') 自调用，
+// 而是直接调用同一个 Express app 的路由栈，绕过 TCP 序列化 + 二次鉴权 DB 查询。
+//
+// 接口与 buildApiClient 完全一致：{ get, post, put, del }，path 以 /api/... 开头，
+// 返回 Promise<解析后的 JSON>，失败抛 Error（与 fetch 路径相同：`REST <method> <path> -> <status> <msg>`）。
+//
+// 实现要点：
+//   - 用 net.Socket 作为 req 的 connection/socket，保证流的销毁生命周期正常；
+//   - 合成 IncomingMessage（method/url/headers/body），模拟一次 HTTP 请求；
+//   - 合成 ServerResponse，缓存 write/end 的字节，结束后解析 JSON；
+//   - 通过 app.handle(req, res) 走完整中间件链（含 requireAuth、限流、审计），保证行为与 HTTP 一致；
+//   - 认证靠 Authorization: Bearer <token> 头，复用现有 requireAuth 逻辑。
+const http = require('http');
+const net = require('net');
+
+function makeSocket() {
+  // 一个未连接的真实 net.Socket：满足 Node 流销毁对 connection 类型的要求。
+  const socket = new net.Socket({ handle: undefined });
+  socket.remoteAddress = '127.0.0.1';
+  socket.destroy = () => {};
+  return socket;
+}
+
+function createDispatcher(app, { token }) {
+  function call(method, path, body) {
+    return new Promise((resolve, reject) => {
+      const headers = { host: '127.0.0.1' };
+      if (token) headers.authorization = 'Bearer ' + token;
+      let payloadBuf = null;
+      if (body !== undefined) {
+        payloadBuf = Buffer.from(JSON.stringify(body), 'utf8');
+        headers['content-type'] = 'application/json';
+        headers['content-length'] = String(payloadBuf.length);
+      }
+
+      // 合成请求（基于真实 socket）
+      const socket = makeSocket();
+      const req = new http.IncomingMessage(socket);
+      req.method = method.toUpperCase();
+      req.url = path;
+      req.headers = headers;
+      req.httpVersion = '1.1';
+      req.httpVersionMajor = 1;
+      req.httpVersionMinor = 1;
+      if (payloadBuf) req.push(payloadBuf);
+      req.push(null);
+
+      // 合成响应
+      const res = new http.ServerResponse(req);
+      const chunks = [];
+      res.write = function (chunk) { if (chunk) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)); return true; };
+      const _headers = {};
+      res.writeHead = function (status, h) { res.statusCode = status; if (h) Object.assign(_headers, h); return this; };
+      res.setHeader = function (k, v) { _headers[String(k).toLowerCase()] = Array.isArray(v) ? v.join(', ') : String(v); return this; };
+      res.getHeader = function (k) { return _headers[String(k).toLowerCase()]; };
+      res.removeHeader = function (k) { delete _headers[String(k).toLowerCase()]; return this; };
+      const finished = () => {
+        const buf = Buffer.concat(chunks);
+        const text = buf.toString('utf8');
+        let data = null;
+        if (text) { try { data = JSON.parse(text); } catch { data = { raw: text }; } }
+        const status = res.statusCode || 200;
+        if (status < 200 || status >= 300) {
+          const msg = (data && data.error) || ('HTTP ' + status) || 'unknown error';
+          const err = new Error('REST ' + method.toUpperCase() + ' ' + path + ' -> ' + status + ' ' + msg);
+          err.status = status;
+          return reject(err);
+        }
+        resolve(data);
+      };
+      let ended = false;
+      res.end = function (chunk) {
+        if (ended) return this;
+        ended = true;
+        if (chunk) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        finished();
+        return this;
+      };
+
+      // 走完整 Express 中间件链
+      try {
+        app.handle(req, res, () => {
+          // 未匹配任何路由 → 404
+          if (!ended) {
+            res.statusCode = 404;
+            chunks.push(Buffer.from(JSON.stringify({ error: 'Not Found' })));
+            finished();
+          }
+        });
+      } catch (e) {
+        if (!ended) reject(e);
+      }
+    });
+  }
+  return {
+    get: (path) => call('GET', path),
+    post: (path, body) => call('POST', path, body),
+    put: (path, body) => call('PUT', path, body),
+    del: (path) => call('DELETE', path),
+  };
+}
+
+module.exports = { createDispatcher };

package/lib/fts.js

@@ -0,0 +1,81 @@
+// FTS5 全文搜索：索引写入 / 删除 / 回填 / 查询转义。
+// 从 server.js 提取，行为保持不变。
+
+const fs = require('fs');
+const path = require('path');
+const logger = require('../logger');
+const { dbRun, dbGet, dbAll } = require('./db');
+const { UPLOAD_DIR } = require('./paths');
+
+const FTS_INDEXABLE_EXTS = new Set(['.html', '.htm', '.md', '.markdown', '.txt']);
+const FTS_MAX_CONTENT_SIZE = 100 * 1024; // 100KB
+
+function isFtsIndexable(fileType, storedName) {
+  if (fileType === 'bundle') return false;
+  const ext = path.extname(storedName || '').toLowerCase();
+  return FTS_INDEXABLE_EXTS.has(ext);
+}
+
+async function indexFileContent(fileId, storedName) {
+  try {
+    const filePath = path.join(UPLOAD_DIR, storedName);
+    if (!fs.existsSync(filePath)) return;
+    let content = await fs.promises.readFile(filePath, 'utf-8');
+    if (content.length > FTS_MAX_CONTENT_SIZE) content = content.slice(0, FTS_MAX_CONTENT_SIZE);
+    // 去除 HTML 标签，只保留纯文本用于索引
+    content = content.replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+    // 对 CJK 字符逐字加空格，使 unicode61 tokenizer 能按字符分词
+    content = content.replace(/([一-鿿])/g, ' $1 ');
+    content = content.replace(/\s+/g, ' ').trim();
+    await dbRun('DELETE FROM file_contents_fts WHERE file_id = ?', [fileId]);
+    await dbRun('INSERT INTO file_contents_fts(rowid, file_id, content) VALUES (?, ?, ?)', [fileId, fileId, content]);
+  } catch (e) {
+    logger.error({ type: 'app', message: 'FTS 索引失败', fileId, error: e.message });
+  }
+}
+
+async function deleteFileIndex(fileId) {
+  try {
+    await dbRun('DELETE FROM file_contents_fts WHERE file_id = ?', [fileId]);
+  } catch (e) {
+    logger.error({ type: 'app', message: 'FTS 删除索引失败', fileId, error: e.message });
+  }
+}
+
+async function backfillFtsIndex() {
+  try {
+    const count = await dbGet('SELECT COUNT(*) AS cnt FROM file_contents_fts');
+    if (count.cnt > 0) return;
+    const files = await dbAll('SELECT id, stored_name, file_type, is_bundle FROM files');
+    let indexed = 0;
+    for (const f of files) {
+      if (f.is_bundle) continue;
+      if (!isFtsIndexable(f.file_type, f.stored_name)) continue;
+      await indexFileContent(f.id, f.stored_name);
+      indexed++;
+    }
+    if (indexed > 0) logger.info({ type: 'app', message: 'FTS 索引回填完成', count: indexed });
+  } catch (e) {
+    logger.error({ type: 'app', message: 'FTS 索引回填失败', error: e.message });
+  }
+}
+
+function escapeFtsQuery(q) {
+  // 移除 FTS5 特殊字符
+  let cleaned = q.replace(/["'*:(){}[\]\\^+\-&|!~]/g, ' ').replace(/\s+/g, ' ').trim();
+  if (!cleaned) return '';
+  // 对 CJK 字符逐字加空格，与索引时一致
+  cleaned = cleaned.replace(/([一-鿿])/g, ' $1 ').replace(/\s+/g, ' ').trim();
+  // 对每个 token 加引号，避免 FTS5 语法错误
+  return cleaned.split(/\s+/).map(w => `"${w}"`).join(' ');
+}
+
+module.exports = {
+  FTS_INDEXABLE_EXTS,
+  FTS_MAX_CONTENT_SIZE,
+  isFtsIndexable,
+  indexFileContent,
+  deleteFileIndex,
+  backfillFtsIndex,
+  escapeFtsQuery,
+};

package/lib/middleware/auth.js

@@ -0,0 +1,114 @@
+// 认证与授权中间件：requireAuth（Session / Bearer Token / MCP_TOKEN）+ requireAdmin。
+// 从 server.js 提取，行为保持不变。
+
+const crypto = require('crypto');
+const { dbGet, dbRun } = require('../db');
+const { now } = require('../util');
+const { getAdminUserId } = require('../auth-state');
+
+// 软认证：尽力解析 Session/Bearer Token 并填充 req.userId / req.userRole，
+// 但不拒绝匿名请求。用于「允许匿名访问公开内容、同时让登录用户/admin 访问受限内容」
+// 的端点（详情 / 渲染 / 下载 / 资源 / 短链）。
+// 与 requireAuth 共用解析逻辑，仅在未通过认证时不返回 401 而是放行。
+async function loadSession(req, res, next) {
+  // Session 路径
+  if (req.session && req.session.userId) {
+    req.userId = req.session.userId;
+    if (req.session.userRole) {
+      req.userRole = req.session.userRole;
+    } else {
+      const user = await dbGet('SELECT role FROM users WHERE id = ?', [req.session.userId]);
+      if (user) {
+        req.session.userRole = user.role;
+        req.userRole = user.role;
+      }
+    }
+    return next();
+  }
+
+  // Bearer Token 路径（与 requireAuth 一致，成功才填充）
+  const auth = req.headers.authorization;
+  if (auth && auth.startsWith('Bearer ')) {
+    const tokenValue = auth.slice(7);
+    const adminUserId = getAdminUserId();
+    if (process.env.MCP_TOKEN && tokenValue === process.env.MCP_TOKEN && adminUserId) {
+      req.userId = adminUserId;
+      const admin = await dbGet('SELECT role FROM users WHERE id = ?', [adminUserId]);
+      req.userRole = admin ? admin.role : 'admin';
+      return next();
+    }
+    const hash = crypto.createHash('sha256').update(tokenValue).digest('hex');
+    const tokenRow = await dbGet(
+      'SELECT t.user_id, u.role FROM tokens t JOIN users u ON t.user_id = u.id WHERE t.token_hash = ?',
+      [hash]
+    );
+    if (tokenRow) {
+      dbRun('UPDATE tokens SET last_used_at = ? WHERE token_hash = ?', [now(), hash]).catch(() => {});
+      req.userId = tokenRow.user_id;
+      req.userRole = tokenRow.role;
+      return next();
+    }
+  }
+
+  // 未通过认证：放行（由下游中间件如 loadFileWithPrivacy 决定是否拒绝）
+  return next();
+}
+
+async function requireAuth(req, res, next) {
+  // Session 路径
+  if (req.session && req.session.userId) {
+    req.userId = req.session.userId;
+    // 从 session 读取 role，若旧 session 无 role 则从 DB 回填
+    if (req.session.userRole) {
+      req.userRole = req.session.userRole;
+    } else {
+      const user = await dbGet('SELECT role FROM users WHERE id = ?', [req.session.userId]);
+      if (!user) {
+        req.session.destroy(() => {});
+        return res.status(401).json({ error: '未登录' });
+      }
+      req.session.userRole = user.role;
+      req.userRole = user.role;
+    }
+    return next();
+  }
+
+  // Bearer Token 路径
+  const auth = req.headers.authorization;
+  if (auth && auth.startsWith('Bearer ')) {
+    const tokenValue = auth.slice(7);
+
+    // 1. 旧 MCP_TOKEN 向后兼容
+    const adminUserId = getAdminUserId();
+    if (process.env.MCP_TOKEN && tokenValue === process.env.MCP_TOKEN && adminUserId) {
+      req.mcpUserId = adminUserId;
+      req.userId = adminUserId;
+      const admin = await dbGet('SELECT role FROM users WHERE id = ?', [adminUserId]);
+      req.userRole = admin ? admin.role : 'admin';
+      return next();
+    }
+
+    // 2. 用户级 Token 查询
+    const hash = crypto.createHash('sha256').update(tokenValue).digest('hex');
+    const tokenRow = await dbGet(
+      'SELECT t.user_id, u.role FROM tokens t JOIN users u ON t.user_id = u.id WHERE t.token_hash = ?',
+      [hash]
+    );
+    if (tokenRow) {
+      dbRun('UPDATE tokens SET last_used_at = ? WHERE token_hash = ?', [now(), hash]).catch(() => {});
+      req.tokenUserId = tokenRow.user_id;
+      req.userId = tokenRow.user_id;
+      req.userRole = tokenRow.role;
+      return next();
+    }
+  }
+
+  return res.status(401).json({ error: '未登录' });
+}
+
+function requireAdmin(req, res, next) {
+  if (req.userRole !== 'admin') return res.status(403).json({ error: '需要管理员权限' });
+  next();
+}
+
+module.exports = { loadSession, requireAuth, requireAdmin };

package/lib/middleware/files.js

@@ -0,0 +1,42 @@
+// 文件加载与归属校验中间件。
+// loadFileWithPrivacy：按权限（admin/所有者/公开）加载文件到 req.fileRecord。
+// checkFileOwnership：判断当前用户是否拥有该文件（admin 拥有一切）。
+// 从 server.js 提取，行为保持不变。
+
+const { dbGet } = require('../db');
+
+function loadFileWithPrivacy(req, res, next) {
+  dbGet('SELECT * FROM files WHERE id = ?', [req.params.id]).then(file => {
+    if (!file) return res.status(404).json({ error: '文件不存在' });
+    const userId = req.userId;
+    const role = req.userRole;
+
+    // admin 可访问一切
+    if (role === 'admin') {
+      req.fileRecord = file;
+      return next();
+    }
+    // 普通用户：公开文件 或 自己的文件
+    if (userId && (file.is_public || file.uploaded_by === userId)) {
+      req.fileRecord = file;
+      return next();
+    }
+    // 未登录：仅公开文件
+    if (!userId && file.is_public) {
+      req.fileRecord = file;
+      return next();
+    }
+    if (!userId) return res.status(401).json({ error: '未登录' });
+    return res.status(403).json({ error: '无权访问此文件' });
+  }).catch(() => {
+    res.status(500).json({ error: '读取失败' });
+  });
+}
+
+function checkFileOwnership(req, file) {
+  if (req.userRole === 'admin') return true;
+  if (file.uploaded_by === req.userId) return true;
+  return false;
+}
+
+module.exports = { loadFileWithPrivacy, checkFileOwnership };

package/lib/paths.js

@@ -0,0 +1,9 @@
+// 路径常量集中管理。被多个 lib 模块和 routes 共享。
+// 从 server.js 提取，行为保持不变。
+
+const path = require('path');
+
+const DATA_DIR = process.env.JPAGE_DATA_DIR || path.join(__dirname, '..', 'data');
+const UPLOAD_DIR = path.join(DATA_DIR, 'uploads');
+
+module.exports = { DATA_DIR, UPLOAD_DIR };

package/lib/render-cache.js

@@ -0,0 +1,48 @@
+// 渲染缓存：Markdown 渲染（marked + highlight.js + KaTeX）是 CPU 热点，
+// 公开短链 /render 热门文档被反复渲染。缓存以 (fileId, updated_at) 为失效键：
+// 覆盖上传会更新 updated_at，旧缓存自动失效。HTML/Bundle 不缓存（主要瓶颈是磁盘读，
+// 且注入逻辑依赖文件内容，缓存收益低、失效复杂）。
+// 从 server.js 提取，行为保持不变。
+
+const RENDER_CACHE = new Map(); // key -> { html, ts }
+const RENDER_CACHE_MAX = 256;
+
+function renderCacheKey(file) {
+  // stored_name 必须进 key：历史版本渲染会用 { ...file, stored_name: ver.stored_name }，
+  // 若不加会错误命中当前版本的缓存。
+  return `${file.id}:${file.stored_name || ''}:${file.updated_at || ''}:${file.is_bundle ? 1 : 0}:${file.entry_path || ''}`;
+}
+
+function getRenderedHtml(file) {
+  const key = renderCacheKey(file);
+  return RENDER_CACHE.has(key) ? RENDER_CACHE.get(key).html : null;
+}
+
+function setRenderedHtml(file, html) {
+  const key = renderCacheKey(file);
+  if (RENDER_CACHE.size >= RENDER_CACHE_MAX && !RENDER_CACHE.has(key)) {
+    // 简单 LRU 淘汰：删最早的 key（Map 保持插入顺序）
+    const firstKey = RENDER_CACHE.keys().next().value;
+    RENDER_CACHE.delete(firstKey);
+  }
+  RENDER_CACHE.set(key, { html });
+}
+
+function invalidateRenderCache(fileId) {
+  for (const k of RENDER_CACHE.keys()) {
+    if (k.startsWith(`${fileId}:`)) RENDER_CACHE.delete(k);
+  }
+}
+
+// 数据导入替换数据库连接后，清空全部渲染缓存
+function clearRenderCache() {
+  RENDER_CACHE.clear();
+}
+
+module.exports = {
+  renderCacheKey,
+  getRenderedHtml,
+  setRenderedHtml,
+  invalidateRenderCache,
+  clearRenderCache,
+};