架构
Specola 由两个程序组成。Core 负责所有网络工作,Specola 应用是控制 Core 的桌面界面。两者只通过控制接口通信, 所以 Core 也可以单独运行、配合别的界面,或由脚本驱动。
Specola app (Qt Quick) scripts, remote app
│ │
│ local IPC │ TCP (api-listen, optional)
▼ ▼
┌──────────────────── Core ────────────────────┐
│ control API → CoreRuntime │
│ proxies · routing · local port · DNS │
│ Enhanced Mode · health checks · tools │
│ telemetry · logging · license │
└──────────────────────────────────────────────┘Core 与应用
| Core | Specola 应用 | |
|---|---|---|
| 可执行文件 | specola-service.exe(Windows)、specola-core(macOS、Linux) | Specola 桌面应用 |
| 源码 | src/(C++20、Asio) | gui/qml/(Qt Quick) |
| 负责 | Profile、监听、DNS、规则、代理协议、增强模式 | 窗口、托盘、主题、页面状态 |
| 是否需要管理员权限 | 仅增强模式需要 | 从不需要 |
谁来启动 Core:
| 平台 | 启动者 | 生命周期 |
|---|---|---|
| Windows(安装版) | 服务控制管理器,以 specola-service 服务(LocalSystem)运行 | 独立于应用;应用请求它启动和停止 |
| macOS、Linux | 应用,作为子进程,带 --parent-pid | 应用退出时随之退出 |
| 任意平台 | 你在终端里启动(--config <文件>) | 直到 Ctrl+C;应用会连接它 |
应用启动时先尝试连接正在运行的 Core,没有响应才自己启动一个。一台电脑上只能运行一个 Core,第二个会立即以 Another specola-core process is already running 退出。
不带 --config 启动的 Core 会等待应用激活 Profile。某个 Profile 启动失败时,Core 仍保持控制接口开放,以便换一个 Profile。
控制接口
应用与 Core 之间使用 MessagePack RPC。请求、应答和数据流定义在 api/*.toml 中(例如 profile.activateProfile、 proxy.selectGroupMember、routing.setMode)。见控制接口。
| 传输方式 | 地址 | 谁能连接 |
|---|---|---|
| 本机 IPC(始终开启) | Windows:命名管道 \\.\pipe\specola;macOS、Linux:Unix 套接字 /tmp/specola.sock | Windows:本机用户;macOS、Linux:启动 Core 的用户(套接字权限 0600,Core 以 root 运行时归属发起启动的用户) |
| TCP(可选) | [general] api-listen,例如 "127.0.0.1:9090" | 只接受回环和私有网段的客户端:10/8、172.16/12、192.168/16、100.64/10、169.254/16、fc00::/7、fe80::/10 |
--ipc-endpoint <路径>可以改变本机 IPC 地址。- TCP 接口没有认证。除非信任网络里的每台设备,否则请绑定到回环地址。许可证相关操作和
core.shutdown在 TCP 上一律拒绝。 api-listen跟随 Profile:激活 Profile 时打开、迁移或关闭,不需要重启。- 尚未加载 Profile 时,只响应
sys.*、core.*、profile.*、license.*、overview.*、ssh.*和gateway.*方法,其他方法返回Core initialization is not complete。Profile 加载期间,请求返回Core is loading a Profile。
应用还会告诉 Core 用户的 Profiles 目录在哪里(profile.setDirectory)。之后 Core 以该用户的身份读写 Profile 文件, 即使 Core 本身以 root 或 LocalSystem 运行。你在应用里编辑节点或规则时,由 Core 把改动写入 Profile 文件并重新加载; 加载不了的改动不会保存。
Core 内部
Core 持有一份不可变的配置快照,以及由它构建出的各个部分(CoreRuntime,src/core/core_runtime.hpp):
| 部分 | 职责 |
|---|---|
| 日志 | 日志级别、内存日志、按天的日志文件 |
| 许可证 | 许可证状态(数据目录里的 license.json) |
| 统计 | 连接、每条规则、每个节点和总流量的计数 |
| 节点 | 每个 [[proxy]] 和 [[proxy-group]] 一个实例,以及代理组的成员选择 |
| 路由 | 规则表、路由模式、bypass、兜底出站、Fake-IP 与 DNS 映射 |
| 入口 | 本地 HTTP/SOCKS5 端口 |
| DNS | 应答被接管的查询、Fake-IP 地址池、可选的 DNS 监听 |
| 增强模式 | Windows 和 macOS 上的 TUN,Linux 上的 eBPF |
| 健康检查 | 定期对代理组成员做 URL 测试 |
| 工具 | 通过控制接口提供的延迟测试等,见工具 |
启动顺序:许可证、节点和代理组、规则、DNS、本地端口、健康检查,最后是增强模式——等它要把流量导入的各部分都就绪之后。 在 Linux 上,路由器网关(--gateway <文件>)与这些部分并行运行,可以为局域网客户端使用 DNS 模块。
Windows 服务模式
Windows 安装程序把 Core 注册为 specola-service 服务。它以 LocalSystem 身份运行,所以应用以普通权限运行时也能使用增强模式。
- 服务自己的数据放在
%ProgramData%\Specola,只有 SYSTEM 和 Administrators 可以读写。 - 服务没有自己的 Profiles 目录。应用会绑定当前登录用户的
%LOCALAPPDATA%\Specola\profiles,服务以该用户身份读取。 - 命名管道允许交互式用户连接,所以未提权的应用可以控制它。
- 被强制结束的 Core 可能留下 Windows 的 DNS 重定向(一条 NRPT 规则)。Core 每次启动都会清除它;也可以以管理员身份 运行
specola-service.exe --reset-network手动清除。
数据目录
| 目录 | Windows | macOS | Linux |
|---|---|---|---|
数据(资源、license.json) | %LOCALAPPDATA%\Specola | ~/Library/Application Support/com.specola.Specola | $XDG_CONFIG_HOME/specola(~/.config/specola) |
| Profiles | <数据>\profiles | <数据>/profiles | <数据>/profiles |
| 下载缓存 | <数据>\Cache\remote | ~/Library/Caches/com.specola.Specola/remote | $XDG_CACHE_HOME/specola/remote |
| 日志 | <数据>\Logs | ~/Library/Logs/com.specola.Specola | $XDG_STATE_HOME/specola/log |
| 运行时 | <数据>\Runtime | ~/Library/Caches/com.specola.Specola/runtime | $XDG_RUNTIME_DIR/specola |
- Windows 服务使用
%ProgramData%\Specola作为数据目录。 SPECOLA_LOG_DIR可以改变日志目录,其他目录没有改动的选项。- 通过
sudo或 polkit 启动的 Core 使用发起启动的那个用户的目录。
Profiles 目录里的内容:
profiles/
├── work.toml a profile
├── work.toml.modules modules it applies, one per line (optional)
├── work.toml.disabled-rules rules switched off in the app (optional)
├── modules/home-lan.toml a module, see Modules
└── .removed/ removed profiles, kept here从 Profile 文件到运行中的配置
激活 Profile(或通过 --config 指定)时,Core 依次:
- 读取文件,然后合并
<profile>.modules里列出的模块。 - 丢弃
[metadata]等被忽略的段落并给出告警,拒绝未知字段。 - 把结果解析成内部配置(
AppConfig)并检查:名字、引用、规则语法、FINAL是否在最后、平台限制。 - 找到 Profile 引用的文件(相对路径依次在 Profile 所在目录、数据目录、可执行文件旁的
resources/中查找), 下载远程的 GeoIP、GeoSite 和规则集文件,下载失败时使用缓存。 - 应用
<profile>.disabled-rules。
--test-config 正是执行这些步骤后停止。任何错误都会中止加载,正在运行的 Profile 不受影响。
然后:
- 第一个 Profile: Core 构建并启动所有部分(
CoreRuntime::bootstrap)。 - 之后的 Profile: Core 把新配置和正在运行的配置比较(
ConfigDiff),只就地应用差异:监听、控制接口、节点表和规则表、 DNS、增强模式、日志设置、路由模式。不能就地应用的改动(以及 Linux eBPF 下监听、DNS、增强模式或嗅探的任何改动) 会按新配置重建所有部分。重建失败时,Core 重建之前的配置;如果连这一步也失败,Core 会停止,需要重新启动。
重新加载时保留什么,见工作原理。
