⚡

Loki配置生成器 loki-config-generator

这是一个全面的工具包，用于生成遵循当前标准和约定的最佳实践Grafana Loki服务器配置。适用于创建新的Loki部署、配置Loki服务器、实施日志聚合系统或构建生产就绪的Loki配置。

Docker/K8s 0 次安装 0 次浏览 更新于 3/4/2026

Loki配置生成器 概述 生成遵循最佳实践的Grafana Loki服务器配置，适用于生产环境。支持单体、简单可扩展和微服务部署模式，支持S3、GCS、Azure或文件系统存储。

当前稳定版： Loki 3.6.2（2025年11月） 重要： Promtail在3.4版本中已被弃用 - 改用Grafana Alloy。查看examples/grafana-alloy.yaml以获取日志收集配置。

何时使用

在部署Loki、从头开始创建配置、迁移到Loki、实现多租户日志记录、配置存储后端或优化现有部署时调用。

生成方法

方法1：脚本生成（推荐）

使用scripts/generate_config.py生成一致且经过验证的配置：

# 简单可扩展与S3（生产）
python scripts/generate_config.py \
  --mode simple-scalable \
  --storage s3 \
  --bucket my-loki-bucket \
  --region us-east-1 \
  --retention-days 30 \
  --otlp-enabled \
  --output loki-config.yaml

# 单体与文件系统（开发）
python scripts/generate_config.py \
  --mode monolithic \
  --storage filesystem \
  --auth-enabled=false \
  --output loki-dev.yaml

# 生产与Thanos存储（Loki 3.4+）
python scripts/generate_config.py \
  --mode simple-scalable \
  --storage s3 \
  --thanos-storage \
  --otlp-enabled \
  --time-sharding \
  --output loki-thanos.yaml

脚本选项：

选项 描述
--mode 单体、简单可扩展、微服务
--storage 文件系统、s3、gcs、azure
--otlp-enabled 启用OTLP摄取配置
--thanos-storage 使用Thanos对象存储客户端（3.4+）
--time-sharding 启用无序摄取（3.4+）
--ruler 启用告警/记录规则
--horizontal-compactor 主/工作模式（3.6+）

方法2：手动配置

当脚本生成不满足特定要求或学习配置结构时，按照下面的分阶段工作流程进行。

输出格式

对于Kubernetes部署，生成两种格式：

  1. 原生Loki配置（loki-config.yaml）- 用于ConfigMap或直接使用
  2. Helm值（values.yaml）- 用于Helm图表部署

查看examples/kubernetes-helm-values.yaml以获取Helm格式。

文档查找

何时使用Context7/Web搜索

必需 - 使用Context7 MCP：

  • 配置Loki 3.4+的功能（Thanos存储、时间分片）
  • 配置Loki 3.6+的功能（水平压缩器、强制标签）
  • Bloom过滤器配置（复杂、实验性）
  • 定制OTLP属性映射超出标准模式
  • 故障排除配置错误

可选 - 跳过文档查找：

  • 标准部署模式（单体、简单可扩展）
  • 基本存储配置（S3、GCS、Azure、文件系统）
  • 默认限制和组件设置
  • references/目录中涵盖的配置

Context7 MCP（首选）

resolve-library-id: "grafana loki"
get-library-docs: /websites/grafana_loki, topic: [component]

示例主题： storage_config, limits_config, otlp, compactor, ruler, bloom

Web搜索备用

当Context7不可用时使用：“Grafana Loki 3.6 [component] configuration documentation site:grafana.com”

配置工作流程

第1阶段：收集需求

部署模式：

模式 规模 用例
单体 <100GB/天 测试，开发
简单可扩展 100GB-1TB/天 生产
微服务 >1TB/天 大规模，多租户

存储后端： S3、GCS、Azure Blob、文件系统、MinIO

关键问题： 预期日志量？保留期？需要多租户？高可用性要求？Kubernetes部署？

如果缺少信息，使用AskUserQuestion。

第2阶段：模式配置（关键）

对于所有新部署（Loki 2.9+），请使用v13模式的TSDB：

schema_config:
  configs:
    - from: "2025-01-01"  # 使用部署日期
      store: tsdb
      object_store: s3     # s3, gcs, azure, 文件系统
      schema: v13
      index:
        prefix: loki_index_
        period: 24h

