完整 API 参考手册 (Full API Reference)

本文档是后端所有 REST + WebSocket 端点的完整技术参考。

Base URL

http://localhost:8000

所有端点均以 JSON 交互（除文件下载外），请求 Content-Type 为 application/json。

1. 健康与系统 (System)

1.1 GET /health

说明：全局健康检查，包含 API 状态、数据库连通性、适配器连通性、节点深度探测。

路由文件：src/unet_dt/api/routes/health.py

请求参数：无

Response 200 — HealthResponse：

字段	类型	说明
`status`	`string`	全局状态：`healthy` / `degraded` / `unhealthy`
`checks`	`object`	`{ api: {ok: bool}, database: {ok: bool, detail: str?} }`
`healthy_nodes`	`int`	探测成功的节点数
`total_nodes`	`int`	配置的总节点数
`db`	`DbHealth`	数据库健康详情
`db.ok`	`bool`	数据库连接是否正常
`db.tables`	`object`	各表是否存在 `{dt_runs: bool, dt_run_summary: bool, dt_run_events: bool}`
`db.detail`	`string?`	错误详情
`adapter`	`AdapterHealth`	适配器健康详情
`adapter.ok`	`bool`	适配器/网关是否可达
`adapter.backend`	`string`	适配器后端类型：`fjagepy` / `arlpy` / `logonly`
`adapter.detail`	`string?`	错误详情
`adapter.unet_host`	`string`	UNet 网关主机
`adapter.unet_port`	`int`	UNet 网关端口
`adapter.node_endpoints`	`NodeEndpointHealth[]`	各节点的 TCP 可达性
`nodes`	`HealthNodeCheck[]`	各节点的深度探测结果

NodeEndpointHealth:

字段	类型	说明
`node`	`string`	节点名 (A-G)
`endpoint`	`string`	TCP 端点地址
`reachable`	`bool`	TCP 是否可达
`detail`	`string?`	错误详情

HealthNodeCheck:

字段	类型	说明
`node_id`	`int`	节点数值 ID
`name`	`string`	节点名称
`ok`	`bool`	网关连接是否成功
`phy_ok`	`bool`	物理层是否可用
`agents`	`int`	运行中的 Agent 数量
`services`	`string[]`	可用服务列表
`unet_addr`	`int?`	动态分配的 UNet 地址
`detail`	`string?`	详情/错误信息

1.2 GET /health/nodes

说明：仅返回节点层面的深度检查结果。

路由文件：src/unet_dt/api/routes/health.py

Response 200 — NodeHealthResponse：

字段	类型	说明
`status`	`string`	`healthy` / `degraded` / `unhealthy`
`nodes`	`HealthNodeCheck[]`	同上
`healthy_count`	`int`	健康节点数
`total_count`	`int`	总节点数

1.3 GET /config

说明：返回当前运行时配置（敏感信息已脱敏）。

路由文件：src/unet_dt/api/routes/config.py

Response 200 — ConfigResponse：

字段	类型	说明
`unet_host`	`string`	UNet 主机
`unet_port`	`int`	UNet 端口
`node_endpoints`	`ConfigNodeEndpoint[]`	节点端点列表
`location_init`	`LocationInitConfig?`	位置初始化配置
`db_url_masked`	`string`	脱敏后的数据库连接串
`adapter_backend`	`string`	适配器后端类型

ConfigNodeEndpoint: { node: string, endpoint: string }

LocationInitConfig: { enabled: bool, mode: string, script_path: string, timeout_seconds: float }

1.4 POST /config/location-init/run

说明：手动触发位置初始化脚本执行。

路由文件：src/unet_dt/api/routes/config.py

Response 200 — LocationInitRunResponse：

字段	类型	说明
`enabled`	`bool`	位置初始化是否启用
`ok`	`bool`	执行是否成功
`skipped`	`bool`	是否跳过（未启用时）
`mode`	`string`	运行模式
`command`	`string[]`	实际执行的命令
`return_code`	`int?`	进程返回码
`stdout`	`string`	标准输出
`stderr`	`string`	标准错误
`duration_ms`	`float`	执行耗时 (ms)
`warning`	`string?`	警告信息

