Agent 安装与维护

当前配套版本为 Lite-agent 2.3.6.0，推荐配合 Lite 2.3.7 的当前服务端和后台构建使用。此版本优化远程文件上传和下载，支持二进制传输与并行上传；只更新 Agent 时仍兼容原有方式。精确流量重置、MCP 完整管理、上游 Agent 迁移、HTTP 压缩回退、运行时内存优化和 Windows 安装修复继续保留。远程终端、文件管理、远程执行和 MCP 共用本地远程控制开关。

本页覆盖 Agent 的安装、状态检查、日志、重启、更新和卸载。节点配置与在线下发见 Agent 接入与配置，旧自动发现安装的处理方法见 旧自动发现安装迁移。

安装前确认

单台服务器应先在 Lite 后台添加节点，再打开该节点的“节点配置”并切换到“部署指令”。选择目标系统和安装选项后，点击“保存并复制部署指令”，在目标服务器上执行完整命令。

Linux 安装脚本的默认值如下：

项目	默认值
服务名	lite-agent
安装目录	/opt/lite-agent
程序路径	/opt/lite-agent/Lite-agent
运行用户	root

如果安装时使用了 --install-service-name 或 --install-dir，后续命令必须替换为实际服务名和目录。

安装 Agent

Linux 和 macOS

推荐直接执行后台生成的命令。需要手工安装时，可下载脚本后运行：

curl -fsSL https://raw.githubusercontent.com/nuomiiiii/Lite-agent/main/install.sh -o install-lite-agent.sh
sudo bash install-lite-agent.sh \
  --endpoint "https://example.com" \
  --token "你的-Agent-Token" \
  --enable-remote-control=false

安装脚本会识别 systemd、OpenRC、OpenWrt procd、macOS launchd 或 Upstart，并创建对应服务。新安装默认关闭远程控制；需要使用远程终端、文件管理、远程执行或 MCP 时，将最后一项改为 --enable-remote-control，并同时在 Lite 后台开启“允许远程管理”。使用 MCP 还需开启“启用 MCP 代理”，具体流程见MCP 代理与 AI 授权。

脚本再次运行时会替换原 Lite-agent 服务和程序，适合更新或修改必须重装才能生效的安装参数。从上游 komari-agent 接续原节点时，请使用下方专用迁移脚本。

FreeBSD 请从 Agent Releases 下载对应架构的二进制，按 JSON 配置启动，并自行配置系统服务。当前脚本不会自动创建 FreeBSD 原生 rc.d 服务。

保护节点凭据

Cloudflare Access Service Token、完整安装命令和历史身份文件都属于敏感信息。不要把它们或服务启动参数、日志原样贴到公开工单。

从上游 komari-agent 迁移

如果已经完成从上游 Komari 到 Lite 的服务端迁移，并且原有节点记录仍保留在 Lite 后台，可在每台仍运行上游 komari-agent 的服务器上使用专用迁移脚本接续原节点。不要重新添加节点或生成新 Token。

脚本会保留原面板地址、Token 和启动参数，安装 Lite-agent，并在新服务成功启动后才卸载旧服务。具体变更记录见 Lite-agent 2.3.6.0 Release。

Linux 上主控地址不变时执行：

curl -sL https://raw.githubusercontent.com/nuomiiiii/Lite-agent/main/migrate.sh | sudo bash

主控改为新地址时执行：

curl -sL https://raw.githubusercontent.com/nuomiiiii/Lite-agent/main/migrate.sh | sudo bash -s -- \
  --endpoint "https://lite.example.com"

Windows 上在管理员 PowerShell 中执行：

powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "iwr https://raw.githubusercontent.com/nuomiiiii/Lite-agent/main/migrate.ps1 -UseBasicParsing -OutFile 'migrate.ps1'; & .\migrate.ps1"

迁移时不要传入新的 --token，也不要修改安装目录或服务名。Docker 不运行迁移脚本，应保留原来的 endpoint 和 Token 参数，直接重建为 Lite-agent 容器。

Docker

Docker 用户应优先使用后台生成的 docker run 或 Compose 配置。默认拉取 latest：

docker pull ghcr.io/nuomiiiii/lite-agent:latest

需要固定当前正式版时使用：

docker pull ghcr.io/nuomiiiii/lite-agent:2.3.6.0

镜像地址必须使用小写 lite-agent；如果后台生成的命令中仍是 Lite-agent，请先改为上述小写地址，否则 Docker 会拒绝执行。

