exflower-license-server 1.3.1 → 1.4.0

package/Dockerfile

@@ -13,7 +13,10 @@
 FROM node:18-alpine
 
 # better-sqlite3 原生模块编译工具（alpine/musl 无预编译二进制）
-RUN apk add --no-cache python3 make g++
+# apk 源切腾讯云镜像（默认 dl-cdn 国内不可达）；海外机构建可 --build-arg APK_MIRROR=dl-cdn.alpinelinux.org
+ARG APK_MIRROR=mirrors.cloud.tencent.com
+RUN sed -i "s|dl-cdn.alpinelinux.org|${APK_MIRROR}|g" /etc/apk/repositories \
+    && apk add --no-cache python3 make g++
 
 # 从 npm registry 全局安装已发布版本（国内机构建机可换 npmmirror）
 ARG VERSION=latest

package/README.md

@@ -2,6 +2,90 @@
 
 ExFlower 在线授权验证服务。管理 License Key、企业授权、实例追踪、模板分发。
 
+## 私有化自助部署手册（客户 IT 照此执行）
+
+前提：一台 Linux 服务器（1C1G 即可），已装 Docker；防火墙放行 4001（或反代用的 80/443）；能访问 `https://license.exflower.pro`（每日激活复核）。
+
+### 第 1 步：获取部署文件
+
+只需 `Dockerfile` 与 `docker-compose.yml` 两个文件（镜像构建时会自动从 npm 拉取服务本体，无需完整源码）：
+
+```bash
+npm pack exflower-license-server
+tar xzf exflower-license-server-*.tgz package/Dockerfile package/docker-compose.yml --strip-components=1
+```
+
+### 第 2 步：构建镜像
+
+```bash
+# 指定版本构建；国内服务器建议加 npm 镜像源参数
+docker build --build-arg VERSION=1.3.2 \
+  --build-arg NPM_REGISTRY=https://registry.npmmirror.com \
+  -t exflower/license-server:1.3.2 .
+```
+
+### 第 3 步：生成管理员 Token（请自行保管，厂商不需要知道）
+
+```bash
+# 生成随机 Token —— 这就是管理后台的登录凭证，只显示这一次，立即妥善保存
+TOKEN=$(openssl rand -hex 24) && echo "Admin Token: $TOKEN"
+
+# 计算哈希（部署配置里只放哈希，不落明文）
+echo -n "$TOKEN" | sha256sum | cut -d' ' -f1    # macOS 用: shasum -a 256
+```
+
+### 第 4 步：启动服务
+
+```bash
+docker run -d --name exflower-license-server --restart unless-stopped \
+  -p 4001:4001 \
+  -v license-data:/app/data \
+  -e NODE_ENV=production \
+  -e PORT=4001 \
+  -e LICENSE_DATA_DIR=/app/data \
+  -e ADMIN_TOKEN_HASH=<第3步算出的哈希> \
+  exflower/license-server:1.3.2
+```
+
+### 第 5 步：验证 + 激活（必做）
+
+```bash
+# 健康检查
+curl http://127.0.0.1:4001/health
+```
+
+1. 浏览器打开 `http://<服务器IP>:4001/admin`，用第 3 步的 Token 登录
+2. 进入「中央激活」，输入**厂商签发的 customer_key**（格式 `EXFC-XXXXXX-…`，向厂商索取）并激活
+3. ⚠️ **未激活前所有客户端接口一律 403**，激活后立即恢复；之后每日自动复核，中央短暂不可达不影响服务
+
+### 第 6 步：发放激活码
+
+管理台「License 管理」→ 新建 License（备注用途、选有效期与实例数）→ 完整 Key **仅显示一次**，复制交付给终端用户在客户端填写。客户端「授权服务器地址」填 `http://<服务器IP>:4001`（配置了域名反代则填域名）。
+
+### 升级版本
+
+```bash
+docker build --build-arg VERSION=<新版本> -t exflower/license-server:<新版本> .
+docker rm -f exflower-license-server
+# 用与第 4 步完全相同的参数重新 docker run（数据在命名卷 license-data 里，不受影响）
+```
+
+⚠️ 不要使用 `docker compose down -v`——`-v` 会连数据卷一起删除。
+
+### （可选）HTTPS 反代
+
+以 Caddy 为例（`Caddyfile` 一行搞定，自动签发证书）：
+
+```
+license.example.com {
+    reverse_proxy 127.0.0.1:4001
+}
+```
+
+⚠️ 境内服务器挂域名须已完成 ICP 备案，否则 80/443 会被云厂商拦截。
+
+---
+
 ## 快速开始
 
 ### 方式一：npm 全局安装（推荐）
