故障概述

故障时间： 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 缓存

---

经验总结

成功因素

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

关键教训

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

可复用方案

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

• 所有使用 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分钟（从故障发现到完全解决）

后续提议：

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

---

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