跳到主要内容

安装与快速上手

安装方式怎么选​

Grafana 是单个 Go 二进制加一个数据目录，怎么跑都行。三条常见路线：

方式适合场景优点缺点
Docker学习、本地验证、小环境一条命令起，环境干净注意容器网络和数据卷
Homebrew（macOS）Mac 本机长期跑原生进程，brew services 托管升级跟随 brew，不如容器灵活
APT 官方源Linux 服务器生产部署systemd 托管，装完即服务要先配官方仓库

学习阶段用 Docker 最快，本篇以 Docker 为主线，brew 和 apt 各给一段。K8s 场景一般直接用 kube-prometheus-stack 全家桶（自带 Grafana），不在本篇展开。

版本口径

当前主流是 Grafana 11.x 和 12.x（12 于 2025 年发布），本篇操作两个大版本通用。Docker 官方主镜像 grafana/grafana 是 Enterprise 发行版（不激活 license 等同 OSS），纯开源版选 grafana/grafana-oss，本系列以 OSS 为准。

Docker 跑起来​

一条命令：

docker run -d \
  --name grafana \
  -p 3000:3000 \
  -v grafana-storage:/var/lib/grafana \
  -e "GF_SECURITY_ADMIN_PASSWORD=admin123" \
  grafana/grafana-oss:12.1.0

参数说明：

  • -p 3000:3000：Grafana 的 Web 服务端口是 3000。
  • -v grafana-storage:/var/lib/grafana：数据目录挂成命名卷，容器删了重建，仪表盘和账号都还在。
  • -e "GF_SECURITY_ADMIN_PASSWORD=admin123"：用环境变量直接定死 admin 初始密码，免得每次重建都走默认密码加强制改密的流程（变量命名规则见下文「配置与数据目录」）。

启动后浏览器打开 http://localhost:3000，看到登录页即成功。

镜像 tag

示例里的 12.1.0 换成你要的版本号即可。学习可以用固定小版本号保证可复现，生产别用 latest。

Homebrew（macOS）：

brew install grafana
brew services start grafana

配置文件在 /opt/homebrew/etc/grafana/grafana.ini（Apple Silicon；Intel 在 /usr/local/etc/grafana/grafana.ini），数据目录在 /opt/homebrew/var/lib/grafana。停服务用 brew services stop grafana。

APT 官方源（Debian/Ubuntu）：

sudo apt-get install -y apt-transport-https software-properties-common wget
sudo mkdir -p /etc/apt/keyrings
wget -q -O - https://apt.grafana.com/gpg.key | gpg --dearmor | sudo tee /etc/apt/keyrings/grafana.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/grafana.gpg] https://apt.grafana.com stable main" | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt-get update
sudo apt-get install -y grafana
sudo systemctl enable --now grafana-server

装完即注册为 systemd 服务（服务名 grafana-server），配置文件 /etc/grafana/grafana.ini，数据目录 /var/lib/grafana。APT 源里 grafana 包就是 OSS 版，企业版包名是 grafana-enterprise，注意别和 Docker 镜像的命名习惯搞反了。

首次登录​

浏览器打开 http://localhost:3000：

  • 默认账号 admin / admin。没用环境变量改过初始密码的话，首次登录会强制要求改密（界面提供 Skip 跳过，学习可以跳，生产别跳）。
  • 用了上面 GF_SECURITY_ADMIN_PASSWORD 的，直接拿新密码登录即可。

登录后进入首页，先花一分钟认识界面五个区域：

  • 左侧导航栏：核心入口都在这里——Dashboards（看板）、Explore（临时查询排障）、Alerting（告警）、Connections（数据源与插件接入）、Administration（实例管理）。点左上角菜单图标可折叠展开。
  • 顶部搜索：点放大镜或按快捷键 Ctrl+K（macOS 是 Cmd+K），全局搜索仪表盘、页面和功能，看板多了以后全靠它。
  • 右上角用户菜单：个人偏好（主题、时区、默认首页）、修改密码、切换 Organization（有多个 Org 时才出现）。
  • 面包屑与收藏：页面顶部的路径导航；看板右上角的星标收藏后，会出现在首页和导航的 Starred 里，常用看板一键直达。
  • 帮助入口：左侧导航底部的 ? 图标，里面是官方文档链接和当前版本号——报版本、查兼容性先看这里。

接第一个数据源​

以接入 Prometheus 为例。前置条件：Prometheus 已在运行且能打开它的 UI，部署方式见 Prometheus 部署与快速上手。

操作路径：左侧导航 Connections → Data sources → Add data source，搜索框里选 Prometheus。配置页绝大多数项先保持默认，关键只有一个：

  • Connection → URL：Prometheus 的 HTTP 地址。
    • Grafana 与 Prometheus 同机裸进程（brew、二进制、apt 方式）：填 http://localhost:9090。
    • Grafana 在 Docker 容器里，Prometheus 在宿主机或另一个容器（macOS、Windows 的 Docker Desktop）：填 http://host.docker.internal:9090。
    • Linux 的 Docker：host.docker.internal 默认不存在，启动 Grafana 时加 --add-host=host.docker.internal:host-gateway，或者干脆用 --network host 共享宿主机网络栈。

填完拉到页面最底部点 Save & Test：绿色提示「Successfully queried the Prometheus API」就说明通了；红色报错按提示检查 URL 与网络，常见错误见下文「常见问题」。

URL 是「服务端视角」的

数据源的 URL 是 Grafana 服务端进程去访问的，不是你的浏览器。你的浏览器能打开 localhost:9090，不代表容器里的 Grafana 能——它俩不在同一个网络命名空间。理解这一点，数据源连通性问题就排掉了一半。

