前言：为什么要有这篇笔记
最近在 https://pan.gxsnote.cn 上折腾 Files Gallery 这个文件管理器。官方称其为“单文件 PHP 文件管理器”，功能很全，支持图片、视频、PDF 预览和缩略图生成。不过，从部署到所有功能跑通，前前后后遇到了不少坑，尤其是缩略图生成这块。
索性把整个过程和解决方案记下来，方便自己以后查阅，也给可能遇到同样问题的朋友一个参考。
一、部署与初始配置
1.1 部署
部署很简单，从官网下载 index.php 上传到服务器目录就行。我的环境是：
- 服务器：CentOS 8 + nginx/1.30.3
- PHP：8.0.26（宝塔面板管理）
- 域名：pan.gxsnote.cn
首次访问 http://你的域名/index.php，程序会自动在 _files/config/ 目录下生成配置文件 config.php。
1.2 基础配置
配置文件里有很多选项，默认都是被 // 注释掉的。要想让某个配置生效，必须删除开头的 //。
比如，开启缩略图功能，需要确保这几项是 true 且未被注释：
'load_images' => true,
'image_resize_enabled' => true,
'image_resize_cache' => true,后续优化还会用到 image_resize_cache_use_dir 和 image_resize_dimensions_retina 等选项，具体见第五章。
二、第一个需求：隐藏 .开头的文件
我习惯把 .htaccess、.env 这类文件放在目录里，但不想在文件管理器里看到它们，显得乱。
官方文档提供了 files_exclude 和 dirs_exclude 两个配置项，支持正则表达式。
- 隐藏点开头的文件：
'files_exclude' => '/^\..*/', - 隐藏点开头的目录：
'dirs_exclude' => '/^\..*/',
修改 _files/config/config.php，去掉这两行前面的 //，保存刷新，世界清净了。
三、缩略图不显示？核心问题排查
上传了几张图片，发现缩略图出不来。这是 Files Gallery 最常见的问题，通常跟服务器环境有关。
3.1 诊断页面：第一手信息源
访问 http://你的域名/index.php?action=tests，可以看到详细的环境检测报告。我的初始报告里，gd、exif、imagick 都正常，但 ffmpeg、ghostscript、imagemagick 显示为 ❌。
3.2 安装缺失的工具
不同的文件类型需要不同的“帮手”来生成缩略图：
| 文件类型 | 需要的工具 |
|---|---|
| 普通图片 (jpg/png/gif) | GD 或 ImageMagick |
| 特殊图片 (HEIC/PSD/TIFF) | ImageMagick |
| ImageMagick + Ghostscript | |
| 视频 (mp4/webm等) | FFmpeg |
我的是 CentOS 系统，用 yum 安装：
# 安装 Ghostscript
yum install ghostscript -y
# 安装 FFmpeg（需要先添加 EPEL 和 RPM Fusion 源）
yum install epel-release -y
yum localinstall --nogpgcheck https://download1.rpmfusion.org/free/el/rpmfusion-free-release-8.noarch.rpm -y
yum install ffmpeg -y安装完后，在诊断页面里，ghostscript 和 imagemagick 都变成了 ✅，但 ffmpeg 依然是 ❌。
四、FFmpeg 的“顽疾”与解决
4.1 尝试指定路径
在配置文件中指定 ffmpeg 的完整路径：
'ffmpeg_path' => '/usr/bin/ffmpeg',但诊断页面依然显示失败。
4.2 PHP 调用测试
在根目录创建一个 test.php，测试 PHP 能否调用 ffmpeg：
<?php
exec('/usr/bin/ffmpeg -version 2>&1', $output, $return_code);
echo "返回码: " . $return_code . "\n";
echo "输出:\n" . implode("\n", $output);
?>访问 test.php，返回码 127，输出报错：
/usr/bin/ffmpeg: symbol lookup error: /lib64/libopenmpt.so.0: undefined symbol: mpg123_param2这是典型的动态链接库版本冲突——系统里的 libmpg123 版本太旧，不包含 FFmpeg 需要的 mpg123_param2 函数。
4.3 终极方案：静态编译版本
为了让 FFmpeg 彻底摆脱系统库的依赖，我用上了静态编译版本。它把所有依赖都打包进去了，不挑系统环境。
在 /usr/local/bin 目录下操作：
# 下载（如果服务器下载慢，可在本地下载后上传）
wget https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz
# 解压
tar -xf ffmpeg-release-amd64-static.tar.xz
# 复制并重命名为 ffmpeg-static，添加执行权限
cp ffmpeg-*-amd64-static/ffmpeg /usr/local/bin/ffmpeg-static
chmod +x /usr/local/bin/ffmpeg-static然后修改配置文件：
'ffmpeg_path' => '/usr/local/bin/ffmpeg-static',重启 PHP 服务，再次访问诊断页面——ffmpeg 终于变成了 ✅。
五、性能优化与配置调优
5.1 解决服务器负载过高问题
在完成缩略图功能配置后，我发现一个严重的问题：每当有用户访问包含大量图片或视频的文件夹时，服务器CPU就会瞬间飙升至100%，甚至导致服务器宕机。经过分析，原因是 Files Gallery 在首次访问文件夹时会高并发地生成大量缩略图，瞬间耗尽了服务器资源。
我的服务器配置是4核4GB，对于日常运行是够用的，但扛不住这种突发的高并发生成任务。因此，我从多个方面进行了优化：
5.1.1 调整PHP-FPM进程数（限制并发）
Files Gallery 的缩略图生成任务是由 PHP 进程执行的。通过限制同时处理的 PHP 进程数量，可以间接控制并发生成的任务数，避免服务器被瞬间压垮。
在宝塔面板中找到 PHP 设置（软件商店 → 已安装 → PHP 8.0 → 设置 → 性能调整），修改了以下几个关键参数：
pm.max_children = 10 # 最大子进程数，从默认的30调低到10
pm.start_servers = 3 # 启动时创建的进程数
pm.min_spare_servers = 3 # 空闲时最少保持的进程数
pm.max_spare_servers = 10 # 空闲时最多保持的进程数这样调整后，无论多少用户同时访问，服务器最多只会同时处理10个缩略图生成任务，避免了瞬间高并发。虽然其他用户可能需要排队等待，但服务器不会再宕机了。
5.1.2 开启本地缓存（image_resize_cache_use_dir）
这是 Files Gallery 官方推荐的一个优化选项。开启后，每个文件夹的缩略图缓存会直接存放在该文件夹下的 _files 子目录中，而不是统一存放在 _files/cache/images/ 目录下。
注意：此选项需要与 image_resize_cache 同时启用才能生效。
'image_resize_cache' => true,
'image_resize_cache_use_dir' => true,这样做的好处是：
- 缓存更稳定：即使你移动或重命名整个文件夹，缓存依然有效，避免了因路径变化而触发的重新生成。
- 便携性：可以在本地电脑上生成好所有缩略图，然后连同
_files文件夹一起上传到服务器，这样服务器就完全不需要生成缩略图了。
5.1.3 禁用高清屏双倍缩略图
Files Gallery 默认会为高清屏（Retina）生成双倍尺寸的缩略图，这会增加一倍的生成工作量。对于资源有限的服务器，建议禁用它：
'image_resize_dimensions_retina' => 0,这可以直接将缩略图生成的工作量减半。
5.1.4 限制单个IP的并发连接数
在 Nginx 配置中，我添加了以下规则，限制每个IP地址最多同时建立2个连接，防止单个浏览器发起太多并发请求：
# 在 server { ... } 块中添加
limit_conn perip 2;此指令依赖 Nginx 主配置中定义的 limit_conn_zone $binary_remote_addr zone=perip:10m;，如果你使用的是宝塔面板，该定义已默认存在。
5.1.5 最终效果
完成以上优化后，我又重新访问了包含几百个视频和图片的文件夹。这次服务器CPU虽然会持续保持在较高水平（因为要生成缩略图），但不会再瞬间拉满导致无法响应。在缩略图生成完毕后，CPU立刻降了下来，后续访问速度也快了很多。
如果你也遇到类似问题，建议按以下顺序操作：
- 先调整 PHP-FPM 进程数，这是保护服务器最直接的手段
- 确认
image_resize_cache_use_dir已启用 - 禁用
image_resize_dimensions_retina - 等待首次生成完成——只需忍耐这一次，以后就都好了
如果服务器资源实在有限，也可以在本地电脑上提前生成好所有缩略图（命名规则为 _files_原文件名.原扩展名.jpg），然后上传到对应目录，这样 Files Gallery 就会直接使用现成的缩略图，完全不需要服务器生成。
5.2 最终配置文件参考
以下是我优化后的完整 _files/config/config.php 配置，供参考：
<?php
// CONFIG / https://www.files.gallery/docs/config/
// Uncomment the parameters you want to edit.
return [
'load_images' => true,
'load_images_max_filesize' => 200000,
'image_resize_enabled' => true,
'image_resize_use_imagemagick' => true,
'image_resize_cache' => true,
'image_resize_cache_use_dir' => true,
'image_resize_dimensions_retina' => 0,
'cache' => true,
'image_cache_validate_time' => true,
'files_exclude' => '/^\\..*|\\.(php|zip)$/i',
'dirs_exclude' => '/^\\..*/',
'ffmpeg_path' => '/usr/local/bin/ffmpeg-static',
'imagemagick_path' => '/usr/bin/convert',
];六、最终状态与总结
目前，我的 Files Gallery 运行在 pan.gxsnote.cn，所有功能正常：
- ✅ 图片、PDF、视频缩略图正常生成
- ✅ 隐藏点开头的文件和文件夹
- ✅ 自定义网站标题
- ✅ 诊断页面所有关键项均为绿色 ✅
核心经验总结
- 诊断页面是你的第一信息来源：有问题先看
?action=tests。 - 缩略图问题 = 缺少工具 + 配置未生效：对症下药，安装对应的系统工具，并确保配置文件中对应的选项已取消注释。
- 依赖库冲突时，静态编译版本是终极武器：FFmpeg、ImageMagick 都有静态编译版本，可以绕开绝大多数系统环境问题。
- 性能优化的核心是减少并发和复用缓存：调整 PHP-FPM 进程数 + 开启本地缓存，能有效避免服务器宕机。
