zipcalm 0.0.0-stage → 1.0.2

package/server/app.js

@@ -0,0 +1,309 @@
+// 应用装配（Fastify 实例 + 插件与路由挂载）
+//
+// 层次（docs/12 §二）：http/ 只做入口（中间件 + 路由），core/ 放业务，lib/ 放工具。
+// 本文件只负责"接线"，不含任何业务逻辑，便于将来换 Web 框架时只改这一处。
+//
+// 结构：每个装配步骤是一个**模块级小函数**（实例 / 观测 / 安全 / 任务层 / 压缩层 / 前端 / 关停钩子），
+// buildApp 只按顺序把它们串起来 —— 顺序本身有讲究（见各步骤注释）。
+
+import crypto from 'node:crypto';
+import path from 'node:path';
+
+import Fastify from 'fastify';
+import cookie from '@fastify/cookie';
+import fastifyStatic from '@fastify/static';
+
+import { pathExists } from './lib/fs-probe.js';
+import { createAuthStore } from './core/auth/store.js';
+import { verifyPassword } from './core/auth/password.js';
+import { createDeleteService } from './core/compress/deleter.js';
+import { createBlacklistService } from './core/compress/blacklist.js';
+import { createMetricsCollector } from './core/metrics/collector.js';
+import { createOrchestrator } from './core/compress/orchestrator.js';
+import { createCapabilityRegistry } from './core/compress/capRegistry.js';
+import { createRegistry } from './core/compress/registry.js';
+import { createTaskEvents } from './core/task/events.js';
+import { createTaskManager } from './core/task/manager.js';
+import { createTaskStore } from './core/task/store.js';
+import { registerAuth } from './http/middleware/auth.js';
+import { registerErrorHandling } from './http/middleware/error.js';
+import { registerRequestLogger } from './http/middleware/logger.js';
+import { registerPathGuard } from './http/middleware/pathGuard.js';
+import router from './http/router.js';
+import { APP_VERSION } from '../shared/app-version.js';
+
+/** 版本号：与 web 共用 shared/app-version.js 一处定义（避免两处各写一个后漂移） */
+export { APP_VERSION };
+
+/** 请求体上限：M1 只有登录表单，1MB 足够；压缩上传在 M2 之后再评估 */
+const BODY_LIMIT_BYTES = 1024 * 1024;
+
+/**
+ * 构造密码校验函数。
+ * - 优先 passwordHash（scrypt，推荐）；
+ * - 允许 password 明文配置（仅本机开发用），但比较时走 sha256 + timingSafeEqual，避免长度侧信道。
+ */
+function createPasswordVerifier(authConfig) {
+  if (authConfig.passwordHash) {
+    return (plain) => verifyPassword(plain, authConfig.passwordHash);
+  }
+  if (authConfig.password) {
+    const expected = crypto.createHash('sha256').update(String(authConfig.password)).digest();
+    return async (plain) => {
+      const actual = crypto.createHash('sha256').update(String(plain)).digest();
+      return crypto.timingSafeEqual(expected, actual);
+    };
+  }
+  // schema 校验已拦截这种情况，这里只是兜底
+  throw new Error('auth.passwordHash 或 auth.password 必须配置其中之一');
+}
+
+function createFastifyInstance(config) {
+  return Fastify({
+    logger: false, // 用我们自己的结构化日志（lib/logger.js），避免双份日志格式
+    trustProxy: config.server.trustProxy === true,
+    bodyLimit: BODY_LIMIT_BYTES,
+    disableRequestLogging: true,
+    genReqId: () => crypto.randomUUID(),
+  });
+}
+
+/**
+ * 容错 JSON 解析：**空 body 视为无请求体**，而不是 400。
+ * Fastify 默认对"声明了 application/json 但 body 为空"的请求直接回 400
+ * （FST_ERR_CTP_EMPTY_JSON_BODY），这对 `DELETE /tasks/{id}` 这类天然无 body 的请求很不友好 ——
+ * 客户端只要习惯性带上 Content-Type: application/json 就会被拒。
+ */
+function registerTolerantJsonParser(app) {
+  app.addContentTypeParser('application/json', { parseAs: 'string' }, (request, body, done) => {
+    if (body === undefined || body === null || body === '') {
+      done(null, undefined);
+      return;
+    }
+    try {
+      done(null, JSON.parse(body));
+    } catch (error) {
+      error.statusCode = 400;
+      done(error, undefined);
+    }
+  });
+}
+
+/** 认证与路径白名单：authStore 先加载；pathGuard 提供 fsContext（后续所有层都依赖它） */
+async function registerSecurityLayer(app, { config, logger }) {
+  const authStore = createAuthStore({ config: config.auth, logger, dataDir: config.storage.dataDir });
+  await authStore.load();
+  app.decorate('authStore', authStore);
+
+  registerAuth(app, { store: authStore, config: config.auth });
+  await registerPathGuard(app, { config, logger });
+  return authStore;
+}
+
+/**
+ * M3 任务层：落盘 store → 事件总线 → 管理器（含启动恢复）。
+ * 恢复必须在路由挂载前完成：这样第一个请求看到的就已是 interrupted 终态（INV-10）。
+ */
+async function createTaskLayer({ config, logger }) {
+  const store = createTaskStore({
+    dataDir: config.storage.dataDir,
+    historyMax: config.limits.taskHistoryMax,
+    logger,
+  });
+  await store.init();
+
+  const events = createTaskEvents({ retention: config.limits.sseRetention, logger });
+  const manager = createTaskManager({
+    logger,
+    store,
+    events,
+    // 任务活动记录保留策略（failed/interrupted 的上限，来自配置、不写死）
+    retention: {
+      max: config.limits.taskRetentionMax,
+      days: config.limits.taskRetentionDays,
+    },
+    // waiting_confirm 最长等待（数据模型 §八：默认 30 分钟，0=不限；非法值已在 config 层告警）
+    confirmTimeoutMs: config.delete.confirmTimeoutMs,
+    // M5-F09 启动对账所需路径（trash 孤儿补记 + deleting 中断收敛）
+    trashDir: config.storage.trashDir,
+    logDir: config.storage.logDir,
+    rootAbs: config.storage.root,
+  });
+  const recovery = await manager.recover();
+  logger.info('任务状态已加载', { ...recovery, bootId: manager.bootId });
+
+  return { store, events, manager };
+}
+
+/** M2 压缩层：格式注册表 → 删除服务 → 编排器（编排器要用 rootAbs，必须在 pathGuard 之后） */
+async function createCompressLayer({ config, logger, projectRoot, manager, blacklist }) {
+  const registry = createRegistry({ logger });
+  await registry.discover();
+
+  // 能力注册表（docs/19）：扫描能力包 + 与格式包 capabilities 声明对账（PW-4 数据面）
+  const capRegistry = createCapabilityRegistry({ logger, formatIds: registry.ids() });
+  await capRegistry.rescan();
+  for (const failure of capRegistry.loadFailures()) {
+    logger.warn('能力插件加载失败（该能力禁用，不影响其他包）', { failure });
+  }
+
+  const deleteService = createDeleteService({
+    config,
+    logger,
+    logDir: config.storage.logDir,
+    trashDir: config.storage.trashDir,
+    projectRoot,
+    rootAbs: config.storage.root,
+  });
+  const orchestrator = createOrchestrator({
+    config,
+    logger,
+    registry,
+    capRegistry,
+    manager,
+    deleteService,
+    // M6：打包阶段用它解析黑名单层（与预检同一套判定）
+    blacklist,
+    rootAbs: config.storage.root,
+  });
+
+  return { registry, capRegistry, deleteService, orchestrator };
+}
+
+/**
+ * 优雅关闭分两步（顺序很关键）：
+ * - preClose：Fastify 关闭服务器**之前**的钩子，用来结束 SSE 长连接 ——
+ *   否则服务器会一直等这些 hijack 的连接，导致优雅停止超时被 KILL；
+ * - onClose：服务器关闭后收尾，把节流中的任务状态落盘（避免丢最后 500ms 的进度）。
+ */
+function registerShutdownHooks(app, { sseClients, manager, authStore, metrics }) {
+  // 指标定时器必须先停：它们已 unref、但明确 clearInterval 才能保证"停了就是停了"
+  app.addHook('onClose', async () => {
+    if (metrics) metrics.stop();
+  });
+  app.addHook('preClose', async () => {
+    for (const response of sseClients) {
+      try {
+        response.end();
+      } catch {
+        /* 连接可能已断 */
+      }
+    }
+    sseClients.clear();
+  });
+
+  app.addHook('onClose', async () => {
+    await manager.flush();
+    // 认证存储同样要收尾：刚签发的 token 若还压在 50ms 节流里，不 flush 就会随进程一起丢（重启后客户端突然 401）
+    if (authStore && typeof authStore.flush === 'function') await authStore.flush();
+  });
+}
+
+/** 静态前端（可选）：web/dist 存在时同源提供，浏览器地址即 API 地址，无需代理或 CORS */
+async function registerFrontend(app, { projectRoot, logger }) {
+  const distDir = path.join(projectRoot, 'web', 'dist');
+  if (await pathExists(distDir)) {
+    await app.register(fastifyStatic, { root: distDir, prefix: '/', wildcard: false });
+    logger.info('static frontend enabled', { dir: path.relative(projectRoot, distDir) });
+    return;
+  }
+  logger.warn('web/dist 不存在，仅提供 API（如需同源 UI，先执行 npm run build）', {
+    dir: path.relative(projectRoot, distDir),
+  });
+}
+
+/**
+ * 装配 M2（压缩/解压）与 M3（任务）两层，并把它们挂到 app 上。
+ * 单独成函数是为了让 buildApp 只保留"顺序"这一件事（每层内部各有自己的依赖顺序）。
+ */
+async function attachCompressAndTaskLayers(app, { config, logger, projectRoot }) {
+  // 黑名单：用户层落盘在 storage/blacklist-user.json（config.json 是启动期只读快照，不适合放可改设置）
+  const blacklist = createBlacklistService({ dataDir: config.storage.dataDir, logger });
+  await blacklist.loadUser(); // 启动即加载一次用户层（坏文件只告警、不影响启动）
+  app.decorate('blacklist', blacklist);
+
+  // 硬链接去重日志目录（docs/15：storage/logs/hardlink-*.jsonl）
+  app.decorate('hardlinkLogDir', config.storage.logDir);
+
+  const taskLayer = await createTaskLayer({ config, logger });
+  const compressLayer = await createCompressLayer({
+    config,
+    logger,
+    projectRoot,
+    manager: taskLayer.manager,
+    blacklist,
+  });
+
+  // PW-1：把 capRegistry 的通用脱敏器注入 manager（落盘前剔除 capabilities 里的明文）。
+  // compressLayer 在 taskLayer 之后创建，这里补挂（manager 的 ctx 是闭包，走公开方法不可行——
+  // 直接改 deps 引用不行，所以 createTaskLayer 接受可选注入参数）。
+  taskLayer.manager.__setCapabilitySanitizer(compressLayer.capRegistry.sanitizeOptionsForPersist);
+
+  app.decorate('m2', {
+    registry: compressLayer.registry,
+    capRegistry: compressLayer.capRegistry,
+    manager: taskLayer.manager,
+    orchestrator: compressLayer.orchestrator,
+    deleteService: compressLayer.deleteService,
+    config,
+  });
+
+  // M3 的任务三件套（路由与 /health 都从这里取；store/events 不进 API 响应）
+  // sseClients：活跃的 SSE 响应集合，关停时统一 end()，否则长连接会让优雅停止超时
+  const sseClients = new Set();
+  app.decorate('tasks', {
+    store: taskLayer.store,
+    events: taskLayer.events,
+    manager: taskLayer.manager,
+    sseClients,
+  });
+
+  return { taskLayer, sseClients };
+}
+
+/**
+ * 构建 Fastify 应用（不监听端口，便于测试里直接 inject）。
+ * @param {{config: object, logger: object, projectRoot: string}} options
+ */
+export async function buildApp(options) {
+  const { config, logger, projectRoot } = options;
+
+  const app = createFastifyInstance(config);
+  await app.register(cookie);
+  registerTolerantJsonParser(app);
+
+  // 顺序有讲究：请求日志 → 错误处理 → 认证 → 路径白名单 → 任务/压缩层 → 路由
+  registerRequestLogger(app, { logger });
+  registerErrorHandling(app, { logger });
+  const authStore = await registerSecurityLayer(app, { config, logger });
+
+  const { taskLayer, sseClients } = await attachCompressAndTaskLayers(app, { config, logger, projectRoot });
+
+  // M7 指标采集：两个定时器（系统 5s / 进程 1s），随服务启停
+  const metrics = createMetricsCollector({ logger, taskStats: () => taskLayer.manager.stats() });
+  metrics.start();
+  app.decorate('metrics', metrics);
+
+  registerShutdownHooks(app, { sseClients, manager: taskLayer.manager, authStore, metrics });
+
+  const meta = {
+    version: APP_VERSION,
+    startedAt: Date.now(),
+    bootId: taskLayer.manager.bootId,
+    rootWritable: true,
+  };
+  app.decorate('meta', meta);
+
+  await app.register(router, {
+    prefix: '/api/v1',
+    config,
+    logger,
+    store: authStore,
+    meta,
+    verifyPassword: createPasswordVerifier(config.auth),
+  });
+
+  await registerFrontend(app, { projectRoot, logger });
+
+  return { app, authStore, meta };
+}

