HaloRelay
HALORELAY · 使用与维护

证书与节点恢复

面板 / Agent 0.7.19 · 授权站 0.3.7 · 更新于 2026-10-11

故障快速索引 · 授权站更新 · 面板更新

本文适用于面板与 Agent 0.7.18(连接恢复功能自 0.7.15 起提供)。旧节点需要先升级 Agent,才具备持续鉴权重试与地址迁移能力。生产故障不能仅凭“离线”判断,请按实际诊断结果处理。

本次故障与修复范围

  • 宝塔更换证书后重建“非 443 就跳转”的规则,导致 HTTPS 24443 被跳回 443。受限网络不能访问 443,因此节点失联。修复反向代理后已有节点可自动恢复。
  • Agent Token 已撤销时,旧 Agent 退出,systemd 反复重启。新版立即停止转发、保留进程和计数,以有上限的随机退避持续尝试;有效令牌文件恢复后自动重连。不绕过令牌或软件授权。
  • 旧版更新失败回退、旧程序也不健康时,会保留 pending_activation。完整卸载现在可在维护锁保护下校验并取消本 Agent 的切换记录,再停止服务、删除归属明确的安装文件。正在运行的维护任务、其他组件、异常路径仍会拒绝。
  • 新版心跳接收面板批准的 HTTPS 入口,最多保留四个。连接恢复不自动跟随 HTTP 跳转,也不关闭 TLS 校验。缓存与原安装地址、当前令牌绑定;令牌变化后不沿用旧缓存。

正确更换证书

正常替换同域名的有效证书无需重装 Agent,也无需修改隧道出口证书。网站 HTTPS 证书与出口隧道证书是两套独立身份。

  1. 在宝塔“网站 → panel 域名 → SSL”部署包含完整链的有效证书;证书必须覆盖节点使用的域名。
  2. 保持节点 HTTPS 端口监听和云防火墙放行。例如 TCP 24443;不要只保留 443。
  3. 检查强制 HTTPS 规则:if ($server_port != 443) 会把已经使用 HTTPS 的 24443 也跳走。临时修复应改成只在 $scheme = http 时跳转。宝塔可能再次生成这一段,因此推荐下面的独立入口方案。
  4. 在节点执行不带令牌的检查:
curl --proto '=https' --connect-timeout 15 --max-time 30 -sS -D - -o /dev/null https://panel.example.com:24443/api/health

替换为自己的域名。应直接返回 HTTP 200;不加 -L、不加 -k。301/302 应修代理;证书错误应修链、域名或节点时间;超时应查端口、防火墙、DNS与线路。

宝塔独立节点端口:避免证书操作重写跳转

随源码提供 deploy/baota-agent-endpoint.py,适用于一个主站 server 块、标准证书绝对路径、已有唯一 listen 24443 ssl; 的宝塔 Nginx 配置。复杂自定义配置会停止,不猜测修改。

  1. 在宝塔主站“反向代理”核对实际上游端口。本次部署上游为 127.0.0.1:10086,其他客户必须填写自己的端口。
  2. 在面板服务器下载并核对本版工具,下载或校验失败就停止,不执行下一步。以下临时工作目录保留供预览、实施与事后核对:
mkdir -m 700 halorelay-baota-0715
cd halorelay-baota-0715
curl --fail --show-error --proto '=https' --connect-timeout 15 --max-time 120 'https://dl.halorelay.com:24443/repairs/0.7.15/baota-agent-endpoint.py' -o baota-agent-endpoint.py
printf '%s  %s\n' '566fba247d31197e639d0c154d9ab2b730c638c35dbe4651e57955c0a141e7db' 'baota-agent-endpoint.py' | sha256sum -c -

看到 OK 后,替换为自己的域名和实际上游端口,先预览:

sudo python3 baota-agent-endpoint.py --domain panel.example.com --port 24443 --upstream-port 10086
  1. 核对预览后执行:
sudo python3 baota-agent-endpoint.py --domain panel.example.com --port 24443 --upstream-port 10086 --apply

脚本备份主站配置,将 24443 监听移到同目录的独立 Nginx 配置,沿用宝塔证书文件路径,不复制或输出私钥;新入口直接代理到面板,不包含强制 443 跳转。修改前后执行 nginx -t,重载失败恢复原配置。不会改变主站 80/443,也不会删除证书。再次执行不会覆盖已存在的独立配置。

  1. 核对节点与公网检查都返回 200,再在宝塔更换一次测试证书/续期检查,确认 24443 没有跳转、节点持续心跳。证书路径改变或删除整个网站时,独立入口也要同步更新。
  2. 回滚需同时恢复脚本输出的主站备份并移走独立配置,检查 Nginx 后重载,避免同一个端口重复监听。不要只恢复其中一份。

