GinCdn内容分发系统（V1.0.1）详解+完整部署教程（主控+被控节点）

前言：随着中小网站、个人项目的流量增长，自建CDN成为降低带宽成本、提升访问速度的优选方案。GinCdn作为基于Go语言开发的轻量、高性能自研CDN系统，凭借简洁的部署流程、丰富的功能支持，成为中小企业和个人开发者的得力工具。本文将详细介绍GinCdn的版本更新亮点，并手把手教你完成主控端与被控节点端的完整部署，全程实操无冗余，新手也能快速上手。
gincdn透明.png

一、GinCdn系统简介

GinCdn是一款基于Go语言（依托Gin框架高性能特性）开发的私有CDN内容分发系统，支持多节点部署、域名解析、缓存管理、支付集成等核心功能，无需复杂的技术储备，即可快速搭建属于自己的CDN网络，适用于个人站长、中小企事业单位，可有效优化网站访问速度、降低源站压力。

官方授权站：auth.shuha.cn（获取正版授权、最新源码及相关资源）

二、GinCdn版本更新日志（V1.0.0-V1.0.1）

GinCdn迭代速度较快，近期已更新至V1.0.1版本，重点优化节点同步与管理功能，以下是完整更新记录，方便大家了解功能迭代方向，适配对应版本部署。

V1.0.1（2026.03.15）—— 节点管理优化版

本次更新聚焦节点同步与日志管理，解决离线节点同步效率低、节点状态难监控等问题，进一步提升系统稳定性，新增功能如下：

新增离线节点差量同步：无需全量同步所有数据，仅同步离线期间变化的内容，大幅提升同步效率，降低服务器带宽占用，尤其适合多节点分布式部署场景。
新增节点日志记录表：实时记录节点的运行状态、同步记录、异常信息，便于开发者快速排查节点连接、缓存同步等问题，降低运维成本。
新增线路节点异步同步：采用异步机制处理线路与节点的同步操作，不阻塞主进程，提升系统整体响应速度，避免因同步操作导致的卡顿。
新增当前在线节点获取：可在主控端实时查看所有在线节点列表，清晰掌握节点运行状态，便于节点的批量管理与维护。

V1.0.0（2026.03.06）—— 基础功能完整版

初始稳定版本，搭建了GinCdn的核心架构，涵盖CDN运行所需的基础功能，具体如下：

支持阿里云DNS：可快速对接阿里云DNS，实现域名解析的自动化配置，无需手动操作解析记录。
支持多节点部署：可部署多个被控节点，实现多地区内容分发，进一步优化不同地域用户的访问体验。
支持彩虹易支付：集成彩虹易支付接口，可实现CDN套餐的付费购买、续费等功能，适合商业化运营。
支持套餐分类与设置：可根据用户需求，自定义CDN套餐（如带宽、缓存容量、有效期等），灵活适配不同用户场景。
支持邮箱发信：可配置邮箱服务，实现用户注册通知、套餐到期提醒、异常告警等邮件推送功能。
支持全局防火墙配置：可设置全局防火墙规则，拦截恶意访问，保护CDN节点与源站安全。
支持全局Nginx配置：可统一配置所有节点的Nginx参数，无需逐个节点修改，提升运维效率。
缓存、默认页、错误页配置：可自定义缓存规则、默认访问页面、错误页面，优化用户访问体验。
支持角色折扣功能：可设置不同角色（如普通用户、VIP用户）的套餐折扣，提升用户粘性。
支持证书上传：可上传SSL证书，实现HTTPS加密访问，保障数据传输安全。
支持区域线路解析：可根据用户地域，自动分配最近的CDN节点，最大化提升访问速度。
支持站点接入：可快速接入多个网站，实现多站点的CDN加速管理，一站式运维。
支持同步配置：可实现主控端与被控节点的配置同步，修改主控端配置后，节点自动同步更新，无需手动操作。

三、部署前置准备（必看）

部署前需准备好相关服务器、软件及资源，避免部署过程中出现卡顿、失败等问题，以下是详细准备清单，适配V1.0.1版本。

3.1 服务器要求

主控端：CentOS 7.6–7.9 / Ubuntu 18.04-22.04（推荐2核4G及以上，确保网络通畅，带宽≥10M）；
被控节点（边缘节点）：CentOS 7+/Ubuntu 20.04+（推荐1核2G及以上，带宽≥5M，可部署多个节点，分布在不同地域效果更佳）；
网络要求：主控端与被控节点可相互访问，防火墙放行相关端口（后续会详细说明）。

