Traefik Log Dashboard故障排查指南Agent离线、日志不显示、Token不匹配常见问题快速定位解决【免费下载链接】traefik-log-dashboardA real-time dashboard for analyzing Traefik logs in UI with IP geolocation, status code analysis, and service metrics. Built with React (Shadcn UI) and Node.js.项目地址: https://gitcode.com/gh_mirrors/tr/traefik-log-dashboardTraefik Log Dashboard 是一款实时分析Traefik 反向代理日志的可视化监控面板内置 IP 地理定位、状态码分析和系统指标监控。本文面向新手帮你快速定位Agent 离线、日志不显示、Token 不匹配三大高频故障并提供 Docker 权限、容器重启等问题的修复方法。先花30秒理解架构排查顺序为何重要在动手排查前先明白这套Traefik 日志监控面板由两部分组成Agent一个轻量 Go 服务默认端口5000负责读取并解析 Traefik 日志通过 REST API 提供数据DashboardWeb 前端 Node.js 服务默认端口3000负责从 Agent 拉取数据并渲染图表 记住这个链路Traefik 日志文件 → Agent → Dashboard任何一环断了页面都会表现为没有数据。完整的环境变量清单见 docs/content/docs/configuration/environment-variables.mdx故障排查官方文档见 docs/content/docs/troubleshooting.mdx。Agent 离线排查步骤按顺序执行 4 步这是Traefik 日志面板最常见的故障页面通常显示 Agent Offline。第1步确认 Agent 容器正在运行docker ps | grep traefik-agent如果没有输出说明 Agent 根本没启动先执行docker compose up -d拉起服务。第2步用健康检查接口验证 Agent 状态直接访问 Agent 的状态接口对应源码 agent/internal/routes/status_handler.go它能告诉你日志路径是否有效curl http://localhost:5000/api/logs/status返回access_path_exists: false就说明日志路径配置错了——这正是日志不显示最常见的根源。第3步Token 不匹配两端密钥必须完全一致Agent 使用 Bearer Token 鉴权两端必须配置相同的值组件环境变量AgentTRAEFIK_LOG_DASHBOARD_AUTH_TOKENDashboardAGENT_API_TOKEN或新版AGENT_1_TOKEN排查技巧两个值只要有一个字符不同多余空格、换行就会认证失败。修改后务必重启两个容器再验证。第4步检查 Docker 网络连通性Dashboard 需要能直连 Agent 的 HTTP 地址。确认两个容器在同一个 Docker 网络中且AGENT_API_URL用的是服务名如http://traefik-agent:5000而不是localhost。日志不显示的 3 个原因与修复方法当 Agent 在线但面板空白时按以下顺序检查日志路径不对确认TRAEFIK_LOG_DASHBOARD_ACCESS_PATH指向真实存在的文件docker exec traefik-agent ls -la /logs/日志格式不匹配TRAEFIK_LOG_DASHBOARD_LOG_FORMAT需与你的 Traefik 实际输出一致json或common。格式选错时 Agent 能启动但解析不出任何条目。文件读权限不足Agent 需要对日志文件有只读权限。挂载时建议加:ro前缀并确保宿主机文件属主允许容器用户读取。数据异常指标不对 / 地理位置空白日志有但指标统计错误默认展示的是近期数据先在页面上调整时间范围怀疑重复读取或漏读时删除 Agent 容器内的/data/.position位置文件让 Agent 从头重新解析地理地图不显示数据Dashboard 的 GeoIP 采用本地 MMDB 优先 HTTP 服务商兜底的混合链路排查顺序调用curl http://localhost:3000/api/location/status确认enabledtrue且至少一个 provider 的availabletrue内网 IP 无法定位如果请求都来自内网地图必然为空点击页头的Internal Hidden开关可显示内部流量服务商被限流HTTP 403时可挂一个本地 MaxMind 库并设置GEOIP_LOCAL_DB_PATHDocker 容器故障快速修复数据卷 Permission deniedDashboard 容器默认以用户1001:1001运行宿主机目录需提前授权mkdir -p ./data/dashboard chown -R 1001:1001 ./data/dashboard容器反复重启查看两边日志即可锁定原因参考 docker-compose.yml 中的健康检查配置docker logs traefik-log-dashboard docker logs traefik-log-dashboard-agent三大常见原因缺少必填环境变量、日志路径无效、数据库文件权限错误。常见问题速查清单症状优先检查关键变量/接口Agent 离线容器运行 Token 一致性TRAEFIK_LOG_DASHBOARD_AUTH_TOKENAGENT_API_TOKEN日志不显示日志路径与格式TRAEFIK_LOG_DASHBOARD_ACCESS_PATH、/api/logs/status指标统计错误时间范围 位置文件删除/data/.position重读地图空白GeoIP 链路 内网 IP/api/location/status权限报错数据卷属主chown -R 1001:1001环境 Agent 无法删除属设计如此保护主连接改环境变量后重启容器按容器是否在跑 → 接口是否通 → 配置是否对的顺序逐步排查绝大多数Traefik 日志监控面板故障都能在 5 分钟内定位。遇到本文未覆盖的问题可查阅项目内置文档 docs/content/docs/troubleshooting.mdx 获取更详细的英文排错说明。【免费下载链接】traefik-log-dashboardA real-time dashboard for analyzing Traefik logs in UI with IP geolocation, status code analysis, and service metrics. Built with React (Shadcn UI) and Node.js.项目地址: https://gitcode.com/gh_mirrors/tr/traefik-log-dashboard创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考