企业官网建设流程全解析

最近后台有朋友连着问了我好几个关于 Debian 上部署 Grafana 的问题，从 apt 源装不上、Grafana 起不来，到面板导入之后数据源报错，基本上把新手能踩的坑踩了个遍。想想也是，Debian 作为服务器系统确实稳，但它的很多默认配置和 CentOS/RHEL 那套不太一样，第一次上手的人很容易在源头就卡住。我后来复盘了一下，发现大部分问题其实不是 Grafana 本身难搞，而是装 Grafana 之前的系统准备、安装方式选择、以及装完之后的配置细节没理顺。

这篇文章我就把自己在 Debian 11/12 上安装 Grafana 的完整流程、选型思路和排错记录都翻出来，从系统基础准备工作、四种安装方式对比、grafana.ini 关键配置、反向代理，到 Prometheus 数据源接入、面板导入与拷贝、再到 Alertmanager 告警链路和常见报错，一条线讲透。不管你是第一次在 Debian 上装 Grafana，还是从 CentOS 转过来被各种细节折磨的人，都可以直接照着做，少走几小时弯路。

1. 动手前先检查系统底子：网络、休眠与包管理

1.1 先把静态 IP 钉死，DHCP 会坑死监控

很多人装 Grafana 的第一步是直接apt install，但我建议先在 Debian 上把网络配置搞定。尤其是内网服务器默认走 DHCP 的情况，IP 地址一变化，Grafana 的访问地址、Prometheus 抓取地址全部失效，排查起来非常痛苦。之前有个同事的监控看板突然空白，最后发现是测试机的 IP 从 192.168.1.20 漂到了 192.168.1.35，Prometheus 还在照着旧 IP 拉数据，自然什么都拿不到。

Debian 12 如果用的是纯服务器版，默认走/etc/network/interfaces这套 ifupdown 管理，配置静态 IP 直接在文件里加一段就行：

# /etc/network/interfaces auto eth0 iface eth0 inet static address 192.168.1.20 netmask 255.255.255.0 gateway 192.168.1.1 dns-nameservers 223.5.5.5 8.8.8.8

改完执行systemctl restart networking或者直接reboot，再用ip addr和ip route检查一下确认生效。如果你装的是带桌面环境的 Debian，网络可能是由 NetworkManager 管的，那就更简单了，直接：

nmcli con mod "Wired connection 1" ipv4.addresses 192.168.1.20/24 nmcli con mod "Wired connection 1" ipv4.gateway 192.168.1.1 nmcli con mod "Wired connection 1" ipv4.dns "223.5.5.5 8.8.8.8" nmcli con mod "Wired connection 1" ipv4.method manual nmcli con up "Wired connection 1"

这里有个容易踩的坑：Debian 12 开始，NetworkManager 不一定会默认安装，所以你在nmcli遇到NetworkManager is not running时别慌，要么装一下network-manager，要么回退到 interfaces 文件配置。我个人建议服务器保持 ifupdown 风格，干净、稳定、不受桌面环境干扰。

1.2 顺手关掉休眠，别让监控主机睡过去

这个点很多人没想到，但 Debian 装在家里旧笔记本或者迷你主机上做监控机时特别常见。默认情况下，Ubuntu 系和 Debian 桌面版都会带电源管理策略，笔记本合上盖子就 suspend，一段时间不操作也可能自动休眠。如果 Grafana 跑在这台机器上，主机一睡，整个监控链路直接中断，而且你不在本机旁边的话，远程完全唤不醒它。

禁用休眠最干净的方法是直接把 systemd 的休眠目标给 mask 掉：

sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target

执行完可以用systemctl status sleep.target检查，看到状态是 masked 就说明 OK 了。另外还需要改一下 logind 配置，防止合盖触发生效：

# /etc/systemd/logind.conf HandleLidSwitch=ignore HandleLidSwitchExternalPower=ignore IdleAction=ignore

改完重启 logind：systemctl restart systemd-logind。我记得自己第一次在家里的迷你主机上部署 Grafana，没做这一步，结果第二天到了公司远程一查，看板停在昨晚十一点的数据上，整个人都麻了。现在只要装 Debian 做服务机，我都会先把休眠这事一次性处理掉。

