linkmaster-node/INSTALL.md

LinkMaster 节点端安装指南

一句话安装

从 GitHub 安装（推荐）

curl -fsSL https://raw.githubusercontent.com/yourbask/linkmaster-node/main/install.sh | bash -s -- http://your-backend-server:8080

替换说明：

• yourbask/linkmaster-node - 独立的 node 项目 GitHub 仓库地址
• http://your-backend-server:8080 - 替换为实际的后端服务器地址

重要提示：

• ⚠️ 节点端需要直接连接后端服务器（端口 8080），不是前端地址
• 前端通过 /api 路径代理到后端，但节点端不使用前端代理
• 如果节点和后端在同一服务器：使用 http://localhost:8080
• 如果节点和后端在不同服务器：使用 http://backend-ip:8080 或 http://backend-domain:8080
• 本项目是独立的 GitHub 仓库，与前后端项目分离

示例：

# 如果后端服务器在 192.168.1.100:8080
curl -fsSL https://raw.githubusercontent.com/yourbask/linkmaster-node/main/install.sh | bash -s -- http://192.168.1.100:8080

指定分支安装

GITHUB_BRANCH=develop curl -fsSL https://raw.githubusercontent.com/yourbask/linkmaster-node/main/install.sh | bash -s -- http://your-backend-server:8080

安装步骤说明

安装脚本会自动完成以下步骤：

1. 检测系统 - 自动识别 Linux 发行版和 CPU 架构
2. 安装依赖 - 自动安装 Git、Go、ping、traceroute、dnsutils 等工具
3. 下载发布包 - 从 Releases 下载预编译发布包（包含二进制文件和所有脚本）
4. 提取文件 - 从发布包提取所有文件到 /opt/linkmaster-node（无需克隆 Git）
5. 编译安装 - 如果下载失败，自动从源码编译安装
6. 创建服务 - 自动创建 systemd 服务文件（使用 run.sh 启动）
7. 启动服务 - 自动启动并设置开机自启
8. 验证安装 - 检查服务状态和健康检查

重要说明：

• ✅ 新格式发布包：包含二进制文件、安装脚本、运行脚本等所有必要文件，安装时直接从压缩包提取，无需克隆 Git 仓库
• ✅ 向后兼容：如果发布包是旧格式（仅包含二进制文件），安装脚本会自动从 Git 克隆获取脚本文件
• ⚠️ 源码编译模式：如果下载失败，会从 Git 克隆源码并编译（需要网络连接）

安装后管理

查看服务状态

sudo systemctl status linkmaster-node

查看日志

# 实时日志
sudo journalctl -u linkmaster-node -f

# 最近50行日志
sudo journalctl -u linkmaster-node -n 50

重启服务

sudo systemctl restart linkmaster-node

停止服务

sudo systemctl stop linkmaster-node

禁用开机自启

sudo systemctl disable linkmaster-node

验证安装

检查进程

ps aux | grep linkmaster-node

检查端口

netstat -tlnp | grep 2200
# 或
ss -tlnp | grep 2200

健康检查

curl http://localhost:2200/api/health

应该返回：{"status":"ok"}

手动安装（不使用脚本）

如果无法使用一键安装脚本，可以手动安装：

方式一：从发布包安装（推荐）

优点：无需 Git 和 Go 环境，直接使用预编译文件

# 1. 下载发布包（替换为实际版本和平台）
wget https://gitee.nas.cpolar.cn/yoyo/linkmaster-node/releases/download/v1.1.4/agent-linux-amd64-v1.1.4.tar.gz

# 2. 解压
tar -xzf agent-linux-amd64-v1.1.4.tar.gz
cd agent-linux-amd64-v1.1.4

