Ente 基础设施日志采集实战用 Promtail 将实例日志接入 Grafana Loki【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente本文以 Ente 仓库infra/services/promtail目录下的官方部署文档及配套的 systemd 单元文件、Promtail 配置为骨架完整讲解 Promtail 在 Ente 托管基础设施中的定位、安装流程与配置原理。读完本文你将掌握在任意运行着需要监控的服务的实例上通过 systemd Docker 方式部署 Promtail、改写client.url与scrape_configs、并把日志送入 GrafanaLoki的完整实操方案。一、Promtail 在 Ente 基础设施中的角色Ente 仓库的 infra/README.md 明确指出infra目录承载的是运营 Ente 托管基础设施所需的附加服务与工具这些服务并非运行或自托管 Ente 本身所必需。换句话说Promtail 属于团队内部运维栈的一部分与 Grafana、Prometheus、Sentry、Metabase 等并列。其中日志观测链路的分工是Grafana日志与指标的可视化前端数据存放在名为grafana-storage的 Docker 持久卷中见 infra/services/grafana/README.mdPromtail负责在目标实例上采集日志并推送到 LokiGrafana 的日志存储后端。官方 README 用一句话定义了 Promtail 的部署条件Installpromtail.serviceon an instance if it is running something whose logs we want in Grafana.即只要某个实例上运行着我们希望其日志出现在 Grafana 中的服务就在该实例上安装 promtail 服务。这也是判断是否需要部署 Promtail 的唯一标准。二、部署文件组成infra/services/promtail/目录下共三个文件构成了完整的可部署单元文件作用README.md安装说明文档promtail.servicesystemd 单元文件负责拉起并守护 Promtail 的 Docker 容器promtail.yamlPromtail 采集配置Loki 推送地址与各日志源的 scrape 任务安装的核心思路是把这两个文件分别放置到系统路径下配置放/root/promtail.yaml单元文件放/etc/systemd/system/promtail.service随后交给 systemd 管理。三、完整安装步骤按 README 的流程安装分两步先传文件并改配置再让 systemd 接管服务。3.1 传输文件并修改配置scp services/promtail/promtail.* instance: nano promtail.yaml sudo mv promtail.yaml /root/promtail.yaml sudo mv promtail.service /etc/systemd/system/promtail.service三个动作各司其职scp把promtail.service与promtail.yaml两个文件拷贝到目标实例的用户主目录nano promtail.yaml要求你手工替换client.url——即把配置中 Loki 地址改为 Promtail 应当连接的那个 Loki URL这是 README 明确强调的唯一必改项详见下文配置解析两个sudo mv把文件放到约定位置配置在/root/promtail.yamlsystemd 单元在/etc/systemd/system/promtail.service。路径与单元文件中的挂载点一一对应不能随意更换。3.2 让 systemd 接管服务sudo systemctl daemon-reload sudo systemctl enable --now promtaildaemon-reload让 systemd 重新读取新放入的服务定义文件enable --now promtail同时完成开机自启enable与立即启动now两个动作避免分两步操作。四、systemd 单元文件剖析promtail.service 完整内容如下[Unit] Documentationhttps://grafana.com/docs/loki/latest/clients/promtail/ Requiresdocker.service Afterdocker.service [Install] WantedBymulti-user.target [Service] ExecStartPredocker pull grafana/promtail ExecStartPre-docker stop promtail ExecStartPre-docker rm promtail ExecStartdocker run --name promtail \ --hostname %H \ -v /root/promtail.yaml:/config.yaml:ro \ -v /var/log:/var/log \ -v /root/var/logs:/var/logs:ro \ -v /var/lib/docker/containers:/var/lib/docker/containers:ro \ grafana/promtail -config.file/config.yaml -config.expand-envtrue几个值得注意的实现细节依赖 DockerRequiresdocker.serviceAfterdocker.service声明 Promtail 容器依赖 Docker 守护进程保证启动顺序正确启动前自愈ExecStartPre依次执行docker pull grafana/promtail拉取最新镜像、docker stop promtail与docker rm promtail。后两条命令前缀的-表示即使执行失败也不阻断服务启动——首次安装时容器不存在stop/rm 失败是预期行为这是幂等部署的典型写法四个挂载点各有用途/root/promtail.yaml:/config.yaml:ro把宿主机上改好的配置以只读方式注入容器容器内以/config.yaml路径使用/var/log:/var/log暴露系统日志目录可写用于按需采集/root/var/logs:/var/logs:ro暴露 Ente 各服务的自写日志目录只读这正是promtail.yaml中__path__: /var/logs/*.log的宿主机来源/var/lib/docker/containers:/var/lib/docker/containers:ro暴露 Docker 容器日志目录只读用于采集所有容器的 JSON 日志--hostname %H把容器主机名设为 systemd 单元所在机器的宿主机名%H是 systemd specifier为后续host标签提供来源-config.expand-envtrue开启 Promtail 配置中的环境变量展开使得promtail.yaml里的${HOSTNAME}得以被替换为真实主机名。五、Promtail 配置深度解析promtail.yaml 完整内容如下server: disable: true clients: - url: http://loki:3100/loki/api/v1/push # Manually add entries for all our services. This is a bit cumbersome, but # - Retains flexibility in file names. # - Makes adding job labels easy. # - Does not get in the way of logrotation. scrape_configs: - job_name: museum static_configs: - labels: job: museum host: ${HOSTNAME} __path__: /var/logs/museum.log - job_name: copycat-db static_configs: - labels: job: copycat-db host: ${HOSTNAME} __path__: /var/logs/copycat-db.log - job_name: phoenix static_configs: - labels: job: phoenix host: ${HOSTNAME} __path__: /var/logs/phoenix.log - job_name: docker static_configs: - labels: job: docker host: ${HOSTNAME} __path__: /var/lib/docker/containers/*/*-json.log5.1 server 与 clientsserver.disable: true关闭 Promtail 自带的 HTTP 服务它本身不对外暴露端口纯采集推送角色clients[0].urlLoki 的推送端点即 README 要求替换的那一项。默认值http://loki:3100/loki/api/v1/push是典型的 Docker 网络内主机名写法实际部署时应改为目标环境真实可达的 Loki 地址。5.2 scrape_configs 的设计哲学配置中注释明确解释了为什么采用手工逐个添加日志源而不是用 glob 通配一把抓保留文件名的灵活性不同服务日志文件名各异添加 job 标签非常容易每个 job 直接对应一个job标签不会干扰 logrotate 轮转固定路径采集避免通配导致重复读取或误读轮转中的文件。5.3 四个预置采集任务job_name采集路径日志内容museum/var/logs/museum.log照片服务后端 museum 的运行日志copycat-db/var/logs/copycat-db.log数据库备份服务日志phoenix/var/logs/phoenix.log备份可恢复性验证服务日志docker/var/lib/docker/containers/*/*-json.log实例上所有 Docker 容器的标准 JSON 日志前三个任务共用相同的模式host标签通过${HOSTNAME}取自环境变量依赖单元文件中的-config.expand-envtruejob标签固定为服务名__path__指向/var/logs/下对应的.log文件——该目录在单元文件里以只读卷挂载进容器。第四个docker任务则直接采集 Docker 守护进程落盘的*-json.log容器日志文件。5.4 环境变量展开的工程意义一个值得对比的细节Prometheus 的 READMEinfra/services/prometheus/README.md特意提醒Prometheus 目前不支持配置文件中的环境变量因此除了添加remote_write配置外还要记得修改硬编码的XX-HOSTNAME而 Promtail 通过-config.expand-envtrue原生支持${HOSTNAME}展开。这意味着同一份promtail.yaml可以不加修改地部署到多台实例host标签会自动区分日志来源——这正是该设计要解决的问题。六、如何为某个服务接入日志采集将一个新服务的日志纳入 Grafana在 Ente 的运维模式中只需三步确保服务把日志写入/root/var/logs/下的固定文件。以数据库备份服务 copycat-db 为例其 READMEinfra/copycat-db/README.md明确写到服务将日志写到标准输出与标准错误systemd 单元把这些输出重定向到/root/var/logs/copycat-db.log并提示本地查看sudo tail /root/var/logs/copycat-db.log日志同样会出现在 Grafana 上——后者正是经由 Promtail 的copycat-db采集任务实现的在promtail.yaml的scrape_configs中按既有模式新增一个 job指定job_name、job/host标签与__path__重启 Promtail 使配置生效sudo systemctl restart promtail。新任务沿用host: ${HOSTNAME}的写法即可自动带上实例标识在 Grafana 中按实例 服务两个维度过滤日志。七、运维与注意事项小结配置改动后必须重启Promtail 不会热加载配置文件修改promtail.yaml后需sudo systemctl restart promtail只读挂载防误改配置、/var/logs、Docker 容器日志三处以:ro只读挂载容器内无法意外篡改数据源幂等部署ExecStartPre中的 stop/rm 配合-容错前缀使重复执行安装/重启都安全采集范围与 logrotate 兼容固定文件路径的手工任务设计避免了通配采集在日志轮转时产生的重复或丢失问题适用范围Promtail 属于 infra 托管运维栈仅服务于 Ente 官方托管基础设施的日志观测自托管 Ente 时并不需要部署它。通过这套 systemd Docker 包装的 Promtail 方案Ente 团队实现了在任意实例上两三条命令即可接入日志观测体系的标准化流程也为需要自建 Grafana Loki 日志栈的开发者提供了一个简洁、可复用的参考模板。【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/12 16:22:49 · 阅读 1.2k Ente 基础设施日志采集实战：用 Promtail 将实例日志接入 Grafana Loki
Ente 基础设施日志采集实战用 Promtail 将实例日志接入 Grafana Loki【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente本文以 Ente 仓库infra/services/promtail目录下的官方部署文档及配套的 systemd 单元文件、Promtail 配置为骨架完整讲解 Promtail 在 Ente 托管基础设施中的定位、安装流程与配置原理。读完本文你将掌握在任意运行着需要监控的服务的实例上通过 systemd Docker 方式部署 Promtail、改写client.url与scrape_configs、并把日志送入 GrafanaLoki的完整实操方案。一、Promtail 在 Ente 基础设施中的角色Ente 仓库的 infra/README.md 明确指出infra目录承载的是运营 Ente 托管基础设施所需的附加服务与工具这些服务并非运行或自托管 Ente 本身所必需。换句话说Promtail 属于团队内部运维栈的一部分与 Grafana、Prometheus、Sentry、Metabase 等并列。其中日志观测链路的分工是Grafana日志与指标的可视化前端数据存放在名为grafana-storage的 Docker 持久卷中见 infra/services/grafana/README.mdPromtail负责在目标实例上采集日志并推送到 LokiGrafana 的日志存储后端。官方 README 用一句话定义了 Promtail 的部署条件Installpromtail.serviceon an instance if it is running something whose logs we want in Grafana.即只要某个实例上运行着我们希望其日志出现在 Grafana 中的服务就在该实例上安装 promtail 服务。这也是判断是否需要部署 Promtail 的唯一标准。二、部署文件组成infra/services/promtail/目录下共三个文件构成了完整的可部署单元文件作用README.md安装说明文档promtail.servicesystemd 单元文件负责拉起并守护 Promtail 的 Docker 容器promtail.yamlPromtail 采集配置Loki 推送地址与各日志源的 scrape 任务安装的核心思路是把这两个文件分别放置到系统路径下配置放/root/promtail.yaml单元文件放/etc/systemd/system/promtail.service随后交给 systemd 管理。三、完整安装步骤按 README 的流程安装分两步先传文件并改配置再让 systemd 接管服务。3.1 传输文件并修改配置scp services/promtail/promtail.* instance: nano promtail.yaml sudo mv promtail.yaml /root/promtail.yaml sudo mv promtail.service /etc/systemd/system/promtail.service三个动作各司其职scp把promtail.service与promtail.yaml两个文件拷贝到目标实例的用户主目录nano promtail.yaml要求你手工替换client.url——即把配置中 Loki 地址改为 Promtail 应当连接的那个 Loki URL这是 README 明确强调的唯一必改项详见下文配置解析两个sudo mv把文件放到约定位置配置在/root/promtail.yamlsystemd 单元在/etc/systemd/system/promtail.service。路径与单元文件中的挂载点一一对应不能随意更换。3.2 让 systemd 接管服务sudo systemctl daemon-reload sudo systemctl enable --now promtaildaemon-reload让 systemd 重新读取新放入的服务定义文件enable --now promtail同时完成开机自启enable与立即启动now两个动作避免分两步操作。四、systemd 单元文件剖析promtail.service 完整内容如下[Unit] Documentationhttps://grafana.com/docs/loki/latest/clients/promtail/ Requiresdocker.service Afterdocker.service [Install] WantedBymulti-user.target [Service] ExecStartPredocker pull grafana/promtail ExecStartPre-docker stop promtail ExecStartPre-docker rm promtail ExecStartdocker run --name promtail \ --hostname %H \ -v /root/promtail.yaml:/config.yaml:ro \ -v /var/log:/var/log \ -v /root/var/logs:/var/logs:ro \ -v /var/lib/docker/containers:/var/lib/docker/containers:ro \ grafana/promtail -config.file/config.yaml -config.expand-envtrue几个值得注意的实现细节依赖 DockerRequiresdocker.serviceAfterdocker.service声明 Promtail 容器依赖 Docker 守护进程保证启动顺序正确启动前自愈ExecStartPre依次执行docker pull grafana/promtail拉取最新镜像、docker stop promtail与docker rm promtail。后两条命令前缀的-表示即使执行失败也不阻断服务启动——首次安装时容器不存在stop/rm 失败是预期行为这是幂等部署的典型写法四个挂载点各有用途/root/promtail.yaml:/config.yaml:ro把宿主机上改好的配置以只读方式注入容器容器内以/config.yaml路径使用/var/log:/var/log暴露系统日志目录可写用于按需采集/root/var/logs:/var/logs:ro暴露 Ente 各服务的自写日志目录只读这正是promtail.yaml中__path__: /var/logs/*.log的宿主机来源/var/lib/docker/containers:/var/lib/docker/containers:ro暴露 Docker 容器日志目录只读用于采集所有容器的 JSON 日志--hostname %H把容器主机名设为 systemd 单元所在机器的宿主机名%H是 systemd specifier为后续host标签提供来源-config.expand-envtrue开启 Promtail 配置中的环境变量展开使得promtail.yaml里的${HOSTNAME}得以被替换为真实主机名。五、Promtail 配置深度解析promtail.yaml 完整内容如下server: disable: true clients: - url: http://loki:3100/loki/api/v1/push # Manually add entries for all our services. This is a bit cumbersome, but # - Retains flexibility in file names. # - Makes adding job labels easy. # - Does not get in the way of logrotation. scrape_configs: - job_name: museum static_configs: - labels: job: museum host: ${HOSTNAME} __path__: /var/logs/museum.log - job_name: copycat-db static_configs: - labels: job: copycat-db host: ${HOSTNAME} __path__: /var/logs/copycat-db.log - job_name: phoenix static_configs: - labels: job: phoenix host: ${HOSTNAME} __path__: /var/logs/phoenix.log - job_name: docker static_configs: - labels: job: docker host: ${HOSTNAME} __path__: /var/lib/docker/containers/*/*-json.log5.1 server 与 clientsserver.disable: true关闭 Promtail 自带的 HTTP 服务它本身不对外暴露端口纯采集推送角色clients[0].urlLoki 的推送端点即 README 要求替换的那一项。默认值http://loki:3100/loki/api/v1/push是典型的 Docker 网络内主机名写法实际部署时应改为目标环境真实可达的 Loki 地址。5.2 scrape_configs 的设计哲学配置中注释明确解释了为什么采用手工逐个添加日志源而不是用 glob 通配一把抓保留文件名的灵活性不同服务日志文件名各异添加 job 标签非常容易每个 job 直接对应一个job标签不会干扰 logrotate 轮转固定路径采集避免通配导致重复读取或误读轮转中的文件。5.3 四个预置采集任务job_name采集路径日志内容museum/var/logs/museum.log照片服务后端 museum 的运行日志copycat-db/var/logs/copycat-db.log数据库备份服务日志phoenix/var/logs/phoenix.log备份可恢复性验证服务日志docker/var/lib/docker/containers/*/*-json.log实例上所有 Docker 容器的标准 JSON 日志前三个任务共用相同的模式host标签通过${HOSTNAME}取自环境变量依赖单元文件中的-config.expand-envtruejob标签固定为服务名__path__指向/var/logs/下对应的.log文件——该目录在单元文件里以只读卷挂载进容器。第四个docker任务则直接采集 Docker 守护进程落盘的*-json.log容器日志文件。5.4 环境变量展开的工程意义一个值得对比的细节Prometheus 的 READMEinfra/services/prometheus/README.md特意提醒Prometheus 目前不支持配置文件中的环境变量因此除了添加remote_write配置外还要记得修改硬编码的XX-HOSTNAME而 Promtail 通过-config.expand-envtrue原生支持${HOSTNAME}展开。这意味着同一份promtail.yaml可以不加修改地部署到多台实例host标签会自动区分日志来源——这正是该设计要解决的问题。六、如何为某个服务接入日志采集将一个新服务的日志纳入 Grafana在 Ente 的运维模式中只需三步确保服务把日志写入/root/var/logs/下的固定文件。以数据库备份服务 copycat-db 为例其 READMEinfra/copycat-db/README.md明确写到服务将日志写到标准输出与标准错误systemd 单元把这些输出重定向到/root/var/logs/copycat-db.log并提示本地查看sudo tail /root/var/logs/copycat-db.log日志同样会出现在 Grafana 上——后者正是经由 Promtail 的copycat-db采集任务实现的在promtail.yaml的scrape_configs中按既有模式新增一个 job指定job_name、job/host标签与__path__重启 Promtail 使配置生效sudo systemctl restart promtail。新任务沿用host: ${HOSTNAME}的写法即可自动带上实例标识在 Grafana 中按实例 服务两个维度过滤日志。七、运维与注意事项小结配置改动后必须重启Promtail 不会热加载配置文件修改promtail.yaml后需sudo systemctl restart promtail只读挂载防误改配置、/var/logs、Docker 容器日志三处以:ro只读挂载容器内无法意外篡改数据源幂等部署ExecStartPre中的 stop/rm 配合-容错前缀使重复执行安装/重启都安全采集范围与 logrotate 兼容固定文件路径的手工任务设计避免了通配采集在日志轮转时产生的重复或丢失问题适用范围Promtail 属于 infra 托管运维栈仅服务于 Ente 官方托管基础设施的日志观测自托管 Ente 时并不需要部署它。通过这套 systemd Docker 包装的 Promtail 方案Ente 团队实现了在任意实例上两三条命令即可接入日志观测体系的标准化流程也为需要自建 Grafana Loki 日志栈的开发者提供了一个简洁、可复用的参考模板。【免费下载链接】ente End-to-end encrypted cloud for everything.项目地址: https://gitcode.com/GitHub_Trending/en/ente创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考