API 参考

API 概述

PasarGuard Node 提供 REST API 和 gRPC 接口用于管理节点、用户和检索统计信息。

身份验证

所有 API 请求都需要使用在您的 .env 文件中配置的 API_KEY 进行身份验证。

REST API:

Authorization: Bearer <api_key>

gRPC:

authorization: Bearer <api_key>

基础 URL

REST API 请求应发送到：

https://your-node-address:port/

内容类型

REST API 使用 Protocol Buffers 进行数据序列化：

Content-Type: application/x-protobuf

数据结构

Backend

message Backend {
  BackendType type;      // 后端类型（XRAY = 0）
  string config;         // 后端配置
  repeated User users;   // 用户列表
  uint64 keepAlive;      // 保持活动持续时间（秒）
}

User

message User {
  string email;           // 用户唯一电子邮件标识符
  Proxy proxies;          // 代理配置
  repeated string inbounds; // 入站标签列表
}

StatRequest

message StatRequest {
  string name;      // 用户电子邮件或入站/出站标签
  bool reset;       // 检索后重置流量统计
  StatType type;    // 要检索的统计类型
}

enum StatType {
  Outbounds = 0;   // 所有出站统计
  Outbound = 1;    // 单个出站统计
  Inbounds = 2;    // 所有入站统计
  Inbound = 3;     // 单个入站统计
  UsersStat = 4;   // 所有用户统计
  UserStat = 5;    // 单个用户统计
}

API 方法

节点管理

启动 Backend

使用配置启动节点 backend。

POST /start
Authorization: Bearer <api_key>
Content-Type: application/x-protobuf

Body: Backend (protobuf)

rpc Start(Backend) returns (BaseInfoResponse)

这是在创建与节点的连接之前调用的唯一方法。

停止 Backend

停止 backend 并停用客户端连接。

PUT /stop
Authorization: Bearer <api_key>

rpc Stop(Empty) returns (Empty)

获取基本信息

检索基本节点信息并检查连接状态。

GET /info
Authorization: Bearer <api_key>

rpc GetBaseInfo(Empty) returns (BaseInfoResponse)

响应：

message BaseInfoResponse {
  string version;
  string core_type;
  bool running;
}

日志记录

获取日志

从 backend 流式传输实时日志。

GET /logs
Authorization: Bearer <api_key>

// Returns Server-Sent Events (SSE) stream

rpc GetLogs(Empty) returns (stream Log)

日志结构：

message Log {
  string detail;  // Log message
}

统计信息

获取系统统计

检索系统级统计信息。

GET /stats/system
Authorization: Bearer <api_key>

rpc GetSystemStats(Empty) returns (SystemStatsResponse)

响应：

message SystemStatsResponse {
  uint64 mem_total;                  // Total memory
  uint64 mem_used;                   // Used memory
  uint64 cpu_cores;                  // CPU cores
  double cpu_usage;                  // CPU usage %
  uint64 incoming_bandwidth_speed;   // Download speed
  uint64 outgoing_bandwidth_speed;   // Upload speed
}

获取 Backend 统计

检索 backend 运行时统计信息。

GET /stats/backend
Authorization: Bearer <api_key>

rpc GetBackendStats(Empty) returns (BackendStatsResponse)

响应：

message BackendStatsResponse {
  uint32 num_goroutine;    // Active goroutines
  uint32 num_gc;           // GC runs
  uint64 alloc;            // Allocated memory
  uint64 total_alloc;      // Total allocated
  uint64 sys;              // System memory
  uint64 mallocs;          // Malloc count
  uint64 frees;            // Free count
  uint64 live_objects;     // Live objects
  uint64 pause_total_ns;   // Total GC pause
  uint32 uptime;           // Uptime in seconds
}

获取流量统计

检索用户、入站或出站的流量统计信息。

GET /stats
Authorization: Bearer <api_key>
Content-Type: application/x-protobuf

Body: StatRequest (protobuf)

rpc GetStats(StatRequest) returns (StatResponse)

示例：

获取所有用户的统计信息：

StatRequest {
  type: UsersStat,
  reset: false
}

获取特定用户的统计信息：

StatRequest {
  name: "user@example.com",
  type: UserStat,
  reset: true  // Reset after retrieval
}

响应：

message StatResponse {
  repeated Stat stats;
}

message Stat {
  string name;   // User email or tag
  string type;   // Stat type
  string link;   // Link identifier
  int64 value;   // Traffic value in bytes
}

获取用户在线统计

获取用户的在线连接数。

GET /stats/user/online
Authorization: Bearer <api_key>
Content-Type: application/x-protobuf

Body: StatRequest (protobuf)

rpc GetUserOnlineStats(StatRequest) returns (OnlineStatResponse)

响应：

message OnlineStatResponse {
  string name;   // User email
  int64 value;   // Online connection count
}

获取用户在线 IP 列表

获取在线用户连接的 IP 列表。

GET /stats/user/online_ip
Authorization: Bearer <api_key>
Content-Type: application/x-protobuf

Body: StatRequest (protobuf)

rpc GetUserOnlineIpListStats(StatRequest) returns (StatsOnlineIpListResponse)

用户管理

同步用户

添加、更新或删除单个用户。

PUT /user/sync
Authorization: Bearer <api_key>
Content-Type: application/x-protobuf

Body: User (protobuf)

rpc SyncUser(stream User) returns (Empty)

要删除用户，请发送空的 inbounds 数组。gRPC 提供流式接口，但 REST 需要对每个用户进行单独调用。

同步多个用户

用新集合替换所有用户。

PUT /users/sync
Authorization: Bearer <api_key>
Content-Type: application/x-protobuf

Body: Users (protobuf)

rpc SyncUsers(Users) returns (Empty)

此方法将删除所有旧用户并用提供的列表替换它们。

错误响应

HTTP 状态码

代码	含义
200	成功
400	错误请求 - 无效数据
401	未授权 - 无效的 API_KEY
404	未找到 - 端点不存在
500	内部服务器错误

错误格式

{
  "error": "Error description",
  "code": "ERROR_CODE"
}

速率限制

目前没有内置的速率限制，但建议：

尽可能批量更新用户
在本地缓存统计信息
避免过度轮询

API 参考

On this page