关键： 部署后模式不能更改，除非迁移。

第3阶段：存储配置

S3：

common:
  storage:
    s3:
      s3: s3://us-east-1/loki-bucket
      s3forcepathstyle: false

GCS： gcs: { bucket_name: loki-bucket } Azure： azure: { container_name: loki-container, account_name: ${AZURE_ACCOUNT_NAME} } 文件系统： filesystem: { chunks_directory: /loki/chunks, rules_directory: /loki/rules }

第4阶段：组件配置

Ingester：

ingester:
  chunk_encoding: snappy
  chunk_idle_period: 30m
  max_chunk_age: 2h
  chunk_target_size: 1572864  # 1.5MB
  lifecycler:
    ring:
      replication_factor: 3  # 生产环境为3

Querier：

querier:
  max_concurrent: 4
  query_timeout: 1m

Compactor：

compactor:
  working_directory: /loki/compactor
  compaction_interval: 10m
  retention_enabled: true
  retention_delete_delay: 2h

第5阶段：限制配置

limits_config:
  ingestion_rate_mb: 10
  ingestion_burst_size_mb: 20
  max_streams_per_user: 10000
  max_entries_limit_per_query: 5000
  max_query_length: 721h
  retention_period: 30d
  allow_structured_metadata: true
  volume_enabled: true

第6阶段：服务器与认证

server:
  http_listen_port: 3100
  grpc_listen_port: 9096
  log_level: info

auth_enabled: true  # 单租户为false

第7阶段：OTLP摄取（Loki 3.0+）

原生OpenTelemetry摄取 - 使用otlphttp导出器（不是弃用的lokiexporter）：

limits_config:
  allow_structured_metadata: true
  otlp_config:
    resource_attributes:
      attributes_config:
        - action: index_label  # 仅限低基数！
          attributes: [service.name, service.namespace, deployment.environment]
        - action: structured_metadata  # 高基数
          attributes: [k8s.pod.name, service.instance.id]

动作： index_label（可搜索，低基数），structured_metadata（可查询），drop

⚠️ 绝不使用k8s.pod.name作为index_label - 使用structured_metadata代替。

OTel Collector：

exporters:
  otlphttp:
    endpoint: http://loki:3100/otlp

第8阶段：缓存

chunk_store_config:
  chunk_cache_config:
    memcached_client:
      host: memcached-chunks
      timeout: 500ms

query_range:
  cache_results: true
  results_cache:
    cache:
      memcached_client:
        host: memcached-results

第9阶段：高级功能

模式摄取器（3.0+）：

pattern_ingester:
  enabled: true

Bloom过滤器（实验性，3.3+）： 仅限>75TB/月部署。仅适用于结构化元数据。查看examples/以获取配置。

时间分片（3.4+）： 用于无序摄取：

limits_config:
  shard_streams:
    time_sharding_enabled: true

Thanos存储（3.4+）： 新存储客户端，现在选择加入，以后默认：

storage_config:
  use_thanos_objstore: true
  object_store:
    s3:
      bucket_name: my-bucket
      endpoint: s3.us-west-2.amazonaws.com

第10阶段：规则器（告警）

ruler:
  storage:
    type: s3
    s3: { bucket_name: loki-ruler }
  alertmanager_url: http://alertmanager:9093
  enable_api: true
  enable_sharding: true

第11阶段：Loki 3.6功能

  • 水平可扩展压缩器： horizontal_scaling_mode: main|worker
  • 基于策略的强制标签： enforced_labels: [service.name]
  • FluentBit v4： structured_metadata参数支持

第12阶段：验证配置（必需）

部署前总是验证：

# 语法和参数验证
loki -config.file=loki-config.yaml -verify-config

# 打印解析后的配置（显示默认值）
loki -config.file=loki-config.yaml -print-config-stderr 2>&1 | head -100

# 使用Docker进行干运行（如果Loki未在本地安装）
docker run --rm -v $(pwd)/loki-config.yaml:/etc/looki/config.yaml \
  grafana/loki:3.6.2 -config.file=/etc/loki/config.yaml -verify-config

