A modern and elegant dashboard for network traffic visualization and analysis.
Agent 安装指南
中文 | English
支持的目标平台
发布产物覆盖:
darwin-amd64darwin-arm64linux-amd64linux-arm64linux-armv7linux-mipslinux-mipsle
通过脚本安装(推荐)
curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/apps/agent/install.sh \
| env NEKO_SERVER='http://your-panel:3000' \
NEKO_BACKEND_ID='13' \
NEKO_BACKEND_TOKEN='ag_xxx' \
NEKO_GATEWAY_TYPE='clash' \
NEKO_GATEWAY_URL='http://127.0.0.1:9090' \
sh
可选环境变量:
NEKO_GATEWAY_TOKEN:网关认证 tokenNEKO_AGENT_VERSION:latest(默认)或具体标签如agent-v0.2.0NEKO_INSTALL_DIR:安装目录(默认$HOME/.local/bin)NEKO_AUTO_START:true|false(默认true,安装后立即启动并自动注册开机自启)NEKO_LOG:true|false(默认true)NEKO_LOG_FILE:运行时日志文件路径NEKO_PACKAGE_URL:自定义软件包 URLNEKO_CHECKSUMS_URL:自定义校验和 URLNEKO_INSTANCE_NAME:nekoagent管理器中的实例名(默认backend-<id>)NEKO_BIN_LINK_MODE:全局 bin 目录软链模式(auto|true|false,默认auto)NEKO_LINK_DIR:软链目标目录(默认/usr/local/bin)GITHUB_TOKEN:查询 GitHub API 时使用的 token;为空时回退到GITHUB_PAT
采集器端可设置 AGENT_HEARTBEAT_TIMEOUT_MS 调整 Agent 判定离线的心跳超时(后端列表、自动健康检查与手动测试共用)(毫秒,默认 90000,最小 15000)。默认值为 Agent 默认 30 秒心跳间隔的 3 倍,用于容忍上报延迟;此变量应配置在采集器进程的环境中,而非 Agent 安装命令中。
安装完成后,使用以下命令管理 Agent:
nekoagent status <instance>
nekoagent logs <instance>
nekoagent restart <instance>
nekoagent upgrade
nekoagent upgrade agent-vX.Y.Z
nekoagent remove <instance>
卸载二进制:
nekoagent uninstall
GitHub API rate limit / 私有镜像
查询最新版本遇到 GitHub API 匿名限流时,设置 GITHUB_TOKEN 后重试:
GITHUB_TOKEN='<github-token>' nekoagent upgrade
安装时,在已下载的 install.sh 命令前设置同一变量,并保留原有的 NEKO_* 安装参数:
GITHUB_TOKEN='<github-token>' \
NEKO_SERVER='http://your-panel:3000' \
NEKO_BACKEND_ID='13' \
NEKO_BACKEND_TOKEN='ag_xxx' \
NEKO_GATEWAY_TYPE='clash' \
NEKO_GATEWAY_URL='http://127.0.0.1:9090' \
sh ./install.sh
优先使用非空的 GITHUB_TOKEN,否则读取 GITHUB_PAT。token 仅用于 https://api.github.com 请求,不会发送到 Release 二进制、原始文件或镜像下载地址,也不会写入实例配置。使用私有镜像时,若安装仍需查询 GitHub 最新版本,可用此变量为 API 查询鉴权;镜像下载本身的访问权限须单独解决。
GitHub token rejected (401):token 无效或已失效,请更换后重试。GitHub API rate limit or forbidden (HTTP 403); set GITHUB_TOKEN(或HTTP 429):API 限流或禁止访问;设置有效 token,并检查权限或等待限额恢复。
手动安装
- 从 GitHub Releases 下载对应平台的压缩包
- 使用
checksums.txt验证哈希 - 解压
neko-agent - 携带后端参数直接运行可执行文件
可选网关参数
| Flag | 环境变量 | 默认值 | 说明 |
|---|---|---|---|
--gateway-insecure-tls |
NEKO_GATEWAY_INSECURE_TLS |
false |
跳过网关 API 的 TLS 证书校验,适用于 Surge http-api-tls / mihomo external-controller-tls 自签证书;仅在可信局域网内使用。上报服务端仍校验证书。 |
使用 nekoagent add 时可追加 --gateway-insecure-tls,管理器会持久化该配置;已有实例可在 /etc/neko-agent/<name>.env 中设置 NEKO_GATEWAY_INSECURE_TLS=true 后重启。
安装了哪些文件
安装脚本在 NEKO_INSTALL_DIR(默认 ~/.local/bin)中放置两个二进制文件:
neko-agent— 数据采集守护进程(持续运行,向面板上报数据)nekoagent— CLI 管理器(Shell 脚本,管理实例生命周期:start / stop / upgrade / remove)
nekoagent 管理器的存储位置:
- 实例配置:
CONFIG_DIR(默认/etc/neko-agent/<name>.env) - PID 与日志文件:
STATE_DIR(默认/var/run/neko-agent/)
开机自启配置
从 agent-v0.2.1 开始,安装脚本在 NEKO_AUTO_START=true 时会自动尝试注册系统开机自启(systemd / OpenWrt procd / launchd / cron 回退)。
若当前环境权限不足或不支持自动注册,可使用手动方式配置系统服务,确保重启后自动恢复运行。
Linux — systemd
创建 /etc/systemd/system/neko-agent-<instance>.service(将 <instance> 替换为实例名,如 backend-1):
[Unit]
Description=Neko Agent (<instance>)
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=root
EnvironmentFile=/etc/neko-agent/<instance>.env
ExecStart=/usr/local/bin/neko-agent \
--server-url ${NEKO_SERVER} \
--backend-id ${NEKO_BACKEND_ID} \
--backend-token ${NEKO_BACKEND_TOKEN} \
--gateway-type ${NEKO_GATEWAY_TYPE} \
--gateway-url ${NEKO_GATEWAY_URL}
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal
[Install]
WantedBy=multi-user.target
若设置了 NEKO_GATEWAY_TOKEN,在 ExecStart 末尾追加:
ExecStart=/usr/local/bin/neko-agent \
...
--gateway-token ${NEKO_GATEWAY_TOKEN}
启用并启动:
systemctl daemon-reload
systemctl enable neko-agent-<instance>
systemctl start neko-agent-<instance>
systemctl status neko-agent-<instance>
查看日志:
journalctl -u neko-agent-<instance> -f
注意:若
neko-agent安装在~/.local/bin(非 root),需相应调整ExecStart路径,并考虑以非 root 用户运行服务。
macOS — launchd
创建 ~/Library/LaunchAgents/io.neko-master.agent.<instance>.plist:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>io.neko-master.agent.<instance></string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/neko-agent</string>
<string>--server-url</string>
<string>http://your-panel:3000</string>
<string>--backend-id</string>
<string>1</string>
<string>--backend-token</string>
<string>ag_xxx</string>
<string>--gateway-type</string>
<string>clash</string>
<string>--gateway-url</string>
<string>http://127.0.0.1:9090</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>/tmp/neko-agent-<instance>.log</string>
<key>StandardErrorPath</key>
<string>/tmp/neko-agent-<instance>.log</string>
</dict>
</plist>
加载服务:
launchctl load ~/Library/LaunchAgents/io.neko-master.agent.<instance>.plist
卸载服务:
launchctl unload ~/Library/LaunchAgents/io.neko-master.agent.<instance>.plist
OpenWrt — init.d
创建 /etc/init.d/neko-agent:
#!/bin/sh /etc/rc.common
USE_PROCD=1
START=95
STOP=10
PROG=/usr/local/bin/neko-agent
INSTANCE=backend-1 # 按需修改
CONF=/etc/neko-agent/${INSTANCE}.env
start_service() {
mkdir -p /var/run/neko-agent
# 加载配置
[ -f "$CONF" ] && . "$CONF"
procd_open_instance
procd_set_param command "$PROG" \
--server-url "$NEKO_SERVER" \
--backend-id "$NEKO_BACKEND_ID" \
--backend-token "$NEKO_BACKEND_TOKEN" \
--gateway-type "$NEKO_GATEWAY_TYPE" \
--gateway-url "$NEKO_GATEWAY_URL"
[ -n "$NEKO_GATEWAY_TOKEN" ] && \
procd_append_param command --gateway-token "$NEKO_GATEWAY_TOKEN"
procd_set_param respawn 3600 5 5
procd_set_param stdout 1
procd_set_param stderr 1
procd_set_param pidfile "/var/run/neko-agent/${INSTANCE}.pid"
procd_close_instance
}
启用:
chmod +x /etc/init.d/neko-agent
/etc/init.d/neko-agent enable
/etc/init.d/neko-agent start
OpenWrt 注意事项
安装前确认架构:
uname -m
opkg print-architecture
常见对应关系:
x86_64→linux-amd64aarch64→linux-arm64armv7*→linux-armv7mips→linux-mipsmipsle→linux-mipsle