1. Grafana 图片渲染这件事为什么值得单独拎出来讲Grafana 用久了的人都会走到同一个路口仪表盘在浏览器里看着挺舒服但只要想把这个画面搬出去问题就来了。告警通知里想带一张走势图报告里想嵌一张资源曲线再或者定期把某个面板快照推到群里你会发现 Grafana 自己并不会截图它需要一个专门的组件把面板画成图片这个组件就是image renderer。默认情况下 Grafana 是不带这个能力的所以很多人第一次配告警带图收到的通知里只有一行干巴巴的文字图片位置是个占位符或者干脆报错。我接触过的场景里需要图片渲染的诉求大致分三类。第一类是告警联动希望值班的人在收到通知的第一时间就看到曲线的样子而不是点开链接再等页面加载。第二类是周期性报告运营或者管理层每周要看一份汇总图需要把若干面板渲成 PNG 拼进文档。第三类偏运维自证把关键指标快照留档用于事后回溯某个时间点系统长什么样。这三类需求都指向同一个技术动作把 Grafana 的面板变成一张静态图片。这里有个容易混淆的点需要提前说清楚。Grafana 渲染面板走的是无头浏览器那套逻辑它会真的把页面渲染一遍再截屏而不是像某些工具那样用绘图库直接画。这意味着渲染器本身要能跑起一个浏览器内核对系统依赖、字体、内存的要求都比想象中高。也正因为如此官方后来推荐的做法是把渲染器拆成独立服务而不是让它挤在 Grafana 主进程里。你把这条路理顺一次后面无论是告警带图还是报告导出基本都是一路平趟。这篇内容我会按从要不要装装哪种怎么装怎么调怎么排错的顺序走一遍中间会把我踩过的坑和参数计算过程都摊开讲。适合已经跑起 Grafana、正在被图片渲染折腾的运维和 SRE也适合刚接触prometheus grafana这套组合、想在告警通知里加点视觉信息的新手。整个思路不依赖具体云厂商Docker 环境就能完整复现。2. 渲染方案怎么选本地模式还是远程服务模式2.1 本地渲染模式的真实门槛Grafana 的图片渲染有两种形态一种是把渲染器当插件塞进 Grafana 进程里跑也就是本地渲染另一种是把渲染器单独部署成一个服务Grafana 通过 HTTP 调它也就是远程渲染。早些年本地模式是默认推荐因为部署简单加个插件重启就完事。但实际跑下来你会发现它的坑不少。本地模式要求 Grafana 所在的机器上具备完整的浏览器运行环境。渲染器底层依赖一个无头 Chromium这个内核在启动时要加载一堆共享库缺一个就直接崩。我见过最典型的情况是用官方基础镜像跑 Grafana一开本地渲染就报缺少某些.so文件你得自己往镜像里补依赖。而且这个浏览器进程会常驻在 Grafana 进程内占内存、抢 CPUGrafana 本身又是个对延迟敏感的服务两者挤在一起面板加载变慢是常有的事。更麻烦的是扩容。Grafana 做多副本时每个副本都得装一遍渲染环境镜像体积膨胀启动变慢版本升级时还得保证渲染器和 Grafana 版本匹配稍有不一致就渲染失败。所以除非你就是单机玩耍、图省事否则本地模式我一般不推荐上生产。提示本地渲染不是不能用但它更适合临时验证渲染链路是否通这种场景。验证完了就切远程别长期挂着。2.2 远程渲染服务为什么更省心远程渲染把渲染器从 Grafana 里剥出来做成一个独立的 HTTP 服务。Grafana 需要出图时发一个请求过去渲染器自己起浏览器、画页面、返回图片二进制。这个拆分带来几个实打实的好处。资源隔离是最明显的。渲染这件事很吃内存一个复杂的面板加上长周期数据渲染进程吃掉几百兆甚至上 G 内存都有可能。拆出去之后你可以给渲染服务单独设内存上限它崩了也不影响 Grafana 主服务。扩容也简单渲染压力大就多起几个渲染实例前面挂个负载均衡Grafana 这边只认一个地址横向扩展对上层透明。版本管理也清爽了。渲染服务是独立镜像升级它不影响 GrafanaGrafana 升级也不用管渲染器。两边通过一个约定好的接口通信耦合度低了很多。我现在手上所有环境都是远程模式一个渲染服务对应多个 Grafana 实例复用资源利用率比每个实例配一套渲染环境高得多。代价是多了一个部署对象要维护它的生命周期、监控它的存活。但这点运维成本比起本地模式带来的排障痛苦完全划算。所以下面的实操部分我默认按远程服务模式来写。3. 远程渲染服务的完整部署实操3.1 拉取镜像与启动参数逐条解释远程渲染器官方有现成镜像直接拉就行。启动的时候有几个参数必须给足否则跑起来也是半残。下面这条命令是我在生产里用的模板docker run -d \ --name grafana-image-renderer \ --restartalways \ -p 8081:8081 \ -e ENABLE_METRICStrue \ -e RENDERING_MODEdefault \ -e RENDERING_CLUSTER_MODEfalse \ -e RENDERING_ARGS--no-sandbox,--disable-gpu \ -e RENDERING_TIMEOUT60 \ -e RENDERING_DUMPIOfalse \ --shm-size1g \ --memory2g \ grafana/grafana-image-renderer:latest逐条说下我为什么这么配。--restartalways是保命用的渲染器偶尔会因为某个畸形面板请求把自己搞挂自动重启能省不少半夜被叫醒的次数。RENDERING_ARGS里的--no-sandbox在容器内基本是必须的容器里跑 Chromium 沙箱经常起不来--disable-gpu是因为服务器通常没有 GPU不禁掉反而会报错。--shm-size1g这条容易被忽略但极其关键。Chromium 默认用/dev/shm做共享内存容器默认只给 64M渲染稍大一点的图就会崩报错信息还很隐晦。给它 1G 之后我这边基本没再出现过渲染中途挂掉的情况。RENDERING_TIMEOUT设 60 秒给复杂面板留足画图时间默认值偏短遇到数据点多的图容易超时。3.2 Grafana 主服务的对接配置渲染服务起来了得让 Grafana 知道去哪找它。最干净的方式是通过环境变量配置改完重启 Grafana 生效GF_RENDERING_SERVER_URLhttp://renderer-host:8081/render GF_RENDERING_CALLBACK_URLhttp://grafana-host:3000/第一行告诉 Grafana 渲染服务在哪注意路径是/render不是根路径写错了会一直 404。第二行是回调地址渲染器需要反过来访问 Grafana 拿面板数据所以这个地址必须是渲染服务能访问到的 Grafana 地址。这里有个高频坑如果你用容器部署grafana-host不能写localhost因为在渲染服务的网络命名空间里localhost指的是它自己。要么用容器名要么用宿主机可达的 IP。注意RENDERING_CALLBACK_URL填错是图片渲染失败排查里排第一的原因。表现为 Grafana 日志里提示渲染超时或连接被拒但渲染服务日志里能看到它确实在尝试访问一个不存在的主机。配置完去 Grafana 里找个面板点右上角 Share选 Render image 试一下。能出图说明链路通了出不来就按后面的排查章节走。3.3 中文乱码与字体问题处理默认镜像里只带了少量西文字体如果你的面板标题、图例、注释里有中文渲染出来的图会是一堆方框。这个坑几乎每个中文用户都会踩一次而且很多人一开始以为是编码问题绕远路。根子在于渲染器所在的系统缺中文字体。解决办法是往渲染服务里挂载中文字体或者基于官方镜像在构建阶段把字体文件拷进去。最省事的做法是挂载宿主机字体目录-v /usr/share/fonts:/usr/share/fonts:ro \ -v /usr/share/fonts/truetype/custom:/usr/share/fonts/truetype/custom:ro把常用的中文字体文件比如思源黑体、文泉驿这类开源字体放到宿主机的某个目录然后挂进容器。挂载后要让渲染器重新加载字体缓存重启容器即可。如果你不想动宿主机也可以自己写个简单的 Dockerfile把字体文件COPY进去再fc-cache -f一下。字体挂载后还出现乱码就要检查字体权限和缓存。fc-list命令能列出系统当前认到的字体如果中文字体没出现在列表里说明挂载路径不对或者缓存没刷新。这一步走通了后面不管是告警带图还是报告导出中文都能正常显示一劳永逸。4. 关键参数与性能调优4.1 超时、并发与渲染模式的选择渲染服务的性能参数里超时是第一个要调对的。RENDERING_TIMEOUT控制单个渲染请求的最长等待官方默认值是 30 秒这个值对大面板来说太紧。一个宽 2000 像素、横跨 30 天、包含多条曲线的面板渲染耗时跑到 40 秒以上很常见。我一般设成 60如果面板特别复杂可以到 90。但别无限往上加超时设太大意味着一个卡住的请求会长时间占用渲染进程反而拖垮整体吞吐。并发方面默认一个渲染服务实例同时只处理有限数量的请求。如果你的告警很密集比如一次波动触发几十条告警每条都要出图渲染服务就成了瓶颈请求排队后面的全部超时。这时候有两个方向一个是多起几个渲染实例前面做负载均衡另一个是给渲染服务配置集群模式让它内部管理多个渲染 worker。RENDERING_CLUSTER_MODE和相关的 worker 数量参数就是干这个的。我在实际扩容时算过一笔账单实例大约能稳定处理 3 到 4 个并发渲染再高就出现明显排队。假如你的峰值是每分钟 20 张图那至少要有 5 到 6 个并发能力也就是两到三个实例冗余配置。这个数字根据面板复杂度浮动建议先压测再定别拍脑袋。参数建议值作用RENDERING_TIMEOUT60 秒单次渲染最长等待RENDERING_ARGS--no-sandbox,--disable-gpu容器内浏览器启动参数RENDERING_CLUSTER_MODE高并发时开启内部多 worker 管理--shm-size1g 起共享内存防渲染中途崩溃--memory2g 起容器内存上限4.2 内存限制与资源隔离的取舍给渲染容器设内存上限这件事很多人纠结设多少。设太小渲染大图时进程被 OOM 杀掉设太大又失去隔离的意义。我的经验是普通面板 1G 够用复杂面板和报告批量渲染场景给到 2G 比较稳妥。这个值不是拍出来的你可以先不设上限跑一段时间用docker stats观察峰值内存然后在上限上留 30% 的余量。要注意的是渲染器内部可能起多个进程浏览器主进程加若干渲染子进程内存限制是针对整个容器 cgroup 的所以你看到的总内存是所有子进程之和。如果设的--memory比实际峰值低太多容器会直接被杀日志里出现 OOM 相关提示。这种崩溃和你前面遇到的shm不足导致崩溃现象相似但根因不同排查时要区分开。心得内存上限别贴着实测峰值设。渲染负载是有波动的告警风暴时并发上来了内存也会跟着涨。留出余量比事后救火便宜。4.3 出图质量与画布尺寸的控制渲染出来的图清晰不清晰取决于面板请求时带的尺寸参数。Grafana 在发起渲染时会指定图片宽度、高度和缩放比这些值可以调。宽度给大一点图里的小字才看得清但宽度越大渲染耗时和内存占用也跟着涨是个权衡。默认渲染出来的图有时候会偏小字挤在一起。我的做法是在告警通知模板里显式指定一个较大的宽度比如 1000 到 1200 像素高度用 500 左右长宽比跟原面板接近这样出来的图既不拉伸变形细节也够看。如果你需要更精细的图可以调高缩放比让渲染器以更高分辨率画再缩下来反而更清晰。但要注意缩放比翻倍渲染耗时基本也翻倍别在告警场景里过度追求清晰度那会拖慢通知速度。还有个细节是主题。渲染出来的图是深色还是浅色跟面板主题设置有关。告警通知如果发到即时通讯工具里深色图在某些客户端上看着费劲可以固定用浅色主题渲染。这个可以通过渲染请求参数控制也可以在通知模板里统一指定保持所有告警图风格一致看起来很专业。5. 告警通知与报告里的渲染落地5.1 告警通知带图的配置要点图片渲染链路通了之后接下来就是把它用到告警里。Grafana 的告警通知支持嵌入面板截图配置的时候需要开启通知渠道的图片选项并且在通知模板里引用渲染出来的图片。这一步的核心是保证告警触发时渲染服务是可用的而且有足够的时间把图渲出来再发出去。我遇到过的情况是告警很密集的时候通知里的图偶尔缺失。查下来是渲染排队导致超时通知等不及就直接发了不带图的版本。解决办法一个是前面说的扩容渲染服务另一个是给告警通知里的图片渲染单独设一个合理的超时并且允许失败时降级为纯文本通知而不是整个通知发不出去。注意告警通知和报告导出共享同一个渲染服务时报告任务往往是大批量渲染会瞬间占满渲染容量把告警图片挤掉。有条件的话报告渲染和告警渲染分到不同实例或者错开时间执行。5.2 报告导出与定时快照的实践除了告警另一个高频用图场景是周期性报告。Grafana 支持按计划生成报告把指定面板渲染成图并发送。这里最容易出问题的地方是时间范围。报告通常是每周或每月一份面板要展示对应周期内的数据如果时间范围没对齐导出的图可能是空数据或者错位的。我的做法是在报告定义里显式指定时间范围用相对时间表达式比如上一周、上一个自然月而不是用面板的默认范围。这样不管报告什么时候跑图里的都是正确周期。另外报告里面板数量别堆太多一个报告几十张图渲染时间会很长而且报告体积也大接收方未必愿意看。精选几个关键面板就够了。定时快照还有个小用途就是留档。把核心指标面板每天固定时间渲染一张存下来用于事后回溯。这类任务对时效性要求低可以放到凌晨低峰期跑避开白天告警密集的时段既省渲染资源又不影响告警时效。6. 常见报错与排查实录6.1 典型报错速查表图片渲染的报错信息往往不直观我把这些年遇到的高频问题整理成一张表方便对照定位。现象可能原因排查方向通知里图片位置空白渲染超时或服务不可达查渲染服务存活与回调地址渲染日志大量 404渲染地址路径写错确认是否带/render中文显示成方框缺中文字体挂载字体并刷新缓存渲染中途崩溃无日志共享内存不足加大--shm-size容器被杀内存超限 OOM调整--memory上限提示连接回调主机失败回调地址不可达改成渲染服务可达地址偶发图片缺失并发排队导致超时扩容渲染实例这张表覆盖了我九成以上的排障场景。用的时候从现象反推比从头捋配置链路快得多。6.2 排查思路与几个独家避坑排渲染问题有个固定套路先在 Grafana 里手动点一次 Render image看报什么错。手动都能出图说明链路是通的问题出在告警或报告那层的调用参数上手动出不了图就顺着 Grafana 到渲染服务这条线往下查。Grafana 的日志里会记录它请求渲染服务的地址和返回状态渲染服务的日志里会记录它收到请求后干了什么、有没有访问回调地址、渲染耗时多少。两边日志对着看问题基本无处遁形。一个我踩过的坑是网络策略。渲染服务和 Grafana 之间的双向访问都要通很多人只保证了 Grafana 能访问渲染服务忘了渲染服务也要能反过来访问 Grafana 拉数据。有些环境有防火墙或网络策略限制单向通了以为万事大吉结果渲染器拿不到数据画出空白图。部署完第一件事就是从渲染服务容器里curl一下 Grafana 的回调地址能通再往下走。另一个是版本匹配。渲染服务镜像和 Grafana 版本之间虽然接口比较稳定但跨大版本时还是建议对齐一下。特别是 Grafana 升级后如果渲染突然出现奇怪的报错先怀疑渲染服务版本升一下往往就好了。还有告警里引用的面板如果被删了或改了 ID渲染会失败这种问题在面板调整频繁的环境里很常见排查时留意一下告警规则指向的面板是否还存在。最后分享一个我经手优化过的细节渲染服务的日志级别可以调高默认级别信息不够出问题时看不到细节。临时把日志级别调成 debug能直接看到浏览器渲染过程中的具体报错定位完再调回去。这个操作对排查疑难杂症特别有用比盲猜高效太多。整套链路理顺之后图片渲染其实是个很稳的组件配好一次后面基本可以放着不管。