1.3 APT 包管理与软件源准备，装依赖不再报错

Grafana 官方 apt 仓库安装方式其实很简单，但它依赖curl、gnupg2、apt-transport-https这些基础工具。干净的 Debian 系统上这些包不一定都有，尤其是 gnupg2，导致很多人导入 GPG key 的时候报gpg: command not found。所以我习惯在装任何东西之前先把基础工具装齐：

sudo apt update sudo apt upgrade -y sudo apt install -y curl wget gnupg2 apt-transport-https software-properties-common ca-certificates

Debian 的包管理底层是 dpkg，而 apt 是在它上面封装出来的更友好的工具层。很多人会把这两个概念混在一起，其实区别很简单：dpkg -i只能安装本地.deb文件，不会自动处理依赖；apt install会从软件源里拉包并自动解决依赖关系。所以除了确定要离线安装某个 deb 包之外，能用 apt 就用 apt。

另外提醒一下，如果你的服务器访问官方软件源特别慢，或者公司内网有镜像源，可以在/etc/apt/sources.list.d/下新建一个.list文件，把镜像源地址配进去。Debian 12 的源路径用的是deb.debian.org或者security.debian.org，换源之后务必执行apt update验证一下，避免源列表写错导致后续安装全挂。

1.4 顺手配好 SSH 免密，后面反复操作少输口令

虽说这步跟 Grafana 没有直接关系，但如果你要批量部署多台 Debian 节点，SSH 免密能省下大把时间。我常用的做法是本地生成密钥对，然后把公钥推到目标机器：

ssh-keygen -t ed25519 ssh-copy-id user@目标服务器IP

如果你不想给私钥设置 passphrase，直接一路回车就行。但是生产环境我建议给私钥加口令，然后用ssh-agent托管，这样既能保证安全，又不用每次连接都手动输入口令。这个习惯配合自动化脚本，后面部署 agent、拉取配置会顺手很多。

2. 安装 Grafana 的四种方式，按场景选一种就行

2.1 官方 APT 仓库安装，最省心的选择

如果你没有特殊要求，我个人最推荐官方 apt 仓库方式。理由很简单：它会写入 Grafana 官方源，后续apt update && apt upgrade的时候，Grafana 会和系统其他软件一起自动升级，不需要手动维护版本。同时 apt 会自动处理依赖，装完用 systemd 管理，卸载也干净。

具体步骤，先导入 GPG key：

wget -q -O - https://packages.grafana.com/gpg.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/grafana.gpg > /dev/null

再添加 apt 源：

echo "deb [signed-by=/etc/apt/trusted.gpg.d/grafana.gpg] https://packages.grafana.com/oss/deb stable main" | sudo tee /etc/apt/sources.list.d/grafana.list

然后更新索引并安装：

sudo apt update sudo apt install -y grafana

安装完成后，先重载 systemd 再启动服务：

sudo systemctl daemon-reload sudo systemctl enable --now grafana-server

验证是否起来，可以用端口检查和 API 健康检查两种方式：

ss -lntp | grep 3000 curl http://localhost:3000/api/health

如果返回{"commit":"...","database":"ok","version":"11.x.x"}，就说明服务已经正常跑起来了。此时浏览器访问http://服务器IP:3000，默认用户名和密码都是 admin，首次登录会强制要求改密码。

2.2 二进制 deb 包手动安装，适合离线网环境

有些内网环境访问不了外网，或者你对 Grafana 版本有严格锁定要求，不想被apt upgrade悄悄升掉版本，那就适合直接下载 deb 包手动安装。Grafana 官方把二进制包都放在https://dl.grafana.com/oss/release/下，文件名格式类似grafana_11.2.0_amd64.deb。

以 11.2.0 为例：

wget https://dl.grafana.com/oss/release/grafana_11.2.0_amd64.deb sudo dpkg -i grafana_11.2.0_amd64.deb

如果报依赖缺失，比如缺了某些 libc 库，用sudo apt -f install修一下依赖就行。装完之后同样用 systemd 启动：

sudo systemctl daemon-reload sudo systemctl enable --now grafana-server

