升级与迁移指南

本文面向站长，覆盖三类维护场景：版本升级（在线升级与手动升级）、v1.0.x 老站迁移到 v1.0.0、同版本换服务器搬家。系统的日常维护操作（缓存、备份入口）参见 02-使用手册 第 8 章「系统维护」。

无论执行哪种操作，请务必先完成第 2 章的全量备份，并确认备份可下载、可校验。

1. 概述：升级与迁移路径速查

说明：在线升级功能面向 v1.0.0 之后的版本更新。v1.0.x 老站升级至 v1.0.0 不适用在线升级（更新检测不会向老站推送），请按第 5 章方式迁移。

三条路径的共同前提：

1. 操作前完成全量备份，并已下载到本地留档；
2. 确认目标服务器满足运行环境要求（参见 01 手册第 4 章）；
3. 选择访问量低的时段操作，升级与恢复期间访客可能短暂看到异常页面。

2. 升级前必做：全量备份

2.1 在后台创建备份

1. 进入「系统维护 → 数据备份」，提供三种备份方式：
   • 备份数据库：导出全部数据表结构与数据（gzip 压缩的 SQL 文件）；
   • 备份文件：打包 uploads 上传目录中的附件；
   • 全量备份：数据库与 uploads 一并打包为一个 zip 文件；
2. 建议同时执行「备份数据库」与「备份文件」各一次，或直接执行一次「全量备份」；
3. 备份文件统一保存于站点 storage/backups/ 目录，该目录禁止 Web 直接访问；
4. 「备份设置」中可配置备份保留份数（1-30 份，默认 5 份），超出后自动删除最旧的备份。

2.2 验证并下载备份

1. 备份列表展示文件名、类型、大小、时间与 MD5 校验状态，先确认状态正常再继续；
2. 系统为每份备份自动生成同名 .md5 校验文件，恢复时会自动校验，损坏的备份会被拒绝恢复；
3. 逐份点击「下载」保存到本地，并在本地或其他存储上留档，不要只保留服务器上的一份；
4. 下载后可手动核对 MD5 值（应与对应 .md5 文件内容一致）：

# Linux / macOS
md5sum backup_full_20260101_120000.zip

# Windows（命令提示符）
certutil -hashfile backup_full_20260101_120000.zip MD5

2.3 数据库另存一份兜底

后台数据库备份为程序导出格式。重大升级前，建议再通过主机面板（如 phpMyAdmin）额外导出一份 SQL，与后台备份互为兜底。

3. 在线升级详解

3.1 前置条件

1. 完成官网绑定：进入「应用市场 → 市场设置」，填写官网地址与站点密钥（在官网「我的站点」生成并复制，32 位字符），保存后系统自动连接官网完成绑定；
2. 磁盘剩余空间充足（约为升级包体积的 3 倍以上，含升级包、临时解压与备份余量）；
3. storage/tmp、storage/backups 与站点根目录对 Web 进程可写；
4. 未完成绑定时升级入口不可用，页面会引导先前往「市场设置」完成绑定。

3.2 检测更新

1. 进入「系统维护 → 系统升级」；应用市场检测到新版本时，也会在市场页展示红点横幅「立即升级」入口；
2. 升级页自动展示当前版本与最新版本信息（检测结果缓存 10 分钟）；
3. 点击「检测更新」可清除缓存并实时请求官网；
4. 检测到新版本后，点击「开始升级」执行升级；
5. 若提示「无法连接官网」，多为服务器到官网的网络不通或被防火墙拦截，可稍后重试，或改用第 4 章手动升级。

3.3 执行升级

升级按以下步骤自动执行，全程约 1-2 分钟，期间不可中途取消：

升级覆盖的保护范围（以下内容不会被升级包触碰）：

• 目录：uploads（附件）、plugins（插件）、themes（主题）、storage（运行时数据）、data、install；
• 文件：站点根目录的配置与安装锁文件（config.php、install.lock、.htaccess）。

升级期间注意事项：

1. 保持升级页面打开，不要关闭页面或在后台执行其他操作；
2. 升级完成后页面会弹出结果提示，显示新版本号与本次自动备份的文件名。

3.4 升级前自动备份内容

1. 程序文件：将程序目录与根目录入口文件打包为 pre-update-版本号-时间.zip，自动保留最近 3 份；
2. 数据库：以与「数据备份」页相同的格式导出（backup_db_*.sql.gz）；
3. 两份备份均保存于 storage/backups/，是升级失败的回退保障；任一备份未能生成时，升级会立即中止且不对系统做任何修改。

3.5 数据库版本迁移提示

