服务账号与令牌
Grafana 9.3 起用服务账号替代旧版 API Key：为自动化创建固定的服务账号并赋予角色，再签发令牌供脚本、CI 与巡检工具使用。令牌只在创建时完整展示一次，之后无法再次获取，只能重新签发。相比把个人账号的密钥借给自动化，服务账号的权限与归属都更清晰。
基本信息
| 适用版本 | Grafana 9.3 及以上，旧 API Key 已标记弃用 |
|---|---|
| 角色选项 | Viewer、Editor、Admin 三档 |
| 令牌可见性 | 仅创建时展示一次，遗失只能重新签发 |
| 归属管理 | 账号有明确用途说明，便于轮换与审计 |
创建与签发
创建与签发
# 创建服务账号（role：Viewer / Editor / Admin）
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
http://localhost:3000/api/serviceaccounts -d '{"name":"ci","role":"Editor"}'
# 为账号签发令牌（返回的 key 仅显示一次）
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" -H "Content-Type: application/json" \
http://localhost:3000/api/serviceaccounts/1/tokens -d '{"name":"ci-token"}'角色选择
| 角色 | 能做什么 | 适用场景 |
|---|---|---|
| Viewer | 只读查询、导出看板 | 巡检脚本与监控探活 |
| Editor | 创建与修改看板、告警 | CI 发布看板、批量同步 |
| Admin | 管理用户、数据源与组织 | 平台初始化与自动化运维 |
使用规范
- 按用途赋最小够用角色：只读巡检给 Viewer，看板发布给 Editor
- 令牌放密钥管理系统或环境变量，不写进代码与镜像
- 记录每个令牌的归属与用途，定期轮换并保留更换记录
- 人员或流水线下线时同步删除对应服务账号，避免凭据残留
令牌等同于对应角色的权限：泄露一个 Admin 令牌等于交出整个 Grafana 的控制权，必须纳入密钥管理并设置轮换周期。
轮换流程
- 先签发新令牌并在灰度环境验证调用正常
- 切换消费方使用新令牌，确认指标与任务都恢复正常
- 撤销旧令牌并删除无效账号，在变更记录里写下轮换时间
- 按环境分开账号：预发与生产的令牌互不通用，一处泄露不影响另一侧
- 令牌名带用途与责任人，审计时能快速识别归属
- 定期扫描长期未使用的服务账号与令牌，确认是否可以直接下线