README

这个小命令行工具可以帮助您加快在 fortrabbit 上部署 Craft CMS 的一些常见任务。Craft Copy 会同步您的本地开发环境与 fortrabbit App 的 App，包括上传和下载。它方便地部署代码更改并同步最新的图像和数据库条目。此 Craft CMS 插件将在本地和 fortrabbit App 上安装。

演示

这里 是一个介绍视频（1.5 分钟）。

要求

• 包括 Craft 5（自版本 3 以来）、PHP 8 和 Composer 的本地开发环境。
• 以下二进制文件应该是可执行的：php、mysqldump、git 和 rsync
• 应安装一个与您的 fortrabbit 账户关联的 SSH 密钥（目前不支持密码认证）
• 您需要在 fortrabbit 上有一个 App

Craft Copy 适用于通用 App 和专业 App。资产同步仅适用于具有本地资产卷的通用 App。已知它可以与 Laravel Herd、Laravel Valet 和 DDEV 本地一起工作。

安装

最佳安装方式是在您的本地计算机的终端中使用 Composer 安装 Craft Copy

# Jump into your local Craft CMS folder
cd your/craft-project

# Require Craft Copy via Composer
composer config platform --unset
composer require fortrabbit/craft-copy -W

# With the latest version of composer (2.2 or higher) you may see this prompt: 
# Do you trust "fortrabbit/craft-auto-migrate" to execute code and wish to enable it now? (writes "allow-plugins" to composer.json) [y,n,d,?] 
#
# Confirm with `y`

# Install and enable the plugin with Craft CMS
php craft plugin/install copy

您将完成一个表单，以将您的本地 App 与 fortrabbit 上的 App 连接起来。Craft Copy 可在 Craft CMS 插件商店 中找到。

使用

Craft Copy 总是在您的本地计算机上您的本地开发环境中执行。

可选的 {stage} 参数定义了命令应用于哪个 fortrabbit App。当与多个 fortrabbit Apps 一起工作时，这很有用，作为阶段。默认参数是 App 名称。有关更多信息，请参阅下面的多阶段部分。

一些命令是交互式的，这意味着您可能需要确认某些潜在的危险操作。在大多数情况下，您可以通过添加 --interactive=0 标志来禁用此类手动交互。简短的别名版本是 -i=0。

设置

# Connect your development environment with your fortrabbit App
php craft copy/setup

获取帮助

# See a list of available commands
php craft help copy

数据库

# Dump local DB (backup fortrabbit db) and import it to the fortrabbit App
php craft copy/db/up {stage}

# Dump local DB and import it to the fortrabbit App (useful if the fortrabbit db is broken)
php craft copy/db/up {stage}  --force

# Dump fortrabbit DB and import it locally
php craft copy/db/down {stage}

代码

虽然您也可以使用 git push 通过 Git 将代码部署到您的 fortrabbit App，但 Craft Copy 代码命令提供了一些额外的功能：它会检查未提交的更改并在需要时初始化 Git 仓库。

# Push code changes to the fortrabbit App
php craft copy/code/up {stage}

# Pull code changes from your fortrabbit App
php craft copy/code/down {stage}

选项和参数

• 要防止提示（例如，在 CI 管道中运行命令时），您可以使用 php craft copy/code/up -i=0 -m="您的提交信息"。

资产卷

Craft CMS 中的资产是编辑上传并由 CMS 管理的媒体文件。资产存储在卷中，不是 Git 的部分。

# Sync up a local volume to fortrabbit App
php craft copy/volumes/up {stage} {?volumeHandle}

# Sync down a vlume from the fortrabbit App to local
php craft copy/volumes/down {stage} {?volumeHandle}

• Craft CMS 控制面板中卷设置的“文件系统路径”不应是相对路径。您可以使用 @webroot 别名。
• 目前不支持远程卷（如 S3、对象存储等）

选项和参数

• {volumeHandle} 是 Craft CMS 中您的资产卷的句柄名称
• 要同步所有卷，请不要提供 volumeHandle（并添加 -i=0 以避免问题）
• 要测试实际将同步的内容，您可以使用 -n 选项来触发干运行

全部复制

通常，您希望从 App 获取所有最新的内容，或者甚至将所有本地更改推送到 App。您可以使用 all 命令来完成此操作

# Sync database, volumes and git from local to your fortrabbit App
php craft copy/all/up

# Sync database, volumes and git from your fortrabbit App to local
php craft copy/all/down

• 默认情况下，此命令不包括文件夹操作。

DDEV 支持

Craft Copy 支持使用 DDEV。一旦您启动了容器

