VictoriaLogs

pg addon install victorialogs 以受管容器方式运行 VictoriaLogs——VictoriaMetrics 家族的高性能、低成本日志数据库——直接跑官方 docker.io/victoriametrics/victoria-logs 镜像。与 VictoriaMetrics 和 Prometheus 一样，它是顶层插件：不前置某个具体实例（它从多个来源摄入日志），也不依附于任何一个。VictoriaMetrics 存指标、VictoriaLogs 存日志、Grafana 同时可视化两者——三者生命周期形状完全一致（单容器、Linux 上宿主网络、各自端口池里的一个 web 端口、持久数据目录、重启策略）。

VictoriaLogs 在配置方式上是 VictoriaMetrics 插件的精确镜像：完全不需要配置文件——一切都作为镜像名之后的 CLI flag 传入（-storageDataPath / -httpListenAddr / -retentionPeriod / 自定义 flags 经 --extra-arg）。所以 pgcli 在创建容器时直接传这些 flags；无需渲染配置、无需 SIGHUP reload、无需 chown（镜像以 root 运行）。单容器在单个 HTTP 端口上提供一切：摄入（JSON Lines、Elasticsearch 兼容 bulk、syslog、OTLP）、LogsQL 查询与内置 UI。

没有 Web 登录/密码。 VictoriaLogs 完全不带鉴权。它的 HTTP API 可摄入 并查询任意日志，昂贵查询也能把自身打满，所以远程暴露的实例只靠网络边界保护 ——防火墙，或 --listen 127.0.0.1 收紧为仅回环。请把它当作一个无鉴权的读/写 控制台来对待，而非一个有密码保护的面板。

平台：Linux 是已实测的平台。设计上也支持 macOS（镜像多架构；容器在 pgcli-net bridge 上以发布端口的方式跑在 podman machine 里），但尚未在 Mac 上验证过。

参数

数据目录是 VictoriaLogs 的日志存储。它跨 pg addon remove 存活（用 --clean-data 才删除），重装同名实例即复活已存储的日志。镜像以 root 运行（与 Prometheus 的 uid 65534 不同），故无需预先 chown 数据目录。

安装

pg addon install victorialogs

命令会按需拉取镜像、创建容器，并打印 URL 与保留期：

✓ VictoriaLogs installed: "vl"
  Container:  pgcli-victorialogs-default-vl
  Image:      docker.io/victoriametrics/victoria-logs:v1.53.0
  Data:       /home/you/.pgcli/addon/victorialogs/vl/data
  Retention:  binary default (--retention to change)
  URL:        http://0.0.0.0:9428/

VictoriaLogs 立即可摄入和查询。打开 http://<host>:9428/select/vmui/ 进入内置 Web UI（根路径 / 只是可用端点索引页），或用 HTTP API 查询：

# 摄入一条 JSON Lines 日志（Content-Type 必须为 application/json——
# 缺失时 VictoriaLogs 返回 200 但会静默丢弃数据）
echo '{"_msg":"hello from pgcli","app":"demo"}' | \
  curl -s -X POST -H 'Content-Type: application/json' \
    http://127.0.0.1:9428/insert/jsonline --data-binary @-

# 用 LogsQL 查询
curl -s http://127.0.0.1:9428/select/logsql/query \
  --data-urlencode 'query=app:demo' --data-urlencode 'limit=10'

对运行中的实例重复 install：当配置确实变了（端口、监听、保留期、额外参数）时重建，没变则原样不动；--force 即使配置未变也重建容器。

VictoriaLogs 不支持热配置重载，所以所有变更都需要重建容器——与 VictoriaMetrics 一致。这比 Prometheus 简单（无配置文件要渲染、无 reload 信号），但意味着改配置时会有短暂中断。

Web UI

每个 VictoriaLogs 实例都自带 Web UI（VMUI），无需额外安装任何组件。打开：

http://<host>:<port>/select/vmui/

根路径（/）只是可用 HTTP 端点的索引页；UI 位于 /select/vmui/。

UI 是一个面向日志的 LogsQL 控制台：

