Grafana 常用 CLI 命令与工具详解

目标：详解 Grafana 13.2.3 的 CLI 体系与常用运维接口，覆盖主命令、server 子命令、cli（plugins/admin）子命令及 HTTP API，所有命令均在已部署 Grafana 13.2.3 实例上实测回显。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
Grafana 版本：13.2.3
二进制：/usr/share/grafana/bin/grafana（deb 安装生成 grafana-server、grafana-cli 符号链接）
服务地址：http://localhost:3000

二、工具概览

Grafana 13.x 起将原本分离的 grafana-server 与 grafana-cli 合并为单一二进制 grafana，通过子命令区分：server（起服务）、cli（CLI 工具集，含 plugins/admin）。旧版独立 CLI 命令在 13.x 需在前面加 cli 子命令。

三、前置条件

已安装 Grafana 并能在命令行访问二进制（见《Ubuntu 22.04 安装 Grafana 指南》）
具备 root 或 sudo 权限执行运维命令

四、主命令 `grafana`

grafana --help

▶️ 实测回显：

NAME:
   grafana - Grafana server and command line interface
USAGE:
   grafana [global options] command [command options]
VERSION:
   13.2.3
COMMANDS:
   cli      run the grafana cli
   server   run the grafana server
   help, h  Shows a list of commands or help for one command

💡 符号链接 grafana-server/grafana-cli 都指向同一 grafana 二进制，本质是 grafana server/grafana cli 的别名。

五、版本查看

grafana server -v
# 或等价
grafana-cli cli --version

▶️ 实测回显：

