dsh_ai1net_server/src/config.ts

/**
 * Deployment-varying configuration. Every tunable is a validated field here
 * (or read from env), never a hardcoded constant inside the app.
 * @module dshs/config
 */

import { randomBytes } from 'node:crypto'
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
import { homedir, hostname } from 'node:os'
import { join } from 'node:path'

/** Isolation tier. `soft` = per-user home/workspace + sandbox (same OS user);
 * `account` = per-user OS account via a setuid wrapper (Linux, needs root). */
export type IsolationMode = 'soft' | 'account'

/** Deployment mode. `local` = single-host child_process (setuid/iptables);
 * `k8s` = multi-replica control plane spawning per-user DSH Pods via the K8s API. */
export type DeployMode = 'local' | 'k8s' | 'cluster'

/** Resolved, immutable runtime configuration. */
export interface ServerConfig {
  /** Bind host for the orchestrator HTTP server. */
  host: string
  /** Bind port; `0` requests an ephemeral port. */
  port: number
  /** SQLite database path. */
  dbPath: string
  /** Postgres connection string; when set, the DB backend is Postgres (k8s/HA). */
  dbUrl?: string
  /** Root under which per-user homes (`users/<id>/home`) and workspaces live. */
  dataRoot: string
  /** Shared read-only skill directory for all users (injected as
   * `DSH_BUNDLED_SKILL_DIR` into every spawned DSH); empty = feature off. */
  bundledSkillDir: string
  /** Argv used to launch a child DSH; first element is the executable. */
  dshCommand: string[]
  /** Pino log level. */
  logLevel: string
  /** Set the `Secure` flag on session cookies (enable behind HTTPS). */
  secureCookies: boolean
  /** Session lifetime in seconds. */
  sessionTtlSeconds: number
  /** Max upload request body in bytes (base64 JSON; ~0.75× the file size). */
  maxUploadBytes: number
  /** Delay before auto-restarting a crashed child DSH, in milliseconds. */
  restartBackoffMs: number
  /** Upper bound for the exponential crash-restart backoff (档案 20). */
  restartBackoffMaxMs: number
  /** Auto-restarts allowed inside `crashWindowMs` before the circuit opens. */
  crashMaxRestarts: number
  /** Rolling window used to count auto-restarts (档案 20). */
  crashWindowMs: number
  /** Uptime after which a main counts as recovered and the backoff resets. */
  crashStableMs: number
  /** 档案 78：熔断首次冷却时长（冷却期内拒绝隐式启动）。 */
  crashBreakerCooldownMs: number
  /** 档案 78：熔断冷却上限（多次熔断后指数加长到此为止）。 */
  crashBreakerMaxCooldownMs: number
  /** Isolation tier (see {@link IsolationMode}); local mode only. */
  isolationMode: IsolationMode
  /** Argv prefix that drops privileges; `{UID}`/`{GID}` are substituted. Local mode only. */
  spawnAsUserCommand: string[]
  /** Base uid for the deterministic per-user uid. */
  baseUid: number
  /** Parent domain for per-user subdomains (`<username>.<baseDomain>`); empty = disabled. */
  baseDomain: string
  /** Cookie `Domain` value (e.g. `.example.com`) so the session reaches subdomains; empty = host-only. */
  cookieDomain: string
  /** Whether to pass `--patch` to child DSHs (needs a dsh CLI that supports it). */
  enablePatch: boolean
  /** Enable the loopback OUTPUT owner-match port guard (Linux + root). Local mode only. */
  portGuard: boolean
  /** Cap on resident main instances per host (0 = no cap). Local mode idle reap. */
  maxIdleInstances: number
  /** A main instance with no proxied/entered activity for this long is stopped
   * (0 = disabled). Local mode idle reap. */
  instanceIdleTtlSeconds: number
  /** Period between idle-reap scans (seconds). Local mode idle reap. */
  idleReapIntervalSeconds: number
  /** Secret used to encrypt per-user secrets at rest (from env or dataRoot/secret.key). */
  encryptionSecret: string
  /** Deployment mode (see {@link DeployMode}). */
  deployMode: DeployMode
  /** K8s namespace for per-user DSH resources (k8s mode only). */
  k8sNamespace: string
  /** Image for per-user DSH Pods (k8s mode only). */
  dshImage: string
  /** Image for the per-user file sidecar (k8s mode only; shares the control-plane image). */
  controlPlaneImage: string
  /** imagePullSecret every generated per-user Pod/Job uses (k8s mode only). */
  imagePullSecret: string
  /** 443 egress whitelist CIDRs for per-user DSH Pods (Phase 4 egress 收敛);
   * empty = keep the current `0.0.0.0/0` (except private ranges). */
  egressCidrs: string[]
  /** ServiceAccount the orchestrator runs as (k8s mode only). */
  k8sServiceAccount: string
  /** This replica's identity for leader election (POD_NAME, else hostname). */
  podName: string
  // ── cluster 模式（T08 S3/S4；设计 §1.1）────────────────────────────────
  /** 本机在 `dsh_hosts.id` 里的标识（`deployMode=cluster` 时必填语义）。 */
  clusterHostId: string
  /** 本机 worker agent 的**基址**（Manager 侧用它投递实例操作），如 `http://127.0.0.1:9000`。 */
  clusterAgentUrl: string
  /** 与 agent 约定的共享密钥（仅内网 + nft 白名单）。 */
  clusterAgentToken: string
  /** agent 返回给 Manager 做代理的实例地址（同机 1a = `127.0.0.1`）。 */
  clusterInstanceHost: string
  /**
   * **worker 上**的 dataRoot（T08 S5）。
   * 空 = 与本地 `dataRoot` 相同（1a 形态）。多机部署必须显式配置 —— 而且是**基线约定**：
   * 所有 worker 的 dataRoot 必须是同一个绝对路径（同镜像即可满足，设计 §14.3）。
   */
  clusterWorkerDataRoot: string
  /**
   * **worker 侧**会合地址（覆盖网络 S1）：worker 主动拨入的 SSH 反向隧道落点。
   * 形如 `ssh://[email protected]:32022`（也接受不带 scheme 的 `root@host:port`）。空 = 隧道关闭。
   * ⚠️ 与旧变量 `DSHS_TUNNEL_TARGET` **双路径并存**（新变量优先、旧变量兜底）⇒
   * 删掉新 env 即回到旧路径，**零代码回滚**。
   */
  clusterRendezvousUrl: string
  /**
   * **Manager 侧**用的自研中继入口（覆盖网络 R3），如 `wss://alotbuy.com/dshs-relay`。
   * 仅作管理面展示 / 诊断（`RelayRendezvous.dialTarget()`）；空 = 该实现不注册。
   */
  relayUrl: string
  /**
   * 中继的**状态查询地址**（覆盖网络 R3），如 `http://127.0.0.1:20080/status`。
   *
   * 为什么必须查它：relay 为每个注册端口在**它自己的回环**上开一条监听，端口号是
   * `listen(0)` 动态分配的（实测 42067）⇒ **Manager 无法从 `dsh_hosts.endpoint` 推出来**，
   * 只能问 relay「hostId + 端口 → 回环口 + 在线态」。**空 = 不注册 `relay` 实现**
   * （于是 `via='relay'` 会回退到 `manager-ssh`，行为与今天一致）。
   */
  relayStatusUrl: string
  /**
   * **拨号通道**（覆盖网络 R5）：Manager 用哪个 hostId 向 relay 注册为「拨号方」。
   * 默认 `manager`；空 ⇒ **不启用拨号通道**（一切照旧）。
   *
   * 为什么需要它：R1–R4 的落点在 **relay 主机的回环**上 ⇒ Manager 必须与 relay 同机，
   * 「中继可换机 / 多实例」就做不到。拨号通道把落点搬到 **Manager 自己本机**
   * （`src/net/relay/dialer.ts` 的口池）⇒ relay 放哪台机器都行。
   * ⚠️ 该 hostId 必须同时出现在 relay 的密钥文件里，且列在 relay 的 `DSHS_RELAY_DIALERS` 白名单里。
   */
  relayDialHost: string
  /** 拨号方的 64 位 hex 密钥（**与 relay 密钥文件里 `relayDialHost` 那一项逐字节相同**）。空 ⇒ 不启用。 */
  relayDialSecret: string
  /** 拨号落点口池起点。**必须避开 OS 临时端口段（32768–60999）与实例端口段**。默认 25000。 */
  relayDialPortBase: number
  /** 拨号落点口池扫描宽度。默认 1000。 */
  relayDialPortSpan: number
  /** 拨号落点口池大小（= 最多同时挂多少个 `(hostId, port)` 落点）。默认 64。 */
  relayDialPool: number
  /**
   * **实例端口区间起点**（覆盖网络 S3）。`0` = 保持旧行为（`listen(0)` 随机取端口）。
   *
   * 为什么必须能配：跨机实例的**隧道落点全部挤在 Manager 的 `127.0.0.1`**，而
   * `findFreePort()` 是**每台 worker 各自**用 `listen(0)` 随机取的 ⇒ **两台 worker 取到同号
   * 就会撞号**：`-R` 失败被静默忽略（`tunnel.forward()` 的返回值无人看），Manager 仍按该
   * 端口拨 ⇒ **打到别人的实例**（2026-09-16 实测）。给每台 worker 一段**互不重叠**的区间
   * 即可根治，且**不需要改 sshd、不需要端口映射表**。
   *
   * ⚠️ 选区间时应**避开 OS 临时端口段**（本项目两台机器均为 `32768-60999`）。
   */
  instancePortBase: number
  /** 实例端口区间长度（条数）。仅当 `instancePortBase > 0` 时生效。 */
  instancePortSpan: number
  // ── 覆盖网络 P0-2 引导三级链（`net/relay/directory.ts`）─────────────────
  /**
   * **本机所属的网**（P0-1 的 `network_id`）。运维网 = `ops`（47 / 106 / 未来的中继）；
   * 用户设备用 `u:<userId>`。它进目录文档的 `network` 字段（**被签名覆盖**）。
   */
  overlayNetworkId: string
  /**
   * **内置种子**（引导链第 ①级之后的兜底入口）。常量位 —— 已持证书、**不新增域名**。
   *
   * ⚠️ 约定："**引导地址 = 中继入口同源**"：目录端点 = 种子 origin + 固定路径
   * （`net/relay/directory.ts` 的 `DIRECTORY_PATH`）。本文件是**基础层**、
   * 不许 import 能力层 ⇒ 路径字面量两处各写一次，**改动必须两处同改**。
   */
  overlayBootstrapSeeds: string[]
  /**
   * **受信目录签名公钥**（PEM 或裸 32 字节 hex/base64，逗号分隔）。
   * 空 ⇒ 目录一律不接受（**不可验 = 不接受**）⇒ 只剩 env 与种子兜底两级。
   */
  overlayDirTrustedKeys: string[]
  /** 目录**签名私钥**（Ed25519 PEM）路径。空 ⇒ 目录端点 `503`（**绝不发未签名目录**）。 */
  overlayDirKeyFile: string
  /** 目录缓存文件（客户端侧）。空 ⇒ 不缓存（每次取目录，多一次往返）。 */
  overlayDirectoryCacheFile: string
  // ── 覆盖网络 序③ 一机一钥 + 信任根（`net/relay/identity.ts`）────────────
  /**
   * **本机节点私钥**文件路径（Ed25519 PEM，**0600**、属主必须是跑 dsh 的那个用户）。
   * 空 ⇒ 本机不发起身份（只做 HMAC，过渡期形态）。
   */
  overlayNodeKeyFile: string
  /** **本机入网凭据**文件路径（`{"doc":{…},"sig":"<base64>"}`，由离线信任根授权的签名者签发）。 */
  overlayNodeGrantFile: string
}

