@jacksontian/kite-server 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,69 @@
+# @jacksontian/kite-server
+
+[kite](https://github.com/jacksontian/remote-work) 的云端信箱组件：部署在你的云服务器（VPS）上，
+提供 HMAC 签名鉴权的任务队列 API、WebSocket 实时推送和 Web 控制台（手机/PC 双版）。
+
+整体架构、端到端部署流程见仓库根 README；本文只讲 server 这一侧。
+
+## 职责
+
+- 接收控制台提交的任务，持久化到 `dataDir`（任务队列 / 日志 / 结果）
+- 通过 `/worker/ws` 出站长连接向 Worker 即时推送新任务，Worker 不监听任何端口
+- 托管 Web 控制台（`web/` 随包分发），浏览器打开即用；首页按 UA 自动分发
+  手机版（`index.html`）/ PC 版（`pc.html`），也可显式访问对应路径
+- 任务终态可选推送到钉钉群机器人（`imWebhook`）
+
+## 安装与启动
+
+```bash
+npm i -g @jacksontian/kite-server
+
+# 一步生成配置文件（自动填好随机 apiSecret/workerSecret，打印在输出里请保存）
+kites init    # 默认生成在当前目录（server.yaml）；生产部署用 kites init /opt/kite/server.yaml
+# 手工方式：cp "$(npm root -g)/@jacksontian/kite-server/config.example.yaml" /opt/kite/server.yaml 后编辑，
+# 密钥用 kites keygen 或下面命令生成（永不在网络上传输）：
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+
+kites check --config /opt/kite/server.yaml   # 干跑校验：只检查配置不启动服务，通过后退出
+kites start --config /opt/kite/server.yaml   # 前台启动服务；常驻托管交给 systemd（见下文 deploy）
+```
+
+启动后浏览器打开 `http://<vps>:8787`，粘贴密钥即可进入控制台。
+配置统一走 YAML 文件，以 `--config` 显式传入，不读取环境变量/.env。
+`kites` 是完全命令行化的工具：启动服务必须显式 `kites start`，裸 `kites`
+（不带子命令）只打印用法、不会启动服务。`kites --help` 查看完整用法，
+`kites --version` 查看版本号。
+
+## 配置项
+
+模板见包内 `config.example.yaml`：
+
+| 配置 | 说明 |
+|---|---|
+| `apiSecret` | 必填，两端共享的 HMAC 签名密钥 |
+| `port` | 监听端口，默认 8787 |
+| `dataDir` | 持久化目录，建议绝对路径，支持 `~` 展开，默认 `~/.kite/data` |
+| `maxTasks` | 终态任务最多保留条数 |
+| `staleRunningSec` | running 任务超时回收秒数（Worker 离线时判失败，pty 会话不受此限） |
+| `sigWindowSec` | 签名时间窗（秒），两端时钟漂移大时可调宽 |
+| `ptyIdleSec` | pty 会话空闲回收秒数 |
+| `imWebhook` / `imSecret` / `imNotifyEvents` | 钉钉群机器人通知，留空则完全静默 |
+
+## 生产部署
+
+- systemd unit：`kites deploy` 一步生成占位符已替换好的 unit（包内模板
+  `deploy/kiteserver.service`），再 `sudo install` 到 /etc/systemd/system/；
+  unit 以 `www-data` 运行，需给它 `dataDir` 写权限与配置文件读权限
+- 建议 Nginx/Caddy 反代加 HTTPS（Caddy 有域名即自动签证书）；仅 HTTP 部署时
+  按根 README「仅 HTTP 部署」一节做 IP 白名单与密钥轮换
+- `/health` 免签名探活端点，GET 返回 `{ ok: true }`，供 Caddy upstream health /
+  Uptime Kuma 等监控直接探测
+
+## 依赖
+
+Node ≥ 24；运行时依赖 `ws`、`yaml`、`zod`、`dingbot`，随包自动安装。
+
+## 配套组件
+
+Worker 端为 [`@jacksontian/kite-worker`](https://www.npmjs.com/package/@jacksontian/kite-worker)，
+部署在 Mac Mini 等内网机器上，只发起出站连接到本服务。

package/config.example.yaml

@@ -1,12 +1,28 @@
 # kite 云端 server 配置模板。
 # 复制为实际配置文件（如 server.yaml）后填写，启动时显式传入：
-#   node server.js --config /path/to/server.yaml
+#   kites start --config /path/to/server.yaml
 # 实际配置文件含密钥，不要提交到 git。
 
-# 必填：两端共享的 HMAC 签名密钥（永不在网络上传输）。生成：
+# 必填：控制台签名密钥（永不在网络上传输）。生成（二选一）：
+#   kites keygen   # 推荐：生成并打印配置片段
 #   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
 apiSecret: 换成你生成的密钥
 
+# 可选：Worker 专用密钥（建议另生成一个不同的）。配置后 Worker 侧 API
+# （claim/heartbeat/logs/finish）与 /worker/ws 只认该密钥，控制台密钥泄露
+# 不再等于 Worker 执行权；留空则两端共用 apiSecret。
+# Worker 端 worker.yaml 的 apiSecret 需与此处一致
+workerSecret: ""
+
+# 可选：多 Worker 独立密钥（workerId -> 密钥映射，每台 Worker 一个，
+# 各用 kites keygen 生成）。配置后服务端把 Worker 身份绑定到验签命中的密钥：
+# 自报 workerId 必须与映射键一致，Worker 之间无法互相领取定向任务/伪造上报。
+# 各 Worker 的 worker.yaml 里 workerId 与映射键一致、apiSecret 填对应密钥。
+# 可与上面的 workerSecret 并存（命中共享密钥时身份仍自报，兼容旧部署）
+# workerSecrets:
+#   mac-mini: 换成你生成的密钥1
+#   home-nas: 换成你生成的密钥2
+
 # 监听端口
 port: 8787
 

package/config.js

@@ -1,22 +1,111 @@
 /**
  * 云端 server 配置加载与校验。
  *
+ * 纯 CLI 形态：任何动作都走子命令，裸 kites（无参数）只打印用法、绝不启动服务。
  * 只认 --config 指定的 YAML 配置文件（不再读取任何环境变量）：
- *   node server.js --config /path/to/server.yaml
+ *   kites start --config /path/to/server.yaml
  * 结构与类型校验由 zod schema 完成（CONFIG_SCHEMA）：未知配置项、
  * 类型错误、缺必填项一次性报全后 exit 1；dataDir 的可创建/可写校验
  * 是运行时行为，仍在校验通过后单独执行。模板见包内 config.example.yaml。
+ *
+ * 另支持子命令与常规 CLI 选项：
+ *   kites start         启动云端服务（--config 必填）；裸 kites 不带子命令只打印用法，不启动
+ *   kites keygen        生成强随机密钥并打印配置片段
+ *   kites init [路径]   在目标位置（默认当前目录 server.yaml）生成填好随机密钥的配置文件
+ *   kites check         只校验 --config 指定的配置文件，通过打印摘要退出，不启动服务
+ *   kites deploy        基于包内 systemd 模板生成占位符已按本机替换好的 unit 文件
+ *   kites --help        打印用法说明（-h 等效）
+ *   kites --version     打印版本号（-V 等效）
+ * apiSecret 若仍是配置模板的占位符文本，启动时直接拦截，避免裸奔。
  */
 
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import crypto from 'node:crypto';
+import cp from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import YAML from 'yaml';
 import { z } from 'zod';
 
-/** 解析启动参数；--config 必填，缺失/重复/取不到值立即退出 */
-function parseArgs() {
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** 用法说明：--help/-h 输出到 stdout 并 exit 0（符合 CLI 惯例）；
+ * 裸 kites（不带任何子命令）同样只打印用法，不启动服务 */
+function printHelp() {
+  console.log('用法：kites <子命令> [选项]');
+  console.log('');
+  console.log('子命令：');
+  console.log('  kites start          启动云端服务（前台运行；常驻托管交给 systemd，见 deploy）');
+  console.log('    -c, --config <路径>  指定 YAML 配置文件（必填，模板见包内 config.example.yaml）');
+  console.log('  kites check          只校验 --config 指定的配置文件（改配置后干跑验证），通过即退出，不启动服务');
+  console.log('  kites keygen         生成强随机密钥并打印配置片段');
+  console.log('  kites init [路径]    基于包内模板生成配置文件（默认当前目录 server.yaml），自动填好随机密钥');
+  console.log('  kites deploy [输出]  基于包内 systemd 模板生成占位符已替换好的 unit 文件（默认当前目录 kiteserver.service），');
+  console.log('                       可选 --config <路径> 指定 unit 里的配置文件路径（默认 /opt/kite/server.yaml）');
+  console.log('');
+  console.log('选项：');
+  console.log('  -h, --help           打印本帮助');
+  console.log('  -V, --version        打印版本号');
+  console.log('');
+  console.log('不带任何子命令时只打印本用法，不会启动服务。');
+}
+
+/** --version/-V：读取包内 package.json 输出版本号（与 npm 发布版本一致） */
+function printVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, 'package.json'), 'utf8'));
+    console.log(`kites (${pkg.name}) ${pkg.version}`);
+  } catch (err) {
+    console.error(`[server] 无法读取包内 package.json：${err.message}`);
+    process.exit(1);
+  }
+}
+
+/** 常规 CLI 选项：--help/-h 与 --version/-V 优先于子命令/配置加载，识别到即退出 */
+function maybeMeta() {
   const args = process.argv.slice(2);
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    process.exit(0);
+  }
+  if (args.includes('--version') || args.includes('-V')) {
+    printVersion();
+    process.exit(0);
+  }
+}
+
+const SUBCOMMANDS = ['start', 'check', 'keygen', 'init', 'deploy'];
+
+/** 子命令分发：返回 argv[2] 的子命令名。CLI 化的核心约定——启动服务必须显式
+ * 走 start 子命令；裸 kites（不带任何参数）只打印用法退出，绝不启动服务 */
+function dispatch() {
+  const cmd = process.argv[2];
+  if (cmd === undefined) {
+    printHelp();
+    process.exit(0);
+  }
+  if (SUBCOMMANDS.includes(cmd)) return cmd;
+  if (cmd === '--config' || cmd === '-c' || cmd.startsWith('--config=')) {
+    // 旧版写法（kites --config x）：明确告知启动已改为 start 子命令，不静默兼容
+    console.error('[server] 启动服务请显式使用 start 子命令：kites start --config <配置文件路径>');
+    console.error('[server] 运行 kites --help 查看用法');
+    process.exit(1);
+  }
+  console.error(`[server] 未知子命令 "${cmd}"；运行 kites --help 查看用法`);
+  process.exit(1);
+}
+
+/** check 子命令位参数（argv[2] === 'check'）：其余照常解析，校验通过后在
+ * loadServerConfig 末尾打印摘要退出，不真正启动服务 */
+function isCheckMode() {
+  return process.argv[2] === 'check';
+}
+
+/** 解析 start/check 子命令后的参数；--config 必填，缺失/重复/取不到值/出现未知参数立即退出 */
+function parseArgs() {
+  const sub = process.argv[2]; // dispatch 已保证是 start 或 check
+  const args = process.argv.slice(3);
   const values = [];
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--config' || args[i] === '-c') {
@@ -24,11 +113,15 @@ function parseArgs() {
       i++;
     } else if (args[i].startsWith('--config=')) {
       values.push(args[i].slice('--config='.length));
+    } else {
+      // 输错参数不再静默忽略：报出具体参数并指路 --help，避免误以为已生效
+      console.error(`[server] 未知参数 "${args[i]}"；运行 kites --help 查看用法`);
+      process.exit(1);
     }
   }
   if (values.length === 0) {
-    console.error('[server] 缺少启动参数：node server.js --config <配置文件路径>');
-    console.error('[server] 配置模板见包内 config.example.yaml');
+    console.error(`[server] 缺少 --config：kites ${sub} --config <配置文件路径>`);
+    console.error('[server] 运行 kites --help 查看用法；配置模板见包内 config.example.yaml');
     process.exit(1);
   }
   if (values.length > 1) {
@@ -54,6 +147,168 @@ function isPlainObject(v) {
   return v !== null && typeof v === 'object' && !Array.isArray(v);
 }
 
+/** config.example.yaml 里的占位文本：原样未改就启动等于用公开"密钥"裸奔，必须拦下 */
+const PLACEHOLDER_SECRET = '换成你生成的密钥';
+
+/** keygen 子命令（kites keygen）：生成强随机密钥并打印配置片段，免去手工生成/搬运 hex */
+function maybeKeygen() {
+  if (process.argv[2] !== 'keygen') return;
+  const secret = crypto.randomBytes(32).toString('hex');
+  console.log('[server] 已生成签名密钥（永不在网络上传输，请妥善保管）：');
+  console.log('');
+  console.log('  ' + secret);
+  console.log('');
+  console.log('[server] 粘贴到 server.yaml（手机浏览器控制台使用同一密钥）：');
+  console.log('');
+  console.log('  apiSecret: ' + secret);
+  console.log('');
+  console.log('[server] 建议再执行一次 kites keygen 生成不同的 workerSecret（分权见 README「安全说明」），');
+  console.log('[server] Worker 端 worker.yaml 的 apiSecret 与 workerSecret 保持一致');
+  process.exit(0);
+}
+
+/** init/deploy 就跑在目标环境里，顺手解析 kites 可执行路径（等效 `which kites`），
+ * 好把 unit 安装命令里的 __KITES_BIN__ 占位符换成现成值；
+ * 取不到（如仓库源码里直接跑）则返回 null 由调用方决定回退方式 */
+function resolveKitesBin() {
+  try {
+    const p = cp.execSync('which kites', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (p) return p;
+  } catch { /* PATH 里没有 kites */ }
+  return null;
+}
+
+/** init 子命令（kites init [配置文件路径]）：基于包内模板一步生成配置文件，
+ * 自动填好随机 apiSecret/workerSecret，免去「复制模板 + keygen + 粘贴」三步；
+ * 默认生成在当前目录（好找），生产部署建议显式 init 到 /opt/kite/server.yaml；
+ * 已存在的目标绝不覆盖 */
+function maybeInit() {
+  if (process.argv[2] !== 'init') return;
+  const rawPath = process.argv[3] || 'server.yaml';
+  if (!rawPath.trim() || rawPath.startsWith('-')) {
+    console.error('[server] init 用法：kites init [配置文件路径]（默认当前目录 server.yaml）');
+    process.exit(1);
+  }
+  const target = path.resolve(expandHome(rawPath));
+  if (fs.existsSync(target)) {
+    console.error(`[server] ${target} 已存在，init 不会覆盖；如需重新生成请先备份删除或换路径`);
+    process.exit(1);
+  }
+  let tpl;
+  try {
+    tpl = fs.readFileSync(path.join(__dirname, 'config.example.yaml'), 'utf8');
+  } catch (err) {
+    console.error(`[server] 无法读取包内配置模板 config.example.yaml：${err.message}`);
+    process.exit(1);
+  }
+  const apiSecret = crypto.randomBytes(32).toString('hex');
+  const workerSecret = crypto.randomBytes(32).toString('hex');
+  // dataDir 固化为配置文件同目录下的绝对路径，与启动工作目录解耦
+  const dataDir = path.join(path.dirname(target), 'data');
+  const content = tpl
+    .replace(`apiSecret: ${PLACEHOLDER_SECRET}`, `apiSecret: ${apiSecret}`)
+    .replace('workerSecret: ""', `workerSecret: ${workerSecret}`)
+    .replace('dataDir: ./data', `dataDir: ${dataDir}`);
+  if (!content.includes(apiSecret)) {
+    console.error('[server] 包内配置模板结构与预期不符（找不到占位符），请改用手工方式：复制 config.example.yaml 后填写');
+    process.exit(1);
+  }
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.writeFileSync(target, content, { mode: 0o600 });
+  } catch (err) {
+    console.error(`[server] 无法写入 ${target}：${err.message}`);
+    console.error('[server] 目标目录需要 root 权限时请改用 sudo，或 init 到自定义路径');
+    process.exit(1);
+  }
+  console.log(`[server] 已生成配置：${target}（权限 0600）`);
+  console.log('');
+  console.log(`  apiSecret（控制台/手机浏览器粘贴这个）：${apiSecret}`);
+  console.log(`  workerSecret（Worker 专用，填入 worker.yaml 的 apiSecret）：${workerSecret}`);
+  console.log('');
+  console.log('[server] 密钥已写入配置文件，请另行妥善保存（永不在网络上传输）');
+  console.log(`[server] 干跑验证：kites check --config ${target}`);
+  console.log(`[server] 启动：kites start --config ${target}`);
+  if (target.startsWith('/opt/kite')) {
+    console.log('[server] 生产部署后续步骤（systemd 以 www-data 运行）：');
+    console.log(`  sudo mkdir -p ${dataDir} && sudo chown -R www-data:www-data ${dataDir}`);
+    console.log(`  sudo chown www-data:www-data ${target}`);
+    console.log('  安装 systemd unit（kites deploy 自动按本机环境替换占位符，无需手工 sed）：');
+    console.log(`    kites deploy --config ${target}`);
+    console.log('    sudo install -m 644 kiteserver.service /etc/systemd/system/kiteserver.service');
+    console.log('    sudo systemctl daemon-reload && sudo systemctl enable --now kiteserver');
+  } else {
+    console.log('[server] 生产部署建议放 /opt/kite：sudo kites init /opt/kite/server.yaml，');
+    console.log('[server] 再按 README「云端部署」做 www-data 授权与 systemd unit 安装（kites deploy 一步生成）');
+  }
+  process.exit(0);
+}
+
+/** deploy 子命令（kites deploy [输出路径] [--config <配置文件路径>]）：
+ * 读取包内 systemd 模板，把 __KITES_BIN__ / __CONFIG_FILE__ 按本机环境替换后
+ * 写出可直接安装的 unit 文件，免去手工 sed；默认输出到当前目录 kiteserver.service。
+ * 产物可随升级重复生成（覆盖写），安装命令打印在输出里 */
+function maybeDeploy() {
+  if (process.argv[2] !== 'deploy') return;
+  const args = process.argv.slice(3);
+  let rawOut = '';
+  let rawConfig = '/opt/kite/server.yaml';
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--config' || args[i] === '-c') {
+      rawConfig = String(args[++i] ?? '');
+    } else if (args[i].startsWith('--config=')) {
+      rawConfig = args[i].slice('--config='.length);
+    } else if (!args[i].startsWith('-') && !rawOut) {
+      rawOut = args[i];
+    } else {
+      console.error(`[server] deploy 用法：kites deploy [unit 输出路径] [--config <配置文件路径>]`);
+      console.error(`[server] 无法识别的参数："${args[i]}"`);
+      process.exit(1);
+    }
+  }
+  if (!rawConfig.trim() || rawConfig.startsWith('-')) {
+    console.error('[server] deploy 的 --config 后需要给出配置文件路径');
+    process.exit(1);
+  }
+  const configFile = path.resolve(expandHome(rawConfig));
+  const outPath = path.resolve(expandHome(rawOut || 'kiteserver.service'));
+
+  const kitesBin = resolveKitesBin();
+  if (!kitesBin) {
+    console.error('[server] PATH 里找不到 kites 可执行文件（which kites 失败），无法填写 unit 的 ExecStart');
+    console.error('[server] 请在 npm 全局安装本包的机器上运行：npm i -g @jacksontian/kite-server');
+    process.exit(1);
+  }
+  let tpl;
+  try {
+    tpl = fs.readFileSync(path.join(__dirname, 'deploy', 'kiteserver.service'), 'utf8');
+  } catch (err) {
+    console.error(`[server] 无法读取包内 unit 模板 deploy/kiteserver.service：${err.message}`);
+    process.exit(1);
+  }
+  const content = tpl.replaceAll('__KITES_BIN__', kitesBin).replaceAll('__CONFIG_FILE__', configFile);
+  if (/__[A-Z_]+__/.test(content)) {
+    console.error('[server] 包内 unit 模板结构与预期不符（仍有未替换的占位符），请改用手工方式安装');
+    process.exit(1);
+  }
+  try {
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, content, { mode: 0o644 });
+  } catch (err) {
+    console.error(`[server] 无法写入 ${outPath}：${err.message}`);
+    process.exit(1);
+  }
+  console.log(`[server] 已生成 systemd unit：${outPath}`);
+  console.log(`  ExecStart: ${kitesBin} start --config ${configFile}`);
+  if (!fs.existsSync(configFile)) {
+    console.warn(`[server] 注意：${configFile} 尚不存在，安装 unit 前请先生成：kites init ${configFile}`);
+  }
+  console.log('[server] 安装（unit 以 www-data 运行，注意先完成 README「云端部署」的目录授权）：');
+  console.log(`  sudo install -m 644 ${outPath} /etc/systemd/system/kiteserver.service`);
+  console.log('  sudo systemctl daemon-reload && sudo systemctl enable --now kiteserver');
+  process.exit(0);
+}
+
 /** 可选字符串：缺省/给 null 都按空串处理，统一 trim
  * （zod v4 中 union(z.undefined()) 不能让对象键变可选，须用 .optional()） */
 const optStr = (errMsg) =>