2. 策略 (Strategies)

2.1 GET /strategies

说明：列出所有已注册的调度策略。

路由文件：src/unet_dt/api/routes/strategies.py

Response 200 — StrategyListResponse：

字段	类型	说明
`items`	`StrategyItem[]`	策略列表
`total`	`int`	策略总数

StrategyItem: { id: string, name: string }

3. 场景管理 (Scenarios)

3.1 GET /scenarios

说明：合并 YAML 文件 + 数据库两种来源的场景列表。

路由文件：src/unet_dt/api/routes/scenarios.py

Response 200 — ScenarioMergedListResponse：

字段	类型	说明
`items`	`ScenarioDbItem[]`	场景列表
`total`	`int`	场景总数

ScenarioDbItem:

字段	类型	说明
`id`	`string`	场景 ID
`name`	`string`	场景名称
`source`	`string`	来源：`db` / `yaml`
`created_at`	`datetime?`	创建时间（YAML 来源为 null）
`updated_at`	`datetime?`	更新时间（YAML 来源为 null）

3.2 GET /scenarios/

说明：获取场景完整信息（含节点、流量、运行参数）。

路径参数：scenario_id — 场景 ID

Response 200 — ScenarioFullResponse：

字段	类型	说明
`id`	`string`	场景 ID
`name`	`string`	场景名称
`nodes`	`ScenarioNodeItem[]`	节点列表
`traffic`	`ScenarioTrafficItem[]`	流量配置
`run`	`ScenarioRunConfig`	运行参数
`unet`	`object?`	UNet 配置覆盖
`source`	`string`	来源
`created_at`	`datetime?`	创建时间
`updated_at`	`datetime?`	更新时间

ScenarioNodeItem: { id: int, name: string?, position: [float, float]?, tcp: string? }

ScenarioTrafficItem: { flow_id: string, src: int, dst: int, period_ms: float, payload_bytes: int }

ScenarioRunConfig: { seed: int, dt_seconds: float, steps: int, output_dir: string }

Response 404: 场景不存在

3.3 POST /scenarios

说明：创建新场景（保存到数据库）。

Request Body — ScenarioCreateRequest：

字段	类型	必填	说明
`id`	`string`	是	场景 ID（唯一）
`name`	`string`	是	场景名称
`nodes`	`ScenarioNodeItem[]`	是	节点列表
`traffic`	`ScenarioTrafficItem[]`	是	流量配置
`run`	`ScenarioRunConfig`	是	运行参数

Response 201 — ScenarioFullResponse

Response 409: 场景 ID 已存在

3.4 PUT /scenarios/

说明：更新已有场景。

Request Body — ScenarioUpdateRequest：字段同 Create，但均为可选。

Response 200 — ScenarioFullResponse

Response 404: 场景不存在

3.5 DELETE /scenarios/

说明：删除数据库中的场景（YAML 场景不可删除）。

Response 204: 删除成功

Response 404: 场景不存在

3.6 POST /scenarios/import

说明：从本地 YAML 文件导入场景到数据库。

Request Body：{ "yaml_path": "string" }

Response 201 — ScenarioFullResponse

3.7 POST /scenarios/{scenario_id}/export

说明：将数据库场景导出为 YAML 文件。

Response 200：{ "scenario_id": "string", "output_path": "string" }

4. 运行管理 (Runs)

4.1 POST /runs

说明：创建新的仿真运行实例（状态为 created，尚未开始执行）。

路由文件：src/unet_dt/api/routes/runs.py

Request Body — RunCreateRequest：

字段	类型	必填	默认值	说明
`scenario_id`	`string`	是	—	场景 ID
`strategy_id`	`string`	否	`round_robin`	策略 ID
`mode`	`string`	否	`mock`	运行模式：`mock` / `gateway`
`steps`	`int`	否	`100`	仿真步数
`dt_seconds`	`float`	否	`1.0`	时间步长(秒)
`seed`	`int`	否	`42`	随机种子
`run_id`	`string?`	否	自动生成 UUID	自定义 Run ID

