OmniUPF API 文档

概述

OmniUPF API 提供了一个全面的 RESTful 接口，用于管理和监控基于 eBPF 的用户面功能。该 API 使所有 UPF 组件的实时控制和可观察性成为可能。

API 功能

会话管理：

PFCP 会话：查询活动会话，查看会话详情，按 UE IP 或 TEID 过滤
PFCP 关联：监控控制平面节点关联和状态

流量规则：

数据包检测规则 (PDR)：检查上行和下行流量分类器 (IPv4/IPv6)
转发动作规则 (FAR)：查看转发、缓冲和丢弃策略
QoS 强制规则 (QER)：监控速率限制和 QoS 策略
使用报告规则 (URR)：跟踪每个会话的数据量计数器

数据包缓冲：

缓冲状态：查看每个 FAR 的缓冲数据包 (GET /buffer, GET /buffer/:far_id)
缓冲操作：刷新或清除缓冲数据包 (POST /buffer/:far_id/flush, DELETE /buffer/:far_id, DELETE /buffer)
缓冲控制：手动通知触发 (POST /buffer/:far_id/notify)
通知状态：查看 DLDR 通知状态 (GET /buffer/notifications)

监控和统计：

数据包统计：按协议实时数据包计数 (GTP, IP, TCP, UDP, ICMP, ARP)
XDP 统计：数据路径性能指标 (通过、丢弃、重定向、中止)
N3/N6 接口统计：RAN 和数据网络流量分布
路由统计：FIB 查找性能 (缓存命中、查找、错误)

路由管理：

UE 路由：查询 UE IP 到 gNB 的路由表 (GET /routes)
FRR 集成：与 Free Range Routing 守护进程同步路由 (POST /routes/sync)
路由会话：查看路由协议会话 (GET /routing/sessions)
OSPF 数据库：查询 OSPF 外部路由数据库 (GET /ospf/database/external)

配置：

UPF 配置：检索和编辑配置 (GET /config, POST /config)
数据平面配置：查询数据平面特定配置 (GET /dataplane_config)
XDP 能力：查询 XDP 模式支持和接口能力 (GET /xdp_capabilities)
eBPF 映射容量：监控资源利用率和容量 (GET /map_info)

Web UI 集成

OmniUPF Web UI 基于此 API 构建，提供了一个交互式仪表板，涵盖所有 API 功能。请参见 Web UI 指南获取截图和使用示例。

Swagger API 文档

该 API 使用 OpenAPI 3.0 (Swagger) 规范进行了全面文档化。交互式 Swagger UI 提供：

完整��端点文档，包含请求/响应模式
直接从浏览器测试 API 调用的尝试功能
所有数据模型的模式定义
HTTP 状态码和错误响应

Swagger API 文档

交互式 Swagger UI 显示 OmniUPF API 端点及详细文档。

访问 Swagger UI

Swagger 文档可在以下地址访问：

http://<upf-host>:8080/swagger/index.html

例如：http://10.98.0.20:8080/swagger/index.html

API 基础路径

所有 API 端点的前缀为：

/api/v1

## API 特性

### 分页

OmniUPF API 支持对返回大型数据集的端点进行分页。分页可以防止超时，并减少查询数千个会话、PDR 或 URR 时的内存使用。

**支持的分页样式**：

1. **基于页面的分页**（推荐）：
   - `page`：页码（从 1 开始）
   - `page_size`：每页项目数（默认：100，最大：1000）

2. **基于偏移量的分页**：
   - `offset`：要跳过的项目数
   - `limit`：要返回的项目数（最大：1000）

**示例请求**：

```bash
# 基于页面：获取第二页，每页 50 项
GET /api/v1/pfcp_sessions?page=2&page_size=50

# 基于偏移量：跳过前 100 项，返回下 50 项
GET /api/v1/pfcp_sessions?offset=100&limit=50

# 默认行为（无分页参数）：前 100 项
GET /api/v1/pfcp_sessions

响应格式：

&#123;
  "data": [
    &#123; /* session object */ &#125;,
    &#123; /* session object */ &#125;,
    ...
  ],
  "pagination": &#123;
    "total": 5432,
    "page": 2,
    "page_size": 50,
    "total_pages": 109
  &#125;
&#125;

分页端点：

/api/v1/pfcp_sessions - PFCP 会话列表
/api/v1/pfcp_associations - PFCP 关联列表
/api/v1/routes - UE IP 路由
/api/v1/uplink_pdr_map - 上行 PDR（基本信息）
/api/v1/uplink_pdr_map/full - 带有完整 SDF 过滤详细信息的上行 PDR
/api/v1/downlink_pdr_map - 下行 PDR IPv4（基本信息）
/api/v1/downlink_pdr_map/full - 带有完整 SDF 过滤详细信息的下行 PDR IPv4
/api/v1/downlink_pdr_map_ip6 - 下行 PDR IPv6（基本信息）
/api/v1/downlink_pdr_map_ip6/full - 带有完整 SDF 过滤详细信息的下行 PDR IPv6
/api/v1/far_map - 转发动作规则
/api/v1/qer_map - QoS 强制规则
/api/v1/urr_map - 使用报告规则

缓冲管理端点：

GET /api/v1/buffer - 列出所有 FAR 缓冲区及其统计信息
GET /api/v1/buffer/:far_id - 获取特定 FAR 的缓冲状态
GET /api/v1/buffer/notifications - 列出 DLDR 通知状态
DELETE /api/v1/buffer - 清除所有缓冲数据包
DELETE /api/v1/buffer/:far_id - 清除特定 FAR 的缓冲
POST /api/v1/buffer/:far_id/flush - 刷新（重放）缓冲数据包
POST /api/v1/buffer/:far_id/notify - 手动发送 DLDR 通知

配置端点：

GET /api/v1/config - 获取当前 UPF 配置
POST /api/v1/config - 更新 UPF 配置（运行时可编辑字段）
GET /api/v1/dataplane_config - 获取数据平面特定配置

路由集成端点：

GET /api/v1/routes - 列出 UE 路由
POST /api/v1/routes/sync - 触发与 FRR 的路由同步
GET /api/v1/routing/sessions - 获取路由协议会话
GET /api/v1/ospf/database/external - 获取 OSPF 外部 LSA 数据库

最佳实践：

对于 Web UI 显示，使用 page_size=100
对于批量导出，使用 page_size=1000（最大限制）
查询 pagination.total_pages 以确定迭代次数
增加 page_size 以提高 API 性能（请求更少）

CORS 支持

跨源资源共享 (CORS) 默认对所有 API 端点启用，允许 Web UI 和第三方应用程序从不同来源访问 API。

Prometheus 指标

除了 REST API，OmniUPF 还在 /metrics 端点（默认端口 :9090）上公开 Prometheus 指标。

指标提供：

每个对等体的 PFCP 消息计数和延迟
按协议类型的数据包统计
XDP 动作裁决
缓冲统计
eBPF 映射容量利用率
URR 体积跟踪

请参见指标参考获取完整文档。

概述​

API 功能​

Web UI 集成​

Swagger API 文档​

访问 Swagger UI​

API 基础路径​

CORS 支持​

Prometheus 指标​

相关文档​

概述

API 功能

Web UI 集成

Swagger API 文档

访问 Swagger UI

API 基础路径

CORS 支持

Prometheus 指标

相关文档