代理
每个 [[proxy]] 条目就是一台你自己运营或有权使用的服务器。规则、代理组、global-proxy 和 dialer-proxy 都通过 name 引用它。Specola 不自带任何代理;内置出站 DIRECT 和 REJECT 始终存在,不需要声明。
[[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 | 协议 | 必填字段 | TLS | UDP |
|---|---|---|---|---|
http | HTTP 代理(CONNECT) | — | 可选,可用 Reality | 不支持 |
socks5 | SOCKS5 | — | 可选,可用 Reality | 需 udp = true |
ss 或 shadowsocks | Shadowsocks | cipher、password | 不允许 | 支持 |
vmess | VMess(AEAD) | uuid | 可选 | 需 udp = true |
vless | VLESS | uuid | 可选,可用 Reality | 支持,Vision 除外 |
trojan | Trojan | password | 始终开启 | 支持,udp = false 可关闭 |
anytls | AnyTLS | password | 始终开启 | 不支持 |
hysteria2 | Hysteria 2(QUIC) | password | 始终开启 | 支持 |
tuic | TUIC 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
[[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-data | false | 把连接的首批数据和 CONNECT 一起发出,需要服务端支持 |
SOCKS5
[[proxy]]
name = "lab"
type = "socks5"
server = "proxy.example.org"
port = 1080
username = "me"
password = "change-me"
udp = true| 字段 | 默认 | 取值 |
|---|---|---|
username、password | 无 | 用户名/密码认证 |
udp | false | 允许通过 UDP ASSOCIATE 转发 UDP |
tls | 关闭 | SOCKS5 over TLS。可用 Reality,不能写 alpn |
early-data | false | 首批数据随请求一起发出,需要服务端支持。值不是布尔时整个配置被拒绝 |
Shadowsocks
[[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_relay | false | 能写,但不起作用:UDP 始终按 UDP 发送 |
- Shadowsocks 不允许配置
tls:任何 TLS 设置都会让整个配置被拒绝。 2022-blake3-chacha20-poly1305加载时给出告警,TCP 可用,UDP 不可用。- 其他加密方式名称加载时只给出告警
cipher '...' may not be supported,但经过该代理的每条连接都会失败。 请把这条告警当作错误处理。 - 2022 密钥长度不对,加载时不会发现,连接时才失败。
VMess
[[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 格式,格式不对整个配置被拒绝 |
alterId | 0 | 必须为 0。Specola 只支持 AEAD 版 VMess:写正数能加载(带告警),但每条连接都会失败;写负数整个配置被拒绝 |
cipher | auto | auto、aes-128-gcm、chacha20-poly1305、none(别名 zero)。auto 在 x86-64 和 ARM64 上为 AES-128-GCM,其他平台为 ChaCha20-Poly1305。未知值按 AES-128-GCM 处理,并在日志里告警 |
global-padding | false | 布尔 |
authenticated-length | false | 布尔 |
udp | false | 允许 UDP |
packet-encoding | 无 | UDP 封装:packetaddr 或 xudp。其他值告警后忽略 |
tls | 关闭 | 可选,可写 alpn |
transport | raw | 见传输层 |
VLESS
[[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。写其他值能加载,但每条连接都会失败 |
encryption | none | 能写,但不起作用:Specola 发送的 VLESS 始终不加密 |
tls | 关闭 | 可选,可写 alpn,可用 Reality |
transport | raw | 见传输层 |
Vision(flow = "xtls-rprx-vision")要求开启 TLS 或 Reality,传输层必须是 raw,并且不承载 UDP。 配了其他传输层或没开 TLS 的 Vision 代理能加载,但连接会失败。
Trojan
[[proxy]]
name = "trojan-home"
type = "trojan"
server = "proxy.example.org"
port = 443
password = "change-me"
tls = { server-name = "proxy.example.org" }| 字段 | 默认 | 取值 |
|---|---|---|
password | 必填 | 少于 8 个字符时加载会告警 |
udp | true | false 关闭 UDP |
tls | 始终开启 | tls.enabled = false 会被忽略并告警。不写 alpn 时提供 h2 和 http/1.1 |
Trojan 不使用 transport。
AnyTLS
[[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
[[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
[[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-control | cubic | cubic、new_reno、bbr,其他值告警后忽略 |
udp-relay-mode | quic | quic(用 QUIC 流转发 UDP)或 native(用 QUIC 数据报) |
heartbeat-interval | "10s" | 字符串:毫秒数("10000"),或带 s、m 后缀的数字("10s"、"1m")。其他后缀按毫秒算,但以 m 开头的后缀按分钟算:"500ms" 是 500 分钟,请写 "500"。负数按 10 秒处理 |
request-timeout | 10000 | 整数,毫秒;同时也是 QUIC 握手超时。0 表示不超时。写成非整数时会悄悄按 10000 处理 |
reduce-rtt | false | 用 0-RTT 恢复之前的会话 |
fast-open | false | 同时打开 reduce-rtt |
disable-sni | false | 不发送 SNI |
ip | 无 | 直接连这个地址,不再解析 server |
max-udp-relay-packet-size | 1200 | 整数,字节;会被限制在 QUIC 包大小范围内 |
max-open-streams | 100 | 整数 |
token | 无 | 64 个十六进制字符(32 字节),替换由密码派生的认证令牌。格式不对时改用派生令牌,并在日志里告警 |
TUIC 的每个字段也接受下划线写法(congestion_control),heartbeat 是 heartbeat-interval 的别名。
能写但不生效的字段
下面这些字段加载时不报错,但目前什么也不改变,请不要依赖它们:
| 类型 | 字段 |
|---|---|
ss | udp_over_relay |
vless | encryption |
hysteria2 | down |
anytls | idle_session_check_interval、idle_session_timeout、min_idle_session |
ss、vless、hysteria2、tuic、http、anytls | udp(这些类型没有这个字段) |
顶层的旧版 TLS 字段
旧配置把 TLS 字段直接写在代理里:sni、alpn、skip-cert-verify、certificate、 certificate-path、fingerprint。写在这个位置 Specola 会忽略它们。代理没有 tls 表时 (TUIC 则总是),每个字段都会产生告警 uses legacy field '...'; move it under tls block。 请把它们移进 tls:
# 旧写法(被忽略)
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 密钥长度不对 |
未知或不支持的 type | VMess 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 的情况下查看加载错误和告警(见命令行)。 这里的告警很重要:其中好几条的意思就是「这个代理用不了」。
排错
- 先用 Global 测试。 代理在 Global 模式下都不通,就先修代理,别动规则。
- 看告警。 字段拼错不会有任何提示;值写错通常会在加载配置时在日志里告警。
- UDP 不通(游戏、QUIC、语音):对照 UDP 一节。SOCKS5 和 VMess 需要
udp = true; HTTP 和 AnyTLS 不承载 UDP;Vision 没有 UDP。 - TLS 报错:检查 TLS 页面里的
server-name和证书设置。skip-cert-verify = true只能用来排查,不是解决办法。 - TUIC 连不上:在
tls里加上alpn = ["h3"]。
不要把凭据放进共享仓库、日志或截图。
