HaloRelay
HALORELAY · 使用与维护

故障知识库

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

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

历史故障快速索引

下面的条目来自 HaloRelay 已经遇到并修复过的真实运维问题。先按现象定位,再按“先检查、后修复、最后验收”的顺序处理。任何安装器或维护工具报错时,都先保留当前版本和数据,不要连续覆盖安装。

看到的现象常见原因先做什么详细步骤
授权站升级报“源码包存在未列入清单的文件”0.3.6 发行包混入工作站附属文件保留现有安装,使用原命令更新到 0.3.7授权站升级修复
授权站更新下载报 401运营者下载密码与客户 Token 混用或权限无效按组件确认凭据类型授权站下载认证
手机 App 导入失败、名称或图标不对安装包类型、签名或旧包缓存问题区分主站 App 与授权中心,核对真机包iOS 使用与导入
换 SSL 后全部节点离线24443 监听或跳转被改写检查 HTTPS 健康响应,保留现场证书更换
卸载提示程序切换未完成旧维护工具和待完成激活记录更新可信维护工具后预览清理卸载卡住
改面板地址后旧节点失联新地址尚未分发或旧入口已关闭保留旧地址并分批升级地址迁移
套餐已付款却没有节点旧版权益未授予套餐节点面板升级到 0.7.14 或以上套餐节点
Docker 面板更新失败 401下载 Token 缺失、被撤销或已过期修复/重新保存下载凭据Docker 更新 401
下载很慢、超时或中途断开受限线路、读取超时、代理端口不匹配只保留一个安装进程,检查 HTTPS 和完整下载慢速下载
24443 总是跳回 443宝塔按端口强制跳转把“非 443 跳转”改为“HTTP 才跳转”24443 跳转
节点安装准入失败Token、角色、面板地址或授权不匹配使用当前节点生成的新命令准入失败
下载和签名通过后出现 MemoryError旧安装器同时把压缩包和完整 tar 读入内存更新到 0.7.18,再复制当前安装命令低内存安装
重装要求交互确认、或重装后证书冲突缺少真实终端、旧证书仍受信任在 SSH 交互终端按对应重装流程处理重装与证书
nftables、iptables、Realm 不可选依赖、权限、内核或旧 Agent 状态未准备好更新 Agent 后查看引擎能力和日志引擎依赖
公网 IPv4 为空、IX 地址不能填写NAT 元数据超时或过度限制地址类型区分出网地址与服务商可连入地址地址发现
面板更新后仍是旧版本只推送了源码,未发布签名包或未更新生产按组件核对版本、任务和健康状态更新生命周期
订阅里没有协议节点或已部署节点来源未分配给客户、节点仍在部署或订阅绑定已过期刷新来源状态并重新保存订阅订阅交付
Snell v6 只有 Surge,或参数不完整Snell 没有通用 URI,客户端字段未保存选择 Surge,并补齐服务端实际参数订阅交付
节点检测显示端口通但业务仍不可用TCP 检测不验证代理认证再做客户端、UDP、长连接和吞吐验收订阅交付

Agent 更新了,为什么仍无法卸载或重装?

Agent 程序与固定在主机上的管理、连接和卸载工具分别维护。Agent 版本已更新,不代表旧的卸载判断已经替换。0.7.16 面板提供独立状态与修复入口,详情见维护工具修复指南。

「发现原生安装或保留配置」说明用的是首次安装入口,应改用「备份重装」中的 --reinstall 命令。若旧卸载工具提示未完成程序切换,先检查是否真的有更新在运行;没有活动更新时,修复旧工具后重新预览。不要手动删除目录、锁或证书来绕过检查。

三种凭据为什么不能混用?

软件授权码用于验证你的面板许可;下载 Token 用于取得私有发行文件;Agent Token 属于一个节点,用于该节点接入面板。密码、授权码、下载 Token 和节点 Token 都不能相互替代。丢失或撤销后到对应系统重新获取,不把令牌写进 URL 查询参数或公开工单。

授权站删除下载凭据后会发生什么?

在授权站“全部下载凭据”中点击“删除”会先撤销该凭据的下载权限,再将它从正常列表归档。旧 Token 不能继续下载,记录不会被物理抹除;审计日志仍保留关联编号、名称、操作者、来源 IP、访问设备和时间,便于追查。重复删除是幂等操作。

