外观
Node Agent 配置
配置类：apps/node-agent/agent/core/config.py（AgentConfig / load_agent_config()），CLI 解析在 agent/main.py。CLI 全参数与退出码见 CLI 与脚本。
三来源与优先级
CLI 参数 > 环境变量 (DN42_AGENT_*) > TOML 文件 > 内置默认值加载流程：
load_agent_config(toml_path)先取AgentConfig()默认，TOML 文件存在则_apply_toml覆盖，再_apply_env用环境变量覆盖，最后_validate_choices校验枚举。- CLI 层
_config_from_args在上一步结果之上叠加命令行覆盖。
约定：
- TOML 文件不存在不报错，相当于跳过该来源。路径由
--config指定，约定默认/etc/dn42-control/agent.toml。 - TOML 顶层可用
[agent]表，也可直接平铺。 - TOML 只识别白名单字段，出现未知键抛
ConfigError——避免静默拼写错误。 - 各层的覆盖只应用非
None的项，所以低优先级来源不会被高优先级来源的「未提供」清空。
CLI 只暴露身份与模式类参数（--controller-url / --enrollment-token / --state-dir / --mode / 诊断三选一等）。下表 http_timeout_seconds 及其后的全部调优项——间隔、阈值、socket 路径——只能通过环境变量或 TOML 设置。
身份与模式
| 环境变量 | 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|---|
DN42_AGENT_CONTROLLER_URL | controller_url | str | None | None | Control Server 基础 URL（不带尾斜杠）。常驻模式必需 |
DN42_AGENT_ENROLLMENT_TOKEN | enrollment_token | str | None | None | 一次性 enrollment token |
DN42_AGENT_REQUESTED_NODE_ID | requested_node_id | str | None | None | 希望绑定的 node_id |
DN42_AGENT_HOSTNAME | hostname | str | None | None | 覆盖 inventory 中的 hostname |
DN42_AGENT_STATE_DIR | state_dir | Path | /var/lib/dn42-control | 本地状态目录 |
DN42_AGENT_RENDERED_DIR | rendered_dir | Path | None | None（派生） | 渲染输出目录。留空则从节点目录派生 |
DN42_AGENT_MODE | mode | apply / write-rendered / plan-only | apply | reconcile 深度；非法值抛 ConfigError |
DN42_AGENT_LOG_LEVEL | log_level | str | INFO | 日志级别 |
desired_state_path 只能经 TOML 或 CLI --desired-state 设置（无对应环境变量），用于离线运行；与 controller_url 互斥。
网络与收敛
| 环境变量 | 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|---|
DN42_AGENT_HTTP_TIMEOUT_SECONDS | http_timeout_seconds | float | 30.0 | 控制面 HTTP 读超时。大节点的上报端点在服务端处理加跨境路径延迟下可能逼近 10s，超时过短会造成对账假失败 |
DN42_AGENT_LOCAL_CONVERGENCE | local_convergence | bool | True | 是否执行本机收敛（birdc configure、按接口同步 WireGuard） |
旁路任务周期
每一项都独立于 reconcile 闭环，设 0 即关闭该任务。
| 环境变量 | 字段 | 默认（秒） | 任务 |
|---|---|---|---|
DN42_AGENT_ROUTING_INTERVAL_SECONDS | routing_interval_seconds | 300.0 | 路由全表周期采集（直连 BIRD 控制 socket 的纯观测） |
DN42_AGENT_TRAFFIC_INTERVAL_SECONDS | traffic_interval_seconds | 30.0 | WG 流量轻量采集：一次 wg show all transfer 求和上报，供控制面画比完整快照更细粒度的吞吐曲线 |
DN42_AGENT_RERESOLVE_INTERVAL_SECONDS | reresolve_interval_seconds | 45.0 | WG endpoint 周期重解析：对端走动态 DNS、IP 变更后内核仍钉死旧 IP，本任务据握手超时用域名重设 endpoint |
DN42_AGENT_L3_HEAL_INTERVAL_SECONDS | l3_heal_interval_seconds | 60.0 | L3 漂移自愈：比对期望接口（WG + dummy）与 netns 实际接口，缺失即重跑补齐。容器 Up 但接口被删的运行时漂移，config_hash 看不见 |
DN42_AGENT_SELF_MONITOR_INTERVAL_SECONDS | self_monitor_interval_seconds | 60.0 | 进程自观测：采集自身 CPU% 与 RSS 写 metrics 文件 |
DN42_AGENT_HEARTBEAT_INTERVAL_SECONDS | heartbeat_interval_seconds | 30.0 | WS 心跳：报活 + 报版本 + 报 apply 态，并写本地健康文件供自更新器的健康门轮询。设 0 同时关闭心跳与自更新 |
DN42_AGENT_FLAPFEED_INTERVAL_SECONDS | flapfeed_interval_seconds | 60.0 | 前缀级 flap 打分上报 tick。进程内 BGP 采集会话持续收 UPDATE，按此间隔上报衰减计分快照 |
任务清单与实现见 Node Agent 内部。
阈值与路径
| 环境变量 | 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|---|
DN42_AGENT_CPU_WARN_PERCENT | cpu_warn_percent | float | 80.0 | 自身 CPU% 告警阈值：单次自观测窗口占用 ≥ 此值即 WARN（多核可 >100）。80% 足以揪出「烧满一个核」的背景循环热点，又不会被正常突发刷屏 |
DN42_AGENT_BIRD_SOCKET_PATH | bird_socket_path | str | None | None（派生） | BIRD 控制 socket 路径的显式覆盖。留空则从渲染目录推导 <rendered_dir>/run/bird/bird.ctl，与 bird 容器的可写挂载落点一致。仅非常规部署或联调需要指向别处时设置 |
DN42_AGENT_EXABGP_BIN | exabgp_bin | str | None | None | 已废弃。取值不再被读取；字段保留只为容忍存量配置里的残留键——配置加载对未知键报错，删掉字段会让带旧键的节点起不来 |
状态目录布局
由 AgentPaths（agent/core/paths.py）定义，所有节点级文件落在 <state_dir>/nodes/<node_id>/ 之下：
| 路径 | 内容 |
|---|---|
identity.json | 持久化的 agent 身份与世代信息 |
desired-state.json | 最近一次成功获取的 DesiredState 本地副本 |
rendered/ | 渲染输出（配置文件与镜像构建上下文根；rendered_dir 留空时即此处） |
snapshots/ | RuntimeSnapshot 与 ReconciliationReport 历史归档 |
metrics.json | reconcile 运行指标（次数 / 失败 / 时长 / 最近状态） |
containers/ | 已应用的容器定义记录（字段级 diff reason 的数据源） |
secrets/ | 遗留目录（0700，启动时创建）。节点密钥已收归控制面，当前无任何内容写入 |
配置示例
TOML
toml
# /etc/dn42-control/agent.toml
[agent]
controller_url = "https://api.example.dn42"
enrollment_token = "change-me"
requested_node_id = "edge1"
state_dir = "/var/lib/dn42-control"
log_level = "INFO"
# 可选调参（0 关闭对应旁路任务）
# http_timeout_seconds = 30.0
# routing_interval_seconds = 300.0
# reresolve_interval_seconds = 45.0
# flapfeed_interval_seconds = 60.0systemd env-file（生产推荐）
模板单元 deploy/tools/systemd/dn42-node-agent@.service 用 %i 作为 node_id，并读取 /etc/dn42-control/%i.env：
dotenv
# /etc/dn42-control/edge1.env
DN42_AGENT_CONTROLLER_URL=https://api.example.dn42
DN42_AGENT_ENROLLMENT_TOKEN=change-me
# STATE_DIR 与 REQUESTED_NODE_ID 已由 unit 注入（=/var/lib/dn42-control、=%i）启用：sudo systemctl enable --now dn42-node-agent@edge1。
完整部署步骤见 节点 Agent 部署，内部机制见 Node Agent 内部。