SuiteCRM 7.12.x 如何升级到 SuiteCRM 8.x

1. 迁移前

在运行迁移之前，请确保您的系统符合新版本兼容性矩阵。
- 检查兼容性矩阵有关兼容版本的完整信息。
建议您在开发实例中运行迁移过程并进行测试。仅在测试后，将升级版本部署到生产实例上
在迁移之前，请确保创建实例代码和数据库的备份。
将您的 SuiteCRM 7.x 实例升级到最新的 7.12.x 版本
1. 确保仔细阅读每个版本的发行说明中描述的任何手动升级步骤
默认情况下，升级命令将设置error_reporting到一个不太严格的模式来抑制警告。
- error_reporting 值集是E_ALL & ~E_DEPRECATED & ~E_STRICT & ~E_NOTICE & ~E_WARNING
- 如果要应用更严格的模式，可以-vvv在每个命令上指定。这将设置E_ALL在error_reporting
请注意，迁移过程可能会删除您在项目中的任何非核心文件/目录public/legacy/文件夹
在运行接下来描述的任何命令之前，请确保您的 SuiteCRM 8 实例APP_ENV被设定为APP_ENV=prod模式（检查.env和“.env.local”文件）

2. 从 7.12.x 迁移到 SuiteCRM 8.x 版本

仅当您已将 SuiteCRM 7.x 实例升级到最新的 7.12.x 版本时才运行迁移。

2.1.下载新版本迁移包

1 – 从以下位置下载 SuiteCRM 8.x 目标版本迁移包（例如 8.x 7.12.x 迁移）SuiteCRM 发布页面。

2 – 将包内容解压缩到 SuiteCRM 8.x 目标文件夹

2.1 – 例如：您可以将包解压缩到新创建的文件夹中，例如/var/www/<SuiteCRM8-folder>

3 – 如果需要，重新设置正确的权限。

2.2. 复制您的 SuiteCRM 7.12.x 实例

1 – 将您的 SuiteCRM 7.12.x 实例文件夹复制到 SuiteCRM 8.x 目标文件夹上的公用文件夹/path-to-suitecrm-8/public

1.1 – 按照上面的例子，这将是/var/www/<SuiteCRM8-folder>/public/.
1.2 – 添加新文件夹后：/var/www/<SuiteCRM8-folder>/public/<SuiteCRM 7 Instance>.

2 – 将 SuiteCRM 7.12.x 复制的文件夹重命名为legacy

3 – 如果需要，重新设置正确的权限。

2.3. 设置权限

以命令行用户有足够权限读写的方式设置文件的权限

2.4. 运行迁移准备命令

1 – 在您的 SuiteCRM 8 实例根目录上（例如：/var/www/<SuiteCRM8>）运行：./bin/console suitecrm:app:setup-legacy-migration

2 – 应该提示您执行手动步骤以检查和更新旧配置上的值

session_dir：您应该将会话目录更新为''. 迁移后，您可以重新配置系统以使用不同的session_dir
- 请注意，SuiteCRM 8 配置session_dir是不同的。
- 见会话配置更多细节。
site_url: 你应该更新你的 site_url
- 您应该将此值更新为您当前用于迁移和测试 SuiteCRM 8.x 迁移的地址
- 请注意，如果您的虚拟主机没有指向publicSuiteCRM 8 根文件夹中的目录，您应该附加/public
  - 例如，如果您的地址类似于https://your-host/crm/public,

3 – 应提示您执行手动步骤以检查和更新旧 .htaccess 上的值

RewriteBase
- 如果您的虚拟主机指向legacySuiteCRM 8 根文件夹中的目录。那么你应该设置RewriteBase /legacy
- 否则，您应该在路径之前添加public文件夹。
  - 例如，如果您的地址类似于https://your-host/crm/public，那么你应该设置RewriteBase /crm/public/public

2.5. 运行升级命令

在您的 SuiteCRM 8 实例根运行：./bin/console suitecrm:app:upgrade -t "<version>"

在哪里<version>是您下载的 SuiteCRM 8 软件包上的名称，即SuiteCRM-8.2.0
例子： ./bin/console suitecrm:app:upgrade -t SuiteCRM-8.2.0

2.6. 运行升级后命令

在升级高度自定义的实例时，您可能会在此步骤中遇到问题。确保您的自定义代码至少符合 php 7.4。

在您的 SuiteCRM 8 实例根运行：./bin/console suitecrm:app:upgrade-finalize

2.6.1 元数据合并模式

在这个 finalize 命令中，您可以指定要用于合并元数据的合并模式。这可以通过-m在suitecrm:app:upgrade-finalize命令。keep默认使用该模式。

接下来，您可以找到每种模式的说明以及如何使用它。

1. 保持模式