下载凭据和商业软件授权是两个独立对象。删除下载凭据不会按名称猜测并撤销同名商业授权,避免误伤客户的有效许可;如果确实要撤销商业授权,应在“商业授权”中单独执行撤销。

授权站为什么显示“有新版本”?

超级管理员登录后可查看当前授权站管理器版本;只有通过签名校验的新版本才会触发更新提醒。更新命令由本机程序固定提供,远端清单不能下发任意命令。检查失败不会伪造“已是最新版”;成功检查有缓存,刚发布时可以直接执行更新命令,无需等卡片刷新。

更新前先备份授权数据库和独立密码文件,再执行:

sudo halorelay-license update
sudo halorelay-license status

更新完成后确认容器健康、管理员可以登录、下载凭据列表和审计日志可分页查看。授权站更新不会自动升级转发面板或 Agent;三个系统必须分别验收。

授权站更新报“源码包存在未列入清单的文件”

这是已确认并在授权站 0.3.7 修复的发布打包问题:0.3.6 安装包混入 macOS 自动生成的 ._ 附属文件,导致严格文件清单检查拒绝继续。提示中提到 .env、私钥 是通用保护说明,并不表示你的服务器泄露了这些文件,也不是输入下载密码错误。

在授权站所在服务器重新执行原命令,输入原来的运营者下载密码:

sudo halorelay-license update

本次错误发生在候选文件校验阶段,尚未停止原站或切换版本。无需卸载、删配置、清空数据库或重新生成签发私钥。0.3.7 已用原版 0.3.5、0.3.6 更新器在 Linux 验证签名、大小、摘要、解包和完整文件清单;今后的发布流程也校验最终压缩包。

更新结束应显示 更新完成:0.3.7,再执行状态检查,重新打开后台核对版本和原授权记录:

sudo halorelay-license status

如果后续版本出现相同提示,保留版本与完整报错交给发行方核对,不自行放宽清单检查或添加未知文件白名单。如果转为构建、启动或健康检查错误,应按新错误处理,不能当成本次打包问题重复操作。

授权站更新和 Docker 面板更新的 401 一样吗?

不一样,先看你执行的命令和失败阶段。授权站更新使用运营者发行包下载密码;客户的下载 Token、软件授权码、Agent Token 都不能替代它。

出错位置应核对的凭据下一步
halorelay-license update 下载发行包运营者下载密码在隐藏提示处输入有效密码,向发行方确认运营者下载权限
halorelay update panel 下载发行包私有下载 Token按 Docker 更新 401 修复保存的下载凭据
节点接入或心跳 401当前节点 Agent Token按 节点身份修复 核对节点并更新 Token

不要把令牌字符串当成文件名创建空文件。下载地址本来需要认证,直接在浏览器打开私有发行包得到 401 不能单独证明更新服务故障。

主站和授权站为什么名称不同?

HaloRelay 是转发面板,管理节点、规则和客户业务;HaloRelay License 是授权中心,管理软件授权、下载凭据与相关订单。两个系统独立登录、备份和更新,版本号不要求相同。

授权站 0.3.7 将未自定义的旧默认站名迁移为 HaloRelay License,保留运营者明确设置的自定义名称。名称和图标可在各自站点设置中配置;修改网页品牌不会自动替换已经安装的 iOS App 图标或应用名称。

iOS App 导入失败、没有图标怎么办?

移动端先用浏览器打开自己的 HTTPS 面板确认账号、证书和网络正常。HaloRelay iOS App 是面板的访问入口,业务仍由服务器运行,不是手机端转发引擎;授权中心仍使用它自己的地址和账号。

  1. 若拿到 IPA,请确认是面向 iPhone 真机的完整包,不能使用模拟器构建产物,也不能把压缩文件改扩展名冒充 IPA。重新取得原始文件后再导入。
  2. “签名工具导入成功”和“iPhone 可以安装运行”是不同阶段。真机仍需适用于该设备及分发方式的有效签名与描述文件;仅知道 iOS 为 18.3.1 不足以判断兼容。
  3. 无图标或仍显示旧名时,核对安装的包版本、所连接的站点,以及是否保留了旧的主屏幕网页快捷方式。网页图标与原生 App 图标分别配置;不要把授权站名称写进主站 App。
  4. 若仍失败,提供应用包名称、版本、系统版本和完整错误文字。不要发送 Apple 签名私钥、证书密码、面板密码或完整订阅链接。

