Operator API Headers zh

ClashFest Operator API —— 响应头参考

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

状态图例：

• v1 —— 现已实现（或计划于当前分支）
• v2 —— 下一批（扩展运营方信息 + 策略展示）
• v3 —— 稍后（运营方控制的 UI 简化）
• proposed —— 已纳入规范，尚未排期

所有响应头不区分大小写匹配。空 / 空白值视为「响应头不存在」。字符串字段可为纯 UTF-8 或带 base64: 前缀（X-Brand-Name: base64:U3dpZnRWUE4=）—— 客户端两者都解码。

ClashFest 主题以深色为主。凡存在「浅色」替代方案处，它都是可选的覆盖项。

---

0. 主开关

X-Branding-Enabled

类型	boolean
状态	v1
何时必需	任何外观品牌定制。 若此响应头未设为 true，所有 X-Brand-* 标识/标签/信息字段都会被忽略，客户端显示默认 ClashFest UI。例外： 运营方策略响应头（§4b，如 X-Brand-Hide-Global-Mode）无需此开关即生效。
默认	缺失 / false / null → 品牌关闭
备注	品牌为按订阅显式选择性开启。设置 X-Brand-Name、X-Brand-Logo-URL 等而不发送 X-Branding-Enabled: true 是 no-op —— 响应头会被解析并持久化，但 UI 保持默认。要回退错误部署，移除此响应头（或设 false）；客户端品牌状态会在下次订阅刷新后立即恢复。

开启品牌示例：

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

关闭 / kill switch 示例：

X-Branding-Enabled: false

---

1. 品牌标识

X-Brand-Name

类型	string · 最大长度 32 · 状态 v1
作用于	主屏顶部标题（替换「ClashFest」）；关于页
回退	「ClashFest」 · 校验

示例： X-Brand-Name: SwiftVPN

X-Brand-Tagline

类型	string · 最大长度 64 · 状态 v1
作用于	关于页副标题；品牌名下方的可选小副标题 · 回退

X-Brand-Logo-URL

类型	URL（仅 https） · 状态 v1
作用于	顶部圆形徽标（品牌名左侧）；关于页图标
图片格式	PNG、WebP、JPEG。不支持 SVG（见 Security）
推荐尺寸	256×256，≤200KB · 硬上限
缓存	磁盘 <filesDir>/brand/<sha256(url)>，原子写入
校验	仅 https、content-type 白名单、SSRF 防护（无私有 IP / 重定向到私有 IP）、大小上限
回退	启动器图标 · 备注

X-Brand-Logo-Light-URL

类型	URL（仅 https） · 状态 v1 · 作用于
回退	X-Brand-Logo-URL · 备注

X-Brand-Accent-Color

类型	十六进制颜色 #RRGGBB · 状态 v1
作用于	全局 colorPrimary 运行时覆盖 —— 电源按钮、开关、进度条、填充胶囊、选中态、强调表面
校验	正则 ^#[0-9A-Fa-f]{6}$；与表面对比度 < 3:1（WCAG AA 大文本最低值）则拒绝
回退	内置主题强调色 · 备注

示例： X-Brand-Accent-Color: #5E35B1

---

2. 运营方信息 / 外部链接

所有 URL 字段共用同一校验：必须为 https://、tg://、mailto: 或 t.me/（自动升级为 https://t.me/）。其他一律忽略。

• X-Brand-Website-URL（v1）→ 关于页「Visit website」
• X-Brand-Support-URL（v1）→ 配置卡与面板中的支持图标；关于页。也接受旧式 support-url / Profile-Support-URL / Subscription-Support-URL（X-Brand-Support-URL 优先）。
• X-Brand-Telegram-URL（v1）→ 关于页「Telegram channel」
• X-Brand-Bot-URL（v1）→ 关于页「Telegram bot」（与频道分开）
• X-Brand-Privacy-URL · X-Brand-Terms-URL · X-Brand-Help-URL（v1）→ 关于页隐私 / 条款 / 帮助
• X-Brand-Status-URL（v2）→ 断线 / 拉取失败对话框中的「Check service status」

X-Brand-Renew-URL

类型	URL · 状态 v2
作用于	当订阅到期临界（<3 天或已过期）：临期徽标可点击、面板「Renew」按钮、溢出菜单「Renew subscription」；设置后关于页也出现 Renew 按钮。
备注	所有入口仅在提供 URL 时出现。无 URL → 无 Renew UI。

X-Brand-Cabinet-URL

类型	URL（https / tg / mailto）—— 几乎总用面板模板变量构建 · 状态 v3
作用于	Operator 标签上的「My account」按钮。
备注	运营方用面板标识模板构建按用户 URL —— {{SHORT_UUID}}、{{ID}}、{{USERNAME}}。例：Telegram Mini App https://t.me/<bot>?startapp={{SHORT_UUID}}；Web 后台 https://billing.example.com/account?ref={{ID}}。客户端以 ACTION_VIEW 打开。

