# 托管 API 功能

提示

请先参考 文档 搭建托管 API

# 接口鉴权

# 打开鉴权

surgio.conf.js 中增加如下字段:

{
  gateway: {
    auth: true,
    accessToken: 'YOUR_PASSWORD',
  },
}
1
2
3
4
5
6

# 请求需要鉴权的接口

请在请求的 URL 中加入参数 access_token,值为上面所设。

# 未开启鉴权

https://xxxxxx.xxx.now.sh/list-artifact
1

# 开启鉴权

https://xxxxxx.xxx.now.sh/list-artifact?access_token=YOUR_PASSWORD
1

# 面板

直接打开 Vercel 分配的域名就可以看到新版的面板。如果开启了鉴权则需登录。

# Artifact 分类

Artifact 配置新增分类,方便在面板中找到想要的 Artifact。Surgio 内置了一些常用的类型,并且还为内置分类增加了个性化的功能。

categories 接受一个数组,数组内容可以自定也可以使用内置字段。

const { categories } = require('surgio');

module.exports = {
  artifacts: [
    {
      name: 'SurgeV3.conf',
      template: 'surge_v3',
      provider: 'demo',
      categories: [
        'Maying',
        categories.SURGE,
      ],
    },
    {
      name: 'Surge.conf',
      template: 'surge',
      provider: 'demo',
      categories: [
        categories.SURGE,
      ],
    }
  ],
};
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

以下是所有的内置分类字段:

  • categories.SNIPPET - 片段
  • categories.SURGE - Surge
  • categories.QUANTUMULT_X - Quantumult X 完整配置
  • categories.QUANTUMULT_X_SERVER - Remote Server 片段
  • categories.QUANTUMULT_X_FILTER - Remote Filter 片段
  • categories.QUANTUMULT_X_REWRITE - Remote Rewrite 片段
  • categories.CLASH - 完整 Clash 配置

# 接口

# 下载 Artifact

GET /get-artifact/<artifactName>
1
需要鉴权

# 可选 URL 参数

参数 可选值 备注
format surge-policy, qx-server, clash-provider
filter 内置的过滤器或自定义过滤器

定义:

  • surge-policy Surge 远程节点 Policy
  • qx-server QuantumultX 远程节点
  • clash-provider Clash Provider

提示

  1. format 使用的是内置的模板,所以你不需要额外定义模板格式,不过仍然需要定义一个完整的 Artifact。我的建议是定义一个有完整节点的 Artifact,然后根据需要过滤出节点;
  2. filter 的值为过滤器的名称。你可以直接使用内置的过滤器,例如 hkFilter;也可以使用自定义的过滤器,例如 customFilters.myFilter

# 自定义参数

URL 中的 Query 参数能够传入到模板变量 customParams 中,方便用户拓展模板。

比如:

https://example.now.sh/get-artifact/Surge.conf?access_token=token&foo=bar
1

那模板变量 customParams.foo 值为 bar。如果已经在 Artifact 中定义了这个 Key,那预先定义的值将被覆盖。

注意

  1. URL 参数中的值的类型都是字符串,形如 true1 这样的值在模板中是 "true""1"
  2. access_token, format, filter, dl 为保留 Key 无法被定义;

# 直接导出 Provider

GET /export-providers
1
需要鉴权

有时候你只想将 Provider 导出成类似 Surge Policy 或者其它格式的配置,那么可以借助这个功能快速达到目的,免去了新建一个 Artifact 的麻烦。即使这个 Provider 没有被任何一个 Artifact 使用,它也是能够被直接导出的!

# 可选 URL 参数

参数 可选值 备注
format surge-policy, qx-server, clash-provider
template 任意一个 .tpl 文件
filter 内置的过滤器或自定义过滤器

# 使用内置 format 导出

你可以在面板的 Provider 页面找到复制链接按钮。目前面板还不支持复制组装多个 Provider 的 URL。如果你想组装多个 Provider,可以修改 URL 中的 providers 参数,多个 Provider 名称以逗号分隔,例如:

https://example.com/export-providers?providers=maying,dlercloud&format=surge-policy
1

提示

合并多个 Provider 时,第一个 Provider 为主 Provider,遵循过滤器的合并规则。

# 指定 Template 导出

你可以通过增加 URL 参数 template 来制定使用某个 Template 来导出 Provider。值得一提的是,这种方法不需要新定义 Artifact。

注意

  1. 参数 templateformat 不能同时出现;
  2. filter 的值为过滤器的名称。你可以直接使用内置的过滤器,例如 hkFilter;也可以使用自定义的过滤器,例如 customFilters.myFilter

# 直接渲染模板

GET /render?template=[template name]
1

有时候我们并不需要将节点和规则完整的渲染出来,而是渲染某个模板。通过这个接口我们可以方便地渲染某个 Template,例如:

https://example.com/render?template=static
1

这样 Surgio 就会渲染仓库目录下 ./template/static.tpl 的内容。

提示

  1. 只有 downloadUrlgetUrl 这两个模板变量(方法)有效;
  2. 你不可以在这里的模板中引用 nodeList 之类的变量,因为根本不会解析节点;
  3. 子目录下的模板也是可以直接渲染的;

# 正向代理

/proxy/[url]
1

这个正向代理可以让我们方便在没有梯子的情况下获取到一些下载困难的文件,同时也可以为远程片段加速。需要注意的是,正向代理不同于你常用的梯子。

这个功能依赖 Rob--W/cors-anywhere。你可以通过设置以下两个环境变量来限制请求来源。

  • CORSANYWHERE_BLACKLIST(对应 originBlacklist
  • CORSANYWHERE_WHITELIST(对应 originWhitelist

使用方法:

/proxy/https://github.com/lhie1/Rules/raw/master/Surge/Surge%203/Provider/Media/Netflix.list
1