Response 201 — RunItem

4.2 GET /runs

说明：分页查询运行列表。

Query Parameters：

limit (int, 默认 50) — 每页数量
offset (int, 默认 0) — 偏移量

Response 200 — RunListResponse：

字段	类型	说明
`items`	`RunItem[]`	运行列表
`limit`	`int`	请求的 limit
`offset`	`int`	请求的 offset

RunItem:

字段	类型	说明
`id`	`string`	Run ID
`scenario_id`	`string`	场景 ID
`strategy_id`	`string`	策略 ID
`mode`	`string`	运行模式
`status`	`string`	状态：`created` / `running` / `stopping` / `finished` / `stopped` / `failed`
`steps`	`int`	总步数
`current_step`	`int`	当前步数
`dt_seconds`	`float`	时间步长
`seed`	`int`	随机种子
`created_at`	`datetime`	创建时间
`started_at`	`datetime?`	启动时间
`finished_at`	`datetime?`	结束时间
`output_dir`	`string?`	产物输出目录
`error_message`	`string?`	错误信息

4.3 GET /runs/

说明：获取运行详情，包含摘要统计。

Response 200 — RunDetailResponse：

字段	类型	说明
`run`	`RunItem`	运行基本信息
`summary`	`RunSummaryItem?`	摘要统计（可能为 null）

RunSummaryItem:

字段	类型	说明
`run_id`	`string`	Run ID
`avg_throughput_bps`	`float?`	平均吞吐量 (bps)
`avg_loss_rate`	`float?`	平均丢包率
`p95_delay_ms`	`float?`	P95 延迟 (ms)
`trace_count`	`int?`	追踪记录总数
`received_count`	`int?`	接收成功数
`updated_at`	`datetime?`	最后更新时间

Response 404: Run 不存在

4.4 GET /runs/{run_id}/status

说明：获取运行实时状态（为前端轮询设计）。

Response 200 — RunStatusResponse：

字段	类型	说明
`run`	`RunItem`	运行基本信息
`summary`	`RunSummaryItem?`	摘要统计
`current_step`	`int`	当前步
`total_steps`	`int`	总步数
`latest_metrics`	`MetricItem?`	最新一步的指标

4.5 POST /runs/{run_id}/start

说明：启动已创建的运行实例。运行必须处于 created 状态。

Response 200 — RunItem（状态变为 running）

Response 404: Run 不存在

Response 409: Run 状态不允许启动

4.6 POST /runs/{run_id}/stop

说明：请求停止正在运行的实例。运行必须处于 running 状态。

Response 200 — RunItem（状态变为 stopping）

Response 404: Run 不存在

Response 409: Run 状态不允许停止

4.7 GET /runs/{run_id}/metrics

说明：获取运行的步进指标数据（从 CSV 产物或数据库读取）。

Response 200 — RunMetricsResponse：

字段	类型	说明
`run_id`	`string`	Run ID
`status`	`string`	运行状态
`artifact_dir`	`string?`	产物目录
`source_file`	`string?`	数据来源文件
`count`	`int`	指标条数
`items`	`MetricItem[]`	指标列表

MetricItem:

字段	类型	说明
`step_id`	`int?`	步序号
`t_window_start_ms`	`float`	窗口起始时间
`t_window_end_ms`	`float`	窗口结束时间
`throughput_bps`	`float`	吞吐量 (bps)
`loss_rate`	`float`	丢包率
`delay_p50_ms`	`float`	P50 延迟
`delay_p95_ms`	`float`	P95 延迟
`sent_count`	`int`	发送数量
`recv_count`	`int`	接收数量
`sync_error_ms`	`float`	同步误差
`overhead_ms`	`float`	计算开销

4.8 GET /runs/{run_id}/traces

说明：分页获取通信追踪记录。

Query Parameters：

limit (int, 默认 200)
offset (int, 默认 0)

Response 200 — RunTracesResponse：

