用途:从 Grafana 实例导入现有仪表盘,并用 gcx dev import 转换为 Go builder 代码,适合把线上仪表盘转为代码、迁移到代码化管理。
前提:已安装并配置 gcx 的 Grafana 连接(gcx config check 应显示有效 context),且目标 Grafana 实例可访问。
主要命令:导入全部仪表盘用 gcx dev import dashboards,默认写入 imported/ 目录,每个仪表盘生成一个返回 *resource.ManifestBuilder 的函数;导入指定仪表盘用 gcx dev import dashboards/my-dashboard-uid;自定义目录用 gcx dev import dashboards --path src/grafana;导入多种资源类型用 gcx dev import dashboards folders。
工作方式:通过 K8s API(/apis 端点)获取资源,检测资源 API 版本,运行对应版本的转换器把 JSON 转为 SDK builder 代码,再用 resource.NewManifestBuilder() 包装,最后写入 imported/<snake_case_name>.go。生成的代码使用 grafana-foundation-sdk builder 模式,与 dev generate、dev scaffold 一致。
典型流程:先 gcx dev import dashboards --path internal/dashboards 导入,再审查并编辑生成代码,然后 go run . 渲染清单(在 gcx 脚手架项目中写入 ./resources),最后 gcx resources push 推回 Grafana。
常见问题:出现 no converter found 表示该资源 API 版本无转换器,错误信息会给出不支持的版本;401/403 认证错误可运行 gcx config check 验证凭据;导入为空说明选择器未匹配资源,可用 gcx resources get dashboards 检查 UID;若报 undefined: cog 等小写 SDK 标识符,旧版 gcx 会遗漏 SDK import,需为每个未定义标识符补上 github.com/grafana/grafana-foundation-sdk/go/<pkg>(variants 位于 go/cog/variants),新版 gcx 会输出完整 import;复杂仪表盘的转换结果可能仍需手工修正,可反复构建、读取首个错误并修复。