可先使用移动浏览器继续管理。官网未提供公开签名 IPA 下载时,不把本地构建产物当作已经上架或所有签名工具均兼容的正式发行版。企业内部应用的信任要求见 Apple 安装与验证说明,其他分发方式按各自签名流程处理。

授权站审计日志记录哪些内容?

审计日志记录实际的操作类型、关联对象名称与 ID、来源 IP、访问设备、详情和时间,并支持日期筛选、每页数量切换和跳页。可信反向代理必须在授权站服务端明确配置;未配置时只采用实际连接对端,不能把访客自报的 X-Forwarded-For 当成真实来源。

密码、完整 Token、私钥和下载链接中的敏感值不会写入日志。列表中删除下载凭据后保留的审计墓碑用于证明撤销动作,不代表凭据仍然有效。

我需要自己搭建官网、授权站和下载站吗?

普通购买者无需搭建官方运营系统。你部署自己的面板与节点,使用官方客户中心取得授权和下载凭据。面板里的套餐是你向自己的客户交付业务的套餐,与官方软件授权订单不同。

公网 IP 没有自动显示,是否 Agent 坏了?

不一定。NAT 主机接口可能没有公网地址,云元数据接口可能超时,面板也可能无法从可信反代链取得公网来源。先看 Agent 版本和最近心跳,再对照服务商控制台的可连入地址手动补充。公网探测得到的“出网 IP”不能直接当作可入站地址。

为什么前海 IX 的地址看起来像公网,却能填在专线里?

“内网 / 专线”表示你选择的连接用途,并不保证这个地址属于 RFC1918。新版手动字段接受合适的单播专线地址,适用于不同服务商,不是只给某个 IP 放行。入口仍必须具备服务商允许的线路、白名单和端口映射。填写地址不会自动开通路由。

“内网 / 专线已启用”表示连接正常吗?

这条提示说明配置选择了指定接入地址;并不证明 TCP/UDP 握手或业务已成功。证书验证仍保持开启。检查实际相邻节点的隧道端口及真实规则回执,再用客户端验证。

“出口隧道地址或证书配置不完整”怎么办?

查看出口是否有近期心跳,核对连接地址、端口、证书绑定名称和公开验证证书。首次安装应自动登记;保留配置重装应复用匹配证书;完整卸载后的出口需先在“安装 / 管理”授权重新登记,再用新 Token 安装。不要把证书私钥贴到面板,也不要关闭校验。

为什么重装后的新证书不能自动覆盖旧证书?

如果任何带旧 Token 的心跳都能更换信任,冒充者也可能替换出口。面板保留原证书是在保护节点身份。你确认机器与重装事实后,使用“完整卸载后重装:授权重新登记”完成受控更换。单纯改 IP 不要求重置证书。

“节点安装准入失败”应该先查什么?

按安装器给的错误类别处理:301/302 查 HTTPS 跳转;超时查地址、监听和防火墙;401 查当前节点 Token;403 查许可证与额度;编号/角色不匹配重新复制目标节点指令。删除再创建节点后不能用原 node-id。先修复准入,不绕过安装预检查。

PO0 能访问 24443,安装为什么还去 443?

通常是面板反代把 HTTPS 24443 重定向回 443,或只改了回连地址没切换下载通道。两者都要核对。宝塔的“非 443 就跳转”应改为“HTTP 才跳转”,并确认云安全组与本机端口放行。按 受限网络指南 从真实节点验证。

Cloudflare 小黄云能解决所有下载和端口问题吗?

不能。普通代理有支持端口限制,且下载鉴权、缓存策略、证书链和线路质量都需要测试。24443 直连通常使用 DNS-only 与公开可信证书;是否换 CDN 应比较该节点的完整下载速度、失败率和签名校验结果,不能只看一次 HEAD 200。

下载 HTTP 200 了,为什么仍提示失败?

HTTP 200 是响应状态,下载可能在中途断开,或大小/摘要/签名/有效期不匹配。保留最后错误和已下载字节数,检查系统时间、磁盘、证书、下载权限和所选固定通道。不要使用 -k、跳过签名或将未知包重新打包来强行安装。