字段	类型	说明
`run_id`	`string`	Run ID
`status`	`string`	运行状态
`artifact_dir`	`string?`	产物目录
`source_file`	`string?`	数据来源文件
`total`	`int`	记录总数
`limit`	`int`	每页数量
`offset`	`int`	偏移
`items`	`TraceItem[]`	追踪记录列表

TraceItem:

字段	类型	说明
`run_id`	`string`	Run ID
`step_id`	`int`	步序号
`seq`	`int`	序列号
`tx_time_ms`	`float`	发送时间
`src`	`int`	源节点
`dst`	`int`	目标节点
`rx_time_ms`	`float?`	接收时间
`payload_bytes`	`int`	载荷大小
`received`	`bool`	是否接收成功
`source`	`string`	数据来源 (`csv` / `db`)

4.9 GET /runs/{run_id}/artifacts

说明：列出运行的产物文件清单。

Response 200 — RunArtifactsResponse：

字段	类型	说明
`run_id`	`string`	Run ID
`artifact_dir`	`string?`	产物目录
`files`	`ArtifactFileItem[]`	文件列表

ArtifactFileItem:

字段	类型	说明
`filename`	`string`	文件名
`exists`	`bool`	文件是否存在
`size_bytes`	`int?`	文件大小
`download_url`	`string?`	下载 URL

4.10 GET /runs/{run_id}/artifacts/

说明：下载指定的产物文件。

路径参数：

filename — 允许的值：traces.csv, metrics.csv, report.md, scenario.yaml, strategy.json, versions.json

Response 200: 文件流（Content-Type 根据文件类型确定）

Response 400: 不允许的文件名

Response 404: 文件不存在

4.11 GET /runs/{run_id}/events

说明：查询运行事件日志。

Query Parameters：

limit (int, 默认 200)
offset (int, 默认 0)

Response 200 — RunEventsResponse：

字段	类型	说明
`run_id`	`string`	Run ID
`items`	`RunEventItem[]`	事件列表
`total`	`int`	事件总数

RunEventItem:

字段	类型	说明
`id`	`int`	事件数据库 ID
`run_id`	`string`	Run ID
`event_type`	`string`	事件类型 (`state_change`, `step`, `metrics`, ...)
`step_id`	`int?`	关联的步序号
`payload`	`object`	事件 JSON 载荷
`created_at`	`datetime`	事件时间

5. WebSocket 实时推送

5.1 WS /ws/runs/

说明：建立 WebSocket 连接以接收运行事件实时推送。

路由文件：src/unet_dt/api/ws.py

连接流程：

客户端连接 ws://host:port/ws/runs/{run_id}
服务器验证 run_id 存在后 accept
自动推送当前 state 和 metrics 快照
后续持续推送运行过程中的事件

关闭码：

4404: run_id 不存在

消息格式 — RunEventEnvelope：

json

{
  "type": "step|schedule|metrics|sync|state|artifacts",
  "run_id": "string",
  "ts_ms": 1700000000123,
  "payload": {}
}

事件类型：

type	触发时机	payload 关键字段
`state`	状态变更	`id, status, scenario_id, strategy_id, mode, steps, dt_seconds, seed, created_at, started_at, finished_at, output_dir, error_message`
`step`	每步完成	`step_id`
`schedule`	调度决策执行	策略决策相关字段
`metrics`	指标更新	`avg_throughput_bps, avg_loss_rate, p95_delay_ms, trace_count, received_count, updated_at`
`sync`	时间同步	同步精度相关字段
`artifacts`	产物生成完毕	文件列表

背压处理：服务端为每个连接维护大小为 128 的异步队列。队列满时采用 drop-oldest 策略丢弃最旧消息。

6. 错误响应格式

所有 4xx/5xx 错误遵循 FastAPI 标准格式：

json

{
  "detail": "error message string"
}

或 Pydantic 验证错误（422）：

json

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "field_name"],
      "msg": "error description",
      "input": "invalid_value"
    }
  ]
}

7. CORS 配置

