exflower-license-server 1.0.8 → 1.3.2

package/Dockerfile

@@ -1,7 +1,8 @@
 # ExFlower License Server Docker Image
 #
-# Build:
+# 直接从 npm  registry 拉取已发布版本，构建机无需源码：
 #   docker build -t exflower/license-server:latest .
+#   docker build --build-arg VERSION=1.3.1 -t exflower/license-server:1.3.1 .
 #
 # Run:
 #   docker run -d -p 4001:4001 \
@@ -11,17 +12,16 @@
 
 FROM node:18-alpine
 
-# Install build tools for native modules (better-sqlite3)
-RUN apk add --no-cache python3 make g++
+# better-sqlite3 原生模块编译工具（alpine/musl 无预编译二进制）
+# 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++
 
-WORKDIR /app
-
-# Install dependencies
-COPY package.json package-lock.json ./
-RUN npm ci --production
-
-# Copy application files
-COPY . .
+# 从 npm registry 全局安装已发布版本（国内机构建机可换 npmmirror）
+ARG VERSION=latest
+ARG NPM_REGISTRY=https://registry.npmjs.org
+RUN npm install -g --registry=${NPM_REGISTRY} exflower-license-server@${VERSION}
 
 # Create data directory
 RUN mkdir -p /app/data
@@ -39,5 +39,6 @@ HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
 # Default environment
 ENV PORT=4001
 ENV NODE_ENV=production
+ENV LICENSE_DATA_DIR=/app/data
 
-CMD ["node", "index.js"]
+CMD ["exflower-license-server"]

package/README.md

@@ -12,7 +12,7 @@ npm install -g exflower-license-server
 
 # 查看版本
 exflower-license-server --version
-# 输出: 1.0.7
+# 输出: 1.3.1
 
 # 运行
 exflower-license-server
@@ -23,7 +23,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.1 \
+  --build-arg NPM_REGISTRY=https://registry.npmmirror.com \
+  --build-arg APK_MIRROR=mirrors.cloud.tencent.com \
+  -t exflower/license-server:1.3.1 .
+
 # 使用 docker-compose（推荐）
 docker-compose up -d
 
@@ -123,6 +135,7 @@ sudo systemctl enable --now exflower-license-server
 |------|--------|------|
 | `PORT` | `4001` | 服务端口 |
 | `ADMIN_TOKEN` | `exflower-admin-2026` | 管理后台鉴权 Token |
+| `ADMIN_TOKEN_HASH` | — | 管理 Token 的 sha256(hex)。设置后忽略 `ADMIN_TOKEN`，明文不落环境变量（`echo -n "你的token" \| shasum -a 256` 生成） |
 | `LICENSE_DATA_DIR` | 见下方 | 数据库持久化目录 |
 | `NODE_ENV` | `production` | 运行环境 |
 
@@ -140,14 +153,59 @@ sudo systemctl enable --now exflower-license-server
 
 **⚠️ 重要**：npm 全局安装（`npm install -g`）或更新时，安装目录会被完全替换。默认不再将数据存放在包安装目录内，升级不会丢失已有数据。
 
+### 升级与数据安全
+
+升级（换新 tgz / 重建 Docker 镜像）只替换程序代码，以下内容全部保留：
+
+- `license.db`：公司/License/实例记录、**客户上传的模板**、品牌设置、激活状态
+- 上传的文件本体：`packages/`（轻应用）、`library-templates/`（资料图谱）、`updates/`（客户端更新包）
+
+注意事项：
+
+1. **自定义了 `LICENSE_DATA_DIR` 的部署**：升级后的启动脚本/systemd unit 必须继续带同一个值——换了路径等于换了一套空数据库（旧数据仍在原目录，切回即可恢复）。
+2. **Docker 部署**：数据在命名卷 `license-data` 里，删容器/重建镜像不受影响；但不要随手 `docker compose down -v`（`-v` 会连卷一起删）。
+3. **官方 Agent 模板播种**（v1.3.0 起随包自带 102 个全局模板）：只在首次启动播种一次（settings 落标记），管理员删除的官方模板不会因升级/重启复活；播种用 `INSERT OR IGNORE`，绝不覆盖客户已有数据。
+
 ## 管理后台
 
