Skip to content
English下载

代理 ​

每个 [[proxy]] 条目就是一台你自己运营或有权使用的服务器。规则、代理组、global-proxy 和 dialer-proxy 都通过 name 引用它。Specola 不自带任何代理;内置出站 DIRECT 和 REJECT 始终存在,不需要声明。

toml
[[proxy]]
name = "office"
type = "http"
server = "proxy.example.org"
port = 8080

给新代理写规则之前,先单独测试它:设置 route-mode = "global"、global-proxy = "office"。 如果 Global 模式都不通,问题出在代理本身,而不是规则。

条目怎么写 ​

  • 代理的所有字段都写在它的 [[proxy]] 表里。嵌套的表(tls、tls.reality、transport、headers) 必须写成一行的内联表:tls = { server-name = "proxy.example.org" }。写成 [proxy.tls] 这样的子表头会报错 <path> must be an inline table。
  • [[proxy]] 是宽松的:Specola 不认识的字段会被直接忽略,没有任何提示。 比如把字段拼成 skip-cert-verfy 或 udp-over-relay,只会悄悄不生效。字段名请从本页复制。
  • 认识的字段如果类型不对(该写字符串的地方写了数字),会在日志里给出告警并忽略这个值; 下文表格注明「整个配置被拒绝」的情况除外。
  • 字段名区分大小写,alterId、udp_over_relay 必须原样书写。

通用字段 ​

字段必填取值
name是唯一的名称,见名称
type是下面的类型之一
server是主机名或 IP 地址,最长 255 个字符
port是整数 1–65535
dialer-proxy否先经过哪个代理或代理组再连本代理,见代理链。必须用连字符,dialer_proxy 会报错
tls否内联表,见 TLS
transport否内联表,只有 VMess 和 VLESS 使用,见传输层

名称 ​

  • 名称在所有代理和代理组之间唯一。
  • 不能是 DIRECT 或 REJECT,不能包含逗号或 ::,不能为空或全是空格。:: 留给 Specola 内部使用。
  • 引用名称时区分大小写:指向 Office 的规则找不到名为 office 的代理。

类型 ​

type协议必填字段TLSUDP
httpHTTP 代理(CONNECT)—可选,可用 Reality不支持
socks5SOCKS5—可选,可用 Reality需 udp = true
ss 或 shadowsocksShadowsockscipher、password不允许支持
vmessVMess(AEAD)uuid可选需 udp = true
vlessVLESSuuid可选,可用 Reality支持,Vision 除外
trojanTrojanpassword始终开启支持,udp = false 可关闭
anytlsAnyTLSpassword始终开启不支持
hysteria2Hysteria 2(QUIC)password始终开启支持
tuicTUIC v5(QUIC)uuid、password始终开启支持

vless、vmess、tuic 也接受大写。其他 type 会报错 Unknown proxy type。ssh、mieru、 sudoku 能被识别,但当前构建没有包含,使用它们的配置会报错 Protocol is not included in the minimal build。

UDP ​

被分流到不支持 UDP 的代理上的 UDP 流量会被丢弃,不会退回 DIRECT。

  • http 和 anytls 从不承载 UDP。
  • socks5 和 vmess 只有写了 udp = true 才承载 UDP(默认 false)。SOCKS5 还需要服务端支持 UDP ASSOCIATE。
  • trojan 默认承载 UDP,udp = false 关闭。
  • ss、vless、hysteria2、tuic 始终承载 UDP,它们没有 udp 字段,写了也不起作用。
  • flow = "xtls-rprx-vision" 的 VLESS 不能承载 UDP;使用 2022-blake3-chacha20-poly1305 的 Shadowsocks 只能走 TCP。

本地 HTTP/SOCKS5 端口只承载 TCP,所以 UDP 只会从增强模式、路由器网关,或经代理发出的 DNS 到达代理。

HTTP ​

toml
[[proxy]]
name = "office"
type = "http"
server = "proxy.example.org"
port = 8080
username = "me"
password = "change-me"
字段默认取值
username、password无以 Proxy-Authorization: Basic 发送
tls关闭加上即为 HTTPS 代理:tls = { server-name = "proxy.example.org" }。可用 Reality,不能写 alpn
path无用这段文本替换 CONNECT 请求行里的 host:port,只用于要求这样做的服务端
headers无额外请求头的内联表,值为字符串
early-datafalse把连接的首批数据和 CONNECT 一起发出,需要服务端支持

SOCKS5 ​

toml
[[proxy]]
name = "lab"
type = "socks5"
server = "proxy.example.org"
port = 1080
username = "me"
password = "change-me"
udp = true
字段默认取值
username、password无用户名/密码认证
udpfalse允许通过 UDP ASSOCIATE 转发 UDP
tls关闭SOCKS5 over TLS。可用 Reality,不能写 alpn
early-datafalse首批数据随请求一起发出,需要服务端支持。值不是布尔时整个配置被拒绝

