Promtail on Liangweidong's blog

Loki + Promtail 日志体系：helm 部署 + yaml 自定义 + 排错

Sat, 15 Mar 2025 00:00:00 +0800

K8s 日志采集的 3 种方式

方式	资源占用	适用
DaemonSet 采集（默认）	低	中小集群
Sidecar 采集	高	大集群、多租户隔离
应用主动推送	取决于应用	自定义需求

本文部署 Loki + Promtail——K8s 时代最主流的日志方案（比 ELK 轻量 10 倍，查询语法像 PromQL）。

适用版本：Loki 2.9.3 / Promtail / K8s 1.28.5

1. Loki 架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


 ┌──────────────────┐
 │ Grafana │ ← 查询
 └─────────┬────────┘
 │ LogQL
 ┌─────────▼────────┐
 │ Loki │ ← 存储 + 索引
 │ (write/read/ │
 │ backend/ │
 │ gateway) │
 └─────────┬────────┘
 │ push
 ┌──────────────────┴──────────────────┐
 │ │
 ┌────▼────┐ ┌────▼────┐
 │ Promtail│ ←─ 采集 /var/log/pods/ │ Promtail│
 │ (Node1)│ │ (Node2)│
 └─────────┘ └─────────┘
 ▲ ▲
 /var/log/pods/ /var/log/pods/
 /var/lib/docker/containers/ /var/lib/docker/containers/

3 大模块：

Grafana Agent / Promtail：每节点一个 DaemonSet，抓容器日志
Loki：存储 + 查询（分 write / read / backend / gateway 4 个微服务）
Grafana：可视化查询

2. helm 部署（推荐）

2.1 添加仓库

1
2
3
4
5
6
7


helm repo add grafana https://grafana.github.io/helm-charts
helm repo update

# 拉 chart
helm pull grafana/loki-stack
tar xvf loki-stack-2.10.0.tgz
cd loki-stack

2.2 备份默认 values

1

cp values.yaml values-prod.yaml

2.3 修改 values-prod.yaml

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


loki:
 enabled: true
 persistence:
 enabled: true
 storageClassName: nfs-client
 accessModes:
 - ReadWriteOnce
 size: 10Gi

promtail:
 enabled: true

grafana:
 enabled: true
 service:
 type: NodePort
 persistence:
 enabled: true
 storageClassName: nfs-client
 accessModes:
 - ReadWriteOnce
 size: 10Gi

2.4 处理冲突 RBAC

1
2
3
4
5
6


k get ClusterRole
# ClusterRole "loki-promtail" in namespace "" exists and cannot be imported into the current release

cd loki-stack
kubectl delete ClusterRole loki-promtail
kubectl delete ClusterRole loki-grafana-clusterrole

2.5 部署

1
2
3
4
5
6
7


kubectl create ns logging

helm upgrade --install loki . \
 -f values-prod.yaml \
 -n logging

kubectl logs -f -n logging loki-0

2.6 验证

1
2
3
4


kubectl get pod -n logging
# loki-0 1/1 Running
# loki-promtail-xxx 1/1 Running
# loki-grafana-xxx 1/1 Running

3. 私有 yaml 部署（更可控）

如果不想用 helm 那一堆微服务，可以直接用 statefulset + configmap。

3.1 准备镜像

1
2
3


docker pull grafana/loki:2.9.3
docker tag grafana/loki:2.9.3 <harbor>/base/grafana/loki:2.9.3
docker push <harbor>/base/grafana/loki:2.9.3

3.2 完整 yaml

/data/k8scnf/loki.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
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161


---
apiVersion: v1
kind: ServiceAccount
metadata:
 name: loki
 namespace: logging
---
apiVersion: v1
kind: ConfigMap
metadata:
 name: loki
 namespace: logging
 labels:
 app: loki