3.2 软件与资源准备

通用软件：宝塔面板V11.0+（可视化运维，降低部署难度，新手首选）；
主控端依赖：Nginx 1.18+、MySQL 5.6+、Go 1.19+；
被控节点依赖：Go 1.19+、Nginx（无需MySQL，仅需基础运行环境）；
核心资源：GinCdn V1.0.1 主控端源码、被控节点程序（从官方授权站auth.shuha.cn获取）；
其他资源：域名1个（已解析到主控端服务器IP）、GinCdn官方授权码（从官方授权站获取）、SSL证书（可选，用于HTTPS访问）。

3.3 环境预处理

所有服务器安装宝塔面板，安装完成后，登录宝塔面板，安装所需软件（Nginx、MySQL）；
放行运行端口（宝塔面板 → 安全 → 放行端口）；
确保主控端MySQL服务正常运行，创建数据库时记录好账号密码，后续配置会用到。

四、主控端部署（宝塔面板，V1.0.1版本）

主控端是GinCdn的核心管理端，负责节点管理、配置设置、用户管理等功能，部署流程全程可视化，新手可直接跟着操作。

步骤1：创建数据库

登录宝塔面板，点击左侧「数据库」→「添加数据库」；
填写数据库信息（建议统一规范，便于后续维护）：

数据库名：gincdn_db（可自定义，建议包含gincdn标识）；
用户名：gincdn_user（可自定义）；
密码：设置复杂密码（建议包含字母、数字、特殊符号）；
字符集：utf8mb4（兼容所有字符，避免中文乱码）；

点击「创建」，创建完成后，记录好数据库名、用户名、密码，后续配置会用到。

步骤2：上传并解压GinCdn主控端源码

从官方授权站auth.shuha.cn下载GinCdn V1.0.1主控端源码压缩包（格式为zip/tar.gz）；
登录宝塔面板，点击左侧「文件」→「新建目录」，目录路径设置为「/wwwroot/gincdn」（可自定义，建议放在/wwwroot目录下）；
进入「/wwwroot/gincdn」目录，点击「上传」，选择下载好的源码压缩包，上传完成后，点击「解压」，将源码解压到该目录；
解压完成后，检查目录结构，确保包含gincdn（主程序）、config.yaml（配置文件）、gincdn.sql（数据库脚本）三个核心文件，缺一不可。

步骤3：编辑配置文件config.yaml

配置文件是主控端运行的核心，需根据实际环境修改，具体步骤如下：

进入「/wwwroot/gincdn」目录，找到config.yaml文件，点击「编辑」；
按照以下示例修改配置（替换括号内的内容，其他参数默认即可）：

port: 8080 # 主控端运行端口，确保未被占用（如已占用，可修改为其他端口）
db:
host: localhost # 数据库地址，本地部署填写localhost即可
port: 3306 # 数据库端口，默认3306
name: gincdn_db # 步骤1创建的数据库名
user: gincdn_user # 步骤1创建的数据库用户名
pass: 你的数据库密码 # 步骤1设置的数据库密码
auth: 你的官方授权码 # 从auth.shuha.cn获取的授权码

修改完成后，点击「保存」，关闭编辑界面。

步骤4：导入数据库脚本

登录宝塔面板，点击左侧「数据库」→ 找到步骤1创建的gincdn_db数据库，点击「导入」；
点击「选择文件」，找到「/wwwroot/gincdn」目录下的gincdn.sql文件，选中后点击「执行」；
导入完成后，会提示「导入成功」，若提示失败，检查数据库字符集是否为utf8mb4，或脚本文件是否完整。

步骤5：启动GinCdn主控端

登录宝塔面板，点击左侧「网站」→「Go项目」→「添加」；
填写Go项目信息：

项目名称：GinCdn主控端（可自定义）；
项目目录：选择「/wwwroot/gincdn」；
运行命令：go run main.go；
端口：填写config.yaml中设置的端口（默认8080）；

点击「启动」，启动成功后，会提示「启动成功」；
验证启动是否成功：打开浏览器，输入「http://主控IP:8080」或「https://你的主控域名」，能看到GinCdn首页，即启动成功。

步骤6：登录主控端后台

管理员后台：访问「http://主控域名/admin」或「http://主控IP:8080/admin」，默认账号：admin，默认密码：123456；
用户端后台：访问「http://主控域名/user」或「http://主控IP:8080/user」，供普通用户登录使用；
首次登录后，建议立即修改管理员密码，提升安全性，同时进入「系统设置」，检查授权码、域名等配置是否正确。