package/server/boot.js

@@ -0,0 +1,145 @@
+// 启动入口（M1）
+//
+// 职责：加载配置 → 建日志 → 装配应用 → 监听 → 优雅退出。
+// 进程管理（PID 文件、后台运行）交给 scripts/start.sh，这里保持"前台进程"语义，
+// 这样 systemd/supervisor/nohup 都能直接用。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { buildApp } from './app.js';
+import { loadConfig } from './config/index.js';
+import { createLogger } from './lib/logger.js';
+import { checkNodeVersion } from './lib/runtime-guard.js';
+
+// 项目根 = 本文件所在目录（server/）的上一级；不写死绝对路径
+const PROJECT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+/** PID 文件路径：由 start.sh 通过环境变量传入（脚本与进程"谁写 PID"只能有一个权威） */
+const PID_FILE = process.env.ZIPCALM_PID_FILE || null;
+
+/** 由进程自己写 PID：比启动器用 $! 猜更可靠（shell 里 `&` 作用于复合列表时 $! 会拿到子 shell 的 PID） */
+function writePidFile() {
+  if (!PID_FILE) return;
+  try {
+    // 先确保目录存在：PID 路径可由 ZIPCALM_PID_FILE 指定到任意位置，父目录不存在时 writeFile 会 ENOENT
+    fs.mkdirSync(path.dirname(PID_FILE), { recursive: true });
+    fs.writeFileSync(PID_FILE, `${process.pid}\n`, 'utf8');
+  } catch (error) {
+    process.stderr.write(`[ZipCalm] 写入 PID 文件失败：${error.message}\n`);
+  }
+}
+
+/** 退出时清理 PID 文件（只删属于本进程的，避免误删新实例的） */
+function removePidFile() {
+  if (!PID_FILE) return;
+  try {
+    if (fs.existsSync(PID_FILE)) {
+      const recorded = fs.readFileSync(PID_FILE, 'utf8').trim();
+      if (recorded === String(process.pid)) fs.unlinkSync(PID_FILE);
+    }
+  } catch {
+    // 清理失败不影响退出
+  }
+}
+
+async function main() {
+  const env = process.env;
+
+  // ===== 0. 运行期自检（版本不够就明确拒绝启动，别等用户点压缩才炸）=====
+  // 放在配置之前：这是"环境根本不满足"的问题，与配置无关，越早说清越好
+  const nodeCheck = checkNodeVersion();
+  if (!nodeCheck.ok) {
+    process.stderr.write(`[ZipCalm] 运行环境不满足要求，已拒绝启动：\n${nodeCheck.message}\n`);
+    process.exit(1);
+  }
+
+  // ===== 1. 配置 =====
+  let loaded;
+  try {
+    loaded = await loadConfig({ projectRoot: PROJECT_ROOT, env });
+  } catch (error) {
+    // 配置错误必须"人话"输出到 stderr 并退出（否则用户只会看到一个堆栈）
+    process.stderr.write(`[ZipCalm] 配置错误：${error.message}\n`);
+    process.exit(1);
+  }
+  const { config, warnings, sources } = loaded;
+
+  const logger = createLogger({ level: config.log.level });
+  // 自检结果入日志（版本号 + 通过状态），便于事后核"这台机器的运行时到底够不够"
+  logger.info('runtime check passed', {
+    node: nodeCheck.current,
+    requiredNode: nodeCheck.required,
+    message: nodeCheck.message,
+  });
+  for (const warning of warnings) logger.warn('config warning', { message: warning });
+
+  logger.info('config loaded', {
+    sources: sources.length > 0 ? sources : ['defaults'],
+    port: config.server.port,
+    host: config.server.host,
+    storageRoot: config.storage.root,
+    logLevel: config.log.level,
+  });
+
+  // ===== 2. 装配 =====
+  const { app, authStore, meta } = await buildApp({ config, logger, projectRoot: PROJECT_ROOT });
+  const stopCleanup = authStore.startCleanup();
+
+  // ===== 3. 信号与异常处理器（**必须在 listen 之前注册**）=====
+  // 为什么提前：启动期收到 SIGTERM 时若还没有处理器，Node 走默认行为**直接退出且不留任何日志**，
+  // 表现为"日志停在半路、进程消失"，排查时看不出是谁杀的（实测踩过）。
+  let listening = false;
+  let shuttingDown = false;
+  const shutdown = async (reason) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    if (listening) {
+      logger.info('shutting down', { reason });
+    } else {
+      // 启动未完成就收到退出信号：单独一条，便于区分"被外部杀掉"和"启动失败"
+      logger.warn('shutting down during startup', { reason, phase: 'before-listen' });
+    }
+    try {
+      await app.close();
+    } catch (error) {
+      logger.error('close failed', { error: error.message });
+    }
+    stopCleanup();
+    removePidFile();
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+  process.on('SIGINT', () => shutdown('SIGINT'));
+
+  // 兜底：未捕获异常不能"静默把服务带走"（先记日志再优雅退出，让 start.sh 能重启）
+  process.on('unhandledRejection', (reason) => {
+    logger.error('unhandledRejection', { reason: reason instanceof Error ? reason.message : String(reason) });
+  });
+  process.on('uncaughtException', (error) => {
+    logger.error('uncaughtException', {
+      error: error.message,
+      stack: String(error.stack || '').split('\n').slice(0, 4).join(' | '),
+    });
+    shutdown('uncaughtException');
+  });
+
+  // ===== 4. 监听 =====
+  try {
+    await app.listen({ host: config.server.host, port: config.server.port });
+  } catch (error) {
+    logger.error('listen failed', { error: error.message, port: config.server.port, host: config.server.host });
+    process.stderr.write(`[ZipCalm] 端口监听失败：${error.message}\n`);
+    process.exit(1);
+  }
+  listening = true;
+
+  logger.info('ZipCalm server ready', { port: config.server.port, bootId: meta.bootId });
+
+  // 监听成功后再写 PID 文件：这样"PID 文件存在"就等于"服务已就绪"
+  writePidFile();
+}
+
+main();