data:
 loki.yaml: |
 auth_enabled: false
 ingester:
 chunk_idle_period: 3m
 chunk_block_size: 262144
 chunk_retain_period: 1m
 max_transfer_retries: 0
 lifecycler:
 ring:
 kvstore:
 store: inmemory
 replication_factor: 1
 wal:
 enabled: true
 dir: /data/wal
 limits_config:
 enforce_metric_name: false
 reject_old_samples: true
 reject_old_samples_max_age: 8h
 schema_config:
 configs:
 - from: "2024-01-19"
 store: boltdb-shipper
 object_store: filesystem
 schema: v11
 index:
 prefix: index_
 period: 24h
 server:
 http_listen_port: 3100
 storage_config:
 boltdb_shipper:
 active_index_directory: /data/loki/boltdb-shipper-active
 cache_location: /data/loki/boltdb-shipper-cache
 cache_ttl: 24h
 shared_store: filesystem
 filesystem:
 directory: /data/loki/chunks
 chunk_store_config:
 max_look_back_period: 0s
 table_manager:
 retention_deletes_enabled: true
 retention_period: 48h
 compactor:
 working_directory: /data/loki/boltdb-shipper-compactor
 shared_store: filesystem
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
 name: loki
 namespace: logging
spec:
 podManagementPolicy: OrderedReady
 replicas: 1
 serviceName: loki
 template:
 metadata:
 labels:
 app: loki
 spec:
 serviceAccountName: loki
 securityContext:
 fsGroup: 10001
 runAsGroup: 10001
 runAsNonRoot: true
 runAsUser: 10001
 initContainers:
 - name: fix-permissions
 image: busybox:latest
 securityContext:
 privileged: true
 runAsGroup: 0
 runAsNonRoot: false
 runAsUser: 0
 command:
 - sh
 - -c
 - >-
 id;
 mkdir -p /data/loki;
 chown 10001:10001 /data -R;
 ls -la /data/
 volumeMounts:
 - mountPath: /data
 name: loki-storage
 containers:
 - name: loki
 image: grafana/loki:2.9.3
 args:
 - -config.file=/etc/loki/config/loki.yaml
 volumeMounts:
 - name: config
 mountPath: /etc/loki/config/loki.yaml
 subPath: loki.yaml
 - name: loki-storage
 mountPath: /data
 ports:
 - name: http-metrics
 containerPort: 3100
 livenessProbe:
 httpGet:
 path: /ready
 port: http-metrics
 initialDelaySeconds: 45
 readinessProbe:
 httpGet:
 path: /ready
 port: http-metrics
 initialDelaySeconds: 45
 securityContext:
 readOnlyRootFilesystem: true
 volumeClaimTemplates:
 - metadata:
 name: loki-storage
 spec:
 accessModes: [ReadWriteOnce]
 resources:
 requests:
 storage: 3Gi
---
apiVersion: v1
kind: Service
metadata:
 name: loki
 namespace: logging
spec:
 type: ClusterIP
 ports:
 - port: 3100
 name: http-metrics
 selector:
 app: loki
---
apiVersion: v1
kind: Service
metadata:
 name: loki-outer
 namespace: logging
spec:
 type: NodePort
 ports:
 - port: 3100
 nodePort: 32537
 selector:
 app: loki

3.3 部署

1
2


kubectl create ns logging
kubectl apply -f /data/k8scnf/loki.yaml

4. Promtail 部署

Promtail 是 Loki 的"客户端"，每节点跑一个 DaemonSet。

4.1 ConfigMap

 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


apiVersion: v1
kind: ConfigMap
metadata:
 name: promtail
 namespace: logging
data:
 promtail.yaml: |
 server:
 http_listen_port: 9080
 positions:
 filename: /tmp/positions.yaml
 clients:
 - url: http://loki:3100/loki/api/v1/push
 scrape_configs:
 - job_name: kubernetes-pods
 kubernetes_sd_configs:
 - role: pod
 relabel_configs:
 - source_labels: [__meta_kubernetes_pod_label_name]
 target_label: __service__
 - source_labels: [__meta_kubernetes_pod_node_name]
 target_label: __host__
 - action: labelmap
 regex: __meta_kubernetes_pod_label_(.+)
 - action: replace
 source_labels: [__meta_kubernetes_namespace]
 target_label: namespace
 - action: replace
 source_labels: [__meta_kubernetes_pod_name]
 target_label: pod

4.2 DaemonSet + RBAC

 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
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67


apiVersion: v1
kind: ServiceAccount
metadata:
 name: promtail
 namespace: logging
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
 name: promtail
