@jacksontian/kite-server 0.1.0

package/config.example.yaml

@@ -0,0 +1,37 @@
+# kite 云端 server 配置模板。
+# 复制为实际配置文件（如 server.yaml）后填写，启动时显式传入：
+#   node server.js --config /path/to/server.yaml
+# 实际配置文件含密钥，不要提交到 git。
+
+# 必填：两端共享的 HMAC 签名密钥（永不在网络上传输）。生成：
+#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+apiSecret: 换成你生成的密钥
+
+# 监听端口
+port: 8787
+
+# 持久化目录；建议写绝对路径；相对路径相对启动工作目录解析，
+# 支持 ~ 展开；留空/删掉该行则默认 ~/.kite/data
+dataDir: ./data
+
+# 终态（done/failed/canceled）任务最多保留条数
+maxTasks: 200
+
+# running 任务超过该秒数且 Worker 离线则判失败（pty 交互会话不受此限）
+staleRunningSec: 600
+
+# 签名时间窗（秒）；两端时钟漂移大时可调宽
+sigWindowSec: 300
+
+# pty 会话空闲（Worker 断开且无控制台输入）回收秒数
+ptyIdleSec: 90
+
+# 钉钉群机器人 webhook；配置后任务终态事件以 markdown 推送到群，留空则完全静默
+imWebhook: ""
+
+# 机器人启用“加签”安全设置时的密钥（SEC 开头）；关键词/白名单模式留空
+imSecret: ""
+
+# 触发 IM 推送的事件集合，可选值：done / failed / canceled
+imNotifyEvents:
+  - failed

package/config.js

@@ -0,0 +1,205 @@
+/**
+ * 云端 server 配置加载与校验。
+ *
+ * 只认 --config 指定的 YAML 配置文件（不再读取任何环境变量）：
+ *   node server.js --config /path/to/server.yaml
+ * 结构与类型校验由 zod schema 完成（CONFIG_SCHEMA）：未知配置项、
+ * 类型错误、缺必填项一次性报全后 exit 1；dataDir 的可创建/可写校验
+ * 是运行时行为，仍在校验通过后单独执行。模板见包内 config.example.yaml。
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import YAML from 'yaml';
+import { z } from 'zod';
+
+/** 解析启动参数；--config 必填，缺失/重复/取不到值立即退出 */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  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));
+    }
+  }
+  if (values.length === 0) {
+    console.error('[server] 缺少启动参数：node server.js --config <配置文件路径>');
+    console.error('[server] 配置模板见包内 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);
+}
+
+/** 可选字符串：缺省/给 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}`),
+  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';
+  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 = [];
+
+  // 未配置时默认主目录下的固定位置，与配置文件位置、启动目录都解耦；
+  // 相对路径相对启动工作目录解析（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 为空，加签密钥将被忽略`);
+  }
+
+  return {
+    configFile,
+    apiSecret: v.apiSecret,
+    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),
+  };
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@jacksontian/kite-server",
+  "version": "0.1.0",
+  "description": "kite 云端信箱 API：HMAC 签名鉴权、任务队列、WebSocket 实时推送、手机端 Web 控制台",
+  "type": "module",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "bin": {
+    "kites": "server.js"
+  },
+  "main": "server.js",
+  "files": [
+    "server.js",
+    "config.js",
+    "web/",
+    "config.example.yaml"
+  ],
+  "keywords": [
+    "remote",
+    "agent",
+    "mailbox",
+    "websocket",
+    "hmac"
+  ],
+  "dependencies": {
+    "dingbot": "^2.1.0",
+    "ws": "^8.21.3",
+    "yaml": "^2.8.2",
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}