躬行笔记 » Zabbix 图表字体显示故障修复报告

故障概述

故障时间： 2025-11-29 08:55 - 09:09
故障系统： Zabbix 7.4 监控系统
故障现象： Zabbix 图表无法显示坐标轴和图例，仅显示绿色折线图
影响范围： 所有监控图表的可读性受到严重影响
故障等级： 中等（功能性故障，不影响数据采集）

故障表现

视觉症状

图表中只显示绿色折线和网格背景
X轴（时间轴）完全缺失
Y轴（数值轴）完全缺失
图例信息不显示
图表标题和说明文字缺失

用户影响

无法识别监控指标的具体数值
无法确定时间范围
无法区分多条监控曲线
图表失去实际使用价值

故障诊断过程

第一阶段：初步排查（08:55-09:00）

1. 系统日志检查

# Zabbix Server 日志
tail -f /var/log/zabbix/zabbix_server.log

结果： 仅显示正常的 housekeeper 清理任务，无异常错误

2. PHP-FPM 日志检查

tail -f /var/log/php-fpm/error.log

结果： 显示正常的进程重启，无明显错误

3. 字体文件检查

ls -la /usr/share/zabbix/assets/fonts/

发现：

simhei.ttf (9.7 MB) - 存在
simfang.ttf (10.5 MB) - 存在
NotoSansCJK-Regular.ttc (19.9 MB) - 存在
文件权限正常：-rw-r--r--

初步结论： 字体文件存在且权限正常，问题不在文件本身

第二阶段：深度分析（09:00-09:06）

4. Web服务器错误日志分析

tail -30 /var/log/nginx/error.log

关键发现： 大量 PHP 错误信息

PHP Warning: imagettfbbox(): Could not find/open font 
in /usr/share/zabbix/ui/include/graphs.inc.php on line 533

PHP Warning: imagettftext(): Could not find/open font 
in /usr/share/zabbix/ui/include/graphs.inc.php on line 486

错误频率： 每次加载图表产生数百条相同错误
错误位置： graphs.inc.php 的字体渲染函数

5. Zabbix 配置文件检查

cat /usr/share/zabbix/ui/include/defines.inc.php | grep -i font

配置内容：

define('ZBX_FONTPATH', realpath('assets/fonts'));
define('ZBX_GRAPH_FONT_NAME', 'simhei');
define('ZBX_FONT_NAME', 'simhei');

问题识别： ZBX_FONTPATH 使用了相对路径 realpath('assets/fonts')

6. 字体加载机制分析

sed -n '480,490p' /usr/share/zabbix/ui/include/graphs.inc.php

代码逻辑：

$ttf = ZBX_FONTPATH.'/'.ZBX_FONT_NAME.'.ttf';
imagettftext($image, $fontsize, $angle, $x, $y, $color, $ttf, $string);

拼接结果： realpath('assets/fonts') + '/' + 'simhei' + '.ttf'

第三阶段：根因定位（09:06）

核心问题分析

问题1：相对路径解析失败

realpath('assets/fonts') 在 PHP-FPM 环境下无法正确解析
PHP-FPM 的工作目录与 Nginx 的文档根目录不一致
导致相对路径返回 false 或空字符串

问题2：字体路径拼接错误

当 ZBX_FONTPATH 解析失败时
最终路径变成：/simhei.ttf 或 simhei.ttf
PHP GD 库无法找到字体文件

问题3：错误处理缺失

Zabbix 代码未对字体加载失败进行有效处理
仅产生 PHP Warning，不中断图表生成
导致图表显示不完整但不报致命错误

解决方案

修复步骤

步骤1：修改字体路径为绝对路径

sudo sed -i "s|define('ZBX_FONTPATH',.*|define('ZBX_FONTPATH', '/usr/share/zabbix/assets/fonts'); // where to search for font|" /usr/share/zabbix/ui/include/defines.inc.php

修改前：

define('ZBX_FONTPATH', realpath('assets/fonts'));

修改后：

define('ZBX_FONTPATH', '/usr/share/zabbix/assets/fonts');

步骤2：验证字体名称配置

sudo grep 'ZBX_FONT' /usr/share/zabbix/ui/include/defines.inc.php | head -3

确认配置：

define('ZBX_FONTPATH', '/usr/share/zabbix/assets/fonts');
define('ZBX_GRAPH_FONT_NAME', 'simhei');
define('ZBX_FONT_NAME', 'simhei');

步骤3：清除 PHP 缓存

