搬瓦工部署 Promtail 日志代理配置教程

Promtail 是 Grafana Loki 日志系统的官方日志采集代理，专门设计用于将日志数据发送到 Loki。如果你已经在使用 Grafana 和 Prometheus 进行监控，那么 Promtail + Loki 是最自然的日志解决方案，它们共享相同的标签模型和查询理念。本文将介绍如何在搬瓦工 VPS 上部署和配置 Promtail。部署前请确保已安装 Docker 和 Docker Compose。

一、Promtail 工作原理

Promtail 的工作流程非常简洁：

发现目标：通过静态配置或服务发现找到需要收集的日志文件。
读取日志：使用类似 tail -f 的方式持续读取日志文件的新内容。
解析处理：通过 Pipeline Stages 对日志进行解析、过滤和标签提取。
发送到 Loki：将处理后的日志批量发送到 Loki 的 Push API。

二、系统要求

操作系统：Ubuntu 20.04+ 或 Debian 11+。
内存：至少 256MB（Promtail 非常轻量）。
磁盘：至少 1GB 可用空间。
前置条件：需要有一个可访问的 Loki 实例。

搬瓦工入门方案即可运行 Promtail。购买时使用优惠码 NODESEEK2026 可享 6.77% 折扣，购买入口：bwh81.net。

三、创建项目目录

mkdir -p /opt/promtail && cd /opt/promtail

四、编写 Promtail 配置文件

cat > /opt/promtail/promtail-config.yml <<'EOF'
server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push
    tenant_id: default
    batchwait: 1s
    batchsize: 1048576

scrape_configs:
  # 系统日志
  - job_name: syslog
    static_configs:
      - targets:
          - localhost
        labels:
          job: syslog
          host: my-vps
          __path__: /var/log/syslog

  # 认证日志
  - job_name: auth
    static_configs:
      - targets:
          - localhost
        labels:
          job: auth
          host: my-vps
          __path__: /var/log/auth.log

  # Nginx 访问日志
  - job_name: nginx-access
    static_configs:
      - targets:
          - localhost
        labels:
          job: nginx
          type: access
          __path__: /var/log/nginx/access.log
    pipeline_stages:
      - regex:
          expression: '^(?P[\w\.]+) - (?P[^ ]*) \[(?P[^\]]+)\] "(?P\w+) (?P[^ ]+) (?P[^"]+)" (?P\d+) (?P\d+)'
      - labels:
          method:
          status:
      - timestamp:
          source: time_local
          format: "02/Jan/2006:15:04:05 -0700"

  # Nginx 错误日志
  - job_name: nginx-error
    static_configs:
      - targets:
          - localhost
        labels:
          job: nginx
          type: error
          __path__: /var/log/nginx/error.log

  # Docker 容器日志
  - job_name: docker
    static_configs:
      - targets:
          - localhost
        labels:
          job: docker
          __path__: /var/lib/docker/containers/*/*-json.log
    pipeline_stages:
      - json:
          expressions:
            log: log
            stream: stream
            time: time
      - output:
          source: log
EOF

五、编写 Docker Compose 配置

cat > /opt/promtail/docker-compose.yml <<'EOF'
version: '3.8'

services:
  promtail:
    image: grafana/promtail:latest
    restart: always
    ports:
      - "9080:9080"
    volumes:
      - ./promtail-config.yml:/etc/promtail/config.yml:ro
      - /var/log:/var/log:ro
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
      - promtail_positions:/tmp
    command: -config.file=/etc/promtail/config.yml

volumes:
  promtail_positions:
EOF

六、启动服务

cd /opt/promtail
docker compose up -d

检查运行状态：

# 查看日志
docker compose logs -f promtail

# 查看目标状态
curl http://localhost:9080/targets

# 查看就绪状态
curl http://localhost:9080/ready

七、Pipeline Stages 详解

Pipeline Stages 是 Promtail 强大的日志处理机制，常用的 Stage 包括：

regex：使用正则表达式从日志行中提取字段。
json：解析 JSON 格式的日志。
labels：将提取的字段设置为 Loki 标签。
timestamp：从日志中提取时间戳。
output：设置最终发送到 Loki 的日志内容。
match：条件匹配，只处理符合条件的日志。
drop：丢弃不需要的日志行。

八、标签管理最佳实践

Loki 的标签设计与 Prometheus 类似，需要注意以下几点：

标签值的基数不宜过高，避免使用 IP 地址、用户 ID 等高基数值作为标签。
推荐的标签包括：job、host、service、environment、level 等。
高基数字段应该作为日志内容的一部分，在查询时使用过滤表达式。

九、与完整 Loki 栈集成

Promtail 通常与 Loki + Grafana 配合使用。在 Grafana 中添加 Loki 数据源后，可以使用 LogQL 查询语言进行日志搜索：

# 查看 Nginx 错误日志
{job="nginx", type="error"}

# 过滤包含特定关键字的日志
{job="syslog"} |= "error"

# 按 HTTP 状态码统计
sum by (status) (rate({job="nginx"} | json | status != "" [5m]))

十、常见问题

Promtail 未采集到日志

访问 http://localhost:9080/targets 查看目标状态。确认日志文件路径正确且 Promtail 有读取权限。

日志时间戳不正确

在 Pipeline Stages 中配置 timestamp stage，确保时间格式与日志中的格式匹配。

总结

Promtail 是 Grafana Loki 生态中的官方日志采集代理，如果你已经在使用 Grafana 进行监控，Promtail + Loki 是最佳的日志方案。如果需要更通用的日志处理能力，可以参考 Fluent Bit 或 Vector。选购搬瓦工 VPS 使用优惠码 NODESEEK2026 可享 6.77% 折扣。