Agent 接入与配置

Agent 负责采集服务器状态、执行探测并在管理员授权后提供远程能力。

Agent 口径

本页使用 Lite 配套的 nuomiiiii/Lite-agent。它有独立仓库、Lite-agent-* 二进制、Docker 镜像和自动更新源；协议细节见 Agent RFC。

接入单台服务器时，先在 Lite 后台添加节点，再打开该节点的“节点配置”，切换到“部署指令”，选择平台和安装选项后复制完整命令到目标服务器执行。

安装、服务状态、日志、更新、重启和卸载命令统一见 Agent 安装与维护。

请使用版本与功能范围中列出的配套 Lite-agent 2.3.6.0。当前版本仅使用协议 2，支持 MCP 完整管理和精确流量重置时间，并保留远程执行去重、Lite 安装目录迁移和断线重连。Windows 开启远程控制后不再弹出桌面提示；Windows 安装脚本也修复了服务状态误报和误提 komari-agent 的问题。只支持旧协议的 Agent 无法继续接入，应先升级。

JSON 配置

json

{
  "endpoint": "https://example.com",
  "token": "your-token",
  "interval": 3,
  "month_rotate": 1,
  "month_rotate_time": "00:00:00",
  "month_rotate_timezone": "Asia/Shanghai",
  "disable_auto_update": false,
  "remote_control_enabled": false,
  "ignore_unsafe_cert": false
}

bash

./Lite-agent --config ./config.json

完整参数以 Agent 仓库和 ./Lite-agent --help 为准。

常用参数

参数	用途
`--interval`	服务器状态采集间隔，单位秒
`--include-nics` / `--exclude-nics`	限定参与流量统计的网卡
`--include-mountpoint`	限定参与统计的挂载点
`--month-rotate`	每月流量重置日期；`0` 表示关闭，`1..31` 表示日期
`--month-rotate-time`	流量重置时间，格式为 `HH:MM:SS`
`--month-rotate-timezone`	流量重置使用的 IANA 时区，如 `Asia/Shanghai` 或 `UTC`
`--enable-remote-control`	启用远程终端、文件、命令和 MCP；新安装默认关闭
`--prefer-ip-version`	优先使用 IPv4 或 IPv6
`--custom-dns`	指定 Agent 使用的 DNS
`--ignore-unsafe-cert`	忽略证书错误，仅用于受控测试环境

配置保存与在线下发

服务器列表中的 Agent 部署配置按节点保存在 Lite 服务端，不依赖当前浏览器。可在线修改的运行配置包括采集间隔、流量重置时区/日期/时间、包含或排除网卡、包含挂载点、内存缓存计入方式和 GPU 监控。

操作流程如下：

“保存配置”只把内容保存到 Lite，状态为“已保存”。
“保存并下发”会保存最新内容并发送给在线 Agent，状态变为“已发送”。
Agent 应用成功并回传确认后，状态变为“已生效”。
Agent 拒绝或应用失败时显示“应用失败”，界面会保留原因供排查。

离线节点只保留最后一次等待下发的配置。恢复连接后不会重复应用此前已经被覆盖的版本。

不能在线下发的选项

启用远程控制、忽略不安全证书、禁用自动更新、从网卡获取 IP 地址、GitHub 代理、安装目录和服务名只会保存到安装配置，用于生成新的部署指令。它们不会进入在线下发内容，需要在节点本地更新启动参数并重启或重新安装 Agent 才能改变。

Agent 会上报当前生效配置。Lite 仅使用上报内容初始化尚未保存过配置的节点，不会用旧 Agent 状态覆盖管理员已保存的内容。

从旧 Agent 迁移

完成从上游 Komari 到 Lite 的服务端迁移后，可在仍运行 komari-agent 的原节点上执行 Lite-agent 专用迁移脚本。它会保留原 endpoint、Token 和启动参数，并在新服务成功启动后才卸载旧服务；不要改用新节点部署命令，也不要给迁移脚本传入新的 Token。Linux、Windows 与 Docker 的具体做法见从上游 komari-agent 迁移。

Lite 已经停止自动发现注册，新节点必须先在后台添加，再使用各自的普通部署命令。旧自动发现安装的保留条件和迁移步骤见旧自动发现安装迁移。

远程执行去重

Lite-agent 会在本地记录最近 24 小时、最多 256 条远程执行任务状态。通过 WebSocket 直接下发和断线后的排队投递使用同一套检查，同一个 task_id 不会重复执行。

如果 Agent 在命令执行期间崩溃或被强制结束，重启后会向 Lite 报告“执行状态未知”，不会自行重新运行该命令。这里的 256 指任务记录条数，不是磁盘容量。

流量重置时间

面板中的“流量重置时间”同时用于服务器账单统计、流量校准和 Agent 本地流量周期。按服务商账单选择 IANA 时区，填写每月日期和 HH:MM:SS 时间；日期 0 表示关闭，1..31 表示启用。日期超出当月天数时按当月最后一天计算。

已有节点只设置了重置日时，Lite-agent 2.3.6.0 会继续按 Asia/Shanghai 当天 00:00:00 重置。通过“保存并下发”发送给在线 Agent 后，Agent 会确认是否已应用；离线 Agent 恢复连接后再应用最新变更，不会删除本地 net_static.json 中已经采集的流量。

Cloudflare Access

Agent 支持 Service Token：

bash

./Lite-agent \
  --endpoint "https://example.com" \
  --token "你的-Agent-Token" \
  --cf-access-client-id "client-id" \
  --cf-access-client-secret "client-secret"

这两个值必须成对配置。不要把它们放进公开仓库或可被普通用户读取的进程日志。

连接故障

遇到证书、DNS、连接超时、反复重启或进程运行但节点离线时，按 Agent 日志排查的顺序检查。

Agent 接入与配置 ​

JSON 配置 ​

常用参数 ​

配置保存与在线下发 ​

不能在线下发的选项 ​

从旧 Agent 迁移 ​

远程执行去重 ​

流量重置时间 ​

Cloudflare Access ​

连接故障 ​