vergoh/vnstat

容器化vnStat

vnStat是一款网络流量监控工具，它使用内核提供的网络接口统计信息作为数据来源，无需实际嗅探流量，因此无论网络流量速率如何，都能保持较低的系统资源占用。

默认情况下，流量统计数据按以下周期保留：最近48小时为5分钟级别、最近4天为每小时级别、最近2个完整月份为每天级别、年度级别数据永久保留。数据保留周期可完全由用户配置，同时提供总流量统计和每日流量排名功能。

更多详情和输出示例可参见官方网站或https://github.com/vergoh/vnstat%E3%80%82%E5%9B%BE%E5%83%8F%E8%BE%93%E5%87%BA%E7%A4%BA%E4%BE%8B%E5%8F%AF%E6%9F%A5%E7%9C%8B%E6%AD%A4%E5%A4%84%E3%80%82

容器内容

• vnStat守护进程（vnstatd）作为主进程运行
• lighttpd通过HTTP提供vnStat图像输出（vnstati）（默认在所有接口的8685端口）
  • 同时提供JSON和Prometheus兼容的指标端点作为替代
• vnStat命令行工具（vnstat）

支持的标签

• Docker Hub
  • https://github.com/vergoh/vnstat-docker/blob/master/Dockerfile - https://github.com/vergoh/vnstat/releases%E7%9A%84vnStat%E7%89%88%E6%9C%AC
  • https://github.com/vergoh/vnstat-docker/blob/master/Dockerfile-dev - GitHub仓库的https://github.com/vergoh/vnstat/commits/master%E7%89%88%E6%9C%AC
• GitHub Container Registry
  • https://github.com/vergoh/vnstat-docker/blob/master/Dockerfile - https://github.com/vergoh/vnstat/releases%E7%9A%84vnStat%E7%89%88%E6%9C%AC
  • https://github.com/vergoh/vnstat-docker/blob/master/Dockerfile-dev - GitHub仓库的https://github.com/vergoh/vnstat/commits/master%E7%89%88%E6%9C%AC

从2.7版本开始提供特定版本标签，最新发布版与latest标签一致。latest和dev标签每月至少自动构建一次，以包含可能的构建时依赖更新。

构建容器

sh
docker build -t vergoh/vnstat .

运行容器

sh
docker run -d \
    --restart=unless-stopped \
    --network=host \
    -e HTTP_PORT=8685 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /etc/timezone:/etc/timezone:ro \
    --name vnstat \
    vergoh/vnstat

• --network=host是必需的，用于访问Docker主机的网络接口，而非容器特定接口
• 卷/etc/localtime和/etc/timezone用于配置容器与主机使用相同的时区
  • 也可使用TZ环境变量（-e TZ=）指定支持的时区值，若同时使用，TZ会覆盖时区卷配置
• 如果容器内日期从1970年开始，可能需要使用--privileged
  • 更优解决方案是将libseccomp2更新到新版本
• HTTP服务器默认绑定所有接口，端口由HTTP_PORT指定。由于需要--network=host，无法使用Docker的-p或--publish端口映射。可通过防火墙规则限制HTTP服务器可见性，或使用HTTP_BIND变量绑定特定IP。设置HTTP_BIND=127.0.0.1可仅允许本地访问
  • 完整环境变量列表见下文
  • 也可使用下文所述的docker compose双容器方案，实现非特权HTTP服务器
• 图像输出默认可通过http://localhost:8685/访问
• JSON输出默认可通过http://localhost:8685/json.cgi访问
• Prometheus兼容指标端点默认可通过http://localhost:8685/metrics访问
• 添加-v some_local_directory:/var/lib/vnstat可将数据库目录映射到本地文件系统，便于访问和备份

可通过以下命令访问命令行界面：

sh
docker exec vnstat vnstat --help

docker-compose.yml

提供两个示例docker compose文件：

