企业官网建设流程全解析

监控面板这东西，很多时候不是数据量不够，而是展示方式不够直观。我之前在团队里负责搭建云上服务的监控大屏，最头疼的就是几十个服务的运行状态没法在一屏里看清。每个服务单独拉一张图表，翻好几页才能定位到异常节点。后来把 Grafana 的 Polystat 面板和腾讯云可观测平台的数据链路打通，一个面板就能同时展示所有服务的健康状态，并按阈值自动变色。这篇文章会把整套方案的链路设计、PromQL 写法、Polystat 参数调整、以及我实际踩过的坑都整理出来，适合正在做云上监控大屏、又不想维护一堆单值面板的同学参考。

提示：本文不包含任何平台内部的敏感配置细节，所有地址和密钥均以变量占位，请根据你实际的环境替换。

1. 方案概览：这套实践到底在解决什么问题

1.1 从“每服务一张图”到“一张图看全部”

先说说我最初的问题。团队里有几十个微服务和云资源实例，每个实例都有 CPU、内存、延迟、错误率这类指标。之前用的方案是 Grafana 默认的 Stat 面板，一个服务配一个 Panel，整个 Dashboard 排成长龙。这会带来三个问题：页面加载慢、值班同学找不到异常目标、同类指标没法横向对比。Polystat 这种磁贴式面板能把这些指标缩成一个瓦片，每个瓦片显示一个服务或实例的当前状态，颜色代表健康度，整体看下来就像一张“服务健康地图”。

Polystat 的展示模式是网格瓦片。如果一个查询返回多个时间序列，面板默认会按每个序列生成一个瓦片。瓦片上的文字和背景都可以通过阈值控制。这正好满足“多对象状态总览”的需求，比 Stat 面板的信息密度高很多，也比 Status History 面板更适合当前状态快照场景。

1.2 链路里每一环都负责什么

整个数据链路可以理解为三步。

第一步是采集。云上的数据库、负载均衡、容器服务等资源，都会通过可观测平台提供的采集规则把指标收到托管 Prometheus 实例里。第二步是暴露，平台会给 Prometheus 实例一个 HTTP API 地址，Grafana 用这个地址配置数据源。第三步是展示，在 Grafana 中安装 Polystat 插件，用 PromQL 查询指标，查询结果被瓦片化展示。

这套链路的价值在于，Grafana 只负责“看”，可观测平台负责“采”。指标采集范围、存储时长、告警规则都在云平台侧维护，Grafana 侧的配置量很小。后期如果新增监控对象，只需要在采集规则里加目标，面板里的 PromQL 会自动带上新序列。

1.3 为什么不用云平台自带控制台

有人可能觉得，云厂商控制台里本来就有资源监控页，为什么还要绕一圈到 Grafana。我的体会有几点。

第一，控制台的视角是“单个云产品”，而团队要的是“跨产品、跨地域的业务视角”。比如我想同时看数据库和服务器的状态，控制台没有这种聚合视图。第二，Grafana 的模板变量、下钻链接、权限管理更灵活，可以把运维经验沉淀成团队共用的 Dashboard。第三，如果公司还有其他自建系统或开源组件，指标也能进同一个 Grafana，避免多个控制台来回切换。

2. 动手前的准备：插件、数据源和指标规划

2.1 安装 Polystat 插件

Polystat 不是 Grafana 内置的，需要额外安装社区插件。在 Grafana 所在的服务器上执行安装命令，命令的大致形式如下：

grafana-cli plugins install satellogic-polystat-panel

装完以后需要重启 Grafana 服务才会在可视化列表中看到 Polystat。重启方式取决于你的部署形态，systemd 托管的执行systemctl restart grafana-server，容器部署的重启容器。我之前有一次装完没重启就在面板列表里找，找了半天没找到，所以这个细节值得提前记下来。

