CLI
Core 是负责分流的进程,平时由桌面应用替你启动和停止。需要校验 Profile、在没有桌面的机器上运行 Specola, 或排查启动问题时,可以自己运行它。
| 平台 | 可执行文件 |
|---|---|
| Windows | specola-service.exe |
| macOS、Linux | specola-core |
specola-core --test-config --config home.toml # 校验后退出
specola-core --config home.toml # 用这个 Profile 运行
specola-core # 运行,等待应用选择 ProfileWindows 上把 specola-core 换成 specola-service.exe。Windows 版不带任何参数启动时只打印一行提示, 并以退出码 1 退出;不需要其他选项时请加 --console。
选项
| 选项 | 平台 | 作用 |
|---|---|---|
--config <文件> | 全部 | 启动时加载的 Profile |
--test-config、-t | 全部 | 加载并校验 --config,打印结果后退出,不启动 Core |
--ipc-endpoint <路径> | 全部 | 改用其他本地控制端点(见下文) |
--parent-pid <pid> | 全部 | 该进程退出时 Core 也退出;桌面应用会传入自己的 PID。--parent-id 是旧别名 |
--gateway <文件> | Linux | 路由器模式(见下文) |
--console | Windows | 在终端前台运行;没有其他作用 |
--service | Windows | 作为 Windows 服务运行,只供服务控制管理器使用 |
--reset-network | Windows | 清除被强行结束的 Core 遗留的 DNS 重定向后退出;需要管理员权限 |
-h、--help | 全部 | 打印选项后退出 |
-v、--version | 全部 | 打印版本后退出 |
- 选项的值可以跟在后面(
--config home.toml),也可以用=连写(--config=home.toml)。 - 选项必须完全匹配:未知或拼错的选项会打印
Unknown argument和帮助,并以退出码 1 退出。-t不能和其他短选项合写。 - 没有指定数据目录或便携模式的选项,也不能在命令行设置日志级别;Core 使用文件和目录 里列出的位置。
--config
specola-core --config /home/me/profiles/home.toml # 绝对路径
specola-core --config home.toml # 文件名相对路径按以下顺序查找:
- Profiles 目录(Linux 上是
~/.config/specola/profiles/home.toml); - 可执行文件所在目录。
不会在当前目录查找:在 Profile 所在目录里运行 specola-core --config ./home.toml,只要这个文件不在上面两个 位置,就会失败。其他位置的文件请写绝对路径。
Profile 里资源文件(规则集、geoip.dat、证书)的相对路径,优先相对于 Profile 自己所在的目录, 见分流规则。
正常启动时 Profile 加载失败,Core 不会退出:它继续运行,把错误报告给应用并写入日志,等待选择另一个 Profile。
--test-config
specola-core -t --config home.toml- 校验通过时打印
Config validation passed: <路径>,退出码 0;失败时打印Config validation failed:和全部错误,退出码 1。 - 告警(例如被忽略的配置段)写入日志,不打印到终端。
- 加载方式和正式启动完全一样:会应用模块和停用的规则,本地资源文件必须存在,远程规则集和 geo 文件会下载。 下载失败但有缓存时使用缓存。
- 不需要管理员权限,不改动网络设置,另一个 Core 正在运行时也可以放心使用。
- 不带
--config时以退出码 2 退出。
本地控制端点
应用通过本地通道控制 Core。Core 运行期间它始终打开。
| 平台 | 默认端点 | 谁能连接 |
|---|---|---|
| Windows | 命名管道 \\.\pipe\specola | 启动 Core 的用户;Core 以服务或管理员身份运行时,还包括 SYSTEM、Administrators 和所有已登录用户 |
| macOS、Linux | Unix socket /tmp/specola.sock | 启动 Core 的用户(文件权限 0600);Core 以 root 运行时,是申请 root 的那个用户 |
--ipc-endpoint 可以修改它,接受 socket 路径(/run/me/specola.sock)、管道(\\.\pipe\name), 或 unix:///path、pipe://name 这样的 URL 写法。应用也必须指向同一个端点。
一台电脑只能运行一个 Core:第二个 Core 会以退出码 3 退出(Another specola-core process is already running)。 控制协议见控制接口;可选的 TCP 监听见 api-listen。
管理员权限
增强模式需要管理员(root)权限。在 macOS 和 Linux 上,如果没有权限的 Core 启动时加载的 Profile 开启了增强模式, 它会申请一次权限,然后重新启动自己:
| 版本 | 申请方式 |
|---|---|
| Linux 正式版 | pkexec,弹出桌面的认证对话框 |
| macOS 正式版 | 系统的管理员授权框;输出写入日志目录下的 core-privileged-launch.log |
| 调试版 | 在终端里用 sudo;没有终端时以退出码 1 退出 |
拒绝授权则 Core 退出。在 Windows 上,应用通过以 LocalSystem 运行的服务启动 Core。
Windows 服务
安装程序会注册一个名为 specola-service 的服务(显示名称 “Specola Service”):
- 它以 LocalSystem 身份运行
specola-service.exe --service,启动类型为手动:应用需要 Core 时才启动它。 已登录用户可以启动、停止和查询它,只有管理员能修改它。 - 它的数据放在
%ProgramData%\Specola,只有 SYSTEM 和 Administrators 能访问。Profile 仍在各用户自己的目录里, 由应用告诉服务位置。 - 服务进程没有正常停止就结束时(被强行结束、崩溃),Windows 会运行
specola-service.exe --reset-network, 删除把系统 DNS 指向 TUN 网卡的 NRPT 规则。服务本身不会被重启。
如果 Core 被强行结束后 DNS 不能用,可以在管理员终端里自己运行 --reset-network:
& "C:\Program Files\Specola\specola-service.exe" --reset-network规则已删除(或本来就没有)时退出码为 0,没有管理员权限时为 1。
路由器模式
Linux 版可以把 Core 作为局域网的透明网关运行:
specola-core --gateway /etc/specola/gateway.toml --config /etc/specola/profiles/router.toml
specola-core -t --gateway /etc/specola/gateway.toml # 只校验网关文件网关文件配置局域网网卡、TPROXY 接管、DHCP、局域网 DNS 服务和控制监听(lan-interfaces、local-domain、 device、tproxy、dhcp、dns、api)。除非写了 [api] enable = false,Core 会在加载任何 Profile 之前, 在第一块局域网网卡的 IPv4 地址的 9090 端口(或 [api] listen 指定的地址)打开控制监听,让远程应用选择 Profile。 它和 api-listen 一样只服务私有网络的客户端,没有认证。网关文件加载失败时 Core 以退出码 2 退出。
文件和目录
| Windows | macOS | Linux | |
|---|---|---|---|
| 数据 | %LOCALAPPDATA%\Specola | ~/Library/Application Support/com.specola.Specola | $XDG_CONFIG_HOME/specola(~/.config/specola) |
| Profiles | <数据>\profiles | <数据>/profiles | <数据>/profiles |
| 日志 | <数据>\Logs | ~/Library/Logs/com.specola.Specola | $XDG_STATE_HOME/specola/log(~/.local/state/specola/log) |
| 下载缓存 | <数据>\Cache\remote | ~/Library/Caches/com.specola.Specola/remote | $XDG_CACHE_HOME/specola/remote(~/.cache/specola/remote) |
作为 Windows 服务运行时,数据目录是 %ProgramData%\Specola,没有自己的 Profiles 目录。在 macOS 和 Linux 上以 root 运行时,使用的是申请 root 的那个用户的目录,而不是 root 的。
正式版启动后不向终端输出任何内容:Cannot find --config 这类消息只写进日志文件。Core 没有任何提示就退出时, 请去看日志。调试版还会打印到终端,并且只保留一个 specola.log,每次启动时覆盖。
环境变量
| 变量 | 作用 |
|---|---|
SPECOLA_LOG_DIR | 日志写到这个目录,而不是默认日志目录 |
XDG_CONFIG_HOME、XDG_CACHE_HOME、XDG_STATE_HOME | Linux:改变数据、缓存和日志目录;只认绝对路径 |
XDG_RUNTIME_DIR | Linux:运行时文件目录,需属于当前用户 |
LOCALAPPDATA | Windows:绝对路径会替代用户的 Local AppData 目录(测试用) |
Core 自己申请 root 时,会把这些变量传给新进程。
停止 Core
Ctrl+C、SIGTERM 和关闭控制台窗口都会让 Core 正常停止:撤下增强模式并恢复系统 DNS。 停止过程超过 10 秒时,Core 会直接退出。带 --parent-pid 时,那个进程结束 Core 也会停止。
退出码
| 退出码 | 含义 |
|---|---|
0 | 正常停止、--help、--version、--test-config 通过、--reset-network 成功 |
1 | --test-config 发现错误;未知选项或缺少值;本地控制端点打不开;网关无法启动;Windows:不带任何参数、--reset-network 失败或没有管理员权限;macOS/Linux:申请管理员权限失败 |
2 | Core 的目录无法创建;找不到 --config;--test-config 没有 --config;--parent-pid 无效或无法监视该进程;--gateway 文件加载失败 |
3 | 这台电脑上已经有一个 Core 在运行 |
4 | 因其他原因拿不到单实例锁 |
Profile 加载失败不会导致退出:Core 继续运行,等待选择另一个 Profile。
