Skip to content
English下载

快速开始 ​

本页带你从零得到一份能用的 Profile:

  1. 写一份小 Profile:一个本地端口、一个节点、几条规则和 FINAL。
  2. 校验它。
  3. 在 Specola 应用里激活它。
  4. 让浏览器、某个工具或整个系统使用本地端口。
  5. 可选:开启增强模式,让无视代理设置的程序也按规则分流。

下面这份 Profile 不依赖任何额外文件,在 Windows、macOS、Linux 上原样都能加载。

入门 Profile ​

toml
[general]
route-mode = "rule"
port = 7890
protocols = "mixed"

[[proxy]]
name = "work"
type = "socks5"
server = "proxy.example.org"
port = 1080
username = "me"
password = "change-me"

[route]
rules = [
  # Private networks stay direct
  "IP-CIDR,10.0.0.0/8,DIRECT",
  "IP-CIDR,172.16.0.0/12,DIRECT",
  "IP-CIDR,192.168.0.0/16,DIRECT",
  # These sites go through the proxy
  "DOMAIN-SUFFIX,github.com,work",
  "DOMAIN-SUFFIX,githubusercontent.com,work",
  # These programs go through the proxy, on every platform (Windows adds .exe)
  "PROCESS-NAME-REGEX,^(git|git-remote-https?|curl|cargo|node)(\\.exe)?$,work",
  # Everything else goes direct
  "FINAL,DIRECT",
]

把服务器地址、端口和账号换成你自己运营或有权使用的 SOCKS5 服务器。Shadowsocks、VMess、VLESS、Trojan、 Hysteria2 等其他类型见代理。

各部分的含义:

部分含义
route-mode = "rule"按规则决定每条连接。global 把所有流量交给 global-proxy,direct 全部直连。
port = 7890、protocols = "mixed"在 127.0.0.1:7890 开一个本地端口,同时接受 HTTP 和 SOCKS5。
[[proxy]]一个上游节点,名字叫 work。规则按这个名字引用它,大小写必须一致。
rules从上往下检查,第一条命中的规则说了算。列表必须以 FINAL 结尾。

进程规则按可执行文件名匹配程序。模式结尾写 (\.exe)?,是因为 Windows 报告的是 git.exe,macOS 和 Linux 报告的是 git;而 Git for Windows 的 HTTPS 连接来自 git-remote-https.exe。自己写进程规则之前请先读 进程规则:写成你的平台不会报告的名字,规则就永远不会命中,而且没有任何提示。

每个 [[proxy]] 都必须有 name、type、server 和 port。节点里的嵌套设置(例如 tls)必须写成 内联表:tls = { server-name = "proxy.example.org" }。

Profile 放在哪里 ​

把文件以 .toml 为扩展名保存到 Profiles 目录。应用会列出这个目录里的所有 .toml 文件,Core 也按文件名 在这里查找 Profile。

平台Profiles 目录
Windows%LOCALAPPDATA%\Specola\profiles\
macOS~/Library/Application Support/com.specola.Specola/profiles/
Linux$XDG_CONFIG_HOME/specola/profiles/,通常是 ~/.config/specola/profiles/

文件也可以放在别处,再用应用里的 Import file(导入文件)复制进 Profiles 目录。导入不会覆盖同名的 Profile。

Specola 可能会在 Profile 旁边放两个小文件:<名字>.toml.modules(这个 Profile 应用的模块) 和 <名字>.toml.disabled-rules(你在应用里关掉的规则)。手动复制或改名 Profile 时,请把它们一起带上。

校验 Profile ​

Core 可以只检查 Profile 而不启动任何东西,不需要管理员权限。

bash
# Windows (in the Specola installation folder)
specola-service.exe --test-config --config my.toml

# macOS and Linux
specola-core --test-config --config my.toml

-t 是 --test-config 的简写。相对路径先在 Profiles 目录里找,再到 Core 可执行文件所在目录找,不会 在当前目录找。别处的文件请写绝对路径。