这里有一个细节：dpkg 方式安装的 Grafana 版本是固定的，但在下次apt upgrade时，如果系统能解析到官方源，它仍然可能被升级。不想让它升，就得锁版本：

sudo apt-mark hold grafana

执行后可以apt policy grafana查看状态，看到apt-mark showhold里有 grafana 就表示已经锁住了。这个做法适合那些 Grafana 版本跟旧版面板插件强绑定的场景，我遇到过几次因为升级后某个数据源插件不兼容，导致面板大面积报错的事，所以生产环境保守一点没坏处。

2.3 Docker 方式，五分钟拉起一个 Grafana

如果你对容器比较熟，或者本来就在用 Docker 跑 Prometheus 那一套，那 Grafana 直接容器化反而最干净。前提是先装好 Docker，Debian 上装 Docker 的命令不算复杂，装完直接用官方镜像：

docker run -d \ --name=grafana \ --restart=always \ -p 3000:3000 \ -v grafana-data:/var/lib/grafana \ grafana/grafana:latest

这里重点说一下-v grafana-data:/var/lib/grafana。很多新手图方便直接docker run不挂卷，结果容器一删，所有配置、面板、数据源全部归零，哭都来不及。用命名卷之后，即使容器删了重建，数据还在。你也可以把宿主机目录映射进去，比如-v /data/grafana:/var/lib/grafana，这样备份更直观。

Docker 方式有几个好处：一是宿主机很干净，不会残留一堆配置文件；二是版本切换方便，换镜像 tag 重启容器就行；三是 Grafana 和其他监控组件可以一起用 docker-compose 编排。缺点是容器内时间默认 UTC，如果看板时区显示不对，需要在环境变量里加TZ=Asia/Shanghai：

docker run -d \ --name=grafana \ --restart=always \ -e TZ=Asia/Shanghai \ -p 3000:3000 \ -v grafana-data:/var/lib/grafana \ grafana/grafana:latest

2.4 不同安装方式的选型建议

我用一个表格把三种方式横向对比一下，方便你根据场景快速做决定：

我的建议是：如果服务器能访问外网，直接用官方 apt 仓库；如果公司有内网镜像或者要离线交付，用 deb 包配合apt-mark hold；如果你本来就把监控组件跑在容器里，那 Docker 方式最统一。三种方式装完之后的配置逻辑其实完全一样，接下来讲的内容都可以通用。

3. 装好之后的部署细节：别让服务裸奔

3.1 用 systemd 管好 Grafana 服务生命周期

无论哪种方式安装，最终在 Linux 上 Grafana 都是以后台服务方式运行的。apt 和 deb 包安装默认会注册 systemd 服务单元，文件在/usr/lib/systemd/system/grafana-server.service。Docker 方式虽然不需要 systemd，但也要靠--restart=always保证容器挂了能自动拉起。

我常用的几个 systemd 命令顺手列一下：

# 查看状态 systemctl status grafana-server # 重启服务 systemctl restart grafana-server # 实时查看日志 journalctl -u grafana-server -f

日志这个环节要重点说。Grafana 默认把运行日志写在/var/log/grafana/目录，但 systemd 环境下用journalctl查看最方便，尤其是排查启动失败时，journalctl -u grafana-server -f能看到完整的报错栈。一次典型的启动失败会看到类似level=info msg="Starting Grafana"后面紧跟 error 信息，根据关键字就能快速定位是端口被占用、数据库文件权限不对，还是配置文件语法错误。

3.2 grafana.ini 核心配置项，运行前先过一遍

Grafana 的主配置文件在/etc/grafana/grafana.ini，里面大部分配置默认是被注释的，理论上开箱即用，但有几个关键项我强烈建议你手动确认一遍。

[server] http_port = 3000 domain = your-domain.com root_url = %(protocol)s://%(domain)s:%(http_port)s/ [security] admin_user = admin admin_password = 一个足够强的密码 ;disable_gravatar = true [users] allow_sign_up = false [auth.anonymous] enabled = false [database] type = sqlite3 path = /var/lib/grafana/grafana.db