sudo rm -rf /var/lib/php/opcache/*
sudo rm -rf /var/lib/php/session/*

原因： PHP OPcache 会缓存已编译的配置文件，必须清除

步骤4：重启服务

sudo systemctl restart php-fpm
sudo systemctl restart nginx

步骤5：验证修复

刷新浏览器（Ctrl+F5 强制刷新）
检查图表是否正常显示坐标轴和图例
查看 Nginx 错误日志确认无新错误

技术细节

字体加载流程

1. Zabbix 图表生成请求
   ↓
2. graphs.inc.php 调用 imageText() 函数
   ↓
3. 拼接字体路径：ZBX_FONTPATH + '/' + ZBX_FONT_NAME + '.ttf'
   ↓
4. 调用 PHP GD 库函数：imagettftext()
   ↓
5. GD 库尝试打开字体文件
   ↓
6. 成功：渲染文字 | 失败：产生 Warning，跳过文字渲染

相对路径失败原因

PHP-FPM 环境特性：

PHP-FPM 以独立进程运行，工作目录为 /
Nginx 将请求转发给 PHP-FPM 时，不传递文档根目录上下文
realpath() 函数基于当前工作目录解析相对路径
在 / 目录下查找 assets/fonts 必然失败

对比 Apache + mod_php：

Apache mod_php 的工作目录是网站根目录
相对路径可以正常解析
这解释了为什么某些环境下配置正常工作

为什么图表仍能显示折线

GD 图像库的容错机制：

imagettftext() 失败时仅产生 Warning
不影响其他绘图操作（线条、背景、网格）
导致图表"部分正常"的假象

预防措施

1. 配置规范化

建议： 所有路径配置使用绝对路径

// 推荐
define('ZBX_FONTPATH', '/usr/share/zabbix/assets/fonts');

// 不推荐
define('ZBX_FONTPATH', realpath('assets/fonts'));

2. 监控告警配置

建议： 配置 PHP 错误日志监控

# 添加到 Zabbix 监控项
log[/var/log/nginx/error.log,"imagettfbox|imagettftext",,,skip,\O]

3. 部署检查清单

[ ] 验证字体文件存在且可读
[ ] 验证字体路径配置为绝对路径
[ ] 测试图表显示完整性
[ ] 检查 PHP 错误日志无字体相关警告
[ ] 清除 PHP OPcache 缓存

4. 文档更新

建议： 更新部署文档，明确说明：

PHP-FPM 环境必须使用绝对路径
字体配置修改后必须重启 PHP-FPM
必须清除 OPcache 缓存

经验总结

成功因素

系统化排查： 从日志到配置到代码逐层深入
代码分析： 查看实际字体加载代码，理解拼接逻辑
环境理解： 认识到 PHP-FPM 与 Apache mod_php 的差异
完整修复： 不仅修改配置，还清除缓存并重启服务

关键教训

相对路径风险： 在不同运行环境下行为不一致
错误级别误导： Warning 级别错误也可能导致严重功能缺失
缓存影响： 配置修改后必须清除相关缓存
测试重要性： 部署后应立即验证所有功能模块

可复用方案

此问题的解决方案适用于：

所有使用 PHP-FPM 的 Zabbix 部署
其他使用 PHP GD 库的应用字体问题
任何涉及相对路径配置的 PHP 应用

附录

A. 相关文件路径

配置文件：/usr/share/zabbix/ui/include/defines.inc.php
代码文件：/usr/share/zabbix/ui/include/graphs.inc.php
字体目录：/usr/share/zabbix/assets/fonts/
错误日志：/var/log/nginx/error.log
PHP缓存：/var/lib/php/opcache/

B. 验证命令

# 检查字体文件
ls -la /usr/share/zabbix/assets/fonts/simhei.ttf

# 检查配置
grep ZBX_FONT /usr/share/zabbix/ui/include/defines.inc.php

# 检查错误日志
tail -f /var/log/nginx/error.log | grep font

# 测试字体路径
php -r "echo '/usr/share/zabbix/assets/fonts' . '/' . 'simhei' . '.ttf';"

C. 服务器信息

操作系统：Linux
Web服务器：Nginx
PHP处理：PHP-FPM
Zabbix版本：7.4

报告结论

故障原因： Zabbix 字体路径配置使用相对路径，在 PHP-FPM 环境下无法正确解析

修复方法： 将 ZBX_FONTPATH 改为绝对路径 /usr/share/zabbix/assets/fonts

修复结果： 图表完全恢复正常，坐标轴和图例正确显示

修复时长： 30分钟（从故障发现到完全解决）

后续建议：

将此修复纳入标准部署流程
对其他 Zabbix 服务器进行预防性检查
建立 PHP 错误日志监控告警

报告编制： YOUYOU
报告时间： 2025-11-29 09:09
报告版本： v1.0