安全开发-Grafana与Loki

1 引言:为什么需要集中式日志收集

Gitea、Harbor、SonarQube、Dependency-Track、Gatus 就位之后,甚至“服务活着没“也有状态页在盯。但还有一块看不见:服务活着的时候,里面发生了什么?

现在要看一个服务的日志,标准姿势是 docker logs <容器> 或 kubectl logs <Pod>。这对“瞄一眼“够用,但真要排查问题时,它的三个局限很快就顶到脸上:

  1. 要先知道容器在哪台机:容器/日志都在具体那台机器的本地。多机部署时,得先查“这个服务跑在哪“,再登到对应机器上敲命令,排查的起点就卡在“找位置“;
  2. 容器删了日志就丢:Docker 的日志默认写在本地的 json-file 文件里,容器或 Pod 一删,日志往往跟着删,事后想追“它挂之前最后说了什么“,已经晚了;
  3. 跨机器没法一起查:同一个服务的日志散在多台机器上,想问“最近一小时整个服务一共报了多少错“,得一台一台 grep,再人肉汇总。

集中式日志系统解决的正是这三件事:每台机器上装一个收集器,把本机日志持续送到一个中心存储;查询时只面对一个统一入口,跨机器、跨时间一起搜;再配一个可视化界面,把日志量、错误分布画成图,“哪里不对“一眼可见。

本文的主角就是这条链路的后半段:

  • Loki,Grafana Labs 出品的开源日志系统。一句话定位:“只索引标签,不索引正文”。传统日志系统会把正文里每个词都建成索引,查得全,但索引巨大、内存磁盘都贵;Loki 只给每条日志流建一小撮标签的索引,标签记的就是“这批日志来自哪个服务、哪个容器“这类信息;正文本身按压缩块存起来,索引小、存储便宜、查询快:先按标签定位到日志流,再在时间范围内扫正文。代价是全文关键词搜索不如 Elasticsearch 灵活,按行过滤是逐行扫描而不是查索引。本环境的服务规模完全够用,而且它和 Grafana 同源,集成最省事;
  • Grafana,开源可视化平台,是统一的查询与可视化入口,Loki 是它原生支持的数据源,配好就能开查。

2 定位与整体架构

2.1 观测的两层分工

内网体系的“观测“分两层,两层分工不同:

  • “活没活“层:Gatus 周期性探测各端点,状态页红绿展示。它回答的是“哪个服务出事了,该去哪儿看”;
  • “发生了什么“层:就是本篇的 Grafana + Loki。服务跑起来之后,里面发生的每一件事,不管是处理了什么请求、报了什么错还是做了什么升级动作,都留了痕。它回答的是“到了那儿,接下来看什么”。

两层合起来才是观测闭环。

2.2 整体架构:一条日志的旅程

flowchart LR
    subgraph 收集侧
        A[Docker 容器] -->|stdout/stderr| B[loki-docker-driver]
    end
    subgraph k3s["k3s 集群内部"]
        C[Loki<br/>chart 19.1.1 / 应用 3.7.9]
        D[MinIO 对象存储<br/>+ 持久化]
        C --- D
    end
    subgraph 入口
        E[Grafana<br/>grafana.kali-team.internal]
    end
    B -->|推送| C
    E -->|LogQL 查询| C

Loki 只在集群内可达,不对外暴露。

  • 收集侧:每台跑业务容器的机器上,给 Docker 装一个 Loki 日志驱动,接法在后面“接入新服务“一节细讲。Docker 守护进程收到容器的 stdout/stderr 后,顺手交给这个驱动,驱动批量推给 Loki,应用本身完全无感;
  • 存储侧:Loki 跑在 k3s 集群里,chart 19.1.1、应用 3.7.9,配 MinIO 对象存储做后端、PVC 做持久化;只在集群内可达,不对外暴露;
  • 入口侧:Grafana 通过数据源连 Loki,域名是 grafana.kali-team.internal,在 Explore / 仪表盘里用 LogQL 查询、把结果画出来。

3 搭建 Grafana

3.1 总体思路

这次部署的四个要点:

项选择说明
部署方式Helm chart,chart 14.0.1仓库用 grafana-community,先登记 chart 仓库,再从目录里挑
命名空间grafana独立命名空间,与其他平台隔离
IngressTraefik + 内网 CA 证书域名 grafana.kali-team.internal,证书由内网证书体系统一签发
存储开启 PVC 持久化仪表盘、用户等数据重建不丢

chart 仓库是 grafana-community,地址 https://grafana-community.github.io/helm-charts。先把仓库加进集群的 Chart 仓库并更新,再从目录里创建应用。Rancher UI 里 grafana chart 的页面如下,版本列表里本文用 14.0.1,对应应用版本 13.2.4:

Rancher 里的 grafana chart 页面

图 1:Rancher UI 里的 grafana chart 页面

3.2 values 两处修改逐项讲

创建应用时,默认的 values 需要改两处。下面是 diff,只引用改动的两段:

@@ -195,10 +195,10 @@
   tolerations: []
 ingress:
   annotations: {}
-  enabled: false
+  enabled: true
   extraPaths: []
   hosts:
-    - chart-example.local
+    - grafana.kali-team.internal
   labels: {}
   path: /
   pathType: Prefix
@@ -262,7 +262,7 @@
   accessModes:
     - ReadWriteOnce
   disableWarning: false
-  enabled: false
+  enabled: true
   extraPvcLabels: {}
   finalizers:
     - kubernetes.io/pvc-protection

3.3 安装与获取初始密码

实际安装命令与输出:

helm install --labels=catalog.cattle.io/cluster-repo-name=grafana --namespace=grafana --timeout=10m0s --values=/home/shell/helm/values-grafana-14.0.1.yaml --version=14.0.1 --wait=true grafana /home/shell/helm/grafana-14.0.1.tgz
level=WARN msg="--wait=true is deprecated (boolean value) and can be replaced with --wait=watcher"
NAME: grafana
LAST DEPLOYED: Fri Oct 23 03:17:35 2026
NAMESPACE: grafana
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
NOTES:
1. Get your 'admin' user password by running:
   kubectl get secret --namespace grafana grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo
2. The Grafana server can be accessed via port 80 on the following DNS name from within the cluster:
   grafana.grafana.svc.cluster.local
   If you configure Grafana itself to listen on port 80, grant the container
   the `NET_BIND_SERVICE` capability in values.yaml and reinstall:
   ```
   containerSecurityContext:
     capabilities:
       add:
         - NET_BIND_SERVICE
   ```
   For details, see https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/#http_port.
   From outside the cluster, the server URL(s) are:
     http://grafana.kali-team.internal
3. Login with the password from step 1 and the username: admin
---------------------------------------------------------------------
SUCCESS: helm install --labels=catalog.cattle.io/cluster-repo-name=grafana --namespace=grafana --timeout=10m0s --values=/home/shell/helm/values-grafana-14.0.1.yaml --version=14.0.1 --wait=true grafana /home/shell/helm/grafana-14.0.1.tgz

输出里有三处值得停一下:

  • 第 1 条就是获取 admin 初始密码的方法:

    kubectl get secret --namespace grafana grafana -o jsonpath="{.data.admin-password}" | base64 --decode ; echo
  • 安全约定,很重要:首登后立即修改初始密码。

  • 第 2 条:服务地址说明。集群内的 DNS 名是 grafana.grafana.svc.cluster.local,集群外的 URL 是 http://grafana.kali-team.internal。chart 默认文案写的是 http;本环境 TLS 由 Traefik 网关终结,浏览器实际走的是 https。这正是下一节 grafana.ini 加固里 root_url 要设成 https 的原因;

  • 第 3 条:用 admin + 第 1 条取到的密码登录。

初始密码在 Rancher UI 里也能看到(图 3)。

3.4 首次登录 + 界面改中文 + 健康检查

浏览器打开 https://grafana.kali-team.internal。本机 /etc/hosts 已登记该域名,指向 10.111.13.105,与 hub/mirror/nexus 同一个 k3s 节点。看到首次登录页,见图 2:用户名 admin + 上一节取到的初始密码。

Grafana 首次登录页

图 2:Grafana 首次登录页,admin + 初始密码