Version 13.2.3 (commit: 90ffed056f0884267356c12a0eeb72a022af53f1, branch: release-13.2.3#patched)

⚠️ 13.x 使用 grafana server -v（-v 是 server 子命令选项），旧的 grafana-server -v 根级写法已失效。

六、server 子命令（启动服务）

# 查看 server 选项
grafana server --help

▶️ 实测回显（关键选项）：

OPTIONS:
   --config value          Path to config file
   --homepath value        Path to Grafana install/home path
   --pidfile value         Path to Grafana pid file
   --packaging value       describes the way Grafana was installed (default: "unknown")
   --configOverrides value Configuration options to override defaults as a string

启动示例：

cd /usr/share/grafana
nohup /usr/sbin/grafana-server server --config=/etc/grafana/grafana.ini --homepath=/usr/share/grafana --packaging=deb >/tmp/grafana-server.log 2>&1 &

server 下还有内部子命令 target（指定 Grafana 内部服务，通常调试用）：

grafana server target --help

七、cli 子命令（CLI 工具集）

7.1 cli 全局选项

grafana cli --help

▶️ 实测回显（关键选项）：

COMMANDS:
   plugins  Manage plugins for grafana
   admin    Grafana admin commands
OPTIONS:
   --homepath value     Path to Grafana install/home path
   --configOverrides value
   --pluginsDir value   (default: "/var/lib/grafana/plugins")
   --repo value         (default: "https://grafana.com/api/plugins")

八、plugins 子命令（插件管理）

grafana cli plugins --help

▶️ 实测回显（全部子命令）：

COMMANDS:
   install       install <plugin id> <plugin version (optional)>
   list-remote   list remote available plugins
   list-versions list-versions <plugin id>
   update, upgrade          update <plugin id>
   update-all, upgrade-all  update all your installed plugins
   ls            list installed plugins (excludes core plugins)
   uninstall, remove        uninstall <plugin id>

8.1 列出已安装插件

grafana cli plugins ls

▶️ 实测回显（首次无第三方插件）：
no installed plugins found

8.2 列出远程可用插件

grafana cli plugins list-remote

▶️ 实测回显（片段）：

id: aceiot-svg-panel version: 0.2.0
id: ae3e-plotly-panel version: 0.5.0
id: aggregations-io-datasource version: 1.2.0

8.3 安装插件

grafana cli plugins install grafana-piechart-panel
# 指定版本
grafana cli plugins install grafana-piechart-panel 1.6.2

💡 安装第三方插件后需重启服务：systemctl restart grafana-server（或无 systemd 时重启进程）。

8.4 卸载 / 更新插件

grafana cli plugins uninstall grafana-piechart-panel
grafana cli plugins update-all

九、admin 子命令（管理员维护）

grafana cli admin --help

▶️ 实测回显（全部子命令）：

COMMANDS:
   reset-admin-password        reset-admin-password <new password>
   data-migration              Runs a script that migrates or cleanups data in your database
   secrets-migration           Runs a script that migrates secrets in your database
   secrets-consolidation       Re-encrypts all encrypted values with new data keys
   flush-rbac-seed-assignment  Clears RBAC seeding
   db-migrate                  Run schema migrations against the database
   resource-db-migrate         Run the unified storage resource schema migrations

9.1 重置管理员密码

grafana cli admin reset-admin-password q1w2e3r4

▶️ 实测回显（执行成功，尾行）：

logger=settings level=info msg="Starting Grafana" version=13.2.3 commit=90ffed056f0884267356c12a0eeb72a022af53f1 compiled=2026-09-28T20:55:24Z
（命令以退出码 0 结束）

⚠️ 忘记管理员密码时用此命令重置为指定值。

9.2 数据库迁移

grafana cli admin db-migrate

9.3 密钥重新加密（安全维护）

grafana cli admin secrets-consolidation

十、HTTP API 运维接口

命令行运维常结合 HTTP API 使用，示例账号 admin/q1w2e3r4：

# 健康检查
curl http://localhost:3000/api/health

# 获取组织信息（需认证）
curl -u admin:q1w2e3r4 http://localhost:3000/api/org

# 列出数据源
curl -u admin:q1w2e3r4 http://localhost:3000/api/datasources

# 获取首页看板（`/api/dashboards/home`）
curl -u admin:q1w2e3r4 http://localhost:3000/api/search?type=dash-db

▶️ 实测回显（/api/org）：

{"id":1,"name":"Main Org.","address":{"address1":"","address2":"","city":"","zipCode":"","state":"","country":""}}

十一、注意事项

13.x 所有 CLI 需按 grafana cli <族> <命令> 层级调用，<族> 取 plugins 或 admin、<命令> 取对应子命令名；旧版 grafana-cli plugins ls 直接调用会报 'plugins' is not a grafana command。
--homepath 必须指向安装目录；plugins ls 依赖 --pluginsDir（默认 /var/lib/grafana/plugins）存在。
修改配置/重置密码等操作后需重启服务生效。

十二、常见问题

Q1：直接敲 grafana-cli plugins ls 报错？ 13.x 语法为 grafana-cli cli plugins ls，需补 cli 子命令。

Q2：grafana: 'plugins' is not a grafana command？ 同理，未加 cli 前缀。示例：grafana-cli cli admin reset-admin-password。

Q3：stat /var/lib/grafana/plugins: no such file or directory？ 先 mkdir -p /var/lib/grafana/plugins 再执行插件命令。

十三、参考链接

Grafana CLI 文档：https://grafana.com/docs/grafana/latest/administration/cli/
Grafana HTTP API：https://grafana.com/docs/grafana/latest/developers/http_api/
插件管理：https://grafana.com/docs/grafana/latest/administration/plugin-management/

Grafana 常用 CLI 命令与工具详解

Grafana 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、主命令 grafana

五、版本查看

六、server 子命令（启动服务）

七、cli 子命令（CLI 工具集）

7.1 cli 全局选项

八、plugins 子命令（插件管理）

8.1 列出已安装插件

8.2 列出远程可用插件

8.3 安装插件

8.4 卸载 / 更新插件

九、admin 子命令（管理员维护）

9.1 重置管理员密码

9.2 数据库迁移

9.3 密钥重新加密（安全维护）

十、HTTP API 运维接口

十一、注意事项

十二、常见问题

十三、参考链接

四、主命令 `grafana`