Loki Deployment UI 使用指南:在 Loki 中部署、访问与管理运维界面
Loki Deployment UI 使用指南:在 Loki 中部署、访问与管理运维界面
Loki Deployment UI(Loki 部署用户界面)是 Loki 提供的基于 Web 的运维管理界面,用于在微服务模式或单二进制模式下管理和监控整个 Loki 部署。本文将基于 docs/sources/operations/loki-ui/_index.md 并结合仓库源码,完整介绍该 UI 的部署方式、访问路径、已就绪与开发中的功能清单,以及 Nodes、Rings、Analyze Labels、Deletes 等核心页面的使用方法与底层实现原理。
简介与定位
Loki Deployment UI 面向运维人员,提供了查看集群节点状态、检查分布式哈希环(Ring)成员、分析日志流标签分布、管理删除请求等能力。它不是一个替代 Grafana 的全新可视化平台,而是补充了 Grafana 中缺失的 Loki 自身运行状态管理视角——例如每个组件的服务健康度、配置生效情况、原始指标与性能汇总等。
在使用之前必须明确:该 UI 目前处于 experimental(实验性) 状态,功能与界面随时可能变化。开始部署前,请务必阅读下文 部署前须知 一节。
部署前须知(Considerations)
官方文档在介绍部署步骤之前,用显著的警告框列出了三点必须了解的限制,它们直接决定了该 UI 的使用边界:
- 功能并不完整:并非所有功能都已在 Loki Deployment UI 中可用,部分功能仍在开发中。从源码 pkg/ui/handler.go 注册的路由可以看到,当前已实现的 API 包括集群节点、节点详情、分析标签(analyze-labels)、分析指标等,而 Object Storage、Limits、Rules 等页面仍处于规划状态。
- 没有内置认证与授权:任何能够访问到该 UI 的人都可以发起删除请求、修改组件日志级别等敏感操作。因此绝不能将 UI 直接暴露在不可信网络中,必须在前面部署反向代理或认证网关。
- 不替代元监控:该 UI 不是 Loki 元监控(meta-monitoring)的替代品,它更偏向交互式排障与管理,持续性告警与指标采集仍应依赖 Prometheus 等监控体系。
此外,由于 UI 缺少认证层,文档在"访问方式"一节特别给出了 caution 提示:/ui 路径当前无法修改为其他路径,如需自定义路径需要向代码库贡献代码。从 pkg/ui/handler.go 可以看到 prefixPath = "/ui" 是硬编码常量,印证了这一限制。
部署方式
Docker 容器部署
每一个 Loki 组件都内置了 UI 服务。当以 Docker 容器方式运行 Loki 时,UI 服务默认启用,无需额外配置。例如直接运行 docker run 或 docker-compose 启动的 Loki 单二进制实例,启动后即可直接访问 /ui。
Helm 部署
对于 Helm 用户,UI 服务的可发现性需要显式开启。在 values.yaml 的 loki 段中加入如下配置:
loki:
ui:
enabled: true
仓库中的 Helm 默认值 production/helm/loki/values.yaml 显示该开关默认关闭(enabled: false),注释说明这是为了向后兼容;同时 gateway.enabled: true 表示默认启用网关到 UI 的 /ui 路径代理。模板逻辑位于 production/helm/loki/values.yaml:仅当 ui.enabled 为 true 时才会在最终 Loki 配置中注入 ui: enabled: true。
从源码 pkg/ui/config.go 可以看出,YAML 配置 ui.enabled 与命令行参数 -ui.enabled(默认 false)一一对应,此外还有 -ui.debug(启用 UI 调试日志)以及一整套以 ui. 为前缀的 Ring 与 Goldfish 配置参数。
分布式模式下的架构要点
从 pkg/ui/README.md 和 pkg/loki/loki.go 可以了解分布式模式下的架构设计:
- 任意组件可通过
uitarget 启动 UI 服务,该节点是 UI API 的入口,并能将请求代理到集群中的其他节点。 - 所有 Loki Pod 都会加入 UI Ring(哈希环),这样承载 UI 的节点才能按节点名找到其他节点并发起代理请求。
- 从模块依赖表(pkg/loki/loki.go)可以看到,几乎每个组件(Distributor、Ingester、Querier、Ruler、Compactor、IndexGateway 等)的模块依赖中都包含
UIRing,印证了"所有节点加入 UI Ring"的设计。
因此,配置 ui.enabled: true 会让所有节点加入 UI Ring,但只有显式指定了 ui target 的节点才会真正对外提供 UI API——这两件事需要分别配置。
访问 Loki Deployment UI
UI 的访问地址为:
http://<LOKI_HOST>:<LOKI_PORT>/ui
其中 <LOKI_HOST> 是 Loki 服务器的主机名或 IP,<LOKI_PORT> 是 Loki 监听端口。Loki 默认运行在 3100 端口。如果你在 Kubernetes 中运行 Loki,UI 通过 loki-gateway 服务暴露,可以通过 port-forward 或使用 LoadBalancer 暴露服务来访问。
一个典型的本地访问示例(单二进制模式,默认端口 3100):
http://localhost:3100/ui
功能总览
Loki Deployment UI 当前规划了以下功能,按就绪状态可分为 Ready(已就绪) 与 Coming Soon(开发中) 两类:
| 功能 | 描述 | 就绪状态 |
|---|---|---|
| Nodes | 展示每个已部署 Loki 组件的状态 | Ready |
| Rollouts & Versions | 历史部署记录视图 | Coming Soon |
| Rings | 展示 Ring 成员状态 | Ready |
| Object Storage | 展示对象存储状态 | Coming Soon |
| Data Objects | 浏览集群中的数据对象 | Coming Soon |
| Analyze Labels | 分析日志流中的标签分布 | Ready |
| Deletes | 查看和管理删除请求 | Ready |
| Limits | 查看和管理租户限额 | Coming Soon |
| Labels | 查看标签统计 | Coming Soon |
| Rules | 查看和管理规则 | Coming Soon |
对照 pkg/ui/handler.go 中已注册的 API 路由,可以验证已就绪功能对应的后端实现均已存在:
GET /ui/api/v1/cluster/nodes— 集群节点状态GET /ui/api/v1/cluster/nodes/{nodename}/details— 节点详情GET /ui/api/v1/analytics— 分析指标GET /ui/api/v1/tenants/{tenantID}/analyze-labels— 标签分析GET /ui/api/v1/proxy/{nodename}/*— 节点代理
下面逐一详解各功能的用法。
Nodes(节点)
Nodes 页面展示每个已部署 Loki 组件的状态。根据部署模式不同,每个组件会被视为一个 node(节点) 或 service(服务)。Node 表格包含以下列:
- Node Name:组件名称,包含 Pod hash、Zone 信息等唯一标识符。
- Target:组件类型分类,如 distributor、ingester、querier 等。从源码 pkg/ui/cluster.go 可以看到,Target 是通过拉取该节点
/config端点并解析 YAML 中的target字段得到的,解析失败时显示unknown。 - Version:组件版本,基于容器镜像 tag。对应实现为拉取节点的
/loki/api/v1/status/buildinfo端点(pkg/ui/cluster.go)。 - Build Date:容器镜像的构建时间。
- Status:组件内每个服务的当前状态。每个组件可能包含多个服务,服务数量取决于组件类型。源码通过请求节点的
/services端点并解析service => status格式的文本行得到(pkg/ui/cluster.go)。 - Ready:组件就绪状态,取决于组件内各服务的状态。所有服务处于
ready状态时组件才算就绪,否则显示为not ready(通常伴随红色图标与错误信息)。实现上通过请求/ready端点并检查响应体是否为ready判定(pkg/ui/cluster.go)。 - Actions:跳转到该节点的专属页面,查看更详细的信息。
值得一提的是,集群节点列表的获取是并发完成的:源码 pkg/ui/cluster.go 使用 errgroup 以最多 16 个并发操作同时拉取各成员状态,单个成员拉取失败时会将错误记录到该成员条目中而不影响整体页面展示。
Node Page(节点详情页)
点击节点进入 Node Page 后,页面顶部继续展示 Nodes 表格中的原始信息,并额外提供排障与监控常用的扩展字段:Version(版本)、Created(创建时间)、Edition(版本形态)、Architecture(架构)、OS(操作系统)。从 pkg/ui/cluster.go 的 NodeDetails 结构可以看到,这些字段(含 ClusterID、ClusterSeededAt 以及汇总指标)来自节点的 /analytics 端点。
元数据区下方提供两个针对该组件的监控工具:
- Log Level(日志级别):动态修改该组件的日志级别,便于在线排障时提高日志详细度。
- Profiling Tools(性能剖析工具):获取该组件的 profile 数据,结果在新标签页展示或作为文件下载。
页面最后是三个标签页:
- Configuration:展示该组件实际生效的 Loki 配置。实现上是代理请求节点的
/config端点(pkg/ui/cluster.go),非常适合核对某个配置是否真正应用到了目标组件上。 - Analytic:组件的汇总指标,用于了解性能与健康状态。例如 ingester 会展示 stream 数量、flush chunk 速率与总量等。
- Raw Metrics:该组件的原始指标数据。
节点详情页背后是 UI 的代理机制:前端请求 /ui/api/v1/proxy/{nodename}/... 时,服务端先在 UI Ring 中按节点名找到目标地址,再由反向代理转发(见 pkg/ui/handler.go 的 clusterProxyHandler 与 pkg/ui/service.go 的 findNodeAddressByName),节点不存在或不在 Ring 中时会重定向到 404 处理页。
Rollouts & Versions
该功能用于提供历史部署记录视图,目前仍在开发中(Coming Soon)。
Rings(哈希环)
Rings 部分展示 Ring 成员的实时状态。一个 Loki 部署中最多可能存在 5 个 Ring,每个 Ring 负责一项特定任务(如 Ingester Ring、Ruler Ring、Compactor Ring、Index Gateway Ring、Query Scheduler Ring 等)。注意并非所有 Ring 都会出现在部署中,这取决于你的配置——例如 Index Gateway 和 Query Scheduler 都需要显式启用配置后才会存在对应 Ring。
Ring 表格包含以下列:
- ID:Ring 成员的唯一标识。
- Status:成员当前状态,如
ACTIVE、UNHEALTHY、LEAVING等。 - Address:成员的 IP 地址。
- Ownership:成员对 token 的所有权百分比。
- Zone:成员所在的 Zone(可用区)。
- Last Heartbeat:成员最后一次发送心跳的时间。
从实现上看,Ring 数据同样通过代理机制获取:例如访问 querier 节点上的 Ring 页面时,前端请求 /ui/api/v1/proxy/querier-1/ring,由于每个 ingester 都维护完整的 Ring 状态,只需查询单个成员即可看到整个 Ring(见 pkg/ui/README.md 中的具体示例)。
Object Storage / Data Objects
- Object Storage:展示对象存储状态,Coming Soon。
- Data Objects:Data Objects Explorer 用于浏览集群中的数据对象,Coming Soon。
Analyze Labels(标签分析)
Analyze Labels 页面用于分析指定租户和时间范围内日志流上的标签分布,是理解**标签基数(cardinality)**的实用工具。工具分为三个部分:
1. Analyze Labels(查询表单)
提供输入 Tenant ID(租户 ID)、Time Range(时间范围)以及可选的 Matchers(匹配器)的入口。官方示例中 Tenant ID 为 meta,Time Range 为 1h,Matchers 留空。
特别注意:如果你以单二进制模式运行 Loki,或者在 Loki 配置中禁用了 auth_enabled 参数,那么 Tenant ID 应为 fake。
从实现角度看,该功能本质上是把请求代理到本地节点的 /loki/api/v1/series 端点:源码 pkg/ui/handler.go 的 analyzeLabelsHandler 会校验路径中的 Tenant ID(复用 tenant.ValidTenantID 校验逻辑),将 X-Scope-OrgID 请求头设置为该租户,并把 URL 重写为 /loki/api/v1/series,同时保留 match[]、start、end 等查询参数——也就是说 UI 背后的数据来源于 series API 返回的标签集合,前端再对标签值做聚合统计。
2. Label Distribution(标签分布)
以柱状图直观展示标签分布。官方示例中总共 11 个唯一标签,其中 instance 拥有最多的唯一值(22 个)。这类标签需要重点关注,因为它可能是高基数标签的隐患。
3. Label Details(标签详情)
以表格形式展示标签及其唯一值的抽样,每个标签都可以展开查看具体唯一值。示例中 instance 标签的 22 个唯一值里包含类似 frontend-59b8c46fcb-ft29z 这样的值——它内部含有大量唯一 token(Pod 名与 hash),按 Loki 标签最佳实践应迁移到 Structured metadata(结构化元数据) 中,以降低标签基数、控制索引膨胀。
Deletes(删除请求)
Deletes 页面允许你查看已排期的 compactor 删除请求,也可以手动删除数据。删除请求表格包含以下列:
- Status:删除请求的状态。
- User:删除请求对应的 Tenant ID。
- Created At:请求创建时间。
- Range:删除请求的时间范围。
- Deleted Lines:已删除的行数。
- Query:用于删除数据的查询语句。
新建删除请求
点击 New Delete Request 按钮,在表单中填写 Tenant ID、Time Range 和 Query 即可创建新的删除请求。提交后该请求会进入 compactor 的删除队列,由 compactor 按排期执行。需要再次强调:由于 UI 没有认证层,任何能访问 UI 的人都可以发起删除请求,这是生产环境必须通过前置网关进行访问控制的关键原因。
Limits / Labels / Rules
这三个功能均处于开发阶段(Coming Soon):
- Limits:查看和管理租户限额。
- Labels:查看标签统计。
- Rules:查看和管理规则。
配置参考与安全建议
配置项速查
结合 pkg/ui/config.go 与 production/helm/loki/values.yaml,与 UI 相关的核心配置如下:
| 配置项(YAML / 命令行) | 默认值 | 说明 |
|---|---|---|
ui.enabled / -ui.enabled |
false |
是否启用 UI 服务(Helm 中位于 loki.ui.enabled) |
ui.debug / -ui.debug |
false |
是否启用 UI 的调试日志 |
ui.ring.* / -ui.ring.* |
— | UI Ring 配置,用于集群成员发现 |
ui.goldfish.enable / -ui.goldfish.enable |
false |
是否启用 Goldfish 查询对比功能 |
ui.goldfish.storage.type |
"" |
Goldfish 存储后端(cloudsql、rds 或空) |
ui.goldfish.results-backend |
"" |
查询结果存储后端(gcs、s3) |
从 pkg/loki/config_wrapper.go 可以看到,UI Ring 在未单独配置时会自动继承通用 Ring 配置(如心跳超时、实例地址、Zone 感知、KVStore 等),并且默认使用 memberlist 协议(pkg/loki/config_wrapper.go),因此多节点部署时无需为 UI Ring 单独搭建 KV Store。
安全与高可用建议
- 访问控制:UI 端点必须置于认证之后。
/ui前缀便于在反向代理中统一配置路由与鉴权,建议只允许可信内网或经过身份认证的用户访问。 - 节点间通信:UI 节点到其他节点的代理通信应限制在内网中。源码显示内部通信走 HTTP/2(pkg/ui/service.go),不应暴露到公网。
- 高可用:任意运行
uitarget 的节点都能提供 UI API,节点之间通过 UI Ring 自动发现,负载均衡器可将流量分发到多个 UI 节点(见 pkg/ui/README.md)。
总结
Loki Deployment UI 是当前仓库中处于实验阶段、但已具备实用能力的运维界面:Nodes 与 Rings 页面让集群拓扑与哈希环状态一目了然,Node Page 提供了动态调日志级别、性能剖析、配置核对与指标查看等排障利器,Analyze Labels 帮助提前发现高基数标签风险,Deletes 则打通了删除请求的创建与跟踪闭环。部署上只需在 Helm 中开启 loki.ui.enabled(Docker 默认开启),随后通过 http://<host>:3100/ui 即可访问。由于它缺少内置认证且仍在快速迭代,生产使用前务必做好网关鉴权,并持续关注各 Coming Soon 功能的演进。