-启动后访问 `http://localhost:4001/admin`，使用 `ADMIN_TOKEN` 登录。
+启动后访问 `http://localhost:4001/admin`，使用 `ADMIN_TOKEN` 登录（登录时会真实校验 Token，错误无法进入）。
+
+### 中央激活（v1.3.0 起，必做）
+
+**本服务部署后必须先向 ExFlower 中央授权服务激活，否则将拒绝全部客户端请求**（客户端 verify/心跳、模板、轻应用、更新下载一律 403；管理台不受影响）。
+
+1. 向厂商获取本服务器专属的 `customer_key`（格式 `EXFC-XXXXXX-XXXXXX-XXXXXX-XXXXXX`）
+2. 管理台首页 →「中央激活」→ 输入 key 激活
+3. 激活后每日自动向中央复核（主端点 `https://license.exflower.pro`，可配置备端点；中央短暂不可达时靠本地缓存凭证照常服务）
+
+有效期语义：合同到期前 30 天管理台开始提醒；过期后有 7 天宽限期（服务正常）；宽限过后停止对客户端服务。同一 key 在新服务器激活会顶替旧服务器（旧服务器立即停服并显示大红横幅）。吊销/顶替/过期时管理台全站横幅提示。
+
+**实例配额语义（v1.3.1 起）**：中央签发的 `max_instances` 是客户**创建激活码时可分配的总实例数**——所有激活码的"最大实例数"之和不得超过该额度（创建/编辑时校验，管理台会显示剩余可分配数）。客户端实际激活多少台由各激活码自己的 max_instances 管（7 天无心跳自动释放名额），中央不干预运行时激活。
+
+管理后台功能（v1.2.0 起按私有化部署定位组织：一个后台 = 一个组织）：
+- **License 管理**：创建 License 时填写备注（如"市场部"）并选择有效期（1/3/6 个月、1 年、2 年、永久）；列表显示剩余天数（<30 天标黄、过期标红）；支持编辑（改有效期/配额）、暂停/恢复、删除、**重置 Key**
+- **品牌（白标）**：全局工作台名称设置（见下方"白标品牌名"）
+- **实例监控**：查看已激活的实例列表
+- **模板管理**：按类型页签组织（agent/excard/doc/资料图谱），卡片式列表，支持分类管理与分类过滤、按 License 定向分发（多选），查看导入统计
+- **轻应用分发**：上传 `.exfapp` 包并按 License 隔离分发；客户端「轻应用」页可浏览/下载/导入（上限 5GB，含图谱的包注意部署机磁盘）
+- **客户端更新**：上传各平台更新包（mac 传 **zip**、win 传 NSIS **exe**），客户端启动自动检查 + 帮助菜单手动检查，electron-updater 静默下载安装（每个包 ~700MB+，注意部署机磁盘余量）
 
-管理后台功能：
-- **企业管理**：创建公司时可选择有效期（1/3/6 个月、1 年、2 年、永久）；列表显示剩余天数（<30 天标黄、过期标红）；支持编辑（改有效期/配额）、暂停/恢复、删除
-- **实例管理**：查看已激活的实例列表
-- **模板管理**：按类型选择上传方式（见下方"模板系统"），支持按公司分发，查看导入统计（次数/公司/实例）
+### License Key 显示策略（v1.2.0 起）
+
+- 完整 Key **只在创建/重置成功时显示一次**（弹窗 + 复制按钮），关闭后无法再查看
+- 列表中 Key 以掩码显示（`EXF-XXXXXX-······-······-XXXXXX` 首尾各一段），不可点击复制
+- Key 丢失 → 使用「重置 Key」：旧 Key 立即失效（已激活客户端失去授权需重新激活），新 Key 同样只显示一次
+
+### 安全特性（v1.2.0 起）
+
+- 登录时真实校验 Token，错误 Token 无法进入后台
+- 管理接口限速 60 次/分/IP，license 验证接口 120 次/分/IP（超限 429）
+- Token 比较使用 timing-safe 方式；支持 `ADMIN_TOKEN_HASH` 哈希配置（明文不落环境变量）
+- 使用默认 Token 启动时打印醒目警告；非 localhost 的 HTTP 访问显示明文传输警示 banner
+
+## 白标品牌名
+
+「品牌」频道设置**全局**工作台名称后，客户端每次 verify/心跳都会收到 `brand_name` 并写入本地 `~/.exflower/openexteam.json` 的 `title`，工作台标题随之热更新。留空则客户端保持默认 ExFlower。
 
 ## API 端点
 