rules:
 - apiGroups: [""]
 resources: [nodes, nodes/proxy, services, endpoints, pods]
 verbs: [get, list, watch]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
 name: promtail
subjects:
 - kind: ServiceAccount
 name: promtail
 namespace: logging
roleRef:
 kind: ClusterRole
 name: promtail
 apiGroup: rbac.authorization.k8s.io
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
 name: promtail
 namespace: logging
spec:
 selector:
 matchLabels:
 name: promtail
 template:
 metadata:
 labels:
 name: promtail
 spec:
 serviceAccountName: promtail
 containers:
 - name: promtail
 image: grafana/promtail:2.9.3
 args:
 - -config.file=/etc/promtail/promtail.yaml
 volumeMounts:
 - name: config
 mountPath: /etc/promtail
 - name: docker
 mountPath: /var/lib/docker/containers
 readOnly: true
 - name: pods
 mountPath: /var/log/pods
 readOnly: true
 volumes:
 - name: config
 configMap:
 name: promtail
 - name: docker
 hostPath:
 path: /var/lib/docker/containers
 - name: pods
 hostPath:
 path: /var/log/pods

5. 验证与查询

5.1 Loki 健康

1
2
3
4


kubectl -n logging port-forward svc/loki 3100:3100
# 浏览器
http://localhost:3100/ready
# 看到 "ready" 即 OK

5.2 Grafana 配置 Loki 数据源

Grafana → Configuration → Data sources → Add data source → Loki

URL：http://loki:3100

5.3 查日志

Grafana Explore → 数据源选 Loki → 查询：

1
2
3


{namespace="kube-system"}
{namespace="default"} |= "error"
{app="my-app"} | json | line_format "{{.msg}}"

{job="kubernetes-pods"} |= "ERROR" 查所有 ERROR 日志。

6. 常见问题

6.1 `loki-0 1/2 CrashLoopBackOff`

容器权限问题。yaml 里加 initContainer：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


initContainers:
 - name: fix-permissions
 image: busybox:latest
 securityContext:
 privileged: true
 runAsGroup: 0
 runAsUser: 0
 command:
 - sh
 - -c
 - >-
 mkdir -p /data/loki;
 chown 10001:10001 /data -R;
 ls -la /data/
 volumeMounts:
 - mountPath: /data
 name: storage

实测 2.7.3 有 bug，2.6.1 反而正常——怀疑是 Loki 配置变更导致容器启动顺序问题。直接换成 2.6.1。

6.2 `no such file or directory: /var/log/pods/...`

docker 数据目录迁移过 → Promtail 找不到容器日志。

解决：把 Promtail 的 /var/lib/docker/containers 路径改成实际路径；或重装 docker 到默认路径。

临时方案：重启故障 Pod：

1

kubectl delete po <pod> -n kube-system

6.3 Promtail 一直 Buffer filling up

Promtail 默认 buffer 满了就丢日志。调大：

1
2
3
4
5
6


positions:
 filename: /tmp/positions.yaml
clients:
 - url: http://loki:3100/loki/api/v1/push
 batchwait: 1s
 batchsize: 1048576

6.4 日志保留时间太短

1
2
3
4
5


limits_config:
 retention_period: 168h  # 7 天
table_manager:
 retention_deletes_enabled: true
 retention_period: 168h

6.5 helm 部署 RBAC 冲突

1
2


kubectl delete ClusterRole loki-promtail
kubectl delete ClusterRole loki-grafana-clusterrole

7. 小结

Loki + Promtail 是 K8s 时代"轻量级日志方案"的事实标准：

DaemonSet 采集 占资源最少，适合中小集群
Loki 4 微服务（write / read / backend / gateway）支持水平扩展
LogQL 语法像 PromQL，习惯 Prometheus 的人秒上手
容器权限问题 用 initContainer 修
保留策略 默认 48h，生产建议 7-30 天

下一步：K8s 实战：Deployment/StatefulSet/DaemonSet 区别 + 探针 + hostNetwork 调度。

Loki + Promtail 日志架构：像查指标一样查日志

Wed, 15 May 2024 00:00:00 +0800