要注意版本兼容。Grafana 大版本升级后，插件没有跟着升级会有兼容性问题，典型症状是面板显示不出来，或者浏览器控制台报一堆Unknown panel。遇到这种情况，先到插件仓库确认插件支持哪个 Grafana 版本范围，再决定是否升级插件。

2.2 配置云侧 Prometheus 数据源

接下来需要把可观测平台的 Prometheus 数据源加到 Grafana。在云平台控制台里找到 Prometheus 监控实例，实例详情一般会显示访问地址和访问凭证。我建议在同一个私有网络内使用内网地址，延迟更低也更安全。

在 Grafana 中操作流程如下：

1. 左侧选择 Connections，然后点 Data sources；
2. 点击 Add data source，类型选 Prometheus；
3. URL 填平台提供的 HTTP API 地址；
4. 鉴权方式按平台文档选择，常见的是 Basic Auth 或 Token；
5. 点击 Save & Test，确认返回“Successfully queried”。

保存后先在 Explore 页面验证一下。输入一个有代表性的指标名，比如up，如果能看到时间序列列表，说明数据链路已经通了。这个时候再进 Panel 配置，遇到的问题会更少。

2.3 指标规划：先统一标签，再谈展示

很多人在面板配置阶段才纠结“用哪个指标”，我觉得指标规划应该在配置面板前就完成。

首先要确定每个瓦片代表什么。我的一般做法是一个瓦片代表一个服务实例或一个资源实例，所以在指标标签里要有能唯一确定实例的字段，比如instance_id、app、env。同时所有指标最好都带一组公共标签，比如region、service，方便后面做分组和过滤。

其次要确定“绿色代表什么”。核心语义要提前对齐。比如 CPU 使用率是越高越危险，健康度是越高越好。Polystat 的阈值颜色是作用于查询结果的数值，所以你需要把 PromQL 的输出设计成“越大越健康”或“越小越健康”的单一方向。否则配置阈值时很容易把颜色写反。

最后一件事，尽量让一个查询输出一个 0 到 100 的可比较数值。用几个具体例子：

# 查看某个数据库实例的 CPU 使用率，值越高越危险 avg_over_time(cloud_metric_database_cpu_utilization{instance_id="$instance"}[5m]) # 把错误率转换成健康度，值越高越健康 100 - avg_over_time(http_requests_total{code=~"5.."}[5m]) * 100

第一个查询适合配置“低绿色、高红色”，第二个查询要配置“高绿色、低红色”。把方向搞反是配置面板时最常见的问题。

3. Polystat 面板核心配置与实操记录

3.1 添加面板的基本流程

当数据源和指标都准备好后，添加面板的流程很快。新建一个 Dashboard，点 Add Panel，然后在可视化类型里搜索 Polystat 选中。

面板最重要的输入是 Queries 区域。在这里写 PromQL，Polystat 的展示逻辑完全依赖查询结果。以一个简单场景为例，我想展示三个应用的状态，查询返回三个序列：

avg_over_time(service_status{env="production"}[5m])

如果查询结果里有三个不同的service标签值，Polystat 会给每个序列生成一个瓦片。这个阶段可以先不管样式，把 PromQL 写对，确认瓦片数量和预期一致再继续调样式。

我习惯先把legendFormat设置成包含标签的格式，比如{{service}}，这样在排查查询结果时能快速确认哪个瓦片对应哪个服务。这个字段不直接影响 Polystat 的展示，但能帮你调试，尤其是多个查询混在一起的时候。

3.2 阈值和颜色到底怎么配

Polystat 的配置项看起来不少，核心其实就是两块：显示内容、颜色规则。

颜色规则中有一个容易混淆点，面板里有两处跟阈值相关的配置：一处是 Thresholds 用于定义数值对应的状态区间，另一处是 Color when 用于指定对数值上色还是对背景上色。最常用的组合是 Thresholds 定义区间，Color when 选 Value。

举个例子，对于“值越大越健康”的健康度指标：

