JetSprow/J-Board-Lite
1
0
Fork 0
mirror of https://github.com/JetSprow/J-Board-Lite.git synced 2026-05-01 01:14:10 +05:30
Code Issues Packages Projects Releases Wiki Activity
Files
8034392408182b9ecc38c3f0da2496100d2037f3
J-Board-Lite/agent/jboard-agent/README.md
JetSprow 8034392408 docs: update lite deployment and feature docs
2026-05-01 04:56:06 +10:00

9.5 KiB
Raw Blame History

jboard-agent

jboard-agent 是 J-Board Lite 的节点侧旁路程序。它运行在节点 VPS 上，负责把节点体验和节点真实连接证据上报到 J-Board Lite。

它做三件事：

  • 三网 TCP 延迟探测：POST /api/agent/latency
  • 三网路由追踪：POST /api/agent/trace
  • Xray access log 聚合：POST /api/agent/node-access

它不做这些事：

  • 不创建、删除或修改 3x-ui 入站。
  • 不创建、删除或修改 Xray 客户端。
  • 不重启 3x-ui 或 Xray。
  • 不接管节点流量。
  • 不作为公共代理或透明代理。

节点入站、客户端开通、暂停、删除、流量限制等配置均由 3x-ui 面板维护。Agent 只读日志文件，并通过 J-Board Lite 的 Agent Token 上报结果。

工作方式

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 Lite 的 NodeClient。[api -> api] 这类 3x-ui 本地 API 通信通常也会跳过。

Xray client email 与用户邮箱

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

J-Board Lite 用户邮箱：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 Lite 数据库里的 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 或使用反向代理鉴权。
Reference in New Issue View Git Blame Copy Permalink