• 查询 —— 输入 LogsQL 查询（如 app:demo、level:error、error app:demo-api）并选择时间范围，执行后即时返回结果。
• 视图 —— 可在 Group（按 stream 字段分组）、Table（点击行展开全部字段）、JSON（/select/logsql/query 原始响应）与 Live（实时 tail 新到日志）之间切换。
• 探索 —— 字段与 stream 选择器会列出已存储的字段名/值（底层调用 /select/logsql/field_names、field_values、facets 等），无需预先了解 schema 即可构造查询。

例如，摄入一条日志后在 UI 里搜索它（查询 app:demo）：

curl -s -X POST -H 'Content-Type: application/json' \
  -d '{"_msg":"hello from pgcli","app":"demo"}' \
  http://127.0.0.1:9428/insert/jsonline

UI 与 HTTP API 共享同一端口，也共享同样的无鉴权态势：任何能连到端口的人都能查询、也能写入日志。按上文所述用 --listen 127.0.0.1 或防火墙限制访问。

常用查询

查询使用 LogsQL。下面的示例走 HTTP 查询 API；同样的查询串可直接用在 /select/vmui/ 的 VMUI 里。

curl -s http://127.0.0.1:9428/select/logsql/query \
  --data-urlencode 'query=_time:15m level:error' \
  --data-urlencode 'limit=20'

响应是逐行 JSON，每条日志一个对象。

查生产数据时务必带 _time: 过滤条件。不带时 VictoriaLogs 会扫描保留期内的全部日志。

说明：

• field:word 匹配字段中的词；field:=value 是精确匹配，field:~"regex" 是正则匹配。取反形式为 -filter、!=、!~。
• 时间过滤支持相对时长（5m、1h、30d）、绝对时间（2026-10-23Z、2026-10-23T10:00:00Z）和区间（_time:[2026-10-01Z, 2026-10-23Z]）。
• 管道从左到右执行，过滤条件必须写在 sort、limit、stats、top 等处理阶段之前。

日志写入：vlagent、HTTP API、采集器

pgcli 只负责运行 VictoriaLogs 后端——日志怎么进来由你决定。共有三种方式。

vlagent（官方 agent）

vlagent 是 VictoriaLogs 的官方日志 agent——vmagent 的日志对应物（vmagent 只负责指标，不要用它写日志）。它在自己的端口（默认 9429）上接受与 VictoriaLogs 相同的 HTTP 摄入协议，可以从磁盘跟踪日志文件，并通过 -remoteWrite.url 转发到 VictoriaLogs，该 URL 必须以 /insert/native 结尾。pgcli 会替你运行并管理它——完整参数见 vlagent 插件页面：

# 仅转发：在 :9429 接受 HTTP 推送并转发给 VictoriaLogs
pg addon install vlagent \
  --remote-write-url http://127.0.0.1:9428/insert/native

# 跟踪宿主日志文件：/var/log/nginx 以只读方式挂载到容器内相同路径；
# --include/--exclude 使用 vlagent 原生 glob 语法（不是正则）
pg addon install vlagent \
  --log-path /var/log/nginx \
  --include '/var/log/nginx/**/*.log' \
  --exclude '/var/log/nginx/*.gz' \
  --remote-write-url http://127.0.0.1:9428/insert/native

第一种形式不跟踪任何日志文件：没有 --log-path/--include（也没有经 --extra-arg 传入的 -kubernetesCollector）时，vlagent 只接收推到端口 9429 的 HTTP 日志并转发。--log-path 接受任意宿主文件或目录；不给 --include 时，目录默认展开为 <dir>/**/*.log，单个文件默认就是它自身。glob 是在容器内匹配的，所以 pgcli 把每个宿主路径挂载到完全相同的绝对路径。

适合使用 vlagent 的场景：

• 复制 / 高可用 —— 为每个 VictoriaLogs 实例重复传 --remote-write-url。vlagent 会把每条日志复制到所有目标，并为每个 URL 维护独立磁盘缓冲（-remoteWrite.tmpDataPath，可用 -remoteWrite.maxDiskUsagePerURL 限制大小）；后端宕机期间采集的日志会在其恢复后重放。
• Kubernetes Pod 日志 —— 用 --extra-arg -kubernetesCollector，并通过 --log-path 把宿主 /var/log（使用 Docker runtime 时再加 /var/lib 以解析 runtime 符号链接）挂入。它跟踪 /var/log/pods 与 /var/log/containers，自动附加容器元数据，并把读取位点持久化在数据目录（-tmpDataPath）下。
• 磁盘文件 —— --log-path /var/log/nginx --include '/var/log/nginx/*.log'（glob 必须指向文件而非目录）。默认 hostname 与 file 成为 stream 字段，读取位点与缓冲位于插件的数据目录。

