第 1 章：Grafana 入门与核心概念

1.1 什么是 Grafana：可视化与监控平台简介

概念名称	说明	注意事项
Grafana	一个开源的度量分析和可视化套件，主要用于可视化时间序列数据，支持多种数据源。	Grafana 本身不存储数据，仅作为可视化和查询前端，需配合 Prometheus、InfluxDB 等后端使用。
时间序列数据	按时间顺序记录的数值序列，如 CPU 使用率、内存占用、请求延迟等。	Grafana 擅长处理时间序列数据，对非时间序列数据（如关系型数据）支持有限。
可视化	将数据以图表、仪表盘等形式展示，帮助用户快速理解系统状态和趋势。	支持丰富的可视化类型：折线图、柱状图、热力图、表格、单值显示等。
开源与社区版	Grafana 采用 AGPL-3.0 开源协议，社区版功能已非常强大。	企业版提供高级功能（如审计日志、SAML 认证），需付费使用。
插件生态	支持通过插件扩展功能，包括数据源、面板类型和应用插件。	插件需从官方或可信来源安装，避免安全风险。

1.2 Grafana 核心组件解析：数据源、仪表盘、面板

组件名称	说明	注意事项
数据源	Grafana 用于查询数据的后端系统，如 Prometheus、InfluxDB、MySQL、Elasticsearch 等。	每个仪表盘可配置一个或多个数据源；数据源配置错误将导致查询失败。
仪表盘	一组面板的集合，用于展示特定主题的监控信息，可组织为行和列。	仪表盘可导出为 JSON 文件，便于版本控制和跨环境部署。
面板	仪表盘中的基本可视化单元，如折线图、单值显示、表格等。	每个面板绑定一个或多个查询，支持自定义标题、单位、阈值、颜色等。
查询编辑器	用于编写数据查询语句的界面，语法依赖于所选数据源（如 PromQL、InfluxQL）。	查询性能影响仪表盘加载速度，应避免过于复杂的查询。
变量	用于实现仪表盘动态化，用户可通过下拉菜单选择不同实例、应用或时间范围。	变量可基于查询、常量或正则表达式定义，提升仪表盘复用性。

1.3 Grafana 架构概览：前端、后端、插件系统

架构模块	说明	注意事项
前端（UI）	基于 React 和 TypeScript 构建的 Web 界面，负责用户交互和数据展示。	用户通过浏览器访问前端，所有操作通过 API 与后端通信。
后端（Server）	Go 语言编写的服务器，处理 API 请求、认证、数据源代理、告警计算等。	后端不存储指标数据，仅存储仪表盘、用户、配置等元数据。
数据源代理	Grafana 后端作为代理，将前端查询请求转发至实际数据源（如 Prometheus）。	可配置代理以避免跨域问题，并集中管理数据源认证信息。
插件系统	支持运行时加载插件，扩展数据源、面板和应用功能。	插件运行在 Grafana 进程中，需确保其稳定性，避免影响主服务。
告警引擎	内置告警功能，支持基于查询结果触发告警，并通过邮件、Webhook 等方式通知。	告警规则在 Grafana 中定义，状态由后端定期评估。

1.4 常见使用场景：系统监控、应用性能、日志分析

使用场景	说明	注意事项
系统监控	监控服务器 CPU、内存、磁盘 I/O、网络流量等指标，通常结合 Node Exporter + Prometheus。	需确保 Exporter 正常运行并被 Prometheus 抓取。
应用性能监控（APM）	监控 Java 应用的 JVM 内存、GC 次数、HTTP 请求延迟、线程数等。	推荐使用 Micrometer + Prometheus + Grafana 实现。
日志分析	结合 Loki（Grafana Labs 开发的日志系统）或 Elasticsearch，实现日志查询与可视化。	日志需结构化（如 JSON 格式）以便高效查询。
业务指标监控	可视化业务关键指标（KPI），如订单量、支付成功率、用户活跃数等。	需将业务指标暴露为时间序列数据（如通过 Prometheus 或 StatsD）。
多数据源聚合	在同一仪表盘中展示来自不同系统的数据，如数据库慢查询 + 应用响应时间。	注意各数据源时间同步问题，避免图表时间轴错位。

第 2 章：Grafana 安装与基础配置

2.1 在 Linux/Windows 上安装 Grafana

安装方式	说明	注意事项
Linux - YUM (CentOS/RHEL)	使用系统包管理器安装，适用于 RHEL 系列系统。	需先配置 Grafana 官方 YUM 源；安装后服务名为 grafana-server。
Linux - APT (Ubuntu/Debian)	使用 APT 包管理器安装，适用于 Debian 系列系统。	需添加 Grafana GPG 密钥和 APT 源；安装命令为 apt-get install grafana。
Linux - 二进制包	下载 .tar.gz 包解压后直接运行，无需系统级安装。	适合测试或自定义部署；需手动管理启动和配置。
Windows	下载 .exe 安装程序或 .zip 解压包，在 Windows 上运行。	解压后可通过 grafana-server.exe 启动；配置文件位于 conf/ 目录。
Docker	使用官方镜像 grafana/grafana 运行容器。	推荐用于开发和测试；需挂载配置和数据卷以持久化数据。

2.2 启动、停止与服务配置

Linux systemd 操作命令：

操作命令	说明	注意事项
systemctl start grafana-server	启动 Grafana 服务	确保端口 3000 未被占用；首次启动可能较慢。
systemctl stop grafana-server	停止 Grafana 服务	停止前建议导出重要仪表盘。
systemctl restart grafana-server	重启 Grafana 服务	配置文件修改后需重启生效。
systemctl status grafana-server	查看服务状态和日志	可通过 journalctl -u grafana-server 查看详细日志。
systemctl enable grafana-server	设置开机自启	生产环境建议启用。

Windows 操作：

操作	说明	注意事项
grafana-server.exe	直接运行可启动 Grafana（前台）	关闭终端即停止服务。
安装为 Windows 服务	使用工具（如 NSSM）将 grafana-server.exe 安装为系统服务。	可实现开机自启和后台运行。

2.3 初始配置文件 grafana.ini 详解