变更“节点可访问的面板地址”

  1. 先在新地址配置 HTTPS、代理和防火墙;保留旧入口。
  2. 先升级面板,再升级 Agent 至 0.7.15。设置页显示各节点是否支持迁移、最后上报的实际连接地址和在线情况。
  3. 在“面板公开访问地址”保存新地址。在线新版节点通过旧入口收到地址清单,随后尝试新入口。新入口不可达时会轮询已批准的备用入口,恢复后重试首选入口。
  4. 节点重启会读取缓存,不会退回只知道安装时旧地址的状态。缓存写入失败会在日志说明,此时当前进程仍可迁移。
  5. 所有节点实际连接到新地址前,不能关闭旧入口。已经失联且未收到新地址的节点、旧版本节点,需要本机修复。软件无法向完全不可达的机器发送新地址。
  6. 跨域名迁移还需核对商业授权绑定。自动入口切换保留安装时的授权校验身份,不会自行更换签发方、解除域名绑定或忽略软件许可;更换整个许可绑定域名属于部署迁移,要按授权迁移流程处理。

不重装修复现有 Agent

新安装的 0.7.15 管理工具提供:

sudo halorelay repair-connection agent --check
sudo halorelay repair-connection agent --panel-url https://panel.example.com:24443
sudo halorelay repair-connection agent --replace-token

第一条只检查。后两条先验证 HTTPS 和节点准入,成功后才保存、重启。更换令牌隐藏输入,并显示节点编号、角色,要求确认对应服务器。失败不覆盖原配置;重启失败恢复原文件。命令不接受明文 Token 参数。

普通在线升级为了保持固定主机工具的信任边界,不会自动替换旧管理脚本。若提示“未知操作”,要先按该版本发布说明取得经校验的恢复工具,不能靠重复执行同一旧命令解决。Agent 本身仍可在线升级。

完整卸载与重装

sudo halorelay uninstall agent --complete

新工具先预览并要求确认。完整卸载会清理已识别的 Agent 程序、凭据、自有证书、运行目录、维护任务与专属包装命令;保留其他服务、同机面板、外部证书、系统公共日志及其他业务文件。系统包管理器管理的共享依赖不盲目卸载。无法证明归属或包含同机面板时会停止,避免误删。

因更新失败遗留的本 Agent 切换记录不再要求旧程序先恢复健康。工具在独占维护锁下,归档诊断计划,撤销组件维护授权,停止服务后取消切换,才执行清理。不会删除任意 state 文件来绕过检查。

完整卸载后从面板复制对应节点的最新安装命令。出口/双向节点需按界面确认重新登记隧道证书。Agent Token、下载令牌、软件授权码用途不同,不能互换。

Veyra Guard v1

本版将 Veyra Guard v1 与重连修复一起交付。它是 Veyra 的故障恢复调度层,保留标准 TLS/QUIC 密码学和既有协议兼容性。

适用 Rust 引擎的有序主备出口组(2–4 个 TLS / Veyra Secure 出口):失败指数退避加随机抖动、冷却结束只允许一个恢复探测、取消自动释放探测资格、旧并发结果不能覆盖新故障状态。握手耗时平滑统计用于观测,不据此擅自重排用户设定的主备顺序。

故障切换作用于新连接,不重放业务载荷,不承诺既有 TCP 无缝迁移;QUIC、多跳、带宽融合、nftables/iptables/Realm 不冒称已经接入此调度层。没有算法能保证不被封禁、不被线路阻断或绝对零丢包,线路表现仍需同一路径实际验证。

维护工具修复:适用范围与操作顺序

面板 0.7.16 在「服务器节点 → Agent 管理 → 状态与修复」提供固定校验的修复命令。卡片也可直接点击「修复旧版维护工具」。这是 HaloRelay 标准 Linux 原生 Agent 的维护工具,不是通用系统修复器。

情况正确操作
旧卸载命令提示「存在尚未完成的程序切换」,且并无正在执行的更新先修复维护工具,再预览完整卸载计划
repair-connection 提示未知操作或缺少连接工具先修复维护工具,再运行连接检查
首次安装提示发现原生安装或保留配置改用「备份重装」命令,命令包含 --reinstall
尚未安装 Agent 的空白服务器使用「首次安装」,无需修复工具
Docker、非标准目录、自定义安装或共享组件布局不明按原部署方式检查;修复器会拒绝不符合条件的布局
有正在运行的更新、卸载或维护任务等待任务完成;不要删除锁、强行杀进程或直接删除目录
HTTPS 证书无效、端口跳转、令牌失效、网络不可达先查看连接检查结果,按对应章节处理;替换维护工具不会修复这些问题