1. ddev auth ssh - 将主机的 SSH 密钥复制到容器中
2. ddev ssh - 登录到容器
3. 然后按照需要继续操作

请参阅我们关于如何一起设置的旧 博客文章。

Craft Nitro 支持（已弃用）

由于 Craft Nitro 已弃用，此功能将在下一个主要版本中删除。

高级用法

不要停止。继续阅读，以全面了解 Craft Copy！

配置文件

setup 命令在 Craft 的 /config 文件夹中创建一个配置文件。文件名模式为 fortrabbit.{stage}.yml，其中 {stage} 是您在 setup 中定义的 fortrabbit App 环境方式。默认的 {stage} 是 App 名称，通常也可以是 production。该文件受版本控制，可以与团队共享，包括所有基本设置以及一些额外设置，如 before/after 命令。在使用 multi-staging 时，将为每个 fortrabbit App 创建一个配置文件。另请参阅 示例文件。

自动迁移

Craft Copy 集成了另一个名为 Craft auto migrate 的包。它确保在部署到 fortrabbit App 时始终运行数据库迁移。这意味着每次您通过 Git 推送代码时，都会触发数据库迁移，并立即应用 project.yaml 中的更改，而无需点击控制面板上的“应用更改”按钮。

反过来，在拉取更改时，也会运行数据库迁移。这是通过 config 文件 中的默认 after 命令 配置的。

项目配置

Craft Copy 改变了 ProjectConfig 类的行为，以防止在 CP 中执行项目配置操作。默认情况下，我们在 composer install 后的部署过程中 apply 可能的更改。

多环境

在 fortrabbit 中，您可以设置多个 App，为您的项目创建多个环境。请参阅 多环境帮助文章。

多环境配置

一旦您的 Apps 设置好，您就可以将您的本地环境与每个 App 连接起来。

# Run this command to setup a new deployment configuration for each stage
php craft copy/setup

setup 命令为每个 App 创建一个 config 文件。

多环境使用

# Copy code and db down from 'production'
php craft copy/code/down production
php craft copy/db/down production

# Make changes
# ...

# Copy code and db up to 'staging'
php craft copy/code/up staging
php craft copy/db/up staging

before/after 命令

您可以在使用 Craft Copy 运行常见的 up/down 命令之前或之后运行任何脚本。

• 将 before/after 脚本放置在您的 Craft Copy 配置文件 中。
• before/after 命令将在您的本地计算机上运行，而不是在 fortrabbit App 上。要部署时运行脚本，请考虑 Composer 的 post-install-cmd。

支持的命令

• code/up
• code/down
• db/up
• db/down
• volumes/up
• volumes/down
• folder/up
• folder/down

before/after 示例

自动化您的部署流程。每次您使用 code/up 推送新代码时，也压缩 JavaScript 和 CSS 并同步它们

before:
  # Before deploying code by Git, please:
  code/up:
    # 1. Run your NPM production build
    - "npm run prod"
    # 2. Sync the results of the build up
    - "php craft copy/folder/up production web/build/prod -i=0"

以下是一个完整的配置文件示例： config/fortrabbit.example.yaml

数据库到文件

还可以通过命令将您的数据库本地副本保存到文件中。您可以创建一个.sql文件，并将其导入到数据库中。以下是命令：

# Export DB
php craft copy/db/to-file filename

# Import DB
php craft copy/db/from-file filename
# Filename is a required parameter

请注意，还有类似的Craft CLI命令：php craft backup/db和php craft restore/db。

同步文件夹

您还可以同步不在Git中或不是资产容量的文件夹。一个常见的用例是将构建工件（如压缩的JS或CSS）同步到您的fortrabbit应用程序。这可以与前后命令结合使用。

# Sync up a folder from local to your fortrabbit App
php craft copy/folder/up {stage} {folder}

# Example usage
php craft copy/folder/up production web/build

• {folder}是从Craft可执行文件（项目根目录）看到的相对路径

在Docker环境中使用Craft Copy

您可能想在任何Docker容器中运行Craft Copy。您需要在容器内部安装以下依赖项

• mysqldump
• mysql（客户端）
• ssh（客户端）
• 访问您与fortrabbit账户保存的SSH密钥 - 例如，就像这样

Craft Copy如何工作

使用fortrabbit，您已经可以使用Git来部署代码而无需任何额外插件。当通过Git Composer部署代码时，也会触发。Craft Copy通过添加对Git排除的文件的支持来增强这一点，例如在卷中的资产、文件夹和数据库内容。

Craft Copy可以帮助汇集运行Craft CMS所需的不同数据类型。每种数据类型都是独特的，传输层也是如此。以下是一些详细信息，以便您更好地了解幕后发生的事情

