3. Loki 快速部署：使用 Docker Compose 搭建单机 Loki、配置 Promtail 采集日志、验证日志写入

在搭建变更窗口服务目录之前，我们需要先部署一套可用的日志基础设施。本章将使用 Docker Compose 在单机环境快速搭建 Loki + Promtail 组合，完成日志采集与写入验证。这是后续所有告警降噪与变更窗口分析的基础。

3.1 整体架构

单机 Loki 部署包含三个核心组件：Loki（日志存储与查询引擎）、Promtail（日志采集与推送 Agent）、Grafana（可视化与告警面板）。下图展示了它们之间的数据流关系。

Loki 单机部署架构图 应用服务器 Nginx / Java / Python 日志文件 *.log Promtail 日志采集 Agent tail / 文件发现 Loki 日志存储 + 查询 HTTP API :3100 Grafana 可视化面板 Web UI :3000 读取日志 推送日志流 数据源查询 说明：Promtail 部署在应用服务器上，Loki 与 Grafana 可部署在同一台机器

3.2 环境准备

部署前请确保主机满足以下条件：

项目 要求 说明
操作系统 Linux (CentOS 7+ / Ubuntu 20.04+) 推荐使用 Linux 环境
Docker v20.10+ 安装 Docker Engine
Docker Compose v2.x+ 支持 docker compose 命令
内存 ≥ 2GB Loki + Grafana 内存占用
磁盘 ≥ 10GB 日志存储空间
提示：如果使用 macOS 或 Windows，请确保 Docker Desktop 已安装并分配足够内存（建议 4GB+）。

3.3 编写 docker-compose.yml

在目标主机上创建部署目录，并编写 docker-compose.yml 文件：

mkdir -p /opt/loki-stack && cd /opt/loki-stack

创建 docker-compose.yml，内容如下：

version: "3.9"

services:
  loki:
    image: grafana/loki:2.9.2
    container_name: loki
    ports:
      - "3100:3100"
    volumes:
      - ./loki-config.yaml:/etc/loki/loki-config.yaml
      - ./data/loki:/loki
    command: -config.file=/etc/loki/loki-config.yaml
    restart: unless-stopped
    networks:
      - loki-net

  promtail:
    image: grafana/promtail:2.9.2
    container_name: promtail
    volumes:
      - ./promtail-config.yaml:/etc/promtail/promtail-config.yaml
      - /var/log:/var/log:ro
      - ./data/promtail:/tmp/promtail
    command: -config.file=/etc/promtail/promtail-config.yaml
    restart: unless-stopped
    depends_on:
      - loki
    networks:
      - loki-net

  grafana:
    image: grafana/grafana:10.2.3
    container_name: grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - ./data/grafana:/var/lib/grafana
    restart: unless-stopped
    depends_on:
      - loki
    networks:
      - loki-net

networks:
  loki-net:
    driver: bridge

3.4 编写配置文件

3.4.1 Loki 配置文件

创建 loki-config.yaml，这是 Loki 的核心配置：

auth_enabled: false

server:
  http_listen_port: 3100

ingester:
  lifecycler:
    address: 127.0.0.1
    ring:
      kvstore:
        store: inmemory
      replication_factor: 1
  chunk_idle_period: 5m
  chunk_retain_period: 30s

schema_config:
  configs:
    - from: 2020-10-24
      store: boltdb-shipper
      object_store: filesystem
      schema: v11
      index:
        prefix: index_
        period: 24h

storage_config:
  boltdb_shipper:
    active_index_directory: /loki/index
    cache_location: /loki/cache
    shared_store: filesystem
  filesystem:
    directory: /loki/chunks

compactor:
  working_directory: /loki/compactor
  shared_store: filesystem

limits_config:
  reject_old_samples: true
  reject_old_samples_max_age: 168h

3.4.2 Promtail 配置文件

创建 promtail-config.yaml，配置日志采集目标：

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/promtail/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
  - job_name: system
    static_configs:
      - targets:
          - localhost
        labels:
          job: varlogs
          __path__: /var/log/*.log

  - job_name: nginx
    static_configs:
      - targets:
          - localhost
        labels:
          job: nginx
          __path__: /var/log/nginx/*.log
关键配置说明：
  • clients.url：指向 Loki 服务的推送地址，容器内使用服务名 loki:3100
  • scrape_configs：定义日志采集任务，支持 glob 路径匹配
  • positions.filename：记录日志文件读取偏移量，防止重复推送

3.5 启动服务

执行以下命令启动所有服务：

docker compose up -d

启动后检查容器状态：

docker compose ps

NAME                IMAGE                         STATUS          PORTS
loki                grafana/loki:2.9.2            Up              0.0.0.0:3100->3100/tcp
promtail            grafana/promtail:2.9.2        Up              9080/tcp
grafana             grafana/grafana:10.2.3        Up              0.0.0.0:3000->3000/tcp

三个容器均处于 Up 状态，说明部署成功。

3.6 验证日志写入

验证分为三个步骤：检查 Loki 健康状态、通过 API 查询日志、在 Grafana 中查看。

3.6.1 检查 Loki 健康状态

curl http://localhost:3100/ready

# 返回 Ready 表示服务正常

3.6.2 通过 API 查询日志

使用 Loki 的 LogQL 查询接口验证日志是否成功写入：

curl -G "http://localhost:3100/loki/api/v1/query_range" \
  --data-urlencode 'query={job="varlogs"}' \
  --data-urlencode 'limit=5' \
  | jq .

返回结果示例：

{
  "status": "success",
  "data": {
    "resultType": "streams",
    "result": [
      {
        "stream": {
          "job": "varlogs",
          "filename": "/var/log/syslog"
        },
        "values": [
          ["1700000000000000000", "2024-11-15T10:00:00+00:00 localhost systemd[1]: Started Session 1 of user root"]
        ]
      }
    ]
  }
}

3.6.3 在 Grafana 中配置数据源并查看

打开浏览器访问 http://<主机IP>:3000，使用默认账号 admin / admin 登录。按以下步骤配置 Loki 数据源：

  1. 进入 Configuration → Data Sources → Add data source
  2. 选择 Loki
  3. 在 URL 字段填写 http://loki:3100（容器内通信）或 http://主机IP:3100（宿主机通信）
  4. 点击 Save & Test，看到绿色提示表示连接成功
验证技巧：在 Grafana 的 Explore 页面中，输入 LogQL 查询 {job="varlogs"}，如果能看到日志行数据，说明 Promtail → Loki → Grafana 整条链路已打通。

3.7 常见问题排查

问题现象 可能原因 解决方法
Promtail 容器不断重启 配置文件格式错误 检查 YAML 缩进，使用 docker compose logs promtail 查看错误
Loki 返回 404 API 路径错误 确认使用 /loki/api/v1/push 推送路径
Grafana 无法连接 Loki 网络不通或 URL 错误 检查容器网络，使用 loki:3100 而非 localhost:3100
日志查询无数据 Promtail 未读取到日志文件 确认 __path__ 路径存在且 Promtail 有读取权限

3.8 本章小结

通过 Docker Compose 我们成功搭建了 Loki + Promtail + Grafana 的日志采集与存储链路。关键要点回顾：

  • Loki 作为日志存储引擎，提供 HTTP API 接收和查询日志
  • Promtail 负责从宿主机采集日志文件并推送至 Loki
  • Grafana 作为可视化层，通过 Loki 数据源展示日志
  • 验证链路是否通畅的核心命令：curl /ready 和 curl /loki/api/v1/query_range
← 上一章 📖 返回目录 下一章 →