Daily-It

개발, AI, 인프라, 자동화와 일상 IT 제품 후기를 직접 써보며 정리하는 기술 블로그입니다.

Grafana Loki 最新指南：使用 Docker Compose 构建日志收集系统

摘要

Grafana Loki 是一个日志收集系统，可以根据标签查找日志流，而无需对所有日志进行大量索引。截至 2026 年 6 月，最新版本是 Loki 3.7.x 系列，如果您遵循旧的 Loki 3.0 标准文章，则 Promtail、标签设计和存储配置中可能会混合旧信息。在本文中，我们将总结如何使用 Docker Compose 配置测试环境以及实际操作中常见的失败案例。

目录

背景

当你第一次接触 Loki 时，很容易将其视为像 Elasticsearch 一样对整个日志体进行索引的系统。但洛基的核心却不同。不是对整个日志体建立索引， job, service_name, namespace, container 查找具有相同标签的日志流，并在其中按 LogQL 进行过滤。

这种结构在成本和存储效率方面具有优势，但如果标签设计不当，性能就会下降。尤其是 request_id, user_id, trace_id如果将像这样值不断变化的数据作为标签，基数就会爆炸。

另一个重要的变化是Promtail。根据Grafana官方文档，Promtail已于2026年3月2日EOL，未来的功能开发将在Grafana Alloy上进行。现有的 Promtail 示例仍在广泛搜索，但如果您正在构建一个新示例，将 Alloy 作为标准会更安全。

了解洛基结构

基于Loki的日志收集通常分为三个部分：

成分 角色
Loki 存储日志和处理 LogQL 查询的服务器。
合金或原木收集剂 读取文件、容器和 Kubernetes 日志并将其发送给 Loki
Grafana 连接 Loki 数据源以搜索日志并配置仪表板/警报

对于小型测试环境，将 Loki 作为单个二进制文件运行就足够了。然而，在生产环境中，您需要考虑存储、复制、保留期、查询性能、多租户，甚至通知。

Docker Compose 测试配置

官方文档指出，Docker 或 Docker Compose 可用于评估、测试和开发目的。对于生产环境，我们推荐Helm或Tanka等部署方法。

出于测试目的，您可以从如下所示的简单配置开始。

services:
  loki:
    image: grafana/loki:3.7.0
    ports:
      - "3100:3100"
    command: -config.file=/etc/loki/local-config.yaml

  grafana:
    image: grafana/grafana:latest
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=****
    depends_on:
      - loki

跑吧。

docker compose up -d

Loki状态可以通过以下方式检查：

curl http://localhost:3100/ready

如果正常的话 ready您可以看到接近的响应。 Grafana 可通过您的浏览器访问。

http://localhost:3000

此配置仅用于学习目的。在实际操作中，应避免单独依赖文件系统存储或将日志长时间存储在单个容器中。

为什么你应该观看 Alloy 而不是 Promtail

大多数较旧的 Loki 教程都使用 Promtail。然而，截至官方文档，Promtail 处于 EOL 状态。

Promtail EOL: 2026-03-02
향후 기능 개발: Grafana Alloy

如果您已经在现有操作环境中使用 Promtail，这不会立即中断。但是，如果您正在构建新的东西或撰写新文章，那么查看基于合金的配置也是正确的。 Grafana 还提供了引导迁移工具，用于将 Promtail 设置转换为 Alloy 设置。

也就是说，当前标准的推荐方向是：

새 프로젝트: Alloy 우선 검토
기존 Promtail 운영: 마이그레이션 계획 수립
단기 테스트: 기존 예제 참고 가능하나 EOL 상태 명시

标签设计及储存注意事项

在 Loki 中，标签是搜索的起点。官方文档建议使用低基数值的标签来描述日志源。

一些好的标签示例包括：

service_name="api-server"
environment="prod"
namespace="backend"
container="nginx"

应避免使用的标签示例包括：

request_id="a1b2c3..."
user_id="123456"
ip="203.0.113.10"
trace_id="..."

对于需要频繁搜索的高基数值，您应该考虑过滤结构化元数据或日志正文而不是标签。

存储也很重要。对于本地测试，您可以使用文件系统，但出于操作目的，您应该查看对象存储和保留策略，例如 S3、GCS 和 Azure Blob。特别是，如果未设置保留，日志可能会继续堆积并导致磁盘或存储成本问题。

故障案例及解决方案

案例1.Grafana中无法连接Loki数据源

在格拉法纳 http://localhost:3100，但您可能无法连接。这是因为Grafana容器访问Docker Compose中Loki时的地址和用户浏览器访问的地址不同。

在 Compose 内部，我们使用服务名称。

http://loki:3100

直接从主机检查时，使用：

curl http://localhost:3100/ready