Prometheus 解决的是"指标"问题，但线上排障 80% 的时间还是靠"日志"。传统方案是 ELK（Elasticsearch + Logstash + Kibana），重、占资源、运维复杂。Grafana Labs 推出的 Loki + Promtail 组合走的是另一条路——“像查指标一样查日志”：不建索引、只做标签、查询时按需拉取，配合 Grafana 一站式展示。这篇文章把零散在多个笔记里的部署、配置、踩坑细节，整理成"从零拉起→接入业务容器→清理过期日志"的一条完整路径。

阅读对象：已经在用 Prometheus + Grafana 体系，希望把日志也接进来的开发者、运维同学
覆盖范围：Loki 主服务（v2.9.x 时代）、Promtail / docker log driver 两种采集方式、多行日志识别、retention 清理、Nginx 反向代理

一、为什么是 Loki

在引入 Loki 之前，日志方案无外乎这几类：

ELK（Elasticsearch + Logstash + Kibana）：经典但重，JVM + 倒排索引吃资源，小机器跑不动
EFK（Fluentd 替代 Logstash）：稍轻量但仍依赖 ES
自建文件存储 + 简单 grep：能用但没可视化、没聚合
云厂商日志服务：阿里云 SLS、AWS CloudWatch Logs 等，绑定厂商

Loki 的设计哲学是"和 Prometheus 同构"：

维度	Prometheus	Loki
数据类型	指标（时序数值）	日志（文本行）
索引方式	标签（label）	标签（label）
存储	TSDB 本地/远端	对象存储/文件系统
查询语言	PromQL	LogQL
展示	Grafana	Grafana
资源占用	中	低（不做倒排索引）

When to use：如果你已经用 Prometheus + Grafana 做监控，强烈推荐 Loki——同一个 Grafana 实例、同一套标签习惯、几乎零额外学习成本。如果你的日志需要"全文模糊匹配"（Loki 不擅长）或日均日志量 GB 级以上（建议直接上 ES + SLS），那 Loki 就不合适了。

二、架构总览

Loki 体系的角色分工极简：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


业务容器（被采集）
 │
 ├─→ 方式 A：Promtail 进程 → 读容器日志文件 → 推送
 └─→ 方式 B：docker log driver（loki plugin） → 直推
 │
 ▼
 Loki 主服务（存储 + 查询）
 │
 ▼
 Grafana（展示）

Loki：主服务，负责存储日志和处理查询
Promtail：代理，负责从各种来源（文件、syslog、journald）采集日志并推给 Loki
Grafana：UI 展示 + 数据源对接（和 Prometheus 同一个实例即可）

三、Loki 部署

3.1 直接 docker run（最小可用）

1

docker run -d --name=loki --restart=always -p 3100:3100 grafana/loki:2.9.5

默认数据存到容器内 /loki 目录，容器销毁即数据丢失，生产环境必须挂载出来。

3.2 docker-compose（推荐）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


version: "3"
services:
 loki:
 image: grafana/loki:2.9.5
 container_name: loki
 restart: always
 network_mode: host
 volumes:
 - /home/docker/loki/config:/etc/loki
 command: -config.file=/etc/loki/local-config.yaml

默认配置 /etc/loki/local-config.yaml（Loki 2.9.5 自带）：

 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


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: boltdb-shipper
 object_store: filesystem
 schema: v11
 index:
 prefix: index_
 period: 24h

ruler:
 alertmanager_url: http://localhost:9093

schema 版本：v11 是 Loki 2.9 时代的默认 schema。如果以后升级 Loki 主版本，要查 CHANGELOG 看 schema 是否需要迁移。生产环境建议把 chunks 和 rules 目录挂到大磁盘上，不要放系统盘。

四、日志采集：两种方式

4.1 方式 A：Promtail（推荐，灵活）

Promtail 是 Loki 官方的采集器，配置和 Promtail/Loki 同源：

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


# promtail 配置片段
server:
 http_listen_port: 9080

positions:
 filename: /tmp/positions.yaml

clients:
 - url: http://{{LOKI_HOST}}:3100/loki/api/v1/push

scrape_configs:
 - job_name: docker
 docker_sd_configs:
 - host: unix:///var/run/docker.sock
 refresh_interval: 5s
 relabel_configs:
 - source_labels: ['__meta_docker_container_name']
 target_label: 'container'
 - source_labels: ['__meta_docker_container_log_stream']
 target_label: 'stream'
 pipeline_stages:
 - docker: {}