https://github.com/vergoh/vnstat-docker/blob/master/docker-compose.yml%EF%BC%9A%E7%AE%80%E5%8D%95%E7%A4%BA%E4%BE%8B%EF%BC%8CvnStat%E5%AE%88%E6%8A%A4%E8%BF%9B%E7%A8%8B%E5%92%8CHTTP%E6%9C%8D%E5%8A%A1%E5%99%A8%E5%9C%A8%E5%90%8C%E4%B8%80%E5%AE%B9%E5%99%A8%E4%B8%AD%E8%BF%90%E8%A1%8C%E3%80%82%E5%A4%A7%E5%A4%9A%E6%95%B0%E7%94%A8%E6%88%B7%E6%97%A0%E9%9C%80%E4%BF%AE%E6%94%B9%E5%8D%B3%E5%8F%AF%E4%BD%BF%E7%94%A8%EF%BC%8C%E4%BD%86HTTP%E6%9C%8D%E5%8A%A1%E5%99%A8%E4%B9%9F%E4%BC%9A%E4%BD%BF%E7%94%A8%E4%B8%BB%E6%9C%BA%E7%BD%91%E7%BB%9C%EF%BC%8C%E5%8F%AF%E8%83%BD%E4%B8%8D%E7%AC%A6%E5%90%88%E9%83%A8%E5%88%86%E7%94%A8%E6%88%B7%E9%9C%80%E6%B1%82%E3%80%82

https://github.com/vergoh/vnstat-docker/blob/master/docker-compose_isolated_httpd.yml%EF%BC%9A%E5%8F%8C%E5%AE%B9%E5%99%A8%E6%96%B9%E6%A1%88%EF%BC%8C%E4%BD%BF%E7%94%A8%E5%90%8C%E4%B8%80%E9%95%9C%E5%83%8F%E8%BF%90%E8%A1%8C%E4%B8%A4%E4%B8%AA%E5%AE%B9%E5%99%A8%E3%80%82%E7%AC%AC%E4%B8%80%E4%B8%AA%E5%AE%B9%E5%99%A8%EF%BC%88%60vnstat%60%EF%BC%89%E8%BF%90%E8%A1%8CvnStat%E5%AE%88%E6%8A%A4%E8%BF%9B%E7%A8%8B%EF%BC%8C%E4%BD%BF%E7%94%A8%E4%B8%BB%E6%9C%BA%E7%BD%91%E7%BB%9C%E4%BB%A5%E8%AE%BF%E9%97%AE%E6%89%80%E6%9C%89%E7%BD%91%E7%BB%9C%E6%8E%A5%E5%8F%A3%EF%BC%8C%E4%BD%86%E4%B8%8D%E6%8F%90%E4%BE%9B%E6%9C%8D%E5%8A%A1%E6%88%96%E7%BB%91%E5%AE%9A%E7%AB%AF%E5%8F%A3%EF%BC%9B%E7%AC%AC%E4%BA%8C%E4%B8%AA%E5%AE%B9%E5%99%A8%EF%BC%88%60vnstati%60%EF%BC%89%E4%B8%8D%E4%BD%BF%E7%94%A8%E4%B8%BB%E6%9C%BA%E7%BD%91%E7%BB%9C%EF%BC%8C%E6%8F%90%E4%BE%9BHTTP%E6%9C%8D%E5%8A%A1%E5%99%A8%EF%BC%8C%E9%80%9A%E8%BF%87%E5%8F%AA%E8%AF%BB%E5%85%B1%E4%BA%AB%E5%8D%B7%E8%AE%BF%E9%97%AE%E7%BB%9F%E8%AE%A1%E6%95%B0%E6%8D%AE%E3%80%82

环境变量

已弃用环境变量

使用技巧

添加接口描述名称

sh
docker exec vnstat vnstat -i eno3 --setalias " Basement switch"

停止监控不必要的接口

sh
docker exec vnstat vnstat -i br-20f8582bfc70 --remove --force

添加接口监控

1. 检查接口是否在可用接口列表中：

   sh
   docker exec vnstat vnstat --iflist
   

2. 添加接口

   sh
   docker exec vnstat vnstat -i br-20f8582bfc70 --add
   

3. 守护进程会在5分钟内检测到变更并开始监控该接口

故障排除

• 容器启动后所有图像显示“no data available”

  • 数据库更新间隔为5分钟，初始数据需等待最多5分钟才会显示

• 容器是否运行？

  sh
  docker ps
  

• 容器日志内容？

  sh
  docker logs vnstat
  

• 使用Synology NAS时时区不正确？

  • 使用/etc/TZ:/etc/localtime:ro代替/etc/localtime:/etc/localtime:ro，或使用TZ环境变量

• 容器日志显示Latest database update is in the future (db: 2037-04-03 18:16:49 > now: 1970-01-01 02:00:00)或类似时间异常

  • 使用--privileged或升级libseccomp2到新版本