配置项（节.键）	默认值	说明	注意事项
app_mode	production	运行模式：production 或 development	开发模式可能启用调试功能。
server.http_port	3000	HTTP 服务监听端口	可修改为其他端口（如 8080），需确保防火墙放行。
server.domain	localhost	服务器域名，用于生成绝对链接	若通过域名访问，应设置为实际域名。
server.root_url	%(protocol)s://%(domain)s:%(http_port)s/	应用根 URL，影响外部链接生成	配置反向代理时需正确设置。
security.admin_user	admin	初始管理员用户名	首次登录后建议修改。
security.admin_password	admin	初始管理员密码	强烈建议首次登录后修改为强密码。
security.allow_embedding	false	是否允许嵌入到 iframe 中	若需嵌入其他系统，需设为 true 并配置 CSP。
users.allow_sign_up	true	是否允许用户自助注册	生产环境建议设为 false，由管理员创建用户。
database.type	sqlite3	元数据存储类型：sqlite3, mysql, postgres	sqlite3 适合小规模部署；生产环境推荐 MySQL 或 PostgreSQL。
database.path	grafana.db	SQLite 数据库文件路径	需定期备份此文件以防数据丢失。

2.4 首次登录与管理员账户设置

操作步骤	说明	注意事项
访问 Grafana Web 界面	浏览器打开 http://<服务器IP>:3000	确保服务器防火墙开放 3000 端口。
登录初始账户	使用默认用户名 admin 和密码 admin 登录	登录后系统会强制要求修改密码。
修改管理员密码	进入”Configuration” → “Preferences” → “Change Password”	新密码需满足复杂度要求（通常至少 4 位）。
配置基本偏好	设置时区（建议 UTC 或本地时区）、语言、主页仪表盘等。	时区设置影响所有用户的时间显示。
创建新用户（可选）	进入”Server Admin” → “Users” → “New user”	可为团队成员创建独立账户，分配角色（Viewer、Editor、Admin）。
注销与重新登录	验证新密码和用户权限	建议使用新账户进行后续操作。

第 3 章：数据源配置与管理

3.1 添加 Prometheus 作为数据源

配置项	说明	注意事项
Name	数据源名称，用于在仪表盘中选择。	建议使用有意义的名称，如 Prometheus-Prod。
Type	选择 Prometheus	必须正确选择类型，否则查询将失败。
URL	Prometheus 服务器的访问地址，如 http://prometheus.example.com:9090	确保 Grafana 服务器能网络可达该地址；避免使用 localhost（容器部署时）。
Access	代理（Server）或直接（Browser）	生产环境必须使用 Server 模式，避免暴露 Prometheus 给前端浏览器。
Basic Auth	是否启用基础认证	若 Prometheus 配置了反向代理认证，需开启并填写用户名密码。
Custom HTTP Headers	自定义 HTTP 请求头	可用于传递认证 Token 等信息。
Scrape Interval	覆盖 Prometheus 默认的抓取间隔	通常留空使用 Prometheus 默认值。
Query Timeout	查询超时时间	根据网络状况调整，避免慢查询阻塞仪表盘。
HTTP Method	与 Prometheus 通信的 HTTP 方法（GET/POST）	大查询建议使用 POST。

3.2 添加 InfluxDB 作为数据源

配置项	说明	注意事项
Name	数据源名称，如 InfluxDB-Dev	便于在多个 InfluxDB 实例间区分。
Type	选择 InfluxDB	类型错误将导致无法使用 InfluxQL 或 Flux 查询。
URL	InfluxDB API 地址，如 http://influxdb.example.com:8086	确保端口正确（8086 为默认 API 端口）。
Version	InfluxDB 版本（1.x 或 2.x）	版本影响认证方式和查询语言（1.x 用 InfluxQL，2.x 用 Flux）。
Database	默认数据库名称（仅 InfluxDB 1.x）	2.x 使用 Organization 和 Bucket。
User & Password	数据库用户名和密码（1.x）	建议使用只读账号，遵循最小权限原则。
Token	InfluxDB 2.x 的访问 Token	需在 InfluxDB 中预先创建具有读取权限的 Token。
Organization	InfluxDB 2.x 的组织名称	必填项。
Default Bucket	InfluxDB 2.x 的默认存储桶	可选，用于简化查询。
Min time interval	最小查询时间间隔	避免过于频繁的查询，影响性能。

3.3 数据源测试与验证

验证步骤	说明	注意事项
Save & Test 按钮	配置完成后点击此按钮，Grafana 会尝试连接并验证数据源。	成功提示为 “Data source is working”；失败则显示错误详情（如连接超时、认证失败）。
查询示例数据	在数据源配置页或仪表盘中执行简单查询，如 Prometheus 的 up。	验证数据可正常返回，图表能渲染。
检查网络连通性	在 Grafana 服务器上使用 curl 或 telnet 测试到数据源的网络。	排除防火墙或 DNS 问题。
查看 Grafana 日志	若测试失败，查看 grafana.log 获取详细错误信息。	日志通常位于 /var/log/grafana/grafana.log。
验证查询性能	执行时间范围较长的查询，观察响应速度。	慢查询需优化数据源或索引。
权限验证	使用非管理员账户登录，验证其是否能正常查看该数据源数据。	确保权限配置正确，避免越权访问。

3.4 使用 Java 程序动态管理数据源（API）

本节内容将在第 6 章详细展开，此处仅作概念说明。

概念名称	说明	注意事项
Grafana HTTP API	提供 RESTful 接口用于管理数据源、仪表盘、用户等。	需先配置 API Key 或认证信息。
API Key	用于 API 认证的密钥，分为 Viewer、Editor、Admin 权限。	Admin 权限 API Key 可管理数据源，需妥善保管。
Java HTTP 客户端	如 OkHttp、Apache HttpClient，用于在 Java 中调用 HTTP API。	推荐使用 OkHttp，简洁高效。
JSON 请求体	创建/更新数据源时，需构造符合 API 规范的 JSON 数据。	参考官方 API 文档确保字段正确。
错误处理	处理 HTTP 状态码（如 401 未授权、409 冲突）。	实现重试机制和日志记录。

第 4 章：Grafana HTTP API 基础

4.1 API 认证机制：API Key 与 Basic Auth

认证方式	语法格式	用途说明	注意事项
API Key	Authorization: Bearer <API_KEY>	最常用，通过 API Key 进行请求认证。	API Key 在 Grafana UI 中创建，具有固定权限；过期或删除后立即失效。
Basic Auth	Authorization: Basic <base64(username:password)>	使用用户名密码进行认证。	可用于管理员账户，但密码硬编码有安全风险；建议仅用于脚本或 CI/CD。
服务账户 Token	Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>	Grafana 8+ 引入，更安全的自动化认证方式。	服务账户可精细控制权限，推荐用于程序化访问。

4.2 API 基础路径与请求结构

