安装与激活

在 Windows、Linux 或 macOS 上安装 BlankTrail Proxy，信任其根证书并激活许可证。整个过程只需几分钟。

Windows

从您在 blanktrail.com 的账户下载安装程序 (.exe)。
运行安装程序并选择语言（英文、俄文或中文）。
阅读安装须知，然后完成向导。可选择启用桌面图标以及“登录时启动”。
当 Windows 提示时，请批准安装根证书 (CA) —— 这样代理即可提供 HTTPS 服务而不出现证书警告。
应用会自动启动，其图标将出现在系统托盘中。

安装目录取决于您在向导最开始处的选择。选择“为所有用户安装”时安装到 C:\Program Files\BlankTrail Proxy；选择“仅为我安装”时安装到 %LOCALAPPDATA%\Programs\BlankTrail Proxy。向导默认不要求管理员权限，因此普通账户会得到第二个路径——如果在 Program Files 下找不到本产品，请到该路径查找。两种情况下都会添加两个开始菜单快捷方式：一个用于启动托盘应用，另一个用于在浏览器中打开控制面板。

更新或重新安装

如果已存在旧版本，安装程序会提供三个选项：

更新 —— 保留许可证、设置和密码。仅替换程序文件。
从头重新安装 —— 重置为全新状态。可选择保留许可证和根证书 (CA)。
移除 —— 从本机卸载 BlankTrail Proxy。

说明由于 BlankTrail Proxy 使用自己的证书拦截 TLS，某些杀毒软件可能会将其标记为可疑。如果您的杀毒软件与本应用冲突，请将 BlankTrail Proxy 添加到其排除列表中。

状态与日志的位置

状态——配置文件数据库、根证书、许可密钥、缓存与日志——位于应用可执行文件旁的 data 目录中。若该目录不可写（在无权限的情况下安装到 Program Files，或文件夹被杀毒软件监视），应用会转到 %LOCALAPPDATA%\BlankTrail——因此可能有两个位置，两处都值得检查。

data\proxy.log——应用日志；达到 50 MB 时旧内容移入 proxy.log.1。
data\profiles.db——配置文件数据库；data\ca.crt 与 data\ca.key——根证书及其密钥。
data\license.key、data\license.secret 与 data\device_id——许可与设备标识。把安装迁移到另一台机器时必须一并迁移它们，否则会被视为新设备并占用第二个席位。
data\traffic_port_<端口>.jsonl——若曾启用过，则为端口的请求日志。

这同样回答了“重装前该保留什么”：整个 data 目录。在 Linux 上，相同的状态位于 /var/lib/blanktrail，日志可通过 journalctl -u blanktrail -f 查看。

Linux

最快捷的方式是使用您账户“下载”页面上显示的个性化一行命令安装脚本 —— 它会为您的架构获取正确的软件包、安装 OpenVPN，并自动激活您的许可证。

如需手动安装软件包，请下载适用于您架构的 .deb 文件并安装：

sudo dpkg -i blanktrail_1.3.1_amd64.deb
sudo systemctl enable --now blanktrail

该服务以专用系统用户身份运行。其配置文件位于 /etc/blanktrail/config.yaml，其状态数据（许可证、证书、数据库）位于 /var/lib/blanktrail 下。

管理服务

sudo systemctl status blanktrail     # check status
sudo systemctl restart blanktrail    # restart
sudo journalctl -u blanktrail -f     # follow logs

控制面板在 8891 端口提供服务。在服务器上，可通过 SSH 隧道或私有网络访问它 —— 例如：ssh -L 8891:127.0.0.1:8891 user@host，然后在本地打开 http://127.0.0.1:8891。

提示更喜欢 tarball？请解压适用于您架构的 .tar.gz，并以 root 身份运行其中附带的安装脚本。

macOS

macOS 提供面向 Intel 与 Apple Silicon 两种架构的压缩包。从下载页面解压 .tar.gz 并运行随附的安装脚本；应用以后台服务方式运行，控制面板同样在 127.0.0.1:8891 打开。

说明macOS 上没有菜单栏图标——与 Linux 一样，全部操作在控制面板中完成。

Docker

镜像由发布产物构建，并使用与客户端相同的版本号发布：blanktrail/blanktrail-proxy，支持 linux/amd64 与 linux/arm64。其中包含与桌面安装相同的代理与控制面板。

完整的启动命令——包含代理密码、状态与证书的数据卷、已映射的控制面板以及验证码 API 端口——展示在用户面板的下载页面上，并已带有当前标签。8892 端口会预先发布，尽管验证码 API 默认关闭：它在面板中开启并立即生效，而创建容器时未发布的端口事后无法补加。镜像页面列出了所有已发布的标签。

Docker Hub 上的 blanktrail/blanktrail-proxy标签、架构与简要启动说明

配置文件

在 Linux 上该文件位于 /etc/blanktrail/config.yaml，在容器中位于您挂载的位置，在 Windows 上与应用同目录。所有在控制面板中配置的内容都保存在数据库里，而不在此处：该文件设定的是第一个请求之前就需要的东西——地址、路径与启动端口。