新安装和重建容器应使用 Lite 后台为具体节点生成的普通 docker run 或 Compose 配置。仍在运行的旧自动发现容器需先按旧自动发现安装迁移处理。Docker Agent 不会在容器内替换自身程序，更新时必须拉取新镜像并重建容器。

Windows

在管理员 PowerShell 中执行后台生成的安装命令。脚本默认安装到：

C:\Program Files\Lite

默认服务名为 lite-agent，由 NSSM 管理并设置为自动启动。

查看当前状态

systemd

sudo systemctl is-enabled lite-agent
sudo systemctl is-active lite-agent
sudo systemctl status lite-agent --no-pager -l

正常情况下，服务应同时显示 enabled 和 active。状态页中的启动命令还能帮助确认面板地址、安装路径和是否使用了自定义参数。

Docker

docker ps --filter name=lite-agent
docker inspect --format '{{.State.Status}} / restart={{.RestartCount}}' lite-agent

容器状态为 running 只表示进程存在，还应在 Lite 后台确认节点在线、最后上报时间持续更新。

OpenRC 与 OpenWrt

sudo rc-service lite-agent status

OpenWrt procd：

/etc/init.d/lite-agent status

Windows

Get-Service -Name lite-agent
$nssm = (Get-Command nssm -ErrorAction SilentlyContinue).Source
if (-not $nssm) { $nssm = Join-Path $env:ProgramFiles "Lite\nssm.exe" }
& $nssm status lite-agent

macOS

系统级安装：

sudo launchctl print system/com.lite.lite-agent

用户级安装：

launchctl print "gui/$(id -u)/com.lite.lite-agent"

查看日志

systemd

最近 100 行：

sudo journalctl -u lite-agent -n 100 --no-pager

持续查看：

sudo journalctl -u lite-agent -f

只看最近 30 分钟：

sudo journalctl -u lite-agent --since "30 minutes ago" --no-pager

如果使用了自定义服务名，请把命令中的 lite-agent 替换为实际名称。

Docker

docker logs --tail 100 lite-agent
docker logs -f lite-agent

OpenRC、OpenWrt 与 macOS

OpenRC 不固定日志文件位置，需按系统实际使用的 syslog 服务查看；Alpine 常见方式是先检查 /var/log/messages，或使用系统已经配置的日志命令。

OpenWrt 可查看系统日志：

logread -e lite-agent
logread -f

macOS 安装脚本会把标准输出和错误写入以下文件之一：

/var/log/lite-agent.log
~/Library/Logs/lite-agent.log

tail -n 100 /var/log/lite-agent.log

用户级安装请改用 $HOME/Library/Logs/lite-agent.log。

Windows

Windows 安装脚本默认不会创建独立的 Agent 文本日志。先用 Get-Service 和 Lite 后台的最后上报时间判断状态；服务启动失败时，再查看“事件查看器 → Windows 日志 → 应用程序”中的 NSSM 或服务错误。

分享日志前先脱敏

删除面板域名、IP、Cloudflare Access 凭据和完整启动参数。不要为了排查而关闭 TLS 校验。

根据日志排查

现象	优先检查
401 或 403	面板地址是否指向正确实例、Cloudflare Access 凭据是否成对配置
证书或 x509 错误	域名是否匹配证书、证书链是否完整、服务器时间是否正确
connection refused	面板端口是否监听、防火墙和反向代理是否指向正确端口
DNS 或超时	Agent 所在节点能否解析并访问面板域名，自定义 DNS 和 IPv4/IPv6 偏好是否合适
服务反复重启	查看最早出现的参数、权限或配置文件错误，不要只截取最后一行
进程运行但面板离线	先核对 Lite 与 Lite-agent 是否为手册列出的兼容组合，再检查 WebSocket 和代理超时
在线但流量或磁盘缺失	检查包含/排除网卡、挂载点和采集间隔，确认没有把实际设备过滤掉
配置停在“已发送”	确认 Agent 在线且版本支持配置回执；查看日志中的配置应用失败原因

当前配套 Lite-agent 使用 WebSocket 心跳、读超时和快速重连。更新后仍频繁离线时，应继续检查反向代理、Cloudflare Access、DNS 和网络路径，不要靠定时重启掩盖问题。

重启与更新

systemd

sudo systemctl restart lite-agent
sudo systemctl status lite-agent --no-pager -l

