Flyimg 1.12.10 安装:Ubuntu 22.04 源码直装与 systemd 服务化

目标:在 Ubuntu 22.04 真机上以源码方式完成 Flyimg 1.12.10 的从零安装——PHP 8.3 运行时与扩展、composer 依赖、nginx + php-fpm 站点、目录权限、systemd 托管与 cron 清理任务,并以真实 URL 请求验收图片处理与缓存能力。本文全部命令与回显均为 2026-10-28 在 Ubuntu 22.04.5 LTS 真机逐条实测;组件定位与同类对比见 《Flyimg 认知选型:按需图片处理服务的定位、原理与同类方案对比》。

一、环境信息

• 操作系统:Ubuntu 22.04.5 LTS x86_64(systemd 可用);
• PHP:8.3.36(NTS,来源 deb.sury.org 源,包名 8.3.36-1+ubuntu22.04.1+deb.sury.org+1);
• Web 服务:nginx/1.18.0(Ubuntu 官方仓库);
• 应用栈:Flyimg 1.12.10(git clone 钉版,源码 HEAD commit 2878b1b chore(release): 1.12.10 [skip ci]),composer 2.x;
• 部署目录:/var/www/flyimg,Web 根 /var/www/flyimg/web,缓存 web/uploads,临时 var/tmp;
• 服务端口:80(实测环境通过反向端口 8146 暴露,正文统一写 80);
• 源图服务器:局域网内 192.168.1.10:8000 提供静态原图(实测用 2266x1957 JPEG,1,025,710 字节),用于验收拉图与处理。

⚠️ 网络说明:实测环境访问 github.com 较慢,git clone 与 composer 走默认源均可用但耗时较长;若官方源超时,可按「官方源 → 国内加速 → 代理」降级链处理(如给 git/composer 配代理)。本文实测主渠道成功,未发生下载渠道切换;GitHub REST API 查询版本时曾遇到匿名限额(rate limit exceeded),版本核对降级到 Packagist p2 源完成,详见选型篇环境信息一节。

二、版本选型与前置条件

2.1 版本选型说明

Flyimg 采用语义化版本,1.12.10 为 2026-10-28 经 Packagist 官方源核实的最新稳定版(Packagist p2 源返回版本列表首位)。版本核对命令:

# 从 Packagist 官方源取最新版本列表(前 5 个)
curl -s "https://repo.packagist.org/p2/flyimg/flyimg.json" | python3 -c "
import json,sys
d=json.load(sys.stdin)
vs=[p['version'] for p in d['packages']['flyimg/flyimg']]
print('最新版本列表(前5):', vs[:5])
"

实测回显:

最新版本列表(前5): ['1.12.10', '1.12.9', '1.12.8', '1.12.7', '1.12.6']

PHP 版本约束:源码 composer.json 实证为 php >=8.1。Ubuntu 22.04 官方仓库的 PHP 8.1 满足该约束;本文实测选 PHP 8.3(deb.sury.org 源),以获得更好的性能与更长的安全维护期。未实测项标注:PHP 8.1 路径预期同样可用(满足 composer 约束),但本文全部回显来自 8.3.36。

2.2 前置条件:系统依赖

安装 PHP-FPM、nginx、git、composer 及 Flyimg 必需扩展:

# 先启用 deb.sury.org 的 PHP 源(若用官方 8.1 可跳过本步)
add-apt-repository -y ppa:ondrej/php && apt-get update -y

# 安装 PHP-FPM、nginx、git、composer 与关键扩展
apt-get install -y php8.3-fpm php8.3-cli php8.3-imagick php8.3-gd nginx git composer

实测回显(输出节选,实测首尾):

Setting up php8.3-fpm (8.3.36-1+ubuntu22.04.1+deb.sury.org+1) ...
Setting up nginx (1.18.0-6ubuntu14.8) ...
Processing triggers for man-db (2.10.2-1) ...

验证基础组件就绪:

php -v | head -2 && nginx -v && composer --version

实测回显:

PHP 8.3.36 (cli) (built: Oct 21 2026 14:31:50) (NTS)
Copyright (c) The PHP Group
nginx version: nginx/1.18.0
Composer version 2.9.2 2026-05-13 14:22:12

确认关键扩展(imagick/gd/fileinfo)已加载:

php -m | grep -iE "imagick|gd|fileinfo"

实测回显:

fileinfo
gd
imagick