Shadowsocks ​

toml
[[proxy]]
name = "ss-home"
type = "ss"
server = "proxy.example.org"
port = 8388
cipher = "2022-blake3-aes-128-gcm"
password = "AAAAAAAAAAAAAAAAAAAAAA=="
字段默认取值
cipher必填aes-128-gcm、aes-256-gcm、chacha20-ietf-poly1305、2022-blake3-aes-128-gcm、2022-blake3-aes-256-gcm
password必填2022-* 系列填服务端给出的 base64 密钥:aes-128 为 16 字节,aes-256 为 32 字节
udp_over_relayfalse能写,但不起作用:UDP 始终按 UDP 发送
  • Shadowsocks 不允许配置 tls:任何 TLS 设置都会让整个配置被拒绝。
  • 2022-blake3-chacha20-poly1305 加载时给出告警,TCP 可用,UDP 不可用。
  • 其他加密方式名称加载时只给出告警 cipher '...' may not be supported,但经过该代理的每条连接都会失败。 请把这条告警当作错误处理。
  • 2022 密钥长度不对,加载时不会发现,连接时才失败。

VMess ​

toml
[[proxy]]
name = "vmess-home"
type = "vmess"
server = "proxy.example.org"
port = 443
uuid = "e6e1acfe-5b1e-4b1c-87c8-92beecb98ba2"
udp = true
tls = { server-name = "proxy.example.org" }
transport = { type = "ws", path = "/ws" }
字段默认取值
uuid必填xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 格式,格式不对整个配置被拒绝
alterId0必须为 0。Specola 只支持 AEAD 版 VMess:写正数能加载(带告警),但每条连接都会失败;写负数整个配置被拒绝
cipherautoauto、aes-128-gcm、chacha20-poly1305、none(别名 zero)。auto 在 x86-64 和 ARM64 上为 AES-128-GCM,其他平台为 ChaCha20-Poly1305。未知值按 AES-128-GCM 处理,并在日志里告警
global-paddingfalse布尔
authenticated-lengthfalse布尔
udpfalse允许 UDP
packet-encoding无UDP 封装:packetaddr 或 xudp。其他值告警后忽略
tls关闭可选,可写 alpn
transportraw见传输层

VLESS ​