@@ -12,7 +96,7 @@ npm install -g exflower-license-server
 
 # 查看版本
 exflower-license-server --version
-# 输出: 1.0.7
+# 输出: 1.3.2
 
 # 运行
 exflower-license-server
@@ -23,7 +107,19 @@ ADMIN_TOKEN=your-secret-token PORT=4001 exflower-license-server
 
 ### 方式二：Docker
 
+镜像构建直接从 npm registry 拉取已发布版本（构建机无需源码）：
+
 ```bash
+# 构建（默认 latest；指定版本用 --build-arg VERSION=x.y.z）
+docker build -t exflower/license-server:latest .
+
+# 国内构建机走镜像源（npm registry 与 alpine apk 源都可换）
+docker build \
+  --build-arg VERSION=1.3.2 \
+  --build-arg NPM_REGISTRY=https://registry.npmmirror.com \
+  --build-arg APK_MIRROR=mirrors.cloud.tencent.com \
+  -t exflower/license-server:1.3.2 .
+
 # 使用 docker-compose（推荐）
 docker-compose up -d
 
@@ -174,7 +270,7 @@ sudo systemctl enable --now exflower-license-server
 - **License 管理**：创建 License 时填写备注（如"市场部"）并选择有效期（1/3/6 个月、1 年、2 年、永久）；列表显示剩余天数（<30 天标黄、过期标红）；支持编辑（改有效期/配额）、暂停/恢复、删除、**重置 Key**
 - **品牌（白标）**：全局工作台名称设置（见下方"白标品牌名"）
 - **实例监控**：查看已激活的实例列表
-- **模板管理**：按类型选择上传方式（见下方"模板系统"），支持按 License 分发，查看导入统计
+- **模板管理**：按类型页签组织（agent/excard/doc/资料图谱），卡片式列表，支持分类管理与分类过滤、按 License 定向分发（多选），查看导入统计
 - **轻应用分发**：上传 `.exfapp` 包并按 License 隔离分发；客户端「轻应用」页可浏览/下载/导入（上限 5GB，含图谱的包注意部署机磁盘）
 - **客户端更新**：上传各平台更新包（mac 传 **zip**、win 传 NSIS **exe**），客户端启动自动检查 + 帮助菜单手动检查，electron-updater 静默下载安装（每个包 ~700MB+，注意部署机磁盘余量）
 
@@ -206,6 +302,7 @@ sudo systemctl enable --now exflower-license-server
 | `/api/license/heartbeat` | POST | 心跳上报（响应含 `brand_name`） |
 | `/api/templates` | GET | 获取模板列表（需 `x-license-key`） |
 | `/api/templates/:id` | GET | 获取模板详情（需 `x-license-key`） |
+| `/api/templates/:id/download` | GET | 下载资料图谱模板 `.exflib`（需 `x-license-key`） |
 | `/api/packages` | GET | 轻应用包列表，按公司隔离（需 `x-license-key`） |
 | `/api/packages/:id/download` | GET | 下载轻应用包（需 `x-license-key`） |
 | `/api/updates/latest.yml` | GET | Windows 更新清单（electron-updater，需 `x-license-key`） |
@@ -224,6 +321,11 @@ sudo systemctl enable --now exflower-license-server
 | `/api/admin/instances/:id` | DELETE | 删除实例 |
 | `/api/admin/templates` | GET/POST | 模板列表/创建 |
 | `/api/admin/templates/:id` | PATCH/DELETE | 更新/删除模板 |
+| `/api/admin/templates/library` | POST | 资料图谱模板上传（multipart，字段 `file`，`.exflib`） |
+| `/api/admin/templates/doc-upload` | POST | 知识库文档包上传（v1.3.2 起；multipart，字段 `file`，zip 内含 `README.md` + `assets/`） |
+| `/api/admin/template-categories` | GET/POST | 模板分类列表/创建（按类型分组，按 `sort_order` 排序返回） |
+| `/api/admin/template-categories/:id` | PATCH/DELETE | 分类改名/删除 |
+| `/api/admin/template-categories/order` | PUT | 分类手动排序（v1.3.2 起；body `{type, ids:[...]}`，客户端按此顺序展示分类） |
 | `/api/admin/imports` | GET | 导入统计（支持 `?template_id=` / `?company_id=` 过滤） |
 | `/api/admin/packages` | GET/POST | 轻应用包列表/上传（multipart，字段 `file`+`company_id`） |
 | `/api/admin/packages/:id` | DELETE | 删除轻应用包 |
@@ -234,16 +336,20 @@ sudo systemctl enable --now exflower-license-server
 
 ## 模板系统
 
-模板用于向客户端分发预设配置。管理后台支持创建 `agent`、`excard`、`workflow`、`doc` 四种类型的模板。
+模板用于向客户端分发预设配置。管理后台支持 `agent`、`excard`、`doc`、`library`（资料图谱）四种类型的模板。
+
+> **workflow 类型暂不开放**：上传/下载形态待重新设计，管理台与客户端均已隐藏入口；API 与存量数据保留，重新开放前不要清理 workflow 数据。
 
 ### 上传方式（v1.0.7 起）
 
 管理后台根据类型提供不同的上传方式：
 
 - **agent / excard / doc**：**Markdown 原生上传**。直接上传客户端导出的 `.md` 文件（或粘贴 Markdown 文本），后台自动解析 frontmatter 预填模板名称并生成 `content_json`，无需手写 JSON。
-- **workflow**：仍以 JSON 描述步骤结构（步骤间的 excardId 引用和分支跳转无法由 Markdown 表达），上传框预填骨架示例。
+- **doc 附加方式（v1.3.2 起）**：可改传一个 **zip 文档包**（根目录 `README.md` + `assets/` 附件目录），与客户端「发布到模板库」的产物格式一致；名称留空自动取 README 的一级标题。选了 zip 则以包内容为准。
+- **library**：上传客户端导出的 `.exflib` 包（multipart `POST /api/admin/templates/library`，字段 `file`），服务端解包校验 manifest（`format: exflower-library`）并记录文件大小与 sha256；客户端经 `GET /api/templates/:id/download` 下载导入。
+- **workflow**（暂不开放）：以 JSON 描述步骤结构，上传框预填骨架示例。
 
-通过 API 创建模板时，`content_json` 与 `content_md` 至少提供一个（`workflow` 类型必须提供 `content_json`）。
+通过 API 创建模板时，`content_json` 与 `content_md` 至少提供一个（`workflow` 类型必须提供 `content_json`；`library` 类型走专用上传端点）。
 
 ### 通用字段
 
@@ -412,9 +518,16 @@ node scripts/seed-templates.js \
 - 导入的模板均为**全局模板**（所有 License 可见）。
 - 脚本遵守 admin 接口限速（60 次/分钟），遇到 429 自动退避重试。
 
-## 构建 Docker 镜像
+## 发布新版本（厂商侧）
 
 ```bash
