Merge pull request #262 from surgioproject/dev

Sing-box configuration support

CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# CONTRIBUTING
+
+## Development
+
+- Run `pnpm run dev` to start the development toolchain
+- Run `pnpm link -g` to link the package globally
+- Run `pnpm link -g surgio` in your local surgio config repository to use the local version of surgio
+- Run generate command to check the result
+
+## Testing
+
+- Run `pnpm run test` to run the tests
+- Tests will be automatically checked by GitHub Actions
+- A green pipeline is required to merge a PR
+
+## Versioning
+
+TODO
+
+## Documentation
+
+- Run `pnpm run docs:dev` to start the live preview of the documentation
+- Add version tag in Markdown if the feature is only available in/after a specific version

docs/.vuepress/config.ts

@@ -1,9 +1,10 @@
-import { defineUserConfig, HeadConfig, PluginConfig } from 'vuepress'
+import { defineUserConfig, type HeadConfig, type PluginConfig, type UserConfig } from 'vuepress'
 import { path } from '@vuepress/utils'
-import docsearchPlugin from '@vuepress/plugin-docsearch'
-import registerComponentsPlugin from '@vuepress/plugin-register-components'
+import { docsearchPlugin } from '@vuepress/plugin-docsearch'
+import { registerComponentsPlugin } from '@vuepress/plugin-register-components'
 import { sitemapPlugin } from 'vuepress-plugin-sitemap2'
 import { umamiAnalyticsPlugin } from 'vuepress-plugin-umami-analytics'
+import { viteBundler } from '@vuepress/bundler-vite'
 
 import customTheme from './theme'
 
