NATLAN Docs

外观

Control Server —— 公开 API 与健康探针 ​

源码：apps/control-server/app/api/v1/public.py（公开只读）、app/api/v1/health.py 与 app/main.py（探针）。

公开端点无鉴权，是 natlan.io 首页的数据源。CORS 由控制面白名单放行（生产已含 https://natlan.io）。

端点一览 ​

方法路径缓存说明
GET/control/v1/public/mappublic, max-age=300公开世界地图数据：城市点 + 城市间链路 + fleet 三数字
GET/control/v1/public/fleetpublic, max-age=60公开只读 fleet 总览，与控制台 GET /ui/fleet/overview 同形状同实现
GET/healthz无存活 + DB 连通性探针
GET/control/v1/healthz无轻量存活探针

GET /public/map ​

一个接口喂首页两个区块：nodes / links 渲染世界地图，stats 供数据条的三个数字。

json
{
  "asn": 4242420028,
  "updated_at": "2026-08-10T12:28:26.596811+00:00",
  "stats": { "nodes_online": 10, "bgp_sessions": 127, "routes": 2491 },
  "nodes": [
    {
      "label": "hkg",
      "lat": 22.3,
      "lon": 114.2,
      "city": "Hong Kong",
      "country": "HK",
      "region": 52,
      "online": true,
      "sessions": 32
    }
  ],
  "links": [["can", "hkg"], ["hkg", "tyo"]]
}
字段语义
asn本网 ASN，取自节点 spec 的 node.asn；无节点时 null
updated_at响应生成时刻（ISO 8601）；命中缓存时为缓存生成时刻
stats.nodes_online在线物理节点数。health 为 ok 或 degraded 都算在线，stale / down 不算
stats.bgp_sessions全 fleet established BGP 会话数（内 iBGP + 外 eBGP）
stats.routes各节点路由表规模的中位数（iBGP 收敛后趋同，代表网络表规模；不是求和）
nodes[]地图城市点，按 label 升序
nodes[].labelIATA 城市码（节点 site）
nodes[].lat / lon城市级坐标，四舍五入到 1 位小数
nodes[].city / country / region城市名、ISO 国家码、DN42 region 编号（geo 表静态数据）
nodes[].online该城市任一节点在线
nodes[].sessions该城市全部节点的 established 会话合计
links[]城市对 [a, b]，a < b 字典序，整体排序稳定；由节点级 IGP 邻接折叠去重

隐私裁剪（不变量） ​

同城多节点折叠为一个地图点，城内互联的自环边剔除——node_id、IP、endpoint、agent 版本、健康细节一概不出网，节点编号天然不可见。坐标 1 位小数约 11 km 粒度，只到城市级。

前端接法 ​

js
const r = await fetch('https://api.natlan.io/control/v1/public/map');
const { stats, nodes, links } = await r.json();
// nodes → 地图打点（label 即城市码，online 控制点态）
// links → 以 label 查 nodes 坐标连弧线
// stats → 数据条三个数字

轮询无意义（5 分钟缓存），页面加载取一次即可。

GET /public/fleet ​

与控制台 GET /ui/fleet/overview 同一形状、同一实现（直接复用 build_fleet_overview），首页因此能原封不动挂载控制台的 FleetMap 组件。

公开口径较 /map 放宽：节点级只读运维元数据出网——node_id、health、generation 与 drift、agent 版本、心跳时间、能力列表、站点 / 区域 / 地理解析、WG 邻接（接口名与 cost）。形状里没有 IP、endpoint、密钥，也没有任何可写面。

健康探针 ​

端点行为
GET /healthz执行一次 SELECT 1。DB 不可达返回 503 {"status": "unavailable", "database": "down"}，正常返回 {"status": "ok", "database": "up"}。供负载均衡与容器健康检查使用——DB 挂了就该报不健康，而不是仍报 ok
GET /control/v1/healthz轻量存活探针，恒返回 {"status": "ok"}

auth-server 与 registry-server 各自也有根上的 GET /healthz。