-docker build -t exflower/license-server:latest .
+# 1. 提升 package.json 版本号
+# 2. 确认 files 白名单覆盖全部运行时文件（activation.js / seed-templates.js /
+#    central-public.pem / seeds/ 缺一个都会发出启动即崩的包）
+npm pack --dry-run   # 检查 Tarball Contents
+# 3. 发布（npm 已下线 Classic Token，用勾了 bypass 2FA 的 Granular Token）
+npm publish
 ```
 
+Docker 镜像构建参数见上方「方式二：Docker」。
+

package/admin/index.html

@@ -415,6 +415,10 @@
         <label>Markdown 文件（直接上传客户端导出的 .md）</label>
         <input type="file" id="tmpl-md-file" accept=".md,.markdown,text/markdown,text/plain" onchange="onTemplateFileSelected(event)">
       </div>
+      <div id="tmpl-doc-zip-group" class="hidden">
+        <label>文档 zip 包（含 README.md + assets/；选择了则以包为准，下方 Markdown 忽略）</label>
+        <input type="file" id="tmpl-doc-zip" accept=".zip,application/zip">
+      </div>
       <div id="tmpl-json-group">
         <label>内容 (JSON) <span class="muted" id="tmpl-json-hint"></span></label>
         <textarea id="tmpl-json" rows="8"></textarea>
@@ -967,12 +971,15 @@
         tbody.innerHTML = '<tr><td colspan="3" class="muted" style="text-align:center;padding:16px">暂无分类</td></tr>';
         return;
       }
-      for (const c of categoriesCache) {
+      for (let i = 0; i < categoriesCache.length; i++) {
+        const c = categoriesCache[i];
         const tr = document.createElement('tr');
         tr.innerHTML = `
           <td><strong>${c.name}</strong></td>
           <td>${c.template_count}</td>
           <td>