结果要么是 Config validation passed: <路径>,要么是 Config validation failed: 加上具体问题。校验还会 检查 Profile 引用的文件(GeoIP 数据、规则集文件),并下载远程文件,所以这里通过的 Profile 在应用里也能加载。

常见错误:

提示解决办法
Unknown general field 'mixed-port'改写成 port
Use general.port and general.api-listenport / protocols 和 api-listen 要写在 [general] 里
inbound.type contains unsupported value '...'protocols 只接受 mixed、socks5(socks)、http、none,或它们组成的数组
Unsupported top-level field '...'顶层只允许 general、proxy、proxy-group、route、dns、sniffer、enhanced-mode
Rule list requires an explicit FINAL target在 [route].rules 末尾加上 "FINAL,<出站>"
FINAL must be the last rule把 FINAL 挪到最后
Rule references unknown outbound: XX 必须是 DIRECT、REJECT、某个节点或代理组,大小写一致
Global mode requires an existing proxy target把 global-proxy 设为已存在的节点或代理组
GEOIP rule requires a geoip resource设置 [route] geoip,见分流规则
enhanced-mode.backend=tun is not supported on Linux; use ebpf or disable enhanced modeLinux 上去掉 backend,或写 ebpf
Unknown enhanced-mode field: type字段名是 backend

Ignoring configuration field 'metadata' in the minimal build 这类是告警,不是错误:Core 丢弃该段,照常加载其余部分。

在应用里激活 ​

macOS 首次打开

macOS 版 Specola 没有经过 Apple 公证,第一次打开时系统会提示无法验证开发者。打开 系统设置 → 隐私与安全性, 滚动到下方,在关于 Specola 的提示旁点 仍要打开,再确认一次即可。每个版本只需要这样做一次。也可以在终端里 清除下载标记:

bash
xattr -dr com.apple.quarantine /Applications/specola-qml.app

更新版本后,macOS 可能会重新询问之前授予过的权限,例如本地网络。

  1. 打开 Specola,进入 Profiles 页。
  2. 列表里没有这个 Profile 时,点 Import file,或直接把 .toml 文件拖到页面上。
  3. 选中它,点 Use this profile(使用此 Profile)。

Core 随即加载。Profile 有错时,应用会显示 Core 给出的原因,之前在运行的 Profile 保持不变。以后手动编辑了文件, 再激活一次即可:Core 就地应用改动,不需要重启(见重新加载时保留什么)。

不用应用时,也可以直接带着 Profile 启动 Core:

bash
specola-core --config my.toml            # macOS, Linux
specola-service.exe --config my.toml     # Windows, from a terminal

按 Ctrl+C 停止。一台电脑上只能运行一个 Core,第二个会以 Another specola-core process is already running 退出;在 Windows 上,已安装的 specola-service 服务也算一个。

让流量走本地端口 ​

Core 只在 127.0.0.1:7890 上监听,从不修改操作系统的代理设置。应用里的 System proxy(系统代理)开关 只是启动和停止这个本地端口,并不会让 Windows、macOS 或 Linux 使用它。程序要走这个端口,需要你自己设置。

单个命令或工具 ​

bash
curl -x http://127.0.0.1:7890 -I https://github.com
curl -x socks5h://127.0.0.1:7890 -I https://github.com

很多命令行工具会读取代理环境变量:

bash
# macOS, Linux
export http_proxy=http://127.0.0.1:7890 https_proxy=http://127.0.0.1:7890 all_proxy=socks5h://127.0.0.1:7890
powershell
# Windows PowerShell, current window only
$env:HTTP_PROXY = "http://127.0.0.1:7890"; $env:HTTPS_PROXY = "http://127.0.0.1:7890"

Git 有自己的设置:git config --global http.proxy http://127.0.0.1:7890。

整个系统 ​

在系统设置里把 HTTP 代理设为 127.0.0.1、端口 7890。大多数浏览器和很多应用会跟随这个设置。

平台位置
Windows 11设置 > 网络和 Internet > 代理 > 手动设置代理:打开使用代理服务器,地址 127.0.0.1,端口 7890
macOS系统设置 > 网络 > 当前网络 > 详细信息 > 代理:网页代理(HTTP)和安全网页代理(HTTPS),127.0.0.1 端口 7890
Linux(GNOME)设置 > 网络 > 网络代理 > 手动:HTTP 和 HTTPS 代理 127.0.0.1 端口 7890

