sing-box：通用代理平台

站点结构

本站为独立静态网站，文档与仓库内容分别放在 wiki/ 与 github/ 栏目下。

项目是什么

官方定位一句话：The universal proxy platform（通用代理平台）。文档站自称是 sing-box 项目的 wiki；仓库 README 只指向文档站，不另写长介绍。

两个站点分别做什么

GitHub 仓库

发布轨道

CI 脚本按分支区分包名与 Docker tag：stable → sing-box / latest；带连字符的稳定标签视为 beta → sing-box-beta / latest-beta；testing → sing-box-testing；oldstable → sing-box-oldstable。

仓库主要目录

adapterclientscmd commonconstantdaemon dnsdocsexperimental includelogoption protocolreleaseroute schemaservicetest transport

安装

官方文档把安装分成包管理器仓库、一键脚本、各发行版托管包、Docker、源码编译。文档站根路径 /installation/ 本身 404，实际入口是子页。

官方 APT / DNF 仓库

# Debian / APT
sudo mkdir -p /etc/apt/keyrings &&
sudo curl -fsSL https://sing-box.app/gpg.key -o /etc/apt/keyrings/sagernet.asc &&
sudo chmod a+r /etc/apt/keyrings/sagernet.asc &&
echo 'Types: deb
URIs: https://deb.sagernet.org/
Suites: *
Components: *
Enabled: yes
Signed-By: /etc/apt/keyrings/sagernet.asc' | sudo tee /etc/apt/sources.list.d/sagernet.sources &&
sudo apt-get update &&
sudo apt-get install sing-box   # 或 sing-box-beta

# Red Hat / DNF 5
sudo dnf config-manager addrepo --from-repofile=https://sing-box.app/sing-box.repo
sudo dnf install sing-box

官方安装脚本

从 GitHub Releases 拉取最新 deb/rpm，也支持 Arch Linux 与 OpenWrt：

curl -fsSL https://sing-box.app/install.sh | sh
curl -fsSL https://sing-box.app/install.sh | sh -s -- --beta
curl -fsSL https://sing-box.app/install.sh | sh -s -- --version <version>

各平台托管包

官方点名若干第三方打包改动了默认 build tags，或使用过旧 Go：AOSC、Homebrew、Termux、FreeBSD ports。建议优先用官方仓库或 GitHub Releases。

Docker

docker run -d \
  -v /etc/sing-box:/etc/sing-box/ \
  --name=sing-box \
  --restart=always \
  ghcr.io/sagernet/sing-box \
  -D /var/lib/sing-box \
  -C /etc/sing-box/ run

源码编译

文档写明：sing-box 1.11 需要 Go 1.23.1+；1.10 需要 Go 1.20+。变更日志另写 1.13.0 起至少需要 Go 1.24。简单构建：make 或 make install。自定义：TAGS="tag_a tag_b" make。

默认开启的 build tag 包括 with_quic、with_dhcp、with_wireguard、with_utls、with_acme、with_clash_api、with_gvisor、with_tailscale、with_ccm、with_ocm、with_naive_outbound、with_cloudflared 等。with_grpc、with_v2ray_api、with_embedded_tor 默认关闭。下游打包应直接使用仓库 release/DEFAULT_BUILD_TAGS* 与 release/LDFLAGS。

systemd 服务

来源：Package Manager · Docker · Build from source

图形客户端

由 Project S 维护，目标是统一体验并提供平台能力（例如 TUN）。官方明确：大量自称使用 sing-box 的第三方客户端不会列入文档，认为其动机是拉用户，代码质量差且常带广告。

客户端共性能力

• 本地配置：必须提供编辑器。
• iCloud 配置（iOS/macOS）：文件放在 iCloud 的 sing-box 目录。
• 远程配置：按 URL 更新，默认 60 分钟；支持 HTTP Basic；必须实现导入 URL Scheme：sing-box://import-remote-profile?url=...#name。
• Dashboard：运行时显示内存、连接、流量；配置了多个 clash_mode 时提供模式切换；Selector / URLTest 组可切换节点。
• Core 区：显示内核版本、清理工作目录、内存限制开关。

