@jacksontian/kite-server 0.3.0 → 0.4.0

package/config.js

@@ -1,540 +0,0 @@
-/**
- * 云端 server 配置加载与校验。
- *
- * 纯 CLI 形态：任何动作都走子命令，裸 kites（无参数）只打印用法、绝不启动服务。
- * 只认 --config 指定的 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';
-
-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') {
-      values.push(args[i + 1]);
-      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] 缺少 --config：kites ${sub} --config <配置文件路径>`);
-    console.error('[server] 运行 kites --help 查看用法；配置模板见包内 config.example.yaml');
-    process.exit(1);
-  }
-  if (values.length > 1) {
-    console.error('[server] --config 只能指定一次');
-    process.exit(1);
-  }
-  const file = String(values[0] ?? '').trim();
-  if (!file || file.startsWith('-')) {
-    console.error('[server] --config 后需要给出配置文件路径');
-    process.exit(1);
-  }
-  return path.resolve(file);
-}
-
-function fail(errors, tag) {
-  console.error(`[${tag}] 配置错误，无法启动：`);
-  for (const e of errors) console.error('  - ' + e);
-  console.error(`[${tag}] 请检查 --config 指定的 YAML 文件，模板见包内 config.example.yaml`);
-  process.exit(1);
-}
-
-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) =>
-  z.string({ error: errMsg }).trim().optional().nullable().transform((v) => v ?? '');
-
-/** 把 zod issues 转成错误行：未知配置项逐条展开并附该层级可用项清单；
- * custom/各叶子的报错文案均已自带字段名，直接透传 */
-function formatIssues(issues, knownByPath) {
-  const out = [];
-  for (const iss of issues) {
-    if (iss.code === 'unrecognized_keys') {
-      const known = knownByPath[iss.path.join('.')] || [];
-      for (const key of iss.keys) out.push(`未知配置项 "${key}"（可用：${known.join(', ')}）`);
-      continue;
-    }
-    out.push(iss.message);
-  }
-  return out;
-}
-
-/** 展开开头的 ~ 为用户主目录（YAML 不会替我们做这件事） */
-function expandHome(p) {
-  if (p === '~') return os.homedir();
-  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
-  return p;
-}
-
-const SECRET_HINT =
-  '（两端共享的签名密钥；生成：node -e "console.log(require(\'crypto\').randomBytes(32).toString(\'hex\'))"）';
-
-const CONFIG_SCHEMA = z.strictObject({
-  apiSecret: z
-    .string({
-      error: (iss) =>
-        iss.input === undefined || iss.input === null
-          ? `缺少 apiSecret${SECRET_HINT}`
-          : 'apiSecret 必须是字符串（建议加引号，避免被 YAML 解析为数字）',
-    })
-    .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 必须是整数')
-    .min(1, 'port 超出范围 [1, 65535]')
-    .max(65535, 'port 超出范围 [1, 65535]')
-    .default(8787),
-  // 语义（~ 展开 / 相对启动工作目录 / 缺省 ~/.kite/data / 可写校验）
-  // 无法纯声明式表达，schema 只约束类型，解析后命令式处理
-  dataDir: optStr('dataDir 必须是字符串'),
-  maxTasks: z.coerce.number({ error: 'maxTasks 必须是数字' }).positive('maxTasks 必须是正数').default(200),
-  staleRunningSec: z.coerce
-    .number({ error: 'staleRunningSec 必须是数字' })
-    .positive('staleRunningSec 必须是正数')
-    .default(600),
-  sigWindowSec: z.coerce
-    .number({ error: 'sigWindowSec 必须是数字' })
-    .positive('sigWindowSec 必须是正数')
-    .default(300),
-  ptyIdleSec: z.coerce
-    .number({ error: 'ptyIdleSec 必须是数字' })
-    .positive('ptyIdleSec 必须是正数')
-    .default(90),
-  imWebhook: optStr('imWebhook 必须是字符串'),
-  imSecret: optStr('imSecret 必须是字符串'),
-  imNotifyEvents: z
-    .array(
-      // 与原实现一致：元素宽容转字符串后归一化小写再比枚举
-      z.coerce.string({ error: 'imNotifyEvents 元素必须是字符串' }).trim().toLowerCase().pipe(
-        z.enum(['done', 'failed', 'canceled'], {
-          error: (iss) => `imNotifyEvents 含非法事件 "${iss.input}"（可用：done|failed|canceled）`,
-        }),
-      ),
-      { error: 'imNotifyEvents 必须是数组（如 [failed, done]）' },
-    )
-    .default(['failed']),
-});
-
-/** 加载并校验配置，返回归一化后的常量对象 */
-export async function loadServerConfig() {
-  const tag = 'server';
-  maybeMeta();
-  dispatch(); // 裸调用/旧写法/未知子命令在此拦截；能走到下面的必是五个子命令之一
-  maybeKeygen();
-  maybeInit();
-  maybeDeploy();
-  const configFile = parseArgs();
-
-  let raw;
-  try {
-    raw = await fs.promises.readFile(configFile, 'utf8');
-  } catch (err) {
-    console.error(`[${tag}] 无法读取配置文件 ${configFile}: ${err.message}`);
-    process.exit(1);
-  }
-
-  const doc = YAML.parseDocument(raw);
-  if (doc.errors.length) {
-    console.error(`[${tag}] 配置文件 YAML 语法错误（${configFile}）：`);
-    for (const e of doc.errors) console.error('  - ' + e.message);
-    process.exit(1);
-  }
-  const cfg = doc.toJS();
-  if (!isPlainObject(cfg)) {
-    console.error(`[${tag}] 配置文件内容必须是一个键值映射（${configFile}）`);
-    process.exit(1);
-  }
-
-  const parsed = CONFIG_SCHEMA.safeParse(cfg);
-  if (!parsed.success) {
-    fail(formatIssues(parsed.error.issues, { '': Object.keys(CONFIG_SCHEMA.shape) }), tag);
-  }
-  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(
-    expandHome(v.dataDir || path.join(os.homedir(), '.kite', 'data')),
-  );
-  // 启动前校验可创建、可写：误配在这里一次性报清，
-  // 而不是运行中落盘失败才静默降级（只打日志、数据留在内存）
-  try {
-    await fs.promises.mkdir(dataDir, { recursive: true });
-    const probe = path.join(dataDir, '.rw-write-probe');
-    await fs.promises.writeFile(probe, '');
-    await fs.promises.rm(probe);
-  } catch (err) {
-    if (err.code === 'EEXIST' || err.code === 'ENOTDIR') {
-      errors.push(`dataDir 指向的路径已存在但不是目录：${dataDir}`);
-    } else {
-      errors.push(`dataDir 无法创建或不可写（${dataDir}）：${err.message}；请确认运行用户对该目录有读写权限`);
-    }
-  }
-  if (errors.length) fail(errors, tag);
-
-  // 典型误配提示：配了加签密钥但没配 webhook，secret 会被静默忽略
-  if (v.imSecret && !v.imWebhook) {
-    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,
-    staleRunningMs: v.staleRunningSec * 1000,
-    sigWindowSec: v.sigWindowSec,
-    ptyIdleMs: v.ptyIdleSec * 1000,
-    imWebhook: v.imWebhook,
-    imSecret: v.imSecret,
-    imNotifyEvents: new Set(v.imNotifyEvents),
-  };
-}