设一条默认数据源

环境里有多条数据源时，把最常用的那条设为 Default（数据源列表里点进去勾选）：新建 Panel、打开 Explore 时都会默认选中它，少点很多次下拉框。

导入第一个仪表盘​

自己从零画面板是后话，先体验社区现成的。grafana.com/dashboards 上有上万块用户贡献的看板，按数据源和场景分类。以监控 Linux 主机的经典看板 Node Exporter Full（ID 1860） 为例。

前置条件：宿主机跑了 node_exporter，且 Prometheus 已经抓取它——抓取配置同样在 Prometheus 部署与快速上手 的「第一个抓取目标」一节。

导入流程：

  1. 左侧导航 Dashboards → New → Import。
  2. 「Import via grafana.com」输入框填 1860，点 Load——Grafana 会联网拉取看板定义。
  3. 底部下拉框选择刚配好的 Prometheus 数据源。
  4. 点 Import，立刻看到 CPU、内存、磁盘、网络的全套图表；左上角变量下拉可以切换不同主机。
现成看板的两个提醒
  • 第三方看板可能更新或下架，ID 失效就去 dashboards 页面按名字搜同名替代。
  • 现成看板指标多、查询密，右上角默认刷新频率别调太低，小环境 30 秒足够。

会用别人的看板之后，第 4 篇再学自己画：Panel、变量、查询的组合拳。

配置与数据目录​

  • 主配置 grafana.ini：容器内 /etc/grafana/grafana.ini；brew 安装 /opt/homebrew/etc/grafana/grafana.ini；apt 安装 /etc/grafana/grafana.ini。几百项配置注释写得很全，入门阶段基本不用动。
  • 环境变量覆盖：ini 里任何配置都能用 GF_ 前缀环境变量覆盖，规则是 GF_段名_键名（段名和键名大写）。比如 [security] 段的 admin_password 对应 GF_SECURITY_ADMIN_PASSWORD——上面 Docker 命令用的就是它。容器场景基本都走环境变量，不直接改 ini。
  • provisioning 目录：/etc/grafana/provisioning/ 下按 YAML 声明数据源、仪表盘、告警联系点，Grafana 启动时自动加载。这是「配置即代码」的玩法，不点鼠标就能复刻一套环境——第 3 篇专门展开。
  • 数据默认存 SQLite：/var/lib/grafana/grafana.db，仪表盘定义、用户、数据源配置全在里面，单机自用完全够；多实例高可用才需要换成 MySQL 或 PostgreSQL 作后端库。
备份就一件事

备份 Grafana 等于备份 /var/lib/grafana 这个目录（Docker 里就是 grafana-storage 卷）。整目录拷走，换新机器原样放回，启动即还原。

常见问题​

端口被占​

3000 被占了换宿主机映射端口，容器内不用动：

docker run -d --name grafana -p 13000:3000 -v grafana-storage:/var/lib/grafana grafana/grafana-oss:12.1.0

容器里的 Grafana 连不上宿主机的服务​

数据源 URL 填 localhost 或 127.0.0.1 是新手第一课：那指向的是 Grafana 容器自己。

  • macOS / Windows：用内置域名 host.docker.internal 指代宿主机。
  • Linux：启动时加 --add-host=host.docker.internal:host-gateway，或用 --network host。

更整洁的做法是给相关容器建一个共享网络，用容器名互访：

docker network create monitor
docker run -d --name prometheus --network monitor -p 9090:9090 prom/prometheus:v3.5.0
docker run -d --name grafana --network monitor -p 3000:3000 grafana/grafana-oss:12.1.0
# Grafana 里数据源 URL 填 http://prometheus:9090

登录页一直转圈、登录后空白​

  • 反向代理没转发 WebSocket：Grafana Live 实时推送走 WebSocket，Nginx 代理要加 Upgrade 和 Connection 头，否则页面卡在加载态。
  • root_url 配错：子路径部署（比如挂在 /grafana/ 下）时，[server] 段的 root_url 与代理路径不匹配会导致静态资源 404。打开浏览器开发者工具的 Network 面板，谁红了一目了然。
  • Save & Test 转圈或超时：回到「服务端视角」原则——进到 Grafana 容器里 curl 一下那个 URL，多半就不通了。

忘记 admin 密码​

不用重置数据，命令行直接改：

# 容器场景
docker exec -it grafana grafana-cli admin reset-admin-password NewPass123

# 裸机、brew 场景
grafana-cli admin reset-admin-password NewPass123

小结​

  • 安装三选一：Docker 最快（学习首选）、brew 适合 Mac 本机、apt 官方源适合 Linux 生产；K8s 交给 kube-prometheus-stack。
  • Docker 起步三要素：端口 3000、数据卷 grafana-storage、GF_SECURITY_ADMIN_PASSWORD 改初始密码。
  • 默认 admin/admin 登录后，先认五块界面区域：导航栏、搜索、用户菜单、面包屑收藏、帮助入口。
  • 接 Prometheus 数据源只改一个 URL，记住「服务端视角」和 host.docker.internal；Save & Test 绿了才算通。
  • 现成看板去 grafana.com/dashboards，ID 1860 导入即出图；配置集中在 grafana.ini，provisioning 目录和 SQLite 数据文件知道位置就行，下一篇细讲。

跑起来、接上数据、看到图，三部曲完成。下一篇用 provisioning 把这套「点鼠标配出来的环境」变成「YAML 声明出来的环境」，实现整个 Grafana 的可复制重建。