验证清单：

  • [ ] -verify-config没有语法错误
  • [ ] 模式使用tsdb和v13
  • [ ] 生产环境replication_factor: 3
  • [ ] 多租户auth_enabled: true
  • [ ] 存储凭证/IAM配置
  • [ ] 保留期符合要求

生产清单

高可用性要求

区域感知复制（多AZ部署的关键）：

使用replication_factor: 3时，始终为多AZ部署启用区域感知：

ingester:
  lifecycler:
    ring:
      replication_factor: 3
      zone_awareness_enabled: true  # 多AZ的关键

# 通过环境变量或配置设置区域
common:
  instance_availability_zone: ${AVAILABILITY_ZONE}

原因： 没有区域感知，所有3个副本可能落在同一个AZ。如果该AZ失败，您将丢失数据。

Kubernetes实现：

# 在Helm值或pod规范中
env:
  - name: AVAILABILITY_ZONE
    valueFrom:
      fieldRef:
        fieldPath: metadata.labels['topology.kubernetes.io/zone']

TLS配置（生产必需）

为所有组件间和客户端通信启用TLS：

server:
  http_tls_config:
    cert_file: /etc/loki/tls/tls.crt
    key_file: /etc/loki/tls/tls.key
    client_ca_file: /etc/loki/tls/ca.crt  # 对于mTLS
  grpc_tls_config:
    cert_file: /etc/loki/tls/tls.crt
    key_file: /etc/loki/tls/tls.key
    client_ca_file: /etc/loki/tls/ca.crt

查看examples/production-tls.yaml以获取完整的TLS配置。

生产清单摘要

要求 设置 必需
replication_factor: 3 common块 所有生产
zone_awareness_enabled: true ingester.lifecycler.ring 多AZ
auth_enabled: true 根级别 多租户
TLS启用 server块 所有生产
IAM角色（非密钥） 存储配置 云存储
缓存启用 chunk_store_config, query_range 性能
模式摄取器 pattern_ingester.enabled 可观察性
保留配置 compactor + limits_config 成本控制

监控建议

要监控的关键指标

配置Prometheus以抓取Loki指标，并在这些关键指标上发出警报：

# Prometheus抓取配置
- job_name: 'loki'
  static_configs:
    - targets: ['loki:3100']

临界警报

groups:
  - name: loki-critical
    rules:
      # 摄取失败
      - alert: LokiIngestionFailures
        expr: sum(rate(loki_distributor_ingester_append_failures_total[5m])) > 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "检测到Loki摄取失败"

      # 高流基数（性能杀手）
      - alert: LokiHighStreamCardinality
        expr: loki_ingester_memory_streams > 100000
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "流基数高 - 审查标签"

      # 压缩未运行（保留破坏）
      - alert: LokiCompactionStalled
        expr: time() - loki_compactor_last_successful_run_timestamp_seconds > 7200
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "Loki压缩停滞 - 保留未执行"

      # 查询延迟
      - alert: LokiSlowQueries
        expr: histogram_quantile(0.99, sum(rate(loki_request_duration_seconds_bucket{route=~"loki_api_v1_query.*"}[5m])) by (le)) > 30
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Loki查询P99延迟> 30s"

      # 摄取器内存压力
      - alert: LokiIngesterMemoryHigh
        expr: container_memory_usage_bytes{container="ingester"} / container_spec_memory_limit_bytes{container="ingester"} > 0.8
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "Loki摄取器内存使用率> 80%"

关键指标参考

指标 描述 行动阈值
loki_ingester_memory_streams 内存中的活动流 >100k：审查基数
loki_distributor_ingester_append_failures_total 摄取失败 >0：立即调查
loki_request_duration_seconds 查询延迟 P99 >30s：增加缓存/查询器
loki_ingester_chunks_flushed_total 块刷新率 低速率：检查摄取器健康
loki_compactor_last_successful_run_timestamp_seconds 上次压缩 >2小时前：压缩破坏

Grafana仪表板

导入官方Loki仪表板：

  • 仪表板ID：13407 - Loki日志
  • 仪表板ID：14055 - Loki操作

与Grafana Alloy一起收集日志

Promtail已弃用（支持于2026年2月结束）。新部署使用Grafana Alloy。

基本Alloy配置

查看examples/grafana-alloy.yaml以获取完整配置。

