# LinkMaster 节点端安装指南

## 一句话安装

### 从 GitHub 安装（推荐）

```bash
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 仓库**，与前后端项目分离

**示例：**
```bash
# 如果后端服务器在 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
```

### 指定分支安装

```bash
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 克隆源码并编译（需要网络连接）

## 安装后管理

### 查看服务状态

```bash
sudo systemctl status linkmaster-node
```

### 查看日志

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

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

### 重启服务

```bash
sudo systemctl restart linkmaster-node
```

### 停止服务

```bash
sudo systemctl stop linkmaster-node
```

### 禁用开机自启

```bash
sudo systemctl disable linkmaster-node
```

## 验证安装

### 检查进程

```bash
ps aux | grep linkmaster-node
```

### 检查端口

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

### 健康检查

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

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

## 手动安装（不使用脚本）

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

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

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

```bash
# 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 服务（参考下面的服务配置）
```

### 方式二：克隆源码并编译

```bash
# 克隆仓库
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. 安装系统依赖

```bash
# 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 服务

```bash
# 确保 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` 会**覆盖**配置文件中的设置
- 即使配置文件存在，设置环境变量后也会优先使用环境变量的值
- 这确保了编译后的二进制文件不会硬编码后端地址
- 配置文件不会被编译进二进制文件，是运行时读取的

**使用环境变量（推荐）：**
```bash
# 在 systemd 服务文件中设置
Environment="BACKEND_URL=http://your-backend-server:8080"

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

**使用配置文件：**
创建 `/opt/linkmaster-node/config.yaml`：
```yaml
server:
  port: 2200
backend:
  url: http://your-backend-server:8080
heartbeat:
  interval: 60
log:
  file: node.log
  level: info
debug: false
```

### 4. 启动服务

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

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

## 防火墙配置

确保开放端口 2200：

```bash
# 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 显示服务失败

**解决：**
```bash
# 查看详细日志
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 已被占用

**解决：**
```bash
# 查找占用进程
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` 优先级最高，会覆盖配置文件中的设置
- 如果同时设置了环境变量和配置文件，优先使用环境变量的值
- 这确保了编译后的二进制文件不会硬编码后端地址

## 卸载

```bash
# 停止服务
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
```