+            <button class="btn-sm btn-plain" ${i === 0 ? 'disabled' : ''} onclick="moveCategory('${c.id}', -1)" title="上移">↑</button>
+            <button class="btn-sm btn-plain" ${i === categoriesCache.length - 1 ? 'disabled' : ''} onclick="moveCategory('${c.id}', 1)" title="下移">↓</button>
             <button class="btn-sm btn-plain" onclick="renameCategory('${c.id}')">改名</button>
             <button class="btn-sm btn-danger" onclick="deleteCategory('${c.id}', '${c.name.replace(/'/g, "\\'")}')">删除</button>
           </td>
@@ -981,6 +988,18 @@
       }
     }
 
+    async function moveCategory(id, dir) {
+      const idx = categoriesCache.findIndex(c => c.id === id);
+      const swap = idx + dir;
+      if (idx < 0 || swap < 0 || swap >= categoriesCache.length) return;
+      const ids = categoriesCache.map(c => c.id);
+      [ids[idx], ids[swap]] = [ids[swap], ids[idx]];
+      const res = await api('PUT', '/api/admin/template-categories/order', { type: currentAssetType, ids });
+      if (!res.success) return toast(res.message || '排序失败');
+      await loadCategories();
+      renderCategoryList();
+    }
+
     async function renameCategory(id) {
       const cat = categoriesCache.find(c => c.id === id);
       if (!cat) return;
@@ -1144,6 +1163,9 @@
       const isMd = MD_TYPES.includes(type);
       document.getElementById('tmpl-json-group').classList.toggle('hidden', isMd);
       document.getElementById('tmpl-md-file-group').classList.toggle('hidden', !isMd);
+      // doc zip 上传只在新建时提供（编辑模式只改元信息与 md）
+      const isDocCreate = type === 'doc' && !document.getElementById('tmpl-id').value;
+      document.getElementById('tmpl-doc-zip-group').classList.toggle('hidden', !isDocCreate);
       document.getElementById('tmpl-md-label').textContent = isMd
         ? 'Markdown 内容（上传文件后可编辑）'
         : 'Markdown 内容 (可选)';
@@ -1220,6 +1242,7 @@
       document.getElementById('tmpl-json').value = '';
       document.getElementById('tmpl-md').value = '';
       document.getElementById('tmpl-md-file').value = '';
+      document.getElementById('tmpl-doc-zip').value = '';
       populateCompanySelect();
       onTemplateTypeChange();
       document.getElementById('template-modal').classList.add('show');
@@ -1267,6 +1290,7 @@
       document.getElementById('tmpl-json').value = jsonStr;
       document.getElementById('tmpl-md').value = t.content_md || '';
       document.getElementById('tmpl-md-file').value = '';
+      document.getElementById('tmpl-doc-zip').value = '';
       onTemplateTypeChange();
       document.getElementById('template-modal').classList.add('show');
     }