// Kubernetes日志发现
discovery.kubernetes "pods" {
  role = "pod"
}

// Kubernetes元数据重新标记
discovery.relabel "pods" {
  targets = discovery.kubernetes.pods.targets

  rule {
    source_labels = ["__meta_kubernetes_namespace"]
    target_label  = "namespace"
  }
  rule {
    source_labels = ["__meta_kubernetes_pod_name"]
    target_label  = "pod"
  }
  rule {
    source_labels = ["__meta_kubernetes_pod_container_name"]
    target_label  = "container"
  }
}

// 日志收集
loki.source.kubernetes "pods" {
  targets    = discovery.relabel.pods.output
  forward_to = [loki.write.default.receiver]
}

// 发送到Loki
loki.write "default" {
  endpoint {
    url = "http://loki-gateway.loki.svc.cluster.local/loki/api/v1/push"

    // 对于多租户
    tenant_id = "default"
  }
}

从Promtail迁移

# 将Promtail配置转换为Alloy
alloy convert --source-format=promtail --output=alloy-config.alloy promtail.yaml

完整示例

查看examples/目录以获取所有模式的完整配置：

  • monolithic-filesystem.yaml - 开发/测试
  • simple-scalable-s3.yaml - 使用S3的生产
  • microservices-s3.yaml - 大规模分布式
  • multi-tenant.yaml - 多租户，每个租户限制
  • production-tls.yaml - 启用TLS的生产配置
  • grafana-alloy.yaml - 使用Alloy收集日志
  • kubernetes-helm-values.yaml - Helm图表值

最小单体：

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: 2025-01-01
      store: tsdb
      object_store: filesystem
      schema: v13
      index:
        prefix: loki_index_
        period: 24h

limits_config:
  retention_period: 30d
  allow_structured_metadata: true

compactor:
  working_directory: /loki/compactor
  retention_enabled: true

Helm部署

helm repo add grafana https://grafana.github.io/helm-charts
helm install loki grafana/loki -f values.yaml

为Kubernetes部署生成原生配置和Helm值。

# values.yaml
deploymentMode: SimpleScalable

loki:
  schemaConfig:
    configs:
      - from: "2025-01-01"
        store: tsdb
        object_store: s3
        schema: v13
        index:
          prefix: loki_index_
          period: 24h
  limits_config:
    retention_period: 30d
    allow_structured_metadata: true
  # 多AZ的区域感知
  ingester:
    lifecycler:
      ring:
        zone_awareness_enabled: true

backend:
  replicas: 3
  # 跨区域分布
  topologySpreadConstraints:
    - maxSkew: 1
      topologyKey: topology.kubernetes.io/zone
      whenUnsatisfiable: DoNotSchedule
read:
  replicas: 3
write:
  replicas: 3

最佳实践

性能：

  • chunk_encoding: snappy, chunk_target_size: 1572864
  • 启用缓存（块，结果）
  • parallelise_shardable_queries: true

安全性：

  • auth_enabled: true与反向代理认证
  • 云存储的IAM角色（绝不硬编码密钥）
  • 所有通信的TLS（见生产清单）

可靠性：

  • 生产环境replication_factor: 3
  • 多AZzone_awareness_enabled: true（见生产清单）
  • 摄取器的持久卷
  • 监控摄取率和查询延迟（见监控部分）

限制： 设置ingestion_rate_mb, max_streams_per_user以防止过载

常见问题

问题 解决方案
高摄取器内存 减少max_streams_per_user，降低chunk_idle_period
查询缓慢 增加max_concurrent，启用并行化，添加缓存
摄取失败 检查ingestion_rate_mb，验证存储连接
存储快速增长 启用保留，检查压缩，审查基数
AZ故障中的数据丢失 启用zone_awareness_enabled: true
配置验证失败 运行loki -verify-config，检查YAML语法

弃用（迁移）

  • boltdb-shipper → tsdb
  • lokiexporter → otlphttp
  • Promtail → Grafana Alloy（支持于2026年2月结束）

资源

scripts/generate_config.py - 程序性生成配置（推荐） examples/ - 所有模式的完整配置示例 references/ - 全参数参考和最佳实践

相关技能

  • logql-generator - LogQL查询生成
  • fluentbit-generator - 收集日志到Loki