使用 WP-CLI 远程运行命令

使用 SSH 连接

WP-CLI 是 WordPress 的命令行界面，用于以程序化方式执行管理和开发任务，项目网站为 wp-cli.org 和 WordPress WP-CLI 项目页。它接受全局参数 --ssh=[<scheme>:][<user>@]<host>[:<port>][<path>]，对远程 WordPress 安装执行命令。该参数的写法类似于 scp、git 等工具中指定 SSH 连接的方式。SSH（Secure SHell）是一种安全连接远程系统的协议。

在内部，WP-CLI 将命令转交给 ssh 可执行程序，再由它传给远程机器上安装的 WP-CLI。该参数按以下规则解释：

• scheme 默认为 ssh，也接受 vagrant、docker 和 docker-compose。
• 只提供 host 时，例如 wp --ssh=example.com，用户名取当前系统用户，端口采用 SSH 默认端口22，路径采用 SSH 用户的主目录。
• 可以在主机前添加以 @ 结束的前缀来覆盖 user，例如 wp --ssh=admin_user@example.com。
• 可以在主机后添加以冒号开头的后缀来覆盖 port，例如 wp --ssh=example.com:2222。
• 可以添加路径后缀来覆盖 path，例如 wp --ssh=example.com~/webapps/production。路径紧接端口；如果没有显式指定端口，则紧接主机的顶级域名。
• 也可以提供 ~/.ssh/config 中已知的 alias。例如，原文对 @rc 别名给出的调用是 wp --ssh=rc。

另外，如果你定义了 shell 别名，或者通过配置扩展了 $PATH，--ssh=<host> 不会加载 ~/.bash_profile。遇到这种情况，可以参阅使远程服务器能够调用 wp 的详细说明。

连接方案（scheme）

可以使用 SSH 参数中的 scheme 部分，为连接本地容器或虚拟机定义简写。默认 scheme 是 ssh，其他选项是 vagrant、docker 和 docker-compose。

docker

使用 Docker 时，命令为 wp rewrite flush --ssh=docker:<name>。可以运行 docker ps 找到 Docker 容器名称。

docker-compose

使用 Docker Compose 时，命令为 wp option get home_url --ssh=docker-compose:<name>。Docker 容器名称可在 docker-compose.yml 中找到。

vagrant

使用 Vagrant 时，可以执行 wp rewrite flush --ssh=vagrant:<name>。

别名

WP-CLI 别名是注册在 wp-cli.yml 或 config.yml 中的快捷方式，让你方便地针对任意 WordPress 安装执行命令。

例如，本地开发时注册了新的重写规则，需要在基于 Vagrant 的虚拟机内刷新规则，可以运行：

# Run the flush command on the development environment
$ wp @dev rewrite flush
Success: Rewrite rules flushed.

代码上线后，可以运行：

# Run the flush command on the production environment
$ wp @prod rewrite flush
Success: Rewrite rules flushed.

不必先 SSH 登录机器、切换目录，再花一分钟找到指定的 WordPress 安装。只需告诉 WP-CLI 应使用哪台机器，它就会建立实际连接。

它也能使用 Vagrant 的 SSH 辅助命令确定连接参数：采用 vagrant scheme，例如 --ssh=vagrant:default，把 WP-CLI 命令传给 vagrant ssh。这里的 default 是 Vagrant 虚拟机名称或ID，也可以像下例一样注册为别名。部分 Vagrant box 默认带有这项配置，因此宿主机可以直接使用 WP-CLI。

别名组还允许把多个别名注册成一组。若要对两个示例站点执行同一命令，可以使用 @both 这样的组：

# Run the update check on both environments
$ wp @both core check-update
Success: WordPress is at the latest version.
Success: WordPress is at the latest version.

别名可以注册在项目的 wp-cli.yml 中，也可以注册在用户的全局文件 ~/.wp-cli/config.yml 中：

@prod:
  ssh: dev_user@example.com~/webapps/production
@dev:
  ssh: vagrant@192.168.50.10/srv/www/example.dev
@local:
  ssh: vagrant:default
@both:
  - @prod
  - @dev

有关配置文件的更多信息，参见配置章节。

远程运行自定义命令

要在远程服务器执行自定义命令，该命令必须安装在远程服务器上；不必安装在启动 wp 的本地机器上。

可以远程使用 WP-CLI 包管理器，把自定义命令安装到远程机器。例如：

# The command is not installed on either local or remote machine
$ wp db ack
Error: 'ack' is not a registered subcommand of 'db'. See 'wp help db'.
$ wp @dev db ack
Error: 'ack' is not a registered subcommand of 'db'. See 'wp help db'.