五、被控节点端部署（通用版，适配V1.0.1）

GinCdn内容分发系统Ubuntu18-24被控节点部署安装教程

GinCdn是一款轻量级的内容分发系统，本文将详细讲解在Ubuntu 18.04~24.04系统中，如何快速部署GinCdn被控节点，全程通过命令行操作，新手也能轻松上手。
gincdn透明.png

一、部署前准备

1. 环境要求

系统版本：Ubuntu 18.04/20.04/22.04/24.04（64位）
网络要求：服务器可访问公网，且80/443/8080端口（根据主控端配置）可正常通信
配置要求：2H2G、2H4G、4H4G、4H8G、8H2G、8H4G、8H8G、8H16G、16H16G、16H2G、16H4G、16H8G、16H32G等规格（根据业务负载选择）
权限要求：使用 root 用户执行命令（非 root 需在命令前加sudo）

2. 基础依赖检查

提前安装基础网络工具（可选，脚本会自动安装）：

apt update -y && apt install -y curl wget

二、一键部署步骤

1. 下载部署脚本

执行以下命令下载官方部署脚本，并赋予执行权限（核心命令，解决HTTP/2协议兼容问题）：

curl -k --http1.1 -o /root/start.sh https://www.gincdn.cn/download/ubuntu/start.sh && chmod +x /root/start.sh

执行成功标志：

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100 10932  100 10932    0     0   254k      0 --:--:-- --:--:-- --:--:--  254k

显示100%下载完成且无报错，说明脚本下载成功。

2. 运行部署脚本

执行下载好的脚本，启动全自动部署流程：

/root/start.sh

3. 配置主控地址

脚本执行过程中会提示输入主控地址，格式示例：http://192.168.1.100:8080（替换为你的实际主控端地址）：

三、部署结果验证

1. 检查服务状态

执行以下命令查看GinCdn节点服务状态：

systemctl status ws_config_client.service

成功标志：输出中包含Active: active (running)，示例：

● ws_config_client.service - GinCDN WS配置客户端服务
     Loaded: loaded (/etc/systemd/system/ws_config_client.service; enabled; vendor preset: enabled)
     Active: active (running) since Sat 2026-03-07 17:48:08 UTC; 1min ago
   Main PID: 118070 (bash)
      Tasks: 5 (limit: 9507)
     Memory: 13.3M
     CGroup: /system.slice/ws_config_client.service
             └─118070 /bin/bash /opt/gincdn/ws_config_client.sh

2. 验证主控地址配置

检查配置文件中主控地址是否正确：

grep MASTER_API_URL /opt/gincdn/conf/node_config.conf

成功标志：输出显示你配置的主控地址，示例：

MASTER_API_URL="http://192.168.1.100:8080"

3. 检查开机自启

确认服务已配置开机自启：

systemctl is-enabled ws_config_client.service

成功标志：输出enabled。

四、常见问题解决

1. 脚本下载失败（curl: (92) HTTP/2 stream 0 was not closed cleanly）

原因：目标服务器HTTP/2协议兼容问题，解决方案：使用--http1.1参数强制HTTP/1.1协议（本文核心命令已包含）。

2. 解压失败（unzip: command not found）

原因：未安装unzip工具，解决方案：

apt install -y unzip

3. 服务启动失败（Active: inactive (dead)）

解决方案：

# 重新加载服务配置
systemctl daemon-reload
# 重启服务
systemctl restart ws_config_client.service

4. 主控地址配置错误

修改配置文件并重启服务：

# 编辑配置文件
sed -i "s|MASTER_API_URL=\".*\"|MASTER_API_URL=\"新主控地址\"|g" /opt/gincdn/conf/node_config.conf
# 重启服务
systemctl restart ws_config_client.service

五、日常运维命令

1. 服务启停

# 启动服务
systemctl start ws_config_client.service
# 停止服务
systemctl stop ws_config_client.service
# 重启服务
systemctl restart ws_config_client.service

2. 卸载节点（可选）

# 停止服务
systemctl stop ws_config_client.service
# 禁用开机自启
systemctl disable ws_config_client.service
# 删除相关文件
rm -rf /root/gincdn.sh /opt/gincdn /etc/systemd/system/ws_config_client.service
# 重新加载服务配置
systemctl daemon-reload

总结