图 3 是 Rancher 里 grafana 命名空间的 Secret grafana 页面,两项分别是 admin-user,即用户名,固定为 admin,与 admin-password,即初始密码。上一节那条 kubectl 命令,取的就是这个 Secret 的后者。

Rancher 里 grafana 命名空间的 Secret grafana

图 3:Rancher 里 grafana 命名空间的 Secret

登录后顺手做一个小设置:把界面语言改成简体中文,入口在 个人设置 → 通用 → 语言。后文界面截图都是中文,见图 4。

Grafana 个人设置:语言设为简体中文

图 4:Grafana 个人设置页:语言已设为简体中文

最后做一次“活了没“的健康检查:访问 Grafana 内置的健康端点 https://grafana.kali-team.internal/api/health,实测返回:

{"database": "ok", "version": "13.2.4", "commit": "0e79aef9d91abf3bdadae9af15763029072fb45b"}

database: ok 说明内部存储健康;version: 13.2.4 是真实的应用版本,正好对上 chart 14.0.1。chart 版本与应用版本是两个独立的编号,别混淆:前者是“安装包的版本“,后者是“装出来软件本身的版本“。

4 Gitea SSO:Grafana 接入统一登录

4.1 Gitea 侧:建 OAuth2 应用

Gitea → 组织 dev-sec-ops → 设置 → 应用 → 新建 OAuth2 应用。图 5 即该应用的设置页,处于编辑状态:

  • 应用名称:Grafana,登录按钮和授权同意页上显示的名字;
  • 重定向 URL:https://grafana.kali-team.internal/login/generic_oauth。这是 Grafana 固定的回调地址,Gitea 授权完成后浏览器被送回这个地址完成登录闭环。协议和路径必须与 Grafana 的回调精确一致,一个字符都不能差,差一点就是登录循环或 404,这是最常见的坑,详见“常见问题与坑”;
  • 机密客户端:勾选,confidential client,指“能安全保管客户端密钥“的客户端。跑在服务端的 Web 应用属此类;与之相对的是跑在用户本地、守不住密钥的脚本类应用,即公有客户端。

保存后 Gitea 颁发一对值:半公开的标识 Client ID,与客户端密钥,密钥等价于密码,只写进 Grafana 侧配置。

Gitea 组织的 OAuth2 应用 Grafana

图 5:Gitea 的 OAuth2 应用设置

4.2 Grafana 侧:新建 Generic OAuth 数据源

Grafana → Connections → Data sources → Add data source,即 连接 → 数据源 → 添加数据源,类型选 Generic OAuth,见图 6:

  • Name:Gitea,登录按钮上显示的名字;
  • OIDC 发现 URL:https://hub.kali-team.internal/.well-known/openid-configuration。这是 Gitea 的标准“自描述“文件。.well-known/openid-configuration 是 OIDC 发现端点的行业约定路径,Grafana 拉取这个文件,就能自动识别 Gitea 的各个端点,不用手工逐个填。

Grafana 新建 Generic OAuth 数据源

图 6:新建 Generic OAuth 数据源,填 OIDC 发现 URL

填完保存后,表单里的 Auth URL / Token URL / API URL 等字段被自动填充,见图 7。这就是“发现“的结果:授权端点、令牌端点、用户信息端点,一次填全。

发现后各端点自动填充

图 7:各端点自动填充

最后把上一节 Gitea 颁发的 Client ID 与客户端密钥填进表单,保存。

4.3 验证:用 Gitea 身份进 Grafana

退出 admin 账号回到登录页,表单上多了一个新入口:“Sign in with Gitea”,见图 8。点它,浏览器被送到 Gitea 的授权确认页,见图 9:“Grafana 申请授权访问你的账户”,回调地址 grafana.kali-team.internal/login/generic_oauth 清清楚楚。点同意,浏览器自动回到 Grafana,人已经在里面了,全程没输一次 Grafana 密码,输的是 Gitea 的。

Grafana 登录页出现 Sign in with Gitea 按钮

图 8:Grafana 登录页出现 Gitea 登录按钮

Gitea 授权确认页

图 9:Gitea 授权确认页

进入后,右上角用户菜单显示 Gitea 身份 Kali-Team,账号 [email protected],见图 10。这个账号是首次 SSO 登录时 Grafana 自动创建的,无需手工建号。