• [server]里的domain和root_url决定了页面里生成的回调链接。如果你用了 Nginx 反代和域名访问，root_url必须写成外部访问地址，否则会出现登录成功后被跳回内网 IP、回调地址不对之类的问题。
• [security]里的admin_password建议在安装后立刻通过界面改掉，或者直接在这里预设强密码。要注意配置文件权限，避免普通用户可读。
• [users]的allow_sign_up默认关闭，保持关闭就对了，避免随意注册账号。
• 默认数据库是 SQLite，文件在/var/lib/grafana/grafana.db，数据量不大时完全够用。等你可以同时对几十上百台机器做监控时，再考虑迁移到 MySQL 或 PostgreSQL。

改完配置记得重启服务生效：systemctl restart grafana-server或者 Docker 方式docker restart grafana。

3.3 用 Nginx 反代和 HTTPS 统一入口

Grafana 默认站点没有 TLS，如果只是内网访问，问题不大。但如果要跨网络访问，或者对安全性有要求，强烈建议在前面套一层 Nginx 做反向代理，配合证书把 HTTPS 加上。这不光是为了安全，也是为了让 Grafana 对外统一暴露一个稳定的入口，以后端口、IP 变动都不用告诉业务方。

Nginx 配置示例：

server { listen 80; server_name grafana.example.com; location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

记得在grafana.ini里把root_url改成https://grafana.example.com/，这样 Grafana 生成的重定向和回调地址才能正确。Nginx 的proxy_set_header X-Forwarded-Proto $scheme也不能漏，Grafana 依赖这个头判断客户端访问协议，少了它 HTTPS 环境下可能会不断跳回 http。

3.4 防火墙和基础安全加固

Debian 默认不装 UFW，很多人装完 Grafana 就直接裸奔了。如果你对 iptables 不熟，可以直接用 UFW 快速放行：

sudo apt install ufw sudo ufw allow OpenSSH sudo ufw allow 3000/tcp sudo ufw enable

如果前面配置了 Nginx 反代，那3000端口只需要监听本地，对外只放行80/443。这种方式更安全，Grafana 完全在内网环境运行，外面访问只看到 Nginx。

另外有个细节：Grafana 的管理员账号密码务必要改，尤其是暴露到公网的时候，默认 admin/admin 会被暴力扫描器秒破。之前有个朋友在云服务器上装完 Grafana 忘了改密码，两天后就被塞了一堆恶意的数据源配置，内存直接被打满。

4. 接入数据源：让看板真正“有数可看”

4.1 接入 Prometheus 数据源，最主流的组合

虽然 Grafana 本身支持非常多的数据源，包括 MySQL、PostgreSQL、InfluxDB、Loki 等，但最经典的组合还是 Prometheus + Grafana。Grafana 负责可视化面板，Prometheus 负责指标采集和时序存储。

在 Grafana 界面左侧选择 Connections，然后点 Add data source，选 Prometheus，主要填两个关键信息：

• URL：Prometheus 服务地址，一般是http://你的PrometheusIP:9090
• Access：默认是 Server，也就是 Grafana 服务端主动去访问 Prometheus。如果你在浏览器本机直接访问 Grafana，也可以选 Browser，但生产环境建议 Server，避免用户浏览器直接暴露内网拓扑。

填完之后点 Save & Test，如果看到绿色的 Data source is working，就说明连接成功。常见报错之一是Error reading Prometheus: Post "http://...": http: server gave HTTP response to HTTPS client，这个报错的意思是 Prometheus 本身是 HTTP 服务，但 Grafana 用了 HTTPS 去访问，URL 写成了https://开头。把 URL 改成http://即可。

如果你是容器化部署 Prometheus 和 Grafana，推荐直接用 docker 网络互联，URL 写成服务名就行，比如http://prometheus:9090，比写容器 IP 稳定得多。

4.2 接入 MySQL / PostgreSQL 等其他数据源

Grafana 不只是时序监控的专属看板，它也能直接连关系型数据库做业务报表。比如你想把订单量、用户增长、接口响应时间这些业务数据从前端送过来，最直接的方式就是让 Grafana 连业务库，通过 SQL 查询做图表。

添加数据源时选择 MySQL，填上主机、端口、数据库名、账号密码就行。这里有两个容易踩的坑：

第一个是权限。别直接用业务主账号连 Grafana，建议单独建一个只读账号：

CREATE USER 'grafana'@'%' IDENTIFIED BY '强密码'; GRANT SELECT, SHOW DATABASES, SHOW VIEW ON *.* TO 'grafana'@'%'; FLUSH PRIVILEGES;

这样即使 Grafana 被拖库，攻击者也只能读数据，不能改数据。

第二个是时区。Grafana 默认按 UTC 处理时间，如果你的业务库表存的是本地时间，查出来的图表会整体漂移 8 个小时。解决办法是在数据源配置里把 Session 时区或者连接时区设为Asia/Shanghai，或者查询时用CONVERT_TZ()函数显式转换。我建议尽量让数据在写入时统一用 UTC 或时间戳类型，展示层再处理时区转换，这样最不容易出错。

4.3 一个实用建议：数据源命名与环境隔离

很多团队一套 Grafana 同时接了开发、测试、生产三个环境的数据源，面板还全混在一起。这时候建议在数据源名称里加上环境前缀，比如prod-prometheus、dev-prometheus，然后在面板模板变量里绑定数据源，这样复制面板到不同环境时，只要切换数据源就行，不用改面板内所有查询。

Grafana 支持在 Dashboard 里设置模板变量，数据源类型变量可以直接和面板查询联动。我之前给一个客户搭监控，他一开始二十多台机器全塞在一个面板里，切环境全靠手改查询语句，后来我把数据源抽出来做变量，整个面板瞬间清爽了，复制到新环境只要一分钟。

5. 面板操作与告警链路打通

5.1 从模板市场导入现成看板，别自己从零画

搭建监控看板最忌讳的事情就是从零开始画图表。Grafana 社区有非常成熟的面板模板库，地址是https://grafana.com/grafana/dashboards/，你只需要在搜索框输入想要的指标类型，比如 Node Exporter Full、MySQL Overview，通常能找到上千星的现成模板。

导入流程很简单：左侧 Dashboards 菜单，点 New，选 Import，输入模板 ID 或者直接上传 JSON 文件，然后选择目标数据源，重要的一步是在导入页面最下方选择一个已有的数据源，否则面板导入后所有查询都会标红。像 Node Exporter 全平台监控模板 1860、Prometheus 2.0 Overview 模板 3662，这些都是经典模板，导入后改一下数据源就能用。

有一个提醒：模板作者用的指标名可能跟你当前环境不一致，比如他用了node_cpu_seconds_total，你的 node_exporter 版本老，可能还是node_cpu。导入后如果图表无数据，可以先在 Explore 里跑一下对应 PromQL，确认指标是否存在，再决定是升级 exporter 还是改查询。

5.2 拷贝整个面板的几种方式，uid 冲突是重灾区

日常运维中经常遇到“这个面板在测试环境调好了，要复制到生产环境”，或者“用户让我帮他把看板搬到另一套 Grafana 上”。拷贝整个面板看起来简单，实际坑不少。

最直接的方式是进入 Dashboard Settings，切到 JSON Model 标签页，全选复制里面的 JSON，然后到目标环境新建面板，同样进入 JSON Model 里粘贴，保存即可。这种方式最大的问题是 uid 冲突。如果源面板 uid 和目标环境已有面板重复，保存时会报错或者覆盖掉已有面板，处理办法是导入前把 JSON 里的"uid"字段删掉或者改成一个全新值。

另外还有两种更省事的做法：

第一种是直接在 Dashboards 列表页勾选面板，点 Export，把 JSON 文件导出，再到目标环境上传导入，导入时勾选“Change uid”，会得到一个全新 uid，避免冲突。

第二种是如果你只是想在同一个 Grafana 实例里复制面板做变体，打开 Dashboard，右上角 Settings，选 Save As，填一个新名字保存，就得到一份独立副本。这个操作不改 uid 的情况下，两个面板会共用同一份 API Key 权限，但不算大问题。

5.3 Grafana 接入 Alertmanager，把告警链路串起来

Prometheus 生态里，Alertmanager 专门负责告警的分组、抑制和路由，Grafana 负责可视化。有人会用 Grafana 本身的告警规则，有人则希望统一由 Alertmanager 处理告警，Grafana 只做展示。这两种方式不冲突，甚至可以共存在一套监控体系里。

如果选择让 Grafana 直接发告警，步骤是：Alerting 菜单里新建 Contact point，选择通知类型，比如 webhook、邮件、钉钉、企业微信等，配置好接收地址。然后新建 Alert rule，关联数据源和查询条件，设置阈值和评估频率。触发后 Grafana 会往通知渠道发送消息。

如果选择接入 Alertmanager，则是在 Grafana 的 Alerting 里配置数据源类型为 Alertmanager，填入 Alertmanager 地址，通常是http://你的AlertmanagerIP:9093。这样 Grafana 就能展示 Alertmanager 当前收到的告警，也能在面板里制作告警状态图表。但要注意，已经由 Prometheus 规则产生的告警，Grafana 展示的是结果，而不是重新计算。

一个典型方案是：Prometheus 负责抓取指标并按照 rules 文件计算告警规则，命中后推送 Alertmanager，Alertmanager 根据 route 规则做分组、抑制，最后发到钉钉或者企业微信。Grafana 只负责把告警状态可视化出来。这个链路的好处是告警策略集中在 Prometheus 配置里，跟监控任务放在一起，管理起来清晰。

5.4 告警通知渠道配置示例

以 webhook 和邮件两个常见渠道为例。webhook 适合接到内部即时通讯机器人，配置一个接收回调地址就行。比如企业微信群机器人 webhook，地址形如：

https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=你的key

在 Grafana Contact point 里选择 Webhook，把上面的地址填进 URL，消息模板保持默认即可。邮件渠道则需要配置 Grafana 的 SMTP，在grafana.ini的[smtp]段：

[smtp] enabled = true host = smtp.example.com:587 user = alert@example.com password = 邮箱密码或授权码 from_address = alert@example.com from_name = Grafana Alert

需要特别提醒的是，邮件端口 25 在很多云厂商默认被封，尽量用 465 或 587，并配合 STARTTLS 或 SSL 才能发出去。公司内部如果部署了自己的邮件系统，直接填内部 SMTP 地址通常最省心。

6. 高频报错与排查实录

6.1 面板报“failed to upgrade legacy queries datasource”怎么办

这个报错在 Grafana 升级到较新版本后非常常见，尤其是面板从旧版 6.x、7.x 迁移上来时。完整的报错文本通常是这样：

failed to upgrade legacy queries datasource xxx was not found

这个xxx是一串数据源 uid，比如im7_otuvz。出现原因很简单：旧版面板里的某个查询绑定了一个数据源 uid，但新版 Grafana 里这个数据源不存在了（可能是数据源被删除、uid 变更，或者数据源类型被迁移）。Grafana 在加载面板时会尝试把旧查询格式升级成新版格式，结果发现绑定的数据源找不到，于是直接报错。

排查步骤是这样：

1. 进入面板编辑模式，切到 JSON Model，搜索datasource关键字，找到所有引用 uid 的地方。
2. 记录下报错中提示的 uid。
3. 在 Connections 数据源列表中找到你当前实际要用的数据源，进入它的设置页面，URL 末尾那一串就是 uid。
4. 把 JSON 里所有指向旧 uid 的字段替换成新 uid。

如果面板里引用 uid 的地方太多，手动替换很痛苦，也可以用 jq 处理。另外还有一个偷懒的办法：如果整个面板都是旧数据源类型导致的兼容性问题，直接从模板市场重新导入一个新版面板，把模板变量切换成现有数据源，比手动修 JSON 更省事。

6.2 apt 安装时 GPG 公钥报错

这个错在 Debian 上很典型：

W: GPG error: https://packages.grafana.com/deb stable InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 4D40D18F7F0E7C85

出现原因通常是首次添加 Grafana 源时没有把 GPG key 正确导入，或者导入位置不对。Debian 12 要求 key 放在/etc/apt/trusted.gpg.d/下，并且源列表里用signed-by显式指定 key 路径，像我前文写的那样。如果用的是旧式apt-key add方式，新版本 apt 会直接忽略，导致签名验证失败。

解决方法是重新执行一次导入命令：

wget -q -O - https://packages.grafana.com/gpg.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/grafana.gpg > /dev/null

然后确认/etc/apt/sources.list.d/grafana.list这行里的路径和 key 文件路径一致，再apt update就不会报错了。

6.3 grafana-server 启动失败，学会看日志

服务启动失败的原因五花八门，但排查思路是一致的：先看状态，再看日志。

systemctl status grafana-server journalctl -u grafana-server -n 50

常见问题有这么几类：

• 端口被占用。检查 3000 端口，ss -lntp | grep 3000或者lsof -i:3000，有别的进程占用就改 Grafana 的http_port，或者先杀掉占用进程。
• 目录权限不对。默认数据目录/var/lib/grafana、日志目录/var/log/grafana、配置目录/etc/grafana的属主必须是grafana用户。如果之前用 root 跑过，或者目录是从别处拷贝来的，很容易出现 permission denied。修复方法：

sudo chown -R grafana:grafana /var/lib/grafana /var/log/grafana

• 数据库文件损坏。SQLite 模式偶尔会因为异常断电导致 grafana.db 损坏，日志里会看到database is locked或disk I/O error。这种情况下，先备份原文件，然后停止服务，删除或重命名 grafana.db 再启动，服务会重新初始化一个空库。数据源和面板会丢，所以好的习惯是定期备份。

关于备份，我再多提一句：Grafana 的配置、数据源、面板全存在 grafana.db 里，但 api key、用户信息也在里面。最简单的备份就是定时把这个文件复制出来。我一般用 cron 每天凌晨打包一次：

0 2 * * * tar -czf /backup/grafana_$(date +\%F).tar.gz /var/lib/grafana/grafana.db /etc/grafana/grafana.ini

恢复的时候把文件和配置放回去重启服务就行，比其他方案都直接。

6.4 时区不对，图表时间漂移八小时

这个问题我前面提过，但值得再单独说一遍，因为遇到的人实在太多。Grafana 默认以 UTC 为基准显示时间，哪怕你的浏览器时区是 Asia/Shanghai，面板默认设置依然是 UTC。结果就是：你上午 10 点看到的图，x 轴时间却显示凌晨 2 点。

两个修复入口：

一个是在每个面板右上角设置里，将 Timezone 改成 Asia/Shanghai 或 Local browser time。这个只对当前面板生效。

另一个更推荐的做法是手工修改 Dashboard 的 JSON Model，在"timezone": "browser"位置统一改掉，然后保存。如果是 Docker 容器部署的 Grafana，还要额外设置环境变量TZ=Asia/Shanghai，否则容器内时间的默认值还是 UTC，某些插件的内部逻辑依然会按 UTC 取时间。

我当时在一套混合云监控项目里就吃过这个亏，节点上线时间全部显示成 GMT，当时还以为是什么神秘 bug，最后发现就是面板时区配置的锅。从那之后，凡是新装一套 Grafana，我做的第一件事不是建数据源，而是先检查时区设置。

最后再说几句实在话

很多人觉得装 Grafana 是网上随便搜条命令就能搞定的事，但真到自己搭的时候，往往会在系统准备、版本选择、数据源关联这些小地方反复折腾。根据我自己的实际体验，最容易让人崩心态的问题基本都集中在三件事：数据源连不上、面板导入后数据源失效、告警通知反复测试不成功。这三件事没有一件是“代码写错”导致的，基本都是配置上下文没对齐。

所以我会建议你在一开始就把基础打牢：Debian 的静态 IP、休眠策略、软件源、系统时间，这些看起来跟 Grafana 无关的细节，反而是后面稳定运行的基石。同时候养成一个习惯，每次改完grafana.ini或者导入导出面板之前，先手动备份一次配置文件和 SQLite 数据库。很多时候你排查了半天，最后发现还不如花一分钟把备份恢复回去来得快。

还有一个小技巧算是个人经验吧：面板 JSON 是一种非常通用的资产，我一般会把环境里做好的经典面板导出成 JSON 文件，存到一个 Git 仓库里，跟配置文件一起做版本管理。这样每次升级 Grafana 或者迁移环境，我都可以快速重建出一模一样的看板，不会出现升级之后某个面板“找不到数据源”就只能干瞪眼的情况。这个习惯看着不起眼，真正用上的时候，能帮你省下一整个下午的时间。