@@ -94,6 +349,19 @@ const CONFIG_SCHEMA = z.strictObject({
     })
     .trim()
     .min(1, `缺少 apiSecret${SECRET_HINT}`),
+  // Worker 专用密钥（可选）：配置后 Worker 侧 API（claim/heartbeat/logs/finish）
+  // 与 /worker/ws 只认该密钥，控制台密钥（apiSecret）泄露不再等于 Worker 执行权。
+  // 留空则两端共用 apiSecret（向后兼容）
+  workerSecret: optStr('workerSecret 必须是字符串'),
+  // 多 Worker 独立密钥（可选）：workerId -> 密钥映射，每台 Worker 一密钥。
+  // 配置后 Worker 侧验签命中该映射的密钥即绑定其 workerId 身份（请求自报的
+  // workerId 必须一致），Worker 之间无法互相冒充；与 workerSecret 可并存
+  // （命中共享密钥时身份仍自报，兼容旧部署）。均未配置时回落共用 apiSecret
+  workerSecrets: z
+    .record(z.string(), z.string({ error: 'workerSecrets 的密钥必须是字符串' }).trim(), {
+      error: 'workerSecrets 必须是「workerId: 密钥」的映射',
+    })
+    .optional(),
   port: z.coerce
     .number({ error: 'port 必须是数字' })
     .int('port 必须是整数')