/** Untyped overrides collected from argv / env. */
export interface ConfigOverrides {
  host?: string
  port?: string | number
  dbPath?: string
  dbUrl?: string
  dataRoot?: string
  bundledSkillDir?: string
  dshCommand?: string[]
  logLevel?: string
  secureCookies?: boolean
  sessionTtlSeconds?: number | string
  maxUploadBytes?: number | string
  restartBackoffMs?: number | string
  restartBackoffMaxMs?: number | string
  crashMaxRestarts?: number | string
  crashWindowMs?: number | string
  crashStableMs?: number | string
  crashBreakerCooldownMs?: number | string
  crashBreakerMaxCooldownMs?: number | string
  isolationMode?: IsolationMode | string
  spawnAsUserCommand?: string[]
  baseUid?: number | string
  baseDomain?: string
  cookieDomain?: string
  enablePatch?: boolean
  portGuard?: boolean
  maxIdleInstances?: number | string
  instanceIdleTtlSeconds?: number | string
  idleReapIntervalSeconds?: number | string
  encryptionSecret?: string
  deployMode?: DeployMode | string
  k8sNamespace?: string
  dshImage?: string
  controlPlaneImage?: string
  imagePullSecret?: string
  egressCidrs?: string[]
  k8sServiceAccount?: string
  podName?: string
  clusterHostId?: string
  clusterAgentUrl?: string
  clusterAgentToken?: string
  clusterInstanceHost?: string
  clusterWorkerDataRoot?: string
  clusterRendezvousUrl?: string
  relayUrl?: string
  relayStatusUrl?: string
  relayDialHost?: string
  relayDialSecret?: string
  relayDialPortBase?: number | string
  relayDialPortSpan?: number | string
  relayDialPool?: number | string
  instancePortBase?: number | string
  instancePortSpan?: number | string
  overlayNetworkId?: string
  overlayNodeKeyFile?: string
  overlayNodeGrantFile?: string
  overlayBootstrapSeeds?: string[]
  overlayDirTrustedKeys?: string[]
  overlayDirKeyFile?: string
  overlayDirectoryCacheFile?: string
}

