DOCSEARCHbyAlgolia
Submit Docs

Surgio

website·Indexed 29 days ago

https://surgio.js.org/

A one-stop proxy rule generator that uses a single set of Providers and templates to generate configurations for clients including Surge, Clash, Quantumult X, and sing-box. It supports Nunjucks-based templates, custom providers, and automated management via GitLab, Docker, Netlify, or Cloudflare Workers. Version 4 transitions configuration repositories into native TypeScript ESM projects.

Tokens
31.1K
Snippets
173
Records
233
Agent score
63%

What's inside Surgio

  1. Overview of Surgio and its core functionality

    Surgio is a tool designed to automate the creation and management of proxy client configurations. It solves the problem of maintaining multiple different configuration files across various platforms (desktop and mobile) and multiple proxy providers ('airports').

    It works in two primary stages:

    1. Parsing: It parses subscription addresses from proxy providers or reads user-maintained node lists.
    2. Generation: It uses templates to generate specific rule sets and configurations for different proxy clients.

    Additionally, Surgio includes a utility to upload generated configurations to object storage (Aliyun OSS, Cloudflare R2, and other S3-compatible services) to easily implement subscription functionality.

  2. Upgrade Surgio to v4 (General Overview)

    Surgio v4 transitions configuration repositories into native TypeScript ESM Projects, allowing the local CLI, Node Gateway, and Cloudflare Worker to share a single configuration. Because entry points, Provider loading, and caching have changed, upgrading is treated as a migration rather than a simple version bump. v4 is currently in beta; users must explicitly use the @beta tag for both surgio and @surgio/gateway.

  3. Understand Surgio core terminology

    Surgio uses three primary concepts to generate configuration files:

    • Provider: The source of nodes, which can be a subscription URL or a set of node configurations.
    • Template: The blueprint used by Surgio to render the final files.
    • Artifact: The final generated rule/product.

    Relationship: Surgio uses the Artifact definition to take nodes from a Provider and render them via a Template into a usable configuration.

  4. Create a server entry point for Surgio Gateway

    To run the Gateway in a Docker container, create a server.ts file in the root directory. The startServer function must be configured to listen on 0.0.0.0 (instead of the default 127.0.0.1) to be accessible from outside the container.
    import { startServer } from '@surgio/gateway/node'

await startServer({
  hostname: '0.0.0.0',
  port: Number(process.env.PORT) || 3000,
})

  5. Implement reusable rule snippets using Nunjucks macros

    Snippets are implemented using Nunjucks macros. Define a macro in a .tpl file and import it into your main template to generate rules with dynamic policy names.
    {# In ./snippet/blocked_rules.tpl #}
{% macro main(rule) %}
DOMAIN-KEYWORD,bitly,{{ rule }}
DOMAIN-SUFFIX,youtu.be,{{ rule }}
{% endmacro %}

{# In main template #}
{% import './snippet/blocked_rules.tpl' as blocked_rules %}
{{ blocked_rules.main('🚀 Proxy') }}

  7. Verify Surfboard mobile version requirements for protocol capabilities

    When configuring Surgio for Surfboard, ensure the target mobile client version meets the minimum requirement for the specific protocol capability being used. Surgio documents these version floors for configuration purposes but does not implement client-version negotiation.
    CapabilityMobile version
    WireGuard2.22.0
    WireGuard preshared key / keepalive2.23.2 / 2.25.2
    SS2022 AES and Hysteria22.26.0
    AnyTLS2.27.0
    Snell / SS2022 identity passwords2.28.0 / 2.28.1
    WireGuard IPv62.29.1
    Underlying proxy2.30.0
    Certificate pinning, block-quic, Snell v42.31.1
    Hysteria2 Salamander2.32.2
    AnyTLS UDP and UDP proxy chaining2.32.4
    TUIC v52.33.0
    Gecko, VMess encrypt-method, IPv6 WireGuard endpoint fix2.34.4

  8. Manage and clean Surgio Redis cache data

    Surgio prefixes all Redis keys with surgio:. The expiration time for these keys is determined by the cache TTL, and Redis handles the cleanup automatically. To manually clear the cache, use the surgio clean-cache command, which only deletes keys with the surgio: prefix, leaving other data in the same database intact.

  9. Create a dynamic Provider using asynchronous functions

    Surgio supports asynchronous functions for Providers to allow for customized or dynamic node fetching. You can use defineCustomProvider and return an object containing the nodeList.
    const { defineCustomProvider } = require('surgio')

module.exports = defineCustomProvider(async function () {
  const myNodeList = await someAsyncFunction()

  return {
    nodeList: myNodeList,
  }
})

  10. Configure Hysteria2 and TUIC v5 proxies in Surfboard

    Specific configuration requirements for Hysteria2 and TUIC v5:

    • Hysteria2 Bandwidth: download-bandwidth is measured in Mbps.
    • Hysteria2 Port Hopping: Use a quoted, semicolon-separated value (e.g., "1234;5000-6000"). The interval is in seconds.
    • Hysteria2 Obfuscation: If both salamander-password and gecko-password are present, Gecko takes precedence.
    • Hysteria2 UDP: Defaults to true.
    • TUIC v5 Defaults: ALPN defaults to h3, hopping interval defaults to 30 seconds, and UDP relay is enabled by default.

  11. TrustTunnel client version requirements

    The following minimum versions are required for TrustTunnel support. Note that Surgio documents these but does not enforce them via target-version settings.
    Surge:
- Basic TrustTunnel: Mac 6.4.4+
- Headers and max-streams: Mac 6.6.0+
- Custom ALPN: Mac 6.7.0+

Stash:
- iOS 3.4.0+ / macOS 4.2.0+

Mihomo:
- Basic TrustTunnel: v1.19.21+
- Connection reuse fields: v1.19.23+
- bbr-profile: v1.19.24+

  12. Migrate UDP relay settings in Providers

    Surgio v2.0.0 introduces stricter type checking and naming for UDP relay settings in Providers:

    1. The udp-relay field must now be a boolean type. String values like "true" or "false" are no longer supported.
    2. For Custom Vmess nodes, the key used to enable UDP forwarding has been renamed from udp to udp-relay.