HaloRelay
HALORELAY · 使用与维护

部署指南

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

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

开始前:你需要准备什么

普通客户只需要部署自己的转发面板与节点,不需要搭建官方授权站或下载站。

项目准备与检查
面板服务器受支持的 Linux,建议从 2 核、2 GiB 内存起步;内置数据库和业务规模会增加需求
节点服务器能运行当前签名 Agent 架构;标准安装使用 Linux systemd;具备管理员权限
域名自己的面板域名,解析到面板服务器,HTTPS 证书可信且覆盖该域名
三种凭据软件授权码、私有下载令牌;节点创建后再取得该节点 Agent Token
网络面板能访问授权与发行服务;节点能访问面板、下载通道及业务目标
安全组与防火墙按实际配置放行 HTTPS 管理端口与业务 TCP/UDP 端口;数据库不公开
安装材料官方当前安装命令及其固定校验摘要;不要使用工单里的旧节点命令

建议 Debian / Ubuntu 标准环境。发行包必须与你的 CPU 架构匹配,x64 包不能当成 arm64 包使用。选择 MySQL/PostgreSQL 时,还要准备对应数据库或可获取数据库镜像的环境。

文中 panel.example.com 都需要替换为你自己的面板域名。只有执行后收到成功输出并完成实际验收,才算安装完成。

安装入口 默认安装最新兼容签名版本

普通 Linux 面板服务器执行;Agent 从面板复制专用指令。先完整取得入口再执行,下载运行包仍须校验签名、大小和摘要。

bash -c 's=$(curl -fsS https://get.halorelay.com) && bash -c "$s"'
展开固定摘要的完整校验命令
bash -c 'set -eu; umask 077; f=$(mktemp); trap '"'"'rm -f -- "$f"'"'"' EXIT; curl --fail --silent --show-error --proto '"'"'=https'"'"' --tlsv1.2 --connect-timeout 15 --max-time 120 --output "$f" "$2"; printf '"'"'%s  %s\n'"'"' "$1" "$f" | sha256sum -c - >/dev/null; if [ "$(id -u)" -eq 0 ]; then bash "$f"; else sudo bash "$f"; fi' halo-bootstrap '234a5177e4c896db1496ae4601ae45d5d46f1d357a2a8386d231d0dec1b83b97' 'https://dl.halorelay.com/repairs/0.7.19/bootstrap.sh'
受限网络面板服务器使用 24443 下载
bash -c 'set -eu; umask 077; f=$(mktemp); trap '"'"'rm -f -- "$f"'"'"' EXIT; curl --fail --silent --show-error --proto '"'"'=https'"'"' --tlsv1.2 --connect-timeout 15 --max-time 120 --output "$f" "$2"; printf '"'"'%s  %s\n'"'"' "$1" "$f" | sha256sum -c - >/dev/null; if [ "$(id -u)" -eq 0 ]; then bash "$f"; else sudo bash "$f"; fi' halo-bootstrap '30eb28eadc2fb840d37785a0f30cdb01864deb20983420b680755980ba935fdf' 'https://dl.halorelay.com:24443/repairs/0.7.19/bootstrap.sh'

第一步:安装你自己的面板

  1. 在官方授权客户中心取得有效软件授权与下载凭据。确认授权域名、期限及节点额度。
  2. 获取官网或购买交付页提供的当前面板安装命令。命令应绑定官方 HTTPS 安装入口和固定 SHA256;不要用随意拼接的 curl | bash 替代校验流程。

官网展示的安装入口默认请求签名发行目录中的 latest,完整校验命令会下载临时脚本并核对固定 SHA256;它不会把版本号、授权码或下载 Token 放入 URL。若官网暂未显示命令,说明发布者还没有配置当前可信入口,不要自行替换成未经校验的地址。

  1. 在面板服务器的管理员终端执行命令。安装提示中选择端口、管理员账号、强密码及数据库;默认宿主机端口为 10086。已有 Docker 按安装器提示复用,缺少依赖时先确认安装计划。
  2. 在隐藏提示处输入软件授权码和下载 Token。安装器先核验域名、授权、签名、架构和发行文件,再安装;任何阶段报错先处理该原因。
  3. 记录实际监听端口和安装完成信息。受控 Docker 面板通常位于 /opt/halorelay-docker;不要删除其中的数据、私有配置和凭据文件。

第二步:宝塔绑定 HTTPS 与反向代理

  1. 在面板服务器的宝塔“网站”中新建对应域名的站点,选择纯静态即可,无须 PHP 数据库。
  2. 在该站点配置覆盖域名的有效 SSL 证书。节点必须信任完整证书链,不使用自签名证书或关闭校验。
  3. 添加反向代理到实际监听,例如同机默认是 http://127.0.0.1:10086。安装时自选其他端口就使用实际端口,远程后端不能用本机回环地址冒充。
  4. 关闭业务 API 缓存,保留 Host 和 HTTPS 来源信息,转发真实来源地址。面板只信任你明确配置的反向代理 IP/CIDR,不要填全网信任。
  5. 保存前做 Nginx 配置检测,成功后重载,再从外部浏览器打开自己的 HTTPS 面板。

使用反向代理时可核对以下信息;保留站点原有其他设置,不用片段覆盖整份配置:

proxy_set_header Host $http_host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;

HTTPS 配置成功的标准是证书有效、能打开登录页、API 正常,不能只看首页静态资源能加载。