const DEFAULT_HOST = '127.0.0.1'

// 覆盖网络 S3：实例端口区间（`0` = 保持旧行为 `listen(0)` 随机）。
const DEFAULT_INSTANCE_PORT_BASE = 0
const DEFAULT_INSTANCE_PORT_SPAN = 1000
const DEFAULT_PORT = 3080
const DEFAULT_DSH_COMMAND = ['dsh']
const DEFAULT_LOG_LEVEL = 'info'
const DEFAULT_SESSION_TTL_SECONDS = 60 * 60 * 24 * 7
const DEFAULT_MAX_UPLOAD_BYTES = 25 * 1024 * 1024
const DEFAULT_RESTART_BACKOFF_MS = 1000
/** 崩溃自愈退避上限（档案 20）。 */
const DEFAULT_RESTART_BACKOFF_MAX_MS = 30000
/** 熔断窗口内允许的自动重启次数（档案 20）。 */
const DEFAULT_CRASH_MAX_RESTARTS = 5
/** 熔断窗口长度（档案 20）。 */
const DEFAULT_CRASH_WINDOW_MS = 600000
/** 连续运行多久视为已恢复、重置退避步数（档案 20）。 */
const DEFAULT_CRASH_STABLE_MS = 60000
// 档案 78：熔断冷却 —— 首次 10 分钟，指数加长，封顶 6 小时
const DEFAULT_CRASH_BREAKER_COOLDOWN_MS = 600000
const DEFAULT_CRASH_BREAKER_MAX_COOLDOWN_MS = 21600000
const DEFAULT_ISOLATION_MODE: IsolationMode = 'soft'
const DEFAULT_SPAWN_AS_USER_COMMAND = [
  'setpriv',
  '--reuid',
  '{UID}',
  '--regid',
  '{GID}',
  '--inh-caps=-all',
  '--clear-groups',
  '--',
]
const DEFAULT_BASE_UID = 100000
const DEFAULT_BASE_DOMAIN = ''
const DEFAULT_COOKIE_DOMAIN = ''
const DEFAULT_ENABLE_PATCH = false
const DEFAULT_MAX_IDLE_INSTANCES = 4
const DEFAULT_INSTANCE_IDLE_TTL_SECONDS = 60 * 60 * 24 * 7
const DEFAULT_IDLE_REAP_INTERVAL_SECONDS = 60
const DEFAULT_DEPLOY_MODE: DeployMode = 'local'
const DEFAULT_K8S_NAMESPACE = 'dsh'
const DEFAULT_K8S_SERVICE_ACCOUNT = 'dsh-orchestrator'
const DEFAULT_IMAGE_PULL_SECRET = 'dsh-acr-pull'
/**
 * 覆盖网络 P0-2：**内置种子**（引导链的常量位）。
 * 锚在已持证书的门户域名上（**不新增域名**）；第二地域**留位不填**。
 * ⚠️ 目录端点路径由 `net/relay/directory.ts` 的 `DIRECTORY_PATH` 决定（同源约定）。
 */
