169 lines
5.3 KiB
Markdown
169 lines
5.3 KiB
Markdown
# 节点端安装
|
||
|
||
`ppanel-node` 是部署在边缘服务器上的轻量代理守护进程，基于 `xray-core`，负责同步路由、订阅、心跳与密钥。本指南提供最快速的一键安装方式，并补充源码与容器方案。
|
||
|
||
## 快速开始
|
||
|
||
```bash
|
||
wget -N https://raw.githubusercontent.com/perfect-panel/ppanel-node/master/scripts/install.sh
|
||
sudo bash install.sh --api-host https://panel.example.com --server-id 1 --secret-key <SECRET>
|
||
```
|
||
|
||
脚本会自动识别系统/架构、拉取最新版、安装 geo 数据，并配置 `ppnode` CLI 与系统服务。
|
||
|
||
### 环境要求
|
||
|
||
- 64 位 Linux（Debian/Ubuntu ≥16、CentOS ≥7、Alpine、Arch 等）
|
||
- 拥有 root 权限，且可访问 `github.com`
|
||
- 防火墙需放通对外协议端口及访问面板的 443 端口
|
||
- 面板后台已生成匹配的 **Server ID** 与 **Secret Key**
|
||
|
||
### 可选参数
|
||
|
||
- 位置参数 `vX.Y.Z`：安装指定 tag。
|
||
- `--api-host https://panel.example.com`
|
||
- `--server-id <ID>`（对应运维→服务器 管理页面中的记录）
|
||
- `--secret-key <KEY>`
|
||
|
||
若未传入参数，脚本会在安装过程中交互式询问。
|
||
|
||
### 服务管理
|
||
|
||
安装完成后可通过 CLI 管理：
|
||
|
||
```bash
|
||
ppnode status # 查看状态
|
||
ppnode start # 启动
|
||
ppnode restart # 重启 + 重新加载配置
|
||
ppnode log # 查看日志
|
||
ppnode update # 升级至最新版本
|
||
ppnode update v1.2 # 安装指定版本
|
||
ppnode uninstall # 卸载
|
||
ppnode generate # 重新生成 /etc/PPanel-node/config.yml
|
||
```
|
||
|
||
## 安装方式
|
||
|
||
### 方式一：一键脚本（推荐）
|
||
|
||
执行上方快速开始命令或运行 `sudo bash install.sh` 并按提示填写信息。脚本包含以下步骤：
|
||
|
||
1. 根据发行版安装依赖（`wget`、`curl`、`tar`、`socat`、cron 等）。
|
||
2. 下载 `ppanel-node-linux-<arch>.zip`（支持 amd64/arm64/s390x）。
|
||
3. 解压到 `/usr/local/PPanel-node`，安装 `geoip.dat`、`geosite.dat`，配置系统服务。
|
||
4. 安装 `/usr/bin/ppnode` 管理脚本并设置开机自启。
|
||
|
||
### 方式二：从源码构建
|
||
|
||
1. 安装 Go 1.21+，并启用 JSON v2 实验特性：
|
||
|
||
```bash
|
||
export GOEXPERIMENT=jsonv2
|
||
```
|
||
|
||
2. 克隆仓库并编译：
|
||
|
||
```bash
|
||
git clone https://github.com/perfect-panel/ppanel-node.git
|
||
cd ppanel-node
|
||
GOEXPERIMENT=jsonv2 go build -v -o ./ppnode -trimpath -ldflags "-s -w -buildid="
|
||
```
|
||
|
||
3. 复制二进制与 geo 数据：
|
||
|
||
```bash
|
||
sudo install -Dm755 ./ppnode /usr/local/PPanel-node/ppnode
|
||
sudo install -Dm644 ./geoip.dat /etc/PPanel-node/geoip.dat
|
||
sudo install -Dm644 ./geosite.dat /etc/PPanel-node/geosite.dat
|
||
```
|
||
|
||
4. 创建 systemd 服务：
|
||
|
||
```bash
|
||
sudo tee /etc/systemd/system/PPanel-node.service <<'EOF'
|
||
[Unit]
|
||
Description=PPanel Node
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
ExecStart=/usr/local/PPanel-node/ppnode server
|
||
Restart=always
|
||
RestartSec=10
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
EOF
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable --now PPanel-node
|
||
```
|
||
|
||
5. 复制仓库中的 `config.yml` 或手动创建（见配置章节），最后重启服务。
|
||
|
||
### 方式三：容器化部署
|
||
|
||
仓库自带 `Dockerfile`，可在不方便直接安装的宿主机上运行：
|
||
|
||
```bash
|
||
git clone https://github.com/perfect-panel/ppanel-node.git
|
||
cd ppanel-node
|
||
docker build -t ppanel-node:latest .
|
||
docker run -d --name ppanel-node \
|
||
--net host \
|
||
-v /etc/PPanel-node:/etc/PPanel-node \
|
||
ppanel-node:latest server
|
||
```
|
||
|
||
建议挂载的目录：
|
||
|
||
- `/etc/PPanel-node/config.yml` —— 保存 API/密钥配置。
|
||
- `/etc/PPanel-node/geoip.dat` 与 `/etc/PPanel-node/geosite.dat` —— 持久化 Geo 数据文件。
|
||
- `/var/log/ppanel-node`（可选）—— 在宿主机收集日志。
|
||
|
||
## 配置节点
|
||
|
||
运行时配置位于 `/etc/PPanel-node/config.yml`，结构如下：
|
||
|
||
```yaml
|
||
Log:
|
||
Level: warn # debug | info | warn | error
|
||
Output: "" # 为空代表 stdout，也可以写入文件
|
||
Access: none # 访问日志路径，none 为关闭
|
||
|
||
Api:
|
||
ApiHost: https://panel.example.com
|
||
ServerID: 3
|
||
SecretKey: b23d8ee1cfe44d7f
|
||
Timeout: 30
|
||
```
|
||
|
||
修改完成后重启服务：
|
||
|
||
```bash
|
||
sudo systemctl restart PPanel-node
|
||
# 或
|
||
ppnode restart
|
||
```
|
||
|
||
### 与面板的映射关系
|
||
|
||
1. 在 **运维管理 → 服务器管理** 中创建记录，获取对应的 Server ID 与 Secret Key。
|
||
2. 将上述信息填入 `config.yml`，`ApiHost` 必须是面板的公网可访问地址。
|
||
3. 确保节点能够访问面板 443 端口，且面板允许节点 IP 回连。
|
||
4. 节点上报后会在面板中显示为在线，通常 30 秒内即可看到心跳。
|
||
|
||
## 升级与回滚
|
||
|
||
- `ppnode update` 仅替换二进制，保留配置与 geo 文件。
|
||
- `ppnode update vX.Y.Z` 可按版本号回滚。
|
||
- 源码部署时，重新构建目标 tag，替换 `/usr/local/PPanel-node/ppnode` 并 `systemctl restart PPanel-node`。
|
||
|
||
## 故障排查
|
||
|
||
- `ppnode log` 或 `journalctl -u PPanel-node -f` 查看运行日志。
|
||
- 确认 `/etc/PPanel-node/config.yml` 中 `ApiHost`、`SecretKey` 填写正确。
|
||
- 保证服务器可访问 GitHub（更新）与面板域名的 443 端口。
|
||
- 面板显示离线时检查防火墙是否放行心跳、系统时间是否同步（`chronyc tracking`）。
|
||
|
||
更多细节可参阅源仓库：[`github.com/perfect-panel/ppanel-node`](https://github.com/perfect-panel/ppanel-node)。
|