toml
[[proxy]]
name = "vless-reality"
type = "vless"
server = "proxy.example.org"
port = 443
uuid = "b1479ae4-f64b-4b27-bdab-4fb0f4ecdba9"
flow = "xtls-rprx-vision"
tls = { server-name = "www.example.com", reality = { enabled = true, public-key = "public-key-from-your-server", short-id = "0123456789abcdef" } }
字段默认取值
uuid必填UUID 格式,格式不对整个配置被拒绝
flow"""" 或 xtls-rprx-vision。写其他值能加载,但每条连接都会失败
encryptionnone能写,但不起作用:Specola 发送的 VLESS 始终不加密
tls关闭可选,可写 alpn,可用 Reality
transportraw见传输层

Vision(flow = "xtls-rprx-vision")要求开启 TLS 或 Reality,传输层必须是 raw,并且不承载 UDP。 配了其他传输层或没开 TLS 的 Vision 代理能加载,但连接会失败。

Trojan ​

toml
[[proxy]]
name = "trojan-home"
type = "trojan"
server = "proxy.example.org"
port = 443
password = "change-me"
tls = { server-name = "proxy.example.org" }
字段默认取值
password必填少于 8 个字符时加载会告警
udptruefalse 关闭 UDP
tls始终开启tls.enabled = false 会被忽略并告警。不写 alpn 时提供 h2 和 http/1.1

Trojan 不使用 transport。

AnyTLS ​

toml
[[proxy]]
name = "anytls-home"
type = "anytls"
server = "proxy.example.org"
port = 443
password = "change-me"
tls = { server-name = "proxy.example.org" }
字段默认取值
password必填
tls始终开启不能写 alpn
idle_session_check_interval、idle_session_timeout、min_idle_session—能写,但不起作用

Hysteria2 ​

toml
[[proxy]]
name = "hy2-home"
type = "hysteria2"
server = "proxy.example.org"
port = 443
password = "change-me"
obfs = "salamander"
obfs-password = "change-me-too"
tls = { server-name = "proxy.example.org" }
字段默认取值
password必填
obfs无salamander。写其他值会直接关闭混淆,没有任何提示
obfs-password无Salamander 密钥,只在写了 obfs 时读取
down—能写,但不起作用:Specola 总是告诉服务端接收速率未知
ca—tls.certificate-path 的旧写法;写了就优先于 tls.certificate-path
tls始终开启不能写 alpn,Hysteria2 固定使用 h3

TUIC ​

toml
[[proxy]]
name = "tuic-home"
type = "tuic"
server = "proxy.example.org"
port = 443
uuid = "e6e1acfe-5b1e-4b1c-87c8-92beecb98ba2"
password = "change-me"
congestion-control = "bbr"
tls = { server-name = "proxy.example.org", alpn = ["h3"] }
字段默认取值
uuid必填UUID 格式,格式不对整个配置被拒绝
password必填
tls始终开启可写 alpn。不写 alpn 就不发送 ALPN,大多数 TUIC 服务端要求 alpn = ["h3"]
congestion-controlcubiccubic、new_reno、bbr,其他值告警后忽略
udp-relay-modequicquic(用 QUIC 流转发 UDP)或 native(用 QUIC 数据报)
heartbeat-interval"10s"字符串:毫秒数("10000"),或带 s、m 后缀的数字("10s"、"1m")。其他后缀按毫秒算,但以 m 开头的后缀按分钟算:"500ms" 是 500 分钟,请写 "500"。负数按 10 秒处理
request-timeout10000整数,毫秒;同时也是 QUIC 握手超时。0 表示不超时。写成非整数时会悄悄按 10000 处理
reduce-rttfalse用 0-RTT 恢复之前的会话
fast-openfalse同时打开 reduce-rtt
disable-snifalse不发送 SNI
ip无直接连这个地址,不再解析 server
max-udp-relay-packet-size1200整数,字节;会被限制在 QUIC 包大小范围内
max-open-streams100整数
token无64 个十六进制字符(32 字节),替换由密码派生的认证令牌。格式不对时改用派生令牌,并在日志里告警

TUIC 的每个字段也接受下划线写法(congestion_control),heartbeat 是 heartbeat-interval 的别名。

能写但不生效的字段 ​

下面这些字段加载时不报错,但目前什么也不改变,请不要依赖它们:

类型字段
ssudp_over_relay
vlessencryption
hysteria2down
anytlsidle_session_check_interval、idle_session_timeout、min_idle_session
ss、vless、hysteria2、tuic、http、anytlsudp(这些类型没有这个字段)

顶层的旧版 TLS 字段 ​

旧配置把 TLS 字段直接写在代理里:sni、alpn、skip-cert-verify、certificate、 certificate-path、fingerprint。写在这个位置 Specola 会忽略它们。代理没有 tls 表时 (TUIC 则总是),每个字段都会产生告警 uses legacy field '...'; move it under tls block。 请把它们移进 tls:

toml
# 旧写法(被忽略)
sni = "proxy.example.org"
skip-cert-verify = true

# 新写法
tls = { server-name = "proxy.example.org", skip-cert-verify = true }

唯一仍然有效的顶层 TLS 字段是 Hysteria2 的 ca。

问题在什么时候暴露 ​

有些错误会让配置加载失败;另一些能正常加载,直到有连接用到这个代理时才失败。

加载时被拒绝能加载,连接时失败
缺少 name、type、server 或 port;端口超出范围Shadowsocks 加密方式不在列表里,或 2022 密钥长度不对
未知或不支持的 typeVMess alterId 不是 0
缺少该类型的必填字段VLESS flow 不是 "" 或 xtls-rprx-vision;Vision 配了传输层或没开 TLS
uuid 格式不对(VMess、VLESS、TUIC)alpn 与传输层冲突(见传输层)
名称重复或使用了保留名Reality 配了 raw、grpc 以外的传输层
不支持的 TLS 字段,或给 Shadowsocks 配了 TLS(见 TLS)gRPC multi-mode = true
transport 表缺少 type 或 type 未知(即使是不使用传输层的类型)密码、密钥或证书不对
tls.certificate-path 指向的文件不存在
dialer-proxy 无效(见代理链)

用 --test-config --config <file> 可以在不启动 Core 的情况下查看加载错误和告警(见命令行)。 这里的告警很重要:其中好几条的意思就是「这个代理用不了」。

排错 ​

  1. 先用 Global 测试。 代理在 Global 模式下都不通,就先修代理,别动规则。
  2. 看告警。 字段拼错不会有任何提示;值写错通常会在加载配置时在日志里告警。
  3. UDP 不通(游戏、QUIC、语音):对照 UDP 一节。SOCKS5 和 VMess 需要 udp = true; HTTP 和 AnyTLS 不承载 UDP;Vision 没有 UDP。
  4. TLS 报错:检查 TLS 页面里的 server-name 和证书设置。 skip-cert-verify = true 只能用来排查,不是解决办法。
  5. TUIC 连不上:在 tls 里加上 alpn = ["h3"]。

不要把凭据放进共享仓库、日志或截图。

另见 TLS、传输层、代理组和代理链。