FlowMaster 是一个面向 Linux 服务器的轻量级网络流量监控面板。它通过系统 vnstat 读取历史与实时流量，由 Node.js/Express 提供 Web 页面和 API，并使用 systemd 管理生产服务。
- 自动发现并验证 vnstat 已记录的网络接口。
- 展示实时、5 分钟粒度、小时、日、月和年流量统计。
- 支持自定义日期范围查询和多网卡切换。
- 提供响应式页面、深浅主题、图表与数据表格。
- 使用有容量和内存上限的进程内 LRU 缓存。
- 提供版本、缓存、进程内存、系统状态和 vnstat 诊断 API。
- 安装、更新和卸载均保留
/var/lib/vnstat历史数据。
- 使用 systemd 247 或更高版本的 Linux 发行版；Debian 是当前真实验证环境。安装器会读取
systemctl --version并在改动服务前拒绝过旧版本。 - Node.js 18 或更高版本，以及与该版本兼容的 npm；新部署优先使用仍受维护的 Node.js 22/24 LTS。
- vnstat 2.x。
- root 权限，用于安装依赖和创建 systemd 服务。
- 默认监听 TCP
10089；安装前请确认端口可用。
安装器支持 apt-get、dnf 或 yum，并会补装缺失的基础依赖。若发行版仓库中的 Node.js 低于 18，请先通过发行版或 Node.js 官方渠道升级。
首次安装和后续升级使用同一个脚本。已有安装会在菜单中显示“安全更新/重新部署 FlowMaster”。
curl -fL --retry 3 --connect-timeout 10 --max-time 120 -o install.sh \
https://raw.githubusercontent.com/vbskycn/FlowMaster/main/install.sh
chmod +x install.sh
sudo ./install.sh下面的命令尝试让安装脚本和源码归档都通过代理下载；只给第一条 curl 加代理并不能加速安装器后续的源码下载。
curl -fL --retry 3 --connect-timeout 10 --max-time 120 -o install.sh \
https://gh-proxy.com/https://raw.githubusercontent.com/vbskycn/FlowMaster/main/install.sh
chmod +x install.sh
sudo env \
FLOWMASTER_DOWNLOAD_URL='https://gh-proxy.com/https://github.com/vbskycn/FlowMaster/archive/refs/heads/main.tar.gz' \
./install.shgh-proxy.com 是第三方服务，其可用性和返回内容不由本项目控制。能直连 GitHub 时优先使用官方地址；对可复现部署要求较高时，请固定 Release 标签并从可信渠道核对 SHA-256，参见安装与运维指南。
安装器与备份工具共享维护锁；源码归档通过结构校验后才会执行可复现依赖安装和带随机实例令牌的临时冒烟测试。目录替换、unit 和控制命令更新处于同一回滚事务中，收到信号或启动验证失败都会恢复旧状态。成功更新后的旧程序以 /opt/.flowmaster-rollback-* 保留。
从旧 PM2 部署迁移时，如果安装器检测到可信且仍包含 FlowMaster 的 PM2 systemd 服务，无论它当前健康还是无响应，都会列出受影响的已保存应用并要求输入
RECOVER-PM2。请先核对列表，不要自行执行pm2 delete、pm2 kill或直接杀死 PM2 守护进程。详细流程见PM2 迁移与僵尸进程处理。
安装完成后访问：
http://服务器IP:10089
常用命令：
sudo flowmaster start
sudo flowmaster stop
sudo flowmaster restart
sudo flowmaster status
sudo flowmaster logs也可以直接使用 systemd：
sudo systemctl status flowmaster.service --no-pager
sudo journalctl -u flowmaster.service -f公网部署时应使用 HTTPS 反向代理、限制 10089 的访问来源，并设置 ADMIN_TOKEN。该令牌只保护管理接口，不会为整个面板增加登录认证；如需限制全部页面和查询 API，请同时在反向代理层配置访问控制。
生产服务以专用的 flowmaster 系统账号运行，不再以 root 运行。程序目录仅允许 root 写入，服务账号只获得读取程序、配置和 vnstat 数据所需的权限。
生产安装目录是 /opt/flowmaster。首次创建配置文件时：
sudo cp -n /opt/flowmaster/.env.example /opt/flowmaster/.env
sudo chown root:flowmaster /opt/flowmaster/.env
sudo chmod 640 /opt/flowmaster/.env
sudo editor /opt/flowmaster/.env
sudo systemctl restart flowmaster.service更新时安装器会保留已有 .env。不要用当前 Shell 的 export 代替配置文件；systemd 服务不会继承该终端环境。
常用安全项：
ADMIN_TOKEN=请替换为高强度随机值
ALLOW_ANONYMOUS_ADMIN=false
CORS_ORIGINS=https://monitor.example.com
TRUST_PROXY=false只有 FlowMaster 确实位于可信反向代理之后时才能启用 TRUST_PROXY。全部配置项、默认值和边界见安装与运维指南。
FlowMaster 不拥有 vnstat 数据库。安装、更新和卸载不会删除 /var/lib/vnstat。
安装后可运行交互式备份恢复工具：
sudo bash /opt/flowmaster/backup_vnstat.sh默认备份目录是 /var/backups/flowmaster/vnstat。工具会在停服前验证归档结构、内外校验和与 vnstat 数据库，恢复失败或被信号中断时会换回原数据。
卸载时重新运行安装脚本并选择“卸载 FlowMaster”。程序文件会原子归档；备份根目录与 /opt 同一文件系统时位于 /var/backups/flowmaster/.flowmaster-uninstalled-*，否则保留为 /opt/.flowmaster-uninstalled-*。vnstat 数据保持不变。
完整的备份、恢复和回滚边界见安装与运维指南。
常用端点：
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/interfaces |
获取可用网络接口 |
| GET | /api/stats/:interface/:period |
获取指定周期统计 |
| GET | /api/stats/:interface/range/:startDate/:endDate |
获取日期范围统计 |
| GET | /api/version |
获取产品版本 |
| GET | /api/system/status |
获取运行状态 |
| POST | /api/cache/clear |
清空缓存，管理接口 |
| GET | /api/test/vnstat |
执行 vnstat 诊断，管理接口 |
period 支持 l、5、h、d、m、y。管理接口默认拒绝匿名请求；配置 ADMIN_TOKEN 后使用请求头 X-Admin-Token。确需兼容可信内网旧调用方时可显式设置 ALLOW_ANONYMOUS_ADMIN=true。
非实时统计在保留现有 data 文本的同时提供 MiB 精度的 series；实时响应提供 timestamp、stale 和 ageMs，便于客户端识别陈旧样本。
请求、响应、鉴权和状态码说明见 API 文档。
sudo flowmaster status
sudo journalctl -u flowmaster.service -n 100 --no-pager
curl --fail http://127.0.0.1:10089/api/version如果修改过 PORT 或 HOST，请按 /opt/flowmaster/.env 中的实际值检查。
sudo systemctl status vnstat --no-pager
vnstat --dbiflist 1
ip route show default新接口需要先由 vnstat 建库和采样；刚添加后可能需要等待一个采样周期。
sudo ss -ltnp | grep ':10089'确认占用进程后再决定是释放端口，还是修改 /opt/flowmaster/.env 中的 PORT 并重启服务。
不要反复调用 PM2 命令。下载最新版安装脚本并重新执行；无论旧 PM2 当前健康还是无响应，安装器都只会在确认 PM2 守护进程、独立 systemd 服务、cgroup 和保存清单均可信后提供 RECOVER-PM2 迁移。恢复备份位于 /var/backups/flowmaster/pm2-recovery-*。
更多诊断步骤见安装与运维指南。
npm ci
npm run test:ci源码调试、Linux 测试、提交规范和完整发布前检查见 CONTRIBUTING.md。项目版本以 package.json 的 version 为唯一来源，正式变化记录在 CHANGELOG.md。
- 问题反馈：GitHub Issues
- 版本发布：GitHub Releases
- 开源协议：MIT
如果 FlowMaster 对你有帮助，也可以支持项目：