GinCdn 被控节点在 Ubuntu 18~24 系统中的部署流程高度自动化，核心步骤仅需「下载脚本→运行脚本→配置主控地址」三步，全程无需手动修改配置文件。部署完成后重点验证服务是否为active (running)状态，确保节点与主控端正常通信。该部署方案适配全版本 Ubuntu 系统，不同配置的服务器均可按需部署，满足各类内容分发场景的需求

六、V1.0.1版本新增功能使用说明

部署完成后，可重点体验V1.0.1版本的新增功能，提升节点管理效率，以下是核心功能的使用方法：

离线节点差量同步

当节点因网络问题离线后，重新上线时，系统会自动触发差量同步，仅同步离线期间主控端修改的配置、新增的缓存内容，无需全量同步，节省带宽和时间。可在主控端「节点管理」→「节点详情」中，查看同步记录。

节点日志记录表

登录主控端管理员后台，点击左侧「日志管理」→「节点日志」，可查看所有节点的运行日志，包括同步记录、异常信息、访问记录等，支持按节点、时间筛选，快速排查问题。

线路节点异步同步

系统默认开启异步同步，修改主控端线路配置、节点配置后，无需等待同步完成，可继续操作其他功能，同步过程在后台自动进行，不影响主控端正常运行。

当前在线节点获取

登录主控端管理员后台，点击左侧「节点管理」，可实时查看所有在线节点的列表，包括节点IP、地区、状态、缓存使用率等信息，便于批量管理和监控。

七、常见问题排查（新手必看）

部署过程中，可能会遇到一些小问题，以下是高频问题及解决方案，帮助大家快速排查，避免走弯路。

问题1：主控端启动失败

解决方案：1. 检查MySQL连接信息是否正确（config.yaml中的db配置）；2. 检查8080端口是否被占用（宝塔面板→安全→端口占用，关闭占用端口的程序）；3. 检查授权码是否正确，是否过期（可在官方授权站验证）；4. 检查数据库脚本是否导入成功，重新导入gincdn.sql。

问题2：被控节点无法注册到主控端

解决方案：1. 检查主控端防火墙是否放行8080端口，节点服务器是否能ping通主控端IP；2. 检查节点安装命令是否正确，节点密钥是否填写错误；3. 检查节点服务器的环境是否安装成功；4. 检查节点配置文件中的主控端IP、端口是否正确。

问题3：访问加速域名提示异常

解决方案：1. 检查域名CNAME解析是否生效（可通过ping命令验证）；2. 检查节点服务是否正常运行，状态是否为「在线」；3. 检查SSL证书是否上传成功，配置是否正确；4. 检查主控端全局防火墙是否拦截了访问请求。

八、生产环境优化建议

如果用于生产环境，建议做好以下优化，提升系统稳定性和安全性：

主控端：使用独立服务器，配置MySQL主从复制，定期备份数据库和配置文件，避免数据丢失；
被控节点：多地区部署节点（如华东、华北、华南），配置负载均衡，提升不同地域用户的访问速度；
安全防护：开启主控端和节点的防火墙，限制非法IP访问；定期更新GinCdn版本，修复已知漏洞；设置复杂的管理员密码，避免账号泄露；
监控告警：配置服务器监控（如宝塔面板监控、Zabbix），实时监控节点运行状态、带宽使用率、缓存容量，设置异常告警（如节点离线、缓存满）；
带宽优化：根据节点访问量，合理调整缓存容量，定期清理过期缓存，释放磁盘空间。

九、总结

GinCdn V1.0.1版本在V1.0.0的基础上，重点优化了节点同步与日志管理功能，进一步提升了系统的稳定性和运维效率，部署流程简洁，无需复杂的技术储备，新手也能快速上手。通过本文的教程，你可以轻松完成主控端与被控节点的部署，搭建属于自己的私有CDN网络，有效优化网站访问速度、降低源站压力。

后续如果GinCdn更新新版本，或遇到部署、使用相关的问题，可访问官方授权站auth.shuha.cn获取帮助，也可以在评论区留言，一起交流探讨。

最后，觉得本文有用的话，记得点赞、收藏、关注，后续会持续更新GinCdn的使用技巧和优化方案！

补充说明

本文部署教程适配GinCdn V1.0.1版本，若使用其他版本，需根据版本差异调整配置和部署步骤；
所有命令均经过实测，若出现命令执行失败，可检查服务器系统版本、软件版本是否符合要求；
官方授权站auth.shuha.cn可获取最新源码、授权码及技术支持，建议优先从官方渠道获取资源，避免使用非官方版本导致的安全风险。