监控 - Wizard Doc

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

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

[TOCM]

## 一、简介

```text
Promtail 是 Grafana Loki 官方推出的日志采集代理（Agent）。本文记录 Promtail 在 Linux 服务器上的二进制安装方式（非 Docker 容器），通过 systemd 管理服务，实现开机自启、异常自动重启，采集 Nginx 访问日志、错误日志及 Java 日志并推送到 Loki。

环境说明：安装目录 /data/promtail，配置文件 promtail-config.yaml，服务名 promtail。
```

## 二、安装部署

#### 1. 下载与解压

```shell
# 创建 Promtail 安装目录并进入
mkdir -p /data/promtail
cd /data/promtail

# 下载 promtail.zip（若下载失败，需修改 /etc/hosts 手动映射，添加：111.231.90.76 repo.hivery.cn）
wget https://repo.hivery.cn/promtail.zip

# 解压安装包
unzip promtail.zip

# 若提示无 unzip 命令，先安装：apt install unzip
```

#### 2. 创建采集配置 promtail-config.yaml

```shell
# 创建并编辑配置文件
sudo vim 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  # 等待下一条日志的最长时间（超时则强制结束当前日志块）
```

#### 3. 创建 systemd 服务

```shell
# 创建 Promtail 服务配置文件
sudo vim /etc/systemd/system/promtail.service
```

文件内容（逐行说明）：

```ini
[Unit]  # 单元定义段
Description=Promtail Log Collector  # 服务描述
After=network.target  # 在系统网络就绪后再启动本服务
[Service]  # 服务定义段
Type=simple  # 服务类型：主进程直接运行（非 fork 守护进程）
ExecStart=/data/promtail/promtail-linux-amd64 -config.file=/data/promtail/promtail-config.yaml  # 启动命令：二进制 + 指定配置文件
Restart=always  # 进程异常退出后自动重启
User=root  # 以 root 用户运行（保证日志目录读取权限）
WorkingDirectory=/data/promtail/  # 服务工作目录
StandardOutput=syslog  # 标准输出写入系统日志（journald）
StandardError=syslog  # 标准错误写入系统日志（journald）
LimitNOFILE=65536  # 进程文件描述符上限（高并发采集时防句柄耗尽）
[Install]  # 安装定义段
WantedBy=multi-user.target  # 多用户模式下开机自启
```

#### 4. 启动与验证

```shell
# 赋予服务文件执行权限（注：systemd 服务文件本身无需执行权限，此步可省略；
# 真正需要执行权限的是二进制 /data/promtail/promtail-linux-amd64，zip 解压后通常已具备）
sudo chmod +x /etc/systemd/system/promtail.service

# 重新加载 systemd 配置（新增/修改服务文件后必须执行）
sudo systemctl daemon-reload

# 启用服务开机自启
sudo systemctl enable promtail.service

# 启动 Promtail 服务
sudo systemctl start promtail

# 检查服务运行状态（Active: active (running) 即正常）
sudo systemctl status promtail

# 实时查看 Promtail 日志
journalctl -u promtail -f
```