Loki 社区常见问题解答：许可证、文档导航与贡献指南

本篇指南围绕 Grafana Loki 官方社区 FAQ（见 faqs.md）展开，系统解答了关于 Loki 开源许可证（AGPLv3）的合规边界、官方文档的结构与版本识别方法、文档与代码的贡献流程，以及获取社区帮助的渠道。读完本文，你将能够正确判断自己使用的 Loki 版本对应的文档，明确 AGPLv3 许可对你部署方式的影响，并快速找到参与 Loki 社区（提交 issue、PR 或 LID）的正确入口。

一、Loki 是否开源？采用什么许可证？

Loki 是开源项目，采用 GNU Affero General Public License v3（AGPLv3） 许可证。许可证全文位于仓库根目录的 LICENSE 文件中（共 661 行，包含 AGPLv3 的完整条款与附录）。

版本变更背景：Loki 的许可证从 Apache 2.0 变更为 AGPLv3 的时间点是 2021 年。这一点在仓库中也有印证——例如客户端组件目录下仍保留着历史协议文件 clients/LICENSE_APACHE2 和 loghttp/LICENSE_APACHE2，它们记录了早期 Apache 2.0 时代的授权约定。

AGPLv3 的实际影响：

• 如果你修改了 Loki 并通过网络对外提供服务，则必须将你的修改以相同许可证（AGPLv3）开放源码；
• 对绝大多数仅将 Loki 用于内部日志聚合的团队而言，这一条款没有实际影响；
• 如果你计划将 Loki 嵌入商业产品或以服务形式对外提供，应仔细审阅 LICENSE 条款，或联系 Grafana Labs 洽谈商业许可证。

注意：Grafana 可观测性技术栈中的其他组件（Grafana、Tempo、Mimir、Alloy）各自拥有独立的许可证条款，分别在其对应仓库中说明，不可一概而论。

二、文档如何组织？如何找到特定产品的文档？

Loki 官方文档托管在 grafana.com/docs/loki/，按以下顶级分区组织：

分区	内容
Get started（入门）	架构总览、部署模式、标签（label）概念
Set up（安装）	安装指南（Helm、Docker、本地二进制）、迁移与升级步骤
Configure（配置）	配置参考、常见对象存储后端的示例配置
Send data（采集数据）	使用 Grafana Alloy、Promtail、Docker 驱动及 HTTP API 发送日志
Query（查询）	LogQL 语言参考、查询示例与查询 API
Manage（运维）	存储、保留、缓存、多租户等 Day-2 运维
Alert（告警）	基于 LogQL 的 recording rules 与 alerting rules

本仓库镜像了上述大部分文档源码，位于 docs/sources 目录，其中 get-started、setup、configure、send-data、query、operations、alert 等子目录与在线文档的分区一一对应，读者可直接在仓库内离线查阅。

Grafana Labs 其他产品（Grafana、Mimir、Tempo、Alloy 等）的文档可从 Grafana 文档首页入口访问。

三、我读到的文档版本对吗？

Loki 文档按发行版本（release）进行版本化，默认情况下 grafana.com 与搜索引擎的链接都会指向 latest 版本，但如果你是从博客、论坛帖或旧搜索结果进入的，很可能正在阅读某个旧版本的文档。

判断与修正方法：

1. 查看左侧导航栏的版本选择器，如果显示的不是 latest，请切换为当前版本；
2. 也可以直接在 URL 中使用 /latest/ 路径，例如 grafana.com/docs/loki/latest/；
3. 如果版本选择器显示 next，说明你在阅读尚未发布的文档，其中描述的特性或配置可能在任何已发布版本中都不存在——next 文档适合预览未来功能，但不应作为当前部署的参考依据。

版本不匹配排查建议：如果文档中描述的配置项或特性在你的 Loki 部署中不存在，版本不匹配是最常见的原因。请在质疑文档正确性之前，先确认你的 Loki 版本。从当前仓库源码看，Loki 入口程序 cmd/loki/main.go 通过 PrintVersion 检测 -version 参数并调用 version.Print("loki") 输出版本信息，因此你可以在本地执行：

loki -version

或者查看容器镜像的 tag（image tag）来确认实际运行的版本，再与文档所示版本比对。

四、如何为文档做贡献或反馈文档问题？

Loki 文档是开源的，源码就存放在本仓库的 docs/sources 目录中，社区贡献随时欢迎。每篇文档页面底部都有三个入口：

• Suggest an edit（建议编辑）：直接在 GitHub 中打开该页面的源文件，提交 Pull Request 修正或改进；
• Contribute to docs（贡献文档）：用于反馈小问题或笔误，无需自己动手修改；
• Report a problem（报告问题）：用于反馈文档页面的渲染或行为问题。