💡 技术拓展:PHP 的图片处理扩展不止 imagick 一种。GD 内置于 PHP 发行,轻量但特性少、不支持色彩管理;Imagick 是 ImageMagick 的 PHP 绑定,格式覆盖广、滤镜与色彩空间能力强(Flyimg 默认走 magick CLI + Imagick 混合);此外还有 libvips 的 php-vips 绑定,内存与速度表现更好但部署门槛高。Flyimg 1.12.10 实际采用 Imagick/GD 双引擎加 magick 命令行,本文按其默认依赖安装 php8.3-imagick。

三、方案 A:打包发行部署(官方推荐形态)

3.1 方案说明

官方 install.md 主推两种「打包发行」形态:其一为直接使用官方打包制品(flyimg/flyimg,内置 nginx、php-fpm 与全部依赖,启动即用);其二为拉取源码后按官方制品描述自行构建同构发行物。两者的共同点是:应用根位于 /var/www/html,web 目录为 /var/www/html/web,由发行物内建的进程管理器同时拉起 nginx 与 php-fpm,对外统一暴露 80 端口。

⚠️ 本节为官方文档记载的标准形态,实测环境以方案 B(源码直装)为主线完成全流程验证;本节按官方文档如实转述命令与预期结果,未在本机复跑。若采用本方案,后续「配置说明」一节中目录路径请对应 /var/www/html。

3.2 命令与预期结果

按官方文档,打包发行制品的获取与启动为「拉取官方制品 → 启动 → 对外暴露 8080 端口」三步;制品内已含全部依赖,启动后无需额外配置即可访问。预期结果(转述官方 docs/install.md,查询日期 2026-10-28):

You can navigate to your machine's IP in port 8080 (ex: http://127.0.0.1:8080/) ;
you should get the demo homepage of Flyimg already working.
(来源:官方 docs/install.md,查询日期 2026-10-28)

自定义参数的方式:将 config/parameters.yml 覆盖挂入发行物内对应路径,参数键与源码完全一致(参数逐项含义见 《Flyimg 1.12.10 配置:parameters.yml 全参数详解与逐项生效验证》)。

四、方案 B:源码直装(实测主线)

4.1 获取源码并钉版

# 克隆仓库到部署目录
git clone https://github.com/flyimg/flyimg.git /var/www/flyimg
cd /var/www/flyimg

# 钉到 1.12.10 发布提交(仓库不带 tag,以发布 commit 为准)
git checkout 2878b1b790a7613b50c62d77bad0d68597980454
git log --oneline -1

实测回显:

2878b1b chore(release): 1.12.10 [skip ci]

工作区干净确认:

git status -s

实测回显(无输出,工作区干净)。

4.2 composer 安装依赖

cd /var/www/flyimg && composer install --no-dev --optimize-autoloader

实测回显(输出节选,实测首尾):

Installing dependencies from lock file (including requiring packages)
Verifying lock file contents can be installed on current platform.
Nothing to install, update or remove
Generating optimized autoload files (authoritative)
37 packages you are using are looking for funding.

⚠️ 排障实录 ①:首次启动报 500,nginx error.log 出现 PHP Fatal error: Uncaught Error: Call to undefined function Core\Entity\yaml_parse() in /var/www/flyimg/src/Core/Entity/AppParameters.php:24。原因:Flyimg 用 libyaml 绑定扩展解析 parameters.yml,composer 依赖清单未声明该扩展,系统默认不带。解决:apt-get install -y php8.3-yaml 并重启 php-fpm(命令与回显见 4.5)。验证:php -m | grep -i yaml 输出 yaml。

4.3 配置 nginx 站点

写入 Flyimg 站点配置,Web 根指向源码 web/ 目录,静态缓存文件命中时由 nginx 直接回源,其余入口交给 index.php:

cat > /etc/nginx/sites-available/flyimg.conf << "EOF"
server {
    listen 80 default_server;
    server_name _;
    root /var/www/flyimg/web;
    index index.php;

    # 静态缓存文件命中时直接由 nginx 返回,其余入口全部交给 index.php
    location / {
        try_files $uri /index.php$is_args$args;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    }
}
EOF
rm -f /etc/nginx/sites-enabled/default
ln -sf /etc/nginx/sites-available/flyimg.conf /etc/nginx/sites-enabled/flyimg.conf

语法检查与实测回显:

nginx -t

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

配置要点逐项说明:root 必须指向 web/ 目录(Flyimg 的前端控制器 index.php 与默认演示图都在该目录);try_files 把存在的静态文件(即已生成的缓存图)直接交给 nginx 返回,未命中的全部路由进 index.php 由应用处理;fastcgi_pass 走 Debian/Ubuntu 默认的 unix socket /run/php/php8.3-fpm.sock,与 php-fpm 池配置的 listen 一致。

4.4 目录权限

