positions 文件记录什么
Promtail 用 positions 文件记录每个被采集文件的读取位置（字节偏移），是“重启后从哪里继续”的依据。丢失或损坏会导致历史日志被重新推送一遍，多实例共用同一文件则会互相覆盖造成漏采与重复。容器与 Kubernetes 部署时，把它放在持久卷上是基本要求。
基本信息
| 默认位置 | /var/lib/promtail/positions.yaml，可按部署调整 |
|---|---|
| 内容结构 | 文件路径到字节偏移的映射 |
| 写入时机 | 随采集进度周期性更新，退出前落盘 |
| 部署要求 | 放持久卷，单实例独占，不跨副本共享 |
关键点
关键点
# 配置位置
positions:
filename: /var/lib/promtail/positions.yaml
# 查看当前偏移（YAML 结构，值是字节偏移）
head /var/lib/promtail/positions.yaml
# Kubernetes：DaemonSet 用 hostPath 或专用 volume，升级时保留常见问题
| 现象 | 原因 | 处理 |
|---|---|---|
| 重启后重复推送 | positions 丢失或路径变化 | 确认持久卷挂载与文件路径 |
| 日志漏采 | 两实例共用同一文件互相覆盖 | 改为每个实例独立文件 |
| 偏移停在旧位置 | 写入权限不足或磁盘满 | 检查权限与可用空间 |
| 老文件重复出现 | 文件被 truncate 后偏移失效 | 评估轮转方式与重建策略 |
使用注意
- 容器重建时保留 positions 所在目录，避免全量重采
- 升级或迁移前备份 positions 文件，出问题可快速恢复读取位置
- 紧急恢复时可以直接删文件重读，但要评估重复量对存储的冲击
- 轮转方式与采集器配合要好，truncate 类轮转会让偏移失去意义
两个 promtail 进程共用一个 positions 文件会互相覆盖，出现漏采或重复；Kubernetes 里每个副本必须使用独立文件。
运维要点
- 升级前备份 positions 文件，回滚时可恢复到原来的读取位置
- 只读方式检查文件内容，避免编辑器写坏 YAML 结构
- 采集路径匹配规则要保持稳定，路径变更会让旧偏移全部失效
- 确认位置文件所在目录可写，写不进去会让偏移停在旧位置并造成重复采集