仓库根目录的 CONTRIBUTING.md 也专门设有 "Contribute to documentation" 章节，且 docs/sources/community/contributing.md 提供了快速入门摘要：make 构建命令、make test 单元测试、make test-integration 集成测试（需 Docker，约 15 分钟）以及 make lint 等，均可作为提交文档改动前的本地验证手段。

如果文档未能解答你的疑问，Grafana Community Forum（社区论坛） 是最佳提问去处；你也可以加入 Grafana Labs Community Slack 的 #loki 频道，与维护者和用户交流 Loki 相关话题。

五、如何为代码做贡献或反馈代码问题？

Loki 在 GitHub 上以开放方式开发，贡献途径包括：

• 报告 Bug：在 GitHub 提交 issue，需包含 Loki 版本、部署模式、相关配置以及复现步骤；
• 提议新功能：功能请求同样以 GitHub issue 跟踪，描述使用场景与期望行为；
• 提交 Pull Request：完整贡献指南见仓库根目录 CONTRIBUTING.md，涵盖从源码构建、运行测试、代码风格到评审流程的完整说明；docs/sources/community/contributing.md 页面提供了快速入门摘要；
• 提议较大改动：对于影响 Loki 架构或行为的重大变更，需要先撰写 Loki Improvement Document（LID） 并以 Pull Request 形式提交，供社区讨论后再开始实现。

关于 LID 的补充说明

LID 流程是本仓库中实际落地的一套正式提案机制，相关规范位于 docs/sources/community/lids/_index.md：

• LID 用于在实施重大变更之前促进社区与维护者之间的沟通，确保只开发维护者和社区真正需要的功能；
• Bugfix、次要功能、次要流程变更不需要 LID；
• 创建 LID 需使用模板提交 PR（模板见 docs/sources/community/lids/template.md），且必须找到一位维护者作为 sponsor（发起人/担保人）——可以在 Loki 邮件列表发起主题为 "LID: " 前缀的讨论来寻找；
• LID 需要 sponsor 与另一位维护者共同批准才能被接受；提交后 sponsor 应等待至少 2 周再接受提案，以便社区充分反馈；
• 已接受的 LID 会被分配编号并永久归档，例如 0001-Introduction.md 介绍了 LID 机制的由来（参考了 Python 的 PEP 与 Kafka 的 KIP 思路）；
• LID 在提案被拒绝或对应改进随版本发布后视为完成。

六、新手如何快速起步？

社区对新手非常友好：首次贡献者可以优先寻找标记为 good first issue 的 issue 作为切入点，这些 issue 难度适中、适合熟悉项目流程。

综合本仓库 CONTRIBUTING.md 与 docs/sources/community/contributing.md 中的指引，建议的起步路径为：

1. 阅读 CODE_OF_CONDUCT.md 与 governance.md（了解项目治理规则与团队构成）；
2. 检查已开放的 issue 与 PR，避免重复劳动；
3. 本地克隆并构建：git clone 后执行 make loki（输出 ./cmd/loki/loki）或 make logcli（输出 ./cmd/logcli/logcli）；
4. 从 good first issue 开始提交你的第一个贡献。

七、还有疑问？如何联系 Loki 团队

除社区论坛与 Slack 之外，getting-in-touch.md 还列出了其他官方沟通渠道：

• 邮件列表：发送邮件至 [e-mail]，或访问 Google Groups 的 Loki 项目页（LID 提案的 sponsor 寻找也依赖该列表）；
• GitHub issue：Bug、问题与功能建议统一提交到 Loki 仓库的 issue 跟踪器（注意：Grafana UI 中 Loki 数据源插件的问题应提交到 Grafana 仓库，而非 Loki 仓库）；
• Loki Community Call（社区电话会）：每月第一个周四举行，欧美时区交替（EU 12:00 UTC / US 17:00 UTC），可在会议文档中订阅日历保持同步；
• Grafana Cloud / Enterprise 用户：可分别通过 Grafana.com 账户门户提交工单或联系 Grafana Labs 获取企业级支持。

小结

本文围绕 Loki 社区 FAQ 梳理了四类高频问题：许可证合规（AGPLv3 的边界与适用场景）、文档组织与版本识别（latest / next / 旧版本的区别与切换）、文档与代码贡献流程（issue、PR、LID 提案机制） 以及 社区沟通渠道。无论你是初次接触 Loki 的用户，还是准备提交首个 PR 的贡献者，掌握这些"元知识"都能让你在查阅资料、排查版本问题时少走弯路，更顺畅地融入 Loki 开源社区。