• 0 到 60：红色，严重不健康
• 60 到 85：黄色，需要关注
• 85 到 100：绿色，正常

在 Polystat 的 Color Thresholds 里按顺序添加：

同时要把显示单位设置为 percent，关闭小数位或保留一位，这样画面更干净。

如果配置完颜色没生效，检查顺序是：先看 Color when 是不是 Value，再看 Thresholds 区间有没有重叠，最后确认 PromQL 返回的数值是否真的落在区间内。大部分“不生效”问题都出在前两个。

3.3 用标签聚合实现多粒度视图

默认情况下一个查询返回几个序列，面板就生成几个瓦片。但在真实场景里，我们经常想要不同粒度的视图，比如先看地域级别，再看服务级别。Polystat 支持通过标签聚合把多个序列合并到一个瓦片。

假设查询返回的序列带region和service两个标签，我可以在 Composite 配置里选择按region聚合。相同region的序列会合并显示在一个瓦片里，瓦片内部可以同时展示多个服务的状态。这样大屏先展现地域容灾总览，点击某个地域再进入服务明细。

具体如何配取决于你的 Grafana 版本里插件提供的选项。一般会在面板的 Options 区域找到类似 Composite grouping 的设置项，在里面填入标签名即可。如果配置后瓦片没有按预期合并，可以检查指标里是否真的有这个标签，用 Explore 查询结果确认。

3.4 面板性能和布局的经验

Polystat 网格瓦片本身不复杂，但大屏场景下查询频率高很容易让 Grafana 变卡。我建议在 Dashboard 顶层设置一个$interval变量，查询里统一加[$interval]代替写死的时间范围，并限制最短时间间隔（比如1m）。这样既能降低指标存储侧的查询压力，也能让瓦片的刷新频率保持在合理范围。

布局方面，让瓦片尽量撑满屏幕宽度，关闭不必要的图例和边框。Display 选项里我只保留value和name，背景色已经表达了状态，不需要再叠加 sparkline。如果服务数量特别多，可以考虑用翻页或滚动容器，避免单个 Dashboard 加载一堆序列导致的白屏。

3.5 一个可以直接抄作业的 Panel JSON 示例

下面是我常用的一组面板 JSON 配置片段，已经脱敏。你可以把它贴进 Dashboard JSON 的 panels 数组里，再根据自己的指标名修改。

{ "datasource": { "type": "prometheus", "uid": "your-datasource-uid" }, "type": "satellogic-polystat", "title": "线上服务健康总览", "targets": [ { "refId": "A", "expr": "100 - avg_over_time(service_error_ratio{env=\"prod\"}[$interval]) * 100", "legendFormat": "{{service}}" } ], "options": { "display": "name,value", "colorMode": "value", "fontSize": "12", "sparkline": false, "thresholds": [ { "index": 0, "value": 60, "color": "rgba(230, 0, 0, 1)" }, { "index": 1, "value": 85, "color": "rgba(230, 153, 0, 1)" }, { "index": 2, "value": 100, "color": "rgba(0, 230, 0, 1)" } ], "unit": "percent" } }

注意实际插件的字段名可能因版本略有不同，配置时以界面上的实时渲染为准。这段 JSON 的目的是给你一个起点，而不是直接粘贴就能万事大吉。首次配置时可以先新建面板，再切到 Dashboard JSON 里看面板实际生成的配置结构，对比字段含义，理解会透彻很多。

4. 实施过程中踩过的坑和排查思路

4.1 阈值颜色不生效

这是我被问得最多的问题。现象是 PromQL 查询出来的值已经超过红色阈值，但瓦片依然是绿色。

排查第一步，确认 Color when 选的是 Value 还是 Background。如果选了 Background，上色的逻辑会作用在背景上，数值上的颜色可能不是你预期看到的。第二步，确认 Thresholds 里的区间顺序是否正确，尤其是有重叠区间时，插件通常取命中值靠前的规则。第三步，打开面板编辑界面，看右上角的即时渲染，慢慢调整区间数值，找到真正触发变色的边界值。

