申请与安装子节点
前提条件
- 一台由你管理的机器:官方二进制需要管理员 / root 权限(要常驻运行并占用 80、443);
- 能访问 GitHub、Docker Hub 与各发行版官方源,建议境外线路;
- 注册一个 开源驿站 账号。
⚠️ 如果服务器位于中国大陆,一键安装脚本会提醒你:子节点直接访问上游,
国内网络下加速效果可能不明显,建议改用境外机器。
支持哪些机器
用户中心与后台的安装命令区会按平台列出全部可选方式,复制对应命令到机器上执行即可。
| 运行方式 | 适用系统 | 常驻方式 |
|---|---|---|
| 官方二进制(功能最全) | Linux x86_64 / ARM64 / ARMv7 / 386 | systemd 或 OpenRC |
| 官方二进制(功能最全) | macOS(Apple 芯片 / Intel) | launchd |
| 官方二进制(功能最全) | Windows x64 / ARM64 | 计划任务(管理员 PowerShell 一键安装) |
| Node.js 版(单文件、零依赖) | 有 Node.js 18 以上的任意系统 | systemd / launchd 或自行保持进程 |
| PHP 版(单文件) | 有 PHP 与 curl 扩展的虚拟主机、面板环境 | 计划任务,或由访问请求顺带补心跳 |
流程
- 登录后进入用户中心 → 贡献服务器,填写节点名称、地区、线路、配置、联系方式,并选择流量承诺(无限流量 / 限定额度多少 GB),提交申请;
- 管理员审核通过后,页面会分配安装序号与域名(z1、z2…:第几个安装的节点),并给出始终可见的安装命令(按平台切换;节点安装完成后该命令失效,需要「重新生成」);
- 在你的机器上选择对应平台的命令执行;
- 安装脚本会先检查并请你确认允许使用 80 与 443 端口(用于自动申请 HTTPS 证书;已有网站占用这两个端口时会提示先迁移),随后自动注册、拿到通讯密钥与访问域名、注册系统服务并启动;
- 之后节点每 30 秒向主节点心跳,状态、延迟、已用流量与额度都会出现在节点列表与用户中心里;\n6. 达到承诺额度后主节点会自动暂停该节点,管理员提高额度即自动恢复。
安装命令长什么样
Linux / macOS(官方二进制)
curl -fsSL 'https://www.gh-proxy.cn/node/install.sh?token=一次性令牌' | sudo sh
脚本会自动识别系统与架构(x86_64 / ARM64 / ARMv7 / 386),也可以手动指定:
# 查看本机可用的平台名称
curl -fsSL 'https://www.gh-proxy.cn/node/install.sh?token=一次性令牌' | sudo sh -s -- --list-platforms
# 指定平台(例如 Apple 芯片的 Mac)
curl -fsSL 'https://www.gh-proxy.cn/node/install.sh?token=一次性令牌' | sudo sh -s -- --platform=darwin-arm64
Windows(官方二进制)
在管理员 PowerShell 里执行:
irm 'https://www.gh-proxy.cn/node/install.ps1?token=一次性令牌' | iex
脚本会下载对应架构的程序、放行 80 / 443 端口、注册开机自启的计划任务,
并生成 C:\ProgramData\gha-node\uninstall.ps1 方便随时卸载。
Node.js 版(跨平台、单文件)
curl -fsSL 'https://www.gh-proxy.cn/node/agent.js?token=一次性令牌' -o gha-node.js
sudo node gha-node.js install --yes
要求 Node.js 18 以上,不需要任何第三方依赖。Windows 上把第一行换成
irm 'https://www.gh-proxy.cn/node/agent.js?token=一次性令牌' -OutFile gha-node.js,
再执行 node gha-node.js install --yes 即可。
它不内置证书申请:主节点为该域名开启 CDN 代理(后台默认开启)时由 CDN 终结 HTTPS;
需要节点自己签发证书请使用官方二进制版本。
PHP 版(虚拟主机、面板环境)
curl -fsSL 'https://www.gh-proxy.cn/node/agent.php?token=一次性令牌' -o gha-node.php
- 把
gha-node.php上传到网站根目录(例如public_html/); - 浏览器访问
https://你的域名/gha-node.php?install=1完成注册,
或在 SSH 里执行php gha-node.php install --yes; - 加一条重写规则把加速路径交给它:
# Apache:网站根目录放一个 .htaccess
RewriteEngine On
RewriteCond %%{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ gha-node.php [L,QSA]
# Nginx:在 server 块里加一条
location / {
try_files $uri /gha-node.php?$query_string;
}
- 加一条计划任务保持心跳:
* * * * * php /path/to/gha-node.php heartbeat。
没有计划任务也能用:转发请求时会顺手补一次心跳。
脚本做的事情(可以先下载下来自己审阅再执行):
- 检查 root 权限与系统架构,检测网络所在国家/地区(国内会提醒),并检查 / 确认 80、443 端口可用;
- 从主节点下载对应平台的
gha-node程序; - 用一次性令牌向主节点注册,换取通讯密钥与访问域名,
并把本机机器指纹一起上报(一个安装命令只能绑定一台机器); - 写入配置文件(权限 600)并注册系统服务:Linux 用 systemd(Alpine 用 OpenRC)、macOS 用 launchd、Windows 用计划任务;
- 用 80 端口做 ACME 验证、443 端口对外提供 HTTPS(证书由节点自动申请与续期,CDN 代理开启时同样可用);
- 每 10 分钟重新检测一次公网 IP,IP 变化时主节点会自动更新 DNS 解析;
- 生成卸载脚本方便随时卸载(Linux/macOS 是
/etc/gha-node/uninstall.sh,
Windows 是C:\ProgramData\gha-node\uninstall.ps1,Node.js 版是node gha-node.js uninstall)。
非交互安装(自动化部署)
安装脚本全程只使用普通命令行文本提示,不需要任何终端界面组件,
输出按 [1/7] 这样的步骤编号排列,方便直接贴进日志。
在 CI、批量部署或没有终端(无法输入 y 确认)的环境里,请显式表示同意使用 80 与 443 端口:
curl -fsSL 'https://www.gh-proxy.cn/node/install.sh?token=一次性令牌' | sudo sh -s -- --yes
也可以用环境变量 GHA_ACCEPT_PORTS=1 达到同样效果。脚本还支持
--help(查看用法)与 --uninstall(停止服务并清理文件)。
换机器 / 重装
在「贡献服务器」页面点击重新生成安装命令,旧命令立即失效,然后在新机器上执行新命令即可。
卸载
sh /etc/gha-node/uninstall.sh
# 或者
systemctl disable --now gha-node && rm -rf /etc/gha-node /var/lib/gha-node /usr/local/bin/gha-node
管理员在后台撤销该节点时,节点会在下一次心跳(默认 30 秒)内自动停止服务、
删除配置与程序文件,并从节点列表中消失。
常见问题
| 现象 | 原因与处理 |
|---|---|
| 注册失败:令牌无效 | 令牌是一次性的,或已被重新生成;请在用户中心重新生成安装命令 |
| 注册失败:该机器已绑定其他节点 | 一台机器只能绑定一个节点;请先在原节点上卸载 |
| 状态显示离线 | Linux 看 systemctl status gha-node,macOS 看 launchctl print system/cn.gha-node.agent,Windows 看 Get-ScheduledTask -TaskName gha-node,确认进程在跑且能访问主节点 |
| 延迟/速度为「待测速」 | 节点刚启动,等一个心跳周期(默认 30 秒)后刷新 |
| 域名打不开 | 主节点未配置自动解析,需要管理员在后台「贡献服务器」页配置解析服务商,或手工添加解析 |
| 安装脚本提示平台不支持 | 用 --list-platforms 查看可用平台;ARMv7 / 386 等老架构需要主节点已上传对应程序 |
| Windows 安装后没有反应 | 需要用管理员 PowerShell 执行;安装脚本会创建名为 gha-node 的计划任务,可在任务计划程序里查看 |
| Node.js 版没有 HTTPS | Node.js / PHP 版不内置证书申请:开启 CDN 代理时由 CDN 终结 HTTPS,需要节点自签证书请用官方二进制 |
| PHP 版转发 404 | 重写规则还没生效:确认 .htaccess 已生效(Apache 需要 AllowOverride)或 Nginx 的 location 已指向 gha-node.php |