@@ -134,6 +402,11 @@ const CONFIG_SCHEMA = z.strictObject({
 /** 加载并校验配置，返回归一化后的常量对象 */
 export async function loadServerConfig() {
   const tag = 'server';
+  maybeMeta();
+  dispatch(); // 裸调用/旧写法/未知子命令在此拦截；能走到下面的必是五个子命令之一
+  maybeKeygen();
+  maybeInit();
+  maybeDeploy();
   const configFile = parseArgs();
 
   let raw;
@@ -163,6 +436,46 @@ export async function loadServerConfig() {
   const v = parsed.data;
   const errors = [];
 
+  // 模板占位符原样未改：此时启动等于用公开"密钥"裸奔，显式拦下并指路 keygen
+  if (v.apiSecret === PLACEHOLDER_SECRET) {
+    errors.push('apiSecret 仍是配置模板的占位符文本，请生成真实密钥后填入：kites keygen');
+  }
+  if (v.workerSecret === PLACEHOLDER_SECRET) {
+    errors.push('workerSecret 仍是配置模板的占位符文本，请生成真实密钥后填入（或留空共用 apiSecret）：kites keygen');
+  }
+
+  // workerSecrets：键即 workerId（与 worker.yaml 的 workerId 同规则）；
+  // 密钥非空/非占位符，且两两不同（同密钥会让服务端无法区分身份）
+  const workerSecrets = {};
+  if (v.workerSecrets) {
+    const seen = new Map(); // secret -> workerId
+    for (const [id, secret] of Object.entries(v.workerSecrets)) {
+      if (!/^[\w.-]{1,128}$/.test(id)) {
+        errors.push(`workerSecrets 的 Worker 标识 "${id}" 非法（只能含字母/数字/._-，不超过 128 字符）`);
+        continue;
+      }
+      if (!secret) {
+        errors.push(`workerSecrets.${id} 密钥不能为空（kites keygen 生成）`);
+        continue;
+      }
+      if (secret === PLACEHOLDER_SECRET) {
+        errors.push(`workerSecrets.${id} 仍是配置模板的占位符文本，请填入真实密钥：kites keygen`);
+        continue;
+      }
+      if (seen.has(secret)) {
+        errors.push(`workerSecrets 中 "${id}" 与 "${seen.get(secret)}" 配置了相同密钥，服务端无法区分两者身份`);
+        continue;
+      }
+      seen.set(secret, id);
+      workerSecrets[id] = secret;
+    }
+    if (v.workerSecret && seen.has(v.workerSecret)) {
+      errors.push(
+        `workerSecret 与 workerSecrets.${seen.get(v.workerSecret)} 的密钥相同，身份绑定会有歧义，请配置不同密钥`,
+      );
+    }
+  }
+
   // 未配置时默认主目录下的固定位置，与配置文件位置、启动目录都解耦；
   // 相对路径相对启动工作目录解析（path.resolve 默认行为），建议写绝对路径
   const dataDir = path.resolve(
@@ -189,9 +502,31 @@ export async function loadServerConfig() {
     console.warn(`[${tag}] 已配置 imSecret 但 imWebhook 为空，加签密钥将被忽略`);
   }
 
+  // check 子命令（kites check --config x）：与启动完全相同的校验已通过，
+  // 打印归一化摘要后直接退出，改完配置不用真启动服务（占端口）就能验证。
+  // 密钥只报长度不回显内容
+  if (isCheckMode()) {
+    console.log(`[${tag}] 配置校验通过：${configFile}`);
+    console.log(`  port: ${v.port}`);
+    console.log(`  dataDir: ${dataDir}`);
+    console.log(`  apiSecret: 已配置（${v.apiSecret.length} 字符）`);
+    console.log(`  workerSecret: ${v.workerSecret ? '已单独配置（Worker 专用密钥）' : '未配置，与 apiSecret 共用'}`);
+    console.log(`  IM 通知: ${v.imWebhook ? `已配置（事件：${v.imNotifyEvents.join(', ')}）` : '未配置'}`);
+    console.log(`[${tag}] 可以启动服务：kites start --config ${configFile}`);
+    process.exit(0);
+  }
+
+  // Worker 侧可接受的密钥及身份绑定：workerSecrets 条目验签命中即绑定 workerId；
+  // workerSecret 为共享兼容路径（workerId 为 null 表示身份自报）；
+  // 两者都未配置时回落共用 apiSecret（单密钥模式）
+  const workerAuth = Object.entries(workerSecrets).map(([workerId, secret]) => ({ secret, workerId }));
+  if (v.workerSecret) workerAuth.push({ secret: v.workerSecret, workerId: null });
+  if (!workerAuth.length) workerAuth.push({ secret: v.apiSecret, workerId: null });
+
   return {
     configFile,
     apiSecret: v.apiSecret,
+    workerAuth,
     port: v.port,
     dataDir,
     maxTasks: v.maxTasks,

package/deploy/kiteserver.service

@@ -0,0 +1,24 @@
+# 云服务器（systemd）上托管云端 API 的 unit 文件。
+# 模板随 npm 包分发（包内 deploy/kiteserver.service，
+# 路径：$(npm root -g)/@jacksontian/kite-server/deploy/kiteserver.service）。
+# 占位符 __KITES_BIN__ / __CONFIG_FILE__ 由 `kites deploy` 按本机环境自动替换
+# （安装步骤见 README「云端部署」一节），请勿手工编辑本模板的替换产物之外的内容。
+
+[Unit]
+Description=kite server
+After=network.target
+
+[Service]
+Type=simple
+User=www-data
+# 配置文件与 data 目录的家；server.yaml 里 dataDir: ./data 相对此目录解析
+WorkingDirectory=/opt/kite
+# 配置只认 --config 传入的 YAML 文件（不再读环境变量），模板见包内 config.example.yaml；
+# 启动服务必须显式走 start 子命令（裸调用只打印用法不会启动）
+ExecStart=__KITES_BIN__ start --config __CONFIG_FILE__
+Environment=NODE_ENV=production
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=multi-user.target

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacksontian/kite-server",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "kite 云端信箱 API：HMAC 签名鉴权、任务队列、WebSocket 实时推送、手机端 Web 控制台",
   "type": "module",
   "license": "MIT",
@@ -11,10 +11,14 @@
     "kites": "server.js"
   },
   "main": "server.js",
+  "scripts": {
+    "test": "node --test"
+  },
   "files": [
     "server.js",
     "config.js",
     "web/",
+    "deploy/",
     "config.example.yaml"
   ],
   "keywords": [