模板和依赖代码通过Git

Craft Copy提供了一个轻量级Git包装器。在大多数情况下，方向将是up（推送代码），因为您将首先在本地进行开发，然后将更改推送到fortrabbit应用程序。由于Git是传输层和版本历史，这些更改是非破坏性的。您可以随时回滚。

composer.json也由Git管理，当您向该文件推送更改时，Composer将在fortrabbit部署期间运行。这不是Craft Copy，而是fortrabbit的功能。因此，您不需要通过SSH登录并手动运行Composer。此外，您不应该在fortrabbit应用程序本身的Craft CMS控制面板上触发任何更新。

资产卷

任何资产文件和文件夹，包括可以与卷命令同步上下文的图像转换。这里将使用rsync。传输标志被设置为非破坏性。不会删除任何文件，您可以在任何方向上安全地运行此操作，而不用担心任何数据丢失。您可能需要不时保持您的资产库清洁。

数据库

MySQL数据库是通过使用mysqldump进行复制的。所以它基本上会导出数据库的当前状态为一个file.sql文件，并用该文件替换其他数据库。换句话说：这是一个破坏性操作。您需要确保任何影响数据库的内容更改（如新条目或编辑条目）只在一个环境中进行，无论是本地还是fortrabbit应用程序。它不能像资产或代码那样合并更改。好消息是，Craft Copy总是会创建一个快照文件，您可以将其用于回滚。

my.conf文件

Craft Copy创建一个my.conf文件。它设置了一些默认值，以确保与不同MySQL版本工作时具有最大兼容性。请参阅此处注释的文件并了解SUPER权限这里。

故障排除Craft Copy

当满足系统要求时，设置通常是直接的。然而，根据您的本地设置，您可能会遇到错误。许多错误与MAMP相关，并且很容易修复

本地 MySQL 连接错误

php craft install/plugin copy
  *** installing copy
  *** failed to install copy: Craft CMS can’t connect to the database with the credentials in config/db.php.

修复方法：确保在 MAMP 中 "允许网络访问 MySQL" 复选框被勾选。

mysqldump 命令不存在

mysqldump 客户端是一个用于备份 mysql 数据库的命令行程序。它通常包含在 MySQL 安装中。检查您是否可以访问 mysqldump

which mysqldump
  mysqldump not found

可能的修复方法：将 MAMP 的 bin 路径添加到您的 Bash 配置文件中

echo 'export PATH=/Applications/MAMP/Library/bin:$PATH' >>~/.bash_profile

PHP 命令行版本低于 7.1

在命令行中检查 PHP 版本

php -v
  PHP 7.0.8 (cli) (built: Jun 26 2016 12:30:44) ( NTS )
  Copyright (c) 1997-2016 The PHP Group
  Zend Engine v3.0.0, Copyright (c) 1998-2016 Zend Technologies
     with Zend OPcache v7.0.8, Copyright (c) 1999-2016, by Zend Technologies

修复方法：将 MAMP 的 php bin 路径添加到您的 Bash 配置文件中

echo 'export PATH=/Applications/MAMP/bin/php/php7.2.1/bin:$PATH' >>~/.bash_profile

Composer 版本冲突

当通过 Composer 安装插件时，您可能会看到类似这样的错误

composer require fortrabbit/craft-copy:^1.0.0
  ./composer.json has been updated
  Loading composer repositories with package information
  Updating dependencies (including require-dev)
  Your requirements could not be resolved to an installable set of packages.
  
  Problem 1
  - Installation request for fortrabbit/craft-copy ^1.0.0 -> satisfiable by fortrabbit/craft-copy[1.0.0].
  - Conclusion: remove symfony/console v3.3.6
  - Conclusion: don't install symfony/console v3.3.6
  - fortrabbit/craft-copy 1.0.0 requires symfony/yaml ^4.1
  [...]
   Problem 99

修复方法：更新所有现有依赖项

composer config platform --unset
composer update
php craft migrate/all

Composer 允许插件问题

当尝试部署时，您可能会看到这样的警告

In PluginManager.php line 762: fortrabbit/craft-auto-migrate contains a Composer plugin  which is blocked by your allow-plugins config. You may add  it to the list if you consider it safe. You can run "composer config --no-plugins allow-plugins.fortrabbit/craft-auto-migrate [true|false]" to enable it (true) or disable it explicitly and suppress this exception (false) See https://getcomposer.org.cn/allow-plugins

这是 Composer 的新安全策略在起作用，并且通常发生在您很久以前安装插件时。

修复方法：配置 Composer 以允许插件

composer config --no-plugins allow-plugins.fortrabbit/craft-auto-migrate true