jboard-agent
  ├─ LatencyLoop：定时 TCP connect 三网目标
  ├─ TraceLoop：定时调用 nexttrace 获取三网路由
  └─ XrayAccessLogLoop：读取 Xray access log，聚合真实来源 IP、连接数和不同目标数
       ↓
J-Board Lite /api/agent/*
       ↓
后台节点体验、订阅风控、分析日志、风险报告

Agent 使用 AUTH_TOKEN 认证。这个 token 在 J-Board Lite 后台节点页生成，服务端会通过它匹配到具体 NodeServer。

安装

推荐在 J-Board Lite 后台“节点管理”中点击生成 Agent Token，然后复制弹窗中的一键安装命令到节点机执行。安装脚本会自动完成：

下载 GitHub Release 中对应架构的二进制。
校验 SHA256SUMS。
安装或复用 nexttrace。
自动查找 Xray access log。
创建 /var/lib/jboard-agent 和 /var/log/jboard。
写入 /etc/jboard-agent.env。
停用并移除旧的 Agent systemd 服务，避免冲突。
写入并启动 jboard-agent.service。

手动安装命令形如：

curl -fsSL https://raw.githubusercontent.com/JetSprow/J-Board-Lite/main/scripts/install-jboard-agent.sh | SERVER_URL=https://panel.example.com AUTH_TOKEN=你的Token bash

如果需要指定 Agent Release：

curl -fsSL https://raw.githubusercontent.com/JetSprow/J-Board-Lite/main/scripts/install-jboard-agent.sh | AGENT_TAG=v3.1.1 SERVER_URL=https://panel.example.com AUTH_TOKEN=你的Token bash

升级

curl -fsSL https://raw.githubusercontent.com/JetSprow/J-Board-Lite/main/scripts/upgrade-jboard-agent.sh | bash

升级脚本会读取现有 /etc/jboard-agent.env，保留服务器地址、Token、探测间隔和 Xray 日志配置，并重新写入当前 systemd service。

升级后确认版本：

journalctl -u jboard-agent -n 30 --no-pager

你应该看到类似：

[agent] jboard-agent v3.1.1 starting in probe-only mode

环境变量

变量	默认值	说明
`SERVER_URL`	必填	J-Board Lite 面板公网地址，例如 `https://panel.example.com`。
`AUTH_TOKEN`	必填	后台节点页生成的 Agent Token。
`LATENCY_INTERVAL`	`5m`	延迟探测间隔，支持 `30s`、`5m` 或纯秒数。
`TRACE_INTERVAL`	`30m`	路由探测间隔，支持 `30m` 或纯秒数。
`XRAY_ACCESS_LOG_PATH`	自动探测	Xray access log 路径。为空时节点真实连接风控禁用。
`XRAY_LOG_INTERVAL`	`1m`	access log 读取、聚合、上报间隔。
`XRAY_LOG_STATE_FILE`	`/var/lib/jboard-agent/xray-log-state.json`	access log offset 状态文件。
`XRAY_LOG_START_AT_END`	`1`	首次启动从文件末尾开始，避免上传历史巨量日志；设为 `0` 可从头读取。
`INSTALL_NEXTTRACE`	`1`	安装脚本是否自动安装 nexttrace。

systemd 环境文件默认位于：

/etc/jboard-agent.env

修改环境文件后需要重启：

systemctl restart jboard-agent

Xray access log

安装/升级脚本会优先查找这些路径：

/usr/local/x-ui/access.log
/usr/local/x-ui/bin/access.log
/usr/local/x-ui/xray/access.log
/etc/x-ui/access.log
/etc/x-ui/xray/access.log
/var/log/xray/access.log
/var/log/x-ui/access.log
/opt/3x-ui/access.log
/opt/x-ui/access.log
/usr/local、/etc、/var/log、/opt、Docker volume 下名称包含 access.log 或 xray 的日志

如果没有找到，脚本会提示你在 3x-ui 的 Xray Config 中开启：

"log": {
  "access": "/usr/local/x-ui/access.log",
  "error": "/usr/local/x-ui/error.log",
  "loglevel": "warning"
}

然后重启 x-ui，再重跑 Agent 安装或升级脚本。

支持的日志格式

Agent 支持常见 Xray access log 格式，包括：

2026/04/29 10:11:12 203.0.113.9:51820 accepted tcp:example.com:443 [proxy-in >> freedom] email: user@example.com-cabc1234

也支持 3x-ui/Xray 新格式：

2026/04/29 09:20:05.982584 from 220.240.111.193:59425 accepted tcp:example.com:443 [inbound-17583 >> direct] email: user@example.com-cmojtnp3
2026/04/29 09:20:06.006542 from tcp:220.240.111.193:59433 accepted udp:71.18.167.208:443 [inbound-17583 >> direct] email: user@example.com-cmojtnp3

Agent 会解析：

sourceIp：真实来源 IP。
clientEmail：Xray client email。
inboundTag：入站 tag，例如 inbound-17583。
network：tcp 或 udp。
targetHost / targetPort：样本目标。
action：accepted 或 rejected。
connectionCount：聚合窗口内连接数。
uniqueTargetCount：聚合窗口内不同目标数。
firstSeenAt / lastSeenAt：窗口内首次和最近连接时间。

没有 email: 的日志会跳过，因为服务端无法把它归属到 J-Board 的 NodeClient。[api -> api] 这类 3x-ui 本地 API 通信通常也会跳过。

Xray client email 与用户邮箱

J-Board 用户邮箱和 Xray client email 不一定完全相同。例如：

J-Board 用户邮箱：user@example.com
Xray client email：user@example.com-cmojtnp3

这是正常设计。节点日志风控使用 Xray access log 里的 email: 匹配本地 NodeClient.email，再找到对应用户和订阅。不要手动在 3x-ui 修改 client email，否则日志会无法归属。

systemd 运维

查看服务状态：

systemctl status jboard-agent --no-pager -l

实时日志：

journalctl -u jboard-agent -f --no-pager

看最近 100 行：

journalctl -u jboard-agent -n 100 --no-pager

只看 Xray 日志采集：

journalctl -u jboard-agent -f --no-pager | grep --line-buffered xray-log

查看配置：

cat /etc/jboard-agent.env

查看 access log offset 状态：

cat /var/lib/jboard-agent/xray-log-state.json

排障

Agent 没有启动

systemctl status jboard-agent --no-pager -l
journalctl -u jboard-agent -n 100 --no-pager

常见原因：

/etc/jboard-agent.env 缺少 SERVER_URL 或 AUTH_TOKEN。
二进制没有执行权限。
旧服务没有清理干净。新安装/升级脚本会自动停用并移除旧服务。

没有 `[xray-log]` 输出

这不一定是错误。Agent 只在禁用、报错或成功推送时打印 xray-log。如果没有新 access log，实时 grep 会一直等待。

按顺序检查：

cat /etc/jboard-agent.env | grep XRAY
cat /var/lib/jboard-agent/xray-log-state.json
tail -n 50 /usr/local/x-ui/access.log
grep "email:" /usr/local/x-ui/access.log | tail -n 20

如果状态文件类似：

{"path":"/usr/local/x-ui/access.log","inode":393262,"offset":180}

说明 Agent 已经找到并跟踪日志。它会从 offset 之后继续读。

access log 只有 `[api -> api]`

例如：

2026/04/29 09:16:07.001315 from 127.0.0.1:43702 accepted tcp:127.0.0.1:62789 [api -> api]

这是 3x-ui / Xray 本地 API 通信，不是用户节点连接。你需要让真实客户端连接节点，再查看是否出现带 email: 的记录。

强制从头重读 access log

仅用于测试。生产环境不建议长期保持从头读取。

systemctl stop jboard-agent
rm -f /var/lib/jboard-agent/xray-log-state.json
sed -i 's/^XRAY_LOG_START_AT_END=.*/XRAY_LOG_START_AT_END=0/' /etc/jboard-agent.env
systemctl start jboard-agent
journalctl -u jboard-agent -n 100 --no-pager | grep xray-log

