10. 升级到新版本（手动安装、生产模式）

这份教程是我们自己升级正式商城（0.2.13 升到 0.2.16）时的真实步骤整理出来的。那次升级：前台维护页面大约 7 分钟，商品、订单、设置都没有变，授权和速卖通连接都保持正常。 你的商店大小和服务器不同，时间会有差别。

适合：你是用手动解压的方式装的 GetDropFlow（没有用 Composer），商店运行在 production（生产）模式。用 Composer 装的商店，请看安装包里 INSTALL.md 的"升级"一节。

先读这几句

• 升级会让前台短暂进入"维护中"。 选一个没人下单的时间，先看最近 24 小时的订单量。
• 备份在先。 备份没做好、没检查过，就不要开始升级。
• 不要用"直接解压覆盖"。 新版本已经没有的旧文件会留下，必须先删掉五个旧模块文件夹，再解压新包。
• 命令用网站运行的那个用户来执行，不要直接用 root。 否则会生成 root 才能读写的文件，前台会出怪问题。
• 本文里的 SITE、WEB_USER、PHP 要换成你自己服务器上的实际值，见"第 0 步"。

第 0 步：弄清楚你的情况（只看，不改）

在服务器终端里，先进入 Magento 的根目录（里面有 app、bin、pub 这几个文件夹），然后依次看：

pwd
php -v | head -1
php bin/magento --version
php bin/magento deploy:mode:show
php bin/magento maintenance:status
grep -h '"version"' app/code/DropshipKit/*/composer.json
ls pub/static/frontend/*/*/
df -h . | tail -1

你要记下来：

1. 现在装的版本：五行版本号应该一样。设置页目前不显示版本号，所以要靠这条命令确认。
2. Magento 版本：GetDropFlow 要求 Magento 2.4.9、命令行 PHP 8.4.1 及以上。
3. 前台用了哪些语言：最后那条 ls 会列出语言文件夹，例如 en_US、es_ES、zh_Hans_CN。第 6 步部署静态文件时要把它们全部列出来，少一个，那个语言的页面会缺样式。
4. 磁盘空间够不够放一份备份。
5. 网站用哪个系统用户运行（文件的所有者），记作 WEB_USER；文件所属的组记作 WEB_GROUP。命令：ls -ld app。

下文用这些写法，你换成自己的：

cd /你的/Magento/根目录
M="sudo -u WEB_USER php -d memory_limit=-1 bin/magento"

php 要和网站实际使用的是同一个版本，如果服务器装了多个 PHP，请用网站用的那个（例如 php8.4）。不确定就问主机商。

第 1 步：备份（缺一不升）

B=/root/backup-gdf/before-升级版本号
mkdir -p $B && chmod 700 $B
cp -a app/code/DropshipKit $B/DropshipKit-before
cp -a app/etc/env.php app/etc/config.php $B/
$M module:status > $B/modules-before.txt

数据库备份： 用 mysqldump（或主机商面板里的备份功能）做一份完整备份。数据库账号和密码从 app/etc/env.php 里读，不要贴到聊天、文档或截图里。备份完成后，检查两件事：

• 文件大小不是 0。
• 文件末尾有 Dump completed 的完成标记，里面的建表数和正式库的表数一样。

最好再做一份整机快照：如果你的主机商提供（例如 VPS 的"快照"功能），在升级前创建一份。它能把整台服务器恢复到那一刻，是最后一道保险。注意：快照通常只保留一个，而且有有效期，恢复后快照之后的新订单会丢，所以它只是保险，不替代上面的备份。

能不能真的恢复？ 有条件的话，把数据库备份在一个临时数据库里恢复一次，数几张关键表（订单、商品、dropshipkit_ 开头的表）的行数和正式库对比。我们自己的升级里这一步没做成（数据库账号没有建临时库的权限），所以我们把它标成"未验证"，靠完整性检查加整机快照兜底。

第 2 步：下载新版安装包并核对

1. 打开官网下载页，输入你的授权码，下载 dropshipkit-manual-install-新版本号.zip。
2. 页面上会显示这个文件的 SHA-256 校验值。上传到服务器之后一定要核对，见第 3 步。

第 3 步：上传到服务器并核对

1. 把 zip 上传到 Magento 根目录（用主机面板的文件管理器、SFTP 都可以）。
2. 上传有可能把整站的文件组弄乱，上传完先修一下：

chgrp -R WEB_GROUP .

1. 核对文件没有损坏，把下面第一行里的校验值换成下载页上显示的：

E=下载页上的校验值
H=$(sha256sum dropshipkit-manual-install-新版本号.zip | cut -c1-64)
[ "$H" = "$E" ] && echo HASH_OK || echo HASH_BAD
unzip -p dropshipkit-manual-install-新版本号.zip BUILD-INFO.txt | head -4

看到 HASH_OK，并且 BUILD-INFO.txt 第一行是你要的版本号，才继续。HASH_BAD 就停下，重新下载。

