vnstat.conf 配置项详解：对 vnstatd、vnstat、vnstati 的影响

上级入口：知识地图与图谱/知识地图-基础设施云原生与虚拟化 · 知识地图与图谱/知识地图-网络代理与远程接入 · 知识地图与图谱/知识地图-Linux系统与运维

1. 背景

vnstat.conf 是 vnStat 的统一配置文件。它同时影响三个命令：

本机版本：

vnstat --version

vnStat 2.13 by Teemu Toivola <tst at iki dot fi> (SQLite 3.51.2)

vnstati 在 Fedora 上是单独的子包：

sudo dnf install -y vnstat-vnstati

安装后版本：

vnstati --version

vnStat image output 2.13 by Teemu Toivola <tst at iki dot fi> (SQLite 3.51.2, LibGD 2.3.3)

包内文件：

rpm -ql vnstat-vnstati | sort

/usr/bin/vnstati
/usr/share/licenses/vnstat-vnstati/COPYING
/usr/share/man/man1/vnstati.1.gz

验证图片输出：

mkdir -p /tmp/vnstati-check
vnstati -s -i enp3s0 -o /tmp/vnstati-check/summary.png
file /tmp/vnstati-check/summary.png
ls -lh /tmp/vnstati-check/summary.png

输出：

/tmp/vnstati-check/summary.png: PNG image data, 500 x 200, 8-bit colormap, non-interlaced
-rw-r--r--. 1 dev dev 2.9K May 28 11:03 /tmp/vnstati-check/summary.png

2. 配置文件语法与加载规则

默认配置文件：

/etc/vnstat.conf

man page 说明：如果用户 HOME 下存在 $HOME/.vnstatrc，或命令行通过 --config <file> 指定了配置文件，则可以覆盖默认配置来源。

基本语法：

Keyword value
Keyword "value with spaces"

规则：

• # 或 ; 开头的行是注释。
• 每行是一个 keyword-argument pair。
• 参数可以用双引号包起来。
• 如果配置项不存在、无法解析或超出允许范围，程序会使用硬编码默认值。
• 命令行参数通常优先于配置文件。例如 vnstat -i wg0 会覆盖 Interface 默认接口，vnstat --style 0 会覆盖 OutputStyle。

配置项分三类：

3. 三个命令如何共享配置

3.1 vnstatd

vnstatd 是长期运行的采集进程。它读取接口计数器，计算增量，缓存到内存，并按周期写入 SQLite 数据库。

典型受影响配置：

• DatabaseDir
• UpdateInterval
• PollInterval
• SaveInterval
• 5MinuteHours / HourlyDays / DailyDays
• MaxBandwidth / MaxBW<iface>
• UseUTC
• DatabaseWriteAheadLogging
• UseLogging

修改 daemon 相关配置后，一般需要重启：

sudo systemctl restart vnstat
journalctl -u vnstat -n 40 --no-pager

3.2 vnstat

vnstat 是查询数据库的命令行前端。它不负责长期采集，只负责读取数据库并输出 summary、days、months、json、xml、live 等结果。

典型受影响配置：

• Interface
• UnitMode
• RateUnit
• OutputStyle
• ListDays / ListMonths / ListTop
• QueryMode
• Locale
• EstimateVisible

多数查询展示类配置无需重启 vnstatd，因为每次执行 vnstat 都会重新读取配置。

3.3 vnstati

vnstati 用同一份数据库生成 PNG 图片，适合静态网页或日报。它会读取部分 common 配置，也读取 image output 配置。

典型受影响配置：

• HeaderFormat
• TransparentBg
• ImageScale
• LargeFonts
• CBackground / CRx / CTx
• SummaryGraph
• HourlyRate

修改这类配置后，不需要重启 daemon；下一次执行 vnstati 生成图片时生效。

常用输出：

vnstati -s -i enp3s0 -o summary.png
vnstati -d -i enp3s0 -o daily.png
vnstati -m -i enp3s0 -o monthly.png
vnstati -hs -i enp3s0 -o hsummary.png
vnstati -vs -i enp3s0 -o vsummary.png

vnstati 不支持 vnstat -l 这类 live traffic 功能，它面向已经写入数据库的统计结果。

4. common keywords

common 配置主要影响查询和展示，其中 DatabaseDir 也影响 daemon 的数据库位置。

4.1 Interface

Interface ""

为空时，vnstat 会自动选择接口。数据库查询场景下，通常优先选择总流量最大的接口；非数据库查询会先从当前系统可见接口中选择。

