Linux下Grafana Loki部署配置完全教程

Docker Compose 是目前最省时、可控性最强的部署方案，能将进程隔离、网络互通与卷挂载全部固化在一个 YAML 文件里。相比之下，二进制安装步骤繁琐，约九成的失败案例都卡在权限、路径、配置加载顺序这类细节上。

你可能会问：既然二进制安装这么麻烦，为什么还要提它？因为很多初次部署的人正是被它带入了“坑”。手动处理 loki-linux-amd64 和 promtail-linux-amd64 的执行权限，写错 systemd 单元文件就会静默退出；/etc/loki/config.yaml 不会自动加载，必须显式传 --config.file；日志目录挂载权限不一致就会无声无息地丢日志。而 Docker Compose 把这些全固化在 YAML 里，改端口、换路径、加标签只需改动几行配置即可。

docker-compose.yml 的三处必改项

官方模板拿来就能用，但下面这三个地方若不调好，一定会出问题：

• Loki 的 volumes 映射：必须指向宿主机真实存在的路径，比如 ./loki-config/config.yaml:/etc/loki/local-config.yaml。路径不存在或权限不对，容器启动后立刻退出，docker logs loki 只会显示 failed to load config。
• Promtail 的日志目录映射：要真实存在且容器可以读取。例如 - /var/log:/var/log，如果宿主机 /var/log 的属主不是 root:adm，而容器默认以非 root 用户运行，就会跳过采集并且不报错。
• Grafana 的 GF_SECURITY_ADMIN_PASSWORD：必须显式设置，否则 v10+ 版本首次登录会卡死，在 UI 里也无法重设。

loki-local-config.yaml 的三个硬性配置点

Loki 启动失败，八成的锅都在这三个地方没对齐：

• server.http_listen_port：默认为 3100，如果宿主机端口已被占用（比如另一个 Loki 或 Nginx），必须同步修改 docker-compose.yml 的 ports 映射，例如 "3101:3100"。只改配置不改映射，Grafana 将无法连接。
• storage_config.filesystem.directory：必须是容器内绝对路径，如 /tmp/loki/chunks。如果指向 /opt/loki/chunks 却没有做 volumes 挂载，Loki 启动时会直接报 permission denied。
• limits_config.ingestion_rate_mb 和 ingestion_burst_size_mb：默认分别为 4 和 6，但 Nginx 或 Java 应用几秒内就可能触发限速，promtail 日志里反复出现 rate limited。建议按实际流量设置为 30 和 15。

promtail-config.yaml 的标签和路径最容易漏

Promtail 不是装上就能自动收日志，它依赖 static_configs.labels 来标记流标识，依赖 pipeline_stages 解析内容。漏掉任何一环，Grafana 就会查不到数据：

• labels：至少包含 job 和 host，例如 {job="system", host="${HOSTNAME}"}。如果留空 labels: {} 或全部注释掉，Loki 会直接丢弃该流。
• __path__：必须用双引号包裹，特别当包含变量或 glob 时："__path__: "/var/log/**/*.log"。使用单引号或不加引号会导致匹配失效。
• clients.url：不要写 localhost——同机部署应使用 http://loki:3100/loki/api/v1/push（Docker 网络内的服务名），跨主机则填写目标 IP。不能依赖 DNS 或容器别名。

复杂之处在于 Promtail 自身的日志输出不走 journalctl，排查问题需要进入容器执行 curl -s http://localhost:9080/targets | grep promtail_targets_active，如果返回值为 0，说明根本没有发现日志文件——此时需要回头检查路径、权限、__path__ 的 glob 写法。