安装没有动静,是卡住了吗?

新安装器按准入、下载校验、依赖准备、安装与健康检查显示进度。小文件和运行包的超时预算不同,慢线路下载可能持续较长时间。看当前阶段、已收到的响应和进度;确认超时后只运行一个安装进程,避免同时重试覆盖现场。

“需要交互终端确认重装”如何处理?

重装需要人在实际节点终端确认清理/备份计划。把面板完整命令复制到交互 SSH 会话,按提示输入确认,不用后台定时任务或缺少终端的管道模拟确认。取消会保留现有安装;先解决网络或令牌错误再继续。

为什么 nftables / iptables / Realm 不能选?

检查 Agent 上报的引擎能力与版本。新版标准安装会准备依赖和权限,旧节点只更新二进制未必安装系统包或刷新固定工具。包管理器错误、内核模块、容器限制、IPv6 或不兼容策略也会使引擎不可用。按面板“准备引擎”命令修复后等新心跳,使用同一路径对照验证。

一键升级全部 Agent,会不会保证全部成功?

批量操作会提交符合条件的节点任务,每台仍有网络、下载凭据、固定更新器和兼容检查。离线或条件不足的节点需单独处理。检查每台任务最终状态和实际版本,不能把“提交成功”当成全部完成。先测试一台备用节点更容易发现环境差异。

为什么线上还是旧版本?源码不是已经推送了吗?

源码提交、签名运行包发布、官网部署、授权站部署、面板升级和 Agent 升级各自独立。只推送 Git 不会自动替换生产容器或节点程序;没有签名目录中的目标版本就不能把源码标签当作可安装包。根据你要更新的服务使用对应流程。

订阅为什么没有显示我选择的节点?

订阅来源必须属于当前客户,并且处于可交付状态。协议节点要等待 Agent 回报运行,已部署节点要保持启用;重新拉取时系统还会复核套餐、节点归属、转发绑定和凭据指纹。修改了入口端口或撤销了节点后,旧订阅不会继续输出过期地址,重新保存或轮换链接即可。

有标准 URI 的节点可以使用原始、Base64、Mihomo 或 sing-box;Snell 没有通用 URI,仅提供 Surge 文本。Loon / Quantumult X 只导出本版能完整表达的协议。客户端格式只输出系统实际掌握的字段,不会用源站地址或猜测参数生成伪配置。

默认检测是本站面板到节点的 TCP 端口检查,不验证代理密码。HTTP / SOCKS5 可另外选择通过该代理访问测试 URL,默认 http://1.1.1.1/generate_204;其他协议请在对应客户端验证认证和网页访问。检测不代表客户网络、UDP、长连接或吞吐表现。测试地址只允许公开 HTTP/HTTPS,拒绝内网、回环、保留地址与包含账号密码的 URL,且不跟随跳转。

更新失败回到旧版,能直接强行再试吗?

先看最终错误、恢复记录、当前健康状态和连续心跳。版本不兼容或数据库格式变化时不能绕过保护。确认备份、原下载凭据、磁盘与主机工具满足要求后再重试;程序回退不会把订单和用量恢复成过去。

卸载为什么没有删除面板里的节点?

本机卸载删除服务器上的 Agent 所属安装;面板节点记录是远程配置,两者分开。如果退役该节点,应迁移业务、停止进程、撤销/删除面板记录,再核对主机卸载。重装保留同一记录时按证书与 Token 流程处理。

“卸载干净”是否等于把服务器恢复出厂?

不是恢复系统快照。完整卸载移除可证明属于本次 Agent 安装的程序、配置、凭据与独占维护文件;共享系统包、其他应用、系统日志、外部证书及无法确认归属的内容不能盲目删除。遇到未知文件或共享组件时会停止并列出原因,不能用强删目录掩盖风险。

为什么节点流量和套餐用量不同?

网卡统计包含整台机器其他流量;节点规则汇总、客户规则计费和套餐倍率是不同口径。单向按周期累计上下行较大值,双向按累计之和,再按适用倍率计算。节点重置策略与客户订阅周期分别配置,先对照当期和账单口径再判断异常。

设置了到期日期,是否会自动续费或月清零?

到期、月度流量重置和续费不同。选择“按到期日”才用到期日期的日号计算重置;选择“不重置”不会自动月清零。到期需要实际续期或有效权益,不能因为重置额度就继续无限使用。