const DEFAULT_OVERLAY_BOOTSTRAP_SEEDS = ['https://alotbuy.com/dshs-relay']

/** Load the encryption secret from env, or persist a generated one at
 * `<dataRoot>/secret.key` (0600) so it survives restarts without setup. */
function resolveEncryptionSecret(dataRoot: string): string {
  const fromEnv = process.env.DSHS_SECRET
  if (fromEnv !== undefined && fromEnv !== '') return fromEnv
  const path = join(dataRoot, 'secret.key')
  try {
    const existing = readFileSync(path, 'utf8').trim()
    if (existing !== '') return existing
  } catch {
    // fall through to generate
  }
  const secret = randomBytes(32).toString('hex')
  mkdirSync(dataRoot, { recursive: true })
  writeFileSync(path, secret, { mode: 0o600 })
  return secret
}

function toBool(value: string | undefined, fallback: boolean): boolean {
  if (value === undefined) return fallback
  return value === 'true' || value === '1'
}

/**
 * 解析端口号（覆盖网络 S3）。空 / 非法 / 越界 ⇒ 回落到 `fallback`（`0` = 旧行为 `listen(0)`）。
 * 不接受 NaN：`listen(NaN)` 会以"启动正常但实例起不来"的形式烂在运行时。
 */
function toPortNumber(value: string | number | undefined, fallback: number): number {
  if (value === undefined || value === '') return fallback
  const n = Number(value)
  return Number.isInteger(n) && n >= 0 && n <= 65535 ? n : fallback
}

