Operator API Quick Start zh

ClashFest 品牌定制 —— 运营方快速开始

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

本文面向希望让自己那份 ClashFest 看起来像自家服务的面板运营方。客户端会读取你订阅 URL 的 HTTP 响应头并据此自我调整。

如果你是希望在管理后台原生呈现这些响应头的面板开发者，请见响应头参考。

你需要什么

1. 客户端会以 GET <sub-url> 请求你的订阅 URL。
2. 你的面板能为这些响应添加自定义 HTTP 响应头。所有现代 Clash 面板都支持 —— 见下方各面板说明。
3. 一个托管你徽标的公开 HTTPS URL（PNG 或 WebP，推荐 256×256，≤200KB）。ClashFest 默认主题为深色，因此一个在深色下好看的徽标就够了；若你也想为浅色主题用户提供单独徽标，请两个都托管。

最小可用品牌

⚠️ X-Branding-Enabled: true 是必需的。 品牌为按订阅选择性开启。没有这个主开关，其他所有 X-Brand-* 响应头都会被解析但忽略，应用保持默认。这是「我的品牌不显示」的第一大原因。

主开关加三个标识响应头即可获得明显的「品牌化」观感：

X-Branding-Enabled: true
X-Brand-Name: SwiftVPN
X-Brand-Logo-URL: https://cdn.example.com/swiftvpn-logo-dark.png
X-Brand-Accent-Color: #5E35B1

若日后要回退品牌，移除 X-Branding-Enabled 或设为 false —— 客户端会在下次订阅刷新时恢复默认 UI。

例外： 像 X-Brand-Hide-Global-Mode 这样的运营方策略响应头仅凭存在即生效，不需要 X-Branding-Enabled。见响应头参考。

之后填入运营方信息，让关于页看起来像一张真正的名片：

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-Logo-Light-URL: https://cdn.example.com/swiftvpn-logo-light.png

v1 到此为止。v2 增加 X-Brand-Status-URL、X-Brand-Renew-URL 以及静态的 X-Brand-Max-Devices 徽标。v3 增加 X-Brand-Hide-Routing 以简化终端用户 UI。

各面板配置

各面板版本的 UI 标签措辞不同。原理处处相同：找到订阅响应的「custom headers」区域，粘贴这些值。

Pasarguard

1. 管理面板 → Settings → Subscription
2. 滚动到 Custom Headers（或 Response Headers）
3. 每行一条添加：

   X-Branding-Enabled: true
   X-Brand-Name: SwiftVPN
   X-Brand-Logo-URL: https://cdn.example.com/swiftvpn-logo-dark.png
   X-Brand-Accent-Color: #5E35B1
   X-Brand-Support-URL: https://t.me/swiftvpn_support
   

4. 保存。
5. 用 curl -I <subscription-url> 验证 —— 响应中应包含 X-Brand-* 响应头。

Marzban

Marzban 通过主机级模板配置（/etc/marzban/.env 或你安装所用的配置文件）暴露订阅响应头。

SUB_PROFILE_TITLE="vasya@example.com"
SUBSCRIPTION_PAGE_TEMPLATE="subscription/page.html"
CUSTOM_TEMPLATES_DIRECTORY="/var/lib/marzban/templates/"

要添加任意 X-Brand-* 响应头，可在 app/subscription/v2ray.py（或你版本所用的响应构建器）中用 response.headers["X-Brand-Name"] = "SwiftVPN" 扩展响应来覆盖订阅路由。对多数面板部署者而言，更简单的做法是在前面放一个小型反向代理（nginx / Caddy）并在那里添加响应头 —— 见下方「通用反向代理」。

Marzneshin

Marzneshin v0.5+ 在管理后台 Settings → Branding 下有 「Subscription branding」 区域。直接在那里粘贴响应头。

旧版本请使用反向代理方案。

Remnawave

管理后台 → Hosts → 选择主机 → Branding。每个字段对应一个响应头。保存并用 curl -I 复查。

3x-ui / X-UI

3x-ui 有 「Subscription Settings」 面板。在较新版本中查找 Response Headers。若你的版本没有，请使用反向代理方案。

通用反向代理（适用于任何面板）

若你的面板不暴露自定义响应头，在订阅路由前放置 nginx（或 Caddy）来注入响应头：

nginx：

location /sub/ {
    proxy_pass http://localhost:8080;

    add_header X-Branding-Enabled "true" always;
    add_header X-Brand-Name "SwiftVPN" always;
    add_header X-Brand-Logo-URL "https://cdn.example.com/swiftvpn-logo-dark.png" always;
    add_header X-Brand-Accent-Color "#5E35B1" always;
    add_header X-Brand-Website-URL "https://swiftvpn.example.com" always;
    add_header X-Brand-Support-URL "https://t.me/swiftvpn_support" always;
    add_header X-Brand-Telegram-URL "https://t.me/swiftvpn_news" always;
    add_header X-Brand-Privacy-URL "https://swiftvpn.example.com/privacy" always;
    add_header X-Brand-Terms-URL "https://swiftvpn.example.com/terms" always;
}

always 标志很重要 —— 没有它，nginx 会在非 2xx 响应上跳过这些响应头。

Caddy：

sub.swiftvpn.example.com {
    reverse_proxy localhost:8080

    header X-Branding-Enabled "true"
    header X-Brand-Name "SwiftVPN"
    header X-Brand-Logo-URL "https://cdn.example.com/swiftvpn-logo-dark.png"
    header X-Brand-Accent-Color "#5E35B1"
    header X-Brand-Website-URL "https://swiftvpn.example.com"
    header X-Brand-Support-URL "https://t.me/swiftvpn_support"
    header X-Brand-Telegram-URL "https://t.me/swiftvpn_news"
    header X-Brand-Privacy-URL "https://swiftvpn.example.com/privacy"
    header X-Brand-Terms-URL "https://swiftvpn.example.com/terms"
}

验证

部署后：

curl -I "https://your-domain.example/sub/<token>"

你应在响应中看到你的 X-Brand-* 响应头。若没有，则面板 / 代理没有发送它们 —— 检查你的配置。

若响应头在但应用无反应，多半是值未通过校验。常见问题：

• 徽标 URL 是 http://（必须是 https://）
• 徽标文件过大（>512KB）或类型错误（非 PNG / WebP / JPEG）
• 强调色不是严格的 #RRGGBB（不支持 #RGB、rgba()）
• 品牌名称含控制字符，或 trim 后 >32 字符

完整校验规则见安全。

重置行为

用户可点击 Settings → Reset branding 来移除你的品牌并恢复应用的默认身份。这不是攻击 —— 而是应用必须提供的有意逃生口（类似「恢复出厂设置」）。只要响应头仍在发送，你的品牌会在下次订阅拉取时回来。

品牌定制不会改变什么

按设计，无论是否品牌定制，以下始终保持 ClashFest 默认：

• Android 启动器图标（用户从商店安装的是「ClashFest」，主屏上仍是它）
• Android 包名与应用商店条目
• 关于页上的「powered by ClashFest」一行
• Settings → About → 「App version」/ 构建标识

如果你需要完全 white-label 的应用商店呈现（自己的图标、自己的条目），那属于另一个范畴 —— 请与我们联系，做一个正式的 fork / 重新品牌化构建。