项目	说明	注意事项
基础 URL	http://:/api	默认端口为 3000；若配置了 root_url，需包含路径前缀。
请求头 Content-Type	application/json	所有发送 JSON 数据的请求必须包含此头。
响应格式	JSON	成功响应通常包含 id、message 等字段；错误响应包含 message 和状态码。
路径参数	如 /api/datasources/:id，:id 为数据源 ID	需替换为实际数值。
查询参数	如 ?name=MyDashboard，用于搜索或过滤。	URL 编码特殊字符。
请求体（Body）	POST/PUT 请求中包含 JSON 数据，如创建资源的配置。	结构必须符合 API 文档要求。

4.3 常用 HTTP 方法与状态码说明

HTTP 方法	用途说明	典型 API 路径示例	注意事项
GET	获取资源信息	/api/dashboards/uid/:uid	安全且幂等，可多次调用。
POST	创建新资源	/api/datasources	非幂等，重复调用可能创建多个资源。
PUT	更新现有资源（全量替换）	/api/dashboards/db	需提供完整资源对象。
PATCH	部分更新资源	/api/users/:id	仅更新指定字段。
DELETE	删除资源	/api/datasources/:id	删除操作通常不可逆，需谨慎。

状态码	说明	应对措施
200	请求成功，返回数据	正常处理响应体。
201	资源创建成功	通常在 POST 响应中返回。
400	请求错误（如 JSON 格式错误、参数缺失）	检查请求体和参数。
401	未授权（认证失败）	检查 API Key 或用户名密码。
403	禁止访问（权限不足）	确认 API Key 权限是否足够。
404	资源未找到	检查路径或资源 ID 是否正确。
409	冲突（如创建已存在的资源）	先查询是否存在，或使用更新操作。
500	服务器内部错误	检查 Grafana 服务状态和日志。

4.4 使用 Java 发起 HTTP 请求（OkHttp 示例）