SSO 登录后的 Grafana Explore 页

图 10:SSO 登录成功,右上角显示 Kali-Team

登录链路通了。下一节给配置文件做一轮加固。

5 grafana.ini 加固逐项

Grafana 的配置文件是 grafana.ini,INI 格式:[section] 段落加 key = value 键值对。chart 部署时这个文件被挂载进容器。改动 diff 如下,分布在文件中部与末尾两段:

@@ -1,5 +1,5 @@
 [analytics]
-check_for_updates = true
+check_for_updates = false
 [log]
 mode = console
 [paths]
@@ -10,6 +10,11 @@
 [plugins]
 preinstall_auto_update = false
 [server]
+root_url = https://grafana.kali-team.internal
 domain = grafana.kali-team.internal
 [unified_storage]
 index_path = /var/lib/grafana-search/bleve
+[plugins]
+allow_updates = false
+check_for_updates = false
+allow_loading_unsigned_plugins = false
+[users]
+auto_assign_org_role = Editor

diff 里出现了两个 [plugins] 段落,这是 INI 文件合法写法:同名段落会被合并,同名键以后出现的值为准,本次部署实际生效,已验证。下面按 key 归并讲解:

[server] root_url = https://grafana.kali-team.internal:本章最重要的项。

root_url 是“在 Grafana 自己看来,它被外部访问的地址“,必须与对外 URL 逐字符一致,包括协议。Grafana 的很多行为都拿它当基准:OIDC 登录的回调要送回哪里、页面里相对链接怎么解析、邮件通知里的地址等。一旦不一致,比如写成 http 而实际是 https,或漏了域名,典型症状就是 OIDC 回调 404 或浏览器在 Gitea 与 Grafana 之间无限循环,是这类部署最常见的坑。diff 里 root_url 下一行的 domain = grafana.kali-team.internal 是文件里原本就有的值,上下文行,未改动,供邮件模板等使用;root_url 才是本次新增的。

[analytics] check_for_updates = false:关闭“检查新版本“。 Grafana 默认会定期向公网发请求检查新版本;内网本来就到不了公网,关掉既避免无意义的请求,也避免把“当前版本是多少“这种信息往外暴露。

[plugins] allow_updates = false + check_for_updates = false:插件在线更新与更新检查全关。 这一条是供应链视角的安全加固:不让 Grafana 自己联网拉东西。插件更新改由团队走人工流程,从审计过的渠道拿离线包,而不是让它“自动装一个新版本“。自动更新意味着某天 Grafana 里多了一个你不认识的插件,而且说不清它是从哪里、什么时候装进来的。diff 里的 preinstall_auto_update = false 是原有值,预装插件同样不自动更新。

[plugins] allow_loading_unsigned_plugins = false:只加载签名插件。 插件是运行在 Grafana 进程里的第三方代码,“签名“意味着插件带有可验证的来源签名。设为 false 就是拒绝加载未签名插件,只放行来源签名可验证的。

[users] auto_assign_org_role = Editor:SSO 用户的初始角色。 经 SSO 首次登录的用户,进入组织时自动分配 Editor 角色,即刻可以干活。这里有一个便利与最小权限的取舍要说清楚:Grafana 的组织角色从低到高是 Viewer(查看者)< Editor(编辑者)< Admin(组织管理员):Editor 可以创建/修改仪表盘、做查询,但改不了组织级设置,成员增删、组织信息等那是 Admin 的权限。直接给 Editor 的好处是省掉了“进来先申请权限“这一步;想更严可以改成 Viewer,登录后只能看和查,不能创建/修改仪表盘,代价是用户想建仪表盘得找管理员。本环境选 Editor:内网 + SSO 已经把“谁能进来“管住了,进来的人默认给编辑权,便利优先。

生效方式:配置文件由 chart 挂载进容器,改完必须重启 Grafana 才生效,本次的实际操作就是修改 grafana.ini 后重新启动。

6 搭建 Loki

6.1 为什么选 Loki 不选 ELK

