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——同机部署应使用https://loki:3100/loki/api/v1/push（Docker 网络内的服务名），跨主机则填写目标 IP。不能依赖 DNS 或容器别名。
复杂之处在于 Promtail 自身的日志输出不走 journalctl，排查问题需要进入容器执行 curl -s https://localhost:9080/targets | grep promtail_targets_active，如果返回值为 0，说明根本没有发现日志文件——此时需要回头检查路径、权限、__path__ 的 glob 写法。
