NodeLite
5 分钟把 NodeLite 跑起来，再按需接入 HTTPS、WSS、Prometheus 和 2FA。
默认推荐路径
第一次部署时，先只做能让第一台节点上线的那几步。等确认面板正常工作，再继续配 HTTPS、Prometheus、2FA 和反向代理，会清爽很多。
把“一键安装 + Agent 上线”先跑通，就是这页最重要的部分；其余内容都可以按需慢慢展开。
快速部署
如果你只想尽快看到第一台节点在线，先按下面的最短路径走；生产环境的细化配置放在下一节。
一键安装（推荐）
交互式安装器，适合快速上手
服务端一条命令安装。脚本会自动检测架构、校验二进制哈希、生成配置和 systemd unit。
# 一条命令安装，同样命令也可用于升级
curl -fsSL https://github.com/XiNian-dada/NodeLite/releases/latest/download/install-server.sh | sudo sh
curl -fsSL https://github.com/XiNian-dada/NodeLite/releases/latest/download/install-server.sh | \ sudo NODELITE_SERVER_MODE=upgrade sh
开始前确认
- 一台可 SSH 的 Linux 主机，用来部署
nodelite-server - 一台或多台 Linux 子机，用来部署
nodelite-agent - 服务端建议预留一个域名，后面用于 HTTPS / WSS 和安装脚本分发
- 生产环境建议提前放行
80/443，并让服务端只监听回环地址
如果只是本地验证，先用内网 IP 或临时域名也可以，跑通后再补反向代理。
跑通后检查
- 服务端
systemctl status nodelite-server为active (running) - Agent 日志中出现成功连接到
/ws的记录 - 浏览器打开面板后能看到至少一台节点处于在线状态
/metrics可以被抓取，或至少本地curl返回 Prometheus 文本
进阶配置
当第一台节点已经跑起来后，再看这一节会更容易理解，也更适合生产环境使用。
手工部署
适合需要精细控制配置的进阶用户
- 从 GitHub Releases 下载对应架构的
nodelite-server二进制 - 复制
config/server.example.toml并修改关键配置（监听地址、域名、认证凭据、GeoIP 模式等） - 将二进制安装到
/usr/local/bin/nodelite-server，配置文件放到/opt/nodelite/config/server.toml - 创建 systemd unit 并启动
- 执行
install-agent签发节点命令
sudo systemctl status nodelite-server.service sudo journalctl -u nodelite-server.service -f
sudo journalctl -u nodelite-server.service -n 100 --no-pager
节点定位 & GeoIP
默认用 ipwhois 在线查询，dbip 只在需要本地数据库时启用
NodeLite 默认使用 provider = "ipwhois" 在线查询 GeoIP，不需要下载 DB-IP Lite 数据库。
如果切到 provider = "dbip"，才会启用数据库下载，右下角的 DB-IP attribution 也只在这个模式下显示。
[geoip] enabled = true provider = "ipwhois" edition = "country-lite" database_path = "./data/geoip/dbip.mmdb"
如果你在节点设置页手动指定了位置，手动结果会覆盖自动 GeoIP；需要离线使用本地数据库时再改成 provider = "custom" 并指定自己的 database_path。
节点签发 & Agent 部署
在服务端生成含一次性 token 的安装命令，粘贴到目标子机执行
# 在服务端执行，生成一条可直接粘贴到子机执行的安装命令
/usr/local/bin/nodelite-server \
--config /opt/nodelite/config/server.toml \
install-agent \
--node-id hk-01 \
--node-label "Hong Kong 01"
curl -fsSL https://monitor.example.com/install/install-agent.sh | \ NODELITE_AGENT_INSTALL_TOKEN='one-time-token' sh -s -- \ --bootstrap-url https://monitor.example.com/install/bootstrap \ --base-url https://github.com/XiNian-dada/NodeLite/releases/latest/download
# 不需要重新 bootstrap，保留现有 agent.toml
curl -fsSL https://monitor.example.com/install/install-agent.sh | \
NODELITE_AGENT_MODE=upgrade sh -s -- \
--base-url https://github.com/XiNian-dada/NodeLite/releases/latest/download
一次性 install token 有效期 15 分钟。过期后重新执行 install-agent 生成新的 token 即可。
长期 node token 只在 bootstrap 响应体中下发，不会出现在 URL 或命令参数中。
反向代理配置
Nginx 终结 HTTPS/WSS，服务端监听回环地址
生产环境推荐：nodelite-server 监听 127.0.0.1:<port>，Nginx 对外暴露 443 端口。
server {
listen 443 ssl http2;
server_name monitor.example.com;
ssl_certificate /path/to/fullchain.pem;
ssl_certificate_key /path/to/privkey.pem;
location / {
proxy_pass http://127.0.0.1:<port>;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
}
location /ws {
proxy_pass http://127.0.0.1:<port>/ws;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 120s;
proxy_send_timeout 120s;
}
location /install/ {
proxy_pass http://127.0.0.1:<port>;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
trusted_proxies。
Prometheus 集成
NodeLite 提供 /metrics 端点，输出 Prometheus exposition 文本
/metrics 端点，输出 Prometheus exposition 文本
/metrics 与仪表盘共用只读认证，抓取端需带上同样的 Basic Auth 凭据。
curl -u '<readonly-username>:<generated-strong-password>' https://monitor.example.com/metrics
scrape_configs:
- job_name: nodelite
scheme: https
metrics_path: /metrics
basic_auth:
username: <readonly-username>
password: <generated-strong-password>
static_configs:
- targets:
- monitor.example.com
交叉编译
在开发机上构建 Linux 静态二进制
仓库内置 musl 目标的 lld 链接配置，可直接交叉编译静态二进制。
cargo build --release --target x86_64-unknown-linux-musl \ -p nodelite-server \ -p nodelite-agent cargo build --release --target aarch64-unknown-linux-musl \ -p nodelite-server \ -p nodelite-agent
常见问题
部署和使用中可能遇到的问题及解决方法。
先检查 Agent 日志：
sudo journalctl -u nodelite-agent.service -n 50 --no-pager
常见原因：
- Agent 配置中的
server不是wss://或证书有问题 - 反向代理未正确转发 WebSocket（检查
Upgrade和Connection头） - Agent 的 node token 与服务端
server.json不匹配 - 防火墙未放行 443 端口或 WebSocket 路径
你仍然在使用 http:// 或 ws:// 明文链路。NodeLite 会在启动日志中每隔一段时间输出不安全传输警告。
解决方法：配置 Nginx/Caddy 终结 HTTPS/WSS，确保 server.toml 中的 public_base_url 以 https:// 开头。
请升级到 1.2.16 或更新版本。旧版本中即使 2FA 关闭，服务端也会因为 totp_secret 配置而拒绝启动。
如果你不想升级，临时方案是删除 server.toml 中的 totp_secret 字段。
一次性 install token 有效期只有 15 分钟。超时后需要在服务端重新执行 install-agent 或 issue-node 来生成新的 token。
/usr/local/bin/nodelite-server \ --config /opt/nodelite/config/server.toml \ install-agent \ --node-id hk-01 \ --node-label "Hong Kong 01"
检查以下配置：
- 服务端
[ws]段的max_total_connections和max_connections_per_ip是否太小 - 远端反代/WAF 的出口网段是否已写入
server.trusted_proxies - 同机 Nginx/Caddy 不需要额外配置
trusted_proxies
限流参数（位于 server.toml）：
[ws] max_total_connections = 1024 max_connections_per_ip = 32 auth_fail_window_secs = 300 auth_fail_max_attempts = 12 auth_block_secs = 900
每个节点 token 默认 30 天 有效期。正常在线的节点会在 token 剩余不足 7 天时自动刷新。
如果 Agent 离线超过 token 有效期：
- Agent 进入 1 小时间隔的退避重连
- 在服务端执行
install-agent --rotate-token轮换 token - 将新的
agent.toml部署到该子机
/usr/local/bin/nodelite-server \ --config /opt/nodelite/config/server.toml \ install-agent \ --node-id hk-01 \ --node-label "Hong Kong 01" \ --rotate-token
两种方式：
- 修改
server.toml中的[auth] password，然后重启服务端 - 登录面板，在设置页（
/→ 右下角齿轮图标 → 设置）中修改密码
注意：密码必须是 12 到 128 个字符 的强密码，并同时包含大写字母、小写字母、数字和特殊字符；常见弱密码会被拒绝，启动期校验不通过时服务端会直接拒绝启动。
在 server.toml 中配置：
[auth] username = "<readonly-username>" password = "<generated-strong-password>" enable_2fa = true totp_secret = "<base32-secret-from-setup>"
生成一个新的 base32 secret：
python3 - <<'PY'
import base64, secrets
print(base64.b32encode(secrets.token_bytes(20)).decode().rstrip("="))
PY
使用二维码格式添加到认证器 App：
otpauth://totp/NodeLite:viewer?secret=<totp_secret>&issuer=NodeLite
- 浏览器弹出 Basic Auth 对话框，输入用户名和密码
- 通过后跳转到
/verify-2fa页面，输入 6 位 TOTP 动态码 - 验证通过后进入面板，会话有效期 24 小时
连续 5 次 TOTP 输错会强制失效，必须重新走 Basic Auth。同一个 30 秒步长内的 TOTP 码不会被接受两次（重放防御）。
审计日志默认记录认证失败、TOTP 校验结果、token 事件和限流封禁等安全事件。
通过 API 查询：
# 查看最近 100 条失败认证
curl -u '<readonly-username>:<generated-strong-password>' 'https://monitor.example.com/api/audit-log?event_type=login_failure&success=false&limit=100'
审计日志默认保留 90 天，可在 server.toml 的 [audit] 段调整。
如果你有 SSH 和服务端文件系统访问权限：
- 编辑
server.toml中的auth.password - 重启服务端：
sudo systemctl restart nodelite-server.service
如果你开启了 2FA 且丢失了认证器，同上操作可以同时重置密码和关闭 2FA（enable_2fa = false）。
800-1000 KB 只能看作 Agent 的冷启动基线，不应该理解成长时间运行后的固定占用。
- 服务端：4-10 MB 内存
- Agent 冷启动：约 800 KB
- Agent 运行 24 小时后：约 1.2 MB
- Agent 运行 72 小时后：约 3 MB
- 200 节点并发：p95 延迟 < 5ms，metrics 吞吐 18,677/s
也就是说，当前版本的 Agent 常驻内存会随着运行时长增加而缓慢上升。这个现象已经在文档里明确标注，实际表现还会受到反向代理、SQLite I/O、历史保留时长和宿主机环境影响。
如果你对常驻内存比较敏感，建议把这些数字当作实测参考值，而不是容量上限，并在自己的环境中持续观察 RSS 变化。
系统架构
按当前源码绘制：Agent 采集并通过 WebSocket 上报，Server 认证、清洗、聚合、持久化，再向 Web UI、JSON API 和 Prometheus 暴露视图。
整体运行架构
从部署入口到 Agent 上报、Server 内存状态、历史写入和前端读取的主路径。
Server 内部组件图
AppState 是 Axum handler 和 WebSocket 会话拿到的共享上下文，后台任务围绕注册表、快照和离线状态运行。
WebSocket 协议时序
握手、认证、实时上报、心跳 RTT、token 刷新和断开处理都在一条已认证会话里完成。
存储、安全与部署边界
敏感凭证不直接暴露给前端；Registry、History、Audit 与 Snapshot 分别承担授权、趋势、安全事件和恢复。