如果只有单个、网络稳定的 VictoriaLogs 实例，直接发送（见下）更简单——这是推荐的默认方式。

HTTP API

VictoriaLogs 在 UI/查询 API 的同一端口上提供多个摄入端点：

所有 HTTP 摄入端点都接受同一组调优参数（query string 或 VL-* 请求头）：_msg_field（日志消息所在字段，如 message）、_time_field（如 @timestamp）、_stream_fields（用逗号分隔的 stream 字段）、extra_fields（env=prod）、ignore_fields、decolorize_fields，以及 debug=1（只记录 payload 而不入库）。当采集器输出的 schema 无法被自动识别时用它们做映射。

# JSON Lines，显式字段映射
curl -s -X POST -H 'Content-Type: application/json' \
  --data-binary @app.jsonl \
  'http://127.0.0.1:9428/insert/jsonline?_stream_fields=host,app&_time_field=@timestamp&_msg_field=message'

日志采集器

任何能使用上述格式之一的采集器都可以；pgcli 不安装也不配置它们。常用采集器及官方配置指南：

采集器也可以不直接连 VictoriaLogs，而是指向 vlagent（端口 9429）——需要缓冲、复制或统一出口时更合适。

自定义参数（--extra-arg）

VictoriaLogs 接受许多 CLI flags 来调优缓存大小、查询限制、摄入速率等。经 --extra-arg 传入（可重复）：

pg addon install victorialogs --name vl1 \
  --extra-arg -search.maxQueryDuration=60s \
  --extra-arg -memory.allowedPercent=80

额外参数最后追加到容器的命令行，故它们经 last-wins 语义覆盖早期 flags。这让你在 pgcli 的一等旋钮之外调优 VictoriaLogs，无需编辑任何配置文件。验证 flags 已生效（二进制不会把 flags 打进日志）：

podman inspect pgcli-victorialogs-default-vl1 --format '{{json .Config.Cmd}}'

监听与暴露

VictoriaLogs 的 Listen 默认 0.0.0.0：容器共享宿主网络命名空间，所以 UI 与 API 在宿主每个网卡的分配端口上可达。这与 VictoriaMetrics 的默认一致（别的机器上的日志采集器和 Grafana 要能连它）——但背后没有密码。任何能连到端口的人都能执行任意 LogsQL、读你存储的日志。想要仅回环的部署，传 --listen 127.0.0.1（用 --force 重建）；pg addon list 会显示 http://127.0.0.1:<port>/。否则请在防火墙层面限制访问。

端口

每个 VictoriaLogs 实例占有一个端口：Web UI/API。它取自以 victorialogs_start_port（默认 9428——VictoriaLogs 惯例 HTTP 端口）为基址的端口池，每多一个实例递增，并跳过任何已被受管容器或 used_ports 列表占用的端口。分配结果写入 pg.yaml，所以重装绝不会把别的插件在用的端口再发一遍。9428 与 VictoriaMetrics（8428）、vmcluster（8480-8484）、Prometheus（9090）、Grafana（3000）、pgAdmin（5050）、nginx（8080）都不重号；显式 --port 仍优先。

pg addon install victorialogs --name vl2          # 第二个实例：下一个空闲端口（9428 被占则 9429）
pg addon install victorialogs --name vl3 --port 9500  # 显式端口仍优先

配置

addons:
  victorialogs:
    vl1:
      name: vl1
      image_tag: docker.io/victoriametrics/victoria-logs:v1.53.0
      host_port: 9428
      listen: 0.0.0.0
      retention: "30d"
      extra_args:
        - -search.maxQueryDuration=60s
        - -memory.allowedPercent=80
      # data_dir: /srv/victorialogs-data      # 可选，覆盖默认位置