说到“日志系统“,很多人第一反应是 ELK 组合,Elasticsearch、Logstash、Kibana 三件套。本环境选 Loki 的理由:

  • 索引成本:Elasticsearch 对日志正文做全文索引,正文里每个词都进索引,搜索能力极强,但索引巨大、内存和磁盘开销都高;Loki 只索引标签、不索引正文,索引通常比全文索引小得多;
  • 存储:正文按压缩块存放,存储便宜,同样预算能留更久的日志;
  • 生态:与 Grafana 原生集成,数据源点几下就配好,Explore 查询页现成;
  • 规模匹配:内网服务规模就几台机器、少量容器,用 ELK 属于大材小用。

代价也如实说:全文关键词搜索不如 ES 灵活,LogQL 的行过滤语法 |= 是“定位到日志流后逐行扫描“,不是查索引,超大流量下速度会吃亏。对本环境,完全够用。

6.2 chart 结构与三项决策

Loki 同样从 grafana-community 仓库安装:chart 19.1.1(应用版本 3.7.9)。loki chart 和 grafana chart 有个不同:它自带子 chart(sub-chart),就是装在本 chart 里、随之一并部署的组件 chart。chart 页面,见图 11,可以看到 minio 与 rollout_operator 两个:

  • minio:开源对象存储(兼容 S3 API),作为 Loki 的存储后端,日志正文最终写进这里;
  • rollout_operator:负责编排 Loki 服务的滚动更新。Loki 是有状态服务,更新流程比无状态服务讲究,细节以 chart 文档为准。

Rancher 里的 loki chart 页面

图 11:Rancher UI 里的 loki chart 页面

部署决策就一句话:不需要租户隔离,开启 MinIO,加上持久化。逐项解释:

  1. 不开租户隔离:多租户,英文 tenant isolation,指多个团队共用一套 Loki、数据按租户互相隔离。开了之后,查询方必须在数据源侧配置 X-Scope-OrgID 请求头声明“我在查哪个租户“,详见“常见问题与坑“;本环境是单团队内网、一套用户,没这个复杂度需求,简单优先;
  2. 开启 MinIO:Loki 的正文要写进对象存储。为什么不直接写本地文件系统?本地磁盘绑死在单个节点上,扩容不方便、迁移不方便,节点更换数据就悬了;MinIO 是分布式对象存储,而且 chart 直接带了,开出来即用,具体开关项以 chart 文档为准;
  3. 加持久化:PVC,与 Grafana 开持久化同一个道理:索引与配置数据落持久存储,Pod 重建不丢日志。

说明:除下一节的内存分配调整外,其余具体 values 项不逐项展开,开关项以 loki chart 19.1.1 的官方文档为准。

6.3 网络形态:Loki 只在集群内可达

Grafana 和 Loki 的“暴露姿态“是刻意不同的:

  • Grafana:有对外域名 grafana.kali-team.internal,走 ingress + 内网证书,本机浏览器直接可达。它是入口,本来就要可达;
  • Loki:对外走 ingress。本机 /etc/hosts 里只登记了 grafana 的域名,没有 loki.kali-team.internal;k3s 节点 IP 的 3100 端口,也就是 Loki 的服务端口。

6.4 内存分配:启动提示不够内存,可以把 allocatedMemory 调小

values 还有一处真实调整,属于“启动遇到问题再修“的场景,单独拿出来讲。

loki chart 的 values 给各组件声明了 allocatedMemory,即内存配额,与 allocatedCPU,即 CPU 配额。比如 500m 就是 0.5 个核,m 是毫核,k8s 声明 CPU 的惯用单位。声明的作用是告诉 k8s:“这个组件要预留这么多资源”。如果声明值超过了节点上实际可用的内存,组件就调度不上去、起不来,也就是“启动提示不够内存“。这时候的修法是:把声明值调小,先让它跑起来。

diff 共两处,行号对应 values 文件:

@@ -407,7 +407,7 @@
     include "loki.namespace" $ }}.svc.{{ .Values.global.clusterDomain }}
   affinity: {}
   allocatedCPU: 500m
-  allocatedMemory: 8192
+  allocatedMemory: 1024
   annotations: {}
   batchSize: 4
   connectionLimit: 16384
@@ -429,7 +429,7 @@
 }}
   affinity: {}
   allocatedCPU: 500m