@@ -60,14 +61,16 @@ if (process.env.NODE_ENV === 'production') {
     sitemapPlugin({
       hostname: 'https://surgio.js.org',
     }),
-    umamiAnalyticsPlugin({
-      id: '444a5a25-af75-4c30-b7a4-6aaba520daf6',
-      src: 'https://sashimi.royli.dev/sashimi.js',
-    }),
+    // umamiAnalyticsPlugin({
+    //   id: '444a5a25-af75-4c30-b7a4-6aaba520daf6',
+    //   src: 'https://sashimi.royli.dev/sashimi.js',
+    // }) as any,
   )
 }
 
 export default defineUserConfig({
+  bundler: viteBundler(),
+  theme: customTheme,
   locales: {
     '/': {
       lang: 'zh-CN',
@@ -78,6 +81,5 @@ export default defineUserConfig({
   title: meta.title,
   description: meta.description,
   head,
-  theme: customTheme,
   plugins,
-})
+}) as UserConfig

docs/.vuepress/theme/index.ts

@@ -35,7 +35,7 @@ export default {
           },
           {
             text: '客户端规则维护指南',
-            children: ['/guide/client/clash', '/guide/client/examples'],
+            children: ['/guide/client/sing-box', '/guide/client/clash', '/guide/client/examples'],
           },
           '/guide/api',
           '/guide/cli',

docs/guide/client/sing-box.md

@@ -0,0 +1,115 @@
+---
+sidebarDepth: 1
+---
+
+# sing-box
+
+> <Badge text="v3.7.0" vertical="middle" />
+
+因为 sing-box 的配置文件为 JSON 格式，所以我们引入了一种新的方式来维护 sing-box 规则，或是其它 JSON 格式的规则。
+
+## 准备
+
+首先我们找到一份基础的规则文件，它可能是这样的：
+
+```json
+{
+  "inbounds": [],
+  "outbounds": [
+    {
+      "type": "block",
+      "tag": "block"
+    },
+    {
+      "type": "dns",
+      "tag": "dns"
+    }
+  ],
+  "route": {},
+  "experimental": {
+    "cache_file": {
+      "enabled": true
+    },
+    "clash_api": {
+      "external_controller": "127.0.0.1:9090"
+    }
+  }
+}
+```
+
+我们看到此时 `outbounds` 已经包含了一些内容，我们要做的就是把节点信息填充到 `outbounds` 中。
+
+把这个文件保存在 `tempalte` 目录下，命名为 `singbox.json`。
+
+## 编写 Artifact
+
+```js{9-26}
+const { extendOutbounds } = require('surgio');
+
+module.exports = {
+  artifacts: [
+    {
+      name: 'singbox.json',
+      template: 'singbox',
+      templateType: 'json',
+      extendTemplate: extendOutbounds(
+        ({ getSingboxNodes, getSingboxNodeNames, nodeList }) => [
+          {
+            type: 'direct',
+            tag: 'direct',
+            tcp_fast_open: false,
+            tcp_multi_path: true,
+          },
+          {
+            type: 'selector',
+            tag: 'proxy',
+            outbounds: ['auto', ...getSingboxNodeNames(nodeList)],
+            // outbounds: getSingboxNodeNames(nodeList), // 如果你不需要 auto 节点
+            interrupt_exist_connections: false,
+          },
+          ...getSingboxNodes(nodeList),
+        ],
+      ),
+      provider: 'ss',
+    },
+  ]
+}
+```
+
+这个配置的含义是：
+
+- `template` 为 `singbox`，即我们刚刚创建的模板文件
+- `extendTemplate` 为 `extendOutbounds`，这个函数会把节点信息填充到 `outbounds` 中 
+
+第 10 行的 `getSingboxNodes`, `getSingboxNodeNames` 属于「模板方法」，具体有哪些可用的模板方法可以看 [这里](/guide/custom-template.md#模板方法)。
+
+## `extendOutbounds` 函数
+
+`extendOutbounds` 支持两种写法，一种是直接输入一个不可变的变量，另一种是输入一个函数。变量即确定的不会变化的内容，函数则是相对动态的内容。上面的例子中我们使用了函数的写法。
+
+### 直接输入变量
+
+```js
+const { extendOutbounds } = require('surgio');
+
+module.exports = {
+  artifacts: [
+    {
+      name: 'singbox.json',
+      template: 'singbox',
+      templateType: 'json',
+      extendTemplate: extendOutbounds([
+        {
+          type: 'direct',
+          tag: 'direct',
+          tcp_fast_open: false,
+          tcp_multi_path: true,
+        },
+      ]),
+      provider: 'ss',
+    },
+  ]
+}
+```
+
+你可以在 [这里](/guide/custom-template.md#模板方法) 查看这篇文章中提到的所有模板方法的文档。

docs/guide/custom-artifact.md

@@ -7,7 +7,7 @@ sidebarDepth: 2
 
 Surgio 会根据 Artifact 的值来生成配置文件。你可以一次性配置多个 Artifact，一次性生成所有需要的配置文件。
 
-```js
+```json5
 {
   name: 'SurgeV3.conf',
   template: 'surge_v3',
@@ -33,6 +33,23 @@ Surgio 会根据 Artifact 的值来生成配置文件。你可以一次性配置
 
 模板名。会在 `./template` 目录内寻找同名文件（`.tpl` 后缀可省略）。
 
+### templateType
+
+- 类型: `string`
+- 默认值: `default`
+- 有效值: `default`, `json`
+- <Badge text="可选" vertical="middle" />
+
+模板类型。默认为 `default`，即以传统方式解析模板文件。
+
+### extendTemplate
+
+- 类型: `function`
+- 默认值: `undefined`
+- <Badge text="可选" vertical="middle" />
+
+拓展 JSON 类型的模板，在编写 sing-box 规则时会用到。
+
 ### provider
 
 - 类型: `string`
@@ -81,7 +98,7 @@ Surgio 会根据 Artifact 的值来生成配置文件。你可以一次性配置
 
 例如：
 
-```js
+```json5
 {
   customParams: {
     beta: true,

docs/guide/custom-provider.md

@@ -45,12 +45,12 @@ module.exports = defineCustomProvider(async function () {
 
 ## 订阅类型
 
-目前 Surgio 支持两种 Provider 类型：
+目前 Surgio 支持以下几种 Provider 类型：
 
 |                       类型                       | 描述                                       | 备注                                                                                                                         |
 | :----------------------------------------------: | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
-| `custom` <Badge text="推荐" vertical="middle" /> | 自己维护的节点                             | 支持 Shadowsocks, Shadowsocksr, Snell, HTTPS, HTTP, Vmess, Socks5, Tuic                                                      |
-| `clash` <Badge text="推荐" vertical="middle" />  | Clash 配置                                 | 支持 Shadowsocks, Shadowsocksr, Snell, HTTPS, HTTP, Vmess, Vless, Hysteria 2, Socks5, Tuic                                   |
+| `custom` <Badge text="推荐" vertical="middle" /> | 自己维护的节点                             | 支持 Shadowsocks, Shadowsocksr, Snell, HTTPS, HTTP, Vmess, Vless, Hysteria 2, Socks5, Tuic, Trojan, Wireguard                    |
+| `clash` <Badge text="推荐" vertical="middle" />  | Clash 配置                                 | 支持 Shadowsocks, Shadowsocksr, Snell, HTTPS, HTTP, Vmess, Vless, Hysteria 2, Socks5, Tuic, Trojan, Wireguard                  |
 |                     `trojan`                     | Trojan 订阅                                | Shadowrocket 支持的 Trojan 订阅格式                                                                                          |
 |           `shadowsocks_json_subscribe`           | 针对 Windows 客户端的 Shadowsocks 订阅地址 | 通常命名为 _gui-config.json_                                                                                                 |
 |             `shadowsocks_subscribe`              | 通用的 Shadowsocks 订阅地址                |                                                                                                                              |
@@ -159,6 +159,7 @@ module.exports = defineCustomProvider({
   tfo: false, // TCP Fast Open
   tls13: false, // TLS 1.3，适用于 v2ray-plugin
   mux: false, // 目前仅 Clash + Shadowsocks + v2ray-plugin 可用
+  multiplex: {}, // 多路复用，可选，见本页面的 `multiplex多路复用` 部分
 }
 ```
 
@@ -228,6 +229,7 @@ module.exports = defineCustomProvider({
       'x-key': 'x-value',
     },
   },
+  multiplex: {}, // 多路复用，可选，见本页面的 `multiplex多路复用` 部分
 }
 ```
 
@@ -251,6 +253,7 @@ module.exports = defineCustomProvider({
       Host: 'www.example.com',
     },
   },
+  multiplex: {}, // 多路复用，可选，见本页面的 `multiplex多路复用` 部分
 }
 ```
 
@@ -271,6 +274,7 @@ module.exports = defineCustomProvider({
   grpcOpts: {
     serviceName: 'example',
   },
+  multiplex: {}, // 多路复用，可选，见本页面的 `multiplex多路复用` 部分
 }
 ```
 
@@ -295,6 +299,47 @@ module.exports = defineCustomProvider({
 }
 ```
 
+#### `network: 'quic'`
+
+```json5
+{
+  nodeName: '🇭🇰HK',
+  type: 'vmess',
+  hostname: 'hk.example.com',
+  method: 'auto',
+  network: 'quic',
+  alterId: '64',
+  port: 8080,
+  tls: true,
+  uuid: '1386f85e-657b-4d6e-9d56-78badb75e1fd',
+  udpRelay: true,
+}
+```
+
+#### `network: 'httpupgrade'`
+
+```json5
+{
+  nodeName: '🇭🇰HK',
+  type: 'vmess',
+  hostname: 'hk.example.com',
+  method: 'auto',
+  network: 'httpupgrade',
+  alterId: '64',
+  port: 8080,
+  tls: false,
+  uuid: '1386f85e-657b-4d6e-9d56-78badb75e1fd',
+  udpRelay: true,
+  httpUpgradeOpts: {
+    path: '/',
+    host: 'www.example.com',
+    headers: {
+      'x-key': 'x-value',
+    }
+  },
+}
+```
+
 ### Vless
 
 Vless 节点遵循和 Vmess 类似的配置规则，除了以下几个差异：
@@ -347,6 +392,10 @@ Vless 节点遵循和 Vmess 类似的配置规则，除了以下几个差异：
   username: 'username',
   password: 'password',
   tls13: false, // TLS 1.3
+  path: '/', // 可选
+  headers: { // 可选
+    'x-key': 'x-value',
+  },
 }
 ```
 
@@ -360,6 +409,10 @@ Vless 节点遵循和 Vmess 类似的配置规则，除了以下几个差异：
   port: 8080,
   username: 'username',
   password: 'password',
+  path: '/', // 可选
+  headers: { // 可选
+    'x-key': 'x-value',
+  },
 }
 ```
 
@@ -380,6 +433,7 @@ Vless 节点遵循和 Vmess 类似的配置规则，除了以下几个差异：
   network: 'ws', // 可不填
   wsPath: '/', // 可选
   wsHeaders: {}, // 可选
+  multiplex: {}, // 多路复用，可选，见本页面的 `multiplex多路复用` 部分
 }
 ```
 
@@ -1064,3 +1118,24 @@ module.exports = defineClashProvider({
   }
 })
 ```
+
+## Multiplex 多路复用
+
+- sing-box 的多路复用说明：[链接](https://sing-box.sagernet.org/configuration/shared/multiplex/)
+- mihomo 的多路复用说明：[链接](https://wiki.metacubex.one/config/proxies/sing-mux/)
+
+```json5
+{
+  multiplex: {
+    protocol: '', // smux, yamux, h2mux
+    maxConnections: 1, // 最大连接数量，与 max_streams 冲突
+    minStreams: 1, // 在打开新连接之前，连接中的最小多路复用流数量，与 max_streams 冲突
+    maxStreams: 1, // 在打开新连接之前，连接中的最大多路复用流数量，与 max_connections 和 min_streams 冲突
+    padding: false, // 启用填充
+    brutal: { // 可选，TCP Brutal 拥塞控制算法
+      upMbps: 0, // 上行 Mbps
+      downMbps: 0, // 下行 Mbps
+    },
+  }
+}
+```