单连接带宽为什么达不到两条线路之和?

多入口、多个目标或主备出口不等于同一连接聚合。实验 TCP 融合也受共同瓶颈、时延差、重排、CPU 和目标速度限制。固定客户端到入口、入口到出口、出口到目标三段做同路径对照,不用不同测速目标的两个峰值直接比较。

面板宕机后业务是否永久继续?

不能这样承诺。业务执行在 Agent,控制面暂时不可达与许可/控制租约最终到期是不同阶段。实际行为按节点状态和有效租约执行。准备备用链路、监控和恢复演练;当前不是自动多主控制面集群。

能保证无人盗用、无法破解吗?

不能作绝对承诺。系统通过授权签名、短租约、下载鉴权、资源权限、凭据隔离和审计降低滥用风险。拥有主机 root 的人控制本地环境。管理端仍应使用强密码、最小权限、及时更新和异地备份,不公开私钥或管理入口资料。

需要支持时,提供什么最有用?

提供发生时间与时区、面板/Agent 实际版本、相关节点和规则名称、操作步骤、期望结果、实际错误、是否 TCP/UDP、脱敏日志及你已做的检查。不要发送服务器密码、完整 Token、订阅链接、私钥或整个数据库。先保留现场,避免为同一错误反复重装。

Docker 面板更新失败 401

401 代表发行服务拒绝了下载凭据,通常是旧版没有保存下载 Token、Token 文件被清空,或授权已撤销/到期。这不是面板业务数据损坏,也不需要删除数据目录或重新初始化数据库。

  1. 在面板服务器的真实 SSH 终端执行 sudo halorelay repair-token panel,按隐藏提示输入授权站中的“下载凭据”。不要输入软件授权码,不要加 Bearer 、引号或空格,也不要把 Token 放进命令参数、URL、截图或工单。

如果旧版工具没有这个子命令,再创建固定凭据文件:

sudo install -d -m 0700 /opt/halorelay-docker
sudo test -e /opt/halorelay-docker/release-download-token || sudo install -m 0600 /dev/null /opt/halorelay-docker/release-download-token
sudoedit /opt/halorelay-docker/release-download-token

编辑器中只粘贴凭据原文并保存;不要把 Token 当作文件名。维护工具只读取 release-download-token。

  1. 凭据修复完成后执行 sudo halorelay update panel latest。更新任务会再次检查清单、签名、摘要、架构、兼容性和业务备份;其中任何一项失败都会保留旧版本。
  2. 用 sudo halorelay status panel 和 sudo halorelay history panel 确认任务成功、当前版本变化及健康检查通过,再回网页检查登录、规则、节点心跳和实际转发。

如果授权站已经撤销或到期,服务器无法恢复旧 Token,需要由授权管理员重新签发。403 通常对应授权或额度,404 对应版本/资产不存在,429 对应频率限制;先处理对应原因,不要反复点击更新。不要用 curl -L 跟随未知跳转,也不要用 -k 关闭证书校验。

Docker 维护菜单命令不完整

不同年代的固定维护工具接受的参数可能不同;当前源码支持部分简写。若输入命令后看到“Docker 管理仅接受操作、panel 及目标版本/--dry-run”。先在真实终端逐条执行下面的完整格式,切勿把多条命令连成同一行:

sudo halorelay status panel
sudo halorelay logs panel
sudo halorelay update panel latest
sudo halorelay rollback panel <本机已有的兼容版本>

若完整命令仍报同样错误,记录实际入口路径 command -v halorelay 和错误,按部署版本刷新固定主机工具;不要继续猜参数,也不要删除数据。

如果使用交互菜单,就先执行 sudo halorelay,再按菜单提示选择 panel 和目标版本;不要把菜单编号当成命令参数。任务显示“已提交”不等于已经完成,必须继续查看最终状态和实际版本。

慢速下载、超时或完整包校验失败