第三步:登录、激活和备份

  1. 使用安装时设置的账号登录。如果使用过初始默认账号,按首次登录提示立即更换强密码。
  2. 在“软件许可证”输入同一软件授权码,激活实际面板域名和实例;安装前校验不等于已完成实例激活。
  3. 在“系统设置”核对节点公开回连地址、下载通道、数据库、可信反向代理和通知渠道。
  4. 创建第一份业务备份并另外保管集成密钥、安装配置及服务器证书。确认文件能够下载,之后安排隔离恢复演练。
  5. 接入一台测试节点,运行第一条转发规则,再向客户分配权限。

PO0 等受限网络:准备两个 HTTPS 地址

节点安装要分别连接你的面板与官方分发站。仅修改其中一个地址,另一个仍可能在 443 超时。

用途普通情况受限网络示例
你的面板回连https://panel.example.comhttps://panel.example.com:24443
官方固定下载通道发行配置提供的标准通道发行配置提供的 24443 通道

24443 是一种配置示例,不代表服务商一定允许。先核对当次网络限制与端口可达性;更换地址不会自动建立专线、开防火墙或绕过服务商的接入白名单。

在宝塔增加 24443,避免跳回 443

操作位置:你的面板服务器,不是 PO0 节点。

  1. 宝塔 → 网站 → 对应面板域名 → 配置文件。先把完整配置保存为备份;也记录所有将修改的 include 文件。
  2. 找到包含该域名、listen 443 ssl 和证书路径的 server 块,在监听位置增加下面一行。保留原 443、证书及现有可用代理。
listen 24443 ssl;
  1. 查找强制 HTTPS 的规则。如果是“端口不是 443 就跳转”,只替换条件为“HTTP 才跳转”。保留内部原有 return 或 rewrite,不重复添加一组跳转。
# 错误条件: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. 检查其他无条件 301/302、固定端口或域名跳转;server 级规则可能早于 location 执行。
  2. 在云安全组与本机防火墙放行 TCP 24443。只在已具备 IPv6 路由、AAAA 和对应放行时增加 IPv6 监听。
  3. 在宝塔检查配置并重载。标准宝塔 Nginx 路径的命令如下;检测失败不继续重载。
sudo /www/server/nginx/sbin/nginx -t && sudo /www/server/nginx/sbin/nginx -s reload
  1. 检测或访问失败时恢复原配置,再次检测通过后重载。不需要重启整台服务器。

不要对 Cloudflare 普通代理默认假设支持 24443。使用直连入口时应配置 DNS-only(灰云)及客户端可信的公开证书。Origin CA 专供相应代理链路使用,直连节点不一定信任。最新代理端口与证书规则请查官方资料。

从真实节点验证,然后再安装

操作位置:待安装的 PO0 / 受限节点。

先在面板“系统设置 → 面板公开访问地址”保存实际 https://panel.example.com:24443,选择发行配置支持的备用下载通道,再从该节点复制最新连通性诊断和安装命令。已有 Agent 的本机配置不会仅因保存网页设置自动迁移。

下面只验证你自己的面板接口,不带 Token、不执行安装、不跟随重定向:

curl --proto '=https' --tlsv1.2 --silent --show-error --connect-timeout 15 --max-time 30 --output /dev/null --write-out 'HTTP %{http_code}\n' 'https://panel.example.com:24443/api/health'
  • HTTP 200:健康接口可访问,再检查官方选定下载通道。
  • HTTP 301/302:还有跳转规则;不能用 -L 掩盖它,尤其不要让带 Token 的请求跟到其他地址。
  • HTTP 000/超时:核对 DNS、路由、监听、安全组、防火墙和服务商白名单。
  • 证书错误:核对域名、证书链、时间和公开可信 CA;不能通过 -k 关闭校验安装。

下载 HEAD 返回 200 只说明响应可得,不代表整个运行包已完整下载。安装器还会检查签名、大小和 SHA256,慢线路等待时观察进度,不要重复启动多个安装进程。

安装 Agent 并验收

  1. 在“服务器节点”创建实际角色,保存当前节点 Token,复制该节点安装命令。
  2. 在对应节点服务器执行,交互输入当前 Agent Token 和独立下载 Token。
  3. 等待准入、发行文件核验、依赖准备、安装和服务健康检查完成。标准新节点会准备 nftables、iptables、签名包内 Realm;失败需核对包管理器与系统权限。
  4. 刷新面板:必须出现本次安装之后的新心跳、实际 Agent 版本和正确角色。出口还要确认公开证书已登记。
  5. 创建测试规则,从实际客户端连接入口并验证目标响应。需要 UDP 时单独验证 UDP。

标准节点只读检查:

sudo systemctl is-active halo-agent.service
sudo /opt/halo-forward/releases/current-agent/bin/halo-agent --version
sudo halorelay status agent

服务返回 active、版本符合预期、面板持续收到心跳与真实业务可达,才算完成。详见 用户手册。

接下来做什么

外部配置参考

证书更换和面板入口迁移

更换同域名有效证书无需重装 Agent。证书操作后检查 24443 监听、证书链和强制 HTTPS 规则,防止宝塔再次将该端口跳回 443。推荐使用经校验的独立节点入口工具,并按 证书与节点恢复专题 操作、验收和回滚。

需要改面板回连地址时,先升级面板及 Agent 至 0.7.18,再开通新入口并保留旧入口。所有节点实际迁入之前不能关闭旧地址。已离线节点和旧版本节点须在本机修复。详细步骤见 入口迁移。

协议与算法按场景选择

公网互联从 Rust + Veyra Secure 起步;主备出口使用支持 Guard 的出口组;QUIC 和 TCP 融合先做隔离试验。查看 Veyra 协议与算法指南,其中包含广州到香港、云厂商 IX、国际线路、UDP 业务和吞吐测试场景。