Lychee 照片管理系统升级指南:git 更新与手动更新的完整实操(含数据库迁移脚本解析)
Lychee 照片管理系统升级指南:git 更新与手动更新的完整实操(含数据库迁移脚本解析)
导读
本文围绕 Lychee 官方 docs/Update.md 文档,系统讲解 Lychee 的升级前置条件、git pull 一键更新、手动替换文件更新两种升级路径,并结合仓库中的数据库迁移脚本(php/database 目录)与版本管理源码,深度剖析 Lychee 从 2.7.0 到 3.1.x 的升级机制、数据安全边界与版本校验原理。读完本文,你将能够安全、无痛地将自建 Lychee 实例升级到最新版本,并在升级异常时快速定位问题根源。
一、升级前的准备:Update requirements(更新要求)
升级并非直接执行命令那么简单,Lychee 官方在 docs/Update.md 中明确了两条硬性前置要求,缺一不可:
1. 满足最新的系统运行要求
- 你的服务器环境必须符合 Lychee 最新的系统要求。以当前仓库为例,docs/Installation.md 明确列出:
-
运行环境:Web 服务器 + PHP 5.5 或更高版本 + MySQL 数据库;
-
必须启用的 PHP 扩展:
session、exif、mbstring、gd、mysqli、json、zip; -
建议调整的
php.ini参数:max_execution_time = 200 post_max_size = 100M upload_max_size = 100M upload_max_filesize = 20M memory_limit = 256M -
使用 nginx 或 CGI/FastCGI 的用户,升级前还应额外确认上传相关配置(详见 FAQ)。
-
提示:升级脚本执行期间需要较高的执行时间与内存上限(尤其是大量照片需要重建缩略图时),建议在升级前核对
php.ini中max_execution_time与memory_limit的取值。
2. 当前版本必须大于 2.7.0
官方文档明确声明:
"Ensure that your current version is greater than 2.7.0. Updates from older Lychee versions aren't supported."
即:只有 2.7.0 及以上版本才支持在线升级,更老版本的升级不被支持。这一点在仓库的数据库迁移脚本结构上可以得到印证——php/database 目录下现存的最早迁移脚本正是 update_020700.php(升级到 2.7.0),其后依次是 update_030000.php、update_030001.php、update_030003.php、update_030100.php、update_030102.php、update_030107.php。这组脚本构成了 Lychee 可追溯的"升级基线":数据库结构迁移的起点就是 2.7.0。
二、升级方式一:使用 git 更新(推荐)
Lychee 官方将 git 方式列为最简便的升级路径。如果你的 Lychee 是通过 git clone 部署的,整个升级过程只需一条命令:
git pull
执行后,git 会自动拉取远程最新代码并合并到当前分支。这种方式的优势在于:
- 文件差异最小化:git 只更新发生变更的文件,不需要手动判断哪些文件该保留、哪些该覆盖;
- 版本可回溯:一旦升级出现问题,可以借助 git 历史快速回退到旧版本;
- 用户数据零干预:
git pull只作用于代码目录,不会触碰uploads/(照片原图、中图、缩略图、导入目录)与data/(配置文件、缓存等用户数据目录)。
需要注意,git pull 仅同步程序代码,数据库结构的升级(例如新增字段、新增设置项)并不包含在其中——这部分由 Lychee 的数据库迁移机制完成,详见本文第四节。
三、升级方式二:手动更新(Manual update)
对于通过压缩包(如 zip)部署、未使用 git 的用户,官方提供了一套四步手动升级流程:
- 下载最新版本:前往 Lychee 官方发布页下载最新版本的压缩包;
- 替换所有现有文件,但必须排除
uploads/和data/两个目录; - 打开 Lychee 并输入数据库连接信息,触发升级流程;
- 升级完成后,可查看更新日志了解新版本特性。
为什么必须排除 uploads/ 和 data/?
这是手动升级中最容易出错、也最关键的一步。从源码目录常量定义(php/define.php)可以看清这两个目录的职责:
// Define dirs
define('LYCHEE_DATA', LYCHEE . 'data/');
define('LYCHEE_SRC', LYCHEE . 'src/');
define('LYCHEE_UPLOADS', LYCHEE . 'uploads/');
define('LYCHEE_UPLOADS_BIG', LYCHEE_UPLOADS . 'big/');
define('LYCHEE_UPLOADS_MEDIUM', LYCHEE_UPLOADS . 'medium/');
define('LYCHEE_UPLOADS_THUMB', LYCHEE_UPLOADS . 'thumb/');
define('LYCHEE_UPLOADS_IMPORT', LYCHEE_UPLOADS . 'import/');
uploads/:存放照片的big/(原图)、medium/(中等尺寸图)、thumb/(缩略图)以及import/(导入暂存),是你的照片资产本体;data/:存放数据库配置文件(LYCHEE_CONFIG_FILE指向data/config.php)等实例专属数据,包含你的数据库连接凭证。
如果覆盖这两个目录,轻则丢失全部照片与配置,重则导致站点无法连接数据库。因此无论何种升级方式,uploads/ 与 data/ 都应当原封不动。
手动升级后的"打开 Lychee"做了什么?
第 3 步"打开 Lychee(并输入数据库详情)"背后是完整的版本检测与数据库迁移流程:Lychee 的入口会读取 data/config.php 中的数据库配置,比对当前数据库记录版本与程序版本,若不一致则依次执行 php/database 下的更新脚本,最后将版本号写回设置表(详见第四节)。
关于目录权限
按照安装文档的要求,uploads/、data/ 及所有子目录需要具备足够的读写权限(如 chmod -R 750 uploads/ data/)。升级前后都应注意保持这一权限状态,否则升级脚本可能因无法写入 uploads/medium/ 等目录而失败——例如 update_020700.php 中就有"仅在目录缺失时创建 medium 目录、创建失败即报错"的检查逻辑(php/database/update_020700.php)。
四、源码级解析:升级背后的数据库迁移机制
原文档只描述了升级操作步骤,而仓库中的迁移脚本揭示了"版本号校验 + 幂等迁移 + 逐版本升级"的完整机制。理解它,你才能在升级卡壳时准确判断是代码问题、数据库问题还是权限问题。
1. 版本号的存储与更新
Lychee 将当前数据库版本号存放在 lychee_settings 表的 version 键中。核心读写逻辑位于 php/Modules/Database.php:
- 读取当前版本:查询
SELECT * FROM lychee_settings WHERE key = 'version'(Database.php 附近); - 写入新版本:
Database::setVersion($connection, $version)执行UPDATE lychee_settings SET value = ? WHERE key = 'version'(Database.php)。
每一个迁移脚本的结尾都会调用 setVersion 将版本号推进到对应值,形成"脚本执行成功 → 版本号落库 → 下次升级从新版本继续"的链条。
2. 迁移脚本的执行模式:检查存在性,避免重复执行
从源码看,Lychee 的迁移脚本普遍采用"先检查、后修改"的幂等写法,保证脚本即使重复执行也不会破坏数据。以 update_020700.php 为例:
// Add medium to photos
$query = Database::prepare($connection, "SELECT `medium` FROM `?` LIMIT 1", array(LYCHEE_TABLE_PHOTOS));
$result = Database::execute($connection, $query, 'update_020700', __LINE__);
if ($result===false) {
// 字段不存在时才执行 ALTER TABLE 添加 medium 字段
$query = Database::prepare($connection, "ALTER TABLE `?` ADD `medium` TINYINT(1) NOT NULL DEFAULT 0", array(LYCHEE_TABLE_PHOTOS));
...
}
同样,update_030001.php 在插入新的设置项(如 sortingAlbums、identifier)之前,都会先 SELECT ... WHERE key = '...' 判断是否已存在,只有 num_rows===0 时才执行 INSERT。
3. 各版本迁移脚本做了什么:完整脉络
结合 php/database 目录,可以还原 Lychee 从 2.7.0 到 3.1.7 的数据库演进历史:
| 脚本 | 目标版本 | 核心变更 |
|---|---|---|
| update_020700.php | 2.7.0 | lychee_photos 表新增 medium 字段(TINYINT(1) 默认 0);创建 uploads/medium/ 目录 |
| update_030000.php | 3.0.0 | 重置 username/password 设置(登录改为 crypt 存储,移除 md5 遗留代码);所有公开相册改为私有并清空密码 |
| update_030001.php | 3.0.1 | 照片/相册 title 字段长度改为 VARCHAR(100);新增 sortingAlbums 设置(默认 ORDER BY id DESC);sorting 重命名为 sortingPhotos;新增 identifier 设置(md5(microtime(true)) 生成) |
| update_030003.php | 3.0.3 | 新增 skipDuplicates 设置(默认 0,控制导入时是否跳过重复照片) |
| update_030100.php | 3.1.0 | 相册表 id 字段扩展为 BIGINT(14) |
| update_030102.php | 3.1.2 | 照片表 album、id 字段改为 BIGINT(14) UNSIGNED;checksum 改为 CHAR(40) 可空;thumbUrl 改为 CHAR(37);为 album、star 字段新增索引以加速查询(对应 Changelog 中 "Added indexes to SQL fields") |
| update_030107.php | 3.1.7 | 照片表新增 position 字段(TINYINT(1) NOT NULL) |
从源码结构看,这些脚本揭示了升级的破坏性变更:例如 3.0.0 会清空登录用户名/密码并把所有相册改为私有,3.0.3 引入了
skipDuplicates导入策略。升级前建议先阅读对应版本的更新日志,确认新版本行为是否符合预期。
4. 迁移失败的错误处理
每个脚本的执行结果都会经过 Response::error() 检查,失败即终止并返回明确错误信息,例如:
Could not add medium-field to database!(2.7.0)Could not reset username in database!(3.0.0)Could not add index to the album id field!(3.1.2)
这意味着升级失败不会"静默半途而废"——你会在界面上看到具体是哪一步、哪个表、哪个操作出了问题,方便针对性地排查数据库权限或字段冲突。
五、升级完成后:确认新版本与了解变更
1. 如何确认升级成功
升级成功的标志有两层:
- 数据库层面:
lychee_settings表中的version值已被迁移脚本推进到最新版本(例如030107),可通过数据库客户端查看; - 功能层面:相册、照片、搜索、设置等模块均能正常访问,新版本引入的新设置项(如
skipDuplicates、sortingAlbums)出现在设置界面中。
2. 通过 Changelog 了解版本差异
升级之后,建议通读更新日志确认本次升级涉及的行为变化。从当前仓库的 Changelog 可以提取几个与升级直接相关的典型变更,供升级决策参考:
- v3.1.2:为 SQL 字段添加索引以提升查询速度;使用 Imagick 时移除中等尺寸图片与缩略图的元数据并降低画质(docs/Changelog.md 附近);
- v3.1.3:基于 EXIF 方向信息旋转/翻转图片(GD);在未安装/启用 Imagick 时给出警告(对应
php.ini中session扩展成为必需项); - v3.1.6:修复 SmartAlbum 下载崩溃与 PHP7 下 htaccess IfModule 问题。
若升级后某些功能表现与旧版不同(例如缩略图不再保留 EXIF 元数据、相册默认排序变化),多半可在对应版本 Changelog 中找到答案。
六、升级注意事项速查(Checklist)
综合原文档与源码,整理一份升级前自检清单:
- PHP 版本:≥ 5.5,且已启用
session、exif、mbstring、gd、mysqli、json、zip扩展; - MySQL 可用性:数据库服务正常,账号具备对
lychee_*表的 ALTER/INSERT/UPDATE 权限; - 当前版本:必须 ≥ 2.7.0(更老版本请先查阅历史发布说明,规划"先升到 2.7.0 再继续升级"的路径);
- php.ini 参数:
max_execution_time、memory_limit、上传体积相关参数满足要求; - 备份策略:升级前备份
data/与数据库(uploads/为照片本体,建议一并纳入备份计划); - git 方式:执行
git pull前确认本地无未提交的代码改动,避免合并冲突; - 手动方式:解压新版本后只覆盖程序文件,严格排除
uploads/与data/; - 升级触发:手动升级后打开 Lychee 首页并按要求输入数据库信息,等待迁移脚本执行完成;
- 失败定位:若升级报错,根据
Response::error提示的错误信息定位到对应迁移脚本,检查表结构冲突、目录权限(uploads/medium/等)与设置表数据。
七、总结
Lychee 的升级体系可以概括为"代码更新 + 数据库迁移"双轨机制:git pull 或手动替换文件只负责更新程序代码,php/database 下的版本化迁移脚本则负责把数据库结构从当前版本逐级推进到目标版本,并以 lychee_settings.version 作为校验锚点。只要守住"uploads/ 与 data/ 不动、当前版本 ≥ 2.7.0、环境满足 PHP/MySQL 要求"这三条底线,无论采用 git 还是手动方式,都能顺利完成升级;而一旦遇到问题,迁移脚本的幂等设计与明确的错误信息也足以让你快速定位并恢复。