如果服务器上有多个接口，建议显式指定查询接口，而不是依赖默认选择：

vnstat -i enp3s0
vnstat -i wg0

如果希望默认总是看某个接口：

Interface "enp3s0"

影响：

• vnstat：不带 -i 时默认查该接口。
• vnstati：不带 -i 时默认画该接口。
• vnstatd：不受这个配置控制，daemon 监控接口由数据库和 daemon 发现逻辑决定。

4.2 DatabaseDir

DatabaseDir "/var/lib/vnstat"

这是最关键的路径配置之一。

影响：

• vnstatd 在这个目录创建 / 维护 vnstat.db。
• vnstat 从这个目录读取数据库。
• vnstati 从这个目录读取数据库并生成图片。

修改时必须同时考虑权限：

ls -ld /var/lib/vnstat
ls -l /var/lib/vnstat/vnstat.db

如果改到自定义目录，vnstatd 运行用户需要有写权限，查询用户需要能读。

4.3 单位相关：UnitMode、RateUnit、RateUnitMode

UnitMode 0
RateUnit 1
RateUnitMode 1

UnitMode 控制流量总量单位：

RateUnit 控制速率显示：

RateUnitMode 只在 RateUnit 1 时影响 bit/s 前缀：

影响：

• vnstat 文本输出、-tr、-l、summary rate。
• vnstati 图片中的单位。
• 不影响 vnstatd 存储，数据库里仍保存 bytes。
• vnstat --json 的 traffic 值默认仍是 bytes，不应被显示单位误导。

4.4 输出样式：OutputStyle 与视觉字符

OutputStyle 3
RXCharacter "%"
TXCharacter ":"
RXHourCharacter "r"
TXHourCharacter "t"

OutputStyle 控制文本输出布局：

这些配置只改变展示，不改变采集或数据库。

影响：

• vnstat -d / -m / -t 等列表输出。
• vnstat -hg hourly graph。
• vnstati 会受 OutputStyle 的部分语义影响，尤其和 BarColumnShowsRate 组合时。

4.5 列表长度：List*

List5Mins      24
ListHours      24
ListDays       30
ListMonths     12
ListYears       0
ListTop        10

这些配置控制默认显示多少条，不控制数据库保留多少条。

例如：

ListDays 30
DailyDays 365

含义是：数据库最多保留 365 天日统计，但 vnstat -d 默认只显示最近 30 条。要显示更多：

vnstat -d 365
vnstat -d 0

影响：

• vnstat -5 / -h / -d / -m / -y / -t
• vnstati 对应列表图
• 不影响 vnstatd 保留策略

4.6 QueryMode

QueryMode 0

控制不带参数执行 vnstat 时默认显示什么。

常用值：

如果你常用 JSON 自动化，可以设置：

QueryMode 10

但更推荐脚本显式写：

vnstat --json

4.7 InterfaceMatchMethod

InterfaceMatchMethod 3

控制 vnstat -i <name> 如何匹配数据库接口名和 alias。

配合别名使用：

sudo vnstat -i enp3s0 --setalias wan
vnstat -i wan

影响：

• vnstat 查询接口选择。
• vnstati 图片输出接口选择。
• 不影响 vnstatd 采集哪个接口。

4.8 estimate 相关

EstimateVisible 1
EstimateText "estimated"
EstimateBarVisible 1

影响：

• vnstat summary / list 中是否显示 estimated 行。
• vnstati 图片中是否显示 estimate。
• vnstat --alert 中 rx_estimate、tx_estimate、total_estimate 条件是否可用。

如果禁用：

EstimateVisible 0

则 estimate 输出消失，基于 estimate 的告警也不可用。

5. daemon related keywords

daemon 配置影响 vnstatd 的采集、接口生命周期、数据库写入和维护。修改后通常需要：

sudo systemctl restart vnstat

5.1 daemon 配置总览

5.2 用户与权限：DaemonUser、DaemonGroup

DaemonUser ""
DaemonGroup ""

这两个配置只在进程以 root 启动时有意义，用于启动后切换到低权限用户 / 组。

发行版 systemd 包通常已经在 unit 文件或打包逻辑里处理了运行用户。本机服务状态显示 daemon 以 uid:958 gid:958 运行：

Info: vnStat daemon 2.13 (pid:306455 uid:958 gid:958 64-bit, SQLite 3.51.2)

影响：

• vnstatd 的数据库、日志、pid 文件读写权限。
• 不影响 vnstat 查询命令的执行用户。

5.3 带宽检测与异常过滤