1. 升级覆盖完成后，系统自动执行数据库结构迁移，正常情况下无需手动操作；
2. 若自动迁移失败，升级完成后页面会提示前往「系统维护 → 数据迁移」手工执行；
3. 升级页会持续检测数据库结构版本与程序版本的差异，不一致时展示迁移引导；
4. 迁移内容为新增表、字段、索引与内置配置项、菜单项，执行前请确认已完成数据备份，操作说明参见 02-使用手册 8.3 节。

3.6 升级历史

升级页展示最近一次升级记录，包括：起始版本、目标版本、升级时间、覆盖文件数、自动生成的文件备份与数据库备份文件名、迁移结果。

3.7 升级失败回退

1. 升级任一步失败即中止并清理临时文件，系统保持升级前状态；
2. 数据库可回到「数据备份」页，使用升级前自动生成的数据库备份恢复；
3. 程序文件可下载 storage/backups/ 下对应的 pre-update 备份包，解压覆盖回站点根目录；
4. 回退完成并确认站点正常后，按页面提示的原因处理问题，再重新执行升级。

4. 手动升级（在线升级不可用时）

适用于服务器无法访问官网、网络受限或需要离线升级的情形。手动升级的本质是「新程序文件覆盖 + 保留既有数据」，覆盖范围与在线升级的保护策略一致。

4.1 操作步骤

1. 按第 2 章完成全量备份并下载到本地；
2. 从官网或官方源码仓库下载新版本完整安装包；
3. 解压安装包，按 4.2 节清单整理后覆盖上传至站点根目录；
4. 上传完成后，可对照包内 core/config/version.php 确认版本号无误。

4.2 覆盖范围清单

具体做法：解压后先检查并删除包内的 core/config/database.php（若存在），再将其余程序文件与目录上传覆盖到站点根目录。覆盖完成后可对照升级包内的 core/config/version.php 确认版本号。

4.3 覆盖后操作

1. 访问后台，进入「系统维护 → 数据迁移」；若页面提示数据库结构版本与目标版本不一致，先预览变更再执行迁移；
2. 进入「系统维护 → 缓存设置」，清理全部缓存；
3. 逐页检查前台与后台功能正常，升级页显示的当前版本已更新。

5. 老站迁移到 v1.0.0

v1.0.x 老站升级到 v1.0.0 不适用在线升级（更新检测不会向老站推送），请按「备份 → 全新安装 → 导入数据」方式迁移，整体流程与 01-系统介绍 常见问题中的升级问答一致。

迁移前请了解内容归属：文章、分类、标签、评论、用户等数据存于数据库，附件存于 uploads 目录，二者随备份迁移；插件与主题的程序文件不在迁移范围，迁移后需到应用市场重新安装。

5.1 第一步：旧站全量备份与下载

1. 旧站后台「数据备份」执行全量备份，并下载数据库备份与全量备份到本地；
2. 另通过 FTP 或主机面板将 uploads 目录打包下载一份兜底；
3. 记录旧站已安装的插件清单、主题名称及其配置，便于迁移后重装与恢复；
4. 记录旧站「基本设置」中的站点 URL 与伪静态配置方式。

5.2 第二步：新服务器全新安装 v1.0.0

按 01-系统介绍 第 5 章完成下载上传、伪静态配置与安装向导。安装时数据库表前缀建议与旧站保持一致（默认 bk_），可简化后续导入。

5.3 第三步：导入旧站数据

以下两种方式任选其一。

方式 A（推荐）：通过数据备份页恢复

1. 将旧站全量备份 backup_full_*.zip 通过 FTP 上传至新站 storage/backups/ 目录；
2. 进入「数据备份」页，备份列表中会出现该备份，点击「恢复」；
3. 恢复会将旧站数据库与 uploads 附件一并还原（恢复会覆盖新站现有全部数据，请在全新安装后立即执行，不要先发布新内容）。

方式 B：数据库工具导入

1. 通过 phpMyAdmin 等数据库工具，向新站数据库导入旧站的数据库备份 SQL（若提示表已存在，先删除全新安装生成的 bk_ 前缀数据表再导入）；
2. 将旧站 uploads 目录内容通过 FTP 上传至新站 uploads 目录。

5.4 第四步：执行数据库结构迁移

1. 进入「系统维护 → 数据迁移」，页面显示数据库结构当前版本与目标版本；
2. 先点击「预览」查看将执行的变更，确认无误后执行迁移；
3. 迁移将旧库结构补齐至当前版本：新增缺失的表、字段、索引与内置配置项、菜单项；迁移只增不减，不会删除或修改既有文章与用户数据。

5.5 第五步：重新安装插件与收尾核对

