Loki + Grafana + Promtail 日志查看

单机 Docker 日志栈：按项目采集、按级别筛选、网页检索。当前仓库仅保留改进版配置。

组件	作用
Promtail	采集宿主机日志文件，推送到 Loki
Loki	存储与检索（含 Compactor，保留策略真正生效）
Grafana	Web UI（已自动配置 Loki 数据源）

---

github 地址：https://github.com/438083791/log-search/blob/master/loki-log/

一、目录结构

loki-log/
├── docker-compose.yml          # 本机 Windows 开发用
├── loki-config.yaml
├── promtail-config.yaml
├── grafana/provisioning/...
├── .env / .env.example

---

二、部署前必改：Windows / Linux 路径

只改宿主机路径（冒号左边），容器内路径（右边）不要改。

1. docker-compose.yml → promtail.volumes

多项目公共根目录（约定：宿主机日志根/<项目名>/*.log）：

系统	宿主机示例	容器内（勿改）
Windows	D:/app/logs	/host/logs
Linux	/opt/app/logs	/host/logs

单项目示例 codoc-ai-service（日志文件直接在目录下）：

系统	宿主机示例	容器内（勿改）
Windows	E:/work/log	/host/codoc
Linux	/opt/log	/host/codoc

配置文件中已用注释标出两套写法：启用当前系统的那一行，注释掉另一行。

2. promtail-config.yaml

__path__ 全部是容器内路径，与上面挂载的右边一致，一般 Win/Linux 相同，无需按系统改写。

新增“日志直接在某目录下”的项目时：

1. 在 docker-compose.yml 增加一条 volume（写好 Win/Linux 注释）
2. 在 promtail-config.yaml 复制 codoc-ai-service 那段 job，改 job_name / project / __path__
3. docker compose up -d --force-recreate promtail

3. 其余文件

文件	是否按 OS 修改
loki-config.yaml	否（容器内路径）
Grafana provisioning	否
.env	改密码即可，与 OS 无关

4. Windows 额外注意

• Docker Desktop → Settings → Resources → File sharing：放行日志所在盘符（如 D:、E:）
• 挂载写法用正斜杠：D:/app/logs，不要用 D:\app\logs

---

三、启动与访问

cd loki-log
cp .env.example .env   # 首次：编辑密码
docker compose --env-file .env up -d

服务	地址
Grafana	http://服务器IP:3000
Loki API	http://服务器IP:3100

账号密码见 .env（GF_SECURITY_ADMIN_USER / GF_SECURITY_ADMIN_PASSWORD）。
数据源已自动配置，无需在 UI 里再手工添加 Loki。

查看状态：

docker compose ps
docker logs loki --tail 50
docker logs promtail --tail 50

---

四、Grafana 查日志

1. 左侧 Explore → 数据源选 Loki
2. Label filters 常用：
   • project：项目名（如 demo1、codoc-ai-service）
   • level：ERROR / INFO / DEBUG / WARN …
   • filename：指定某个日志文件
3. 也可用 LogQL，例如：

{project="codoc-ai-service", level="ERROR"}
{project="codoc-ai-service", filename="/host/codoc-ai-service/api_2026-07-10.log"}
{project="codoc-ai-service"} |= "timeout"

4. 右上角可开自动刷新；新写入日志一般数秒内可见。

主题：左下角头像 → Profile → Theme；默认已设浅色（GF_USERS_DEFAULT_THEME=light）。

---

五、常用运维

改挂载路径 / 新增项目后

docker compose --env-file .env up -d --force-recreate promtail

改日志保留时长

编辑 loki-config.yaml 中 limits_config.retention_period（如 168h = 7 天），然后：

docker compose restart loki

须已启用 Compactor（当前配置已开启），否则保留不会真正删数据。

停止 / 清空

docker compose down      # 停服务，保留 volume
docker compose down -v  # 连同 Loki/Grafana 数据一并删除（谨慎）

---

六、Linux 部署检查清单

1. 安装 Docker + Docker Compose 插件
2. 把本目录拷到服务器（如 /opt/loki-log）
3. 改 docker-compose.yml：注释 Windows 挂载，启用 Linux 挂载，路径改成实际日志目录
4. cp .env.example .env 并设置强密码
5. 确认宿主机日志目录存在且 Docker 可读
6. docker compose --env-file .env up -d
7. 防火墙放行 3000（建议仅内网或前面加反向代理 + HTTPS）
8. 浏览器打开 Grafana → Explore → 确认有 project 标签

---

七、能力与局限

优点： 一键 Docker、比 ELK 轻、按项目/级别/文件筛选、近实时 tail。
局限： 超大规模 TB 检索、复杂聚合弱于 ES/ClickHouse；适合查阅与关键词搜索。

---

八、配置要点（改进版相对旧方案）

• Loki 开启 Compactor，retention_period 真正生效
• Grafana Provisioning 自动数据源
• Promtail：子目录自动 project；正文提取 level；positions 落 volume
• healthcheck + depends_on，避免 Loki 未就绪就起依赖服务
• 密码走 .env，默认浅色主题