外观
被控节点安装（Ubuntu）
被控节点（边缘节点）是实际承载流量转发、缓存加速与安全防护的角色。 本文提供 Ubuntu 全系列（18.04 / 20.04 / 22.04 / 24.04）的一键部署方式，推荐使用 Ubuntu 24.04 LTS。
云服务器推荐
边缘节点服务器推荐使用贝海云：https://www.beihaiyun.com
前置条件
- 已按 主控端安装 部署好主控端，并能正常访问后台
- 节点服务器为 root 权限，且可访问公网
- 节点服务器可连通主控端口（可先用
telnet 主控IP 主控端口测试）
一、下载并执行一键脚本
直接复制下面这条完整命令执行，脚本会自动完成下载、环境部署、依赖安装与服务注册：
bash
curl -k --http1.1 \
-o /root/gincdn-install \
https://www.gincdn.cn/download/ubuntu/gincdn-install \
&& chmod +x /root/gincdn-install \
&& sudo /root/gincdn-install多行命令可以整段复制
上面的命令用 \ 续行，粘贴到终端后会作为一条命令执行。 如果你更习惯单行写法，去掉 \ 与换行即可： curl -k --http1.1 -o /root/gincdn-install https://www.gincdn.cn/download/ubuntu/gincdn-install && chmod +x /root/gincdn-install && sudo /root/gincdn-install
执行后会显示部署工具的用法说明（若只看到帮助信息，说明还没带主控地址，继续下一步即可）：
脚本运行后显示的参数说明
命令说明：
| 参数 | 作用 |
|---|---|
curl -k | 跳过证书校验，避免部分服务器因证书链不完整而下载失败 |
--http1.1 | 强制使用 HTTP/1.1，规避 curl: (92) HTTP/2 stream error |
-o /root/gincdn-install | 将安装程序保存到 /root 目录 |
chmod +x | 赋予可执行权限 |
关于命令中的两处调整
chmod 与执行都使用了绝对路径 /root/gincdn-install。 原始写法是 chmod +x gincdn-install（相对路径），只有在当前工作目录正好是 /root 时才成立； 改为绝对路径后，在任意目录下执行都不会出错。
二、指定主控地址并完成部署
上一步只是下载了程序，还需带上主控地址才能真正部署：
bash
sudo /root/gincdn-install --master-url http://192.168.1.100:8080请把 http://192.168.1.100:8080 替换为你自己的主控地址（域名或 IP + 端口）。
带上 --master-url 参数执行部署
脚本会自动下载组件、安装 OpenResty 与 WAF、写入配置并注册系统服务：
安装部署过程输出
出现部署成功提示即表示节点组件已安装并注册为系统服务。
脚本参数速查
text
GinCdn 部署工具（命令行模式）
用法:
gincdn-install --master-url <url> 完整部署并指定主控地址
gincdn-install --update-master-url <url> 更新主控地址
gincdn-install --help 显示此帮助信息
示例:
gincdn-install --master-url http://192.168.1.100:8080
gincdn-install --update-master-url http://192.168.1.200:8080
常用命令（部署完成后）:
启动: /usr/local/openresty/nginx/sbin/nginx
停止: /usr/local/openresty/nginx/sbin/nginx -s stop
重载: /usr/local/openresty/nginx/sbin/nginx -s reload安装版不含 --update 参数
上面是安装包自带的帮助输出，只有 3 个参数。 升级节点组件要用更新包，其帮助中会多出一项 --update，详见 被控节点更新。
此时节点还没被主控接管
如果脚本最后提示连接失败或节点未生效，通常是因为主控后台还没有添加这个节点的信息。 请继续下一步。
三、在主控后台添加节点
如果主控后台尚未登记该节点，节点服务会启动但无法完成注册，表现为连接失败：
主控后台没有该节点信息时的报错
需要到主控后台手动添加节点：
- 登录主控管理员控制台 → 进入节点管理
- 添加节点，填写节点名称、IP、区域、线路等信息
在主控后台「节点管理」中添加节点
- 节点名称不能包含任何空格（包括首尾空格），否则会导致节点无法连接
节点名称中不能出现空格
节点名称不能有空格
这是最容易踩的坑。名称里只要出现空格，节点就会一直连不上主控， 且报错信息通常不直观，排查起来很费时间。
添加完成后，回到节点服务器执行：
bash
# 重启配置同步服务
systemctl restart ws_config_client.service
# 执行一次节点初始化脚本
bash /opt/gincdn/client.sh四、验证部署
1. 查看节点服务状态
bash
systemctl status ws_config_client.service成功标志：输出中出现
text
Active: active (running)服务绿色高亮、持续运行：
服务状态显示 active (running)
2. 检查主控地址是否写入正确
bash
grep MASTER_API_URL /opt/gincdn/conf/node_config.conf输出为你填写的主控地址即正常。
3. 检查开机自启
bash
systemctl is-enabled ws_config_client.service输出 enabled 表示已配置开机自启，重启服务器后节点会自动恢复。
4. 回到主控后台确认
在节点管理中查看该节点的状态与最后心跳时间。状态为在线、且能看到磁盘与内存信息，即为完全接入成功。
五、修改主控地址
如果主控地址变更（换了域名、IP 或端口），在节点上执行：
bash
sudo /root/gincdn-install --update-master-url http://新的主控地址:端口执行后建议重启一次同步服务：
bash
systemctl restart ws_config_client.service六、下一步
节点接入成功后，可在主控后台把站点下发到该节点。 日常启停、日志查看等操作请参考 常用运维命令； 遇到连接异常请参考 常见问题排查。
批量部署
需要上线多台节点时，把本文第一节的命令与第二节的 --master-url 组合成一条命令， 在各节点服务器上分别执行即可，无需人工改配置。