3. Loki 快速部署：Docker Compose 方式搭建 Loki + Promtail + Grafana 本地环境

在 CI/CD 流水线 SLI 监控体系中，日志是还原故障现场、计算错误率与延迟分布的关键数据源。本章将使用 Docker Compose 在本地一键搭建 Loki + Promtail + Grafana 三件套，为后续的 SLI 口径采集与日志监控实战提供可复现的实验环境。

3.1 组件角色与数据流

Loki 采用 「推送-存储-查询」 的轻量架构，与 Prometheus 的指标监控体系高度互补。三个核心组件的职责如下：

下图展示了日志从产生到可视化的完整数据流：

3.2 环境准备与目录结构

在开始部署前，请确保宿主机已安装 Docker Engine 20.10+ 和 Docker Compose v2+。建议在 Linux 或 macOS 环境下操作，Windows 用户可使用 WSL2。

创建项目目录并规划文件结构：

mkdir -p ~/loki-lab/{config,data/loki,data/grafana,logs}
cd ~/loki-lab

3.3 编写配置文件

3.3.1 Loki 配置（config/loki-config.yml）

Loki 采用 boltdb-shipper 模式，将索引和数据统一存储在本地文件系统，适合单机开发与测试：

auth_enabled: false

server:
  http_listen_port: 3100
  grpc_listen_port: 9095

common:
  path_prefix: /loki
  storage:
    filesystem:
      chunks_directory: /loki/chunks
      rules_directory: /loki/rules
  replication_factor: 1
  ring:
    kvstore:
      store: inmemory

schema_config:
  configs:
    - from: 2024-01-01
      store: boltdb-shipper
      object_store: filesystem
      schema: v13
      index:
        prefix: index_
        period: 24h

limits_config:
  ingestion_rate_mb: 10
  ingestion_burst_size_mb: 20

3.3.2 Promtail 配置（config/promtail-config.yml）

Promtail 需要明确指定日志采集源、标签以及 Loki 的推送地址：

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

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

scrape_configs:
  - job_name: cicd-pipeline-logs
    static_configs:
      - targets: [localhost]
        labels:
          job: cicd-pipeline
          __path__: /var/log/cicd/*.log
    pipeline_stages:
      - regex:
          expression: '^(?P<level>\w+)\s+(?P<timestamp>\S+)\s+(?P<message>.*)$'
      - labels:
          level:
      - timestamp:
          source: timestamp
          format: RFC3339

3.3.3 Docker Compose 编排（docker-compose.yml）

将三个服务整合到同一个网络内，并挂载配置与数据目录：

version: "3.8"

networks:
  loki-net:
    driver: bridge

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

  promtail:
    image: grafana/promtail:2.9.2
    container_name: promtail
    volumes:
      - ./config/promtail-config.yml:/etc/promtail/promtail-config.yml
      - ./logs:/var/log/cicd
      - /var/log:/var/log
    command: -config.file=/etc/promtail/promtail-config.yml
    networks:
      - loki-net
    restart: unless-stopped
    depends_on:
      - loki

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

3.4 启动与验证

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

cd ~/loki-lab
docker compose up -d

等待 10~15 秒后，使用 docker compose ps 检查三个容器的状态，应全部显示 Up：

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       0.0.0.0:9080->9080/tcp
grafana    grafana/grafana:10.2.3        Up       0.0.0.0:3000->3000/tcp

生成模拟日志以验证数据流：

# 生成 CI/CD 流水线模拟日志
for i in {1..5}; do
  echo "INFO 2025-01-15T10:00:0${i}Z Build stage completed for commit a1b2c3d${i}" >> ~/loki-lab/logs/pipeline.log
  echo "WARN 2025-01-15T10:00:1${i}Z Test flaky detected in module auth" >> ~/loki-lab/logs/pipeline.log
  echo "ERROR 2025-01-15T10:00:2${i}Z Deploy failed: connection timeout" >> ~/loki-lab/logs/pipeline.log
done

3.5 配置 Grafana 数据源与快速查询

打开浏览器访问 http://localhost:3000，使用 admin / admin 登录。按以下步骤添加 Loki 数据源：

1. 进入 Configuration → Data Sources → Add data source。
2. 选择 Loki，在 URL 字段填入 http://loki:3100。
3. 点击 Save & Test，确认返回绿色提示 Data source connected and labels found.

切换到 Explore 页面，输入以下 LogQL 查询验证日志采集：

{job="cicd-pipeline"} |= `ERROR`

预期结果：返回 5 条包含 ERROR 的模拟日志，每条日志携带 job、level 等标签。

3.6 常见问题与排障