测试完成后改回：

sed -i 's/^XRAY_LOG_START_AT_END=.*/XRAY_LOG_START_AT_END=1/' /etc/jboard-agent.env
systemctl restart jboard-agent

服务端没有收到节点日志风控

检查：

后台系统设置是否开启订阅风控总控。
后台是否开启节点日志风控。
access log 是否包含 email:。
email: 是否与 J-Board 数据库里的 NodeClient.email 一致。
Agent Token 是否属于当前节点。
面板日志是否有 /api/agent/node-access 的错误。

构建

go test ./...
make build
make build-linux

生成校验和：

shasum -a 256 jboard-agent-linux-amd64 jboard-agent-linux-arm64 > SHA256SUMS

Release 规则

只有 Agent 代码或 Agent 安装/升级体验需要随二进制发布时，才创建新的 Agent tag 和 GitHub Release。普通面板页面、后台 UI、文档或 Server Action 改动不需要强行更新 Agent release。

Release 需要包含：

jboard-agent-linux-amd64
jboard-agent-linux-arm64
SHA256SUMS

安装/升级脚本默认使用 GitHub 最新 Release。需要固定版本时传入 AGENT_TAG=vX.Y.Z。

安全边界

Agent 只读 Xray access log，但日志中包含真实来源 IP、访问目标和 client email，应按敏感数据处理。
Agent Token 等同节点上报凭据，不要外传。
节点服务器上不要公开 /etc/jboard-agent.env。
3x-ui 面板建议限制来源 IP 或使用反向代理鉴权。

README.md Unescape Escape

jboard-agent

工作方式

安装

升级