我还遇到过一种情况，查询返回的数值是字符串而不是数字，比如某些指标在无数据时返回NaN。Polystat 对非数字的处理是保持默认颜色，所以看起来就是“阈值不生效”。这时候需要回查询里用coalesce或者last_over_time把空值兜底成 0，保证瓦片始终有数字可展示。

4.2 面板只有空白网格没有数值

空白网格一般有两种原因。第一种是查询结果确实没有值，可能是指标名写错，或者时间范围内没有数据。用 Explore 验证 PromQL，把时间范围拉到和 Dashboard 一样，看看到底有没有序列返回。

第二种原因是 Grafana 的模板变量为空。比如我在 PromQL 里用了$instance，但 Dashboard 的变量没有默认值，渲染出来的查询会变成空字符串，导致没有匹配项。处理方法是给模板变量都配置 All 选项和默认值，并确认 All 对应的 regex 写法不会影响查询。

还有一种偏门情况：Grafana 版本升级后插件列表里还能看到 Polystat，但渲染器已经不支持了，浏览器控制台会报错。这种情况直接重新安装匹配版本的插件就能解决。

4.3 多个查询和多个序列搞混

当面板里有多个目标时，Polystat 不是把所有查询合并成一个瓦片，而是默认一个序列一个瓦片。如果你的本意是“所有服务的 CPU 使用率放一个瓦片”，那只需要一个查询返回多序列即可。如果你的本意是“一个服务有 CPU、内存、延迟多个指标合成一个瓦片”，那要用复合瓦片或把多个指标通过运算符聚合成一条 PromQL。

这里我建议通过legendFormat给每个序列起名字，确认序列和瓦片是一一对应还是聚合关系。如果发现瓦片数量比预期多，往往是因为查询里没有过滤掉无关标签，比如把不同环境的数据都查出来了。在 PromQL 里用{}限定env、region等公共标签，是控制瓦片数量最直接的手段。

4.4 数据源连接和网络隔离问题

自建 Grafana 接云上 Prometheus 时，最容易踩的坑是网络不通。托管实例默认只在内网可达，如果你把 Grafana 部署在了另一套网络环境，需要先确认平台是否提供公网访问入口，或者通过安全组白名单放通 Grafana 的出口 IP。输入地址时不要带多余的协议和路径，直接填平台给的完整 API 地址即可。

鉴权失败则表现为 Save & Test 报 401 或 403。这时候检查是不是把 Token 填写到了用户名字段，有些平台要求把 Token 放在 Basic Auth 的密码位置，用户名留空。甚至可以先用命令行的curl直接请求一次 API 地址，用返回结果判断是网络问题还是鉴权问题，再做针对性修改。

4.5 常见问题速查表

这张表基本覆盖了我从搭建到上线遇到的大部分问题。如果还有新的问题，多数会落在 PromQL 查询逻辑上，建议把问题查询逐步简化，先查常量，再加过滤条件，定位出是哪一段让 Polystat 渲染异常。

这套方案我从搭建到现在用了快一年，最大的体会是把工作重心放在“指标模型”而不是“面板样式”。Polystat 的配置本身没有多少可以钻研的地方，真正决定面板好不好用的是指标命名是否统一、标签是否规范、健康度阈值和业务语义是否对齐。如果一开始就把这些理顺，后面加服务、加地域都只是往采集规则里加目标而已。

最后分享一个我一直在用的小技巧：给每个瓦片配置面板链接，点击服务瓦片可以跳转到该服务对应的详情 Dashboard。这样大屏用于总览，点击下钻用于排查，值班同学不用再记着一串服务名去翻其他页面。如果你正在搭同类监控视图，我建议先小范围跑通两三个服务，确认显示效果后，再逐步扩展到全量资源，这样排查起来成本最低。