---

3. 用户上下文

客户端仅用一个字段做面向用户的标识。按用户个性化放在 profile-title —— 运营方可放任意内容（自由文本，面板控制）。

• profile-title（既有，非 Brand，v1）→ 配置卡标题
• X-Brand-User-Display-Name（string，最大 64，v2）→ 关于页「Logged in as 」。通过模板变量填充，如 {{USERNAME}}。见模板变量。
• X-Brand-Greeting（string，最大 120，v2）→ Operator 标签上的问候语。常配合模板动态内容，如 Welcome back, {{USERNAME}}! {{DAYS_LEFT}} days remaining。若缺失但设了 X-Brand-User-Display-Name，回退为内置「Hello, !」。

---

4. UX 默认 —— 运营方控制的简化

X-Brand-Show-Operator-Tab

类型	boolean · 状态 v1
作用于	在底部导航新增「Operator」标签，含徽标 + 名称 + 标语 + Renew CTA + 信息链接列表。
备注	显式选择性开启。仅发送标识（名称/徽标/强调色）不会自动新增标签。与 X-Brand-Hide-Routing 搭配可替换 Routing 而非新增第 5 个标签。

X-Brand-Hide-Routing

类型	boolean · 状态 v1
作用于	与 X-Brand-Show-Operator-Tab=true 搭配时，Operator 标签在底部导航中替换 Routing（仍为 4 个标签）。单独使用无效。

---

4b. 运营方策略 —— 无需 X-Branding-Enabled 即生效

以上皆为外观品牌，需要 X-Branding-Enabled: true。下列为运营方策略（对用户行为的限制，而非外观），仅凭存在即生效，不需要开启品牌，并且能在 X-Branding-Enabled: false kill-switch 后存留（该开关仅清除外观品牌）。

X-Brand-Hide-Global-Mode

类型	boolean · 状态 v4
需要 X-Branding-Enabled？	否 —— 唯一完全无品牌也生效的响应头。
作用于	隐藏主页 Global 模式按钮并将应用锁定在 Rule（若用户在 Global 会切回 Rule）。「Mode」行与 Rule 按钮保留。
备注	运营方管控而非品牌：防止用户将全部流量走代理、绕过规则。无论 X-Branding-Enabled 缺失 / true / false 都生效。

---

5. 订阅策略

• Subscription-Userinfo（既有，v1，格式 upload=N; download=N; total=N; expire=UNIX）→ 配置卡上的流量进度、临期徽标
• profile-update-interval（既有，整数小时，v1）→ 自动更新间隔，强制 ≥15 分钟
• share-links（既有，boolean，v1）→ true/1/yes/on 时隐藏「复制节点链接」/「分享」，并仅对该订阅锁定 URL 编辑。按配置文件存储，不同订阅可有不同策略。
• X-Network-Stack（枚举 system | gvisor | mixed | auto，v1，无需 X-Branding-Enabled）→ 交给 VpnService 的 TUN 网络栈。system/gvisor/mixed 会锁定该订阅的栈，覆盖用户手动的「栈模式」设置；auto = 运营商不锁定（交给用户设置 / system 默认值）。缺省该头 → 客户端默认 system。按配置文件存储（subscriptionNetworkStackFor(uuid)）。优先级：运营商头 > 用户手动设置 > Auto（采用订阅的 tun.stack）> system 默认。推荐 system——内核栈在断连时更快、更省电。可接受写法（大小写不敏感）：X-Network-Stack、Network-Stack、X-NetworkStack、X-NetworkStack-enabled。
• x-hwid-active / x-hwid-not-supported / x-hwid-max-devices-reached / x-hwid-limit（既有，boolean，v1）→ 配置卡上的 HWID 强制警告

---

6. 公告

• announce / Announcement（既有，string UTF-8 或 base64:，最大 256，v1）→ 配置卡上的行内公告栏
• announce-url / Announcement-URL（既有，URL，v1）→ 公告栏的点击目标

---

我们有意不提供的（及原因）

• X-Brand-Default-Mode —— mihomo 已从 YAML 读取 mode:。
• X-Brand-Recommended-Group —— Selector 默认选列表中第一个代理；运营方经 YAML 控制。
• X-Brand-Locale / X-Brand-Theme —— 属于用户偏好；由运营方静默覆盖是敌意 UX。
• X-Brand-Max-Devices / X-Brand-Current-Devices —— 没有当前计数，静态徽标只是填充；当前计数在响应头层面不可靠。

若未来确有需求，会先纳入 proposed 再讨论。