1. 到「应用市场」重新安装所需插件（插件程序不随主程序数据迁移），并按 5.1 节记录恢复插件配置；
2. 如非默认主题，重新安装主题并启用，核对导航菜单与站点设置；
3. 核对「基本设置」中的站点 URL 与实际域名一致；
4. 核对新服务器伪静态规则已生效（参见 01 手册 5.2）；
5. 进入「缓存设置」清理全部缓存；
6. 逐页检查前台文章、分类、标签、评论与图片显示正常，后台数据完整。

6. 换服务器迁移（同版本搬家）

同版本搬家不涉及数据库结构变更，核心是「数据搬全、配置核对」。以下两种方式任选其一。

6.1 方式一：整站直搬（推荐）

配置与数据原样保留，操作最直接。

1. 旧服务器：通过 FTP 或主机面板将整站目录打包下载（程序、uploads、storage 一并包含）；
2. 旧服务器：通过主机面板导出数据库 SQL；
3. 新服务器：部署运行环境，上传整站文件并解压至站点目录；新建数据库并导入旧库 SQL；
4. 修改 core/config/database.php，将主机、端口、数据库名、用户名、密码更新为新服务器的数据库信息；
5. 按新服务器环境重新配置伪静态（Apache 与 Nginx 规则见 01 手册 5.2）；
6. 确认 uploads/ 与 storage/ 目录对 Web 进程可写。

6.2 方式二：全新安装 + 备份恢复

1. 新服务器全新安装同版本程序（参见 01 手册第 5 章）；
2. 旧服务器后台执行全量备份并下载，将 backup_full_*.zip 上传至新站 storage/backups/ 目录；
3. 新站「数据备份」页点击恢复，旧站数据库与 uploads 附件一并还原（数据库连接配置仍指向新库，无需改动）；
4. 核对伪静态规则与目录权限。

6.3 迁移后核对清单

7. 常见问题

Q：升级执行到一半中断怎么办？

A：升级按步骤自动执行，任一步失败即中止并清理临时文件，系统保持升级前状态，不会出现「覆盖了一半」的无备份状态。按页面提示的原因处理后重新执行即可：下载失败（网络被拦截、官网不可达）稍后重试；磁盘空间不足先清理空间；目录不可写先修正权限。若覆盖步骤失败，可用 storage/backups/ 下的程序文件备份解压覆盖回站点根目录，数据库可在「数据备份」页用升级前自动生成的备份恢复。

Q：恢复备份后前台除首页外全部 404？

A：多为伪静态未生效。按 01 手册 5.2 检查服务器伪静态规则：Apache 确认 mod_rewrite 已启用且 AllowOverride 为 All；Nginx 确认规则位于正确的 server 块并已重载配置。若程序已为新版而数据库仍为旧结构，还需进入「数据迁移」页执行结构迁移。

Q：恢复备份或搬家后文章图片丢失？

A：依次排查：uploads 目录是否已恢复或上传到位（仅恢复了数据库备份时附件不会还原）；「基本设置」中的站点 URL 是否与实际域名一致（部分附件路径可能记录了旧域名）；完成后清理全部缓存再刷新页面。

Q：迁移或搬家后后台登录失效？

A：登录会话保存在站点 storage/sessions 目录中，会话 Cookie 与访问域名绑定。更换域名或 http/https 协议切换后，浏览器中的旧会话凭证不再匹配，退出后重新登录即可。「记住我」的登录凭证保存在数据库中，跨站点不通用；恢复旧库或换库后如登录状态异常，清除浏览器中站点的 Cookie 后重新登录。另请确认服务器时间正确，会话在 30 分钟无操作后自动过期。

Q：升级完成后提示需要数据迁移？

A：说明新版本包含数据库结构变更。进入「系统维护 → 数据迁移」，先预览变更再执行；执行前请确认已完成数据备份。迁移内容只增不减（新增表、字段、索引与内置配置、菜单项），不会删除既有数据。

Q：升级或迁移后页面样式异常、后台菜单缺失？

A：先进入「缓存设置」清理全部缓存；若后台菜单缺失，到「数据迁移」页执行一次结构迁移（会补齐缺失的内置菜单项），完成后刷新页面。

Q：老站迁移后应用市场提示未绑定怎么办？

A：通过第 5.3 节方式恢复旧库后，市场绑定信息（官网地址与站点密钥）随数据库一并还原，一般无需重新设置。若备份中不含该信息或需要更换密钥，进入「应用市场 → 市场设置」，重新填写官网地址与站点密钥（官网「我的站点」生成）并保存即可完成绑定。

8. 相关文档

• 01-系统介绍：安装部署与伪静态配置（第 5 章）、升级常见问答（第 7 章）；
• 02-使用手册：缓存、数据备份、数据迁移、系统升级的日常操作（第 8 章）；
• 03-目录与文件说明：站点目录与关键文件（如 core/config/database.php）的位置说明。