按官方制品构建脚本的同样做法准备缓存与临时目录(官方对 var/ 与 web/uploads/ 授权 www-data 并放开写权限):

cd /var/www/flyimg
mkdir -p var/tmp web/uploads/.tmb
chown -R www-data:www-data var/ web/uploads/
chmod -R 777 var/ web/uploads/

实测回显(无输出即为成功)。权限依据:官方构建描述中对该两目录执行 chown -R www-data:www-data 与 chmod 777 -R(来源:源码发行描述文件,查询日期 2026-10-28);php-fpm 池以 www-data 运行,产物缓存由其写入。

4.5 启动服务(systemd 托管)

Ubuntu 发行版自带 nginx 与 php8.3-fpm 的 systemd 单元,直接启用开机自启并启动;补装排障实录 ① 定位的 php-yaml 扩展后重启 fpm:

systemctl enable --now php8.3-fpm
systemctl enable --now nginx

实测回显:

Synchronizing state of php8.3-fpm.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable php8.3-fpm
Synchronizing state of nginx.service with SysV service script with /lib/systemd/systemd-sysv-install.
Executing: /lib/systemd/systemd-sysv-install enable nginx

apt-get install -y php8.3-yaml && systemctl restart php8.3-fpm && php -m | grep -i yaml

实测回显(输出节选):

Processing triggers for php8.3-fpm (8.3.36-1+ubuntu22.04.1+deb.sury.org+1) ...
yaml

三个常驻服务状态核对:

systemctl is-active php8.3-fpm nginx cron

实测回显:

active
active
active

💡 说明:cron 服务在最小安装后可能尚未安装(实测 systemctl enable cron 报 Unit file cron.service does not exist),执行 apt-get install -y cron 后再 systemctl enable --now cron 即可,它是 4.6 清理任务的前置。

4.6 安装缓存清理定时任务

官方 cleanup-tmp.sh 读取 parameters.yml 中的 enable_cronjob_cleanup 与 cronjob_cleanup_interval,把清理任务写入 /etc/cron.d/cleanup-cron。注意该脚本内置路径为打包发行形态的 /var/www/html,源码直装在 /var/www/flyimg 时需先做路径适配再执行:

cd /var/www/flyimg
# 将脚本内 /var/www/html 全部替换为实际部署路径,并覆盖原脚本
sed "s|/var/www/html|/var/www/flyimg|g" cleanup-tmp.sh > /tmp/cleanup-adapted.sh
chmod +x /tmp/cleanup-adapted.sh && /tmp/cleanup-adapted.sh && cp /tmp/cleanup-adapted.sh cleanup-tmp.sh

⚠️ 排障实录 ②:直接执行原脚本后,/etc/cron.d/cleanup-cron 生成的调度行仍指向原脚本路径。原因是 cron 行引用的是脚本自身路径,而脚本内部读取的 YAML 路径还是打包形态的 /var/www/html,原脚本在源码直装环境下读不到参数、按默认值工作。解决:如上用适配版覆盖原脚本,使 cron 调度的脚本与内部路径一致。

cat /etc/cron.d/cleanup-cron

实测回显:

0 */5 * * * root /var/www/flyimg/cleanup-tmp.sh

该行含义:每 5 小时(对应默认参数 cronjob_cleanup_interval: "0 */5 * * *")由 root 执行一次清理,删除 var/tmp 中超过 1 小时的临时文件。核对 cron 服务在跑:

systemctl is-active cron

active

4.7 安装验收

首页验收:

curl -s -o /dev/null -w "首页 HTTP %{http_code}\n" http://127.0.0.1/

实测回显:

首页 HTTP 200

图片处理全链路验收(源图为局域网静态源站上 1,025,710 字节的 2266x1957 JPEG):

curl -s -o /tmp/out-w300.jpg \
  -w "首次: HTTP %{http_code} | %{content_type} | %{size_download}B | %{time_total}s\n" \
  "http://127.0.0.1/upload/w_300,q_80/http://192.168.1.10:8000/Citroen-DS.jpg"
curl -s -o /dev/null \
  -w "二次(缓存): HTTP %{http_code} | %{size_download}B | %{time_total}s\n" \
  "http://127.0.0.1/upload/w_300,q_80/http://192.168.1.10:8000/Citroen-DS.jpg"
file /tmp/out-w300.jpg

实测回显:

首次: HTTP 200 | image/jpeg | 22867B | 0.075951s
二次(缓存): HTTP 200 | 22867B | 0.002190s
out-w300.jpg: JPEG image data, JFIF standard 1.01, aspect ratio, density 1x1, segment length 16, progressive, precision 8, 300x259, components 3

缓存落盘核对:

find /var/www/flyimg/web/uploads -type f

