基础配置
[general] 决定 Core 怎样路由流量、记录哪些日志、在哪里监听。每个字段都可以不写,不写就取默认值; 整个 [general] 都不写也是合法的。
[general]
route-mode = "rule"
global-proxy = ""
log-level = "info"
log-file = true
port = 7890
protocols = "mixed"
allow-lan = false
api-listen = ""字段
| 字段 | 类型 | 默认值 | 取值 |
|---|---|---|---|
route-mode | 字符串 | "rule" | rule、global、direct(小写) |
global-proxy | 字符串 | "" | 节点、代理组、DIRECT 或 REJECT;route-mode = "global" 时必须存在 |
log-level | 字符串 | "info" | trace、debug、info、warn(或 warning)、error、critical、off,不区分大小写 |
log-file | 布尔 | true | false 时不写日志文件 |
port | 整数 | 7890 | 1–65535;0 关闭本地端口 |
protocols | 字符串或数组 | "mixed" | mixed、socks5(别名 socks)、http、none |
allow-lan | 布尔 | false | true 时监听 0.0.0.0,否则监听 127.0.0.1 |
api-listen | 字符串 | "" | IP:端口、localhost:端口 或 [IPv6]:端口;为空表示不开 TCP 控制接口 |
ipv6 | 布尔 | false | 能解析和保存,但 Core 里没有任何模块读取它 |
写了其他字段会报错:Unknown general field '<key>'。旧配置里的 api-secret 会被静默丢弃。
路由模式
| 模式 | 效果 |
|---|---|
rule | 每条连接按 [route].rules 匹配,第一条命中的生效 |
global | 所有连接都走 global-proxy |
direct | 所有连接都直连;节点、代理组和规则照常加载,但不使用 |
[general]
route-mode = "global"
global-proxy = "work" # 节点或代理组
[[proxy]]
name = "work"
type = "socks5"
server = "proxy.example.org"
port = 1080route-mode = "global"而global-proxy为空或不存在时,加载失败:Global mode requires an existing proxy target。其他模式下不检查global-proxy。- 写成
Rule、GLOBAL会报错(Unknown mode),模式必须小写。 - 在界面里切换模式只改正在运行的 Core,不会改文件。重新激活 Profile 时,只有当你在文件里改过
route-mode,文件里的值才会生效。
初次配置时可以按这个顺序排查:先用 direct 确认本机环境正常,再用 global 确认某个节点可用, 最后切到 rule。
日志
log-level 决定 Core 记录多少日志。它同时过滤日志文件和界面 日志 页显示的内存日志(最近 5000 条)。 设为 off 两者都不再记录。
log-file = false 只停止写文件,内存日志照常工作。
日志文件写在日志目录:
| 平台 | 日志目录 |
|---|---|
| Windows | %LOCALAPPDATA%\Specola\Logs;以 Windows 服务运行时为 %ProgramData%\Specola\Logs |
| macOS | ~/Library/Logs/com.specola.Specola |
| Linux | $XDG_STATE_HOME/specola/log,默认 ~/.local/state/specola/log |
- 启动 Core 前设置环境变量
SPECOLA_LOG_DIR可以换一个目录。它只影响日志。 - 正式版每天一个文件,文件名为
specola_YYYY-MM-DD,零点换新文件,保留最近 7 个。 - 还没有加载 Profile 时,Core 按
info级别记录。
本地端口
port 和 protocols 为支持代理设置的程序开一个本地端口。
[general]
port = 7890
protocols = "mixed" # 同一个端口同时支持 SOCKS5 和 HTTP[general]
port = 1080
protocols = ["socks5"] # 只支持 SOCKS5protocols | 接受 |
|---|---|
mixed | SOCKS5 和 HTTP |
socks5 或 socks | 只接受 SOCKS5 |
http | 只接受 HTTP,包含 CONNECT |
none | 什么都不接受,不开端口 |
- 数组可以列出多个值:
["socks5", "http"]等同于mixed。 - 数组不能为空(要关闭请写
"none"),不能重复同一协议(["mixed", "http"]重复了 HTTP),none不能和其他值一起写。 - 没有
https这个值。http本身包含CONNECT,HTTPS 网站照样能用。 port = 0或protocols = "none"时只剩增强模式,没有显式代理端口。- 端口小于 1024 时能加载,但会告警;打开这样的端口需要管理员或 root 权限。
端口支持哪些请求
端口根据每条连接的第一个字节区分 SOCKS5 和 HTTP。
| 客户端协议 | 支持 | 不支持 |
|---|---|---|
| SOCKS5 | 对 IPv4 地址、IPv6 地址或域名的 CONNECT | 用户名密码认证、UDP ASSOCIATE、BIND、SOCKS4 |
| HTTP | CONNECT host:port(HTTPS 及其他 TCP);带完整 http:// URL 的普通请求;或者路径加 Host 头 | 代理认证(Proxy-Authorization 会被删掉)、一个连接上发多个请求 |
- 端口只承载 TCP。程序发出的 UDP 只有通过增强模式才会进入 Specola。
- 普通 HTTP 请求的响应带
Connection: close,一个连接只处理一个请求。 - 请求头超过 64 KiB 时返回
431并断开。 - 经 SOCKS5 或 HTTP 传来的域名按原样参与域名规则匹配,Core 不需要先解析它。
客户端这样设置:
curl -x http://127.0.0.1:7890 https://example.com
curl -x socks5h://127.0.0.1:7890 https://example.com
export ALL_PROXY=socks5h://127.0.0.1:7890Core 从不修改操作系统的代理设置。界面里有一个开关可以在运行时停止、开启这个端口;在那里停掉的端口, 重新激活 Profile 后仍然保持停止。
[general.inbound]
旧配置把这两个字段写在子表里,现在仍然可用:
[general.inbound]
port = 7890
protocols = "mixed"两种写法只能选一种。port(或 protocols)两处都写会报错: Configure general.port only once; do not also use general.inbound。子表里写其他字段也会报错。
局域网访问
allow-lan = true 时端口绑定到 0.0.0.0,局域网里的其他设备也能使用。只绑定 IPv4。
控制接口
桌面应用总是通过本地通道和 Core 通信:Windows 上是命名管道,macOS 和 Linux 上是 Unix socket, 不需要任何配置(见 CLI)。api-listen 额外开一个 TCP 监听,让脚本或另一台机器上的 应用控制这个 Core。它使用同样的 MessagePack-RPC 协议,不是 HTTP,详见控制接口。
[general]
api-listen = "0.0.0.0:9090" # 也可以是 "127.0.0.1:9090"、"[::1]:9090"、"localhost:9090"- 地址必须是 IP 字面量或
localhost,后面跟 1–65535 的端口。写成router.lan:9090这样的主机名会报错:general.api-listen must be IP:port, localhost:port, or [IPv6]:port。 - 无论绑定哪个地址,Core 只为本机和私有网络的客户端服务:回环、
10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、100.64.0.0/10(CGNAT、Tailscale)、169.254.0.0/16、fc00::/7和fe80::/10, 以及这些地址的 IPv4 映射 IPv6 形式。其他客户端一连上就会被断开,并记入日志。 - 没有认证,也没有加密。这些网络里的任何设备都能读取流量统计、修改路由、编辑 Profile。 绝对不要把这个端口映射到公网。
license.*和core.shutdown通过 TCP 调用会被拒绝,只能走本地通道。- 同一时间最多接受 8 个连接。
- 修改或删除
api-listen后重新激活 Profile 即生效。Core 先打开新的监听,再让旧的继续服务约两秒, 保证发出这次修改的客户端能收到完整回复。新地址打不开(端口被占用、地址不属于本机)时,激活失败, 一切保持原样。
在 Linux 路由器上以 --gateway 启动时,Core 还会在加载任何 Profile 之前,在 LAN 地址的 9090 端口 打开控制监听,见 CLI。
ipv6
general.ipv6 能解析、能保存,界面也会显示,但 Core 不使用它。DNS 是否返回 IPv6 由 [dns].ipv6 控制,是否接管 IPv6 流量由 [enhanced-mode].ip-version 控制。
改动如何生效
重新激活 Profile 后,[general] 的所有改动都会应用到正在运行的 Core,不需要重启。
| 改动 | 效果 |
|---|---|
log-level、log-file | 立即生效 |
route-mode、global-proxy | 对新连接生效 |
port、protocols、allow-lan | 监听迁移到新设置,已建立的连接不受影响 |
api-listen | TCP 监听按上文所述迁移 |
Linux 上增强模式使用 eBPF 时,监听的改动会重建整个运行时,已建立的连接会断开。任何一步失败, 前面已完成的步骤都会撤销。加载失败的 Profile 不会影响正在运行的那一份。
报错
| 报错 | 原因 |
|---|---|
Unknown general field '<key>' | 字段拼错,或已被移除 |
general.port must be an integer | 写成了 port = "7890" |
Invalid mixed port: <n> | port 不在 0–65535 之间 |
inbound.type contains unsupported value '<v>' (expected mixed, socks5, http, or none) | protocols 的值不对,包括 https |
inbound.type contains duplicate protocol '<v>' | 同一协议写了两次,例如 ["mixed", "http"] |
inbound.type none cannot be combined with another protocol | ["none", "http"] |
inbound.type array must not be empty; use 'none' explicitly | protocols = [] |
Unknown mode: <v> (should be rule/global/direct) | route-mode 写错或大小写不对 |
Global mode requires an existing proxy target | global 模式下 global-proxy 为空或不存在 |
Unknown log level: <v> | log-level 写错 |
general.api-listen must be IP:port, localhost:port, or [IPv6]:port | 写了主机名、缺端口或端口为 0 |
Use general.port and general.api-listen | 旧配置里的 mixed-port 或 external-controller |
关于 protocols 的报错写的是 inbound.type,因为 Core 内部用这个名字读取 protocols。
旧版字段名
| 旧写法 | 现在 |
|---|---|
mixed-port | port(报错) |
external-controller | api-listen(报错) |
顶层 [inbound] | [general] 里的 port 和 protocols(报错) |
protocols = ["http", "https"] | protocols = "http"(报错) |
api-secret | 不需要:控制接口没有密钥(静默丢弃) |
排错
- 程序连不上端口。 确认
protocols包含客户端使用的协议,且端口没有被别的程序占用;端口打不开时, 激活会失败并给出原因。客户端设成 SOCKS4,或设成带密码的 SOCKS5,都会被拒绝。 - 其他设备连不上端口。 设置
allow-lan = true,使用本机的 IPv4 地址,并在防火墙里放行端口。 - 远程客户端连不上控制接口。 客户端必须在私有网络里,公网地址一连上就会被断开(日志里搜索
refused TCP client)。经 VPN 访问时,请使用100.64.0.0/10或其他私有网段的地址。 - 没有日志文件。 检查
log-file和log-level,到对应平台的日志目录查找;如果设置了SPECOLA_LOG_DIR,就去那个目录找。