文档写明：因审核误判，Apple App Store 应用暂时无法更新；TestFlight 用户不受影响。TestFlight 邀请可通过赞助后加入赞助者 Telegram，或向 contact@sagernet.org 发送 Apple ID。

来源：Graphical Clients · Android · Apple · Desktop · General

配置结构

配置文件是 JSON。1.14 起提供 JSON Schema，可在兼容编辑器里补全和校验。文档发布的 schema 用顶层 $schema 选择；sing-box schema 可按当前二进制和 build tags 生成 schema。

{
  "$schema": "https://singbox.ai/wiki/schema.json",
  "log": {},
  "dns": {},
  "ntp": {},
  "certificate": {},
  "certificate_providers": [],
  "http_clients": [],
  "network_namespaces": [],
  "endpoints": [],
  "inbounds": [],
  "outbounds": [],
  "route": {},
  "services": [],
  "experimental": {}
}

来源：Configuration

协议与模块（文档目录）

Inbound（入站）

directmixedsocks httpshadowsocksvmess trojannaivehysteria shadowtlsvlesstuic hysteria2anytlssnell tunredirecttproxy cloudflared

Outbound（出站）

directbridgeblock sockshttpshadowsocks vmesstrojannaive wireguardhysteriashadowtls vlesstuichysteria2 anytlssnelltor sshdnsselector urltest

block / dns 特殊出站以及 WireGuard outbound 已弃用，分别改用路由动作和 Endpoint。旧字段在 1.13.0 移除。

Endpoint

WireGuardTailscale OpenConnect ClientOpenVPN Client OpenVPN Server

Service

sing-box APIDERPResolved SSM APICCMOCM Hysteria RealmUSB/IP ServerUSB/IP Client

DNS Server 类型

LegacyLocalHosts TCPUDPTLS QUICHTTPSHTTP3 DHCPmDNSFakeIP TailscaleOpenConnectOpenVPN Resolved

配置其他章节

• Route：GeoIP / Geosite（已移除，改 Rule Set）、Route Rule、Rule Action、Protocol Sniff。
• Rule Set：源格式、Headless Rule、AdGuard DNS Filter。
• Experimental：Cache File、Clash API、V2Ray API。
• Shared：Listen / Dial、TLS、HTTP Client、HTTP2、QUIC、证书提供者（ACME / Tailscale / Cloudflare Origin CA）、Multiplex、V2Ray Transport、UDP over TCP、TCP Brutal、Wi-Fi State 等。
• Network Namespace：Default、Unshare。

使用方式（手册要点）

客户端手册把图形系统上的代理分成三类：

1. 系统代理：本质是只支持 TCP 的 HTTP 代理。Windows / macOS / GNOME / KDE 原生支持；Android 需要 ROOT 或 adb。很多非 HTTP 的 TCP 客户端不会走系统代理，UDP / ICMP 会泄漏。
2. 防火墙重定向：Windows WFP、Linux redirect / TProxy / eBPF、macOS pf。侵入性强、配置繁琐，在部分开源代理项目中仍常见。
3. 虚拟网卡（TUN）：官方认为这是 L4 代理在 Android / iOS 上作为 VPN 工作的唯一方式。sing-box 继承并发展 Clash Premium 的 TUN inbound，做 L3 到 L4 转换后交给路由器。

手册还提供服务端与客户端示例，以及 Shadowsocks、Trojan、Hysteria 2 等协议说明；杂项包括 TunnelVision 与 AnyTLS client metadata。

来源：Manual / Proxy / Client

版本与变更

采集时（2026-08-22）Release 页最新为 1.14.0-beta.17（测试）与 1.13.19（稳定），均标注 Fixes and improvements。

来源：Change Log · GitHub Releases

已弃用项（摘录）

来源：Deprecated · Migration

支持渠道

来源：Support

许可

GNU GPL v3 或更新版本。附加条款：未经事先同意，衍生作品不得使用该应用名称，也不得暗示与该应用有关联。

Copyright (C) 2022 by nekohasekai <contact-sagernet@sekai.icu>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

官方链接索引