更新可在 Lite 后台发起，也可以重新执行当前节点的完整安装命令。重新运行脚本会替换程序和服务配置，但不会主动删除安装目录中的 auto-discovery.json、net_static.json 等数据文件，也会保留升级前的远程控制状态。使用普通部署命令后，遗留的 auto-discovery.json 不再参与启动；仍使用旧自动发现参数的安装必须先完成迁移。新安装默认关闭远程控制，不代表已有节点升级后会被自动关闭。

Docker

docker pull ghcr.io/nuomiiiii/lite-agent:latest

拉取后使用 Lite 后台为原节点生成的普通参数、卷挂载和重启策略重建容器。旧自动发现容器在改用普通部署命令并确认原节点上线前，不要删除持久化的 auto-discovery.json。

OpenRC、OpenWrt、Windows 与 macOS

sudo rc-service lite-agent restart

/etc/init.d/lite-agent restart

Restart-Service -Name lite-agent

# macOS 系统级安装
sudo launchctl kickstart -k system/com.lite.lite-agent

# macOS 用户级安装
launchctl kickstart -k "gui/$(id -u)/com.lite.lite-agent"

卸载 Agent

卸载系统服务不会自动删除 Lite 后台中的服务器记录。确认该节点不再使用后，再决定是否从后台删除服务器。

一键完全卸载（默认 systemd 安装）

确认不再需要恢复节点身份后，可复制并执行下面这一条命令。它会停止并删除默认的 lite-agent 服务，同时永久删除 /opt/lite-agent 中的程序、历史身份文件和本地流量状态：

sudo sh -eu -c 'if [ "$(systemctl show -p LoadState --value lite-agent.service)" != "not-found" ]; then systemctl disable --now lite-agent.service; fi; rm -f /etc/systemd/system/lite-agent.service; systemctl daemon-reload; systemctl reset-failed lite-agent.service 2>/dev/null || true; rm -rf -- /opt/lite-agent'

执行后无法恢复节点凭据

这条命令只适用于默认服务名 lite-agent 和默认安装目录 /opt/lite-agent。使用过 --install-service-name 或 --install-dir 时不要直接执行，请按下面的分步方式替换为实际值。

systemd

先移除服务：

sudo systemctl disable --now lite-agent
sudo rm -f /etc/systemd/system/lite-agent.service
sudo systemctl daemon-reload
sudo systemctl reset-failed lite-agent.service

这时 /opt/lite-agent 仍保留节点凭据和流量文件。确认不再需要恢复原节点身份后，才执行完整清理：

sudo rm -rf /opt/lite-agent

完整清理不可恢复

删除安装目录会同时删除 Agent 程序、历史身份文件和本地流量状态。旧自动发现安装在改用普通部署命令前，应保留 auto-discovery.json；需要保留本地流量周期时，还应备份 net_static.json。

Docker

docker stop lite-agent
docker rm lite-agent

以上命令不会删除宿主机持久化文件。确认不再需要节点身份后，再手工删除对应的 auto-discovery.json；不要误删其他容器共用目录。

OpenRC 与 OpenWrt

sudo rc-service lite-agent stop
sudo rc-update del lite-agent default
sudo rm -f /etc/init.d/lite-agent

OpenWrt：

/etc/init.d/lite-agent stop
/etc/init.d/lite-agent disable
rm -f /etc/init.d/lite-agent

确认无需保留凭据后，再删除实际安装目录。

Windows

在管理员 PowerShell 中执行：

$nssm = (Get-Command nssm -ErrorAction SilentlyContinue).Source
if (-not $nssm) { $nssm = Join-Path $env:ProgramFiles "Lite\nssm.exe" }
& $nssm stop lite-agent
& $nssm remove lite-agent confirm

只移除服务会保留 C:\Program Files\Lite。确认无需保留节点身份和本地数据后，再删除该目录：

Remove-Item -LiteralPath "$env:ProgramFiles\Lite" -Recurse -Force

macOS

系统级服务：

sudo launchctl bootout system /Library/LaunchDaemons/com.lite.lite-agent.plist
sudo rm -f /Library/LaunchDaemons/com.lite.lite-agent.plist

用户级服务：

launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.lite.lite-agent.plist"
rm -f "$HOME/Library/LaunchAgents/com.lite.lite-agent.plist"

最后确认实际安装目录和凭据是否仍需保留，再决定是否删除 /usr/local/lite-agent 或 $HOME/.lite-agent。