name: wp-migrate description: WordPress网站迁移和部署使用wp-migrate.sh。在迁移WordPress站点、同步数据库、管理备份、测试迁移、调试迁移问题或处理WordPress部署工作流（包括Duplicator、Jetpack Backup和Solid Backups归档）时使用。还用于代码修改、测试、git工作流、PR创建和此项目的发布管理。 allowed-tools:

Bash
Read
Edit
Write
Glob
Grep
Task
TodoWrite

WordPress迁移技能

此技能提供对wp-migrate.sh WordPress迁移工具的专业知识。

项目概览

wp-migrate.sh是一个全面的WordPress迁移工具，它以两种模式运行：

推送模式：通过SSH（源 → 目标）迁移WordPress站点
归档模式：在目标服务器上导入WordPress备份归档（Duplicator、Jetpack Backup、Solid Backups）

当前版本：检查最新版本

git describe --tags --abbrev=0  # 从git获取当前版本

最新发布：查看GitHub Releases

仓库：BWBama85/wp-migrate.sh

主分支：main

核心能力

迁移模式

推送模式

通过SSH从源迁移wp-content和数据库到目标
在迁移期间在两个服务器上启用维护模式
在覆盖前创建带时间戳的备份
执行URL搜索替换以对齐目标域名
排除object-cache.php以保留目标缓存基础设施
支持StellarSites托管兼容性（–stellarsites标志）

归档模式

自动检测归档格式（Duplicator、Jetpack Backup、Solid Backups）
将归档提取到临时目录
验证磁盘空间（需要3倍归档大小）
在导入前创建目标数据库和wp-content的备份
如果与wp-config.php不同，则自动对齐表前缀
执行URL搜索替换以与目标URL对齐
提供带有确切命令的回滚说明

功能特点

迁移预览与确认：迁移前摘要与详细统计和确认提示（v2.6.0）
回滚命令：使用–rollback标志自动从备份中恢复（v2.6.0）
进度指示器：当安装pv时，实时进度条用于长时间运行的操作（v2.6.0）
干运行模式：预览所有操作而不做更改（–dry-run）
详细日志记录：显示详细诊断信息（–verbose）
跟踪模式：在执行前显示每个命令（–trace）
插件保留：保留目标中不在源中的插件/主题（–preserve-dest-plugins）
StellarSites模式：与mu-plugins排除一起托管兼容性（–stellarsites）
跳过搜索替换：只更新home/siteurl选项的快速迁移（–no-search-replace）
自动化支持：使用–yes标志跳过CI/CD的确认提示（v2.6.0）
安静模式：在非交互式脚本中抑制进度指示器（v2.6.0）

常见任务

运行迁移

推送模式：

./wp-migrate.sh --dest-host user@dest.example.com --dest-root /var/www/site

归档模式：

./wp-migrate.sh --archive /path/to/backup.zip
./wp-migrate.sh --archive /path/to/backup.tar.gz --archive-type jetpack

干运行：

./wp-migrate.sh --dest-host user@dest --dest-root /var/www/site --dry-run --verbose

回滚（v2.6.0）：

./wp-migrate.sh --rollback  # 自动检测最新备份
./wp-migrate.sh --rollback --rollback-backup /path/to/specific/backup  # 特定备份
./wp-migrate.sh --rollback --yes  # 自动化跳过确认

自动化友好（v2.6.0）：

./wp-migrate.sh --archive /path/to/backup.zip --yes --quiet  # CI/CD：跳过提示，无进度条

测试

运行所有测试：

make test

运行特定测试：

./test-wp-migrate.sh

ShellCheck验证：

shellcheck wp-migrate.sh

开发工作流

代码结构（v2+）

项目使用模块化源结构：

src/
├── header.sh           # Shebang, defaults, variable declarations
├── lib/
│   ├── core.sh         # 核心公用事业（log, err, validate_url）
│   ├── functions.sh    # 所有其他功能
│   └── adapters/       # 归档格式适配器
│       ├── README.md
│       ├── duplicator.sh
│       ├── jetpack.sh
│       └── solidbackups.sh
└── main.sh             # 参数解析和主执行

重要：修改应在src/文件中进行，而不是直接在wp-migrate.sh中。

构建过程

修改源文件后：

make build

这将：

在连接的源上运行shellcheck
将src/文件合并到dist/wp-migrate.sh
复制到./wp-migrate.sh（仓库根目录）
生成SHA256校验和

预提交钩子

预提交钩子防止在不重建的情况下提交源更改：

ln -s ../../.githooks/pre-commit .git/hooks/pre-commit

Git工作流

分支：使用描述性名称从main创建：
- feature/<slug>用于增强功能
- fix/<slug>用于错误修复
- docs/<slug>用于文档
- chore/<slug>用于维护
提交：使用.gitmessage模板格式：
```
type: 简短的命令性总结

如果需要，提供更长的解释
```
类型：feat, fix, docs, chore, refactor, test
更改日志：在每次功能或修复时更新CHANGELOG.md的[Unreleased]部分
拉取请求：
- 使用.github/pull_request_template.md清单
- 根据所有提交（不仅仅是最新的）提供全面的摘要
- 包括带有验证步骤的测试计划
- 引用相关的问题
合并：保持main发布就绪，使用git merge --no-ff或在审查后压缩
发布：使用语义化版本控制（例如git tag v2.7.0）

创建拉取请求

创建PR时，请确保：

审查分支中的所有提交（使用git log main..HEAD和git diff main...HEAD）
摘要涵盖更改的完整范围
测试计划验证所有功能
CHANGELOG.md已更新
ShellCheck通过
测试通过（make test）

常见文件检查

wp-migrate.sh - 主脚本（构建工件，不要直接编辑）
src/ - 模块化源文件（编辑这些）
src/lib/adapters/ - 归档格式适配器
CHANGELOG.md - 版本历史记录
README.md - 用户文档
Makefile - 构建和测试目标
test-wp-migrate.sh - 测试脚本

故障排除指南

常见问题

托管主机上的权限错误（StellarSites）

症状："权限被拒绝"当同步wp-content时
解决方案：使用--stellarsites标志排除受保护的mu-plugins
详细信息：托管主机保护某些mu-plugins目录（例如，stellarsites-cloud）

数据库导入失败

检查表前缀对齐（脚本自动检测和更新wp-config.php）
验证足够的磁盘空间（归档模式需要3倍归档大小）
检查MySQL max_allowed_packet大小以进行大型导入

URL搜索替换问题

使用--verbose查看检测到的URL
如果检测失败，请使用--dest-home-url或--dest-site-url覆盖
使用--no-search-replace进行只需要更新home/siteurl的更快迁移

归档检测失败

使用明确的--archive-type指定格式（duplicator, jetpack, solidbackups）
验证归档结构是否符合适配器预期（参见src/lib/adapters/）
使用–verbose查看详细的验证错误（v2.6.0+）

非交互式上下文失败（v2.6.0）

症状：脚本以"此脚本需要TTY进行确认提示"退出
解决方案：在CI/CD、cron或管道上下文中运行时添加--yes标志
详细信息：迁移预览和回滚默认需要确认；使用–yes绕过

回滚问题（v2.6.0）

自动检测在db-backups/和wp-content.backup-*中查找最新的带时间戳的备份
如果找不到备份，请使用--rollback-backup /path/to/backup明确指定
回滚仅适用于归档模式迁移（从本地备份中恢复）

SSH连接问题

使用--ssh-opt添加自定义SSH选项（可以重复）
示例：--ssh-opt 'Port=2222'或--ssh-opt 'ProxyJump=bastion'

ShellCheck错误

安装ShellCheck：brew install shellcheck（macOS）或参见https://www.shellcheck.net/
运行：shellcheck wp-migrate.sh
所有代码在合并前必须通过ShellCheck

调试命令

显示详细迁移预览：

./wp-migrate.sh --dest-host user@dest --dest-root /var/www/site --dry-run --verbose

显示每个命令（跟踪模式）：

./wp-migrate.sh --dest-host user@dest --dest-root /var/www/site --dry-run --trace

检查归档结构：

unzip -l /path/to/backup.zip | head -50
tar -tzf /path/to/backup.tar.gz | head -50

验证目标上的wp-cli：

ssh user@dest 'cd /var/www/site && wp core version'

归档适配器系统

脚本使用可扩展的适配器系统处理不同的备份格式。

支持格式

Duplicator：带有dup-installer/dup-database__*.sql结构的ZIP归档
Jetpack Backup：带有sql/*.sql多文件结构的ZIP/TAR.GZ归档
Solid Backups：带有wp-content/uploads/backupbuddy_temp/{ID}/中分割SQL的ZIP归档

添加新适配器

参见src/lib/adapters/README.md供贡献者指南。

每个适配器必须实现：

validate_<adapter>() - 检查文件是否匹配格式
extract_<adapter>() - 将归档提取到临时目录
detect_db_<adapter>() - 查找数据库文件
detect_wp_content_<adapter>() - 查找wp-content目录

最佳实践

协助代码更改时

始终检查是否需要修改源文件（src/）而不是直接修改wp-migrate.sh
**在任何源更改后运行make build**以重新生成wp-migrate.sh
在提交前运行ShellCheck验证
为所有功能和修复更新CHANGELOG.md
使用TodoWrite跟踪多步骤任务
创建专注于单一问题的PR

测试迁移时

始终以干运行开始以预览操作
使用详细模式进行故障排除（–verbose或–trace）
在破坏性操作前验证备份
在安全环境中测试回滚程序
在迁移后检查logs/目录中的日志

创建发布时

更新CHANGELOG.md，包含版本号和日期
创建git标签，使用语义化版本（例如v2.7.0）
生成GitHub发布，包含更改日志摘录
在干净的检查中验证测试通过
如果存在用户面向更改，则更新README

常见模式

搜索代码

使用Grep工具进行代码搜索：

pattern: "function_name"
output_mode: "content"
-n: true （显示行号）

阅读源文件

使用Read工具查看文件内容：

file_path: /Volumes/personal/codeprojects/bash/wp-migrate/src/lib/functions.sh

编辑代码

使用Edit工具进行精确更改：

file_path: /Volumes/personal/codeprojects/bash/wp-migrate/src/lib/functions.sh
old_string: "文件中的确切匹配"
new_string: "替换文本"

运行Git命令

git status
git diff main...HEAD  # 查看分支中的所有更改
git log main..HEAD    # 查看分支中的所有提交

重要提示

永远不要直接编辑wp-migrate.sh - 编辑src/中的文件
总是在源更改后运行make build
总是在提交前更新CHANGELOG.md（功能和修复）
总是在提交前运行ShellCheck（make test）
始终一起提交源文件和构建文件
在创建PR时始终审查所有提交（不仅仅是最新的提交）
始终使用TodoWrite进行多步骤任务以跟踪进度