Operator API zh

ClashFest Operator API

🌐 English · Русский · 中文

面向 VPN 运营方的规范：定制你分发给用户的 ClashFest Android 客户端 —— 品牌、支持链接、按用户上下文、默认行为 —— 全部通过订阅 URL 上的 HTTP 响应头传递。

状态：草案（v1 设计中）。 本文档在设计与实现期间为权威来源。各响应头的实现状态见响应头参考（v1 / v2 / v3 / proposed）。

这是什么

每次 ClashFest 客户端拉取你的订阅 URL 时，都会读取一组 HTTP 响应头，用于描述：

• 品牌标识 —— 名称、徽标（深色 + 浅色变体）、标语、强调色
• 运营方信息 —— 网站、支持 / telegram / bot、隐私 / 条款 / 帮助、状态、续费
• 按用户上下文 —— 已由 profile-title 覆盖（自由文本，面板控制）
• UX 简化 —— 为终端用户隐藏 Routing 标签
• 订阅策略 —— 分享链接策略、HWID 强制、最大设备数
• 公告 —— 带可选 URL 的广播消息

客户端将这一切视为运营方提示 —— 绝不盲目信任。每个值都会经过校验（最大长度、格式、URL 白名单、图片大小限制、SSRF 防护）。见安全。

为什么用响应头而非 JSON 端点？

• 直接复用现有订阅 URL —— 无需额外端点，无需鉴权状态
• 每个 Clash 兼容面板（Pasarguard / Marzban / Marzneshin / Remnawave / 3x-ui / X-UI）都已支持在订阅路由上自定义响应头 —— 你的面板团队填值，客户端读取
• 易于代理 / 缓存
• 前向兼容：不认识某响应头的客户端会直接忽略

响应头命名

所有 ClashFest 专用响应头使用 X-Brand-* 前缀。

部分响应头保留其常规 V2Ray / Clash 兼容名称（profile-title、Subscription-Userinfo、announce、share-links、x-hwid-*），因为面板已普遍支持它们。我们是扩展而非重命名。

响应头不区分大小写匹配。

快速示例

一个订阅响应可能是这样：

HTTP/1.1 200 OK
Content-Type: application/x-clash
Subscription-Userinfo: upload=1234; download=5678; total=107374182400; expire=1735689600

profile-title: vasya@example.com — Premium

X-Branding-Enabled: true
X-Brand-Name: SwiftVPN
X-Brand-Tagline: Fast and private since 2024
X-Brand-Logo-URL: https://swiftvpn.example.com/static/logo-dark-256.png
X-Brand-Logo-Light-URL: https://swiftvpn.example.com/static/logo-light-256.png
X-Brand-Accent-Color: #5E35B1

X-Brand-Cabinet-URL: https://t.me/<bot>?startapp={{SHORT_UUID}}
X-Brand-Website-URL: https://swiftvpn.example.com
X-Brand-Support-URL: https://t.me/swiftvpn_support
X-Brand-Telegram-URL: https://t.me/swiftvpn_news
X-Brand-Bot-URL: https://t.me/swiftvpn_bot
X-Brand-Privacy-URL: https://swiftvpn.example.com/privacy
X-Brand-Terms-URL: https://swiftvpn.example.com/terms
X-Brand-Help-URL: https://swiftvpn.example.com/help
X-Brand-Renew-URL: https://swiftvpn.example.com/billing

announce: New servers added in Frankfurt and Amsterdam.
announce-url: https://swiftvpn.example.com/news/2026-05

ClashFest 读取后：

• 主屏顶部显示 SwiftVPN 并在左侧显示运营方徽标，而非「ClashFest」—— 深/浅徽标变体匹配用户当前主题
• 全 UI 的主强调色为 #5E35B1（前提是通过对比度过滤 —— 见安全）
• 关于页显示「SwiftVPN — powered by ClashFest」，并带 Website / Privacy / Terms / Help / Telegram / Bot 链接
• 配置卡显示订阅名称「vasya@example.com — Premium」（运营方控制的自由标题）
• 公告栏显示运营方消息并链接到新闻页
• 当订阅距到期 <3 天时，现有的临期徽标变为可点击 → 打开续费 URL；配置文件溢出菜单中也会出现「Renew」项

文档

• 响应头参考 —— 每个响应头的完整参考：类型、示例、语义、校验规则、回退、实现状态。
• 模板变量 —— 面板模板变量（{{USERNAME}}、{{DAYS_LEFT}} 等）如何流入品牌响应头，含各面板速查表与实用配方。
• 安全 —— 客户端校验什么、威胁模型、SSRF 防护、图片大小限制。
• 快速开始 —— 在 Pasarguard / Marzban / Remnawave / 3x-ui 上的分步配置。

面向面板开发者

若你维护的面板希望一流地支持 ClashFest 品牌，最快路径：

1. 阅读响应头参考并挑选要暴露的子集（多数运营方从 X-Brand-Name + X-Brand-Logo-URL + X-Brand-Accent-Color 开始）
2. 在你的管理面板中添加供运营方配置这些值的 UI
3. 在每个订阅 HTTP 响应中回显它们

多数现代面板已支持「自定义响应头」功能 —— 运营方无需改动面板即可将响应头以列表形式粘贴。

许可

本规范有意宽松 —— 实现它、镜像它、fork 它、扩展它。若你在其之上构建了作品，欢迎（但不强制）回链到本仓库。