@@ -1289,6 +1313,29 @@
 
       if (!name) return toast('请输入模板名称');
 
+      // 知识库文档 + 选了 zip 包：走 zip 上传通道（携带 assets），以包内 README.md 为内容
+      const docZip = type === 'doc' && !id ? document.getElementById('tmpl-doc-zip').files[0] : null;
+      if (docZip) {
+        const fd = new FormData();
+        fd.append('file', docZip);
+        fd.append('name', name);
+        fd.append('description', desc);
+        if (version) fd.append('version', version);
+        if (category !== undefined) fd.append('category', category);
+        fd.append('company_ids', JSON.stringify(companyIds));
+        const res = await fetch('/api/admin/templates/doc-upload', {
+          method: 'POST',
+          headers: { 'x-admin-token': ADMIN_TOKEN },
+          body: fd
+        });
+        const data = await res.json();
+        if (!data.success) return toast(data.message || '上传失败');
+        closeTemplateModal();
+        toast('文档包上传成功');
+        loadTemplates();
+        return;
+      }
+
       let contentJson, contentMd;
       if (type === 'workflow') {
         if (!jsonRaw) return toast('请输入 JSON 内容');

package/db.js

@@ -205,6 +205,9 @@ db.exec(`
 // 幂等列迁移：轻应用分类（受管分类 template_categories type='app'）
 try { db.exec('ALTER TABLE app_packages ADD COLUMN category TEXT'); } catch { /* 已存在 */ };
 
+// 幂等列迁移：分类手动排序（0 序并列时按 created_at，保持存量行为）
+try { db.exec('ALTER TABLE template_categories ADD COLUMN sort_order INTEGER NOT NULL DEFAULT 0'); } catch { /* 已存在 */ };
+
 // ── 轻应用定向分享（多 License 可见；语义同 template_companies） ──
 db.exec(`
   CREATE TABLE IF NOT EXISTS package_companies (
@@ -236,6 +239,9 @@ db.exec(`
   CREATE INDEX IF NOT EXISTS idx_client_versions_platform ON client_versions(platform, is_latest)
 `);
 
+// 幂等列迁移：CDN 远程地址（有值 = 文件在中央 CDN，本地不落盘；PLAN-CDN-DISTRIBUTION）
+try { db.exec('ALTER TABLE client_versions ADD COLUMN remote_url TEXT'); } catch { /* 已存在 */ };
+
 // ── Server-level settings（品牌等全局配置，私有化部署 = 一个组织） ──
 db.exec(`
   CREATE TABLE IF NOT EXISTS settings (

package/index.js

@@ -54,6 +54,9 @@ setupRoutes(app);
 // ── 中央激活调度：已配置 customer_key 则启动即复核，之后每日复核（失败 1 小时重试） ──
 require('./activation').startScheduler();
 
+// ── 客户端版本 manifest 同步（启动即拉一次 + 每小时兜底；失败维持本地） ──
+require('./updateSync').startUpdateSync();
+
 app.listen(PORT, () => {
   const tokenLine = ADMIN_TOKEN_HASH
     ? 'Admin Token: (hashed via ADMIN_TOKEN_HASH)'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "exflower-license-server",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "description": "ExFlower License Server - 在线授权验证服务",
   "main": "index.js",
   "bin": {

package/routes.js

@@ -10,6 +10,7 @@ const unzipper = require('unzipper');
 const { queryAll, queryGet, queryRun, getSetting, setSetting, DATA_DIR } = require('./db');
 const { generateLicenseKey, generateId } = require('./utils');
 const activation = require('./activation');
+const { ensureFresh } = require('./updateSync');
 
 const DEFAULT_ADMIN_TOKEN = 'exflower-admin-2026';
 // ADMIN_TOKEN_HASH（sha256 hex）优先；否则用明文 ADMIN_TOKEN。二选一。
@@ -154,13 +155,21 @@ function buildLatestYml(mac) {
   // version 取各行里语义最新（简单按创建时间最新的一行）
   rows.sort((a, b) => (a.created_at < b.created_at ? 1 : -1));
   const esc = (s) => String(s).replace(/'/g, "''");
+  // 本地文件就绪（存在且大小匹配）→ 本地相对路径（客户端局域网速度）；
+  // 否则 remote_url（CDN）兜底——后台下载完成后下一轮自动切回本地
+  const fileUrl = (r) => {
+    if (r.file_path && fs.existsSync(r.file_path) && fs.statSync(r.file_path).size === r.file_size) {
+      return `files/${r.platform}/${esc(r.file_name)}`;
+    }
+    return r.remote_url || `files/${r.platform}/${esc(r.file_name)}`;
+  };
   const lines = [`version: ${rows[0].version}`, 'files:'];
   for (const r of rows) {
-    lines.push(`  - url: 'files/${r.platform}/${esc(r.file_name)}'`);
+    lines.push(`  - url: '${fileUrl(r)}'`);
     lines.push(`    sha512: '${r.sha512}'`);
     lines.push(`    size: ${r.file_size}`);
   }
-  lines.push(`path: 'files/${rows[0].platform}/${esc(rows[0].file_name)}'`);
+  lines.push(`path: '${fileUrl(rows[0])}'`);
   lines.push(`sha512: '${rows[0].sha512}'`);
   lines.push(`releaseDate: '${new Date(rows[0].created_at.replace(' ', 'T') + 'Z').toISOString()}'`);
   return lines.join('\n') + '\n';
@@ -574,8 +583,12 @@ function setupRoutes(app) {
     sql += ' ORDER BY type, name';
 
     const templates = queryAll(sql, params);
+    // 分类手动排序下发：客户端按服务端顺序展示分类筛选（各类型全量，体积小）
+    const orderRows = queryAll('SELECT type, name FROM template_categories ORDER BY sort_order ASC, created_at ASC');
+    const categoryOrder = {};
+    for (const r of orderRows) (categoryOrder[r.type] = categoryOrder[r.type] || []).push(r.name);
     const hint = upgradeHint(req);
-    res.json({ success: true, templates, ...(hint ? { upgrade_hint: hint } : {}) });
+    res.json({ success: true, templates, category_order: categoryOrder, ...(hint ? { upgrade_hint: hint } : {}) });
   });
 
   // Import summary (must come before /:id to avoid matching 'import-summary' as an id)
@@ -697,7 +710,7 @@ function setupRoutes(app) {
     `;
     const params = [];
     if (type) { sql += ' WHERE c.type = ?'; params.push(type); }
-    sql += ' ORDER BY c.created_at ASC';
+    sql += ' ORDER BY c.sort_order ASC, c.created_at ASC';
     const cats = queryAll(sql, params);
     // 轻应用分类的计数走 app_packages（模板计数查 templates 永远是 0）
     if (type === 'app') {
@@ -718,10 +731,25 @@ function setupRoutes(app) {
     const dup = queryGet('SELECT id FROM template_categories WHERE type = ? AND name = ?', [type, name]);
     if (dup) return res.status(409).json({ success: false, message: '该类型下分类已存在' });
     const id = generateId();
-    queryRun('INSERT INTO template_categories (id, type, name) VALUES (?, ?, ?)', [id, type, name]);
+    const maxOrder = queryGet('SELECT MAX(sort_order) AS m FROM template_categories WHERE type = ?', [type])?.m ?? -1;
+    queryRun('INSERT INTO template_categories (id, type, name, sort_order) VALUES (?, ?, ?, ?)', [id, type, name, maxOrder + 1]);
     res.json({ success: true, category: { id, type, name } });
   });
 
+  // 手动排序：按 ids 数组顺序重排该类型下分类（未列入的保持相对顺序排在末尾）
+  app.put('/api/admin/template-categories/order', requireAdmin, (req, res) => {
+    const { type, ids } = req.body || {};
+    if (!type || !Array.isArray(ids)) {
+      return res.status(400).json({ success: false, message: 'type 与 ids 必填' });
+    }
+    const rows = queryAll('SELECT id FROM template_categories WHERE type = ? ORDER BY sort_order ASC, created_at ASC', [type]);
+    const rest = rows.map(r => r.id).filter(id => !ids.includes(id));
+    [...ids, ...rest].forEach((id, i) => {
+      queryRun('UPDATE template_categories SET sort_order = ? WHERE id = ? AND type = ?', [i + 1, id, type]);
+    });
+    res.json({ success: true });
+  });
+
   app.patch('/api/admin/template-categories/:id', requireAdmin, (req, res) => {
     const cat = queryGet('SELECT * FROM template_categories WHERE id = ?', [req.params.id]);
     if (!cat) return res.status(404).json({ success: false, message: 'Category not found' });
@@ -984,6 +1012,85 @@ function setupRoutes(app) {
     }
   });
 
+  // ── Admin: 知识库文档 zip 上传（README.md + assets/，与客户端发布产物的存储契约一致） ──
+  const docZipUpload = multer({
+    storage: multer.memoryStorage(),
+    limits: { fileSize: 200 * 1024 * 1024 }
+  });
+  const DOC_ASSET_MIMES = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif', '.svg': 'image/svg+xml', '.webp': 'image/webp',
+    '.pdf': 'application/pdf', '.md': 'text/markdown', '.txt': 'text/plain',
+  };
+  app.post('/api/admin/templates/doc-upload', requireAdmin, docZipUpload.single('file'), async (req, res) => {
+    try {
+      if (!req.file) return res.status(400).json({ success: false, message: 'file is required' });
+
+      let zip;
+      try {
+        zip = await unzipper.Open.buffer(req.file.buffer);
+      } catch {
+        return res.status(400).json({ success: false, message: '无效的 zip 包' });
+      }
+      const readme = zip.files.find(f => f.type === 'File' && f.path.toLowerCase() === 'readme.md');
+      if (!readme) {
+        return res.status(400).json({ success: false, message: '无效的文档包：根目录缺少 README.md' });
+      }
+      const contentMd = (await readme.buffer()).toString('utf8');
+
+      const assets = [];
+      for (const f of zip.files) {
+        if (f.type !== 'File' || !f.path.startsWith('assets/')) continue;
+        const filename = path.basename(f.path);
+        if (!filename) continue;
+        const buf = await f.buffer();
+        assets.push({
+          filename,
+          mimeType: DOC_ASSET_MIMES[path.extname(filename).toLowerCase()] || 'application/octet-stream',
+          data: buf.toString('base64'),
+        });
+      }
+
+      const { company_id, category, version } = req.body || {};
+      let shareIds = null;
+      if (req.body?.company_ids) {
+        try { shareIds = JSON.parse(req.body.company_ids).filter(Boolean); } catch { shareIds = null; }
+      }
+      if (company_id && !shareIds) {
+        const company = queryGet('SELECT id FROM companies WHERE id = ?', [company_id]);
+        if (!company) return res.status(404).json({ success: false, message: 'Company not found' });
+      }
+
+      const h1 = contentMd.match(/^#\s+(.+)$/m)?.[1]?.trim();
+      const name = (req.body?.name || '').trim() || h1 || '未命名文档';
+      const id = generateId();
+      queryRun(
+        `INSERT INTO templates (id, company_id, type, name, description, content_json, content_md, tags, category, version, created_at, updated_at)
+         VALUES (?, ?, 'doc', ?, ?, ?, ?, '[]', ?, ?, datetime('now'), datetime('now'))`,
+        [
+          id,
+          shareIds ? null : (company_id || null),
+          name,
+          (req.body?.description || '').trim(),
+          JSON.stringify({ assets }),
+          contentMd,
+          category || null,
+          (version || '').trim() || '1.0',
+        ]
+      );
+      if (shareIds && shareIds.length) {
+        const err = setTemplateCompanies(id, shareIds);
+        if (err) {
+          queryRun('DELETE FROM templates WHERE id = ?', [id]);
+          return res.status(404).json({ success: false, message: err });
+        }
+      }
+      res.json({ success: true, template: { id, name, assets: assets.length } });
+    } catch (err) {
+      res.status(500).json({ success: false, message: err.message });
+    }
+  });
+
   // ── Template Import Log (client-facing) ──
   app.post('/api/templates/:id/import-log', (req, res) => {
     const licenseKey = req.headers['x-license-key'];
@@ -1209,16 +1316,18 @@ function setupRoutes(app) {
   });
 
   // ── Client Updates: client-facing (electron-updater generic provider) ──
-  app.get('/api/updates/latest.yml', (req, res) => {
+  app.get('/api/updates/latest.yml', async (req, res) => {
     if (!companyByLicenseKey(req, res)) return;
+    await ensureFresh(); // manifest 过期则先同步中央（失败不阻塞）
     const yml = buildLatestYml(false);
     if (!yml) return res.status(404).json({ success: false, message: 'No win update available' });
     res.setHeader('Content-Type', 'text/yaml; charset=utf-8');
     res.send(yml);
   });
 
-  app.get('/api/updates/latest-mac.yml', (req, res) => {
+  app.get('/api/updates/latest-mac.yml', async (req, res) => {
     if (!companyByLicenseKey(req, res)) return;
+    await ensureFresh();
     const yml = buildLatestYml(true);
     if (!yml) return res.status(404).json({ success: false, message: 'No mac update available' });
     res.setHeader('Content-Type', 'text/yaml; charset=utf-8');
@@ -1232,7 +1341,10 @@ function setupRoutes(app) {
       'SELECT * FROM client_versions WHERE platform = ? AND file_name = ?',
       [platform, filename]
     );
-    if (!row || !fs.existsSync(row.file_path)) {
+    if (!row) return res.status(404).json({ success: false, message: 'Update file not found' });
+    if (!fs.existsSync(row.file_path)) {
+      // 本地无文件但有 CDN 地址 → 302 兜底（对齐 ensureFresh 未覆盖的旧 yml 场景）
+      if (row.remote_url) return res.redirect(302, row.remote_url);
       return res.status(404).json({ success: false, message: 'Update file not found' });
     }
     res.setHeader('Content-Type', 'application/octet-stream');
@@ -1243,7 +1355,7 @@ function setupRoutes(app) {
   // ── Client Updates: admin ──
   app.get('/api/admin/updates', requireAdmin, (req, res) => {
     const updates = queryAll(
-      'SELECT id, platform, version, file_name, file_size, sha512, release_notes, is_latest, created_at FROM client_versions ORDER BY created_at DESC'
+      'SELECT id, platform, version, file_name, file_size, sha512, release_notes, is_latest, remote_url, created_at FROM client_versions ORDER BY created_at DESC'
     );
     res.json({ success: true, updates });
   });