第 4 步：打开维护模式，换掉模块

从这一步开始前台会显示"维护中"。

$M maintenance:enable
[ -d app/code/DropshipKit/Core ] && rm -rf app/code/DropshipKit/Admin app/code/DropshipKit/Catalog app/code/DropshipKit/Core app/code/DropshipKit/Orders app/code/DropshipKit/Shipping
unzip -q -o dropshipkit-manual-install-新版本号.zip "app/code/*"
chown -R WEB_USER:WEB_GROUP app/code/DropshipKit
find app/code/DropshipKit -type d -exec chmod 2770 {} +
find app/code/DropshipKit -type f -exec chmod 660 {} +
grep -h '"version"' app/code/DropshipKit/*/composer.json

最后一行应该五行都是新版本号。

第 5 步：数据库升级和代码编译

$M setup:upgrade --keep-generated
$M setup:di:compile

setup:di:compile 在我们的小店上用了不到一分钟，大店会更久，屏幕安静时不要关页面，等到出现 Generated code and dependency injection configuration successfully.。

升级时可能打印 generated/code/Magento cannot be deleted，这是已知的无害提示，可以忽略。别的红色报错都要停下，看"回退"一节。

第 6 步：部署静态文件、清缓存、关维护模式

把语言列表换成你第 0 步看到的全部语言：

$M setup:static-content:deploy -f en_US es_ES zh_Hans_CN
$M cache:flush
chgrp -R WEB_GROUP .
$M maintenance:disable
$M maintenance:status

商店保持 production 模式，不要切换。

第 7 步：验证

前台（用浏览器或命令都可以）： 首页、登录页、购物车、联系页、一个商品或分类页，都能正常打开；结账页（到"选择运输方式"为止，不要下单）能打开。每种前台语言都看一遍。

用命令看返回码：

for u in / /customer/account/login/ /checkout/cart/ /contact/ ; do echo "$u  $(curl -s -o /dev/null -w '%{http_code}' https://你的域名$u)"; done

应该是 200；空购物车去结账页返回 302（跳转）也正常。第一次打开会比较慢，因为缓存刚清。

后台： 登录后台，依次看：

1. GetDropFlow → 设置：授权状态是"有效"，速卖通账号"已连接"。点一次"立即验证"（只是向授权服务器查一次状态，不改设置）。
2. GetDropFlow 菜单里的子菜单都能打开。
3. 目录（Catalog）下面 GetDropFlow 的新入口都能打开。
4. 销售 → 订单：列表能显示。不要点进订单，不要点任何提交按钮。

升级之后不要改设置，不要打开"真实提交到速卖通"。

日志： 升级完成之后看一下 var/log/exception.log 和 var/report 有没有新增的文件。system.log 里在维护模式期间出现 maintenance mode is enabled 之类的提示是正常的（定时任务在维护期间被拒绝），关掉维护模式之后会恢复。

再观察一小时： 前台有没有 5xx，定时任务有没有报错，订单是否正常进来。

回退（任何一步不对就用）

$M maintenance:enable
rm -rf app/code/DropshipKit
cp -a $B/DropshipKit-before app/code/DropshipKit
chown -R WEB_USER:WEB_GROUP app/code/DropshipKit
$M setup:upgrade --keep-generated
$M setup:di:compile
$M setup:static-content:deploy -f 你的全部语言
$M cache:flush
chgrp -R WEB_GROUP .
$M maintenance:disable

一般不需要恢复数据库。真要恢复，先确认备份文件是好的，再恢复；恢复数据库会丢掉备份之后的新订单，要想清楚。整机快照是最后手段。

常见问题

设置页没有版本号，我怎么知道升级成功了？ 用第 0 步那条 grep '"version"' 命令看五个模块的版本号，都是新版本就对了。从 0.2.17 起，设置页的授权区有一行"GetDropFlow 插件版本"，直接显示五个模块共同的版本号；如果五个模块版本不一致，那一行会用粗体警告并列出每个模块的版本，说明升级没有做完整，请重新安装完整的安装包。0.2.17 之前的版本没有这一行。

设置页报错，说创建设置页类时"需要 15 个参数、只传了 14 个"？ 这是升级后预编译的依赖配置还是旧的。先执行 $M setup:di:compile，再执行 $M cache:flush，然后刷新设置页。升级到 0.2.17 的站点如果之前编译过（生产模式一定编译过），升级后必须重新编译；第 5 步的命令里已经包含这一步，不要省略。

前台打开是 500 或空白页？ 先 $M cache:flush，再 chgrp -R WEB_GROUP .，还不行就用上面的"回退"。

后台设置页打不开？ 看 var/log/exception.log 最后几行，把报错发给我们的客服。不要贴数据库密码和授权码。

我用 Composer 装的？ 不适用这份教程，请看安装包里 INSTALL.md 的"升级"一节。