# 在您的WordPress网站上使用WP-CLI

Source: https://support.kapsulehost.com/zh-cn/wordpress-wp-cli

KPanel 包含一个 WP-CLI 控制台，可直接在浏览器中对您的 WordPress 网站运行命令，无需 SSH 客户端，也无需登录服务器。本指南将介绍该控制台的位置、具体允许运行哪些命令及其原因、界面内置的快捷方式，以及当您需要控制台无法运行的操作时应如何处理。

## 打开控制台

1. 登录 [KPanel](https://kpanel.kapsulehost.com)，点击左侧边栏中的 **网站**。
2. 点击您的 WordPress 网站。
3. 打开 **WordPress** 选项卡，然后进入 **Console** 部分。

![KPanel 中 WordPress 网站上的 WP-CLI 控制台](https://support.kapsulehost.com/help/screenshots/wordpress-wp-cli.c3f61741.webp)

输入框已固定显示 `wp`，因此您只需输入其后的内容。`plugin list`，而非 `wp plugin list`。按回车键或点击 **Run**。

> **Note:** **Console** 是在托管套餐中才会显示的部分之一。在其他套餐中，选项卡栏末尾会显示一个 **+8 on Managed** 链接。本文中提到的每一个非原始命令的操作，在 KPanel 的其他位置都有对应的按钮，因此没有什么是无法实现的：控制台只是访问同一引擎的更快方式。

命令以您网站自身的系统用户身份运行，且仅在您网站自身的目录内执行，无法看到或触及任何其他网站。

## 控制台可以运行和不可以运行的内容

控制台使用白名单机制。下表中列出的命令前缀才会被接受，其余命令会在到达服务器之前就被拒绝，并显示一条说明被拒绝命令名称的提示信息。

| 类别 | 允许的命令 |
|---|---|
| 核心 | `core version`, `core check-update`, `core update`, `core is-installed`, `core verify-checksums` |
| 插件 | `plugin list`, `plugin update`, `plugin install`, `plugin activate`, `plugin deactivate`, `plugin status`, `plugin get`, `plugin delete`, `plugin verify-checksums` |
| 主题 | `theme list`, `theme update`, `theme install`, `theme activate`, `theme status`, `theme get`, `theme delete` |
| 用户 | `user list`, `user get`, `user create`, `user update`, `user set-role`, `user delete`, `user reset-password`, `user add-cap`, `user remove-cap`, `user generate` |
| 数据库 | `db size`, `db tables`, `db optimize`, `db repair`, `db check` |
| 缓存与瞬态 | `cache flush`, `cache get`, `cache set`, `cache add`, `cache delete`, `transient get`, `transient set`, `transient delete` |
| 重写规则 | `rewrite flush`, `rewrite list`, `rewrite structure` |
| 计划任务（cron） | `cron event list`, `cron event run`, `cron schedule list` |
| 配置 | `config get`, `config list`, `config has`, `config shuffle-salts` |
| 维护模式 | `maintenance-mode activate`, `maintenance-mode deactivate`, `maintenance-mode status` |
| 只读检查 | `option get`, `option list`, `post list`, `post get`, `comment list`, `comment get` |
| 媒体与语言 | `media regenerate`, `language core install`, `language core update` |
| 搜索与替换 | `search-replace` |

刻意排除的内容比允许的内容更为重要：

- **`eval` 和 `shell`** 均被禁用。任意执行 PHP 或任意执行 Shell 命令，会使控制台等同于在浏览器标签页中获得 root 权限提示符。
- **`db import`、`db export`、`db drop`、`db query` 和 `db reset`** 均被禁用。导入和重置操作会在没有任何确认步骤的情况下破坏数据库；`db query` 则是一个不受限制的 SQL 提示符。请改用 phpMyAdmin：[通过 phpMyAdmin 访问您的数据库](https://support.kapsulehost.com/zh-cn/sites-phpmyadmin)。
- **`config set` 和 `config delete`** 均被禁用。错误的 `wp-config.php` 写入会导致网站下线。请在此处查看相关值，并通过文件管理器进行修改。
- **`option update` 和 `option delete`** 均被禁用。盲目编辑选项是导致网站无法恢复的常见方式。

> **Warning:** 无论执行何种命令，控制台都不会为您自动备份。只有 **快速操作** 部分中的按钮才会执行备份。在执行 `search-replace`、`core update`、`plugin update`、`theme update`、`db optimize` 或 `db repair` 之前，请先在网站的 **备份** 页面中自行进行备份。请参阅[创建备份](https://support.kapsulehost.com/zh-cn/taking-a-backup)。

## 在控制台中操作

该界面的功能不仅限于一次接受一条命令。

**预设按钮。** 命令提示符上方分组排列着多种快捷方式：Performance（清空缓存、清除瞬态、刷新重写规则、自动加载检查）、Database（优化、检查、修复、大小）、Diagnostics（WP 版本、检查更新、验证核心、计划任务事件）、Content（列出插件、主题、用户，立即运行计划任务）、Security（管理员用户、插件校验和、重置密钥、wp-config）以及 Maintenance（启用和关闭维护模式、重新生成缩略图、状态）。只需点击一次即可运行相应命令。

**历史记录。** 在提示符中按上下方向键，即可浏览您在该网站上最近的 50 条命令记录。

**代码片段。** 点击命令旁边的书签图标，即可为其命名并保存，这样每月都要使用的长命令，下次只需点击一次即可执行。

**环境信息卡。** 提示符上方的卡片会显示网站的 PHP 版本、WordPress 版本、内存限制、当前已用内存、上传大小上限以及执行时间限制，并附有一个 **复制以供支持** 按钮，可将上述全部信息连同您当前启用的插件列表一并复制到剪贴板。将其粘贴到支持工单中，即可省去一次往返沟通。

**复制输出。** 每个结果区块都配有复制和清除按钮。

命令运行时，输出会实时流式返回，因此长时间运行的操作会显示进度，而不是毫无反应。

## 值得了解的命令

### 诊断

```
core version
core verify-checksums
plugin verify-checksums --all
plugin list --status=active --format=table
db size --tables
option list --autoload=yes
```

`verify-checksums` 会将您的核心文件和插件文件与官方发布的版本进行比对，并报告任何被修改的内容。对于您怀疑被篡改的网站，这是最快的初步检查方式。

`option list --autoload=yes` 会列出 WordPress 在每一次请求中加载的所有选项。自动加载表过于臃肿，是导致网站出现莫名卡顿的最常见原因之一。

### 日常维护

```
cache flush
transient delete --all
rewrite flush
db optimize
cron event list
cron event run --due-now
```

### 用户

```
user list --role=administrator --format=table
user create jo jo@example.com --role=editor
user update 4 --user_pass='a-long-unique-password'
```

在此处输入的任何内容（包括密码）都会被记录在您账户的活动日志中。如果您以这种方式设置了密码，请在登录后尽快进行更改。关于账户恢复的完整说明，请参阅[重置丢失的 WordPress 管理员密码](https://support.kapsulehost.com/zh-cn/wordpress-reset-password)。

### 搜索与替换

```
search-replace 'http://old-domain.co.nz' 'https://old-domain.co.nz' --all-tables --dry-run
```

请务必先进行试运行（dry run）。完整操作步骤，包括为何直接使用原始 SQL 替换会破坏 WordPress 数据库，请参阅[执行搜索与替换](https://support.kapsulehost.com/zh-cn/wordpress-search-replace)。

## 控制台还是 Quick Actions？

两者底层运行的都是同一套 WP-CLI。请按以下原则选择：

| 任务 | 更合适的方式 |
|---|---|
| 清空缓存、更新插件、重新生成媒体文件 | **快速操作**，一键完成且会先行备份 |
| 按数据表预览的搜索与替换 | **快速操作**，Search & Replace 卡片 |
| 需要特定参数的任何操作 | 控制台 |
| 列出、查看、诊断类操作 | 控制台 |
| 运行某个逾期的计划任务事件 | 控制台 |
| 编辑 `wp-config.php` 或导入数据库 | 两者皆不适用，请使用文件管理器或 phpMyAdmin |

## 当您需要超出白名单范围的功能时

如需不受限制地使用 WP-CLI，请通过 SSH 连接，并直接在网站目录中运行 `wp`。SSH 仅支持密钥认证，因此请先在网站的 **设置** 中的 **SSH 密钥** 选项卡添加您的公钥。连接详情（包括确切的主机、端口和用户名）会显示在同一屏幕上。请参阅[添加 SSH 密钥](https://support.kapsulehost.com/zh-cn/adding-ssh-keys)和[通过 SFTP 连接](https://support.kapsulehost.com/zh-cn/sftp-access)。

## 故障排查

**“'x y' is not in the allowed command list.”** 该命令不在白名单之列。请查阅上表，找到最接近的允许命令，或改用 SSH。

**“No results returned. Check that WP-CLI is available.”** 命令已运行但未输出任何内容，这通常是查询无匹配结果时的正常表现。

**命令超时。** 控制台命令的运行时间上限为 60 秒。对于重新生成大型媒体库等耗时较长的操作，应从 **快速操作** 运行（其限制时间更长），或改用 SSH。

**没有任何操作运行，按钮均显示为禁用状态。** 您的 KapsuleHost 账户在该网站上的角色为只读。请联系账户所有者提升您的权限。