监控 - Wizard Doc

最后修改人	孙荣利
最后修改时间	2026-10-03 15:57:12
创建人	孙荣利
创建时间	2026-10-03 15:57:12

该文档由孙荣利创建于 2026-10-03 15:57:12 ，孙荣利在 2026-10-03 15:57:12 修改了该文档。

[TOCM]

## 一、简介

```text
Promtail 是 Grafana Loki 官方推出的日志采集代理（Agent）。本文记录 Promtail 基于 docker-compose 的部署方式（区别于二进制版：无需下载解压、无需 systemd 管理，容器自动拉起/重启），采集 Nginx 访问日志、错误日志及 Java 日志并推送到 Loki。

环境说明：部署目录 /data/promtail，编排文件 docker-compose.yml，采集配置 promtail-config.yaml，镜像 repo.358369.xyz/grafana/promtail:2.9.0。
```

## 二、安装部署

#### 1. 目录准备

```shell
# 创建部署目录并进入
mkdir -p /data/promtail
cd /data/promtail

# 创建编排文件和采集配置文件
touch docker-compose.yml
touch promtail-config.yaml
```

#### 2. docker-compose.yml

```yaml
services:  # 服务定义
  promtail:  # Promtail 日志采集代理服务
    image: repo.358369.xyz/grafana/promtail:2.9.0  # 私有仓库镜像（Grafana Promtail 2.9.0）
    container_name: promtail  # 容器名称
    restart: always  # 容器异常退出/主机重启后自动拉起
    volumes:  # 数据卷挂载
      #- /var/log:/var/log:ro  # 挂载宿主机系统日志（按需启用，只读）
      #- /var/lib/docker/containers:/var/lib/docker/containers:ro  # 挂载 Docker 容器日志（按需启用，只读）
      - ./promtail-config.yaml:/etc/promtail/promtail-config.yaml:ro  # 挂载采集配置文件（只读）
      - /data/promtail:/data/promtail  # 挂载进度文件目录（positions 断点续读，防止容器重建后重复采集）
    command: -config.file=/etc/promtail/promtail-config.yaml  # 启动命令：指定配置文件路径
    network_mode: "host"  # 使用宿主机网络模式（可直接访问宿主机上的 Loki）
```

#### 3. 采集配置 promtail-config.yaml

```yaml
server:  # Promtail 自身 HTTP 服务配置
  # 云服务器需开放 9080 端口
  http_listen_port: 9080  # HTTP 服务监听端口（健康检查/指标）
  grpc_listen_port: 0  # gRPC 监听端口（0 表示禁用）
  # 设置日志级别为 info
  log_level: info  # Promtail 自身日志级别
positions:  # 读取进度记录配置
  filename: /data/promtail/positions.yaml  # 记录日志读取进度的文件（重启后断点续读，防止重复采集）
# Loki 地址
clients:  # 推送目标配置
  - url: http://loki.hivery.cn/loki/api/v1/push  # Loki 接收日志的推送地址
# 命名规范：项目名-access-nginx（/ 项目名-error-nginx）
scrape_configs:  # 日志抓取任务配置
  - job_name: zhiliangguanli-pro-access-nginx  # 任务名称（质量管理生产环境 Nginx 访问日志）
    pipeline_stages:  # 日志处理流水线
      - regex:  # 正则解析阶段：按 Nginx 默认访问日志格式拆解为命名字段
          expression: ^(?P<ip>\S+) (?P<identd>\S+) (?P<user>\S+) \[(?P<timestamp>[^\]]+)\] "(?P<action>\S+) (?P<path>[^\s\?]+)(\?\S*)? HTTP/(?P<protocol>\S+)" (?P<status_code>\d{3}) (?P<size>\d+) "(?P<referer>[^"]*)" "(?P<useragent>[^"]*)"  # 正则表达式：匹配 Nginx combined 格式访问日志，依次提取 IP/时间/方法/路径/协议/状态码/大小/来源/UA
      - labels:  # 标签提取阶段：从正则解析出的字段中挑出部分作为 Loki 标签
          status_code:  # 提取 HTTP 状态码为标签（如 200/404/500）
          action:  # 提取请求方法为标签（如 GET/POST）
          protocol:  # 提取 HTTP 协议版本为标签（如 1.1/2.0）
    static_configs:  # 静态采集配置
      - targets:  # 抓取目标
          - localhost  # 本地主机
        labels:  # 日志标签
          server: zhiliangguanli  # 服务器/项目标识标签
          service_name: nginx  # 服务名称标签
          service_env: prod  # 服务环境标签（生产环境）
          log_type: ngx_access  # 日志类型标签（Nginx 访问日志）
          __path__: /var/log/nginx/*access.log  # 采集的日志文件路径（通配符匹配）
  - job_name: zhiliangguanli-pro-error-nginx  # 任务名称（质量管理生产环境 Nginx 错误日志）
    static_configs:  # 静态采集配置
      - targets:  # 抓取目标
          - localhost  # 本地主机
        labels:  # 日志标签
          server: zhiliangguanli  # 服务器/项目标识标签
          service_name: nginx  # 服务名称标签
          service_env: prod  # 服务环境标签（生产环境）
          log_type: ngx_error  # 日志类型标签（Nginx 错误日志）
          __path__: /var/log/nginx/*error.log  # 采集的日志文件路径（通配符匹配）
  - job_name: java-demo  # 任务名称（采集 Java 应用日志）
    static_configs:  # 静态采集配置
      - targets: [localhost]  # 抓取目标（本地主机）
        labels:  # 日志标签
          server: zhiliangguanli  # 服务器/项目标识标签
          log_type: java  # 日志类型标签（Java 日志）
          log_type_detail: java-demo  # 日志类型细分标签（具体应用名）
          __path__: /var/log/nginx/error*.log  # 采集的日志文件路径（注意：此处指向了 nginx 日志目录，若是 Java 应用日志请改为实际路径）
    pipeline_stages:  # 日志处理流水线
      - multiline:  # 多行日志合并配置
          firstline: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}'  # 匹配日志行首的正则（时间戳开头视为一条新日志）
          max_wait_time: 3s  # 等待下一条日志的最长时间（超时则强制结束当前日志块）
```

#### 4. 启动与验证

```shell
# 启动 Promtail 容器（-d 后台运行）
docker compose up -d

# 查看容器运行状态
docker compose ps

# 实时查看容器日志
docker compose logs -f

# 查看 Promtail 自身日志
journalctl -u docker -f | grep promtail
```