HMWDigital Space

Lychee｜开源相册手动升级与数据库备份（以 v7.9 及更高版本为例）

Lychee 是一款优秀且轻量的开源 PHP 自建相册。在没有开启自动更新或使用命令行环境时，手动完成源码覆盖与数据库迁移是最稳妥的升级方式。

本文将以升级至 Lychee v7.9.0 为例，讲解如何通过 SSH 命令行安全地完成相册升级、数据库备份及缓存清理，确保照片数据与配置文件（.env）不受影响。

一、前置准备：下载新版并确认版本

首先通过 SSH 登录服务器，将最新的 Lychee 发行包下载至临时目录并解压确认。

ssh xserver
# 1. 进入临时目录并下载最新的 Lychee.zip
cd /tmp
wget -q https://github.com/LycheeOrg/Lychee/releases/latest/download/Lychee.zip -O Lychee_new.zip

# 2. 解压至临时提取目录
mkdir -p /tmp/Lychee_new_extract
unzip -q /tmp/Lychee_new.zip -d /tmp/Lychee_new_extract

# 3. 检查解压后的版本号
cat /tmp/Lychee_new_extract/Lychee/version.md

二、备份 MySQL 数据库

在执行任何源码覆盖或数据库结构迁移（Migration）之前，务必先导出数据库备份。

mysqldump -u 【数据库用户名】 -p 【数据库名】 > ~/backup/lychee_db_$(date +%Y%m%d).sql

如果忘记数据库密码，可以通过以下命令直接查看 Lychee 根目录下的 .env 配置文件来获取：

grep DB_PASSWORD /your/path/to/photos/.env

三、执行核心升级步骤

为了防止升级过程中有访问请求写入数据，建议先开启维护模式（artisan down），然后使用 rsync 安全覆盖项目文件。

1. 开启维护模式并安全同步文件

rsync 命令行中必须排除（--exclude）数据库配置文件 .env、缓存文件夹 storage 以及保存原图和缩略图的 public/uploads 目录：

# 进入维护模式
php /your/path/to/photos/artisan down

# 使用 rsync 覆盖源码（保留配置文件与用户照片数据）
rsync -av --exclude='.env' \
          --exclude='storage' \
          --exclude='public/uploads' \
          /tmp/Lychee_new_extract/Lychee/ \
          /your/path/to/photos/

注：如果服务器环境有多个 PHP 版本（如 Xserver 等托管主机），请将 php 替换为指定版本的绝对路径（例如 /usr/bin/php8.4）。

2. 执行数据库迁移与清空缓存

文件覆盖完成后，运行 Laravel 核心 Artisan 命令完成数据库结构更新与配置缓存刷新：

# 强制运行数据库迁移
php /your/path/to/photos/artisan migrate --force

# 依次清理配置、缓存、路由与视图缓存
php /your/path/to/photos/artisan config:clear
php /your/path/to/photos/artisan cache:clear
php /your/path/to/photos/artisan route:clear
php /your/path/to/photos/artisan view:clear

# 关闭维护模式，恢复正常访问
php /your/path/to/photos/artisan up

四、常见问题与排错 (FAQ)

Q1：升级后打开网页提示 503 Service Unavailable？

  • 原因：通常是因为升级中断或 artisan up 命令未成功执行，导致系统依然处于维护模式。
  • 解决办法：重新在终端运行一次启动命令即可：
php /your/path/to/photos/artisan up

Q2：更新后页面部分样式缺失或图片显示异常？

  • 解决办法：尝试在终端清理应用缓存并重新建联：
php artisan view:clear
php artisan route:clear

更多文章