Firefox 可以不跟随系统,使用自己的代理设置(设置 > 网络设置)。

Core 没有运行时,记得把系统代理关掉,否则跟随它的程序都连不上网。

确认生效 ​

打开应用的 Connections(连接)页。每条连接都会显示命中的规则、使用的节点,本机程序还会显示进程名。 访问 github.com 的连接应显示 DOMAIN-SUFFIX 和 work,其他大多数网站显示 FINAL 和 DIRECT。

一条连接都没有,说明程序没有走这个端口。连接节点失败时,单独测试节点:设置 route-mode = "global" 和 global-proxy = "work",激活后再试。

开启增强模式 ​

本地端口只看得到使用它的程序。增强模式能接管无视代理设置的程序的流量,进程规则也能看到所有程序。 在 Profile 里加上:

toml
[enhanced-mode]
enable = true

不要写 backend:Core 在 Windows 和 macOS 上用 tun,在 Linux 上用 ebpf,同一份文件到处可用。 增强模式需要管理员权限,运行期间会改动系统的路由和 DNS。port 要保持大于 0,Linux eBPF 会把接管的连接交给本地端口。

平台怎么运行
Windows安装版应用把 Core 作为 specola-service 服务运行,它具备 TUN 所需的权限。激活 Profile,或用托盘、概览页上的 Enhanced mode(增强模式)开关即可。如果 Core 是以别的方式、且没有管理员权限启动的,应用会提示 Administrator rights required。在终端里手动运行时,请使用管理员终端。
macOSTUN 需要 root。应用启动的 Core 不是 root,此时打开增强模式会失败,提示 TUN requires administrator privileges。请改为带着 Profile 启动 Core:sudo specola-core --config my.toml,应用会连接到这个正在运行的 Core。不加 sudo 启动时,如果启动 Profile 需要 TUN,正式版会弹窗要求输入管理员密码。
LinuxeBPF 需要 root,以及 Linux 5.17 以上、cgroup v2 和 BTF。带着 Profile 启动 Core:sudo specola-core --config my.toml。不加 sudo 启动时,如果启动 Profile 需要 eBPF,正式版会通过 polkit 请求授权。

在 sudo 下,相对的 --config 路径仍在你自己的 Profiles 目录里查找,Core 也继续使用你自己的数据目录。

应用里的开关只改变正在运行的 Core;Profile 文件里的 [enhanced-mode] enable 不变,再次激活 Profile 时会按文件里的值生效。

真正依赖增强模式之前,请先读增强模式,再读 TUN 或 Linux eBPF。 尤其在 Linux 上,哪些连接能到达 Core 是由 eBPF 在内核里决定的,目标在私有网段的连接永远不会被接管。

下一步 ​

加一个代理组 ​

代理组从成员里挑一个使用。url-test 用最快的成员,fallback 用第一个可用的成员:

toml
[[proxy]]
name = "work-2"
type = "socks5"
server = "proxy2.example.org"
port = 1080

[[proxy-group]]
name = "auto"
type = "url-test"
proxies = ["work", "work-2"]
url = "https://www.gstatic.com/generate_204"
interval = 300

不写 interval,代理组就从不测试成员。把域名规则指向代理组:"DOMAIN-SUFFIX,github.com,auto"。 详见代理组。

如果你依赖故障切换,进程规则最好指向节点而不是代理组。在 Linux eBPF 下,指向代理组的进程规则第一次命中时会 选定一个成员并一直使用,直到 Profile 重新加载:对这条规则来说,url-test 不会切换,fallback 也不会切走。 见成员固定。

继续阅读 ​

  • 工作原理:一条连接一步步经历了什么。
  • 分流规则:所有规则类型、规则集、GeoIP 与 GeoSite。
  • DNS:增强模式如何应答 DNS。
  • 模块:把共用的改动放进一个文件,应用到多个 Profile。