方法/组件	语法/代码示例	用途说明	注意事项
OkHttpClient	private final OkHttpClient client = new OkHttpClient();	创建 HTTP 客户端实例，可复用。	建议作为单例使用。
Request.Builder	Request request = new Request.Builder()	构建 HTTP 请求。	链式调用设置方法、URL、头、体。
设置 URL	.url(“http://localhost:3000/api/datasources”)	指定请求地址。	确保 URL 正确，包含 /api 前缀。
设置 Header	.addHeader(“Authorization”, “Bearer <your_api_key>“)	添加认证头。	API Key 需替换为实际值。
设置 Body	.post(RequestBody.create(json, MediaType.get(“application/json”)))	为 POST/PUT 请求设置 JSON 体。	json 为 String 类型的 JSON 字符串。
execute()	Response response = client.newCall(request).execute();	同步执行请求。	适用于简单脚本；高并发场景建议用 enqueue() 异步调用。
Response	if (response.isSuccessful()) { String body = response.body().string(); }	处理响应。	body().string() 只能调用一次；及时关闭 Response 防止资源泄漏。
try-with-resources	try (Response response = client.newCall(request).execute()) { … }	自动关闭 Response 资源。	推荐写法，避免资源泄漏。
JSON 处理	使用 Jackson 或 Gson 库序列化/反序列化对象。	简化 JSON 构造和解析。	例如：ObjectMapper.writeValueAsString(dataSourceConfig)。

第 1 章：Grafana 入门与核心概念

1.1 什么是 Grafana：可视化与监控平台简介

概念名称	说明	注意事项
Grafana	一个开源的度量分析和可视化套件，主要用于可视化时间序列数据，支持多种数据源。	Grafana 本身不存储数据，仅作为可视化和查询前端，需配合 Prometheus、InfluxDB 等后端使用。
时间序列数据	按时间顺序记录的数值序列，如 CPU 使用率、内存占用、请求延迟等。	Grafana 擅长处理时间序列数据，对非时间序列数据（如关系型数据）支持有限。
可视化	将数据以图表、仪表盘等形式展示，帮助用户快速理解系统状态和趋势。	支持丰富的可视化类型：折线图、柱状图、热力图、表格、单值显示等。
开源与社区版	Grafana 采用 AGPL-3.0 开源协议，社区版功能已非常强大。	企业版提供高级功能（如审计日志、SAML 认证），需付费使用。
插件生态	支持通过插件扩展功能，包括数据源、面板类型和应用插件。	插件需从官方或可信来源安装，避免安全风险。

1.2 Grafana 核心组件解析：数据源、仪表盘、面板

组件名称	说明	注意事项
数据源	Grafana 用于查询数据的后端系统，如 Prometheus、InfluxDB、MySQL、Elasticsearch 等。	每个仪表盘可配置一个或多个数据源；数据源配置错误将导致查询失败。
仪表盘	一组面板的集合，用于展示特定主题的监控信息，可组织为行和列。	仪表盘可导出为 JSON 文件，便于版本控制和跨环境部署。
面板	仪表盘中的基本可视化单元，如折线图、单值显示、表格等。	每个面板绑定一个或多个查询，支持自定义标题、单位、阈值、颜色等。
查询编辑器	用于编写数据查询语句的界面，语法依赖于所选数据源（如 PromQL、InfluxQL）。	查询性能影响仪表盘加载速度，应避免过于复杂的查询。
变量	用于实现仪表盘动态化，用户可通过下拉菜单选择不同实例、应用或时间范围。	变量可基于查询、常量或正则表达式定义，提升仪表盘复用性。

1.3 Grafana 架构概览：前端、后端、插件系统

架构模块	说明	注意事项
前端（UI）	基于 React 和 TypeScript 构建的 Web 界面，负责用户交互和数据展示。	用户通过浏览器访问前端，所有操作通过 API 与后端通信。
后端（Server）	Go 语言编写的服务器，处理 API 请求、认证、数据源代理、告警计算等。	后端不存储指标数据，仅存储仪表盘、用户、配置等元数据。
数据源代理	Grafana 后端作为代理，将前端查询请求转发至实际数据源（如 Prometheus）。	可配置代理以避免跨域问题，并集中管理数据源认证信息。
插件系统	支持运行时加载插件，扩展数据源、面板和应用功能。	插件运行在 Grafana 进程中，需确保其稳定性，避免影响主服务。
告警引擎	内置告警功能，支持基于查询结果触发告警，并通过邮件、Webhook 等方式通知。	告警规则在 Grafana 中定义，状态由后端定期评估。

1.4 常见使用场景：系统监控、应用性能、日志分析

使用场景	说明	注意事项
系统监控	监控服务器 CPU、内存、磁盘 I/O、网络流量等指标，通常结合 Node Exporter + Prometheus。	需确保 Exporter 正常运行并被 Prometheus 抓取。
应用性能监控（APM）	监控 Java 应用的 JVM 内存、GC 次数、HTTP 请求延迟、线程数等。	推荐使用 Micrometer + Prometheus + Grafana 实现。
日志分析	结合 Loki（Grafana Labs 开发的日志系统）或 Elasticsearch，实现日志查询与可视化。	日志需结构化（如 JSON 格式）以便高效查询。
业务指标监控	可视化业务关键指标（KPI），如订单量、支付成功率、用户活跃数等。	需将业务指标暴露为时间序列数据（如通过 Prometheus 或 StatsD）。
多数据源聚合	在同一仪表盘中展示来自不同系统的数据，如数据库慢查询 + 应用响应时间。	注意各数据源时间同步问题，避免图表时间轴错位。

---

第 2 章：Grafana 安装与基础配置

2.1 在 Linux/Windows 上安装 Grafana

安装方式	说明	注意事项
Linux - YUM (CentOS/RHEL)	使用系统包管理器安装，适用于 RHEL 系列系统。	需先配置 Grafana 官方 YUM 源；安装后服务名为 grafana-server。
Linux - APT (Ubuntu/Debian)	使用 APT 包管理器安装，适用于 Debian 系列系统。	需添加 Grafana GPG 密钥和 APT 源；安装命令为 apt-get install grafana。
Linux - 二进制包	下载 .tar.gz 包解压后直接运行，无需系统级安装。	适合测试或自定义部署；需手动管理启动和配置。
Windows	下载 .exe 安装程序或 .zip 解压包，在 Windows 上运行。	解压后可通过 grafana-server.exe 启动；配置文件位于 conf/ 目录。
Docker	使用官方镜像 grafana/grafana 运行容器。	推荐用于开发和测试；需挂载配置和数据卷以持久化数据。

2.2 启动、停止与服务配置

操作命令（Linux systemd）	说明	注意事项
systemctl start grafana-server	启动 Grafana 服务	确保端口 3000 未被占用；首次启动可能较慢。
systemctl stop grafana-server	停止 Grafana 服务	停止前建议导出重要仪表盘。
systemctl restart grafana-server	重启 Grafana 服务	配置文件修改后需重启生效。
systemctl status grafana-server	查看服务状态和日志	可通过 journalctl -u grafana-server 查看详细日志。
systemctl enable grafana-server	设置开机自启	生产环境建议启用。

操作（Windows）	说明	注意事项
grafana-server.exe	直接运行可启动 Grafana（前台）	关闭终端即停止服务。
安装为 Windows 服务	使用工具（如 NSSM）将 grafana-server.exe 安装为系统服务。	可实现开机自启和后台运行。

2.3 初始配置文件 grafana.ini 详解

配置项（节.键）	默认值	说明	注意事项
app_mode	production	运行模式：production 或 development	开发模式可能启用调试功能。
server.http_port	3000	HTTP 服务监听端口	可修改为其他端口（如 8080），需确保防火墙放行。
server.domain	localhost	服务器域名，用于生成绝对链接	若通过域名访问，应设置为实际域名。
server.root_url	%(protocol)s://%(domain)s:%(http_port)s/	应用根 URL，影响外部链接生成	配置反向代理时需正确设置。
security.admin_user	admin	初始管理员用户名	首次登录后建议修改。
security.admin_password	admin	初始管理员密码	强烈建议首次登录后修改为强密码。
security.allow_embedding	false	是否允许嵌入到 iframe 中	若需嵌入其他系统，需设为 true 并配置 CSP。
users.allow_sign_up	true	是否允许用户自助注册	生产环境建议设为 false，由管理员创建用户。
database.type	sqlite3	元数据存储类型：sqlite3, mysql, postgres	sqlite3 适合小规模部署；生产环境推荐 MySQL 或 PostgreSQL。
database.path	grafana.db	SQLite 数据库文件路径	需定期备份此文件以防数据丢失。

2.4 首次登录与管理员账户设置

操作步骤	说明	注意事项
访问 Grafana Web 界面	浏览器打开 http://<服务器IP>:3000	确保服务器防火墙开放 3000 端口。
登录初始账户	使用默认用户名 admin 和密码 admin 登录	登录后系统会强制要求修改密码。
修改管理员密码	进入 “Configuration” → “Preferences” → “Change Password”	新密码需满足复杂度要求（通常至少 4 位）。
配置基本偏好	设置时区（建议 UTC 或本地时区）、语言、主页仪表盘等。	时区设置影响所有用户的时间显示。
创建新用户（可选）	进入 “Server Admin” → “Users” → “New user”	可为团队成员创建独立账户，分配角色（Viewer、Editor、Admin）。
注销与重新登录	验证新密码和用户权限	建议使用新账户进行后续操作。

---

第 3 章：数据源配置与管理

3.1 添加 Prometheus 作为数据源

配置项	说明	注意事项
Name	数据源名称，用于在仪表盘中选择。	建议使用有意义的名称，如 Prometheus-Prod。
Type	选择 Prometheus	必须正确选择类型，否则查询将失败。
URL	Prometheus 服务器的访问地址，如 http://prometheus.example.com:9090	确保 Grafana 服务器能网络可达该地址；避免使用 localhost（容器部署时）。
Access	代理（Server）或直接（Browser）	生产环境必须使用 Server 模式，避免暴露 Prometheus 给前端浏览器。
Basic Auth	是否启用基础认证	若 Prometheus 配置了反向代理认证，需开启并填写用户名密码。
Custom HTTP Headers	自定义 HTTP 请求头	可用于传递认证 Token 等信息。
Scrape Interval	覆盖 Prometheus 默认的抓取间隔	通常留空使用 Prometheus 默认值。
Query Timeout	查询超时时间	根据网络状况调整，避免慢查询阻塞仪表盘。
HTTP Method	与 Prometheus 通信的 HTTP 方法（GET/POST）	大查询建议使用 POST。

3.2 添加 InfluxDB 作为数据源

配置项	说明	注意事项
Name	数据源名称，如 InfluxDB-Dev	便于在多个 InfluxDB 实例间区分。
Type	选择 InfluxDB	类型错误将导致无法使用 InfluxQL 或 Flux 查询。
URL	InfluxDB API 地址，如 http://influxdb.example.com:8086	确保端口正确（8086 为默认 API 端口）。
Version	InfluxDB 版本（1.x 或 2.x）	版本影响认证方式和查询语言（1.x 用 InfluxQL，2.x 用 Flux）。
Database	默认数据库名称（仅 InfluxDB 1.x）	2.x 使用 Organization 和 Bucket。
User & Password	数据库用户名和密码（1.x）	建议使用只读账号，遵循最小权限原则。
Token	InfluxDB 2.x 的访问 Token	需在 InfluxDB 中预先创建具有读取权限的 Token。
Organization	InfluxDB 2.x 的组织名称	必填项。
Default Bucket	InfluxDB 2.x 的默认存储桶	可选，用于简化查询。
Min time interval	最小查询时间间隔	避免过于频繁的查询，影响性能。

3.3 数据源测试与验证

验证步骤	说明	注意事项
Save & Test 按钮	配置完成后点击此按钮，Grafana 会尝试连接并验证数据源。	成功提示为 “Data source is working”；失败则显示错误详情（如连接超时、认证失败）。
查询示例数据	在数据源配置页或仪表盘中执行简单查询，如 Prometheus 的 up。	验证数据可正常返回，图表能渲染。
检查网络连通性	在 Grafana 服务器上使用 curl 或 telnet 测试到数据源的网络。	排除防火墙或 DNS 问题。
查看 Grafana 日志	若测试失败，查看 grafana.log 获取详细错误信息。	日志通常位于 /var/log/grafana/grafana.log。
验证查询性能	执行时间范围较长的查询，观察响应速度。	慢查询需优化数据源或索引。
权限验证	使用非管理员账户登录，验证其是否能正常查看该数据源数据。	确保权限配置正确，避免越权访问。

3.4 使用 Java 程序动态管理数据源（API）

本节内容将在第 6 章详细展开，此处仅作概念说明。

概念名称	说明	注意事项
Grafana HTTP API	提供 RESTful 接口用于管理数据源、仪表盘、用户等。	需先配置 API Key 或认证信息。
API Key	用于 API 认证的密钥，分为 Viewer、Editor、Admin 权限。	Admin 权限 API Key 可管理数据源，需妥善保管。
Java HTTP 客户端	如 OkHttp、Apache HttpClient，用于在 Java 中调用 HTTP API。	推荐使用 OkHttp，简洁高效。
JSON 请求体	创建/更新数据源时，需构造符合 API 规范的 JSON 数据。	参考官方 API 文档确保字段正确。
错误处理	处理 HTTP 状态码（如 401 未授权、409 冲突）。	实现重试机制和日志记录。

---

第 4 章：Grafana HTTP API 基础

4.1 API 认证机制：API Key 与 Basic Auth

认证方式	语法格式	用途说明	注意事项
API Key	Authorization: Bearer <API_KEY>	最常用，通过 API Key 进行请求认证。	API Key 在 Grafana UI 中创建，具有固定权限；过期或删除后立即失效。
Basic Auth	Authorization: Basic <base64(username:password)>	使用用户名密码进行认证。	可用于管理员账户，但密码硬编码有安全风险；建议仅用于脚本或 CI/CD。
服务账户 Token	Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>	Grafana 8+ 引入，更安全的自动化认证方式。	服务账户可精细控制权限，推荐用于程序化访问。

4.2 API 基础路径与请求结构

项目	说明	注意事项
基础 URL	http://<grafana-host>:<port>/api	默认端口为 3000；若配置了 root_url，需包含路径前缀。
请求头 Content-Type	application/json	所有发送 JSON 数据的请求必须包含此头。
响应格式	JSON	成功响应通常包含 id、message 等字段；错误响应包含 message 和状态码。
路径参数	如 /api/datasources/:id，:id 为数据源 ID	需替换为实际数值。
查询参数	如 ?name=MyDashboard，用于搜索或过滤。	URL 编码特殊字符。
请求体（Body）	POST/PUT 请求中包含 JSON 数据，如创建资源的配置。	结构必须符合 API 文档要求。

4.3 常用 HTTP 方法与状态码说明

HTTP 方法	用途说明	典型 API 路径示例	注意事项
GET	获取资源信息	/api/dashboards/uid/:uid	安全且幂等，可多次调用。
POST	创建新资源	/api/datasources	非幂等，重复调用可能创建多个资源。
PUT	更新现有资源（全量替换）	/api/dashboards/db	需提供完整资源对象。
PATCH	部分更新资源	/api/users/:id	仅更新指定字段。
DELETE	删除资源	/api/datasources/:id	删除操作通常不可逆，需谨慎。

状态码	说明	应对措施
200	请求成功，返回数据	正常处理响应体。
201	资源创建成功	通常在 POST 响应中返回。
400	请求错误（如 JSON 格式错误、参数缺失）	检查请求体和参数。
401	未授权（认证失败）	检查 API Key 或用户名密码。
403	禁止访问（权限不足）	确认 API Key 权限是否足够。
404	资源未找到	检查路径或资源 ID 是否正确。
409	冲突（如创建已存在的资源）	先查询是否存在，或使用更新操作。
500	服务器内部错误	检查 Grafana 服务状态和日志。

4.4 使用 Java 发起 HTTP 请求（OkHttp 示例）

方法/组件	语法/代码示例	用途说明	注意事项
OkHttpClient	private final OkHttpClient client = new OkHttpClient();	创建 HTTP 客户端实例，可复用。	建议作为单例使用。
Request.Builder	Request request = new Request.Builder()	构建 HTTP 请求。	链式调用设置方法、URL、头、体。
设置 URL	.url("http://localhost:3000/api/datasources")	指定请求地址。	确保 URL 正确，包含 /api 前缀。
设置 Header	.addHeader("Authorization", "Bearer <your_api_key>")	添加认证头。	API Key 需替换为实际值。
设置 Body	.post(RequestBody.create(json, MediaType.get("application/json")))	为 POST/PUT 请求设置 JSON 体。	json 为 String 类型的 JSON 字符串。
execute()	Response response = client.newCall(request).execute();	同步执行请求。	适用于简单脚本；高并发场景建议用 enqueue() 异步调用。
Response	if (response.isSuccessful()) { String body = response.body().string(); }	处理响应。	body().string() 只能调用一次；及时关闭 Response 防止资源泄漏。
try-with-resources	try (Response response = client.newCall(request).execute()) { ... }	自动关闭 Response 资源。	推荐写法，避免资源泄漏。
JSON 处理	使用 Jackson 或 Gson 库序列化/反序列化对象。	简化 JSON 构造和解析。	例如：ObjectMapper.writeValueAsString(dataSourceConfig)。

---

第 5 章：Java 调用 Grafana API - 仪表盘管理

5.1 创建仪表盘（Create Dashboard）

方法名称	语法	用途	代码示例	注意事项
POST /api/dashboards/db	HTTP POST 请求，请求体包含仪表盘 JSON 模型和覆盖设置。	创建新的仪表盘或覆盖现有仪表盘。	{"dashboard": {"id": null, "uid": "abc123", "title": "My New Dashboard", "timezone": "browser", "panels": [{"type": "graph", "title": "CPU Usage", "datasource": "Prometheus-Prod", "targets": [{"expr": "100 - (avg by(instance) (rate(node_cpu_seconds_total{mode='idle'}[5m])) * 100)"}]}]}, "folderId": 0, "overwrite": false, "message": "Created via API"}	id 必须为 null；uid 可选，唯一标识，不填则自动生成；overwrite 设为 true 可覆盖同名仪表盘；folderId 指定所属文件夹，0 为通用文件夹；请求体需完整包含 dashboard 对象。

5.2 查询仪表盘列表（Search Dashboards）

方法名称	语法	用途	代码示例	注意事项
GET /api/search	HTTP GET 请求，可带查询参数。	搜索仪表盘，支持按名称、标签、类型过滤。	GET /api/search?query=API&tag=production&type=dash-db&limit=10	query：仪表盘标题模糊匹配；tag：按标签过滤，可多次出现；type：dash-db（持久化仪表盘），dash-folder（文件夹）；limit：返回最大数量；响应为仪表盘摘要列表，不包含完整 JSON 模型。

5.3 获取指定仪表盘（Get Dashboard By UID）

方法名称	语法	用途	代码示例	注意事项
GET /api/dashboards/uid/:uid	HTTP GET 请求，:uid 替换为实际 UID。	获取指定 UID 的完整仪表盘定义。	GET /api/dashboards/uid/abc123	返回 JSON 包含 dashboard 对象和元数据（如 version, folderId）；uid 是全局唯一标识，比 id 更稳定；若仪表盘不存在，返回 404。

5.4 更新仪表盘（Update Dashboard）

方法名称	语法	用途	代码示例	注意事项
POST /api/dashboards/db	HTTP POST 请求，请求体结构同创建。	更新现有仪表盘，需提供完整模型。	{"dashboard": {"id": 15, "uid": "abc123", "title": "Updated Dashboard", "panels": [...], "version": 2}, "folderId": 0, "overwrite": true, "message": "Updated panel title"}	id 必须提供，为当前仪表盘 ID（可从 GET 响应获取）；version 应为当前版本号，防止冲突；overwrite 必须设为 true 才能更新；实际是”创建或覆盖”操作，本质与创建相同。

5.5 删除仪表盘（Delete Dashboard）

方法名称	语法	用途	代码示例	注意事项
DELETE /api/dashboards/uid/:uid	HTTP DELETE 请求，:uid 替换为实际 UID。	根据 UID 删除仪表盘。	DELETE /api/dashboards/uid/abc123	删除操作不可逆，请谨慎调用；成功返回 200 和 {"title": "Dashboard Name", "message": "Dashboard deleted"}；若 UID 不存在，返回 404。

第 6 章：Java 调用 Grafana API - 数据源管理

6.1 创建数据源（Create Data Source）

方法名称	语法	用途	代码示例	注意事项
POST /api/datasources	HTTP POST 请求，请求体为数据源配置。	添加新的数据源到 Grafana。	见下方	name 必须唯一；type 必须是支持的类型（如 prometheus, influxdb）；access 推荐 proxy；敏感信息在 secureJsonData 字段中传递；成功返回 200 和 {"id": 1, "message": "Datasource added", "name": "..."}。

请求体示例：

{
    "name": "Prometheus-Dev",
    "type": "prometheus",
    "url": "http://prometheus-dev:9090",
    "access": "proxy",
    "basicAuth": false,
    "isDefault": false,
    "jsonData": {
        "timeInterval": "5s"
    }
}

6.2 查询数据源列表（Search Data Sources）

方法名称	语法	用途	代码示例	注意事项
GET /api/datasources	HTTP GET 请求，无参数。	获取所有已配置的数据源列表。	GET /api/datasources	返回数组，包含每个数据源的 id, name, type, url, access 等信息；不返回敏感字段（如密码）；用于发现和验证数据源配置。

6.3 获取指定数据源（Get Data Source By ID）

方法名称	语法	用途	代码示例	注意事项
GET /api/datasources/:id	HTTP GET 请求，:id 替换为实际 ID。	获取指定 ID 的数据源完整配置。	GET /api/datasources/1	返回完整的配置对象，包括 jsonData；敏感信息（secureJsonData）不会在响应中显示；用于获取数据源详细信息以供程序使用。

6.4 更新数据源（Update Data Source）

方法名称	语法	用途	代码示例	注意事项
PUT /api/datasources/:id	HTTP PUT 请求，:id 替换为实际 ID，请求体为新配置。	更新现有数据源的配置。	见下方	必须提供 id 和 version（当前版本，可从 GET 获取）；version 用于乐观锁，防止并发修改冲突；敏感信息更新需在 secureJsonData 中传递；成功返回 200。

请求体示例：

{
    "id": 1,
    "name": "Prometheus-Prod-Updated",
    "type": "prometheus",
    "url": "http://prometheus-prod-new:9090",
    "access": "proxy",
    "jsonData": {
        "timeInterval": "10s"
    },
    "version": 2
}

6.5 删除数据源（Delete Data Source）

方法名称	语法	用途	代码示例	注意事项
DELETE /api/datasources/:id	HTTP DELETE 请求，:id 替换为实际 ID。	删除指定 ID 的数据源。	DELETE /api/datasources/1	删除操作不可逆，且会移除所有依赖此数据源的面板；成功返回 200；若 ID 不存在，返回 404。

第 7 章：Java 调用 Grafana API - 用户与组织管理

7.1 查询用户列表（Search Users）

方法名称	语法	用途	代码示例	注意事项
GET /api/users	HTTP GET 请求，可带查询参数。	搜索和分页获取用户列表。	GET /api/users?perpage=10&page=1&query=admin	perpage：每页数量，默认 10；page：页码，从 1 开始；query：用户名或邮箱模糊匹配；响应包含用户 ID、登录名、邮箱、姓名等基本信息。

7.2 创建用户（Create User）

方法名称	语法	用途	代码示例	注意事项
POST /api/admin/users	HTTP POST 请求，请求体为用户信息。	在 Grafana 中创建新用户。	见下方	需 Admin 权限 API Key 调用；login 必须唯一；成功返回 200 和 {"id": 5, "message": "User created"}；若启用 LDAP，此操作可能受限。

请求体示例：

{
    "name": "John Doe",
    "email": "john.doe@example.com",
    "login": "johndoe",
    "password": "securePassword123"
}

7.3 更新用户权限（Update User Permissions）

方法名称	语法	用途	代码示例	注意事项
PUT /api/org/users/:userId	HTTP PUT 请求，:userId 替换为实际用户 ID。	更新用户在当前组织的角色（权限）。	PUT /api/org/users/5 {"role": "Admin"}	role 可选值：Viewer, Editor, Admin；影响用户在当前组织下的所有资源访问权限；需当前组织管理员或 Grafana Admin 权限。

7.4 组织切换与管理（Org API）

方法名称	语法	用途	代码示例	注意事项
GET /api/user/orgs	HTTP GET 请求	获取当前用户所属的所有组织。	GET /api/user/orgs	响应为组织数组，含 orgId, name, role；用于多租户场景下用户组织导航。
POST /api/user/using/:orgId	HTTP POST 请求	切换当前用户到指定组织。	POST /api/user/using/2	切换后，后续 API 操作作用于该组织上下文；需用户是目标组织成员。
POST /api/orgs	HTTP POST 请求	创建新组织（需 Grafana Admin 权限）。	{"name": "New Organization"}	成功返回 200 和组织 ID；创建后需手动添加用户。
GET /api/orgs/:orgId/users	HTTP GET 请求	获取指定组织内的所有用户。	GET /api/orgs/2/users	返回用户列表及在该组织中的角色；用于组织级用户审计。

第 8 章：Java 调用 Grafana API - 告警管理

8.1 创建告警规则（Create Alert Rule）

方法名称	语法	用途	代码示例	注意事项
POST /api/v1/provisioning/alert-rules	HTTP POST 请求，请求体为告警规则定义。	在 Mimir、Loki 或 Prometheus 数据源上创建告警规则。	见下方	folderUid 和 ruleGroup 定义规则分组；data 中 datasourceUid 需替换为实际数据源 UID；condition 指定条件引用（如 “A”）；成功返回 201。

请求体示例：

{
    "annotations": {
        "description": "CPU usage is high"
    },
    "condition": "A",
    "data": [
        {
            "refId": "A",
            "queryType": "",
            "relativeTimeRange": {
                "from": 600,
                "to": 0
            },
            "datasourceUid": "PD8C576611E62080A",
            "model": {
                "expr": "avg(rate(node_cpu_seconds_total{mode=\"idle\"}[5m])) by (instance) < 0.1",
                "intervalMs": 10000,
                "maxDataPoints": 43200,
                "refId": "A"
            }
        }
    ],
    "execErrState": "Alerting",
    "for": "5m",
    "folderUid": "abc123",
    "noDataState": "NoData",
    "orgId": 1,
    "ruleGroup": "example-group",
    "title": "High CPU Usage",
    "uid": ""
}

8.2 查询告警状态（Get Alert States）

方法名称	语法	用途	代码示例	注意事项
GET /api/alertmanager/grafana/api/v2/alerts	HTTP GET 请求	获取当前所有活跃告警的状态。	GET /api/alertmanager/grafana/api/v2/alerts?active=true&state=active	遵循 Alertmanager v2 API 规范；可按状态（active, suppressed）、严重性过滤；响应包含告警标签、注解、开始时间等。

8.3 暂停/恢复告警（Pause Alert）

方法名称	语法	用途	代码示例	注意事项
POST /api/v1/provisioning/alert-rules/{UID}/pause	HTTP POST 请求，JSON 体指定暂停状态。	暂停或恢复单个告警规则的评估。	POST /api/v1/provisioning/alert-rules/abc123/pause {"paused": true}	paused: true 暂停，false 恢复；暂停期间不产生新告警，但历史记录保留；需提供告警规则的 UID。

8.4 告警通知渠道管理（Notification Policies）

方法名称	语法	用途	代码示例	注意事项
GET /api/v1/provisioning/policies	HTTP GET 请求	获取根通知策略树。	GET /api/v1/provisioning/policies	返回完整的策略层级结构；用于查看当前告警路由配置。
PUT /api/v1/provisioning/policies	HTTP PUT 请求	全量更新通知策略树。	见下方	必须发送完整策略树，非部分更新；receiver 必须是已存在的联系人（Contact Point）；格式遵循 AM v2 API。
GET /api/v1/provisioning/contact-points	HTTP GET 请求	获取所有配置的通知渠道（Contact Points）。	GET /api/v1/provisioning/contact-points	返回 Slack、Email、Webhook 等渠道配置；用于审计和发现。
POST /api/v1/provisioning/contact-points	HTTP POST 请求	创建新的通知渠道。	见下方	type 支持 slack, email, webhook 等；敏感字段如 token 在响应中被隐藏。

PUT 通知策略示例：

{
    "receiver": "default-email",
    "group_by": ["..."],
    "routes": [
        {
            "receiver": "critical-pager",
            "matchers": ["severity=critical"]
        }
    ]
}

POST 通知渠道示例：

{
    "name": "slack-ops",
    "type": "slack",
    "settings": {
        "recipient": "#alerts",
        "token": "xoxb-..."
    }
}

第 9 章：Java 应用集成 Prometheus + Grafana

9.1 在 Java 应用中集成 Micrometer

添加依赖：

方法名称	语法/配置	用途	代码示例	注意事项
添加依赖	Maven/Gradle 依赖引入	集成 Micrometer 核心与 Prometheus 支持。	见下方	micrometer-core 提供通用 API；micrometer-registry-prometheus 提供 Prometheus 格式导出。

Maven 依赖：

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-core</artifactId>
</dependency>
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

配置 MeterRegistry：

方法名称	语法/配置	用途	代码示例	注意事项
配置 MeterRegistry	Spring Boot 自动配置或手动注册	收集和导出指标。	见下方	推荐使用 @Bean 方式配置；commonTags 添加应用、环境等通用标签，便于在 Grafana 中过滤。

@Bean
public MeterRegistryCustomizer<PrometheusMeterRegistry> metricsCommonTags() {
    return registry -> registry.config().commonTags("application", "my-java-app");
}

创建自定义指标：

方法名称	语法/配置	用途	代码示例	注意事项
创建自定义指标	Counter, Gauge, Timer, DistributionSummary	记录业务或性能指标。	见下方	Counter：单调递增（如请求数）；Gauge：当前值（如队列长度）；Timer：事件耗时；命名使用小写字母和点号，如 http.server.requests。

@Autowired
private MeterRegistry registry;

public void processOrder() {
    Counter counter = registry.counter("order.processed", "type", "ecommerce");
    counter.increment();
}

9.2 暴露 Prometheus 格式指标端点

方式一：Spring Boot Actuator（推荐）

方法名称	语法/配置	用途	代码示例	注意事项
Spring Boot Actuator	启用 /actuator/prometheus 端点	暴露 Micrometer 收集的指标。	见下方	确保 spring-boot-starter-actuator 已引入；端点默认路径为 /actuator/prometheus；生产环境需配置安全认证（如 Basic Auth）。

management:
  endpoints:
    web:
      exposure:
        include: health,info,prometheus
  endpoint:
    prometheus:
      enabled: true

方式二：自定义 Servlet（非 Spring 应用）

方法名称	语法/配置	用途	代码示例	注意事项
自定义 Servlet	实现 HttpServlet 输出文本格式	在非 Spring 应用中暴露指标。	见下方	需注册 Servlet 到 Web 容器；CollectorRegistry.defaultRegistry 可与 Micrometer 集成。

public class PrometheusServlet extends HttpServlet {
    private final CollectorRegistry registry;

    public PrometheusServlet(CollectorRegistry registry) {
        this.registry = registry;
    }

    protected void doGet(HttpServletRequest req, HttpServletResponse resp) {
        resp.setContentType(TextFormat.CONTENT_TYPE_004);
        TextFormat.write004(resp.getWriter(), registry.metricFamilySamples());
    }
}

9.3 配置 Prometheus 抓取 Java 应用指标

配置项	说明	注意事项
scrape_configs	Prometheus 配置文件中的抓取任务。	必须定义 job_name 和 static_configs 或服务发现。
job_name	抓取任务名称，如 java-app-metrics。	在 Grafana 数据源查询时用于过滤。
static_configs / targets	直接指定目标应用地址，如 targets: ['localhost:8080']。	适用于固定实例；动态环境建议使用服务发现（Consul, Kubernetes）。
metrics_path	指标端点路径，默认 /actuator/prometheus。	必须与应用暴露的路径一致。
scheme	HTTP 协议，http 或 https。	若应用启用 HTTPS，需配置为 https。
scrape_interval	抓取间隔，如 15s。	根据指标变化频率调整，过短增加负载。
relabel_configs	重写标签，用于添加或修改元数据。	可添加 environment=prod 等标签。

示例配置：

scrape_configs:
  - job_name: 'my-java-app'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['app-server-01:8080', 'app-server-02:8080']
    relabel_configs:
      - source_labels: [__address__]
        target_label: instance

配置完成后重启 Prometheus 或调用 /-/reload 热加载。

9.4 在 Grafana 中创建基于 Micrometer 指标的仪表盘

步骤	说明	注意事项
1. 选择数据源	查询时选择已配置的 Prometheus 数据源。	确认数据源状态为 OK。
2. 编写 PromQL 查询	使用 Micrometer 生成的指标名进行查询。	HTTP 请求计数：rate(http_server_requests_seconds_count[5m])；JVM 内存：jvm_memory_used_bytes{area="heap"}；自定义计数器：order_processed_total
3. 使用标签过滤	利用 application, instance, uri, method 等标签细化查询。	rate(http_server_requests_seconds_count{application="my-java-app"}[5m])
4. 选择可视化类型	根据指标选择图表（如 Time series, Bar gauge, Stat）。	计数/速率：Time series；当前值：Stat 或 Gauge；分布：Histogram
5. 添加变量	创建 application、instance 变量实现动态切换。	提升仪表盘复用性（详见 10.1）。
6. 保存仪表盘	命名并保存到指定文件夹。	建议包含版本信息或环境。

第 10 章：高级主题与最佳实践

10.1 使用 Grafana 变量实现动态仪表盘

变量类型	用途	示例	注意事项
Query	从数据源动态获取值（最常用）。	label_values(application) 获取所有应用名。	可用于 instance, job, 自定义标签；更新频率可设为 On Dashboard Load 或 Refresh。
Custom	手动定义一组值。	prod, staging, dev	用于固定环境切换。
Constant	不显示在 UI 的常量，用于模板。	datasource=Prometheus-Prod	简化面板 JSON 中的数据源引用。
Datasource	从可用数据源列表中选择。	类型选择 Prometheus	用于跨数据源仪表盘。

使用方式：在查询中使用 $variable_name，例如：

rate(http_server_requests_seconds_count{application=~"$app"}[5m])

=~ 用于正则匹配变量；变量可设置多选。

10.2 仪表盘模板化与版本控制

实践	说明	工具/方法
导出 JSON	将仪表盘保存为 JSON 文件。	Grafana UI 的 Share → Export → Copy JSON。
使用 Dashboard UID	在代码或 CI/CD 中引用仪表盘时使用 uid 而非 id。	uid 全局唯一且稳定，id 在导入时可能变化。
版本控制	将仪表盘 JSON 文件纳入 Git 管理。	git add my-dashboard.json
代码生成	使用 Jsonnet、Tanka 或 Grafana Terraform Provider 生成仪表盘。	Terraform: resource "grafana_dashboard" "mydash" { config_json = file("dash.json") }
CI/CD 集成	在流水线中自动创建/更新仪表盘。	使用 terraform apply 或直接调用 Grafana API。

10.3 API 调用的异常处理与重试机制

实践	说明	代码示例/建议
捕获 HTTP 异常	处理连接失败、超时、认证错误等。	见下方代码
检查状态码	根据不同状态码采取不同措施。	401/403：检查 API Key 权限；404：资源不存在，可能需创建；429：限流，需退避；5xx：服务端错误，可重试。
实现重试机制	对可恢复错误进行指数退避重试。	使用 OkHttp 的 RetryAndFollowUpInterceptor 或自定义逻辑。
日志记录	记录请求、响应和错误详情。	使用 SLF4J 记录 request.url(), response.code(), 注意 body 只能读一次。

异常处理示例：

try (Response response = client.newCall(request).execute()) {
    if (!response.isSuccessful()) {
        throw new IOException("Unexpected response " + response);
    }
    // 处理成功响应
} catch (IOException e) {
    // 记录日志并处理
}

10.4 安全实践：API Key 管理与权限最小化

实践	说明	注意事项
权限最小化	为不同用途创建不同权限的 API Key。	仅读取仪表盘：Viewer；创建/更新仪表盘：Editor；管理数据源/用户：Admin；避免在程序中使用 Admin Key，除非必要。
使用服务账户	Grafana 8+ 推荐使用服务账户（Service Accounts）替代 API Key。	服务账户可分配精细角色（RBAC），生命周期更易管理。
密钥存储	避免硬编码 API Key。	使用环境变量：System.getenv("GRAFANA_API_KEY")；使用密钥管理服务（如 Hashicorp Vault, AWS Secrets Manager）。
定期轮换	定期更新 API Key。	降低密钥泄露风险。
网络隔离	限制 Grafana API 的访问来源。	通过防火墙或反向代理（如 Nginx）只允许特定 IP 访问 /api 路径。
审计日志	启用并监控 Grafana 服务器日志。	关注 t=... lvl=info msg="API key auth successful" 和失败登录尝试。