@@ -156,37 +214,55 @@ sudo systemctl enable --now exflower-license-server
 | 端点 | 方法 | 说明 |
 |------|------|------|
 | `/health` | GET | 健康检查 |
-| `/api/license/verify` | POST | 验证 License Key |
-| `/api/license/heartbeat` | POST | 心跳上报 |
+| `/api/license/verify` | POST | 验证 License Key（响应含 `company.brand_name`，全局品牌设置） |
+| `/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`） |
+| `/api/updates/latest-mac.yml` | GET | macOS 更新清单（需 `x-license-key`） |
+| `/api/updates/files/:platform/:filename` | GET | 更新包下载（需 `x-license-key`） |
 
 ### 管理后台接口
 
 | 端点 | 方法 | 说明 |
 |------|------|------|
-| `/api/admin/companies` | GET/POST | 企业管理 |
-| `/api/admin/companies/:id` | PATCH/DELETE | 更新/删除公司 |
+| `/api/admin/companies` | GET/POST | License 列表（**key 掩码返回**）/创建（**key 完整返回仅此一次**） |
+| `/api/admin/companies/:id` | PATCH/DELETE | 更新/删除 License |
+| `/api/admin/companies/:id/reset-key` | POST | 重置 License Key（旧 key 立即失效，新 key 完整返回仅此一次） |
+| `/api/admin/brand` | GET/PUT | 全局品牌名（白标）读取/设置 |
 | `/api/admin/instances` | GET | 实例列表 |
 | `/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/template-categories` | GET/POST | 模板分类列表/创建（按类型分组） |
+| `/api/admin/template-categories/:id` | PATCH/DELETE | 分类改名/删除 |
 | `/api/admin/imports` | GET | 导入统计（支持 `?template_id=` / `?company_id=` 过滤） |
+| `/api/admin/packages` | GET/POST | 轻应用包列表/上传（multipart，字段 `file`+`company_id`） |
+| `/api/admin/packages/:id` | DELETE | 删除轻应用包 |
+| `/api/admin/updates` | GET/POST | 更新包列表/上传（multipart，字段 `file`+`platform`+`version`） |
+| `/api/admin/updates/:id` | DELETE | 删除更新包 |
 
 所有管理接口需在 Header 中携带 `x-admin-token`。
 
 ## 模板系统
 
-模板用于向客户端分发预设配置。管理后台支持创建 `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 表达），上传框预填骨架示例。
+- **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` 类型走专用上传端点）。
 
 ### 通用字段
 
@@ -340,9 +416,31 @@ curl -X POST http://localhost:4001/api/admin/templates \
   }'
 ```
 
-## 构建 Docker 镜像
+### 批量种子导入（部署自带模板）
+
+`scripts/seed-templates.js` 用于部署时批量导入 Agent 模板（自动建分类、挂分类）与内置帮助文档，幂等可重复执行（分类按名复用，模板按 type+name 跳过）：
+
+```bash
+node scripts/seed-templates.js \
+  --url http://127.0.0.1:4001 --token <ADMIN_TOKEN> \
+  --agents-dir /path/to/agent-mds \
+  [--guide /path/to/guide/README.md]
+```
+
+- Agent 目录中的 `agent-*.md` 按脚本内置的序号→分类映射归入 5 个分类（新媒体内容运营 / 增长与获客 / 销售与客户成功 / 企业职能与合规 / AI 与专业生产力），frontmatter 自动转为 `content_json`。
+- 导入的模板均为**全局模板**（所有 License 可见）。
+- 脚本遵守 admin 接口限速（60 次/分钟），遇到 429 自动退避重试。
+
+## 发布新版本（厂商侧）
 
 ```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/activation.js

