Grafana Loki 认证管理指南多租户、mTLS 与 nginx 反向代理实战【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/lokiGrafana Loki 本身不提供任何内置的认证层所有认证都必须由部署在服务前方的反向代理或传输层安全机制来完成。本文基于 Loki 官方运维文档系统讲解 Loki 的多租户认证模型X-Scope-OrgID、原生支持的 Mutual TLSmTLS客户端认证以及如何使用 nginx 为 Loki 配置 HTTP Basic Authentication 的完整实战流程帮助读者在单二进制、简单可扩展SSD与微服务等部署模式下安全地暴露 Loki API。Loki 的认证模型为什么需要反向代理Grafana Loki 不包含任何认证层这是设计使然你必须在服务前方部署一个具备认证能力的反向代理。简单可扩展Simple Scalable与微服务Microservices部署模式都要求在前端部署反向代理用于将客户端 API 请求路由到各个组件如 querier、distributor、ingester 等。默认情况下Loki 的 Helm chart 自带一个默认的反向代理配置使用 nginx 容器来处理流量路由与授权详见 production/helm/loki/templates/_helpers.tpl 中的 gateway nginx server 配置。官方建议可以选用的开源反向代理包括HAProxynginx可参考其 使用 HTTP Basic Authentication 限制访问的指南OAuth2 proxyPomerium其官方提供了 保护 Grafana 的指南在反向代理之上还可以搭配 Grafana Alloy 等日志采集 Agent 进行客户端侧的认证配置参考 Grafana Alloy 文档。多租户模式与 X-Scope-OrgID 头Loki 默认以多租户模式运行auth_enabled: true。在该模式下每个请求都必须携带X-Scope-OrgIDHTTP 头其值为标识租户的字符串填充该值的责任应由认证反向代理承担。一个未携带该头的请求会收到 HTTP401 Unauthorized错误和no org id消息。关于该错误的排查方法可参考 Error: No org ID完整的租户隔离机制说明见 多租户文档。从源码层面看这一行为在 pkg/util/fakeauth/fake_auth.go 的SetupAuthMiddleware中实现当auth_enabled为真时Loki 为 HTTP 请求挂载middleware.AuthenticateUser为 gRPC 请求挂载ServerUserHeaderInterceptor/StreamServerUserHeaderInterceptor从请求头中提取租户 ID 注入到请求上下文。user.ErrNoOrgID来自 dskit 的github.com/grafana/dskit/user包会被 pkg/util/server/error.go 归类为FailureUserError且 reason 为no_org_id并映射为401状态码返回给客户端。关闭多租户单租户模式如果希望单租户部署可以在配置中设置auth_enabled: false或使用等效的命令行标志-auth.enabledfalse默认值为true注册于 pkg/loki/loki.go 的RegisterFlags。关闭认证后Loki 会将每个请求的租户 ID 固定为no_auth_tenant配置项的值默认fake命令行标志为-auth.no-auth-tenant。此时 pkg/util/fakeauth/fake_auth.go 会为 HTTP 与 gRPC 请求统一注入noAuthTenant下游代码仍可假设租户始终存在代码路径无需分叉。需要留意的是在一个全新的、桶为空的集群上更改no_auth_tenant是安全的但若集群已经写入数据更改租户 ID 需要先将既有数据迁移到新的租户路径下可参考 cmd/migrate 迁移工具。Mutual TLSLoki 原生支持的传输层客户端认证Loki 的 HTTP 与 gRPC 服务器都可以要求客户端在连接建立前出示有效的 TLS 证书这是 Loki 无需反向代理即可原生支持的一种客户端认证形式。需要强调的是mTLS 在传输层对客户端进行认证但它不会填充X-Scope-OrgID。因此当auth_enabled: true时你仍然需要反向代理、日志采集 Agent 或客户端自身来设置该头以完成租户识别。启用 mTLS 的配置示例要要求客户端出示证书需要先在服务器上启用 TLS配置证书与私钥然后设置客户端认证策略client authentication policy以及签发客户端证书的证书颁发机构CA。例如server: http_tls_config: cert_file: /etc/loki/certs/server.crt key_file: /etc/loki/certs/server.key # Reject any client that does not present a certificate signed by this CA. client_auth_type: RequireAndVerifyClientCert client_ca_file: /etc/loki/certs/ca.crt参数说明cert_file/key_file服务器证书与私钥文件路径用于在服务器侧启用 TLS。client_auth_type客户端认证策略取值见下表。client_ca_fileCA 证书文件的路径也可以使用client_ca直接将证书内容内联写在配置文件中。grpc_tls_config块对 gRPC 服务器接受完全相同的选项。与之等价的命令行标志为-server.http-tls-client-auth与-server.http-tls-ca-pathHTTP 服务器-server.grpc-tls-client-auth与-server.grpc-tls-ca-pathgRPC 服务器client_auth_type 的可选值取值行为NoClientCert不要求也不验证客户端证书默认宽松行为RequestClientCert请求客户端证书但不强制要求也不验证RequireAnyClientCert要求客户端必须提供证书但不验证证书是否由指定 CA 签发VerifyClientCertIfGiven若客户端提供了证书则验证允许完全不提供证书的客户端RequireAndVerifyClientCert严格要求既拒绝不发送证书的客户端也拒绝未由指定 CA 签发的证书最严格的是RequireAndVerifyClientCert它拒绝未发送证书的客户端也拒绝未经指定 CA 签发的证书。其余取值检查相对宽松例如VerifyClientCertIfGiven允许客户端完全不发送证书。完整的 TLS 选项列表请参见 配置参考的 server 块。在真实配置中使用 mTLS在 Loki 的参考配置如 cmd/loki/loki-local-config.yaml中server块位于配置根级。若采用 Helm 部署loki.server下同样可以直接设置http_tls_config/grpc_tls_config。启用 mTLS 后所有 HTTP 与 gRPC 客户端包括日志采集 Agent、logcli、Grafana 数据源、以及组件之间的内部通信都必须配置相应的客户端证书与 CA否则连接将被拒绝。使用 nginx 为 Loki 启用 Basic Authentication本节完整演示使用 nginx 为 Loki 启用 HTTP Basic Authentication 的过程。这也是官方文档中唯一给出端到端验证示例的认证方案。前置条件一个运行中的 Loki 实例一个运行中的 nginx 实例配置 nginx需要为 Loki 实例新建一个 nginx 配置文件。以下示例假设nginx 运行在/opt/homebrew目录下Loki 运行在本机的 3100 端口Loki 的租户 ID 为fake配置文件名为/opt/homebrew/etc/nginx/loki.conf如果你的 Loki 使用了不同的配置参数请相应调整示例。loki.conf配置内容如下upstream loki { server 127.0.0.1:3100; keepalive 15; } server { listen 80; server_name loki.localhost; auth_basic loki auth; auth_basic_user_file /opt/homebrew/etc/nginx/passwords; location / { proxy_read_timeout 1800s; proxy_connect_timeout 1600s; proxy_pass http://loki; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection Keep-Alive; proxy_set_header Proxy-Connection Keep-Alive; proxy_redirect off; } location /ready { proxy_pass http://loki; proxy_http_version 1.1; proxy_set_header Connection Keep-Alive; proxy_set_header Proxy-Connection Keep-Alive; proxy_redirect off; auth_basic off; } }关键点解读upstream loki定义后端为127.0.0.1:3100keepalive 15维持长连接以减少握手开销。auth_basic loki auth与auth_basic_user_file启用 Basic Authentication密码文件路径为/opt/homebrew/etc/nginx/passwords。location /为所有 Loki API 请求启用认证并反代到后端。location /ready单独关闭认证auth_basic off保证 k8s 探针、负载均衡健康检查等自动化探活不受认证阻塞。长查询场景下将proxy_read_timeout设为1800s、proxy_connect_timeout设为1600s避免 nginx 在 Loki 处理慢查询时提前断开连接。将租户 ID 绑定到认证用户名本示例默认期望客户端在提供 Basic 认证凭据之外自己发送X-Scope-OrgID头。如果你的 Loki 以auth_enabled: true运行也可以让 nginx 根据认证后的用户名来设置租户 ID。在location / {}块中增加一行proxy_set_header X-Scope-OrgID $remote_user;加上这行后nginx 会覆盖客户端发送的任何租户头因此客户端无法读写其他租户的数据。这要求密码文件中的每个用户名都必须与某个 Loki 租户 ID 对应。Loki Helm chart 的 gateway 使用的正是这一模式——在 production/helm/loki/templates/_helpers.tpl 中可以看到proxy_set_header X-Scope-OrgID $remote_user通过gateway.nginxConfig.locationSnippet注入到每个 location 块默认值即{{ if .Values.loki.tenants }}proxy_set_header X-Scope-OrgID $remote_user;{{ end }}见 Helm 参考文档同时在启用gateway.basicAuth.enabled时设置auth_basic与auth_basic_user_file /etc/nginx/secrets/.htpasswd并以独立的location /返回200 OK且关闭认证用于探活。将配置纳入主 nginx.conf该配置必须被包含到 nginx 的主配置中例如在nginx.conf中加入include /opt/homebrew/etc/nginx/loki.conf;然后重启 nginx 服务使所有配置变更生效。验证 nginx 配置可以通过curl向两个端点发起请求来验证配置1./ready端点不受 Basic Authentication 保护% curl -i http://loki.localhost/ready HTTP/1.1 200 OK Server: nginx/1.29.2 Date: Thu, 16 Oct 2025 14:28:31 GMT Content-Type: text/plain; charsetutf-8 Content-Length: 6 Connection: keep-alive X-Content-Type-Options: nosniff ready2./端点受 Basic Authentication 保护未带凭据应返回 401curl -i http://loki.localhost/ HTTP/1.1 401 Unauthorized Server: nginx/1.29.2 Date: Thu, 16 Oct 2025 14:32:43 GMT Content-Type: text/html Content-Length: 179 Connection: keep-alive WWW-Authenticate: Basic realmloki auth html headtitle401 Authorization Required/title/head body centerh1401 Authorization Required/h1/center hrcenternginx/1.29.2/center /body /html注意 401 响应中的WWW-Authenticate: Basic realmloki auth头它告诉客户端该资源需要 Basic 认证且 realm 名称与auth_basic指令中的设置一致。更新密码文件密码文件可以用你为其他 Web 服务维护凭据的任何机制来生成。本示例使用htpasswd% htpasswd -c /opt/homebrew/etc/nginx/passwords loki123 New password: Re-type new password: Adding password for user loki123-c用于创建或覆盖密码文件若要在已有文件中追加用户请去掉-c。建议使用htpasswd -Bbcrypt等更安全的哈希算法生成密码条目。完成后重启 nginx 使变更生效。验证密码将密码写入临时文件例如% vi lokipw然后将其存入环境变量% pass$(cat lokipw)接着使用curl向受保护资源发起带凭据的请求来验证 Basic Authentication 是否生效curl -i -u loki123:$pass -H X-Scope-OrgID:fake http://loki.localhost/loki/api/v1/labels HTTP/1.1 200 OK Server: nginx/1.29.2 Date: Thu, 16 Oct 2025 14:46:09 GMT Content-Type: application/json; charsetUTF-8 Content-Length: 21 Connection: keep-alive {status:success}-u loki123:$pass提供 Basic 认证凭据-H X-Scope-OrgID:fake提供租户 ID此时也可以去掉该头改为依赖前文proxy_set_header X-Scope-OrgID $remote_user由 nginx 注入。请求/loki/api/v1/labels返回{status:success}说明认证、代理与租户识别链路均已打通。组合建议完整的安全暴露方案综合以上内容一个生产可用的 Loki 认证方案通常按以下层次组合传输层认证mTLS在 Loki 的server.http_tls_config/server.grpc_tls_config中启用RequireAndVerifyClientCert保证只有持有受信 CA 签发证书的客户端能建立连接。应用层认证Basic / OAuth2 等在反向代理nginx、HAProxy、OAuth2 proxy、Pomerium 等上启用身份认证作为面向最终用户或日志 Agent 的入口。租户注入X-Scope-OrgID由反向代理在认证通过后注入或覆盖X-Scope-OrgID头如 nginx 的proxy_set_header X-Scope-OrgID $remote_user确保客户端无法越权访问其他租户的数据。在 Loki 内部租户隔离贯穿所有组件写入、查询、索引与元数据均按租户隔离详见 多租户文档而当auth_enabled: true时缺少X-Scope-OrgID的请求会在 pkg/util/server/error.go 中被归类并返回401 no org id。理解这条反向代理认证 Loki 租户识别的责任边界是安全运维 Loki 的关键。【免费下载链接】lokiLike Prometheus, but for logs.项目地址: https://gitcode.com/GitHub_Trending/lok/loki创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考