换句话说，Grafana容器内部的设置包括 localhost不 loki 有很多情况需要输入服务名称。

情况2.没有日志进来，但Loki正常

即使 Loki 漂浮，Grafana 也看不到任何内容，除非日志收集代理正确发送。

首先，检查Loki的状态。

curl http://localhost:3100/ready

接下来，查看收集代理日志。

docker compose logs

以下是要检查的内容：

Loki push URL이 맞는가?
컨테이너 간 네트워크 이름이 맞는가?
로그 파일 경로가 컨테이너 안에서 보이는가?
라벨 설정 때문에 다른 stream으로 들어간 것은 아닌가?

案例3. label values当数量太多时，查询就会变慢。

这是Loki中最常见的操作错误。 pod, container, namespace 这可能没问题，但如果你把一个随着每个请求而变化的值作为标签，流的数量将会急剧增加。

如果您怀疑有问题，请首先检查标签列表。

{service_name="api-server"}

在我们的经营中，我们坚持以下原则：

라벨은 낮은 카디널리티 값만 사용
사용자 ID, 요청 ID, 세션 ID는 라벨로 넣지 않기
자주 바뀌는 값은 structured metadata 또는 로그 본문으로 처리

情况4.如果您按照Promtail示例进行操作，但与最新推荐的方法不同

搜索结果中有大量 Promtail 示例。但 Promtail 已停产。因此，在创建新环境时，应该先查看Alloy文档。

如果您有现有的 Promtail 设置，请检查迁移工具和 Alloy 文档，而不是立即将其删除。

Promtail 설정 백업
Alloy 마이그레이션 문서 확인
테스트 환경에서 변환 설정 검증
운영 반영 전 로그 유실 여부 확인

情况5、由于未设置日志保留期限导致存储持续增长

这种情况在测试中不常见，但在生产中经常发生。日志堆积的速度比您想象的要快。特别是，如果您同时收集调试日志和访问日志，存储成本会迅速增加。

操作前请务必确定以下事项：

보존 기간
삭제 정책
저장소 타입
압축/청크 설정
환경별 로그 레벨

案例 6. 按原样使用 Docker Compose 测试配置进行生产

官方文档还指出，Docker Compose 适合评估、测试和开发目的。操作需要针对故障转移、存储、可扩展性、安全性、身份验证和监控进行单独设计。

如果可行，至少检查以下内容：

Helm 기반 Kubernetes 배포
object storage 연동
retention 설정
Grafana 인증과 권한
Loki 자체 모니터링
백업과 장애 복구

最佳实践

首次部署 Loki 时，最好从小处着手并提前建立操作标准。

  • 使用 Docker Compose 快速开始测试
  • 以合金为基础审查的新系列配置
  • 从较少的标签开始，然后根据需要增加
  • 不包含高基数值作为标签
  • 首先设计操作存储和保留
  • 在 Grafana 仪表板之前检查日志丢失/存储成本/查询性能

常见错误

像理解 Elasticsearch 一样理解 Loki

Loki 不会索引整个日志正文。标签设计对搜索性能和成本有重大影响。

将 Promtail 示例误认为是最新推荐的做法

有很多 Promtail 示例，但它们目前已停产。新的部署应首先考虑合金。

localhost 使用容器内的地址

Docker Compose 内部 localhost是每个容器本身。在格拉法纳寻找洛基时 http://loki:3100您可能需要使用这样的服务名称。

继续累积日志而不保留

日志继续增长。没有保留期和删除策略的操作将导致磁盘或对象存储成本问题。

结论

Grafana Loki 是创建经济高效的日志收集系统的不错选择。然而，为了正确使用它，您需要在安装说明之前了解标签设计、收集代理选择、存储、保留和查询模式。

如果您要在 2026 年构建新项目，建议您考虑 Loki 3.7.x 文档作为标准，并考虑 Promtail 示例的 EOL 状态和 Alloy 转换。测试可以从 Docker Compose 开始，但操作必须单独设计，包括 Helm、对象存储、保留和监控。

参考资料

  • Grafana Loki GitHub Release v3.7.2: https://github.com/grafana/loki/releases/tag/v3.7.2
  • Grafana Loki Docker 安装文档：https://grafana.com/docs/loki/latest/setup/install/docker/
  • Grafana Loki Promtail 文档：https://grafana.com/docs/loki/latest/send-data/promtail/
  • Grafana Loki 合金文档：https://grafana.com/docs/loki/latest/send-data/alloy/
  • Grafana Loki 标签文档：https://grafana.com/docs/loki/latest/get-started/labels/
  • Grafana Loki 存储文档：https://grafana.com/docs/loki/latest/operations/storage/
  • Grafana Loki 查询文档：https://grafana.com/docs/loki/latest/query/