Strapi 数据迁移与恢复指南 (2026版)：从本地到生产环境

1. 前置准备

1.1 环境要求

本地：Strapi 项目 + SQLite/PostgreSQL 数据库
服务器：已部署 Strapi 项目（内容类型 schema 已上传）
工具：SSH 访问权限、scp/rsync

1.2 备份原则

数据迁移前必须确保本地与服务器 Strapi 版本一致，否则可能导致：

内容类型 schema 不兼容
数据库迁移失败
插件功能异常

2. 版本检查与同步

2.1 检查本地版本

cd /path/to/strapi
cat package.json | grep "@strapi/strapi"

输出示例：

"@strapi/strapi": "5.47.1"

2.2 检查服务器版本

SSH 登录服务器后执行：

cd /path/to/strapi
cat package.json | grep "@strapi/strapi"

2.3 版本不一致的解决方案

方案 A：将本地版本同步至服务器版本

假设服务器版本为 5.47.1，本地为 5.50.0：

# 本地操作
cd g:\code\astro\bookreview\strapi

# 修改 package.json 中的版本号
npm install @strapi/strapi@5.47.1 @strapi/plugin-cloud@5.47.1 @strapi/plugin-users-permissions@5.47.1

# 清理并重新安装
rm -rf node_modules .cache .tmp
npm install

# 重新构建
npm run build

方案 B：本地和服务器同时升级到最新稳定版

本地升级：

cd g:\code\astro\bookreview\strapi

# 使用官方升级工具
npx @strapi/upgrade latest

# 或手动升级
npm install @strapi/strapi@latest @strapi/plugin-cloud@latest @strapi/plugin-users-permissions@latest

# 清理缓存
rm -rf node_modules .cache .tmp
npm install
npm run build

服务器升级：

# SSH 登录服务器
ssh user@your-server

cd /path/to/strapi

# 停止服务
pm2 stop strapi  # 或 systemctl stop strapi

# 升级
npx @strapi/upgrade latest

# 重新安装依赖
rm -rf node_modules .cache
npm install
npm run build

# 重启服务
pm2 start strapi  # 或 systemctl start strapi

2.4 验证版本一致性

# 本地
npx strapi version

# 服务器
npx strapi version

确保两边输出相同的版本号。

3. 本地数据导出

3.1 执行导出

cd g:\code\astro\bookreview\strapi
npm run export

如果 package.json 中没有 export 脚本，添加：

"scripts": {
  "export": "strapi export -f strapi_backup --no-encrypt"
}

或直接运行：

npx strapi export -f strapi_backup --no-encrypt

3.2 导出内容说明

导出会生成 strapi_backup.tar.gz，包含：

数据：所有集合类型的内容条目
资源：上传的媒体文件（图片、文档等）
配置：插件配置、用户权限、角色等
关联：内容类型之间的关系数据

3.3 常见问题

权限错误：

Failed to load command [Error: EPERM: operation not permitted, open '...config.json']

解决：以管理员身份运行终端，或手动创建配置目录：

New-Item -ItemType Directory -Path "$env:APPDATA\xdg.config" -Force

4. 上传到服务器

4.1 使用 SCP 上传

scp strapi_backup.tar.gz user@your-server:/path/to/strapi/

4.2 使用 Rsync（推荐大文件）

rsync -avz --progress strapi_backup.tar.gz user@your-server:/path/to/strapi/

4.3 验证文件完整性

# 本地
md5sum strapi_backup.tar.gz

# 服务器
md5sum /path/to/strapi/strapi_backup.tar.gz

确保两个 MD5 值一致。

5. 服务器数据导入

5.1 停止服务

# 使用 PM2
pm2 stop strapi

# 或使用 systemd
systemctl stop strapi

5.2 执行导入

cd /path/to/strapi

# 如果 package.json 有 import 脚本
npm run import -- -f strapi_backup

# 或直接使用 npx
npx strapi import -f strapi_backup.tar.gz

如果提示缺少 import 脚本，添加到 package.json：

"scripts": {
  "import": "strapi import"
}

5.3 导入过程说明

导入会：

清空现有数据库表（警告：会覆盖服务器现有数据）
按顺序导入配置、内容、资源
重建数据库索引和关联

5.4 重启服务

# 使用 PM2
pm2 start strapi

# 或使用 systemd
systemctl start strapi

# 查看日志
pm2 logs strapi
# 或
journalctl -u strapi -f

6. 验证与排查

6.1 验证步骤

访问 Strapi 管理后台
```
https://your-server.com/admin
```
检查内容数量
- 登录后台，逐个检查每个内容类型的条目数量
- 与本地导出的数量对比

测试 API 端点

# 测试文章列表
curl https://your-server.com/api/book-reviews?populate=*

# 测试书摘列表
curl https://your-server.com/api/quotes?populate=*

检查媒体文件
- 访问几张图片 URL，确认能正常加载

6.2 常见问题排查

问题 1：导入失败 - 版本不匹配

Error: Data version mismatch

解决：确保本地和服务器 Strapi 版本一致（见第 2 节）

问题 2：数据库连接失败

Error: connect ECONNREFUSED

解决：检查 .env 文件中的数据库配置：

DATABASE_CLIENT=postgres
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_NAME=strapi
DATABASE_USERNAME=strapi
DATABASE_PASSWORD=your_password

问题 3：内容类型不存在

Error: Content type "api::book.book" not found

解决：确保服务器的 src/api/ 目录已包含所有内容类型的 schema

问题 4：权限错误

Error: Forbidden

解决：导入后需要重新配置 Public 角色的权限：

进入 Settings → Roles → Public
为每个内容类型勾选 find/findone 权限
保存

6.3 数据完整性检查清单

所有集合类型的数据数量与本地一致
内容关联关系正确（如文章→书籍→作者）
媒体文件可正常访问
API 端点返回正确数据
管理后台无报错
用户权限配置正确

附录：快速参考命令

# 版本检查
npx strapi version

# 本地导出
npm run export

# 上传
scp strapi_backup.tar.gz user@server:/path/

# 服务器导入
npx strapi import -f strapi_backup.tar.gz

# 服务管理
pm2 restart strapi
pm2 logs strapi

目录