/** Split a comma-separated CIDR list into a trimmed, de-duplicated array. */
function parseCidrs(value: string | undefined): string[] {
  if (value === undefined || value === '') return []
  return [...new Set(value.split(',').map((c) => c.trim()).filter((c) => c !== ''))]
}

/**
 * 逗号分隔列表解析。与 {@link parseCidrs} 的区别：**没配**（`undefined`）⇒ 返回
 * `undefined`，让调用方把"没配"与"配成空列表"区分开（前者走默认值、后者是显式关闭）。
 */
function splitList(value: string | undefined): string[] | undefined {
  if (value === undefined) return undefined
  return [...new Set(value.split(',').map((s) => s.trim()).filter((s) => s !== ''))]
}

/** Parse an isolation-mode value, rejecting anything outside `soft`/`account`
 * so a typo in the env var fails loudly at startup instead of silently
 * falling back to `soft` isolation. */
function toIsolationMode(value: string | undefined): IsolationMode | undefined {
  if (value === undefined) return undefined
  const normalized = value.trim().toLowerCase()
  if (normalized === 'soft' || normalized === 'account') return normalized
  throw new Error(`invalid isolation mode "${value}" (expected "soft" or "account")`)
}

/** Parse a deploy-mode value, rejecting anything outside `local`/`k8s`. */
function toDeployMode(value: string | undefined): DeployMode | undefined {
  if (value === undefined) return undefined
  const normalized = value.trim().toLowerCase()
  if (normalized === 'local' || normalized === 'k8s' || normalized === 'cluster') return normalized
  throw new Error(`invalid deploy mode "${value}" (expected "local", "k8s" or "cluster")`)
}