安装包 HEAD 返回 200 只说明服务器开始响应,不代表整个文件已经下载完成。受限线路可能需要较长时间;安装器会分别限制连接等待、读取停滞和完整下载总时长,并在结束时校验大小、SHA256 和签名。

  1. 先检查节点到面板和下载通道的 DNS、证书、路由、安全组及端口,确认没有 301/302。不要用跟随跳转掩盖地址问题。
  2. 只运行一个安装或更新进程。若当前进程仍在显示下载进度,应等待其完成;确认已经超时后再清理临时文件并重试一次。
  3. 下载完成后必须看到“签名、版本、大小和 SHA256 校验通过”,仅看到 HTTP 200 或下载了部分字节都不算成功。

若同一路径反复出现读取停滞,应记录版本、连接耗时、已下载字节数和最终错误,再检查出口防火墙与服务商线路。不要关闭 TLS、跳过签名或重新打包发行文件。更换 CDN 前先确认它支持所用 HTTPS 端口、完整响应、鉴权头和证书链;24443 直连一般使用 DNS-only。

24443 被宝塔跳回 443

当面板监听了 24443 ssl,但安装器仍收到跳转到 443,通常是宝塔站点配置中的端口条件写成了“不是 443 就跳转”。它会把合法的 HTTPS 24443 也当成错误请求。

  1. 在面板服务器宝塔对应站点的配置文件中,保留原有 listen 443 ssl、证书和反代,只增加 listen 24443 ssl,并确认云安全组和本机防火墙放行 TCP 24443。
  2. 把错误条件改成只对 HTTP 跳转:
