跳到主要内容

Python SDK

XLADA 没有官方的 Python SDK。XLADA 的 API 与 Remnawave 的 API 完全一致， 因此用 requests 只需几十行就能写出可用的客户端，而类型取自 OpenAPI 规范。

兼容性

Remnawave 有基于同一份规范构建的社区 Python 库； 理论上它们也适用于 XLADA，但我们没有用 XLADA 正式验证过。 下面的示例只依赖 requests。

安装​

python3 -m venv .venv
source .venv/bin/activate
pip install requests

异步代码可以用 httpx，但对于脚本和机器人来说， 同步的 requests 已经足够。

客户端​

令牌是 POST /api/auth/login 返回的 JWT，或者 POST /api/tokens 返回的 API 令牌。两者都通过 Authorization: Bearer 请求头传递。直接访问 面板时需要 X-Forwarded-For 和 X-Forwarded-Proto: https 请求头： 没有它们，面板的 middleware 会断开连接。

import os

import requests

PANEL_URL = os.environ.get("XLADA_PANEL_URL", "https://panel.example.com")
API_TOKEN = os.environ.get("XLADA_API_TOKEN", "")


class XladaClient:
    def __init__(self, base_url: str = PANEL_URL, token: str = API_TOKEN) -> None:
        self.base_url = base_url.rstrip("/")
        self.session = requests.Session()
        self.session.headers.update(
            {
                "Authorization": f"Bearer {token}",
                "Content-Type": "application/json",
                "X-Forwarded-For": "127.0.0.1",
                "X-Forwarded-Proto": "https",
            }
        )

    def request(self, method: str, path: str, **kwargs) -> dict:
        response = self.session.request(method, f"{self.base_url}{path}", timeout=30, **kwargs)
        response.raise_for_status()
        return response.json()

身份验证​

如果没有 API 令牌，请获取管理员 JWT 并把它传给客户端：

def login(username: str, password: str) -> str:
    response = requests.post(
        f"{PANEL_URL}/api/auth/login",
        json={"username": username, "password": password},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["response"]["accessToken"]


client = XladaClient(token=login("admin", "password"))

长期 API 令牌通过 POST /api/tokens 创建 —— 在界面中就是 Settings → API Tokens。生成好的令牌只显示一次，位于 response.token 字段：

created = client.request("POST", "/api/tokens", json={"name": "bot", "expiresInDays": 365})
print(created["response"]["token"])

用户列表​

分页输出：start —— 偏移量，size —— 每页大小（1–1000，默认 为 25）。

page = client.request("GET", "/api/users", params={"start": 0, "size": 25})

for user in page["response"]["users"]:
    print(user["username"], user["status"], user["expireAt"])

print("总计:", page["response"]["total"])

创建用户​

POST /api/users 接受 username（3–36 个字符：拉丁字母、数字、_、-） 以及必填的、ISO 8601 格式的 expireAt。

created = client.request(
    "POST",
    "/api/users",
    json={
        "username": "john_doe",
        "status": "ACTIVE",
        "expireAt": "2026-01-17T15:38:45.065Z",
        "trafficLimitBytes": 0,
        "trafficLimitStrategy": "NO_RESET",
    },
)

print(created["response"]["shortUuid"])

获取节点​

单个节点 —— 通过 uuid；节点列表 —— GET /api/nodes。

node = client.request("GET", f"/api/nodes/{node_uuid}")["response"]

print(node["name"], node["address"], node["port"], node["isConnected"])
提示

开始之前，用 GET /api/auth/status 检查面板是否可用很方便 —— 它不需要授权。

注意

不要把 API 令牌存放在仓库里。请从环境变量或 CI 密钥中读取它，并通过 DELETE /api/tokens/{uuid} 撤销多余的令牌。

接下来​

  • TypeScript SDK —— 基于 fetch 和 axios 的客户端。
  • Go SDK —— 基于 Go 标准库的客户端。
  • API Specification —— OpenAPI 中的全部 162 个端点。
  • Webhooks —— 用面板事件代替持续轮询。