API 文档

Sublink Worker 暴露了一组 RESTful 端点，帮助你在 CI、脚本或运维平台中批量生成订阅、保存配置以及共享短链。

基础信息

• Base URL：https://<your-worker-domain>.workers.dev
• 所有请求均使用 HTTPS，推荐附带 Accept-Language 以获得对应语言的提示。

端点

1. 生成配置

/singbox

• 方法：GET
• 参数：
  • config (必需)：URL 编码后的代理列表，可包含多行（使用 %0A 分隔）。
  • selectedRules：预定义规则集数组，JSON 字符串。
  • customRules：自定义规则数组，JSON 字符串。
  • pin：true/false，是否将自定义规则置顶。
  • configId：配合基础配置存储使用，详见基础配置。
  • 其他：ua、group_by_country、enable_clash_ui、external_controller 等。

/singbox?config=vmess%3A%2F%2Fexample&selectedRules=balanced

/clash

• 方法：GET
• 参数与 /singbox 完全一致，响应内容为 text/yaml。

/surge

• 方法：GET
• 参数与 /singbox 基本一致，但不支持 customRules 置顶；返回 Surge 规则文本，并附带 subscription-userinfo 响应头。

/xray

• 方法：GET
• 参数：
  • config (必需)：URL 编码后的代理配置（每行一个）。
  • ua：自定义 User-Agent，用于订阅抓取。

2. 短链接

/shorten

• 方法：GET
• 参数：url (必需)，将生成 https://<domain>/s/<code>。

{
  "shortUrl": "https://worker-domain.workers.dev/s/abcdefg"
}

/s/{shortCode}

• 方法：GET
• 描述：根据 shortCode 重定向到原始 URL，当记录不存在时返回 404。

3. 保存基础配置

/config

• 方法：POST
• Body：

{
  "type": "clash" | "singbox" | "surge",
  "content": "配置内容"
}

• 响应：成功返回 configId（字符串）。失败返回 400 + 错误描述。

使用方式：在生成配置时追加 configId 参数即可，例如：

https://worker-domain.workers.dev/clash?config=vmess://xxx&configId=clash_abc123

预定义规则集

可在 selectedRules 中使用以下名称：

Rule Name	Site Rules	IP Rules
Ad Block	category-ads-all
AI Services	category-ai-!cn
Bilibili	bilibili
YouTube	youtube
Google	google	google
Private		private
Location:CN	geolocation-cn	cn
Telegram		telegram
Microsoft	microsoft
Apple	apple
Bahamut	bahamut
Social Media	facebook, instagram, twitter, tiktok, linkedin
Streaming	netflix, hulu, disney, hbo, amazon
Gaming	steam, epicgames, ea, ubisoft, blizzard
Github	github, gitlab
Education	coursera, edx, udemy, khanacademy, category-scholar-!cn
Financial	paypal, visa, mastercard, stripe, wise
Cloud Services	aws, azure, digitalocean, heroku, dropbox

Sing-Box 规则集来自 lyc8503/sing-box-rules。

自定义规则

customRules 接收 JSON 数组，每个对象支持以下字段：

字段	说明
site	域名规则，逗号分隔
ip	IP 规则，逗号分隔
domain_suffix	域名后缀
domain_keyword	域名关键词
ip_cidr	IP CIDR
protocol	协议匹配
name	对应的出站名称

示例：

[
  {
    "site": "google,anthropic",
    "ip": "private,cn",
    "domain_suffix": ".com,.org",
    "domain_keyword": "Mijia Cloud,push.apple",
    "ip_cidr": "192.168.0.0/16,10.0.0.0/8",
    "protocol": "http,tls,dns",
    "name": "🤪 MyCustomRule"
  }
]

将 pin=true 可把自定义规则置顶，优先级高于预设规则。

错误处理

• 400 Bad Request：缺少 config、url 等必需参数，或 customRules 格式无效。
• 404 Not Found：短链不存在、指定 configId 不存在。
• 500 Internal Server Error：运行时异常；可查看 Worker 日志或增加 KV 可用性。

使用建议

1. config 参数内若包含多条订阅，请使用 %0A（URL 编码后的换行）分隔。
2. 配合 Accept-Language 可获得不同语言的提示文本。
3. 通过 ua 自定义订阅抓取的 User-Agent，避免被目标服务器屏蔽。
4. 配置持久化/短链写操作建议加上访问令牌或速率限制，避免滥用。