BandwidthDetection 1
MaxBandwidth 1000
#MaxBWeth0 8
BandwidthDetectionInterval 5

vnstatd 通过读取内核接口计数器差值来计算流量。为了避免计数器回绕、接口重建、驱动异常导致的巨大假流量，它会使用最大带宽限制过滤不合理增量。

MaxBandwidth 是全局上限，单位 Mbit。MaxBW<iface> 是单接口上限，例如：

MaxBWenp3s0 1000
MaxBWwg0 1000
MaxBWtun-ext 10000

注意：

• BandwidthDetection 1 会尝试自动检测接口带宽。
• Linux 上 tun 接口带宽检测可能不可靠，man page 提到 tun 接口检测会被特殊处理，因为内核可能报告固定值。
• 设置了 MaxBW<iface> 后，该接口不再使用自动检测。

影响：

• 只影响 vnstatd 是否接受某个采样周期的增量。
• 间接影响 vnstat / vnstati 之后能看到的数据。

5.4 历史数据保留策略

5MinuteHours   2160
HourlyDays      365
DailyDays       365
MonthlyMonths  25
YearlyYears    -1
TopDayEntries  20

含义：

本机已把 5 分钟粒度扩展到 90 天，把小时和日统计扩展到 365 天：

5MinuteHours   2160
HourlyDays      365
DailyDays       365

注意：

• 这控制的是数据库保留，不是默认显示条数。
• 已被清理的历史明细无法恢复。
• --95th 要覆盖整月，5MinuteHours 至少需要 744 小时左右的数据窗口。
• 保留越久，SQLite 数据库越大，但 vnStat 的数据量通常仍然很小。

验证：

journalctl -u vnstat -n 40 --no-pager

Info: Data retention: 2160 5MinuteHours, 365 HourlyDays, 365 DailyDays, 25 MonthlyMonths, -1 YearlyYears, 20 TopDayEntries

5.5 采集、轮询与保存周期

UpdateInterval 20
PollInterval 5
SaveInterval 5
OfflineSaveInterval 30

这些是 vnstatd 运行行为的核心。

关系：

• PollInterval 越短，接口上下线发现越快。
• UpdateInterval 越短，采样越细，但不是数据库分辨率；数据库仍按 5 分钟、小时、天等聚合。
• SaveInterval 越短，异常断电时丢失的缓存越少，但磁盘写入更频繁。

一般服务器保持默认即可。低功耗设备可以适当增大保存周期，高动态接口环境可以保持较短轮询。

5.6 接口发现与数据库同步

RescanDatabaseOnSave 1
AlwaysAddNewInterfaces 0
SaveOnStatusChange 1

vnstatd 监控哪些接口，不是由 Interface 决定，而是由数据库中的 interface 表和 daemon 发现逻辑决定。

RescanDatabaseOnSave 1：

• 当你手动执行 vnstat --add -i <iface> 后，daemon 在保存周期会重新扫描数据库并开始监控新接口。
• 关闭后，可能需要重启 daemon。

AlwaysAddNewInterfaces 0：

• 关闭时，daemon 不会在已有数据库情况下自动添加每个新出现接口。
• 开启后，Docker、VPN、临时 veth 等接口可能被自动加进数据库，容易产生噪音。

SaveOnStatusChange 1：

• 接口上线 / 下线时额外保存一次，减少状态变化时数据丢失。

建议：

• 稳定服务器：AlwaysAddNewInterfaces 0。
• 经常插拔网卡或动态创建接口的测试机：可临时使用 vnstatd --alwaysadd 或配置 AlwaysAddNewInterfaces 1。

5.7 月份与账单周期

MonthRotate 1
MonthRotateAffectsYears 0

MonthRotate 控制月统计从每月几号切换。默认 1 表示自然月。

如果运营商账单每月 7 日重置：

MonthRotate 7

影响：

• vnstat -m 的月统计边界。
• vnstat --alert ... m ... 的月度告警判断。
• 不会重算已有数据，只影响之后写入的数据归属。

MonthRotateAffectsYears 1 会让这个非自然月边界也影响年统计。多数场景保持默认 0。

5.8 时间与时区

UseUTC 0
TimeSyncWait 5
BootVariation 15

UseUTC 0 表示使用本地时区写入数据库。改成 1 后，新写入数据使用 UTC。

注意：

• 修改 UseUTC 不会转换已有历史数据。
• 修改系统时区不会重算旧数据。
• 系统时间回拨时，可能把新流量累加到已经存在的时间段。

TimeSyncWait 适合没有 RTC 的设备，启动时如果数据库最新时间看起来在未来，daemon 会等待系统时间同步。

