部署或迁移 Grafana Loki…

适用于为 Loki 3.x 生成/优化 monolithic、simple scalable 或 microservices 配置，并配置存储、OTLP、Ruler、缓存、HA、TLS、监控和 Grafana Alloy 日志采集。

适用场景

解决思路

1. 使用 scripts/generate_config.py 生成一致且已验证的 Loki 配置。
2. 运行 python3 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 生成 Simple Scalable + S3 生产配置。
3. 运行 python3 scripts/generate_config.py --mode monolithic --storage filesystem --no-auth-enabled --output loki-dev.yaml 生成 Monolithic + filesystem 开发配置。
4. 运行 python3 scripts/generate_config.py --mode simple-scalable --storage s3 --thanos-storage --otlp-enabled --time-sharding --output loki-thanos.yaml 生成 Loki 3.4+ 生产 Thanos 存储配置。
5. 脚本选项 --mode 选择 monolithic、simple-scalable、microservices。
6. 脚本选项 --storage 选择 filesystem、s3、gcs、azure。
7. 脚本选项 --auth-enabled / --no-auth-enabled 显式启用或禁用认证。
8. 脚本选项 --otlp-enabled 启用 OTLP ingestion 配置。
9. 脚本选项 --thanos-storage 使用 Thanos object storage client（3.4+，云后端）。
10. 脚本选项 --time-sharding 启用 out-of-order ingestion（simple-scalable）。
11. 脚本选项 --ruler 启用告警/记录规则（非 monolithic）。
12. 脚本选项 --horizontal-compactor 使用 main/worker 模式（simple-scalable，3.6+）。
13. 脚本选项 --zone-awareness 启用多 AZ placement safeguards。
14. 脚本选项 --limits-dry-run 记录限制拒绝但不强制。
15. 当脚本无法满足特定需求或需学习配置结构时，按分阶段工作流手工配置。
16. Kubernetes 部署同时生成 native Loki config loki-config.yaml 和 Helm values values.yaml；参考 examples/kubernetes-helm-values.yaml。
17. 对 Loki 3.4+ Thanos storage、time sharding，3.6+ horizontal compactor、enforced labels，Bloom filter 配置，自定义 OTLP attribute mappings，配置错误排障，必须使用 Context7 MCP 查文档。
18. 对标准部署模式、基本存储配置、默认 limits 和组件设置、references/ 已覆盖配置，可跳过文档查找。
19. 使用 Context7 MCP：resolve-library-id: grafana loki；get-library-docs: /websites/grafana_loki, topic: [component]。
20. Context7 主题示例：storage_config、limits_config、otlp、compactor、ruler、bloom。
21. Context7 不可用时回退搜索 Grafana Loki 3.6 [component] configuration documentation site:grafana.com。
22. Stage 1：按规模确定部署模式：Monolithic <100GB/day 测试/开发；Simple Scalable 100GB-1TB/day 生产；Microservices >1TB/day 大规模多租户。
23. Stage 1：确定存储后端：S3、GCS、Azure Blob、Filesystem、MinIO。
24. Stage 1：询问关键问题：预期日志量？保留期？是否需要多租户？HA 要求？是否 Kubernetes 部署？缺失信息直接问用户。
25. Stage 2：所有新部署（Loki 2.9+）使用 TSDB 与 v13 schema。
26. Stage 2：配置 schema_config.configs：from 用部署日期，store: tsdb，object_store 为 s3/gcs/azure/filesystem，schema: v13，index.prefix: loki_index_，index.period: 24h。
27. Stage 2：注意 schema 部署后不能更改，除非迁移。
28. Stage 3 S3：配置 common.storage.s3.s3: s3://us-east-1/loki-bucket，s3forcepathstyle: false。
29. Stage 3 GCS：配置 gcs: { bucket_name: loki-bucket }。
30. Stage 3 Azure：配置 azure: { container_name: loki-container, account_name: ${AZURE_ACCOUNT_NAME} }。
31. Stage 3 Filesystem：配置 filesystem: { chunks_directory: /loki/chunks, rules_directory: /loki/rules }。
32. Stage 4 Ingester：配置 chunk_encoding: snappy、chunk_idle_period: 30m、max_chunk_age: 2h、chunk_target_size: 1572864、lifecycler.ring.replication_factor: 3（生产）。
33. Stage 4 Querier：配置 max_concurrent: 4、query_timeout: 1m。
34. Stage 4 Compactor：配置 working_directory: /loki/compactor、compaction_interval: 10m、retention_enabled: true、retention_delete_delay: 2h。
35. Stage 5 Limits：配置 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。
36. Stage 6 Server：配置 http_listen_port: 3100、grpc_listen_port: 9096、log_level: info。
37. Stage 6 Auth：多租户设 auth_enabled: true，单租户设 false。
38. Stage 7：使用原生 OpenTelemetry ingestion，OTel Collector 使用 otlphttp exporter，而非已弃用 lokiexporter。
39. Stage 7：配置 limits_config.allow_structured_metadata: true 和 otlp_config.resource_attributes.attributes_config。
40. Stage 7：低基数可检索标签用 action: index_label，属性如 service.name、service.namespace、deployment.environment。
41. Stage 7：高基数属性用 action: structured_metadata，如 k8s.pod.name、service.instance.id。
42. Stage 7：可用 action：index_label（可搜索、低基数）、structured_metadata（可查询）、drop。
43. Stage 7：绝不要用 k8s.pod.name 作为 index_label，应放入 structured_metadata。
44. Stage 7：配置 OTel Collector exporter otlphttp endpoint http://loki:3100/otlp。
45. Stage 8：配置 chunk_store_config.chunk_cache_config.memcached_client.host: memcached-chunks、timeout: 500ms。
46. Stage 8：配置 query_range.cache_results: true 和 query_range.results_cache.cache.memcached_client.host: memcached-results。
47. Stage 9：启用 Pattern Ingester（3.0+）：pattern_ingester.enabled: true。
48. Stage 9：Bloom Filters（实验，3.3+）仅用于 >75TB/month，仅作用于 structured metadata；参考 examples/。
49. Stage 9：Time Sharding（3.4+）用于 out-of-order ingestion：limits_config.shard_streams.time_sharding_enabled: true。
50. Stage 9：Thanos Storage（3.4+）：storage_config.use_thanos_objstore: true，object_store.s3.bucket_name: my-bucket，object_store.s3.endpoint: s3.us-west-2.amazonaws.com。
51. Stage 10：配置 Ruler：ruler.storage.type: s3、ruler.storage.s3.bucket_name: loki-ruler、alertmanager_url: http://alertmanager:9093、enable_api: true、enable_sharding: true。
52. Stage 11：Loki 3.6 水平可扩展 Compactor 配置 horizontal_scaling_mode: main|worker。
53. Stage 11：Loki 3.6 基于策略强制标签配置 enforced_labels: [service.name]。
54. Stage 11：FluentBit v4 支持 structured_metadata 参数。
55. Stage 12：部署前必须验证：运行 loki -config.file=loki-config.yaml -verify-config。
56. Stage 12：打印解析后配置：loki -config.file=loki-config.yaml -print-config-stderr 2>&1 | head -100。
57. Stage 12：本地未安装 Loki 时用 Docker dry-run：docker run --rm -v $(pwd)/loki-config.yaml:/etc/loki/config.yaml grafana/loki:3.6.2 -config.file=/etc/loki/config.yaml -verify-config。
58. Stage 12 校验清单：-verify-config 无语法错误。
59. Stage 12 校验清单：schema 使用 tsdb 和 v13。
60. Stage 12 校验清单：生产环境 replication_factor: 3。
61. Stage 12 校验清单：多租户时 auth_enabled: true。
62. Stage 12 校验清单：存储凭据/IAM 已配置。
63. Stage 12 校验清单：保留期符合需求。
64. 生产 HA：使用 replication_factor: 3 时，多 AZ 部署始终启用 zone_awareness_enabled: true。
65. 生产 HA：设置 common.instance_availability_zone: ${AVAILABILITY_ZONE}。
66. Kubernetes 中通过 env 从 fieldRef.fieldPath: metadata.labels['topology.kubernetes.io/zone'] 注入 AVAILABILITY_ZONE。
67. 生产 TLS：为所有组件间和客户端通信启用 TLS。
68. 生产 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）。
69. 生产 TLS：配置 server.grpc_tls_config 相同 cert/key/client_ca。
70. 参考 examples/production-tls.yaml 获取完整 TLS 配置。
71. 生产检查表：所有生产设 replication_factor: 3（common block）。
72. 生产检查表：多 AZ 设 zone_awareness_enabled: true（ingester.lifecycler.ring）。
73. 生产检查表：多租户设 auth_enabled: true（root level）。
74. 生产检查表：所有生产启用 TLS（server block）。
75. 生产检查表：云存储使用 IAM roles，不要用 keys。
76. 生产检查表：启用 caching（chunk_store_config、query_range）提升性能。
77. 生产检查表：启用 pattern ingester（pattern_ingester.enabled）做可观测性。
78. 生产检查表：配置 retention（compactor + limits_config）控制成本。
79. 监控：配置 Prometheus 抓取 Loki metrics：job_name: loki，targets: ['loki:3100']。
80. 告警：LokiIngestionFailures 用 sum(rate(loki_distributor_ingester_append_failures_total[5m])) > 0，for 5m，severity critical。
81. 告警：LokiHighStreamCardinality 用 loki_ingester_memory_streams > 100000，for 10m，severity warning。
82. 告警：LokiCompactionStalled 用 time() - loki_compactor_last_successful_run_timestamp_seconds > 7200，for 5m，severity critical。
83. 告警：LokiSlowQueries 用 histogram_quantile(0.99, sum(rate(loki_request_duration_seconds_bucket{route=~`loki_api_v1_query.*`}[5m])) by (le)) > 30，for 10m，severity warning。
84. 告警：LokiIngesterMemoryHigh 用 container_memory_usage_bytes{container=`ingester`} / container_spec_memory_limit_bytes{container=`ingester`} > 0.8，for 10m，severity warning。
85. 指标阈值：loki_ingester_memory_streams >100k 检查基数。
86. 指标阈值：loki_distributor_ingester_append_failures_total >0 立即调查。
87. 指标阈值：loki_request_duration_seconds P99 >30s 增加缓存/queriers。
88. 指标阈值：loki_ingester_chunks_flushed_total 低则检查 ingester 健康。
89. 指标阈值：loki_compactor_last_successful_run_timestamp_seconds >2h 前则压缩故障。
90. Grafana 导入官方 dashboard：ID 13407 Loki Logs，ID 14055 Loki Operational。
91. 日志采集：Promtail 已弃用（支持到 2026 年 2 月），新部署用 Grafana Alloy。
92. Alloy：配置 discovery.kubernetes `pods` { role = `pod` }。
93. Alloy：配置 discovery.relabel `pods`，targets 来自 discovery.kubernetes.pods.targets，rule 将 __meta_kubernetes_namespace -> namespace、__meta_kubernetes_pod_name -> pod、__meta_kubernetes_pod_container_name -> container。
94. Alloy：配置 loki.source.kubernetes `pods` targets 为 discovery.relabel.pods.output，forward_to 为 loki.write.default.receiver。
95. Alloy：配置 loki.write `default` endpoint url http://loki-gateway.loki.svc.cluster.local/loki/api/v1/push，多租户设置 tenant_id: default。
96. Promtail 迁移：运行 alloy convert --source-format=promtail --output=alloy-config.alloy promtail.yaml。
97. 完整示例：参考 examples/monolithic-filesystem.yaml、simple-scalable-s3.yaml、microservices-s3.yaml、multi-tenant.yaml、production-tls.yaml、grafana-alloy.alloy、grafana-alloy-daemonset.yaml、kubernetes-helm-values.yaml。
98. 最小 Monolithic 配置：auth_enabled: false，server.http_listen_port: 3100，common.path_prefix: /loki，filesystem chunks/rules，replication_factor: 1，ring kvstore inmemory。
99. 最小 Monolithic 配置：schema_config.configs 用 from: 2025-01-01、store: tsdb、object_store: filesystem、schema: v13、index.prefix: loki_index_、index.period: 24h。
100. 最小 Monolithic 配置：limits_config.retention_period: 30d、allow_structured_metadata: true。
101. 最小 Monolithic 配置：compactor.working_directory: /loki/compactor、retention_enabled: true。
102. Helm：运行 helm repo add grafana https://grafana.github.io/helm-charts。
103. Helm：运行 helm install loki grafana/loki -f values.yaml。
104. Helm：Kubernetes 部署同时生成 native config 和 Helm values。
105. Helm values：deploymentMode: SimpleScalable。
106. Helm values：loki.schemaConfig.configs 用 from: 2025-01-01、store: tsdb、object_store: s3、schema: v13、index.prefix: loki_index_、index.period: 24h。
107. Helm values：loki.limits_config.retention_period: 30d、allow_structured_metadata: true。
108. Helm values：HA 设置 loki.ingester.lifecycler.ring.zone_awareness_enabled: true。
109. Helm values：backend.replicas: 3，read.replicas: 3，write.replicas: 3。
110. Helm values：topologySpreadConstraints 设置 maxSkew: 1、topologyKey: topology.kubernetes.io/zone、whenUnsatisfiable: DoNotSchedule。
111. 最佳实践性能：chunk_encoding: snappy、chunk_target_size: 1572864。
112. 最佳实践性能：启用 chunks/results caching。
113. 最佳实践性能：parallelise_shardable_queries: true。
114. 最佳实践安全：auth_enabled: true 配合反向代理认证。
115. 最佳实践安全：云存储使用 IAM roles，绝不要硬编码 keys。
116. 最佳实践安全：所有通信使用 TLS。
117. 最佳实践可靠性：生产 replication_factor: 3。
118. 最佳实践可靠性：多 AZ zone_awareness_enabled: true。
119. 最佳实践可靠性：ingesters 使用 persistent volumes。
120. 最佳实践可靠性：监控 ingestion rate 和 query latency。
121. 最佳实践限制：设置 ingestion_rate_mb、max_streams_per_user 防止过载。
122. 常见问题：ingester 内存高 -> 降低 max_streams_per_user，降低 chunk_idle_period。
123. 常见问题：查询慢 -> 增加 max_concurrent，启用并行化，增加缓存。
124. 常见问题：ingestion 失败 -> 检查 ingestion_rate_mb，验证存储连通性。
125. 常见问题：存储增长快 -> 启用 retention，检查压缩，审查基数。
126. 常见问题：AZ 故障数据丢失 -> 启用 zone_awareness_enabled: true。
127. 常见问题：配置校验失败 -> 运行 loki -verify-config，检查 YAML 语法。
128. 迁移：boltdb-shipper -> tsdb。
129. 迁移：lokiexporter -> otlphttp。
130. 迁移：Promtail -> Grafana Alloy（支持到 2026 年 2 月）。
131. 资源：使用 scripts/generate_config.py 程序化生成配置（推荐）。
132. 资源：使用 examples/ 完整配置示例。
133. 资源：使用 references/ 完整参数参考和最佳实践。
134. 相关技能：logql-generator 生成 LogQL 查询。
135. 相关技能：fluentbit-generator 将日志采集到 Loki。

适用边界 · 注意事项

• 若只是编写或优化 LogQL 查询而非部署/配置 Loki，应使用 logql-generator 相关技能。
• 若不使用 Grafana Loki（例如仅使用 Elasticsearch/OpenSearch 等日志系统），不适用。
• 若无法运行 Python 脚本，也无法用本地 Loki 二进制或 Docker 做 -verify-config 校验，应先准备环境或改用官方 Helm chart 默认值。