/**
 * Fold argv/env overrides over defaults. `dataRoot` defaults to
 * `~/.dshs` (always writable for dev); production sets
 * `DSHS_DATA_ROOT=/var/lib/dshs`.
 */
export function resolveConfig(overrides: ConfigOverrides = {}): ServerConfig {
  const dataRoot =
    overrides.dataRoot ?? process.env.DSHS_DATA_ROOT ?? join(homedir(), '.dshs')
  const port = overrides.port ?? process.env.DSHS_PORT ?? DEFAULT_PORT
  const dshBin = process.env.DSHS_DSH_BIN
  const isolationMode =
    toIsolationMode(overrides.isolationMode) ??
    toIsolationMode(process.env.DSHS_ISOLATION_MODE) ??
    DEFAULT_ISOLATION_MODE
  const deployMode =
    toDeployMode(overrides.deployMode) ??
    toDeployMode(process.env.DSHS_DEPLOY_MODE) ??
    DEFAULT_DEPLOY_MODE
  return {
    host: overrides.host ?? DEFAULT_HOST,
    port: typeof port === 'number' ? port : Number(port),
    dbPath: overrides.dbPath ?? join(dataRoot, 'dshs.db'),
    dbUrl: overrides.dbUrl ?? process.env.DSHS_DB_URL,
    dataRoot,
    bundledSkillDir:
      overrides.bundledSkillDir ??
      process.env.DSHS_BUNDLED_SKILL_DIR ??
      join(dataRoot, 'bundled-skills'),
    dshCommand: overrides.dshCommand ?? (dshBin !== undefined ? [dshBin] : DEFAULT_DSH_COMMAND),
    logLevel: overrides.logLevel ?? DEFAULT_LOG_LEVEL,
    secureCookies:
      overrides.secureCookies ?? toBool(process.env.DSHS_SECURE_COOKIES, false),
    sessionTtlSeconds: Number(
      overrides.sessionTtlSeconds ?? process.env.DSHS_SESSION_TTL ?? DEFAULT_SESSION_TTL_SECONDS,
    ),
    maxUploadBytes: Number(
      overrides.maxUploadBytes ?? process.env.DSHS_MAX_UPLOAD ?? DEFAULT_MAX_UPLOAD_BYTES,
    ),
    restartBackoffMs: Number(
      overrides.restartBackoffMs ?? process.env.DSHS_RESTART_BACKOFF ?? DEFAULT_RESTART_BACKOFF_MS,
    ),
    restartBackoffMaxMs: Number(
      overrides.restartBackoffMaxMs ??
        process.env.DSHS_RESTART_BACKOFF_MAX ??
        DEFAULT_RESTART_BACKOFF_MAX_MS,
    ),
    crashMaxRestarts: Number(
      overrides.crashMaxRestarts ??
        process.env.DSHS_CRASH_MAX_RESTARTS ??
        DEFAULT_CRASH_MAX_RESTARTS,
    ),
    crashWindowMs: Number(
      overrides.crashWindowMs ?? process.env.DSHS_CRASH_WINDOW ?? DEFAULT_CRASH_WINDOW_MS,
    ),
    crashStableMs: Number(
      overrides.crashStableMs ?? process.env.DSHS_CRASH_STABLE ?? DEFAULT_CRASH_STABLE_MS,
    ),
    crashBreakerCooldownMs: Number(
      overrides.crashBreakerCooldownMs ??
        process.env.DSHS_CRASH_BREAKER_COOLDOWN ??
        DEFAULT_CRASH_BREAKER_COOLDOWN_MS,
    ),
    crashBreakerMaxCooldownMs: Number(
      overrides.crashBreakerMaxCooldownMs ??
        process.env.DSHS_CRASH_BREAKER_MAX_COOLDOWN ??
        DEFAULT_CRASH_BREAKER_MAX_COOLDOWN_MS,
    ),
    isolationMode,
    spawnAsUserCommand: overrides.spawnAsUserCommand ?? DEFAULT_SPAWN_AS_USER_COMMAND,
    baseUid: Number(overrides.baseUid ?? process.env.DSHS_BASE_UID ?? DEFAULT_BASE_UID),
    baseDomain: overrides.baseDomain ?? process.env.DSHS_BASE_DOMAIN ?? DEFAULT_BASE_DOMAIN,
    cookieDomain: overrides.cookieDomain ?? process.env.DSHS_COOKIE_DOMAIN ?? DEFAULT_COOKIE_DOMAIN,
    enablePatch: overrides.enablePatch ?? toBool(process.env.DSHS_ENABLE_PATCH, DEFAULT_ENABLE_PATCH),
    portGuard: overrides.portGuard ?? toBool(process.env.DSHS_PORT_GUARD, false),
    maxIdleInstances: Number(
      overrides.maxIdleInstances ?? process.env.DSHS_MAX_IDLE_INSTANCES ?? DEFAULT_MAX_IDLE_INSTANCES,
    ),
    instanceIdleTtlSeconds: Number(
      overrides.instanceIdleTtlSeconds ??
        process.env.DSHS_INSTANCE_IDLE_TTL ??
        DEFAULT_INSTANCE_IDLE_TTL_SECONDS,
    ),
    idleReapIntervalSeconds: Number(
      overrides.idleReapIntervalSeconds ??
        process.env.DSHS_IDLE_REAP_INTERVAL ??
        DEFAULT_IDLE_REAP_INTERVAL_SECONDS,
    ),
    encryptionSecret:
      overrides.encryptionSecret ?? resolveEncryptionSecret(dataRoot),
    deployMode,
    k8sNamespace: overrides.k8sNamespace ?? process.env.DSHS_NAMESPACE ?? DEFAULT_K8S_NAMESPACE,
    dshImage: overrides.dshImage ?? process.env.DSHS_DSH_IMAGE ?? '',
    controlPlaneImage:
      overrides.controlPlaneImage ?? process.env.DSHS_CONTROL_PLANE_IMAGE ?? '',
    imagePullSecret:
      overrides.imagePullSecret ?? process.env.DSHS_IMAGE_PULL_SECRET ?? DEFAULT_IMAGE_PULL_SECRET,
    egressCidrs: overrides.egressCidrs ?? parseCidrs(process.env.DSHS_EGRESS_CIDRS),
    k8sServiceAccount:
      overrides.k8sServiceAccount ?? process.env.DSHS_K8S_SERVICE_ACCOUNT ?? DEFAULT_K8S_SERVICE_ACCOUNT,
    podName: overrides.podName ?? process.env.POD_NAME ?? hostname(),
    clusterHostId: overrides.clusterHostId ?? process.env.DSHS_CLUSTER_HOST_ID ?? hostname(),
    clusterAgentUrl: overrides.clusterAgentUrl ?? process.env.DSHS_CLUSTER_AGENT_URL ?? '',
    clusterAgentToken: overrides.clusterAgentToken ?? process.env.DSHS_CLUSTER_AGENT_TOKEN ?? '',
    clusterInstanceHost: overrides.clusterInstanceHost ?? process.env.DSHS_CLUSTER_INSTANCE_HOST ?? '127.0.0.1',
    clusterWorkerDataRoot: overrides.clusterWorkerDataRoot ?? process.env.DSHS_CLUSTER_WORKER_DATA_ROOT ?? '',
    // 覆盖网络 S1：会合地址出 env。新变量 `DSHS_RENDEZVOUS_URL` 优先，旧变量 `DSHS_TUNNEL_TARGET`
    // 兜底（两台机器可分先后改；删掉新 env 即回滚到旧路径，**不需要回滚代码**）。
    clusterRendezvousUrl:
      overrides.clusterRendezvousUrl ??
      process.env.DSHS_RENDEZVOUS_URL ??
      process.env.DSHS_TUNNEL_TARGET ??
      '',
    // 覆盖网络 R3：Manager 侧的 relay 接入（**空 = 完全不启用**，与 R2 之前行为一致）。
    relayUrl: overrides.relayUrl ?? process.env.DSHS_RELAY_URL ?? '',
    relayStatusUrl: overrides.relayStatusUrl ?? process.env.DSHS_RELAY_STATUS_URL ?? '',
    // 覆盖网络 R5：Manager 侧拨号通道（**空密钥 = 完全不启用**，落回 `/status` 快照那条老路）。
    relayDialHost: (overrides.relayDialHost ?? process.env.DSHS_RELAY_DIAL_HOST ?? 'manager').trim(),
    relayDialSecret: (overrides.relayDialSecret ?? process.env.DSHS_RELAY_DIAL_SECRET ?? '').trim(),
    relayDialPortBase: toPortNumber(overrides.relayDialPortBase ?? process.env.DSHS_RELAY_DIAL_PORT_BASE, 25000),
    relayDialPortSpan: toPortNumber(overrides.relayDialPortSpan ?? process.env.DSHS_RELAY_DIAL_PORT_SPAN, 1000),
    relayDialPool: Number(overrides.relayDialPool ?? process.env.DSHS_RELAY_DIAL_POOL ?? 64) || 64,
    // 覆盖网络 S3：实例端口区间隔离（`0` = 旧行为）。非法值**回落**而不是变 NaN ——
    // `listen(NaN)` 是那种"启动看起来正常、实例起不来"的坑。
    instancePortBase: toPortNumber(
      overrides.instancePortBase ?? process.env.DSHS_INSTANCE_PORT_BASE,
      DEFAULT_INSTANCE_PORT_BASE,
    ),
    instancePortSpan: toPortNumber(
      overrides.instancePortSpan ?? process.env.DSHS_INSTANCE_PORT_SPAN,
      DEFAULT_INSTANCE_PORT_SPAN,
    ),
    // 覆盖网络 P0-2：引导三级链（env 显式 > 缓存目录 > 内置种子）。
    // 这一组**全部有安全默认**：不配任何东西 ⇒ 与今天行为一致（只认 env；种子地址就是现网地址）。
    overlayNetworkId: (overrides.overlayNetworkId ?? process.env.DSHS_OVERLAY_NETWORK_ID ?? 'ops').trim() || 'ops',
    overlayBootstrapSeeds:
      overrides.overlayBootstrapSeeds ??
      splitList(process.env.DSHS_OVERLAY_BOOTSTRAP_SEEDS) ??
      DEFAULT_OVERLAY_BOOTSTRAP_SEEDS,
    overlayDirTrustedKeys:
      overrides.overlayDirTrustedKeys ?? splitList(process.env.DSHS_OVERLAY_DIR_PUBKEYS) ?? [],
    overlayDirKeyFile: (overrides.overlayDirKeyFile ?? process.env.DSHS_OVERLAY_DIR_KEY ?? '').trim(),
    overlayDirectoryCacheFile: (
      overrides.overlayDirectoryCacheFile ??
      process.env.DSHS_OVERLAY_DIR_CACHE ??
      join(dataRoot, 'overlay', 'directory.json')
    ).trim(),
    // 覆盖网络 序③：本机节点身份（一机一钥 + 入网凭据）。
    // **两个都配了**才发起身份 ⇒ 不配 = 与今天行为一致（只做 HMAC）；配了却读不出来 ⇒ 起动即抛
    //（见 `net/relay/identity.ts#loadClientIdentity` —— 静默退化成"没身份"会让"凭据坏了"
    //  表现成"一切正常"，等 relay 一开强制就整台失联）。
    overlayNodeKeyFile: (overrides.overlayNodeKeyFile ?? process.env.DSHS_OVERLAY_NODE_KEY_FILE ?? '').trim(),
    overlayNodeGrantFile: (overrides.overlayNodeGrantFile ?? process.env.DSHS_OVERLAY_NODE_GRANT_FILE ?? '').trim(),
  }
}