多行日志识别：Java 应用的异常堆栈、Nginx 多行 access log 等，默认会被拆成多行记录。配置 loki-pipeline-stages 的 multiline 段：

1
2
3
4
5
6
7


options:
 loki-url: "http://{{LOKI_HOST}}:3100/loki/api/v1/push"
 max-size: "50m"
 max-file: "10"
 loki-pipeline-stages: |
 - multiline:
 firstline: '^\[\d{2}:\d{2}:\d{2} \w{4}\]'

上面这条规则表示：以 [HH:MM:SS DAY] 开头的行是新日志的起点，其余行归属同一日志。

4.2 方式 B：docker log driver（最简）

Loki 官方提供了 docker plugin，装上后业务容器启动时加 --log-driver=loki 即可：

1
2


# 安装插件
docker plugin install grafana/loki-docker-driver:latest --alias loki --grant-all-permissions

国内直接拉可能 403（gcr.io 同款问题），离线场景需要：

1
2
3
4
5
6


# 离线节点
docker plugin disable loki -f
docker plugin rm loki -f
tar -xzf plugins.tar.gz -C /var/lib/docker
service docker restart
docker plugin enable loki

业务容器接入（示例）：

1
2
3
4
5
6
7
8


docker run -it -d \
 --name my-app \
 --restart=always \
 --log-driver=loki \
 --log-opt loki-url="http://{{LOKI_HOST}}:3100/loki/api/v1/push" \
 --log-opt max-size=50m \
 --log-opt max-file=10 \
 my-app:v1

小坑：loki-pipeline-stages 这种含特殊字符的 option 在 daemon.json 里配置时，JSON 字符串需要转义 \n，写错直接被 docker daemon 拒绝。

4.3 全局模式（所有容器默认走 Loki）

修改 /etc/docker/daemon.json：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


{
 "log-driver": "loki",
 "log-opts": {
 "loki-url": "http://{{LOKI_HOST}}:3100/loki/api/v1/push",
 "max-size": "50m",
 "max-file": "10"
 },
 "registry-mirrors": [
 "https://docker.m.daocloud.io",
 "https://hub-mirror.c.163.com",
 "https://mirror.baidubce.com",
 "https://docker.nju.edu.cn"
 ]
}

重启 docker 后所有容器都会切换日志驱动，已经在跑的应用会因为日志驱动不匹配启动失败。生产环境切换前先停业务，或者用"按容器 logging 字段覆盖"的折中方案。

4.4 docker-compose 模板

最常用的"logging anchor"写法：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


version: "3"
x-logging: &loki-logging
 driver: loki
 options:
 loki-url: "http://{{LOKI_HOST}}:3100/loki/api/v1/push"
 max-size: "50m"
 max-file: "10"
 loki-pipeline-stages: |
 - multiline:
 firstline: '^\[\d{2}:\d{2}:\d{2} \w{4}\]'

services:
 my-service:
 image: my-image:tag
 restart: always
 logging: *loki-logging
 # ...

五、Grafana 对接

Loki + Grafana 是天生一对：

Grafana → Configuration → Data Sources → Add data source → Loki
URL 填 http://{{LOKI_HOST}}:3100
保存

查询语法（LogQL）示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# 查名为 my-app 容器的所有日志
{container="my-app"}

# 包含 "ERROR" 的日志
{container="my-app"} |= "ERROR"

# 不包含 "health-check"
{container="my-app"} != "health-check"

# 正则匹配
{container="my-app"} |~ "Exception.*at .*\\(.+\\.java"

# 过去 5 分钟
{container="my-app"}[5m]

六、Retention 清理（关键！）

Loki 默认永不过期，磁盘会被慢慢吃光。

旧方式（已废弃，2.4 之前）

1
2
3


table_manager:
 retention_deletes_enabled: true
 retention_period: 24h

新方式（2.4+）

1
2
3
4
5
6
7
8


compactor:
 retention_enabled: true
 compaction_interval: 10m  # Compactor 检查过期表的间隔
 retention_delete_delay: 5m  # 过期后多久真正删除
 retention_delete_worker_count: 150

limits_config:
 retention_period: 7d  # 保留 7 天

