Linux 节点安装：完整步骤与排错

这篇文档针对 Debian 12 与 Ubuntu 22.04/24.04 编写。其他发行版的差异主要在包管理器上。

前置条件

• 能访问外网的 Linux 机器，不需要公网 IP 或开放端口。
• root 权限（或能 sudo）。
• 已安装 Docker 并运行着节点容器（如果只做基础设施监控，可以没有 Docker）。
• Pi Desktop 已运行并登录（如果需要采集账号数据）。

第 1 步：检查依赖

客户端是一个预编译的二进制文件，依赖几个系统库：

ldd <解压目录>/pi-admin-monitor-lite | grep "not found"

输出为空说明依赖齐全。如果有 not found，按下面的对照装包：

• libatomic.so.1 对应 libatomic1
• libstdc++.so.6 对应 libstdc++6
• libgcc_s.so.1 对应 libgcc-s1

Debian/Ubuntu 上执行：

apt-get update
apt-get install -y libatomic1 libstdc++6 libgcc-s1

这一步很重要。缺依赖时主进程可能照常运行、也照常上报基础数据，但采集脚本起不来——表现为"节点在线，但算力、余额、用户名全是空的"。这个现象很容易被误判成配置问题。

第 2 步：解压

mkdir -p /opt/pi-admin-agentlite
tar -xzf pi-admin-agentlite-linux-*.tar.gz -C /opt/pi-admin-agentlite
cd /opt/pi-admin-agentlite

解压后目录里应该有：主程序、scripts/ 目录（含 node 运行时和采集脚本）、配置模板。

第 3 步：填写配置

复制配置模板并编辑：

cp config.example.json config.json

需要填的关键字段：

• token：授权令牌，从后台「添加节点」页面复制。
• server_url：服务端地址（形如 wss://api.example.com/monitor/ws，安装包里通常已预填）。
• device_id：留空即可，首次启动会自动生成并写入。

令牌的注意事项：令牌一设备一用。如果你在另一台机器上用过这个令牌，绑定会失败。换机器要重新生成令牌。

第 4 步：首次启动测试

先在前台跑一次，确认没有报错：

./pi-admin-monitor-lite --config config.json

正常的日志会依次出现这些：

• 采集服务启动
• 正在连接服务端
• 连接成功，等待鉴权
• 鉴权通过
• 采集脚本启动

然后按 Ctrl+C 停掉。如果卡在某一步，对照下面的排错表。

第 5 步：注册为系统服务

cp pi-admin-agentlite.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now pi-admin-agentlite

检查状态：

systemctl status pi-admin-agentlite

应该是 active (running)。

第 6 步：确认后台能看到节点

回到控制台，在「节点」列表里刷新，应该能看到新节点。

进入详情页检查：

• 节点名称是否显示为 Pi 账号用户名（而不是容器名）
• 算力、奖励是否有数值
• 区块高度是否在增长

排错对照表

服务起不来，状态是 `activating` 反复重启。

看日志：journalctl -u pi-admin-agentlite -n 50。最常见的原因是令牌为空或格式不对。

服务在跑，但后台看不到节点。

先确认连接是否成功：journalctl -u pi-admin-agentlite | grep -i connect。连接失败通常是网络问题或服务端地址写错（注意 ws:// 与 wss:// 的区别）。

节点在线，但数据全是空的。

按顺序查三项：

1. ldd scripts/node | grep "not found" —— node 运行时是否缺依赖。
2. pgrep -af monitor_core.js —— 采集脚本是否在跑。
3. curl -s /json | head —— Pi Desktop 的调试端口是否可用。

三项里任何一项失败，都会导致账号数据采不到。

提示"授权已被其他设备使用"。

这个令牌绑定过别的机器。在后台解绑旧设备，或重新生成令牌。

节点名称显示成容器名或随机字符串。

说明账号数据没采到，节点用的是兜底名称。按上一条排查。

关于资源占用

正常情况下主进程占用的 CPU 在 1% 以内、内存几十到一百多 MB。采集脚本（node 运行时）会额外占一些内存，属于正常。

如果 CPU 持续高，检查采集间隔是否设得太短。默认 5 分钟一次，不建议低于 1 分钟。

升级

新版发布后，在后台「系统更新」里能看到。也可以手动替换二进制：

systemctl stop pi-admin-agentlite
# 替换主程序文件
systemctl start pi-admin-agentlite

注意：不要在服务运行中直接覆盖二进制文件，会提示文件被占用或导致进程异常。

—— Pi Admin X 团队