API 默认启用 CORS，允许所有来源访问：

python

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

生产环境应限制 allow_origins 为实际前端域名。

8. Pydantic Schema 对照表

所有请求/响应模型定义在 src/unet_dt/api/schemas.py，主要模型如下：

模型名	用途
`HealthResponse`	GET /health 响应
`NodeHealthResponse`	GET /health/nodes 响应
`ConfigResponse`	GET /config 响应
`StrategyListResponse`	GET /strategies 响应
`ScenarioMergedListResponse`	GET /scenarios 响应
`ScenarioFullResponse`	GET /scenarios/{id} 响应
`ScenarioCreateRequest`	POST /scenarios 请求
`ScenarioUpdateRequest`	PUT /scenarios/{id} 请求
`RunCreateRequest`	POST /runs 请求
`RunListResponse`	GET /runs 响应
`RunDetailResponse`	GET /runs/{id} 响应
`RunStatusResponse`	GET /runs/{id}/status 响应
`RunMetricsResponse`	GET /runs/{id}/metrics 响应
`RunTracesResponse`	GET /runs/{id}/traces 响应
`RunArtifactsResponse`	GET /runs/{id}/artifacts 响应
`RunEventsResponse`	GET /runs/{id}/events 响应
`LocationInitRunResponse`	POST /config/location-init/run 响应
`RunEventEnvelope`	WebSocket 消息信封

完整 API 参考手册 (Full API Reference) ​

Base URL ​

1. 健康与系统 (System) ​

1.1 GET /health ​

1.2 GET /health/nodes ​

1.3 GET /config ​

1.4 POST /config/location-init/run ​

2. 策略 (Strategies) ​

2.1 GET /strategies ​

3. 场景管理 (Scenarios) ​

3.1 GET /scenarios ​

3.2 GET /scenarios/ ​

3.3 POST /scenarios ​

3.4 PUT /scenarios/ ​

3.5 DELETE /scenarios/ ​

3.6 POST /scenarios/import ​

3.7 POST /scenarios/{scenario_id}/export ​

4. 运行管理 (Runs) ​

4.1 POST /runs ​

4.2 GET /runs ​

4.3 GET /runs/ ​

4.4 GET /runs/{run_id}/status ​

4.5 POST /runs/{run_id}/start ​

4.6 POST /runs/{run_id}/stop ​

4.7 GET /runs/{run_id}/metrics ​

4.8 GET /runs/{run_id}/traces ​

4.9 GET /runs/{run_id}/artifacts ​

4.10 GET /runs/{run_id}/artifacts/ ​

4.11 GET /runs/{run_id}/events ​

5. WebSocket 实时推送 ​

5.1 WS /ws/runs/ ​

6. 错误响应格式 ​

7. CORS 配置 ​

8. Pydantic Schema 对照表 ​

完整 API 参考手册 (Full API Reference)

Base URL

1. 健康与系统 (System)

1.1 GET /health

1.2 GET /health/nodes

1.3 GET /config

1.4 POST /config/location-init/run

2. 策略 (Strategies)

2.1 GET /strategies

3. 场景管理 (Scenarios)

3.1 GET /scenarios

3.2 GET /scenarios/

3.3 POST /scenarios

3.4 PUT /scenarios/

3.5 DELETE /scenarios/

3.6 POST /scenarios/import

3.7 POST /scenarios/{scenario_id}/export

4. 运行管理 (Runs)

4.1 POST /runs

4.2 GET /runs

4.3 GET /runs/

4.4 GET /runs/{run_id}/status

4.5 POST /runs/{run_id}/start

4.6 POST /runs/{run_id}/stop

4.7 GET /runs/{run_id}/metrics

4.8 GET /runs/{run_id}/traces

4.9 GET /runs/{run_id}/artifacts

4.10 GET /runs/{run_id}/artifacts/

4.11 GET /runs/{run_id}/events

5. WebSocket 实时推送

5.1 WS /ws/runs/

6. 错误响应格式

7. CORS 配置

8. Pydantic Schema 对照表