Loki + Grafana + Promtail 容器化一键部署教程

使用 Docker Compose 快速部署完整的日志监控系统（Loki + Grafana + Promtail），用于采集、存储和展示你的应用程序日志（支持物理机、虚拟机、Docker 环境，尤其适合 Java 等传统应用）。

1. 组件简介

组件 功能
Loki 日志存储引擎，类似 Prometheus 但面向日志，只索引标签，存储成本低
Grafana 统一可视化平台，从 Loki 查询日志并展示，可与 Metrics、Traces 联动
Promtail 日志采集代理，读取本地日志文件，添加标签后推送到 Loki

2. 前提条件

  • 一台 Linux 服务器（或 WSL2、Docker Desktop）
  • 已安装 Docker 和 Docker Compose（Compose V2 或 V3）
  • 一个需要采集日志的 Java 应用（或其他程序），确认其日志文件路径（例如 /var/log/myapp/app.log）
  • 开放端口：3000（Grafana）、3100（Loki API）、9080（Promtail 指标，可选）

3. 一键部署步骤

3.1 创建项目目录

1
mkdir loki-stack && cd loki-stack

3.2 准备配置文件

共需三个文件：docker-compose.yml、loki-config.yaml、promtail-config.yaml。

3.2.1 docker-compose.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
version: '3.8'

networks:
  loki-net:
    driver: bridge

volumes:
  loki-data:
  grafana-data:

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

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    environment:
      - GF_INSTALL_PLUGINS=grafana-lokidata-source
      - GF_AUTH_ANONYMOUS_ENABLED=false
    volumes:
      - grafana-data:/var/lib/grafana
    networks:
      - loki-net
    restart: unless-stopped

  promtail:
    image: grafana/promtail:latest
    container_name: promtail
    volumes:
      - ./promtail-config.yaml:/etc/promtail/config.yaml:ro
      - /var/log:/var/log:ro
      - /Users/kewen/Projects/kw-idp-simple/logs:/app/logs:ro
    command: -config.file=/etc/promtail/config.yaml
    networks:
      - loki-net
    restart: unless-stopped

注意：请将 /path/to/your/app/logs 替换为宿主机上存放 Java 应用日志的真实路径。

3.2.2 loki-config.yaml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
auth_enabled: false

server:
  http_listen_port: 3100

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: 2020-10-24
      store: tsdb
      object_store: filesystem
      schema: v13
      index:
        prefix: index_
        period: 24h

limits_config:
  retention_period: 720h
  ingestion_rate_mb: 10
  ingestion_burst_size_mb: 20

querier:
  query_timeout: 30s

3.2.3 promtail-config.yaml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
server:
  http_listen_port: 9080

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

scrape_configs:
  - job_name: java-app-logs
    static_configs:
      - targets: [localhost]
        labels:
          job: java-app
          env: production
          __path__: /app/logs/*.log
    pipeline_stages:
      - multiline:
          firstline: '^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}'
          max_wait_time: 3s
      - regex:
          expression: '^(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3}) (?P<level>\S+) (?P<message>.*)$'
      - labels:
          level: null

如果你的日志不是这种格式，请调整 regex 表达式或改用 json 解析器（参见 5.3 节）。

3.3 启动服务

1
docker-compose up -d

查看所有容器状态：

1
docker-compose ps

预期输出三个容器状态均为 Up。

3.4 配置 Grafana 数据源

  1. 浏览器访问 http://<你的服务器IP>:3000，默认用户名/密码：admin/admin（首次登录会强制修改密码）。
  2. 点击左侧菜单 Configuration → Data Sources → Add data source。
  3. 选择 Loki。
  4. 在 HTTP URL 处填写 http://loki:3100（因为 Grafana 与 Loki 在同一 Docker 网络）。
  5. 点击 Save & Test，应提示成功。

3.5 探索日志

  • 进入 Explore 页面（左侧菜单指南针图标）。
  • 在 Label filters 中选择 job = java-app，点击 Show logs。
  • 你将看到你的 Java 应用日志实时滚动显示。

4. 常用操作与验证

4.1 向测试日志文件写入数据

如果还没有真实日志，可以手动写入一条测试：

1
echo "2025-01-27 14:30:00,123 INFO This is a test log" >> /path/to/your/app/logs/app.log

在 Grafana Explore 中执行 LogQL 查询 {job="java-app"} 即可看到该日志。

4.2 查看 Promtail 采集状态

1
docker logs promtail -f

4.3 重启或停止服务

1
2
3
docker-compose restart
docker-compose stop
docker-compose down -v   # 彻底删除并清空数据卷（慎用）

4.4 升级组件版本

修改 docker-compose.yml 中的镜像标签（例如 grafana/loki:2.9.2），然后：

1
2
docker-compose pull
docker-compose up -d

5. 进阶配置建议

5.1 采集多个应用的日志

在 promtail-config.yaml 的 scrape_configs 中添加多个 job_name：

1
2
3
4
5
6
7
8
9
10
11
12
13
scrape_configs:
  - job_name: app1
    static_configs:
      - targets: [localhost]
        labels:
          app: order-service
          __path__: /var/log/order/*.log
  - job_name: app2
    static_configs:
      - targets: [localhost]
        labels:
          app: payment-service
          __path__: /var/log/payment/*.log

5.2 日志保留策略调整

修改 loki-config.yaml 中的 retention_period 值（单位小时），例如 168h 表示 7 天。修改后需重启 Loki：

1
docker-compose restart loki

5.3 解析 JSON 格式日志

如果你的 Java 应用通过 Logback 输出了 JSON 格式，可将 pipeline_stages 替换为：

1
2
3
4
5
6
7
8
pipeline_stages:
  - json:
      expressions:
        level: level
        msg: message
        thread: thread
  - labels:
      level: null

5.4 使用环境变量注入标签

在 docker-compose.yml 的 promtail 服务中增加环境变量，并在配置文件中引用（需使用 -config.expand-env=true 参数）。示例略，可参考官方文档。

5.5 配置 Grafana 仪表盘

  • 官方提供了一些 Loki 日志仪表盘，可在 Grafana 中导入（ID：15141、13639）。
  • 也可以自己创建面板，使用 LogQL 查询生成柱状图（日志速率）、饼图（日志级别分布）等。

6. 故障排查

问题 可能原因 解决办法
Grafana 无法连接 Loki URL 填写错误或网络不通 确认 Grafana 中数据源 URL 为 http://loki:3100；检查 docker network inspect loki-stack_loki-net 是否包含两个容器
Promtail 无法读取日志文件 挂载路径错误或权限不足 检查 docker-compose.yml 中 volumes 路径是否正确；尝试添加 user: "0:0" 以 root 运行 Promtail（仅测试）
Explore 中无日志 未产生新日志 / label 过滤错误 手动写一条日志到源文件；检查 __path__ 是否匹配文件；查看 Promtail 日志 docker logs promtail
查询超时 日志量大或查询跨度长 在 Loki 配置中调高 query_timeout；在 Grafana 查询时增加更精细的标签过滤
磁盘占满 未配置保留策略 检查 loki-config.yaml 中 retention_period 是否设置；或手动删除 /loki 卷中的旧数据

7. 总结

你已经成功部署了一套轻量级的日志监控系统。相比 ELK，Loki + Grafana + Promtail 资源消耗低，特别适合传统物理机、虚拟机或 Docker 环境下的 Java 应用。你可以结合 Prometheus 指标监控，在同一个 Grafana 中实现“指标 → 日志 → 追踪”的全链路可观测性。

需要快速搭建日志系统时，只需复制 docker-compose.yml 和两个配置文件，修改日志路径后 up -d 即可。