Skip to content
BranchesTags

Latest commit

 

History

24 Commits

Folders and files

NameName
Last commit message
Last commit date
hy2-dnat-watchdog
hy2-dnat-watchdog
 
 
README.md
README.md
 
 
install.sh
install.sh
 
 

Repository files navigation

xboard-node-key

xboard-node 带证书指纹上报补丁版的一键安装脚本。在官方 xboard-node 基础上新增两处改动：

文件 改动
internal/cert/cert.go 新增 SPKI SHA-256 指纹计算；certMaterial 新增 spkiSha256 字段；新增 SPKIFingerprint() 返回 Base64 指纹，CertPEM() 返回完整 PEM
internal/service/service.go buildMetrics() 注入 cert_fingerprint 和 cert_pem，随每分钟 metrics 上报面板

部署到面板后，v2_server 表会写入 cert_fingerprint（sing-box 用，44 字符 Base64 SPKI）和 cert_pem（完整 PEM，PHP 端按客户端类型派生下发），订阅端从此可用证书指纹固定替代 insecure: true。

v1.1.0-cert-pinning (2026-07-31)

Bug Fix

  • Port label not updating on hot-reload: Fixed logger tag [protocol:port] not refreshing when panel changes node port/protocol via WebSocket push. Previously the tag was stuck on the initial port value after first start.

Features

  • Certificate fingerprint reporting: buildMetrics now includes cert_fingerprint (SPKI SHA-256 Base64) and cert_pem fields for client-side certificate pinning support.
  • cert.Manager.SPKIFingerprint(): New method for computing SPKI SHA-256 fingerprint from the loaded certificate.
  • cert.Manager.CertPEMString(): New method for retrieving the certificate PEM as a string.
  • QUIC/Hysteria2 support: Binary is now built with -tags with_quic, enabling Hysteria2 protocol support out of the box.

Binary

  • xboard-node-linux-amd64 (63.3 MB) — Built from official Xboard-Node dev branch with:
    • internal/cert/cert.go: Added SPKIFingerprint() and CertPEMString() methods
    • internal/service/service.go: Fixed 3x if s.nodeLog == nil guards → always refresh on config change; Added cert metrics in buildMetrics()

一行命令安装（推荐）

把下面 --panel / --token / --machine-id 三个值换成你自己面板的对应值。

curl -fsSL https://raw.githubusercontent.com/pandanetworkgroup/xboard-node-key/main/install.sh \
  | sudo bash -s -- --mode machine \
                      --panel 'https://your-panel-domain.com' \
                      --token '面板导出的_machine_token' \
                      --machine-id 1

参数对应面板「节点管理 → 查看配置」中的导出值：

参数 来源
--panel 面板访问域名（HTTPS）
--token 面板「节点管理」中导出的 machine token
--machine-id 面板中的 machine ID（数字）

交互式安装

先下载脚本，再交互式运行：

curl -fsSL https://raw.githubusercontent.com/pandanetworkgroup/xboard-node-key/main/install.sh -o install.sh
sudo bash install.sh

脚本会逐项询问面板地址、token、machine id。

升级补丁版（--upgrade）

当有新版补丁二进制发布时，使用 --upgrade 一步完成升级：

sudo bash install.sh --upgrade

流程：

  1. 从官方 cedar2025/xboard-node 仓库下载最新原始二进制，替换当前补丁版（确保干净的官方基线）
  2. 从 xboard-node-key 仓库下载最新补丁版二进制，替换官方版
  3. 重启服务（config / credentials 保持不变）

如果官方仓库不可达，会自动 fallback 到本地 .bak.* 备份文件。

重新安装（保留配置）

已存在 /etc/xboard-node/config.yml 时，直接重新运行安装命令也会自动进入升级模式（仅替换二进制，保留配置）：

curl -fsSL https://raw.githubusercontent.com/pandanetworkgroup/xboard-node-key/main/install.sh \
  | sudo bash -s -- --mode machine --panel 'https://...' --token '...' --machine-id 1

回滚

sudo systemctl stop xboard-node
sudo cp /usr/local/bin/xboard-node.bak.列出的时间戳 /usr/local/bin/xboard-node
sudo systemctl start xboard-node

完整参数

参数 默认 说明
--mode machine 配置模式（当前仅 machine）
--panel - 面板访问地址
--token - machine token
--machine-id - 面板 machine ID
--instance-id 自动生成 自定义 instance_id
--health-port 65530 健康检查端口
--kernel singbox singbox / xray
--log-level info info / warn / error / debug
--upgrade - 升级模式：从官方仓库恢复原始二进制，再安装最新补丁版
--xbctl-binary - 使用本地 xbctl 二进制文件（不下载）
--force - 强制覆盖已存在的 config.yml
--skip-download - 不下载二进制，复用现有
--offset K 10000 HY2 DNAT watchdog 端口范围偏移量（HY2 端口 N → 转发 N..N+K）
--no-hy2-watchdog - 跳过集成的 HY2 DNAT watchdog 部署