package/server/config/defaults.js

@@ -0,0 +1,153 @@
+// 默认配置（docs/M0/数据模型.md §八 的 M1 子集）
+//
+// 只放 M1 真正用到的段：server / auth / storage / limits / log。
+// compress（M2）、blacklist（M6）、metrics（M7）等到各自里程碑再加，避免出现"配了但没人读"的死配置。
+//
+// 覆盖优先级（低 → 高）：本文件默认值 → <dataDir>/config.json → 环境变量。
+
+/** POSIX 单段文件名长度上限（NAME_MAX 的常见值）：给 maxPathSegmentLength 当默认值用 */
+const POSIX_NAME_MAX = 255;
+/** 单次列目录返回的默认最大条目数（超出截断并置 truncated=true） */
+const DEFAULT_MAX_LIST_ENTRIES = 5000;
+
+export const DEFAULT_CONFIG = {
+  server: {
+    /** 监听地址：0.0.0.0 表示所有网卡（NAS 场景方便局域网访问） */
+    host: '0.0.0.0',
+    port: 3010,
+    trustProxy: false,
+  },
+
+  auth: {
+    username: 'admin',
+    /** 二选一：passwordHash 优先（推荐）；都为空则启动失败并提示生成方式 */
+    password: null,
+    passwordHash: null,
+    /** Session（HttpOnly Cookie）有效期：7 天滑动续期（API 规范 §二） */
+    sessionTtlMs: 7 * 24 * 60 * 60 * 1000,
+    /** Bearer Token 有效期：30 天（API 规范 §二） */
+    tokenTtlMs: 30 * 24 * 60 * 60 * 1000,
+    /** 登录失败限流 */
+    loginRateLimit: { max: 5, windowMs: 60 * 1000 },
+    /** Cookie 名（API 规范 §二：zc_session） */
+    cookieName: 'zc_session',
+  },
+
+  storage: {
+    /** 可浏览/可压缩的默认存储根：单根回退，也是侧栏里的「应用数据」项 */
+    root: './storage/fs-root',
+    /**
+     * 可切换的根列表（docs/16 §三）：[{ id, label, path }]。
+     * **空数组 = 自动发现**（群晖列 /volumeN 下的共享；其他系统列卷/挂载点）。
+     * 显式配置优先于自动发现；相对 path 与 root 同规则按项目根解析。
+     */
+    roots: [],
+    /** 运行态数据目录（任务状态、令牌、日志、回收站都在这里；已 gitignore） */
+    dataDir: './storage',
+    trashDir: './storage/trash',
+    logDir: './storage/logs',
+  },
+
+  compress: {
+    /** 默认压缩格式（M2 只有 zip） */
+    defaultFormat: 'zip',
+    /** 默认压缩模式：single（每个源各一个包）/ bundle（合成一个包） */
+    defaultMode: 'single',
+    /** 默认保留原文件（删除必须显式请求 + 二次确认，docs/06 §一） */
+    defaultKeepOriginal: true,
+    /** zip 默认压缩级别 */
+    defaultLevel: 6,
+    /** 并行开关（占位：v1 强制串行，docs/05 §二） */
+    parallelEnabled: false,
+    /** INV-07：剩余空间必须 ≥ 待压总量 × preflightFactor（不允许 < 2） */
+    preflightFactor: 2,
+  },
+
+  delete: {
+    /**
+     * 删除执行模式（docs/M0 数据模型 §八）：
+     * - log-only（默认）：只写删除日志、**不真删** —— 开发期核对"校验通过 → 触发删除"的时机；
+     * - trash：真删并进 storage/trash/<batchId>/（可恢复），正式部署用；
+     * 未知值 → 告警并回落 log-only（安全默认：绝不因配置写错而真删数据）。
+     */
+    /**
+     * 回收站后端（mode=trash 时生效）：
+     * - auto（默认）：探测到群晖 `/usr/syno/bin/synorecycle` 就用系统回收站（删除进 DSM 的 #recycle，
+     *   用户可在 File Station 里恢复/清空），否则用项目 storage/trash；
+     * - system：强制系统回收站，不可用/失败时**回退项目 trash**（不报错、绝不真删）；
+     * - project：强制项目 storage/trash；
+     * - none：不启用回收站 —— 删除会被拒绝并记 failed（绝不退化成真删）。
+     */
+    mode: 'log-only',
+    trashBackend: 'auto',
+    /**
+     * waiting_confirm 最长等待（数据模型 §八 / §3.3 硬要求 1）：
+     * 默认 30 分钟；0 = 不超时；非法值（负数/非数字）→ 告警并回落默认。
+     * 超时按放弃删除结算（delete.status='skipped'，reason=confirm_timeout）——超时绝不等于确认。
+     */
+    confirmTimeoutMs: 1800000,
+  },
+
+  limits: {
+    /** 路径字符串长度上限（整条路径，超长直接判非法路径） */
+    maxPathLength: 4096,
+    /**
+     * 单个路径段的长度上限（对应 POSIX NAME_MAX）。
+     * 为什么不写死 255：不同文件系统（ext4/btrfs/APFS/NTFS、以及各种 FUSE/网络盘）上限不同，
+     * 这里是**可配置**的：默认取 POSIX 常见值 255，部署到特殊文件系统时可调。
+     * 超过即在进入磁盘调用前返回 INVALID_PATH(400)，不让底层 ENAMETOOLONG 冒成 500。
+     */
+    maxPathSegmentLength: POSIX_NAME_MAX,
+    /** 单次列目录返回的最大条目数（超出截断并置 truncated=true） */
+    maxListEntries: DEFAULT_MAX_LIST_ENTRIES,
+    /** 单次压缩任务最多源条目数 */
+    maxSourcesPerTask: 200,
+    /**
+     * 单次「移动」最多条目数（API 规范 §4.2：超限 VALIDATION_FAILED）。
+     * 为什么要有上限：v1 是同步操作，一次几百个 rename 会让请求超时；超过应分批或改用复制任务。
+     */
+    maxMoveItems: 200,
+    /** 单次「删除」最多条目数（同上，删除还要逐条走回收站，代价更高） */
+    maxDeleteItems: 200,
+    /** 前端默认分页大小 */
+    defaultPageSize: 200,
+    /**
+     * 任务历史保留条数（task-history.jsonl 的裁剪上限，数据模型 §六）
+     */
+    taskHistoryMax: 200,
+    /** SSE 环形缓冲保留的事件条数（`since` 超出窗口即改用快照兜底，API 规范 §五 规则 2） */
+    sseRetention: 1000,
+    /** SSE 心跳间隔（防中间设备把长连接当空闲连接掐掉） */
+    sseHeartbeatMs: 15000,
+    /**
+     * 任务活动记录保留条数（`failed`/`interrupted` 这两类"为可重试而保留"的终态上限，
+     * 数据模型 §六 规则 6）：超出即清理最旧的，避免 tasks.json 全量重写越来越慢。
+     * 上限走配置、不写死；`done`/`aborted` 本来就即写即移出，不参与该计数。
+     */
+    taskRetentionMax: 100,
+    /** 任务活动记录保留天数（与条数任一先到即清理） */
+    taskRetentionDays: 7,
+  },
+
+  log: {
+    level: 'info',
+  },
+};
+
+/** 环境变量覆盖白名单（只允许"单值"型部署差异，结构性配置一律走 config.json） */
+export const ENV_OVERRIDES = {
+  ZIPCALM_HOST: ['server', 'host'],
+  ZIPCALM_PORT: ['server', 'port'],
+  ZIPCALM_STORAGE_ROOT: ['storage', 'root'],
+  ZIPCALM_DATA_DIR: ['storage', 'dataDir'],
+  // CLI（npx 安装形态）需要把回收站与日志也指到用户数据目录，否则它们会落在包目录里
+  ZIPCALM_TRASH_DIR: ['storage', 'trashDir'],
+  ZIPCALM_LOG_DIR: ['storage', 'logDir'],
+  ZIPCALM_LOG_LEVEL: ['log', 'level'],
+  ZIPCALM_USERNAME: ['auth', 'username'],
+  ZIPCALM_PASSWORD: ['auth', 'password'],
+  ZIPCALM_PASSWORD_HASH: ['auth', 'passwordHash'],
+};
+
+/** 敏感字段：任何日志/响应都不允许带明文（INV-16） */
+export const SENSITIVE_CONFIG_KEYS = ['password', 'passwordHash'];