API

api 块向外部工具（xray api ...、可观测面板、动态规则客户端等） 暴露一个 gRPC 管理面，让它们能与运行中的 Xray 实例通信。该块配置一 个内部入站，路由引擎需要把该入站对应的流量也路由出去 —— 通常通过 inboundTag 规则完成。

选项

字段	类型	默认值	允许值	描述
tag	string	(required)	<inbound tag>	暴露给路由引擎的 API 入站 tag。必填且不能为空 —— 空值在解析阶段就会被拒绝。
listen	string	127.0.0.1:0	<host:port>	gRPC API 的监听地址。未设置时注册一个进程内入站，而不是 TCP 监听器。
services	[]string	[]	HandlerService | LoggerService | StatsService | ObservatoryService | RoutingService | ReflectionService	要暴露的 API 服务列表。大小写不敏感；未知名称会被静默忽略。

源码： infra/conf/api.go:16-20 · 锚定版本 v26.6.1 (94ffd50)

可用服务

services 数组中的名称在 APIConfig.Build （infra/conf/api.go:28-43）中映射到 gRPC 服务注册。大小写不敏感 —— "HandlerService"、"handlerservice" 与 "HANDLERSERVICE" 都 接受。

服务	作用
HandlerService	运行时增删入站 / 出站。
LoggerService	重开日志文件（配合 logrotate 用）。
StatsService	读取 stats 启用后发布的计数器。
ObservatoryService	查询延迟探测的最新结果。
RoutingService	测试路由判断并重新加载规则。
ReflectionService	标准 gRPC 反射，便于通用客户端自我探测。

示例

最小管理端点，配合可读取的统计计数器：

{
  "stats": {},
  "api": {
    "tag": "api",
    "listen": "127.0.0.1:10085",
    "services": ["HandlerService", "StatsService"]
  },
  "routing": {
    "rules": [
      { "type": "field", "inboundTag": ["api"], "outboundTag": "api" }
    ]
  }
}

说明

• tag 不能为空 —— Build 会返回 "API tag can't be empty." （infra/conf/api.go:23-25）。
• 把 api.services 与一条捕获 inboundTag: ["api"] 的路由规则 配套，让流量转入同名出站。否则 API 在监听端口上虽可达，但路由 引擎对其没有任何规则。
• 想做 Prometheus 风格抓取，优先选用 metrics 块 —— 它暴露纯 HTTP 端点，无需 gRPC 机制。

源码： infra/conf/api.go:16-20 · v26.6.1 (94ffd50)