实测回显:

/var/www/flyimg/web/uploads/2d2ba6b9a54ff7e1c0e1c7d68415e079.jpg

⚠️ 排障实录 ③:验收阶段若图片请求返回 503 且耗时恰好等于 source_image_request_timeout(默认 5s),为拉取源图超时。实测环境直连外网源站耗时 8s,超出默认超时;解决途径有二:调大 parameters.yml 的 source_image_request_timeout,或改用可达的内网源站。实测将超时调到 30 并使用内网源站后恢复 200。URL 参数与该参数的联动验证见 《Flyimg 1.12.10 命令运维:URL 参数族实测、缓存管理与备份恢复》。

五、方案对比与选择建议

解读:标准场景与快速评估选方案 A,部署成本最低;需要把 Flyimg 并入既有 nginx 体系、控制 PHP 版本或做安全收敛时选方案 B——本文后续章节均基于方案 B 实测路径展开。

六、配置说明

6.1 配置文件清单

6.2 服务管理速查

systemctl restart php8.3-fpm   # 修改 fpm 池或扩展后重启
systemctl reload nginx         # 修改站点配置后平滑重载
systemctl is-active php8.3-fpm # 服务状态

应用参数(parameters.yml)为请求级加载,改动即时生效、无需重启服务——实测把 header_cache_days 从 365 改为 7,响应头立即从 max-age=31536000 变为 max-age=604800(完整逐项验证见组内配置篇)。

6.3 日志位置

• 应用层:/var/www/flyimg/var/log/(log_level 控制级别,默认 error);
• nginx:/var/log/nginx/error.log 与 access.log(FastCGI 上游报错先看这里);
• php-fpm:/var/log/php8.3-fpm.log。

七、常见问题

Q1:首页 500,日志报 Call to undefined function Core\Entity\yaml_parse()? 缺 php-yaml 扩展。apt-get install -y php8.3-yaml(官方 8.1 则为 apt-get install -y php-yaml 并确认扩展启用)后 systemctl restart php8.3-fpm,以 php -m | grep yaml 出现 yaml 为准。详见 4.2 排障实录 ①。

Q2:图片请求 503,耗时约等于超时阈值? 拉取源图超时。检查源站可达性;外网源站慢时调大 parameters.yml 的 source_image_request_timeout(单位秒)或改用内网源站。详见 4.7 排障实录 ③。

Q3:请求报 500,cron.d 文件里调度路径是打包形态的 /var/www/html? cleanup-tmp.sh 内置路径与实际部署路径不一致,按 4.6 做路径适配后覆盖原脚本。详见排障实录 ②。

Q4:缓存图写不进、页面报权限错误? 核对 var/ 与 web/uploads/ 的属主与权限(4.4 节命令),php-fpm 以 www-data 运行,两目录必须对其可写;可用 ls -ld /var/www/flyimg/web/uploads 核对为 drwxrwxrwx www-data www-data。

八、卸载与清理

# 1) 停用并移除站点与定时任务
rm -f /etc/nginx/sites-enabled/flyimg.conf /etc/cron.d/cleanup-cron
systemctl reload nginx

# 2) 备份或删除应用目录
tar czf /root/flyimg-backup-$(date +%F).tgz -C /var/www flyimg   # 如需保留缓存与配置
rm -rf /var/www/flyimg

# 3) 按需移除运行时(谨慎评估是否被其他应用共用)
apt-get purge -y php8.3-fpm php8.3-cli php8.3-imagick php8.3-yaml nginx
apt-get autoremove -y

卸载后验证:curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1/ 不再返回 200(预期 000 或连接拒绝),ls /var/www/flyimg 报 No such file or directory。

九、参考链接

• 官方安装文档:https://github.com/flyimg/flyimg/blob/main/docs/install.md(查询日期 2026-10-28)
• 官方仓库:https://github.com/flyimg/flyimg(发行描述/文档源/README,查询日期 2026-10-28)
• Packagist 版本源:https://repo.packagist.org/p2/flyimg/flyimg.json(1.12.10 核实,查询日期 2026-10-28)
• deb.sury.org PHP 源:https://deb.sury.org/(PHP 8.3 包来源)
• 组内文档:《Flyimg 认知选型:按需图片处理服务的定位、原理与同类方案对比》、《Flyimg 1.12.10 配置:parameters.yml 全参数详解与逐项生效验证》、《Flyimg 1.12.10 命令运维:URL 参数族实测、缓存管理与备份恢复》
• 同主题参考:《ConvertX 安装:Ubuntu 22.04 源码直装与 systemd 服务化》(同为源码直装+systemd 形态的文件转换服务)