BootVariation 用于判断系统启动时间变化的容忍范围，辅助处理重启后的计数器同步。

5.9 日志、目录和 pid

UseLogging 2
CreateDirs 1
UpdateFileOwner 1
LogFile "/var/log/vnstat/vnstat.log"
PidFile "/var/run/vnstat/vnstat.pid"

UseLogging：

systemd 环境下通常使用 UseLogging 2，日志查看：

journalctl -u vnstat -n 80 --no-pager

注意：当 vnstatd -n / --nodaemon 前台运行时，日志会输出到终端，UseLogging 可能被忽略。

CreateDirs 1 会在目录不存在时尝试创建 DatabaseDir、LogFile、PidFile 所需目录。

UpdateFileOwner 1 会在 daemon 以 root 启动且启用了用户 / 组切换时修正数据库、日志、pid 文件属主。

5.10 SQLite 行为

DatabaseWriteAheadLogging 0
DatabaseSynchronous -1
VacuumOnStartup 1
VacuumOnHUPSignal 1

DatabaseWriteAheadLogging 控制 SQLite WAL 模式：

• 0：默认 rollback journal 模式。
• 1：启用 WAL，可能改善读写并发，但老 SQLite 只读访问兼容性可能有问题。

DatabaseSynchronous 控制 SQLite 写入同步级别：

建议：

• 普通服务器保持默认。
• 不要为了微小性能收益随意关闭同步，vnStat 写入频率本来就低。

VacuumOnStartup / VacuumOnHUPSignal 控制是否执行 SQLite VACUUM，用于删除接口或缩短保留策略后压缩数据库文件。

5.11 计数器位宽与无流量记录

64bitInterfaceCounters -2
TrafficlessEntries 1
CheckDiskSpace 1

64bitInterfaceCounters：

高速接口建议保持 -2 自动检测。错误设置可能导致计数器回绕判断不准。

TrafficlessEntries 1 表示即使某个时间段没有流量，也创建记录。这样图表和列表时间轴更连续。

CheckDiskSpace 1 在写数据库前检查磁盘空间，建议保持开启。

6. image output related keywords

这些配置只影响 vnstati 图片输出。本机已安装 vnstat-vnstati，可使用 vnstati 从同一份 /var/lib/vnstat/vnstat.db 生成 PNG 图片。

vnstati --help 的核心输出模式：

输出文件：

vnstati -s -i enp3s0 -o /tmp/vnstat-summary.png

-o 根据文件扩展名选择图片格式；输出到标准输出时使用 -o -，此时格式限制为 PNG：

vnstati -d -ne -nh -o - > daily.png

缓存输出：

vnstati -h -c 15 -o /tmp/vnstat_h.png

-c 15 表示只有当输出文件超过 15 分钟未更新时才重新生成，适合 cron 或 Web 页面按固定 URL 读取图片的场景。

6.1 图片输出配置总览

命令行参数通常可临时覆盖配置文件。例如：

vnstati -s --scale 150 --transparent 1 -i enp3s0 -o summary.png
vnstati -d -L -i enp3s0 -o daily-large.png
vnstati -hg 1 -i enp3s0 -o hourly-from-midnight.png

含义：

• --scale 150 覆盖 ImageScale。
• --transparent 1 覆盖 TransparentBg。
• -L 覆盖 LargeFonts。
• -hg 1 覆盖 HourlyGraphMode，让小时图从当天 00:00 开始。

6.2 图片尺寸与字体

LargeFonts 0
LineSpacingAdjustment 0
ImageScale 100

影响：

• LargeFonts 1 提高字体尺寸，适合高 DPI 或大屏展示。
• LineSpacingAdjustment 正数增大行距，负数压缩行距。
• ImageScale 按百分比缩放输出，范围 50..500。

如果网页中展示太小：

ImageScale 150

6.3 5 分钟图与小时图

5MinuteGraphResultCount 576
5MinuteGraphHeight 300
HourlyGraphMode 0
SummaryGraph 0

5MinuteGraphResultCount 576 表示图中包含 576 个 5 分钟周期，也就是 48 小时。这个值影响图宽。

也可以用命令行临时覆盖：

vnstati -5g 288 300 -i enp3s0 -o five-minute-24h.png

其中 288 表示 24 小时，因为每小时有 12 个 5 分钟周期；300 表示图高 300 像素。

HourlyGraphMode：

SummaryGraph：

6.4 rate 与 estimate 显示

HourlyRate 1
SummaryRate 1
EstimateStyle 1
BarColumnShowsRate 0

