常见问题排查

本文汇总 GinCdn 部署与运行中的高频问题，按「现象 → 原因 → 解决」组织，命令可直接复制执行。

一、被控节点安装类问题

1. 脚本下载失败：`curl: (92) HTTP/2 stream error`

现象：执行下载命令时报 HTTP/2 协议错误，文件下载不完整或中断。

原因：服务器或中间网络对 HTTP/2 兼容性较差。

解决：命令中加上 --http1.1 强制使用 HTTP/1.1。本文档给出的命令已包含该参数，重新完整复制执行即可：

bash

curl -k --http1.1 \
  -o /root/gincdn-install \
  https://www.gincdn.cn/download/ubuntu/gincdn-install

如果仍然失败，可尝试更换下载方式验证网络：

bash

curl -k --http1.1 -I https://www.gincdn.cn/download/ubuntu/gincdn-install

2. 报错 `unzip: command not found`

现象：脚本执行过程中提示找不到 unzip 命令。

原因：系统为精简镜像，未预装解压工具。

解决：安装缺失依赖后重新执行脚本。

bash

apt-get update
apt-get install -y unzip

3. 服务启动失败，状态显示 `inactive (dead)`

现象：systemctl status ws_config_client.service 显示 inactive (dead)。

排查步骤：

bash

# 1. 看具体报错
journalctl -u ws_config_client.service -n 100 --no-pager

# 2. 确认主控地址是否写入
grep MASTER_API_URL /opt/gincdn/conf/node_config.conf

# 3. 确认能否连通主控端口
telnet 主控IP 主控端口

# 4. 重新写入主控地址后再启动
sudo /root/gincdn-install --update-master-url http://主控IP:端口
systemctl restart ws_config_client.service

4. 节点连不上主控

可能原因（按排查优先级）：

主控地址写错（协议、IP/域名、端口任一有误）
主控端口未放行 —— 既要改宝塔安全页面，也要改云厂商安全组
主控服务未启动
节点本机防火墙拦截出网
主控后台还没有添加该节点信息
节点名称里带了空格

解决：逐条对照上表排查，命令见常用运维命令 · 连通性排查。

5. 节点名称不能包含空格

现象：节点在主控后台添加后，节点端始终无法连接，且无明显报错。

原因：主控后台添加节点时，节点名称中包含了空格（含首尾空格）。

解决：回到主控后台 → 节点管理，把节点名称中的所有空格去掉（建议用 - 或 _ 替代），保存后重启节点服务：

bash

systemctl restart ws_config_client.service
bash /opt/gincdn/client.sh

6. 安装成功后节点仍未生效

原因：主控后台尚未添加绑定该节点信息。

解决：登录主控管理员控制台 → 节点管理 → 添加节点，填写名称、IP、区域、线路，保存后重启节点同步服务。

二、主控端安装类问题

1. 主控启动后运行报错

原因：数据库未成功导入，或 config.yaml 中数据库配置与实际不符。

解决：

确认 gincdn.sql 已成功导入（宝塔 → 数据库 → 管理，查看数据表是否生成）
核对 config.yaml 中的 host / port / name / user / password
修改配置后重启 Go 项目

2. 端口被占用

现象：Go 项目启动失败，日志提示端口已被占用。

排查：

bash

netstat -lntp | grep 8080

解决：在宝塔安全中确认端口放行情况，或将 config.yaml 中的 port 改为未被占用的端口，并在宝塔与云安全组中同步放行。

3. 主控页面无法访问

排查顺序：

检查项	位置
Go 项目是否运行中	宝塔 → 网站 → Go 项目
端口是否放行	宝塔 → 安全，以及云厂商安全组
防火墙是否拦截 `80` / `443`	服务器防火墙规则
反向代理配置是否正确	站点 → 反向代理

4. Redis 相关报错

排查：

bash

# 确认 Redis 是否在运行
systemctl status redis

# 测试连接（替换为你的密码）
redis-cli -h 127.0.0.1 -p 6379 -a 你的密码 ping

解决：

确认宝塔 Redis 设置中 bind 为 0.0.0.0（需被控节点连接时）
确认 requirepass 已设置，且主控与被控配置中的密码一致
确认 6379 已放行

三、证书与授权类问题

1. SSL 证书签发失败

排查：

确认域名已正确解析到主控服务器，且解析已生效
确认 80 端口可从公网访问（证书签发需要 HTTP 校验）
确认反代或 CDN 没有拦截 /.well-known/acme-challenge/ 路径

版本提示

V1.1.8 起支持 SSL 证书签发；V1.1.9 修复了证书签发相关问题；V1.2.0 修复了 SSL 证书清空保存问题。如遇签发异常，建议先升级到最新版本。

2. 授权相关报错

排查：

确认授权码填写正确，无多余空格
确认主控域名与授权绑定的域名一致
更换主控域名后，需在授权中心重新获取授权码

四、更新类问题

1. 更新后节点掉线

排查：

bash

systemctl status ws_config_client.service
grep MASTER_API_URL /opt/gincdn/conf/node_config.conf

解决：更新不会改动主控地址。若地址丢失，用 --update-master-url 重新写入后重启服务。

2. 用错下载地址

现象：更新后功能异常或版本未变化。

原因：首次安装与更新使用不同的下载路径。

用途	地址
首次安装	`/download/ubuntu/gincdn-install`
节点更新	`/download/update/ubuntu/gincdn-install`

五、仍无法解决？

请准备好以下信息，便于快速定位：

主控端版本号（管理员控制台可查看）
节点服务器系统版本与配置
相关命令的完整报错输出
节点服务日志：journalctl -u ws_config_client.service -n 200 --no-pager

联系方式：

邮箱：gincdn@qq.com
QQ：48548598

常见问题排查 ​

一、被控节点安装类问题 ​

1. 脚本下载失败：curl: (92) HTTP/2 stream error ​

2. 报错 unzip: command not found ​

3. 服务启动失败，状态显示 inactive (dead) ​

4. 节点连不上主控 ​

5. 节点名称不能包含空格 ​

6. 安装成功后节点仍未生效 ​

二、主控端安装类问题 ​

1. 主控启动后运行报错 ​

2. 端口被占用 ​

3. 主控页面无法访问 ​

4. Redis 相关报错 ​

三、证书与授权类问题 ​

1. SSL 证书签发失败 ​

2. 授权相关报错 ​

四、更新类问题 ​

1. 更新后节点掉线 ​

2. 用错下载地址 ​

五、仍无法解决？ ​

相关文档 ​

常见问题排查

一、被控节点安装类问题

1. 脚本下载失败：`curl: (92) HTTP/2 stream error`

2. 报错 `unzip: command not found`

3. 服务启动失败，状态显示 `inactive (dead)`

4. 节点连不上主控

5. 节点名称不能包含空格

6. 安装成功后节点仍未生效

二、主控端安装类问题

1. 主控启动后运行报错

2. 端口被占用

3. 主控页面无法访问

4. Redis 相关报错

三、证书与授权类问题

1. SSL 证书签发失败

2. 授权相关报错

四、更新类问题

1. 更新后节点掉线

2. 用错下载地址

五、仍无法解决？

相关文档