键	默认值	作用
`api.addr`	`:8891`	控制服务器的地址：控制面板与 API。容器需要发布的正是这个端口。
`log.level`	`info`	日志级别：debug、info、warn 或 error。可通过 PUT /api/v1/log_level 在运行时更改。
`log.console_level`	`—`	控制台输出的单独阈值；留空表示与文件相同。
`log.file`	`data/proxy.log`	应用日志的写入位置。留空表示仅写入错误流。
`log.max_size_mb`	`50`	超过该大小后日志会轮转为 proxy.log.1，用于限制长期运行时的磁盘占用。
`portmanager.idle_timeout`	`30m`	无流量的端口经过多久后关闭。端口可以有自己的值（PUT /api/v1/port/{port}/idle）。
`portmanager.max_ports`	`100000`	同时打开端口数的上限。它只是余量，而非套餐限制：实际允许的数量由许可决定。
`portmanager.startup_ports`	`—`	产品在启动时自行打开的端口。参见下文。
`mitm.ca_cert / ca_key`	`data/ca.crt / data/ca.key`	用于拆解 TLS 的根证书及其密钥。
`mitm.crl_public_host`	`—`	从另一台机器访问证书吊销列表所用的地址：host 或 host:port。当从其他机器使用代理端口时需要它。
`mitm.cert_ttl`	`24h`	即时签发的站点证书的有效期。
`database.path`	`data/profiles.db`	指纹配置文件数据库。
`license.key_file`	`data/license.key`	存放形如 SPF-XXXXX-XXXXX-XXXXX 的许可密钥的文件。secret_file 与 device_id_file 与之相邻——请与密钥一起迁移，否则该安装会被视为新设备。
`selfupdate.report_rollbacks`	`true`	是否上报自更新失败。这是产品唯一在未被请求时发送的报告；设为 false 则仅把原因写入日志。

注意已安装的文件中含有 proxy 块及其 http_addr 和 socks5_addr 键（例如 0.0.0.0:8090 和 0.0.0.0:1080），mitm 块中还有 cert_cache_size 键。它们是早期版本的遗留项，不配置任何东西：产品既不监听 8090 也不监听 1080，证书缓存大小在程序内部固定。代理端口只能通过 portmanager.startup_ports 或 API 打开，端口号由您指定——需要在防火墙或容器中放行的正是这些端口号，而不是 proxy 块中的值。

启动时打开的端口

这正是最常修改该文件的原因：容器需要在启动时就带着已打开的端口。该列表由产品自行读取，端口恰好在许可门放行服务时打开——不可能更早，而外部脚本并不知道那个时刻，只能要么过早要么盲目等待。与授权服务器恢复连接后，这些端口会自行重新打开。

config.yaml 片段

portmanager:
  idle_timeout: "30m"
  startup_ports:
    - port: 20134
      protocol: socks5
    - port: 20135
      protocol: http

protocol 为空表示 http；允许的取值为 http 与 socks5。
该端口的身份与其他设置随后再给定——通过 PUT /api/v1/port/{port}/config 或加载预设。
空列表的行为与以往完全一致：产品不会自行打开任何端口。

注意在运行中的安装上修改该文件只有配合重启才有意义：它在启动时只读取一次。所有需要在运行时修改的内容——日志级别、空闲超时、域名路由——都通过 API 修改，并可自行跨重启保留。

根证书 (CA)

BlankTrail Proxy 在本地终止 TLS，因此每台通过它连接的设备都必须信任其根证书 (CA)。否则，浏览器和工具在访问 HTTPS 网站时会显示证书错误。

在 Windows 上，安装程序会自动将证书添加到系统信任存储区。若要在其他设备上安装，请打开控制面板，点击标题栏中的“根证书 (CA)”按钮，并按照针对各平台的说明操作。您也可以直接从 API 下载该证书（参见许可证与访问 → 根证书（CA））。

重要仅在您所掌控并通过您自己的 BlankTrail Proxy 实例进行路由的设备上安装该证书。它的唯一用途是让这些设备能够信任您的本地代理。

首次运行

首次启动时，应用会准备其本地状态、生成根证书 (CA) 并启动控制面板。打开 http://127.0.0.1:8891（或使用托盘中的“打开控制面板”项）以完成设置。

系统会引导您激活许可证并设置控制面板密码。此后，控制面板即可用于管理代理端口。

激活您的许可证

运行 BlankTrail Proxy 需要一个许可证。您可以通过以下几种方式激活：

邮箱 + 密码 —— 在引导界面中使用您的 blanktrail.com 账户凭据登录。
工单 + 许可证 ID —— 当需要双重验证确认时，使用确认码。
零接触 —— 受控的安装程序可携带注册令牌，并在首次启动时自动激活。

请从您在 blanktrail.com 的账户获取许可证和下载文件。得益于内置的宽限期窗口，正在运行的实例即使遇到授权服务器短暂中断也能继续工作，因此短暂的故障不会中断任务。

关于宽限期有三点值得了解，因为长时间运行的规划依赖于它们。它恰好持续 24 小时：在授权服务器不可达期间，已运行的实例可继续工作，但 24 小时后已打开的端口会关闭，新端口也无法打开——并返回 “serving suspended: license inactive”。而在启动时完全没有宽限：在无法连接许可服务器的情况下启动的应用不会开始提供服务。

注意由此对容器与服务器有一个实际影响：无论是启动时还是此后，至少每天都需要能连通授权服务器。连接恢复后，portmanager.startup_ports 中列出的端口会自行重新打开。

系统级流量拦截

安装程序的任务页面有一个单独的选项“系统级流量拦截”。它会注册特权服务；没有该服务，产品只能作为普通代理工作——即只适用于可以指定代理地址的应用。

该选项仅在“为所有用户安装”时可见，并需要管理员确认。若按用户安装或拒绝确认，安装会继续，拦截保持不可用——之后可从托盘“TUN helper”分组安装该服务。

注意注册服务本身不会拦截任何流量：在打开带拦截的端口之前，服务只是等待。升级时若此前已安装会重新注册，卸载产品时会一并移除。

系统流量拦截服务对系统的更改、拦截范围、状态与诊断。

🔴 在管理员安装模式下，该选项默认已勾选：管理员只要一路点击“下一步”就会注册该服务。若不想安装，需要手动取消勾选——这不会中断安装，只是拦截功能在从托盘菜单安装该服务之前保持不可用。