修改后重启 Loki 生效。

七、Nginx 反向代理

Loki 服务端（带 WebSocket 实时推送和 HTTP 查询）需要 Nginx 转发：

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


server {
 listen 8080;
 server_name loki.example.com;

 add_header Access-Control-Allow-Origin *;
 add_header Access-Control-Allow-Methods 'GET, POST, OPTIONS';
 add_header Access-Control-Allow-Headers 'DNT,X-Mx-ReqToken,Keep-Alive,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Authorization';

 location / {
 proxy_pass http://{{LOKI_HOST}}:3100;
 proxy_http_version 1.1;
 proxy_set_header Host loki.example.com;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_connect_timeout 60;
 proxy_read_timeout 600;
 proxy_send_timeout 600;
 }
}

必须带 Upgrade/Connection 头：Grafana 查询 Loki 的实时流接口要 WebSocket，没有 Upgrade 头会被 nginx 拒绝。

八、踩坑清单

磁盘吃光——Loki 默认永久保留日志，必须配置 compactor.retention_enabled
查询慢——Loki 不索引日志内容，模糊匹配走"全量扫描"。查询时尽量用 |=、!= 做精确过滤，避免 |~ 正则匹配超大日志流
多行日志被拆碎——Java 异常、Nginx 多行 log 必须配 multiline，否则一条错误变成几十条记录
gcr.io 拉镜像失败——grafana/loki-docker-driver 插件托管在 gcr.io，国内走离线打包或者换用 Promtail 方案
schema 升级——Loki 主版本升级时，schema 不兼容会启动失败。务必先查 CHANGELOG 看是否需要 loki-canary 验证、是否需要执行 loki 内置的 schema 迁移工具
时区问题——Loki 时间戳按 UTC 存储，Grafana 里看日志时间默认也是 UTC。要么在 Grafana 里设 Dashboard timezone 为 Asia/Shanghai，要么在查询时显式带时区

九、2024+ 视角补充

本文写于 2024-05，2024-2026 期间 Loki 关键演进：

Loki 3.x（2024-Q3 起）：全面 BoltDB-shipper 弃用，统一走 TSDB 存储（与 Prometheus 一样的 TSDB），启动速度 / 写入吞吐 / 内存占用全面优化
Loki 3.3+：单二进制模式（Loki / Querier / Ingester / Distributor 合并）——小规模部署 1 容器跑 1 个 Loki 即可，无需拆微服务
Alloy 替代 Promtail：Grafana 2024 推出 Grafana Alloy（基于 Grafana Agent 演进），统一 Telemetry 采集（Logs / Metrics / Traces / Profiles），Promtail 进入 maintenance 模式
Loki 3.4+：结构化元数据（Structured Metadata）——日志标签化效率比 2.9 时代提升 10x
Loki + Promtail 已成过去：2025+ 推荐 Loki + Alloy 组合
对象存储成熟：S3 兼容存储（GCS、MinIO、Azure Blob、华为 OBS）全支持——本地盘生产已不再推荐

实战建议（2025-2026 视角）：

Loki 3.3+ 单二进制 + MinIO / S3 存储后端 + Alloy 采集 是 2025+ 主流
大集群（> 50 节点）：Loki 微服务模式（querier / ingester / distributor 拆分）+ Kafka 缓冲——高吞吐稳定
向量检索：2025+ Loki 实验支持 向量相似度查询（与 Grafana 11 配合），但生产慎用——性能不如专用向量库
告警：Loki 3.x 内置 ruler（不再依赖 alertmanager）——一站式告警

十、参考资料

Loki 官方文档：https://grafana.com/docs/loki/latest/
Promtail 配置：https://grafana.com/docs/loki/latest/clients/promtail/
LogQL 查询语法：https://grafana.com/docs/loki/latest/logql/
离线插件打包：参考 docker plugin install 文档
Grafana Alloy 替代 Promtail：https://grafana.com/docs/alloy/

下一步

监控那层用 Prometheus？→ 看 Prometheus 监控告警体系一文
不想装一堆组件？→ HertzBeat 轻量监控告警把监控 + 告警 + 通知合三为一
Grafana 还想要"链路追踪"？→ 接入 Tempo，复用同一套 Grafana