安装后

HY2 DNAT Watchdog 已随 node 集成部署（惰性，详情见文末）。用 --no-hy2-watchdog 可跳过。

  • 二进制：/usr/local/bin/xboard-node
  • CLI：/usr/local/bin/xbctl
  • 配置：/etc/xboard-node/config.yml（600 权限）
  • 凭证：/etc/xboard-node/credentials.env（600 权限）
  • 实例数据：/etc/xboard-node/instances/<instance_id>/node-<id>/certs/
  • systemd 服务：xboard-node.service

xbctl 常用命令

安装完成后可使用 xbctl 管理 node 服务：

xbctl list                    # 列出所有实例
xbctl status                  # 查看运行状态
xbctl start                   # 启动服务
xbctl stop                    # 停止服务
xbctl restart                  # 重启服务
xbctl logs                    # 查看日志
xbctl health                  # 健康检查
xbctl bind-node ...           # 绑定新节点
xbctl bind-machine ...        # 绑定新机器
xbctl unbind-node ...         # 解绑节点
xbctl unbind-machine ...      # 解绑机器
xbctl upgrade                 # 升级二进制
xbctl version                 # 查看版本

安装脚本会自动从官方 cedar2025/Xboard-Node 仓库下载 xbctl-linux-amd64。如已有本地二进制，可用 --xbctl-binary /path/to/xbctl 指定。已安装的 xbctl 不会重复下载（幂等）。

验证上报：

# 1. 节点日志
journalctl -u xboard-node -f

# 2. 面板服务器查 DB（替换容器名）
docker exec xboard-xboard-1 php /www/artisan tinker --execute='
$rows = \DB::table("v2_server")->select("id","name","cert_fingerprint","cert_pem")->get();
foreach ($rows as $r) {
    echo sprintf("id=%d name=%s fp_len=%d pem_len=%d\n",
        $r->id, $r->name,
        $r->cert_fingerprint ? strlen($r->cert_fingerprint) : 0,
        $r->cert_pem ? strlen($r->cert_pem) : 0);
}
'

每个已配置证书的节点应有 fp_len=44、pem_len=570-900。

面板侧前置条件

部署 node 侧之前，面板必须已：

  1. v2_server 表已加 cert_fingerprint 和 cert_pem 字段
  2. app/Services/ServerService.php 已部署修改版（updateMetrics 持久化两个字段）
  3. app/Protocols/*.php 8 个协议生成器已部署修改版
  4. 容器已重启清 OPcache

详见部署手册。

面板侧 server_ws_url 配置

如果 node 启动后日志出现 WARN ws disconnected error=dial: malformed ws or wss URL：

# 面板服务器执行，注意 scheme 必须是 wss://，路径必须以 /ws 结尾
docker exec xboard-xboard-1 php /www/artisan tinker --execute='
admin_setting(["server_ws_url"=>"wss://你的面板域名/ws"]);
echo admin_setting("server_ws_url");
'

协议兼容性

  • 协议：HY2 / VLESS / VMess / TUIC / anytls / WireGuard 等均支持证书指纹上报
  • xhttp 传输：仅 xray 内核支持，若节点用 xhttp，请 --kernel xray
  • 架构：仅 amd64（x86_64），其他架构暂未编译

HY2 DNAT Watchdog（端口跳变转发，已集成）

装 node 时默认一并集成部署，无需单独安装。watchdog 是惰性的：cron 每分钟检测 Hysteria2 端口，检测到才生成 DNAT 规则，检测不到就空跑（对无 HY2 的 node 无副作用）。

  • 默认 offset=10000：curl ... | sudo bash -s -- --mode machine --panel ... --token ... --machine-id 1
  • 自定义偏移：加 --offset 20000
  • 跳过集成：加 --no-hy2-watchdog

部署后运行时调整偏移量（无需重装，立即生效）：

/usr/local/bin/hy2-dnat-watchdog.sh --offset 20000
/usr/local/bin/hy2-dnat-watchdog.sh --show

卸载 watchdog：

bash <(curl -fsSL https://raw.githubusercontent.com/pandanetworkgroup/xboard-node-key/main/hy2-dnat-watchdog/uninstall.sh)

hy2-dnat-watchdog/ 子目录另保留独立的 install/uninstall/教程，供单独部署或参考：

文件 说明
hy2-dnat-watchdog/install.sh 独立部署脚本（同款，含 --offset）
hy2-dnat-watchdog/uninstall.sh 卸载脚本
hy2-dnat-watchdog/GUIDE.zh-CN.md 完整中文教程

详细原理、双后端自动选择（nftables/iptables）、与宝塔/docker 等工具共存、故障排查等见 hy2-dnat-watchdog/GUIDE.zh-CN.md。

About

修改版 xboard-node 脚本，自动生成指纹证书，上报xboard面板 cert_fingerprint + cert_pem

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages