整站程序迁移时需要注意什么？数据库、文件与配置逐项检查

整站迁移不是把程序目录复制到新服务器，再改一个数据库地址就结束。网站通常还依赖数据库、用户上传文件、运行时配置、定时任务、缓存、邮件服务、证书和 DNS 等资源。只要其中一项没有同步或切换，新站就可能出现页面报错、图片丢失、数据回退、邮件中断，甚至旧站和新站同时写入造成数据分叉。

本文适用于常见的 PHP、Node.js、Python 等网站，以及传统虚拟主机、VPS、云服务器之间的迁移。不同框架和数据库的具体操作可能不同，文中的命令以 Linux、MySQL/MariaDB 和 rsync 为例；执行前应根据实际环境调整，并先在测试环境验证。核心原则是：先盘点依赖，再复制数据，最后安排可控的切换和回滚。

一、先明确迁移方式和边界

迁移方案取决于网站能容忍多长时间的只读或停机，以及迁移期间数据是否持续变化。常见做法有三种：

• 停机迁移：维护窗口开始后暂停写入，导出数据库、复制文件，再切换流量。操作简单，适合更新频率低、可接受短时维护的网站。
• 预同步加最终同步：先复制大部分文件和数据库，在旧站继续运行期间完成准备；切换前短暂停写，再同步增量并做最终数据库导出。适合文件较多、希望缩短停机时间的网站。
• 持续复制或双写：通过数据库复制、日志同步或专门迁移平台持续追平数据。适合停机要求严格的业务，但配置、监控和回退都更复杂，不能仅凭“复制延迟很小”就认为可以安全切换。

迁移前要确定切换边界：何时停止旧站写入、谁有权执行最终同步、如何确认新站已接管、出现问题后能否回切，以及回切后如何处理新站已经产生的数据。若新旧两端都接受写入，简单地把 DNS 改回去并不能合并数据。

二、迁移前盘点：不要只看网站目录

先列出网站运行所依赖的资源，并确认每项由谁管理。至少检查以下内容：

• 应用代码及依赖：语言版本、运行时、扩展、系统库、构建产物和启动方式。
• 数据库：产品与版本、字符集、时区、数据库名、账号权限、视图、触发器、存储过程、事件和定时任务。
• 动态文件：上传目录、附件、用户头像、生成文件、会话目录，以及是否有文件实际存储在对象存储上。
• 配置与密钥：数据库连接、域名、环境变量、邮件、支付、OAuth、对象存储、第三方 API 和加密密钥。
• 外围服务：反向代理、Web 服务器、TLS 证书、CDN、DNS、WAF、防火墙、队列、缓存、搜索服务和邮件发送服务。
• 自动化任务：cron、systemd 定时器、队列消费者、计划任务平台、备份任务及证书续期任务。

盘点时记录新旧环境的版本和差异，而不只是复制配置文件。例如，新服务器的 PHP 版本可能更高，某个扩展被移除；数据库排序规则可能不同；应用可能依赖旧服务器上的系统字体、命令行工具或本地时区。能在新环境提前验证的，不要留到切流量时才发现。

三、数据库：完整导出、导入与校验

1. 先确认一致性和数据库对象

网站持续写入时，数据库导出可能只反映导出过程中的某个时点。MySQL 中，--single-transaction 可为 InnoDB 表建立一致性快照，通常适用于在线导出；它不保证 MyISAM 等非事务表的一致性，也不能冻结数据库结构变更。因此，使用该选项时仍应暂停会改变表结构的部署；混有非事务表或需要严格一致性时，应安排停写或采用经过验证的备份方案。

导出前确认不仅有表数据，还要考虑视图、触发器、存储过程、函数和事件。MySQL 客户端的 --routines、--triggers、--events 分别用于包含相应对象；事件是否执行，还受目标端事件调度器状态影响。不要假设所有对象都会随普通表数据自动迁移。

2. 使用客户端导出和导入

以下示例适用于本机已安装 MySQL 命令行客户端、并且有权访问数据库的情况。-p 会交互式提示输入密码，避免把密码直接写进命令行历史。备份文件包含业务数据，应限制访问权限并妥善保管。

umask 077
mysqldump \
  --host=OLD_DB_HOST \
  --user=BACKUP_USER \
  -p \
  --single-transaction \
  --quick \
  --routines \
  --triggers \
  --events \
  --default-character-set=utf8mb4 \
  OLD_DATABASE > site.sql

mysql \
  --host=NEW_DB_HOST \
  --user=IMPORT_USER \
  -p \
  --default-character-set=utf8mb4 \
  NEW_DATABASE < site.sql

这里的占位值需要替换为真实主机、账号和库名，目标数据库应事先按应用要求创建。若使用的客户端版本不支持某个选项，应查阅该版本帮助并采用相应方式，不能直接删掉选项后就认定备份完整。命令成功退出也不等于业务数据完整；要检查错误输出和退出状态。生产环境中可以将日志写入受限文件，并记录执行时间、源端和目标端信息。

--single-transaction 的一致性快照主要针对 InnoDB；导出期间如果执行了 DDL，仍可能影响结果。--quick 让客户端逐行读取结果，降低客户端内存占用，但不会替代磁盘空间规划。大型数据库还需评估导出时间、压缩和传输耗时、目标端导入耗时，以及备份文件是否有足够空间。

如果数据库规模很大，或需要保持较短停机时间，可评估数据库原生复制、物理备份或云厂商迁移服务。它们对版本、存储引擎、权限、网络和复制拓扑都有要求，不能将一套适用于小型逻辑导出的命令直接套用到所有生产库。

3. 检查字符集、时区和权限

导入后检查数据库和表的字符集、排序规则、时区及 SQL 模式。字符集不一致可能导致中文乱码或排序行为变化；时区差异可能影响订单时间、计划任务和报表边界。应用账号通常只应拥有运行所需权限，不应为了省事直接授予全局管理员权限。数据库迁移账号和应用运行账号也应区分。

还要核对应用配置中的库名、地址、端口、账号和 TLS 要求。数据库从本机迁至独立服务后，localhost 可能不再有效；在部分 MySQL 配置中，使用 localhost 还会走本地套接字，而不是 TCP。不要把“能从新服务器登录数据库”误当成“应用使用的连接参数也正确”。

四、文件：确认哪些必须复制，哪些不应照搬

应用代码通常可以从版本库重新部署，但用户上传文件、运行时生成且不可重建的文件必须纳入迁移。反过来，缓存、临时文件、旧日志和依赖目录不一定适合直接复制。先明确目录职责，再决定同步范围。若网站使用对象存储，应确认桶、区域、访问策略、跨域设置和对象元数据，而不是只检查服务器磁盘。

常见的预同步命令如下。执行前先用 --dry-run 检查差异；源路径末尾的斜杠表示同步目录内容，路径写错可能导致复制层级不符合预期。

rsync -aH --numeric-ids --dry-run \
  --exclude='cache/' \
  --exclude='tmp/' \
  /srv/site/ admin@NEW_HOST:/srv/site/

rsync -aH --numeric-ids --info=progress2 \
  --exclude='cache/' \
  --exclude='tmp/' \
  /srv/site/ admin@NEW_HOST:/srv/site/

-a 用于归档式复制，会保留常见文件属性并递归同步；-H 尝试保留硬链接，只有需要时才启用。--numeric-ids 按数字用户和组 ID 处理所有者信息，要求两端 ID 对应关系符合预期；若新旧服务器用户 ID 不同，盲目保留所有者可能造成权限问题。非 root 用户也可能无法设置某些所有权和属性。按目标环境决定是否保留这些属性，迁移后检查所有权和访问权限。

rsync 默认不会删除目标端多余文件。这个行为通常更安全，但也意味着目标端可能残留旧文件。--delete 会删除目标端在源端不存在的内容，必须先确认源、目标路径与排除规则，再用 --dry-run 检查；误用时可能扩大损失。不要把它当作常规“清理参数”直接加入生产命令。

权限需要按最小可用原则设置。Web 进程应能读取程序文件，只对确实需要写入的上传、缓存等目录开放写权限。避免用 chmod -R 777 解决权限报错：它会让所有本机用户都可写这些文件，增加程序被篡改和上传目录被滥用的风险。还应检查符号链接指向、磁盘挂载点、SELinux 或 AppArmor 策略，以及目录是否位于正确的文件系统中。

五、配置：环境变量、密钥与域名替换

配置文件往往含有数据库密码、API 密钥、支付密钥、JWT 签名密钥和 SMTP 凭据。迁移时不要把这些内容提交到公开代码仓库，也不要为了方便把密钥写进可被 Web 访问的目录。应通过受限权限的环境文件、密钥管理服务或部署平台注入。复制配置时核对文件属主、权限和新环境变量，不要只确认文件“存在”。

密钥的处理需要区分类型。数据库密码或第三方访问密钥通常可以在新旧环境平稳切换期间继续使用，随后再按计划轮换；用于加密已有业务数据、签名会话或令牌的密钥则不能随意更换。更换后，旧密文可能无法解密，旧会话或令牌也可能失效。若必须轮换，应先确认应用支持多密钥过渡或制定数据重新加密方案。

站点 URL 更换还要区分“普通文本替换”和“结构化数据迁移”。一些程序会把 URL 写入 JSON、序列化对象或二进制字段，直接对 SQL 导出文件执行全局替换可能破坏长度信息或数据格式。应使用应用或框架提供的迁移工具；在没有专用工具时，先备份并在副本上测试，再检查命中范围。

反向代理后的客户端 IP、HTTPS 识别和可信代理列表也需复核。不能为了让应用识别 HTTPS 就信任来自任意来源的转发头，否则攻击者可能伪造协议或客户端地址。仅信任实际控制的代理，并按 Web 框架文档设置可信代理范围。

六、运行环境与外围依赖

在新机器上按清单安装运行时和扩展，并执行应用自带的依赖安装或构建流程。不要假设复制旧机器的系统目录就能得到可维护的新环境。核对启动用户、工作目录、监听地址、进程数、内存限制、上传大小限制、请求超时和日志路径。某些问题只会在特定请求或后台任务触发，不能仅靠首页打开成功判定迁移完成。

分别检查反向代理和应用配置：域名绑定、静态文件路径、路由回退、请求体大小、超时、压缩、缓存规则和安全响应头。TLS 证书应确认域名覆盖范围、有效期、私钥权限和自动续期流程；证书续期依赖的验证端口或 DNS API 凭据也要迁移。

对 Redis、队列、搜索引擎和对象存储，先判断其中保存的是可重建缓存还是必须保留的业务状态。缓存通常可以清空，但队列中未处理的任务不能随意丢弃；迁移后还要避免旧消费者继续取走新环境的任务。邮件发送、短信、支付回调和 OAuth 回调地址等外部系统，也可能要求提前登记新域名或出口 IP。

七、切换流程：先验证，再让用户访问

1. 准备新环境：部署应用、创建账号、配置服务并开放受控的测试入口。确认新站不会提前执行会影响真实用户的邮件、扣款、外部回调或定时任务。
2. 预同步：先同步文件并导入数据库副本，检查日志和依赖。此阶段旧站继续提供服务时，新站应避免对生产数据写入，防止测试数据与旧站状态混杂。
3. 安排冻结窗口：告知相关人员切换时间，暂停旧站写入、上传和后台消费者；记录正在处理的任务，并确认没有其他程序继续写入同一数据库。
4. 完成最终同步：对数据库做最终导出导入，对文件做最后一次增量同步。确认目标端数据时间点、文件数量和关键业务记录符合预期。
5. 内部验收：通过 hosts 文件、内部 DNS 或负载均衡的测试后端访问新站，检查登录、读写、上传、下载、搜索、邮件、支付沙箱、后台任务和日志。测试真实支付前应确认不会产生真实交易。
6. 切换流量：按计划修改负载均衡、反向代理或 DNS。DNS 缓存和 TTL 会影响解析更新时间，提前降低 TTL 不代表所有用户会立即切到新地址。
7. 观察并决定收尾：检查错误率、数据库连接、队列积压、响应时间和业务数据。确认新站稳定后，按预案恢复后台任务和外部回调；旧站先保留为只读或隔离状态，而不是立即删除。

八、验证清单：用业务结果而非“命令成功”验收

• 首页、登录、登出、权限判断和关键业务流程是否正常。
• 抽查数据库关键表的记录数、最新记录、关联关系和时间字段；对高价值业务做有意义的核对，而不只比较总表数。
• 抽查历史图片和新上传文件，确认文件内容、路径、访问权限和 URL 一致。
• 检查 PHP 或应用错误日志、Web 服务器日志、数据库日志、系统服务状态及告警。
• 检查邮件、队列、计划任务、缓存失效策略和外部回调是否实际工作。
• 确认证书有效、HTTPS 跳转正确、静态资源和下载链接没有指向旧域名或旧主机。
• 观察 CPU、内存、磁盘空间、连接数和慢查询，确保新环境容量能够承载实际流量。

验收最好由业务人员与运维人员共同完成。运维能确认服务启动，不代表订单金额、权限结果或报告数据正确；业务人员能打开页面，也不代表备份、定时任务和证书续期已经就绪。

九、回滚与常见错误

回滚计划应明确触发条件、负责人、可用时间窗口和数据处理方式。只要新站尚未接受写入，通常可以恢复旧站流量并继续排查；一旦新站已经产生真实业务数据，直接切回旧站会让这些数据留在新库，形成数据丢失或分叉。此时需要先暂停写入并评估数据合并、反向同步或其他恢复方案。回滚不是简单的“把 DNS 改回去”。

• 误区：复制了代码就算迁移完成。上传文件、密钥、任务、证书和外部服务配置可能都在别处。
• 误区：导出文件有了就等于有备份。应验证文件可读取、导入过程成功，并在独立环境实际恢复。未验证恢复的备份不能视为可靠的恢复方案。
• 误区：预同步后无需最终同步。预同步期间旧站仍在变化，最后一次冻结后的同步才用于补齐变化。
• 误区：新站可访问就开放全部流量。首页正常不能覆盖登录、上传、异步任务、邮件和权限等路径。
• 误区：新旧站同时运行没有风险。若两端连接同一生产库，或分别接受写入，可能重复执行任务、发送重复通知或产生数据冲突。
• 误区：权限报错就递归开放写权限。应查清实际运行用户和所需写入目录，避免将整个程序目录暴露为可写。
• 误区：改回域名即可完整回滚。DNS 缓存、CDN、代理和用户本地缓存都可能让流量在一段时间内分散到不同环境。

结语

可靠的整站迁移依赖可核对的清单、经过验证的备份、明确的数据冻结时点，以及可执行的切换和回滚方案。把数据库、文件、配置、运行环境和外围服务分别验证，再用关键业务流程做最终验收，比单纯追求“快速复制”更重要。迁移完成后，保留旧环境一段观察期并持续监控；确认数据、任务和备份均稳定后，再按安全流程下线旧服务器和撤销旧凭据。