@@ -0,0 +1,360 @@
+/**
+ * 中央授权激活模块（M5）
+ *
+ * license-server 作为「客户服务器」向中央授权服务（license.exflower.pro）激活并每日复核：
+ *  - customer_key 永不网传：proof = HMAC_SHA256(sha256(key+'|hmac'), action|prefix|fingerprint|ts)
+ *  - 中央返回 Ed25519 签名凭证（30 天滑动），本地缓存验签后生效
+ *  - 主端点不通自动切备端点；双端点同时不通靠缓存凭证撑到 token_expires_at
+ *  - 未激活 / 被顶替 / 合同过期 / 凭证超期 = 拒绝客户端服务（路由层门禁）
+ *
+ * 状态文件：DATA_DIR/activation.json
+ * 验签逻辑（canonical JSON + Ed25519）与 central-license/lib/credential.js 保持一致，
+ * 此处自包含拷贝——license-server 独立打包部署，不能跨目录引用。
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { DATA_DIR } = require('./db');
+
+const STATE_FILE = path.join(DATA_DIR, 'activation.json');
+const GRACE_MS = 7 * 86400000;        // 合同过期宽限期（与中央一致）
+const REMIND_MS = 30 * 86400000;      // 到期前提醒起点（与中央一致）
+const REVALIDATE_INTERVAL_MS = 24 * 3600000;  // 每日复核
+const RETRY_INTERVAL_MS = 3600000;            // 失败后每小时重试
+const HTTP_TIMEOUT_MS = 10000;
+
+const DEFAULT_PRIMARY = 'https://license.exflower.pro';
+
+// ── 状态读写 ──
+
+let state = null;
+
+function loadState() {
+  if (state) return state;
+  try {
+    state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+  } catch {
+    state = {};
+  }
+  return state;
+}
+
+function saveState() {
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  const tmp = STATE_FILE + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, STATE_FILE);
+}
+
+// 服务器指纹：首次生成后持久不变（激活身份）
+function getFingerprint() {
+  const s = loadState();
+  if (!s.fingerprint) {
+    s.fingerprint = crypto.randomUUID();
+    saveState();
+  }
+  return s.fingerprint;
+}
+
+// ── 验签（自包含，勿改逻辑，与 central-license/lib/credential.js 对齐） ──
+
+const CRED_FORMAT = 'exflower-server-license';
+
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return '[' + value.map(canonicalize).join(',') + ']';
+  }
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value).sort();
+    return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalize(value[k])).join(',') + '}';
+  }
+  return JSON.stringify(value);
+}
+
+function loadCentralPublicKey() {
+  if (process.env.CENTRAL_PUBLIC_KEY) return process.env.CENTRAL_PUBLIC_KEY.replace(/\\n/g, '\n');
+  return fs.readFileSync(path.join(__dirname, 'central-public.pem'), 'utf8');
+}
+
+/** 验签凭证，返回明文主体；失败返回 null */
+function verifyCredential(credential) {
+  try {
+    if (!credential || credential.format !== CRED_FORMAT || !credential.signature) return null;
+    const body = { ...credential };
+    delete body.signature;
+    const sig = Buffer.from(credential.signature, 'base64url');
+    const ok = crypto.verify(null, Buffer.from(canonicalize(body), 'utf8'), loadCentralPublicKey(), sig);
+    return ok ? body : null;
+  } catch {
+    return null;
+  }
+}
+
+// ── HMAC 证明（与 central-license/src/keys.js 协议一致） ──
+
+function computeProof(key, action, fingerprint, ts) {
+  const prefix = key.split('-').slice(0, 2).join('-');
+  const secret = crypto.createHash('sha256').update(key + '|hmac', 'utf8').digest('hex');
+  const hmac = crypto.createHmac('sha256', secret)
+    .update(`${action}|${prefix}|${fingerprint}|${ts}`, 'utf8')
+    .digest('hex');
+  return { key_prefix: prefix, fingerprint, ts, hmac };
+}
+
+// ── 中央端点调用（主备 failover） ──
+
+function getEndpoints() {
+  const s = loadState();
+  // CENTRAL_PRIMARY_URL：开发/测试覆盖主端点（生产默认 license.exflower.pro）
+  const list = [process.env.CENTRAL_PRIMARY_URL || (s.endpoints && s.endpoints.primary) || DEFAULT_PRIMARY];
+  if (s.endpoints && s.endpoints.backup) list.push(s.endpoints.backup);
+  return list.map(u => u.replace(/\/+$/, ''));
+}
+
+async function postJson(url, body) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), HTTP_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    });
+    const data = await res.json().catch(() => ({}));
+    return { status: res.status, data };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * 调中央 activate / revalidate，主备依次尝试。
+ * 返回 { ok, token?, contract_state?, error?, message?, superseded? }
+ */
+async function callCentral(action) {
+  const s = loadState();
+  const key = s.customer_key;
+  if (!key) return { ok: false, error: 'no_key' };
+  const ts = Date.now();
+  const proof = computeProof(key, action, getFingerprint(), ts);
+  let lastErr = 'all endpoints unreachable';
+  for (const base of getEndpoints()) {
+    try {
+      const { status, data } = await postJson(`${base}/api/v1/${action}`, proof);
+      if (data && data.success && data.token) {
+        return { ok: true, token: data.token, contract_state: data.contract_state, endpoint: base };
+      }
+      // 明确的业务拒绝（revoked/expired/superseded/bad_proof…）不再尝试备机——结果一样
+      const err = (data && data.error) || `http_${status}`;
+      return { ok: false, error: err, message: data && data.message };
+    } catch (e) {
+      lastErr = `${base}: ${e.name === 'AbortError' ? 'timeout' : e.message}`;
+    }
+  }
+  return { ok: false, error: 'unreachable', message: lastErr };
+}
+
+// ── 激活 / 复核 ──
+
+/** 首次激活（或清除后重新激活）。返回 { ok, error?, message? } */
+async function activateNow() {
+  const r = await callCentral('activate');
+  const s = loadState();
+  if (r.ok) {
+    const payload = verifyCredential(r.token);
+    if (!payload) {
+      s.last_error = '中央返回的凭证验签失败';
+      saveState();
+      return { ok: false, error: 'bad_signature' };
+    }
+    s.credential = r.token;
+    s.superseded = false;
+    s.terminal = null;
+    s.last_revalidate = new Date().toISOString();
+    s.last_error = null;
+    saveState();
+    return { ok: true, contract_state: r.contract_state };
+  }
+  s.last_error = r.message || r.error;
+  saveState();
+  return r;
+}
+
+/** 每日复核：凭证滑动顺延；被顶替/吊销/过期落状态。返回 { ok, error? } */
+async function revalidateNow() {
+  const s = loadState();
+  if (!s.customer_key) return { ok: false, error: 'no_key' };
+  if (!s.credential) return activateNow();           // 本地无凭证 → 走激活
+  const r = await callCentral('revalidate');
+  if (r.ok) {
+    const payload = verifyCredential(r.token);
+    if (!payload) {
+      s.last_error = '中央返回的凭证验签失败';
+      saveState();
+      return { ok: false, error: 'bad_signature' };
+    }
+    s.credential = r.token;
+    s.superseded = false;
+    s.last_revalidate = new Date().toISOString();
+    s.last_error = null;
+    saveState();
+    return { ok: true, contract_state: r.contract_state };
+  }
+  if (r.error === 'superseded') {
+    s.superseded = true;
+    s.last_error = r.message || '本服务器的激活已被同 License 的新激活顶替';
+    saveState();
+    return r;
+  }
+  if (r.error === 'not_activated') {
+    // 中央侧无此激活记录（库被重置等）→ 重新激活
+    return activateNow();
+  }
+  if (r.error === 'revoked' || r.error === 'expired') {
+    // 合同终止/超宽限：清凭证，立即进入拒绝服务
+    s.credential = null;
+    s.terminal = r.error;   // 终态：revoked / expired（区别于「从未激活」）
+    s.last_error = r.message || (r.error === 'revoked' ? 'License 已被吊销' : '合同已过期且超出宽限期');
+    saveState();
+    return r;
+  }
+  // 网络类失败：保留缓存凭证，下个周期再试
+  s.last_error = r.message || r.error;
+  saveState();
+  return r;
+}
+
+// ── 执行状态推导（路由门禁用） ──
+
+/**
+ * 当前执行状态：
+ *  unactivated    未配置 customer_key，或从未激活成功
+ *  superseded     被同 License 的新服务器顶替
+ *  revoked        被中央吊销（复核时确认）
+ *  expired        合同过期且超宽限期
+ *  token_expired  缓存凭证超 30 天且复核未成功（双端点失联兜底边界）
+ *  grace          合同过期宽限中（可服务，提醒）
+ *  expiring_soon  合同 30 天内到期（可服务，提醒）
+ *  active         正常
+ */
+function getStatus() {
+  const s = loadState();
+  const base = {
+    configured: !!s.customer_key,
+    key_prefix: s.customer_key ? s.customer_key.split('-').slice(0, 2).join('-') : null,
+    fingerprint: s.fingerprint || null,
+    endpoints: { primary: process.env.CENTRAL_PRIMARY_URL || (s.endpoints && s.endpoints.primary) || DEFAULT_PRIMARY, backup: (s.endpoints && s.endpoints.backup) || '' },
+    last_revalidate: s.last_revalidate || null,
+    last_error: s.last_error || null,
+  };
+  if (!s.customer_key) return { ...base, state: 'unactivated' };
+  if (s.superseded) return { ...base, state: 'superseded' };
+  if (!s.credential) return { ...base, state: s.terminal || 'unactivated', message: s.last_error };
+
+  const payload = verifyCredential(s.credential);
+  if (!payload) return { ...base, state: 'unactivated', message: '缓存凭证验签失败' };
+
+  const now = Date.now();
+  const expires = new Date(payload.expires_at).getTime();
+  const tokenExpires = new Date(payload.token_expires_at).getTime();
+  const info = {
+    customer: payload.customer,
+    license_id: payload.license_id,
+    expires_at: payload.expires_at,
+    token_expires_at: payload.token_expires_at,
+    days_remaining: Math.max(0, Math.ceil((expires - now) / 86400000)),
+    limits: payload.limits || {},
+  };
+  if (now > expires + GRACE_MS) return { ...base, ...info, state: 'expired' };
+  if (now > tokenExpires) return { ...base, ...info, state: 'token_expired' };
+  if (now > expires) return { ...base, ...info, state: 'grace' };
+  if (expires - now < REMIND_MS) return { ...base, ...info, state: 'expiring_soon' };
+  return { ...base, ...info, state: 'active' };
+}
+
+/** 是否放行客户端请求。放行时返回 null，否则返回 { status, message } */
+function gateRejection() {
+  const st = getStatus();
+  switch (st.state) {
+    case 'active':
+    case 'expiring_soon':
+    case 'grace':
+      return null;
+    case 'superseded':
+      return { status: 403, message: '本服务器的激活已被同 License 的新激活顶替，已停止服务' };
+    case 'revoked':
+      return { status: 403, message: 'License 已被厂商吊销，已停止服务' };
+    case 'expired':
+      return { status: 403, message: '授权合同已过期且超出宽限期' };
+    case 'token_expired':
+      return { status: 403, message: '授权凭证已过期且无法联系中央授权服务复核' };
+    default:
+      return { status: 403, message: '授权服务器未激活：请联系厂商获取 customer_key 并在管理台完成激活' };
+  }
+}
+
+// ── 配置（admin） ──
+
+/** 设置 customer_key / 备端点并立即激活 */
+async function configure({ customer_key, backup_endpoint }) {
+  const s = loadState();
+  if (customer_key !== undefined) {
+    const key = String(customer_key || '').trim().toUpperCase();
+    if (!/^EXFC-[0-9A-F]{6}-[0-9A-F]{6}-[0-9A-F]{6}-[0-9A-F]{6}$/.test(key)) {
+      return { ok: false, error: 'bad_format', message: 'customer_key 格式应为 EXFC-XXXXXX-XXXXXX-XXXXXX-XXXXXX' };
+    }
+    if (key !== s.customer_key) {
+      // 换 key：旧凭证/顶替/终态作废
+      s.customer_key = key;
+      s.credential = null;
+      s.superseded = false;
+      s.terminal = null;
+    }
+  }
+  if (backup_endpoint !== undefined) {
+    s.endpoints = { primary: (s.endpoints && s.endpoints.primary) || DEFAULT_PRIMARY, backup: String(backup_endpoint || '').trim() };
+  }
+  s.last_error = null;
+  saveState();
+  return activateNow();
+}
+
+/** 清除激活配置（回到未激活） */
+function clear() {
+  const s = loadState();
+  const fingerprint = s.fingerprint;   // 指纹保留，换 key 重激活仍同一身份
+  state = { fingerprint };
+  saveState();
+}
+
+// ── 调度器 ──
+
+let timer = null;
+
+async function tick() {
+  const s = loadState();
+  if (!s.customer_key) return;
+  const r = await revalidateNow();
+  const ok = r.ok;
+  schedule(ok ? REVALIDATE_INTERVAL_MS : RETRY_INTERVAL_MS);
+}
+
+function schedule(delay) {
+  if (timer) clearTimeout(timer);
+  timer = setTimeout(tick, delay);
+  timer.unref();
+}
+
+/** 启动时调用：有 key 则立即复核一次，然后按日循环（失败 1 小时重试） */
+function startScheduler() {
+  const s = loadState();
+  if (!s.customer_key) return;
+  tick().catch(e => {
+    console.error('[Activation] 复核异常:', e.message);
+    schedule(RETRY_INTERVAL_MS);
+  });
+}
+
+module.exports = { getStatus, gateRejection, configure, clear, activateNow, revalidateNow, startScheduler };