常见问题与故障排除
常见问题解答，以及针对用户最常遇到问题的快速解决方案。
访问 HTTPS 网站时出现证书错误
该设备或工具尚未信任 BlankTrail Proxy 根证书 (CA)。请通过控制面板中的 CA 证书按钮进行安装，然后重启浏览器或工具。在 Windows 上，安装程序通常会为您自动完成这一步；其他设备则需要手动安装。
“端口已被占用”或 409 错误
打开端口失败（POST /api/v1/ports/open）会返回 409——调试采集端口除外：它在进入端口管理器之前就被处理器拒绝，返回的是 403。原因不止一种——请阅读响应文本，它会直接说明原因。下面列出常见的几种；其中只有前两种可以通过更换端口号解决。
| 响应文本 | 该怎么做 |
|---|---|
port N is already open | 该端口号已在本应用中打开。请换一个端口号——或使用控制面板推荐的端口（GET /api/v1/ports/suggest 的作用相同）。 |
port N is busy: listen tcp …: bind: … | 该端口号被其他程序占用：监听未能建立，“bind:”之后的内容是操作系统给出的原文。请换一个端口号——或使用控制面板推荐的端口（GET /api/v1/ports/suggest）。 |
serving suspended: license inactive | 许可未激活：订阅已结束，或已有一天未连接授权服务器。换任何端口号都无济于事——请恢复连接或续订。 |
port limit reached | 已达到您的套餐允许的同时打开端口上限。请关闭多余端口或升级套餐。 |
the debug fingerprint port requires a Pro license | 🔴 本表中唯一返回 403 而非 409 的一行：该拒绝由打开端口的处理器在端口管理器之前给出。调试采集端口需要 Pro 套餐。普通端口可以打开，调试端口不行。 |
以上并非全部：同样以 409 返回的端口管理器原文还包括 port N is already being opened（同一端口号正在被打开）、serving suspended during open: license inactive — port not started（打开过程中许可失效），以及拦截冲突的拒绝：系统拦截已被其他端口占用、该应用已被其他端口拦截。
端口在我打开后自行消失了
无流量的端口会在 30 分钟后自行关闭——这是全局空闲超时。计时从打开端口那一刻开始，而不是最后一次请求：打开端口后去配置脚本，一小时后回来，端口已经不在了，而应用本身一切正常。
- 可以为单个端口设置自己的值：PUT /api/v1/port/{port}/idle，请求体为 {"seconds": 0} 表示永不关闭，{"seconds": null} 表示恢复为全局超时。
- 全局超时可通过 PUT /api/v1/idle_timeout 修改，或在 config.yaml 中通过 portmanager.idle_timeout 设置。
- 🔴 对该端口任何接口的调用都会被计为活动并重置计时。每分钟轮询 GET /status 的监控会让端口永不关闭——而提前打开端口的场景反而会丢失它。
- 对于容器与服务器，有一个正式的解决办法：config.yaml 中的 portmanager.startup_ports 列表。产品会自行打开这些端口并保持开启，并在与授权服务器恢复连接后重新打开它们。
我的许可无法激活
先排除显而易见的问题：邮箱与密码属于 blanktrail.com 账户，机器可以访问互联网，若启用了双因素确认则需完成票据步骤。
许可与设备绑定，且席位数量有限。因此会出现若干不同的拒绝原因，各有对应的解决办法——相关文本会显示在控制面板、托盘提示以及 GET /api/v1/license/status 的响应中。
| 拒绝文本 | 发生了什么、该怎么做 |
|---|---|
device limit reached | 许可席位已用尽。请在账户中释放一个设备——通常是旧机器，或被视为新设备的重装系统。 |
another copy of this device is running | 同一设备的第二个副本已在运行：例如克隆的虚拟机，或产品被启动了两次。 |
device key mismatch | 该安装在别处被重新识别。通常是在未迁移密钥的情况下迁移了状态——请重新激活。 |
device key required — reinstall the client | 设备密钥已丢失：状态文件损坏或被删除。请重新安装客户端。 |
device deactivated in your account | 该设备已在账户中被停用——请重新启用它或释放该席位。 |
client build is below the minimum allowed | 构建版本过旧。请更新客户端——具体做法见关于更新的解答。 |
subscription expired | 订阅已到期：请在账户中续订。 |
no active license for this account | 该账户没有有效许可——您登录了错误的账户，或尚未购买许可。 |
问题仍未解决？请从您的账户联系支持，并附上报告：控制面板可自行生成（问题报告按钮），其中已包含日志与端口状态。
代理对部分站点返回 403
如果控制面板顶部在套餐名称下方显示“仅限以下域名：…”，说明您使用的是服务套餐：端口只放行列出的域名，对其他地址一律返回空响应体的 403 Forbidden（SOCKS5 为 “connection not allowed by ruleset”，且根本不会授予 UDP ASSOCIATE）。这既不是代理故障，也不是上游出口的问题——更换上游没有用。同一份列表也会通过 GET /api/v1/license/status 响应中的 allowed_domains 字段返回。不带前缀的条目覆盖该域名及其全部子域，以 “=” 开头的条目只精确匹配该名称，裸 IP 永远不会匹配。若需要其他域名，请在账户中随套餐一起变更。
忘记了控制面板密码
密码通过重新激活许可来重置：在机器本机上打开 /recover，使用 blanktrail.com 账户登录，并在此处设置新的控制面板密码。无需重装产品，状态会保留。
API 密钥不受控制面板密码管理：它是独立的；若丢失的是它，可通过 GET /api/v1/auth/apikey 获取，或通过 POST /api/v1/auth/apikey/rotate 重新签发。
站点要求通过验证——该怎么办？
当普通 HTTP 请求不足、站点出现验证墙时，将由 Challenge Breaker 接手：它自行完成验证，把就绪会话交回同一端口，应用随后继续以普通请求工作。该功能在“编辑”对话框中按端口启用，并需要 MITM。自 Pro 套餐起可用；解题器占用的进程数可在“概览”标签页查看。
如何确保代理没有泄漏？
在打开端口之前，请使用“打开端口”对话框中的预检泄漏检查，或调用 /upstream/test API 并带上 “leak” 检查。它会将 DNS 解析器与出口 IP 进行比对，并探测是否存在 IPv6 逃逸路径，从而在一开始就发现存在泄漏的出口。
在哪里可以找到我的 API 密钥？
打开控制面板，点击齿轮图标进入设置，即可复制其中显示的 API 密钥。如果密钥可能已泄露，也可以在同一处进行轮换。在调用 API 时，将其作为 X-API-Key 请求头发送。
代理端口要求用户名和密码
若设置中启用了代理端口鉴权，您的应用中所填写的地址必须携带凭据——否则连接会被拒绝，看上去就像“代理不工作”。
# 不带鉴权
curl -x socks5://127.0.0.1:20134 https://example.com
# 带代理端口鉴权
curl -x socks5://proxyuser:proxypass@127.0.0.1:20134 https://example.com- 在推荐的 Docker 启动命令中，代理密码是默认设置的——容器会对外发布端口，而没有密码的开放代理等于向整个网络开放。
- “接受来自局域网的连接”这一设置同样如此：开启后端口就交给了网络中的邻居，密码不再只是形式。
- 用户名与密码可在控制面板的设置页面设置，或通过 PUT /api/v1/settings/network 的 proxy_auth_enabled、proxy_auth_user 与 proxy_auth_pass 字段设置。缺少用户名或密码则无法开启该验证。
如何更新？
应用会自行发现更新，但不会自动安装：有新版本时，控制面板会显示“有新版本可用”的横幅与按钮。在点击之前，仍会继续运行旧版本。
点击后，更新会被下载、按签名校验并替换可执行文件，随后应用会自行重启。许可、设置与密码都会保留。
有两种状态下按钮不会生效，且都不是故障。“需要手动安装”——本机无法替换文件（例如应用位于不可写位置）；旁边会出现下载链接，需手动运行安装程序。“更新失败”——旁边有“重试”按钮。多数情况下，尝试在替换文件之前中断（下载、签名校验），磁盘上的旧版本未受影响。较少见的情况是替换已经完成、只是重启失败：此时应用已经收尾停止工作，磁盘上放的是新版本，手动启动后运行的就是新版本。因此看到该状态时，请重启应用并核对版本：在控制面板中查看，或通过 GET /api/v1/update/status（current 字段）查询。
在 Windows 上也可以重新运行安装程序并选择“更新——保留许可、设置与密码”。在 Linux 上，更新通过软件包服务分发。用代码查询状态：GET /api/v1/update/status；触发更新：POST /api/v1/update。
如何获取帮助？
登录您在 blanktrail.com 的账户并打开支持渠道（Telegram 或网页聊天）。如果您在应用中遇到问题，设置对话框中有一个“报告问题”选项，在您同意的前提下，它会将一份经过脱敏处理的诊断包发送给我们的团队。