NATLAN Docs

外观

主动拨测与日志查看 ​

两条从控制面发起、不需要登节点的过境通道。链路同构：控制面经 WS 门铃把作业下发给 agent，agent 执行并经临时 WS 通道逐块回传，浏览器或终端经 SSE 实时看到输出。输出不落库——作业与缓冲都在控制面内存里，完成后 TTL 回收。

接口契约见 控制台 BFF。

主动拨测（ping / mtr / traceroute） ​

agent 在 debug-shell 容器内以 docker exec 流式执行命令。debug-shell 共享 router netns，因此拨测反映的是节点真实的 DN42 路由视角。

bash
# 1) 发起拨测（202 返回 probe_id）
curl -s -X POST "https://api.natlan.io/control/v1/ui/probes" \
  -H "Authorization: Bearer <admin token>" \
  -H "Content-Type: application/json" \
  -d '{"node_id": "edge1", "spec": {"tool": "mtr", "target": "172.20.0.53", "count": 10, "resolve": true}}'

# 2) SSE 实时读输出（先补发已产生的缓冲，再实时推送，done 事件收尾）
curl -sN -H "Authorization: Bearer <admin token>" \
  "https://api.natlan.io/control/v1/ui/probes/<probe_id>/stream"

要点 ​

  • spec.tool 取 ping / mtr / traceroute / mtu；count 有界（1–30）；resolve 控制逐跳反向 DNS。
  • mtu 是 DF ping 二分扫描：在 [1000, max_size − 族开销] 内二分找最大可通 payload，末行输出 PMTU_PAYLOAD <n>，0 表示连最小尺寸都不通。排 MTU 黑洞时直接用它，不必手动试 ping -M do。
  • link-local 目标（fe80::…）须用 spec.interface 指定 scope 接口，否则内核不知道从哪个接口发。
  • 目标白名单双端校验：target 只接受 DN42、私网或 link-local 的 IP 字面量（口径的单一事实源是 dn42_common.validate_probe_target）。这杜绝了把节点当作探测任意公网主机的跳板。控制面解析请求体时校验一次（非法 422），agent 收到事件后再 model_validate 校验一次——纵深防御，不信任门铃里的内容。
  • 逐跳反解走 debug-shell 内只读 resolv.conf 指向的 DN42 递归解析器。节点自身只跑权威 DNS，所以不能指向本机。
  • 节点无在线 agent 返回 409；并发超上限（全局 256 / 单节点 3）返回 429。

Web 界面在节点详情的「互联」组里有对应的拨测页。

Agent 日志查看 ​

与拨测复用同一套作业机与门铃通道。日志只在查看时经控制面中转，不落库。

bash
# 一次性拉取最近 200 行 WARNING 及以上
curl -s -X POST "https://api.natlan.io/control/v1/ui/logs" \
  -H "Authorization: Bearer <admin token>" \
  -H "Content-Type: application/json" \
  -d '{"node_id": "edge1", "spec": {"mode": "snapshot", "source": "buffer", "lines": 200, "min_level": "WARNING"}}'

curl -sN -H "Authorization: Bearer <admin token>" \
  "https://api.natlan.io/control/v1/ui/logs/<log_id>/stream"

两个来源 ​

source内容支持 tail
bufferagent 进程内 ring buffer，结构化，含级别与模块是
journaljournald 历史，覆盖 agent 重启之前否

排查「agent 起不来」或「重启前发生了什么」用 journal；跟踪当下行为用 buffer 的 tail 模式（时长受 duration_seconds 10–600 约束）。

入口信号 ​

运行时快照的 self_metrics 捎带 log_warning_count、log_error_count、last_error_at、last_error_message（ring buffer 最近 1h 口径）。节点页据此决定要不要引导进日志查看——不用先猜哪台机器有问题。

为什么这不是远程执行接口 ​

两个作业都携带业务数据（spec），是仅有的两个例外。它们仍不构成任意命令执行：

  • ProbeSpec.tool 是三选一的枚举，target 过 IP 白名单，count 有界。
  • LogSpec 只能读日志，来源二选一。
  • agent 侧对收到的 spec 独立校验一遍，不信任控制面下发的内容。

控制模型的完整论述见 安全模型。