Sing2

Sing2

Sing2 re-implements XrayR (a multi-tenant proxy billing backend) on a single sing-box fork core, dropping xray-core entirely, and wires the base's built-in Mieru and TrustTunnel inbounds into its translation layer. It keeps XrayR's business value — panel sync, per-user rate/device/online limits, audit, traffic accounting, access-log reporting, cert automation, hot reload — but swaps the engine.

The base is github.com/silentdspeedup/sing-box-extended, used via a replace of github.com/sagernet/sing-box. See Base fork for what that fork is and why it exists.

Panels

Sing2 serves two SSpanel-family panels with one binary. Which one a node talks to is declared in config.yml, never sniffed from the response:

Nodes:
  - PanelType: SSpanel      # traditional SSpanel: the 6-segment `server` string
    ApiConfig:
      ApiHost: http://panel.example.com
      ApiKey: your-mu-key
      NodeID: 1
      NodeType: V2ray
  - PanelType: Rigel      # Rigel: custom_config (flat XrayR, or a sing-box
    ApiConfig:              # inbound body passed through natively)
      ...

PanelType is required per node and picking the wrong one means the node will not start — each parser rejects the other's payload. The panel response's version key is still read, but only to log a warning naming the value to switch to; it never decides anything.

Protocols: VLESS (incl. Vision + REALITY), VMess, Trojan, Shadowsocks, AnyTLS, Hysteria2, TUIC, Mieru, TrustTunnel.

Install and run

Release archives ship the binary plus config.yml, Sing2.service, this README and LICENSE. The Sing2-script installer wires up /etc/Sing2, the systemd unit and logrotate for you.

sing2 serve -c /etc/Sing2/config.yml   # production entry point; hot-reloads on change
sing2 version
sing2 x25519                           # generate a REALITY key pair

-c defaults to /etc/Sing2/config.yml, so sing2 serve alone works on an installed host. Every configuration field is documented inline in the shipped config.yml; the full contract is doc/09-config-and-migration.md.

sing2 run also exists. It is a single-user smoke harness — a bare VLESS inbound driven entirely by flags, with no panel, no billing and no limits. It does not read config.yml. Do not use it to run a node.

Build

Requires Go 1.26.4+ (the base fork's go.mod declares go 1.26.4; the toolchain auto-downloads if your local Go is older).

make build      # -> ./sing2, with the locked build-tag set
make test vet   # unit tests + go vet
make test-race  # race detector (needs cgo + a C toolchain)
make lint fmt   # golangci-lint + gofmt/goimports

The locked build-tag set is:

with_utls with_quic with_acme with_trusttunnel

Always pass all four. The base's reaction to a missing tag is to register an erroring stub, not to fail compilation — so a dropped tag builds and tests clean, and only shows up as a node that will not start in production. Without with_acme every CertMode: http/dns/tls node fails; without with_trusttunnel every TrustTunnel node fails. core/singbox/buildtags_test.go guards this in both directions. with_clash_api is intentionally not required — Sing2's billing tracker mounts via Router.AppendTracker independently of the clash/v2ray api.

Status

Implemented and running; the plan under doc/ is kept in sync with the code, and doc/07-feature-parity-matrix.md is the acceptance baseline.

Verified under real traffic: Mieru, and VLESS + Vision + REALITY (Clash Verge and Shadowrocket). The billing-accuracy gates run in make test and are byte-exact.

Still awaiting manual verification: the remaining cross-client interop matrix (TrustTunnel / Hysteria2 / TUIC / AnyTLS), the port-offset live path, and real ACME DNS-01 issuance.

Xray-core clients (v2rayN / v2rayNG) are not supported — that requirement was dropped, not deferred.

Maintained dependency forks

go.mod pins github.com/silentdspeedup/sing-box-extended, which is shtorm-7/sing-box-extended plus one patch Sing2 cannot do without: six of the base's inbounds identified users by their array index in the config, which is fine for a static file but misattributes traffic, breaks bans and can panic under the live UpdateUsers that Sing2 does on every panel sync. The fork keys those services on the user's name instead. Rebasing that patch is part of every base upgrade (doc/08 R18).

VMess also pins github.com/silentdspeedup/sing-vmess v0.2.8-extended-1.0.0-sing2.3, which carries three patches.

Upstream's bad timestamp and replay authentication returns leaked an RWMutex read lock; the next panel user update then waited forever and eventually stopped new VMess handshakes (doc/08 R19).

Upstream also never removed a connection from the service's live-connection map unless it had been handed to the router — so every post-authentication error and every finished mux session left a dead entry behind, and VLESS leaked on every connection because the tracking closure compared against a variable that had been reassigned since. That map is what UpdateUsers closes to disconnect a removed user, and its removal path is a linear scan under the service write lock, so the entries made both the scan and the lock hold time grow for the life of the process (doc/08 R20).

Finally, NewConnection read the user tables outside the lock while UpdateUsers replaces them wholesale — which Sing2 does every panel sync. One of the two reads was at the very top of the function, so every VMess handshake on every node raced it, legacy users or not (doc/08 R21).

All three are guarded by behavioral regression tests in this repository, because a patch dropped during a rebase produces no other signal.

Day-to-day builds trust only the tag pinned in go.mod; fork upgrades go through an isolated PR (go.mod/go.sum only) that must pass CI before merge. See doc/08-risks-and-maintenance.md.

License

SPDX-License-Identifier: GPL-3.0-or-later

Sing2 is a derivative work of a sing-box fork and links GPL-3.0 protocol engines built into that base (Mieru via enfein/mieru/v3, TrustTunnel). The whole binary is therefore distributed under GPL-3.0-or-later; the full text is in LICENSE.

The base fork is itself GPL-3.0 (sing-box upstream). Some linked libraries (the sagernet/sing family, redirected to shtorm-7 forks) and the ported XrayR logic (billing/limiter, billing/rule, billing/accesslog) were MPL-2.0 upstream and are redistributed under GPL as part of the whole, retaining their upstream per-file headers (see NOTICE).

Complete corresponding source (this repository plus the exact dependency fork commits pinned in go.mod/go.sum) accompanies any binary distribution, satisfying GPLv3 §6. Third-party components and their licenses are listed in THIRD_PARTY_LICENSES.md; both files are in the source archive attached to every release.