-  allocatedMemory: 8192
+  allocatedMemory: 1024
   annotations: {}
   batchSize: 4
   connectionLimit: 16384

给读者的用法:如果你的节点内存比本环境小,部署前可以先把这两项调小;如果部署后启动提示不够内存,优先减 allocatedMemory,它属于资源声明,不是功能配置,调小不会改变 Loki 本身的行为。声明太低会导致组件内存不足被杀,调的时候留点余量,以 chart 文档为准。

7 接通与查询

7.1 Grafana 加 Loki 数据源

Grafana → Connections → Data sources → Add data source,类型选 Loki。图 12 是配好后的数据源列表,Loki 已存在并设为默认:

Grafana 数据源列表

图 12:Grafana 数据源列表

设置页见图 13,关键项:

Loki 数据源设置

图 13:Loki 数据源设置

  • Name:Loki;
  • URL:http://loki.grafana.svc.cluster.local:3100。注意这是集群内服务地址,k8s 集群内 DNS 名的固定格式是 服务名.命名空间.svc.cluster.local,不是对外域名。Grafana 与 Loki 同在一个集群里,走内网互通,正好对应上面说的“只在集群内可达“;
  • Authentication:No Authentication。集群内的 Loki 服务本身没有鉴权层。别急着觉得“裸奔“:本环境的边界画在“集群内可达 + 入口有 SSO“上,集群外根本到不了 Loki,上面实测过。如果将来需要数据面鉴权,可以在 Loki 前再加一层,以官方文档为准;
  • Default:勾选,设为默认数据源,Explore 页默认就用 Loki。

7.2 Explore:跑第一条 LogQL 查询

LogQL,全称 Log Query Language,是 Loki 的查询语言。它的形态和 PromQL,Prometheus 的查询语言,很像。区别在于:PromQL 过滤的是指标,LogQL 过滤的是日志流,即标签集合相同的一组日志的连续流,可以理解为“同一个来源的一条日志管道“。

打开 Explore,左侧导航的“探索“入口,专为“对着单个数据源自由查询“设计的页面。选 Loki 数据源,输入:

{app="watchtower"}

这是最简单的形态:标签选择器,“把 app 标签等于 watchtower 的日志流全查出来”。watchtower 是业务主机上的镜像自动更新容器,它的日志已经通过 Docker 驱动流入 Loki。实际查询结果见图 14。

Explore 查询 watchtower 日志

图 14:watchtower 的 LogQL 查询结果

LogQL 速查表,日常够用,以下均可在本环境直接跑:

语法名称含义示例
{label="value"}标签选择器按流标签过滤日志流{app="watchtower"}
`= “text”`行过滤流内只保留包含某文本的行
!= "text"行排除流内只保留不包含某文本的行{app="watchtower"} != "debug"
输入时标签值自动补全输入 {app= 时页面下拉列出已有的标签值,值不用记{app= → 下拉可见 watchtower

读法:标签选择器回答“哪些流“,行过滤回答“流里哪些行“:先按标签缩小范围,这一步走索引,快,再逐行过滤,这一步是扫描,稍慢。这个“两级过滤“正是 Loki“只索引标签“设计的直接体现。

7.3 读图 14:日志卷图、Common labels、日志行

把图 14 从上到下读一遍:

  1. 日志卷图,顶部:横轴是时间,纵轴是“每秒日志条数“,图例按日志级别区分,图里能看到 debug / info 两个级别。这张图看服务的日志量走势:突刺、周期性峰值、突然停摆,一眼可见;
  2. Common labels 行,中部:列出本次结果的公共标签:app=watchtower、compose_project=watchtower、compose_service=watchtower,另有 6 个字段,界面上折叠显示。这三个标签哪来的?来自收集侧 Docker 驱动的 labels 选项:驱动把容器/compose 标签“提升“为 Loki 流标签。compose_project / compose_service 是 docker compose 自动给容器打的项目名/服务名标签,app 是 compose 文件里声明的标签;
  3. 日志行,下部:每行结构是 时间戳 + 级别 + 正文,正文含结构化字段。行首是时间戳,然后是级别,比如 DEBUG / INFO,正文里带若干键值对字段。

8 接入新服务:Docker Loki 日志驱动

上面的整体架构里,收集侧目前只有一条“活“的日志流,watchtower。其他服务怎么接进来?这一节讲 Docker Loki 日志驱动,Loki 官方提供的 Docker 日志插件:应用本身一行代码不用改,Docker 守护进程把容器的 stdout/stderr 顺手交给驱动,驱动批量推给 Loki。

这一节所有地址/凭据一律用占位符,使用时替换成你自己环境里的实际值。

8.1 收集侧机器:安装插件

Docker 插件 plugin 是给 Docker 守护进程加载的扩展包,日志驱动本质上就是守护进程“日志处理管道“上多出来的一段。在跑业务容器的那台机器,也就是收集侧,上执行:

docker plugin install grafana/loki-docker-driver:3.7.x-amd64 --alias loki --grant-all-permissions
  • 镜像 tag 与当前 Loki 的主版本对齐。本环境 Loki 应用是 3.7.9,所以用 3.7.x 系列的 tag,具体可用 tag 以插件官方文档为准;
  • --alias loki:给插件起别名 loki,后面 compose 文件里直接写 driver: loki,不用写全称;
  • --grant-all-permissions:插件要读容器日志、要往外发网络请求,需要多项守护进程权限,这个参数一次性全部授权,跳过逐项确认弹窗。授权了哪些权限可用 docker plugin inspect loki 查看。

验证 / 升级 / 卸载各一句:

docker plugin ls    # 验证:看到 loki 别名且状态为 active
# 升级:用新版本 tag 重新执行上面的 install 命令(以插件官方文档为准)
docker plugin rm loki    # 卸载

8.2 docker-compose:给服务加 loki 日志驱动

要接入的服务,在其 docker-compose.yml 的服务块里加一个 logging 段:

services:
  example-be:                    # 你的既有服务
    image: example-be:latest
    logging:                     # 新增:日志改走 loki 驱动
      driver: loki               # 上面安装的插件别名
      options:
        loki-url: "https://loki:[email protected]/loki/api/v1/push"   # 推送目标:Loki 的 push API 完整地址,本环境添加鉴权
        loki-retries: "3"        # 推送失败重试次数
        loki-batch-size: "10"    # 每批最多推多少条日志,批量发送,不是一条一条发
        labels: "app,compose_project,compose_service"   # 哪些容器/compose 标签提升为 Loki 流标签,逗号分隔

配置项说明:

配置项含义
loki-url驱动推日志的地址。按插件官方文档,这里填 Loki push API 的完整地址,即 https://loki:[email protected]/loki/api/v1/push
loki-retries一次推送失败后重试的次数,默认 3
loki-batch-size每批最多装多少条日志,默认 10
labels把指定的容器/compose 标签提升为 Loki 流标签,逗号分隔。这正是图 14 Common labels 的来源:compose_project / compose_service 是 compose 自动打的项目名/服务名标签,app 是 compose 文件里声明的标签

给已有服务补 logging 的 diff 小例:

 services:
   example-be:
     image: example-be:latest
+    logging:
+      driver: loki
+      options:
+        loki-url: "https://loki:[email protected]/loki/api/v1/push"
+        loki-retries: "3"
+        loki-batch-size: "10"
+        labels: "app,compose_project,compose_service"

改完 docker compose up -d 重建对应服务生效,之后的新日志就走 loki 驱动了。

8.3 连通性自测:curl 推一条测试日志

正式接服务之前,先自测“收集侧到 Loki 这条路通不通“:用 curl 直接向 push API 推一条测试日志,地址与上面的 loki-url 相同:

curl -XPOST "https://loki:[email protected]/loki/api/v1/push" \
  -H 'Content-Type: application/json' \
  -d '{"streams":[{"stream":{"app":"selftest"},"values":[["<纳秒时间戳>","hello from selftest"]]}]}'

拆开看请求体,Loki push API 的格式,以官方文档为准:

  • 最外层 streams 是数组,一次可以推多条流;
  • 每条流的 stream 字段是标签集合,决定这批日志属于哪条流;
  • values 是 [时间戳, 日志行] 的数组。注意时间戳单位是纳秒,这是 Loki 要求的格式,用秒级时间戳会报 400。

然后到 Grafana 的 Explore 里跑 {app="selftest"}:能查到 “hello from selftest” 这行,说明“收集侧 → Loki → Grafana“整条链路已通。

8.4 对比:Docker 驱动 vs 应用内推送

接入日志还有另一条路:应用内推送,在代码里集成日志客户端,把日志主动发给 Loki,可以顺带把请求 ID、用户 ID、业务流程 ID 等作为结构化字段一并发出。两种方式对比:

Docker 驱动,本章应用内推送
采集对象容器 stdout/stderr代码主动发出的内容,可做结构化
对应用的侵入透明,应用不知道自己日志被采集了要集成客户端、改代码
数据形态原始文本行结构化字段更丰富,级别/追踪 ID/业务字段
适用场景“先把所有容器的日志集中起来”关键服务的业务级日志分析

两者不是二选一,可以共存:驱动管“保底“,所有容器的 stdout 都不漏;应用内推送管“增强“,关键服务把业务语义发出来。新服务接入,从驱动开始,它是接入集中式日志系统成本最低的一步。

9 常见问题与坑

  1. root_url 与对外 URL 不一致:OIDC 回调 404 / 无限循环,最常见的坑 症状:点“Sign in with Gitea“后,浏览器在 Gitea 与 Grafana 之间来回跳,或最终 404。原因:回调地址以 root_url 为基准计算,它与真实对外 URL 在协议或域名上差一点,比如 http 对 https,Gitea 送回的地址就和注册的“重定向 URL“对不上,闭环断掉。修复:root_url 与对外 URL 逐字符对齐,含 https,同时核对 Gitea 侧重定向 URL 也一致。

  2. 开了租户隔离后,数据源查不到 / 403 本环境没开租户隔离;如果开了,查询必须声明“查哪个租户“:在 Grafana 数据源侧配置 X-Scope-OrgID 请求头。不配的话典型症状是查询结果为空或 403。修复:数据源的 HTTP 头设置里加 X-Scope-OrgID: <租户名>,细节以 Loki 多租户文档为准。

  3. 高基数字段别做成标签 请求 ID、用户 ID、会话 ID 这类“基本每条日志都不同“的值,不要放进标签,也就是不要写进 compose 文件 logging 段的 labels 选项里。Loki 只索引标签,每个标签组合就是一条流、都要记进索引。把这些值做成标签,标签组合数会爆炸 → 索引膨胀、内存/磁盘膨胀、查询变慢。正确姿势:把这类值放在正文或正文的结构化字段里,需要时用 |= 行过滤找。扫描有成本但可控。

10 小结

这一篇把内网 DevSecOps 体系的“发生了什么“层接上了:

  • Grafana,chart 14.0.1 / 应用 13.2.4:values 两处改动,ingress 开域名 + persistence 开持久化;初始密码用 kubectl 从 Secret 里取、首登立即修改;Gitea SSO 走 Generic OAuth,OIDC 发现 URL 自动填充;grafana.ini 一轮加固:root_url 逐字符一致、更新检查与插件在线更新全关、只加载签名插件、SSO 新用户直接 Editor;
  • Loki,chart 19.1.1 / 应用 3.7.9:不开租户隔离 + MinIO 对象存储 + 持久化;只在集群内可达,日志不出集群;
  • 接通与查询:Loki 数据源,集群内服务地址、No Authentication、设为默认;LogQL 速查表,标签选择器 + 行过滤/排除 + 自动补全;图 14 读法,日志卷图 / Common labels / 日志行结构;
  • 接入新服务:Docker Loki 日志驱动,装插件 → compose 加 logging 段 → curl 推测试日志自测,与应用内推送可共存。

至此观测闭环齐了:状态页答“活没活“,Grafana + Loki 答“发生了什么“,日志。

下一步是配置工作:

  1. 仪表盘:把高频 LogQL 查询固化成一屏视图:日志量、错误行、按服务分布;
  2. 告警:Loki 告警规则 + 通知渠道,让日志满足条件时自动提醒,配置方式以官方文档为准;
  3. 扩大收集侧:更多机器/服务接入 Docker 驱动,让“日志在哪台机“这件事彻底不用记。

参考