# 3. 复制文件到安装目录
sudo mkdir -p /opt/linkmaster-node
sudo cp -r * /opt/linkmaster-node/
sudo chmod +x /opt/linkmaster-node/agent
sudo chmod +x /opt/linkmaster-node/*.sh

# 4. 复制二进制文件到系统目录
sudo cp /opt/linkmaster-node/agent /usr/local/bin/linkmaster-node
sudo chmod +x /usr/local/bin/linkmaster-node

# 5. 创建配置文件（从示例复制）
sudo cp /opt/linkmaster-node/config.yaml.example /opt/linkmaster-node/config.yaml
# 编辑配置文件，设置后端地址
sudo nano /opt/linkmaster-node/config.yaml

# 6. 创建 systemd 服务（参考下面的服务配置）

方式二：克隆源码并编译

# 克隆仓库
git clone https://github.com/yourbask/linkmaster-node.git /opt/linkmaster-node
cd /opt/linkmaster-node

# 安装 Go 环境（如果未安装）
# Ubuntu/Debian
sudo apt-get install -y golang-go

# CentOS/RHEL
sudo yum install -y golang

# 编译
go build -o agent ./cmd/agent

# 安装到系统目录
sudo cp agent /usr/local/bin/linkmaster-node
sudo chmod +x /usr/local/bin/linkmaster-node

2. 安装系统依赖

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y ping traceroute dnsutils curl

# CentOS/RHEL
sudo yum install -y iputils traceroute bind-utils curl

3. 创建 systemd 服务

# 确保 run.sh 有执行权限
sudo chmod +x /opt/linkmaster-node/run.sh

sudo tee /etc/systemd/system/linkmaster-node.service > /dev/null <<EOF
[Unit]
Description=LinkMaster Node Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/linkmaster-node
ExecStart=/opt/linkmaster-node/run.sh start
Restart=always
RestartSec=5
Environment="BACKEND_URL=http://your-backend-server:8080"

[Install]
WantedBy=multi-user.target
EOF

注意： 使用 run.sh 启动的好处是每次启动会自动拉取最新代码并重新编译。

3.1. 配置说明

配置优先级（从高到低）：

1. 环境变量 BACKEND_URL（最高优先级）
2. 配置文件 config.yaml 中的 backend.url
3. 默认值

重要说明：

• 环境变量 BACKEND_URL 会覆盖配置文件中的设置
• 即使配置文件存在，设置环境变量后也会优先使用环境变量的值
• 这确保了编译后的二进制文件不会硬编码后端地址
• 配置文件不会被编译进二进制文件，是运行时读取的

使用环境变量（推荐）：

# 在 systemd 服务文件中设置
Environment="BACKEND_URL=http://your-backend-server:8080"

# 或在命令行中设置
BACKEND_URL=http://your-backend-server:8080 ./run.sh start

使用配置文件： 创建 /opt/linkmaster-node/config.yaml：

server:
  port: 2200
backend:
  url: http://your-backend-server:8080
heartbeat:
  interval: 60
log:
  file: node.log
  level: info
debug: false

4. 启动服务

sudo systemctl daemon-reload
sudo systemctl enable linkmaster-node
sudo systemctl start linkmaster-node

重要说明：

• 确保 BACKEND_URL 环境变量指向后端服务器的实际地址和端口（默认 8080），不是前端地址
• BACKEND_URL 环境变量会覆盖配置文件中的 backend.url 设置（优先级最高）
• 即使配置文件存在，设置环境变量后也会优先使用环境变量的值
• 这确保了编译后的二进制文件不会硬编码后端地址

防火墙配置

确保开放端口 2200：

# Ubuntu/Debian (ufw)
sudo ufw allow 2200/tcp

# CentOS/RHEL (firewalld)
sudo firewall-cmd --permanent --add-port=2200/tcp
sudo firewall-cmd --reload

常见问题

1. 克隆或编译失败

问题： 无法从 GitHub 克隆源码或编译失败

解决：

• 检查网络连接
• 确认 GitHub 仓库地址正确（独立的 node 项目仓库）
• 确认已安装 Git 和 Go 环境
• 手动克隆并编译：git clone https://github.com/yourbask/linkmaster-node.git && cd linkmaster-node && go build -o agent ./cmd/agent

2. 服务启动失败

问题： systemctl status 显示服务失败

解决：

# 查看详细日志
sudo journalctl -u linkmaster-node -n 100

# 检查后端地址是否正确
sudo systemctl cat linkmaster-node | grep BACKEND_URL

# 手动测试后端连接
curl http://your-backend-server:8080/api/public/nodes/online

3. 端口被占用

问题： 端口 2200 已被占用

解决：

# 查找占用进程
sudo lsof -i :2200

# 停止占用进程或修改配置

4. 无法连接后端

问题： 节点无法连接到后端服务器

解决：

• 检查后端地址是否正确（应该是 http://backend-server:8080，不是前端地址）
• 检查环境变量 BACKEND_URL 是否设置正确（优先级最高）
• 检查配置文件 config.yaml 中的 backend.url 是否正确
• 检查网络连通性：ping your-backend-server
• 检查端口是否开放：telnet your-backend-server 8080 或 nc -zv your-backend-server 8080
• 检查防火墙规则（确保后端服务器的 8080 端口开放）
• 检查后端服务是否运行：curl http://your-backend-server:8080/api/public/nodes/online
• 如果使用前端代理，节点端仍需要直接连接后端，不能使用前端地址

配置优先级说明：

• 环境变量 BACKEND_URL 优先级最高，会覆盖配置文件中的设置
• 如果同时设置了环境变量和配置文件，优先使用环境变量的值
• 这确保了编译后的二进制文件不会硬编码后端地址

卸载

# 停止服务
sudo systemctl stop linkmaster-node
sudo systemctl disable linkmaster-node

# 删除服务文件
sudo rm /etc/systemd/system/linkmaster-node.service
sudo systemctl daemon-reload

# 删除二进制文件和源码目录
sudo rm /usr/local/bin/linkmaster-node
sudo rm -rf /opt/linkmaster-node