没有配置文件——一切都作为 CLI flags 传给 victoria-logs 二进制（-storageDataPath、-httpListenAddr、-retentionPeriod，加上任何 extra_args）。retention 存为时长字符串（省略 = 二进制默认），extra_args 是最后追加的 CLI flags 列表。

列出

pg addon list

Web add-ons (victorialogs):
  victorialogs (name: vl1)
    Status:      running
    URL:         http://0.0.0.0:9428/
    Retention:   30d
    Extra args:  -search.maxQueryDuration=60s -memory.allowedPercent=80
    Data:        /home/you/.pgcli/addon/victorialogs/vl1/data
    Image:       docker.io/victoriametrics/victoria-logs:v1.53.0
    Container:   pgcli-victorialogs-default-vl1

没有凭据可揭示——VictoriaLogs 本就没有——所以 --show-password 对它不会多显示任何东西。

启停

容器以 podman 的 unless-stopped 重启策略运行，宿主重启后随 podman 服务自动回来。start/stop 显式管理它们：

pg addon stop victorialogs
pg addon start victorialogs

开机自启

pg autostart enable --victorialogs --name vl

这会在 pg.yaml 里给实例打标记，并安装/刷新一个开机服务（Linux 上是 systemd --user unit，macOS 上是 LaunchAgent）来执行 pg start --autostart。开机启动只负责把容器拉起来——日志数据目录在 install 时已创建，重启后已有日志仍在。关闭用 pg autostart disable --victorialogs --name vl；完整机制见 开机自启。

移除

pg addon remove victorialogs              # 保留日志存储——已存储日志跨重装存活
pg addon remove victorialogs --clean-data # 连日志存储一起删

rootless podman 下，--clean-data 经 podman unshare rm 删除数据目录——VictoriaLogs 以 root（容器内 uid 0）写文件，它映射到宿主的 subordinate uid，宿主用户无法直接 rm。

排障

• 摄入返回 200 但查询为空 —— JSON Lines 端点要求 Content-Type: application/json；缺失时 VictoriaLogs 接受请求但会静默丢弃数据（/metrics 上的 vl_rows_ingested_total{type="jsonline"} 保持 0）。加上该 header，或改用会自动设置的采集客户端。
• 查询返回空数据 —— 确认 VictoriaLogs 在运行（pg addon list 显示 running）、健康端点有响应（curl -s http://<host>:<port>/-/healthy）、且你查的是正确的时间范围与 stream 过滤（_stream: 前缀、_time: 边界）。查 podman logs <container> 看摄入错误。
• Install 失败于 “container already exists” —— 容器名由 --name 和命名空间派生；用 --force 重建，或先 pg addon remove 清理一次不完整的 install。
• 额外参数没生效 —— --extra-arg 在容器创建时应用，而非运行时。用 --force reinstall 以新 flags 重建容器。查 podman inspect <container> --format '{{json .Config.Cmd}}' 确认 flags 在命令行上（二进制不会打印它们）。
• 端口已被分配 —— 已分配的端口记在 pg.yaml 里并为后续实例跳过；先 pg addon remove 释放，或用 --port N 另选一个。
• 远程 API 打不开 / 意外可访问 —— 默认 0.0.0.0 下打不开是宿主防火墙问题，不是绑定地址；反之若你不想被访问，用 --listen 127.0.0.1 --force。

已知限制

• VictoriaLogs 本身是裸日志后端：pgcli 另外提供专门的 vlagent 插件做文件/HTTP 采集（也可以用上文直连 HTTP API 或第三方采集器），但不安装任何第三方采集器，也不做告警（自行跑 vlalert）。它是你让 Grafana（VictoriaLogs 数据源）和采集器连的长期日志存储。
• 无鉴权。 VictoriaLogs 的 API 摄入并查询任意日志；0.0.0.0 绑定的唯一保护是网络边界。这与 VictoriaMetrics 同一态势——不要把它暴露到不可信网络。
• pgcli 不校验 --extra-arg 值（install 阶段没有 pre-flight 检查）。有错的 flag 只会在启动时从容器日志里暴露。
• macOS 上容器跑在 podman machine 里；目前只在 Linux 上验证过。