修复命令下载并固定校验四个公开文件;任何下载、HTTP 状态或摘要不符都会停止,不执行修复器。校验通过后只备份和替换卸载工具、连接工具、管理入口三项文件,不升级 Agent,不删除节点数据,也不自动卸载。修复器检查 root 权限、安装归属、路径及维护锁;检查失败应根据原因处理。

Agent 版本与维护工具版本分开显示。Agent 0.7.16 上报三个维护文件的摘要,约每 60 秒刷新一次;面板仅在全部匹配发布者固定摘要时显示工具版本。当前工具集为 0.7.15,因此「Agent 0.7.16 / 维护工具 0.7.15」是正常组合。这个状态来自已认证 Agent 的自报信息,并不构成主机安全认证。

显示状态含义
维护工具未上报旧 Agent 或没有有效报告,不能按 Agent 版本推断
维护工具 0.7.15三项文件匹配已发布工具集
维护工具版本未识别摘要不同,可能是旧版或本机自定义修改;先核对
维护工具待检查部分文件缺失、不可读或类型异常
未检测到原生维护工具可能是容器、手动部署或尚未安装;先确认部署方式

节点离线时显示的是最近一次上报,不能据此判断修复是否成功。修复完成后检查服务和面板连接,再等待真实心跳;旧 Agent 需要升级至 0.7.16 才能上报维护状态。实际转发还需单独验证。

若要完整卸载:在「完整卸载」页先复制预览命令,核对后执行卸载并在服务器确认。卸载只删除此 Agent 所有的程序、令牌、证书及数据,保留安装前已有的系统包、同机面板和外部文件。若随后重装出口且旧证书已删除,在「备份重装」页授权重新登记后使用新令牌。

0.7.5 等旧安装取得本版连接与卸载工具

以下完整命令在节点服务器执行;只安装本版连接修复、卸载与菜单工具,不更改令牌、不执行卸载、不切换 Agent 程序版本。每个文件先核对这里固定的 SHA256;旧工具保存在本机受保护目录,重复执行可恢复中断。

sudo bash <<'HALO_REPAIR'
set -euo pipefail
umask 077
halo_repair_dir=$(mktemp -d /root/halorelay-repair-0715.XXXXXXXX)
trap 'rm -rf -- "$halo_repair_dir"' EXIT
while read -r halo_hash halo_file; do
  curl --fail --silent --show-error --proto '=https' --tlsv1.2 --connect-timeout 15 --max-time 120 \
    "https://dl.halorelay.com:24443/repairs/0.7.15/$halo_file" -o "$halo_repair_dir/$halo_file"
  printf '%s  %s\n' "$halo_hash" "$halo_repair_dir/$halo_file" | sha256sum -c -
done <<'HALO_HASHES'
12d83e19540acda64707e1066e3bab20b77a8e9daf49a1991b47a6d217ab36d2 agent-uninstall.py
cfcb7d44be52ef6112fb5e1f396aa4d499f0c2f18d336e4114f51e252bd536b3 agent-connection.py
f91ed9bc7156778e0da5c469cee39b893a51113abdfb9fb44d6c3bf86dbc331b manage.sh
07fcdfa88192d65017ac06f6011bc0168e0aa0dd5f848997a2103da979427063 install-agent-recovery-tools.py
HALO_HASHES
python3 -I "$halo_repair_dir/install-agent-recovery-tools.py"
HALO_REPAIR

完成后先执行 sudo halorelay repair-connection agent --check。若确认是令牌失效,执行 sudo halorelay repair-connection agent --replace-token 并隐藏输入面板对应节点当前令牌;若地址已变更,可同时加 --panel-url。不要将私有下载令牌当成 Agent Token。

低内存节点安装失败:MemoryError

如果发行文件下载、签名和 SHA256 均已通过,但在“检查安装环境”阶段出现 Python gzip.py 的 MemoryError,说明旧安装器的解压峰值超过了节点可用内存。0.7.17 已将校验和 tar 解包改为有界流式处理,不再同时保留整包和完整解压内容。

请先把面板更新到 0.7.17,再从节点卡片复制最新安装命令。无需重新创建节点或更换下载令牌。仍失败时保留具体错误,并检查:

free -h
df -h /tmp /opt
sudo systemctl status halo-agent --no-pager

磁盘、证书、面板地址、Agent Token 和云安全组问题不属于内存解包修复范围,应按错误现场处理。