# To make the command work on the remote machine, we can install it remotely
# through the WP-CLI package manager
$ wp @dev package install runcommand/db-ack
Installing package runcommand/db-ack (dev-master)
Updating /home/vagrant/.wp-cli/packages/composer.json to require the package...
Using Composer to install the package...
---
Loading composer repositories with package information
Updating dependencies
Resolving dependencies through SAT
Dependency resolution completed in 0.311 seconds
Analyzed 4726 packages to resolve dependencies
Analyzed 162199 rules to resolve dependencies
Package operations: 1 install, 0 updates, 0 removals
Installs: runcommand/db-ack:dev-master aff8ccc
 - Installing runcommand/db-ack (dev-master aff8ccc)
Writing lock file
Generating autoload files
---
Success: Package installed.

# Now we can run the command remotely, even though it is not installed locally
$ wp @dev db ack test_email@example.com
wp_users:user_email
9:test_email@example.com

使远程服务器能够调用 WP-CLI

通过 SSH 远程执行命令，要求远程服务器的 $PATH 能找到 wp。由于 SSH 连接不会加载 ~/.bashrc 或 ~/.zshrc，使用 wp --ssh=<host> 时可能需要指定自定义 $PATH。以下是几种使远程服务器能够调用 wp 的方法。

把 WP-CLI 可执行文件复制到 $HOME/bin

许多 Linux 发行版默认把 $HOME/bin 加入 $PATH。因此，可以先创建尚不存在的 $HOME/bin 目录，再将 WP-CLI 文件放到 $HOME/bin/wp：

mkdir -p ~/bin
cd ~/bin
curl -O https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar
chmod +x wp-cli.phar
mv wp-cli.phar wp

如果 $HOME/bin 尚未出现在路径中，可以在远程服务器的 ~/.bashrc，或对应 shell 的配置文件中定义：

#.bashrc
PATH="$HOME/bin:$PATH"

在 $HOME/.ssh/environment 中指定 $PATH

另一种方法是在远程用户的 ~/.ssh/environment 中指定 $PATH，前提是该机器的 sshd 已配置 PermitUserEnvironment=yes。参见 OpenSSH 文档。

让远程非交互式 shell 解析别名，通过 PHP 执行 wp

某些托管服务的限制很严格：

• 不允许执行自己的 shell 脚本，因此放置 WP-CLI 可执行文件的方法失败。
• sshd 设置为 PermitUserEnvironment=no，因此修改 ~/.ssh/environment 没有效果。
• 在客户端使用 before_ssh hook 同样无济于事，因为这些情况下都无法在远程直接运行 wp。

解决办法是在远程按以下方式配置 ~/.bashrc。

配置远程非交互式 shell 解析别名

• 默认情况下，非交互式 shell 不会解析别名，但可以改变这种行为。在 ~/.bashrc 靠前的位置，至少在首次定义别名之前，插入：

shopt -s expand_aliases

还要确保非交互式 shell 不会被某种机制提前退出。如果文件顶部存在下面这样的结构，例如 Ubuntu 的默认配置，请把整个结构注释掉或删除：

# If not running interactively, don't do anything
[ -z "$PS1" ] && return

将 wp 定义为通过 PHP 执行 WP-CLI 文件的别名

• 在 shopt -s expand_aliases 后插入 alias wp="php ~/bin/wp"，或者 alias wp="php ~/bin/wp-cli.phar"。
• 也就是说，wp 是一个单行别名，通过给出 PHAR 文件路径，让 PHP 执行 WP-CLI。文件可以放在任意位置，使用任意名称。
• 基本所有托管服务都允许运行 php。
• wp-cli.phar 本身甚至不必带可执行标记，它可以完全作为被动文件，由 php 解释执行。可执行的 ~/bin/wp（重命名并设置了可执行标记的 PHAR）最终同样会交给 PHP 解释，但 shell 层面的调用方式不同，这正是这里的关键区别。

在客户端使用 before_ssh hook

如果无法在服务器内部完成设置，也可以挂接 before_ssh hook，定义一个环境变量，其中包含希望执行的命令，以达到相同效果：

WP_CLI::add_hook( 'before_ssh', function() {

    $host = WP_CLI\Utils\parse_ssh_url(
        WP_CLI::get_runner()->config['ssh'],
        PHP_URL_HOST
    );

    switch( $host ) {
        case 'example.com':
            putenv( 'WP_CLI_SSH_PRE_CMD=export PATH=$HOME/bin:$PATH' );
            break;
    }
} );

把上述代码放在 pre-ssh.php 中，然后在 ~/.wp-cli/config.yml 中引入这个文件，就能在整个环境中加载：

require:
  - pre-ssh.php