HourlyRate 1 表示小时图使用速率视角，而不是只看传输总量。

SummaryRate 1 会在 summary 图片中显示速率信息。

EstimateStyle：

BarColumnShowsRate 1 需要配合 OutputStyle 3。启用后，list 输出中的 bar column 表示 rate；同时会让 EstimateStyle 自动变为 0。

6.5 透明背景与颜色

TransparentBg 0
CBackground     "FFFFFF"
CEdge           "AEAEAE"
CHeader         "606060"
CHeaderTitle    "FFFFFF"
CHeaderDate     "FFFFFF"
CText           "000000"
CLine           "B0B0B0"
CLineL          "-"
CPercentileLine "CF0045"
CRx             "92CF00"
CTx             "606060"
CRxD            "-"
CTxD            "-"
CTotal          "0098CF"

颜色使用十六进制 RGB，不带 #。

常用含义：

透明背景：

TransparentBg 1

适合把 PNG 嵌入深色或自定义背景网页。注意透明背景可能让浅色文字在某些网页背景上不可读，需要同时调整颜色。

6.6 vnstati 的限制

vnstati(1) 有几个使用限制：

• 可输出的图片格式取决于构建时链接的 GD library。本机版本显示 LibGD 2.3.3。
• 输出到 stdout 时只支持 PNG。
• GD 内建字体对 UTF-8 字符支持有限，中文标题或长文本可能显示不完整。
• 日期格式太长可能导致列对齐问题。
• 启用透明背景后再缩放图片，透明效果可能无法保留。

因此，把 vnstati 用在自动化页面时，建议先固定英文或短中文标题、固定输出尺寸，并用浏览器实际检查图片。

7. 配置变更是否需要重启

重启与验证：

sudo systemctl restart vnstat
systemctl status vnstat --no-pager
journalctl -u vnstat -n 40 --no-pager

查看当前配置：

vnstat --showconfig

8. 常见配置组合

8.1 长期保留细粒度历史

适合做长期流量图、分析每日峰谷：

5MinuteHours   2160
HourlyDays      365
DailyDays       365
MonthlyMonths   36
YearlyYears     -1

影响：

• vnstat -5 能查最近 90 天 5 分钟数据。
• vnstat -h 能查最近 365 天小时数据。
• SQLite 文件会增大。

8.2 VPS 按账单周期统计

如果 VPS 每月 7 日重置流量：

MonthRotate 7

影响：

• vnstat -m 的月份不再是自然月。
• 月度 --alert 会按新周期判断。
• 已有历史不重算。

8.3 多动态接口环境避免噪音

Docker、VPN、临时 TUN/TAP 较多时：

AlwaysAddNewInterfaces 0
RescanDatabaseOnSave 1

手动添加需要的接口：

sudo vnstat --add -i wg0
sudo vnstat --add -i enp3s0

8.4 嵌入式或低写入设备

如果设备写入寿命敏感：

SaveInterval 10
OfflineSaveInterval 60
VacuumOnStartup 0

取舍：

• 磁盘写入减少。
• 异常断电时可能丢失更多未保存缓存。

9. 排障检查清单

9.1 修改配置后没有生效

检查是否编辑了正确文件：

vnstat --showconfig | head

检查是否存在 $HOME/.vnstatrc 覆盖：

ls -l ~/.vnstatrc

daemon 相关配置修改后重启：

sudo systemctl restart vnstat

9.2 数据库路径或权限错误

grep -n '^DatabaseDir' /etc/vnstat.conf
ls -ld /var/lib/vnstat
ls -l /var/lib/vnstat/vnstat.db
journalctl -u vnstat -n 80 --no-pager

9.3 接口没有被监控

vnstat --iflist
vnstat --dbiflist
sudo vnstat --add -i <iface>
sudo systemctl restart vnstat

注意：Interface 只是查询默认接口，不会让 daemon 自动监控该接口。

9.4 输出条数少于预期

区分两个概念：

• DailyDays：数据库最多保留多少天。
• ListDays：默认显示多少条。

如果 DailyDays 365 但 vnstat -d 只显示 30 条，这是 ListDays 30 的正常行为：

vnstat -d 365
vnstat -d 0

10. 与主笔记的关系

这篇文章专注于配置项行为。安装、常用命令、底层采集原理、SQLite schema 和 Grafana 集成可参考：

• vnstat 网络流量统计工具原理与使用指南

11. 参考

• man vnstat.conf
• man vnstat
• man vnstatd
• man vnstati
• 官方 man page：vnstat.conf(5)