默认模式是保留现有的视图元数据自定义，并且将简单地跳过元数据合并过程。
如果要在命令上指定，可以运行：./bin/console suitecrm:app:upgrade-finalize -m keep

2. 合并模式

此模式将尝试将您当前的视图元数据自定义与每个模块的新核心视图元数据合并
合并后的元数据放置在相应模块的自定义文件夹中public/legacy/custom/<Module>/metadata
先前版本的自定义设置的备份文件被添加到同一文件夹中
您可以通过运行使用合并模式./bin/console suitecrm:app:upgrade-finalize -m merge

3. 覆盖模式

此模式将使用新版本的核心元数据覆盖您当前的自定义设置。
请注意，这将删除您当前的自定义文件public/legacy/custom/<Module>/metadata
您可以通过运行使用合并覆盖模式./bin/console suitecrm:app:upgrade-finalize -m override

2.7. 重新设置权限

如果在迁移期间您使用的用户/组与 apache（或其他网络服务器）使用的用户/组不同，则应重新设置正确的权限

2.8. （可选）重启服务器以重置/清除 php 级别缓存

如果您正在使用opcache，apcu或其他 php 缓存，您可能需要重新启动网络服务器才能使新代码生效。

2.9.打开您的实例并测试

完成上述所有步骤后，您现在应该能够登录到您的 SuiteCRM 实例。

3. 日志和调试

3.1 日志

升级期间使用的命令提供了有关步骤及其执行结果的一些信息。但是，当错误发生时，这些信息是不充分的。

有一些日志可能会提供更多信息：

日志/升级.log

这些是 SuiteCRM 8 端升级日志生成的日志。

public/legacy/upgradeWizard.log

这些是由应用程序的旧部分生成的特定于升级的日志。该文件是在legacy-post-upgrade步。

日志/<app-env-mode>/<app-env-mode>.log

主应用程序日志。它的文件路径和名称会根据您设置的值而改变APP_ENV. 例如，如果它被设置为prod路径将是logs/prod/prod.log

很可能，此日志不会包含太多升级信息。

公共/旧版/suitecrm.log

这是应用程序遗留部分的主要日志位置。它可能包含升级相关的日志，以及其他日志。

3.2 APP_ENV 模式

在生产环境中运行应用程序时APP_ENV在.env或在.env.local应设置为prod。但是，此模式具有较高的日志级别，这意味着不会记录所有调试信息。

获取更多日志的一种方法是更改APP_ENVto qa（此模式只能暂时使用）。

之后APP_ENV您可能需要清除 symfony 缓存。

4. 常见问题

4.1.CSRF 代币问题

在我们的内部测试期间，我们进行了多次重新安装和升级。这些测试通常在同一个 url / 实例上完成。

在此过程中可能会发生 cookie 未更新或刷新的情况，这可能会阻止用户使用该应用程序。

如果你得到一个Invalid CSRF token错误，要尝试的一件事是刷新页面并清除 cookie。这将允许服务器为新会话生成新会话。

4.2. 运行升级命令后忘记重置权限

请确保在运行升级命令后重新设置权限。

当您使用与 apache 使用的用户不同的用户运行命令时，需要重新设置权限。请记住，当您使用另一个用户（例如 root 用户）运行命令时，php 将使用该用户，这将影响文件创建。由 php 创建的文件将设置为该用户和组。这可能会阻止应用程序运行，因为 Apache Web 服务器用户可能（并且很可能）没有读取/写入分配给该用户的文件的权限。

4.3. 在执行开始时缺少 suitecrm:app:setup-legacy-migration 命令或错误

我们注意到，这些错误通常发生在使用错误的迁移包时。

请确保您使用的是迁移包而不是 SuiteCRM 8 安装包。迁移包是专门为 7.x 到 8.x 迁移而构建的特殊包。

迁移包的名称遵循名称模式：“SuiteCRM-8.x-7.x-migration”，其中 8.x 和 7.x 是版本。

4.4. 不知道在哪里放置 SuiteCRM 7 或 SuiteCRM 8 文件夹/实例

进行升级时，您将需要在您的网络服务器上为 SuiteCRM 8 提供一个新实例。迁移包不会在现有实例之上应用迁移，换句话说，您不会将迁移包上传到 SuiteCRM 7 实例。

该过程反过来进行，SuiteCRM 7 实例将被移动/复制到 SuiteCRM 8 实例。

迁移包类似于 SuiteCRM 8 安装包，没有public/legacy文件夹。解压缩迁移包后，应将您的 SuiteCRM 7 文件夹复制到publicSuiteCRM 8 根文件夹中存在的文件夹，然后重命名为legacy. 在此过程的稍后阶段，当运行升级命令时，您的 SuiteCRM 7 代码现在在public/legacy将使用 SuiteCRM 8 包含的所有“遗留”更改进行更新。