PPanel

简体中文

English

简体中文

English

Appearance

2025-12-16
1098
4.8m

节点端安装 ​

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。

最近更新

Copyright © 2025 PPanel