# 错误:HTTPS 24443 也会被跳回 443
if ($server_port != 443) { return 301 https://$host$request_uri; }

# 正确:只将 HTTP 请求升级到 HTTPS
if ($scheme = http) { return 301 https://$host$request_uri; }
  1. 在宝塔执行配置检测成功后再重载 Nginx。外部检查应看到 HTTPS 24443 直接返回健康响应或鉴权响应,且没有 Location;不要用 -L 隐藏跳转。证书必须覆盖访问域名,不能用 -k 绕过校验。

节点安装准入失败

“请检查节点 Token、角色、HTTPS 面板地址及有效软件授权”表示安装器在写入系统前就拒绝了请求。常见原因是复制了旧节点命令、节点角色与命令不一致、面板地址有跳转、授权已过期,或把下载 Token 当成 Agent Token。

  1. 在面板中打开目标节点,确认角色、编号、当前 Token、面板公开访问地址和授权状态。
  2. 重新复制该节点当前生成的安装命令;删除并重新创建节点后,必须使用新编号和新 Token,旧命令不能复用。
  3. 从待安装服务器先检查 HTTPS 健康接口、证书和跳转,再执行安装。准入失败时不会写入系统,也不需要先强制卸载。
  4. Agent Token、软件授权码和发行下载 Token 用途不同,不能互换。解决准入错误后再执行一次安装,不要同时启动多个安装器。

交互式重装、完整卸载与证书重登记

提示“需要交互终端确认重装”是为了让管理员明确选择清理/保留计划。请在目标服务器的交互 SSH 会话中运行面板生成的命令,按提示确认;后台任务、无终端管道和自动重试不能代替确认。取消操作会保留现有安装。

纯入口节点可以按当前 Token 重装;重置 Token 或删除重建节点后要使用新的 Token。出口/双角色节点在完整卸载后会删除本机生成的私钥,重新安装前需由管理员明确授权重新登记;私钥不会上传到面板。

完整卸载只删除 Agent 明确拥有的程序、配置、凭据、证书、服务和独占运行数据。安装前已经存在的用户、共享系统包、其他应用、外部证书和独立 Docker 面板不会被猜测删除。面板里的节点记录是远程配置,需另外停用或删除。卸载完成后用面板新命令重新安装并验收服务、版本、心跳和真实转发。

nftables、iptables、Realm 不可选

标准 Agent 安装会检查并准备所需依赖、权限和签名发行包内的 Realm;它不会擅自清空已有防火墙规则,也不会因为显示已准备就替你启动防火墙服务。引擎不可选时,常见原因是包管理器失败、内核/容器能力不足、运行用户权限、旧 Agent 没有刷新能力上报,或心跳尚未更新。

先核对 sudo halorelay status agent、Agent 实际版本和最近日志;修复依赖后重启 Agent,等待新的心跳,再回面板查看能力。不要手工删除现有规则来“腾出空间”,也不要把实验性引擎当作生产可用;每种引擎都要用同一路径做真实 TCP/UDP 验收。

公网 IPv4 为空、IX/专线地址无法填写

有 NAT 的云主机可能只有内网地址,云元数据接口也可能超时;这不代表 Agent 离线。面板显示的出网 IPv4 只是探测结果,不能自动当成服务商允许连入的地址。请从服务商控制台确认实际可连入 IPv4、映射端口和白名单,再手动补充。

“内网 / 专线”是连接用途,不等于 RFC1918 私有地址。合适的单播 IX/专线地址可以填写,不能只针对某个 IP 放行;填写地址不会自动建立路由、端口映射或供应商白名单。入口与出口的地址、证书、端口和角色仍需分别核验。

出口证书自动登记需要出口 Agent 心跳上报公开 CA、公开证书和监听端口。证书名称、公开验证证书和连接端口不完整时,先检查出口心跳和服务商映射,不要粘贴私钥,也不要用普通重装请求覆盖已保存的信任资料。

源码已更新但线上仍是旧版本

Git 提交、签名发行包、下载站、官网、授权站、面板容器和 Agent 是不同的发布环节。推送源码不会自动替换生产容器,也不会让节点跳过签名清单直接更新。

按实际组件验收:先确认目标版本已经生成并发布到正确发行通道,再在对应服务器查看维护任务、当前版本、健康检查、数据库备份和后续心跳。更新失败时旧版本继续运行是保护行为;确认兼容性和备份后再重试。回退只能使用本机已有且经过验证的兼容版本,不能把业务数据库、订单和用量回到过去的状态。

如何提交一份安全的排障信息

提供发生时间和时区、面板/Agent 版本、节点或规则名称、操作步骤、完整错误标题、是否 TCP/UDP、脱敏后的相关日志和已经完成的检查。不要发送服务器密码、完整 Token、订阅链接、私钥、数据库备份或带凭据的 URL。保留现场比连续重装更有助于定位问题。

更换宝塔 SSL 后节点全部离线

已遇到的原因是宝塔重新生成“非 443 就跳转”的配置,将合法 HTTPS 24443 重定向到 443;受限节点无法访问 443。仅换同域名可信证书不应要求重新安装节点。

先从节点检查自己的面板地址,不携带任何令牌:

curl --proto '=https' --connect-timeout 15 --max-time 30 -sS -D - -o /dev/null https://panel.example.com:24443/api/health

把示例域名替换为自己的域名。HTTP 200 且无 Location 才表示健康入口直接可用;301/302 修跳转,证书错误修链和域名/时钟,超时查 DNS、端口和防火墙。不要添加 -L 或 -k。具体宝塔操作、独立端口方案与回滚见 证书恢复专题。修复后验收连续心跳与真实流量,网页刷新一次不足以证明恢复。

Agent Token 已失效但进程仍运行

Agent 的 401 和下载站的 401 是两种故障。前者验证节点身份,后者验证取得私有安装包的权限。0.7.18 收到拒绝后停止转发并保留重试,不会重新启用已经撤销的令牌。

在面板确认对应节点的当前 Token,再在该服务器使用 sudo halorelay repair-connection agent --replace-token,隐藏输入并确认节点身份;若命令不存在,先按 旧工具恢复 更新维护工具。准入成功后保存并重启,再检查心跳与转发。不要用下载 Token 替代 Agent Token。

卸载提示存在尚未完成的程序切换

旧更新器在新版本与回退版本均不健康时可能保留 pending_activation。旧卸载器要求先恢复健康,形成“需要重装却卸不掉”的状态。

0.7.15 的可信维护工具会在独占锁下校验本 Agent 的切换记录,停止服务并取消已确认的失败切换,再清理归属明确的文件。先安装 旧工具恢复包,再运行 sudo halorelay uninstall agent --complete --dry-run,核对后执行完整卸载。正在进行的维护、异常路径、其他组件或未知归属仍会拒绝。不要手删状态文件或整个 /opt 目录。

验收包括服务停止、自有配置与凭据已清理、其他应用仍正常;重新安装使用面板当前节点命令,出口按要求授权重新登记证书。

提示发现原生安装或保留配置

这是首次安装入口检测到现有安装后的保护,不表示应该先删除目录。更新版本用 sudo halorelay update agent 0.7.18;仅修面板地址或令牌用连接修复工具;明确要重装才从面板复制带 --reinstall 的当前命令,在交互终端核对备份计划。先修网络和身份,避免用重装掩盖共同入口故障。

修改节点可访问的面板地址会怎样

0.7.18 新节点通过已认证心跳接收和缓存最多四个批准入口。先开通新入口,保留旧入口,升级面板与 Agent,然后保存新地址。确认各节点实际迁入且重启后仍能接入,才停用旧入口。

旧节点或已经失联的节点需要本机修复。跨域名还要处理商业授权绑定,自动备用入口不解除许可要求。完整步骤见 地址迁移。

套餐已付款却没有可用服务器

0.7.14 修复了套餐节点仍依赖管理员单独分配的问题。升级面板到 0.7.18 后,已付款且有效的订单按下单时套餐快照授予节点;套餐未选节点时沿用单独授权。无需为该修复升级 Agent。

检查订单已确认收款、账号和订阅有效、订单快照包含节点;编辑套餐不会追溯改写历史订单。账号和套餐的其他限制仍取适用的更严格值,例如账号规则上限 20、套餐上限 100 时,实际仍是 20。验收用客户视角确认节点列表、规则创建及到期撤权。

当前没有兼容新版本或未列出目标版本

先核对面板实际版本、Linux 架构、配置的下载通道和“检查新版本”结果。0.7.18 已发布 Linux x64 面板与 Agent;源码版本、网页文案或其他架构包不能替代对应的签名发行项。检查系统时间、清单签名有效期和最低版本限制,不修改清单来强行出现目标。

下载权限正常但仍没有目标时,保留错误与当前架构,按 更新说明 逐组件排查。更新任务已提交或源码已上传都不等于机器已运行新版。

下载和签名通过后出现 MemoryError

如果日志已经显示发行包 HTTP 200、签名和 SHA256 全部通过,随后在“检查安装环境”阶段出现 Python gzip.py 的 MemoryError,故障点是旧安装器的解压峰值,不是 Token、授权或下载凭据。旧版本会同时保留压缩包和完整解压内容;小规格节点可能因此失败。

0.7.17 改为有界流式 SHA256 和 tar 解包,每次只保留一个 512 字节头和最多 1 MiB 文件块,同时保留路径、类型、大小、签名和架构检查。面板先更新到 0.7.17,再从“服务器节点”复制最新命令;不要在同一台机器上重复并行下载旧入口。

若错误不再是 MemoryError,按新的具体原因处理:磁盘错误检查 /tmp 和 /opt,服务启动错误查看 systemd 状态,身份错误重新核对 Agent Token。完整说明见0.7.17 低内存节点安装修复。

开机时长 流量与日志信息没有出现

先核对 Agent 实际版本及最近心跳。网卡累计上传/下载、实时速率、整机开机时长来自节点上报;规则计费是另一套统计。月度额度需要明确选择重置策略,无到期日的新节点默认不重置,带到期日的新节点默认按日号建立周期,旧节点原设置保持不变。

来源 IP 只有在可信反向代理链正确配置时才可采信。访问设备通常是 User-Agent 提示,不能当成硬件身份。历史记录缺少的来源和设备不能凭空补造;新增操作应核对时间、对象名称与 ID、来源和详情,并检查筛选时间与分页。不要为显示真实 IP 信任全网转发头。

这些算法能保证不封禁和不丢包吗

不能。Veyra Secure 保护节点间身份与传输,Guard 减少故障路径的重复握手并选择可用备用出口;QUIC DATAGRAM 不重传业务 UDP。具体场景、性能比较与不支持的组合见 Veyra 协议与算法指南。服务商线路准入、平台规则、真实丢包和共同上游瓶颈仍需独立处理。

订阅格式为何只剩 Surge?如何删除订阅?

0.7.18 会取所选节点共同支持的格式,混入 Snell 后可能只剩 Surge。升级面板到 0.7.19 后,格式入口固定显示原始链接、Base64、Mihomo、sing-box、Surge、Loon、Quantumult X。切换格式会显示兼容及跳过数量,无兼容节点时无法复制。无需重建已有订阅;Snell 不会转换成不支持它的客户端格式。

管理客户端订阅新增“删除”:确认后所有旧链接失效,记录移除,保留操作审计。它不会删除服务器、节点或转发规则,也不会收回已下载到客户端的凭据;凭据泄露时还需更换节点凭据。