farmOS 4.0.9 常用 CLI 命令与工具详解

目标：讲清 farmOS 4.0.9 的命令行管理工具 Drush 13——站点状态检查、缓存重建、配置管理、用户与角色管理、CRON 与队列、日志查看、模块启停、数据库备份、更新与部署等常用命令，全部命令与回显逐条实测照抄（实测日期：2026-10-23，Ubuntu 22.04 + Apache + PHP 8.4 + PostgreSQL 16 实装站点，安装过程见《Ubuntu 22.04 安装 farmOS 4.0.9 指南》）。

一、环境信息

farmOS 4.0.9（farm profile 安装），代码库位于 /opt/drupal
Drupal 11.3.19 / Drush 13.8.0.0 / PHP 8.4.27 / PostgreSQL 16.15 / Apache 2.4.52
Drush 可执行文件：/opt/drupal/vendor/bin/drush
站点配置目录：/opt/drupal/web/sites/default/
已启用模块 81 个（其中 farmOS 包及 farm 前缀模块 45 个，实测 drush pm:list --status=enabled 统计）
示例站点管理员：admin，测试用户密码统一用 q1w2e3r4

二、工具概览

2.1 Drush 与 farmOS 的关系

farmOS 是 Drupal 11 发行版，Drupal 生态的标准命令行工具就是 Drush（DRUpal SHell）。farmOS 没有自己独立的 CLI 程序，日常运维（清缓存、跑 CRON、重置密码、备份数据库、更新数据库表结构）全部通过 Drush 完成；此外 farmOS 在 Drush 中注册了一条专属命令 farm_update:rebuild（见 12.3 节）。

Drush 命令的通用形式：

cd /opt/drupal && vendor/bin/drush <command> [参数] [选项]

Drush 13 的多数命令支持短别名（如 cr = cache:rebuild、uli = user:login），命令清单里括号内即别名。

2.2 命令体系总览

实测 drush list 输出（节选首部，完整清单可用同命令查看）：

Drush Commandline Tool 13.8.0.0

Run `drush help [command]` to view command-specific help.  Run `drush topic` to read even more documentation.

Available commands:
_global:
  archive:dump (ard)          Backup your code, files, and database into a
                              single file.
  browse                      Display a link to a given path or open link in
                              a browser.
  completion                  Dump the shell completion script
  content:export              Exports content entities in YAML format.
  drupal:directory (dd)       Return the filesystem path for modules/themes
                              and other key folders.
  err:purge (errp)            Orphan composite revision deletion.
  farm_update:rebuild         Rebuild farmOS configuration.
  generate (gen)              Generate boilerplate code for
                              modules/plugins/services etc.
  help                        Display usage details for a command.
  jn:get                      Execute a JSONAPI request.
  list                        List available commands.
  mk:docs                     Build a Markdown document for each available
                              Drush command/generator.
  recipe                      Applies a recipe to a site.
  runserver (rs, serve)       Runs PHP's built-in http server for
                              development.
  version                     Show Drush version.
  workspace:publish           Publish a workspace.

按用途归类的常用命令速查表（均为 farmOS 4.0.9 实装站点上实测存在的命令）：

分类	命令（别名）	用途
状态	`core:status`（st）、`core:requirements`（rq）	环境总览、健康检查
缓存	`cache:rebuild`（cr）、`cache:clear`（cc）、`cache:warm`	重建/清除/预热缓存
配置	`config:get`（cget）、`config:set`（cset）、`config:status`（cst）、`config:export`（cex）、`config:import`（cim）	查改导导配置
用户	`user:information`（uinf）、`user:login`（uli）、`user:create`（ucrt）、`user:password`（upwd）、`user:block`（ublk）、`user:unblock`（uublk）、`user:cancel`（ucan）、`user:role:add`（urol）、`user:role:remove`（urrol）	用户与角色管理
角色	`role:create`（rcrt）、`role:delete`（rdel）、`role:list`（rls）、`role:perm:add`（rap）、`role:perm:remove`（rmp）	角色与权限
计划任务	`core:cron`（cron）	手动跑 CRON
队列	`queue:list`、`queue:run`	查看与执行队列
日志	`watchdog:show`（ws）、`watchdog:show-one`（wd-one）、`watchdog:list`（wd-list）、`watchdog:tail`（wt）、`watchdog:delete`（wd-del）	数据库日志
模块	`pm:list`（pml）、`pm:install`（in/en）、`pm:uninstall`（un/pmu）	模块启停
数据库	`sql:query`（sqlq）、`sql:connect`、`sql:cli`（sqlc）、`sql:dump`、`sql:cli`	查询与备份
备份	`archive:dump`（ard）	代码+文件+库一键归档
更新	`updatedb`（updb）、`updatedb:status`（updbst）、`deploy`、`deploy:hook`、`deploy:hook-status`	数据库更新与部署钩子
维护	`maint:get`（mget）、`maint:set`（mset）、`maint:status`（mstatus）	维护模式
状态存储	`state:get`（sget）、`state:set`（sset）、`state:delete`（sdel）	state 键值
PHP	`php:eval`（ev）、`php:cli`（php）、`php:script`（scr）	PHP 调试
主题	`theme:install`（thin）、`theme:uninstall`（thun）、`theme:dev`（thdev）	主题管理
迁移	`migrate:status`（ms）、`migrate:import`（mim）、`migrate:rollback`（mr）	数据迁移
farmOS 专属	`farm_update:rebuild`	重建 farmOS 配置

解读：日常运维最高频的是 cr（清缓存）、cron（跑任务）、uli（拿登录链接）、ws（看日志）四条；涉及代码升级时 updb 与 farm_update:rebuild 必跑（详见第十二节）。

2.3 farmOS 专属命令

farmOS 在 Drush 中注册的专属命令只有一条，实测 drush help farm_update:rebuild：

Rebuild farmOS configuration.

Examples:
 farm_update:rebuild Rebuild farmOS configuration.

Global options:
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output,
                     2 for more verbose output and 3 for debug
-y, --yes            Auto-accept the default for all user prompts. Equivalent
                     to --no-interaction.
-l, --uri=URI        A base URL for building links and selecting a
                     multi-site. Defaults to https://default.
                     To see all global options, run `drush topic` and pick
                     the first choice.

farmOS 的资产管理（asset/log/plan 等实体）没有专属 Drush 命令，增删改查走 Web 后台或 farmOS API（REST/JSON:API），命令行侧以 pm（模块）、sql（数据库）、php:eval（代码级操作）配合使用。

三、前置条件

已按《Ubuntu 22.04 安装 farmOS 4.0.9 指南》完成安装，站点可正常访问；
所有命令在站点根目录 /opt/drupal 下执行（Drush 靠该目录定位站点）：
为省去每次写 vendor/bin/drush 全路径，可创建符号链接（实测）：

ln -s /opt/drupal/vendor/bin/drush /usr/local/bin/drush
drush --version

实测回显：

Drush Commandline Tool 13.8.0.0

⚠️ 说明：本文后续命令统一用短形式 drush；未建符号链接的环境请自行替换为 cd /opt/drupal && vendor/bin/drush。

查看某条命令的完整帮助与参数：drush help <命令>，如 drush help user:cancel。

四、站点状态与环境检查命令

本节命令用于快速回答「站点现在什么状态、环境是否健康」。

4.1 drush status：环境总览

cd /opt/drupal && vendor/bin/drush status

实测回显（完整 28 行）：

 Drupal version   : 11.3.19
 Site URI         : http://default
 DB driver        : pgsql
 DB hostname      : 127.0.0.1
 DB port          : 5432
 DB username      : farm
 DB name          : farm
 Database         : Connected
 Drupal bootstrap : Successful
 Default theme    : gin
 Admin theme      : seven
 PHP binary       : /usr/bin/php8.4
 PHP config       : /etc/php/8.4/cli/php.ini
 PHP OS           : Linux
 PHP version      : 8.4.27
 Drush script     : /opt/drupal/vendor/bin/drush.php
 Drush version    : 13.8.0.0
 Drush temp       : /tmp
 Drush configs    : /opt/drupal/vendor/drush/drush/drush.yml
 Install profile  : farm
 Drupal root      : /opt/drupal/web
 Site path        : sites/default
 Files, Public    : sites/default/files
 Files, Private   : /opt/drupal/web/sites/default/private/files
 Files, Temp      : /tmp
 Drupal config    : sites/default/files/config_w2RH6iHvSaYa2GVI9U6iQghro9LHZp
                   TCK0bM25tvtwD77GQ1y6S_yEpfbg51CQKMdhSsYv7oyw/sync

要点：Database : Connected + Drupal bootstrap : Successful 两行说明数据库连通且站点引导成功，是最常用的「活着没」判据；Site URI : http://default 是默认值，user:login 生成的链接会以它为前缀（见 7.2 节）。

4.2 status 字段过滤

只要个别字段时用 --fields=（逗号分隔多个字段名）：

drush status --fields=drush-version,php-version,db-driver

实测回显：

Drush version : 13.8.0.0
PHP version   : 8.4.27
DB driver     : pgsql

适合脚本里取值（每行 字段 : 值，grep 即可提取）。

4.3 core:requirements（rq）：健康检查

drush core:requirements

输出较长，节选（实测尾部）：

  PHP extensions    Info       Enabled

  PHP memory        Info       256M
  limit
  PHP OPcode        Info       Enabled
  caching
  Random number     Info       Successful
  generation
  Trusted           Error      Not enabled
  Host
  Settings
  Database          Info       Up to date
  updates
  Access to         Info       Protected
  update.php
  Update            Info       Enabled
  notifications
  Module and        Info       Up to date [1]
  theme update
  status                       [1]
                               http://default/admin/reports/updates

  Drupal            Warning    Out of date (version
  core update                  11.4.11 available) [1]
  status
                               [1]
                               http://default/admin/reports/updates

  Web server        Info
 ----------------- ---------- --------------------------------------

要点：Trusted Host Settings 报 Error（Not enabled） 是 farmOS 装完后的常态——$settings['trusted_host_patterns'] 默认未启用，生产必须配置，配置方法与影响见《farmOS 4.0.9 配置参数详解》5.2 节；Drupal core update status 的 Warning 表示官方有新版本可升级。

4.4 site:alias：站点别名

drush site:alias

实测回显：

 [success] No site aliases found.

站点别名（site alias）用于远程操作多站点（@alias 形式调用），单机安装默认没有，忽略即可。

五、缓存管理命令

Drupal 把渲染结果、配置、路由等全部放在缓存里，改完代码/配置后「不生效」的第一排查动作就是清缓存。

5.1 cache:rebuild（cr）：重建全部缓存

drush cr

实测回显：

 [success] Cache rebuild complete.

cr 是使用频率最高的 Drush 命令：修改 settings.php、services.yml、启用模块、改模板之后都应执行一次。

5.2 cache:clear（cc）：清除指定缓存

drush cache:clear

实测回显（不带参数时清除默认 render 缓存）：

 [success] 'render' cache was cleared.

cache:clear 后面可以跟具体 bin 名（如 drush cache:clear data）；与 cr 的区别：cc 只清指定缓存桶、速度更快，cr 重建全部（含路由、依赖注入定义）。

5.3 cache:warm：预热缓存

drush cache:warm

实测回显：

 [success] Warmed caches.

清缓存后立即预热，可避免上线后首批请求变慢。

⚠️ 注意：cache:get <key> 是取单条缓存对象，参数是缓存键名而非 bin 名——传 bin 名会报错（实测 drush cache:get render 回显 The render object in the default bin was not found.），日常运维少用，不展开。

六、配置管理命令

Drupal 的「活动配置」存在数据库中（区别于 settings.php 文件参数），Drush 提供了读写与同步命令。配置体系全貌见《farmOS 4.0.9 配置参数详解》第三章。

6.1 config:get：读配置

drush config:get system.site

实测回显（整个配置对象）：

_core:
  default_config_hash: HlN7eAN2N4JIHsYv56V4E7sqC9bS609KwvGFjyD_mgk
langcode: en
uuid: a43a2d95-163d-4cfb-8cf5-11e0ae85f006
name: 'farmOS Demo'
mail: admin@example.com
slogan: ''
page:
  403: /403
  404: ''
  front: /dashboard
admin_compact_mode: false
weight_select_max: 100
default_langcode: en
mail_notification: null

只取某个键（对象名后跟键路径）：

drush config:get system.logging error_level

实测回显：

'system.logging:error_level': hide

6.2 config:set：改配置

drush config:set system.logging error_level verbose -y

实测回显：

 active store was saved with new value(s).

-y 跳过确认。改完的配置立即生效（活动配置直接写库），无需清缓存。上面的示例把错误详情改为 verbose（开发期排障用，生产请保持默认 hide）。

6.3 config:status：核对文件库差异

drush config:status

实测输出节选（首部）：

 --------------------------------------- ------------
  Name                                    State
 --------------------------------------- ------------
  admin_toolbar.settings                  Only in DB
  block.block.claro_breadcrumbs           Only in DB
  block.block.claro_help                  Only in DB
  block.block.claro_local_actions         Only in DB
  block.block.claro_messages              Only in DB
  block.block.claro_page_title            Only in DB
  block.block.claro_primary_local_tasks   Only in DB
  block.block.claro_secondary_local_tas   Only in DB

Only in DB 表示该配置只存在于数据库、还没导出到文件系统的 sync 目录——farmOS 刚装完这是正常状态。

6.4 config:export：导出配置到文件

drush config:export -y

实测回显：

 // The .yml files in your export directory will be deleted and replaced with
 // the active config.: yes.

 [success] Configuration successfully exported to sites/default/files/config_w2RH6iHvSaYa2GVI9U6iQghro9LHZpTCK0bM25tvtwD77GQ1y6S_yEpfbg51CQKMdhSsYv7oyw/sync.
sites/default/files/config_w2RH6iHvSaYa2GVI9U6iQghro9LHZpTCK0bM25tvtwD77GQ1y6S_yEpfbg51CQKMdhSsYv7oyw/sync

配套的 config:import（cim）把 sync 目录的配置反向导入数据库，两者是环境间搬运配置的标准通道。

七、用户与角色管理命令

本节用一条实测链路演示用户全生命周期管理：创建 → 授权 → 封禁/解封 → 改密 → 注销删除，全部输出照抄。

7.1 user:information：查用户信息

drush user:information admin

实测回显：

 --------- ----------- ------------------- --------------- -------------
  User ID   User name   User mail           User roles      User status
 --------- ----------- ------------------- --------------- -------------
  1         admin       admin@example.com   authenticated   1
 --------- ----------- ------------------- --------------- -------------

User status 为 1 是启用、0 是封禁。

忘记密码或锁在后台外时最有用的一条命令：

drush user:login admin

实测回显：

http://default/user/reset/1/1792762610/SnSoo-Sh0iTcBn1FzGSSehbsy4rzlH4v0vr5-VkGDW8/login?destination=admin

链接中的 1 是用户 UID，长数字是过期时间戳，最后一段是签名令牌；
域名部分取自 status 里的 Site URI（默认 http://default）——浏览器访问时把 http://default 换成你的真实站点地址即可，路径与参数原样保留；
destination=admin 表示登录后跳到后台首页。

7.3 用户创建 → 删除全流程

创建用户（用户名 farmtest、邮箱、初始密码三件套）：

drush user:create farmtest --mail="farmtest@example.com" --password="q1w2e3r4"

实测回显：

 [success] Created a new user with uid 2
 --------- ----------- ---------------------- --------------- -------------
  User ID   User name   User mail              User roles      User status
 --------- ----------- ---------------------- --------------- -------------
  2         farmtest    farmtest@example.com   authenticated   1
 --------- ----------- ---------------------- --------------- -------------

给用户加角色——⚠️ 参数顺序是「角色在前、用户在后」（这是 Drush 13 最容易踩的坑，写反会报错）：

drush user:role:add farmops farmtest

实测回显（角色已存在时）：

 [success] Added farmops role to farmtest

参数写反时的真实报错（角色名和用户名位置颠倒，Drush 把 farmtest 当角色去找）：

 [error]  Unable to load the user_role: farmtest

加完用 user:information 验证：

drush user:information farmtest

实测回显（User roles 多出 farmops）：

 --------- ----------- ---------------------- --------------- -------------
  User ID   User name   User mail              User roles      User status
 --------- ----------- ---------------------- --------------- -------------
  2         farmtest    farmtest@example.com   authenticated   1
                                               farmops
 --------- ----------- ---------------------- --------------- -------------

封禁与解封：

drush user:block farmtest

实测回显：

 [success] Blocked user(s): farmtest

drush user:unblock farmtest

实测回显（解封同时 Drupal 会尝试发送「账户解封」通知邮件；本机未装邮件代理所以报邮件错误，但解封操作本身已成功——两行回显要看全）：

sh: 1: /usr/sbin/sendmail: not found
 [error]  Error sending email (from admin@example.com to farmtest@example.com with reply-to admin@example.com).
 [success] Unblocked user(s): farmtest
 [error]  Message: Unable to send email. Contact the site administrator if the problem persists.

重置密码：

drush user:password farmtest "q1w2e3r4"

实测回显：

 [success] Changed password for farmtest.

注销账户。user:cancel 默认只是禁用账户（保留内容），实测回显：

drush user:cancel farmtest

>  [notice] Blocked user: farmtest <farmtest@example.com>.
>  [notice] Message: Account /farmtest/ has been disabled.

要彻底删除用户及其创建的内容，加 --delete-content（实测，成功后无输出）：

drush user:cancel farmtest --delete-content

删除后再次查询同一用户，Drush 报「找不到用户」，可作删除成功的验证：

 [warning] Unable to load user: farmtest

In UserCommands.php line 380:

  Unable to find any matching user

另一个内容保留选项 --reassign-content（把该用户的内容转给匿名用户）同样可用，按需选择。

7.4 角色管理命令

查看站点现有角色（farmOS 默认装完后只有两个基础角色；「农场经理/工人/查看者」等业务角色需按需在后台创建或启用相应模块后出现）：

drush role:list

实测回显（完整）：

anonymous:
  rid: anonymous
  label: 'Anonymous user'
  perms: {  }
authenticated:
  rid: authenticated
  label: 'Authenticated user'
  perms: {  }

创建角色（机器名 + 可读名两个位置参数）：

drush role:create farmops "Farm Ops"

实测回显（首次创建）：

 [success] Created "farmops"

重复创建同名角色的真实报错：


In EntityStorageBase.php line 558:

  'user_role' entity with ID 'farmops2' already exists.

给角色授予权限（权限名可在后台「权限」页的复选框上看到机器名）：

drush role:perm:add farmops "access content"

实测回显：

 [success] Added "access content" to "farmops"

删除角色（7.3 节演示完的角色清理）：

drush role:delete farmops

实测回显：

 [success] Deleted "farmops"

八、CRON 与队列命令

farmOS 依赖 CRON 执行例行维护（数据聚合、更新检查、队列消化等）。命令行手动触发是最常用的调试与兜底手段。

8.1 core:cron：手动执行 CRON

drush core:cron -y

实测回显（本机未装 sendmail 时，完整原文）：

sh: 1: /usr/sbin/sendmail: not found
 [error]  Error sending email (from admin@example.com to admin@example.com with reply-to not set).
 [error]  Message: Unable to send email. Contact the site administrator if the problem persists.

⚠️ 解读：这两行 [error] 是 CRON 顺带发送「更新通知」邮件失败的报错，不是 CRON 失败——CRON 本身已跑完（下一节的 system.cron_last 时间戳可以证明）。消除报错的方法见第十五章 Q1。

8.2 用 state:get 验证 CRON 已执行

drush state:get system.cron_last

实测回显（CRON 执行前）：

1792762424

跑一次 drush core:cron -y 后再次查询：

1792762530

时间戳换算为可读时间（date -d @<ts> 实测）：

date -d @1792762530

Fri Oct 23 13:35:30 UTC 2026

💡 技术拓展：farmOS 的 CRON 属于「外部触发」型——程序自己不会定时跑，需要外部机制周期性调用。常见触发方式对比：

触发方式原理适用场景
系统 crontab 宿主 crontab 每 N 分钟执行 drush core:cron 最常用，裸机/自管服务器首选
systemd timer 定时器单元调 drush，日志进 journal systemd 托管的服务器
Cron 密钥 URL wget -qO- https://站点/cron/<密钥> 无命令行权限的托管环境

本文实测环境为自管服务器，采用 crontab 方式（每 15 分钟一次）；密钥 URL 在后台 Configuration > System > Cron 页查看。

触发方式	原理	适用场景
系统 crontab	宿主 crontab 每 N 分钟执行 `drush core:cron`	最常用，裸机/自管服务器首选
systemd timer	定时器单元调 drush，日志进 journal	systemd 托管的服务器
Cron 密钥 URL	`wget -qO- https://站点/cron/<密钥>`	无命令行权限的托管环境

8.3 queue:list / queue:run：队列管理

drush queue:list

实测回显：

 ------------------------------------ ------- ---------------------------------
  Queue                                Items   Class
 ------------------------------------ ------- ---------------------------------
  entity_reference_revisions_orphan_   0       Drupal\Core\Queue\DatabaseQueue
  purger
 ------------------------------------ ------- ---------------------------------

手动消化指定队列：

drush queue:run entity_reference_revisions_orphan_purger

实测回显：

 [success] Processed 0 items from the entity_reference_revisions_orphan_purger queue in 0 sec.

队列积压（Items 数大）时，除了手动 queue:run，通常由 CRON 周期性消化，无需干预。

九、日志查看命令（watchdog）

Drupal 的数据库日志（watchdog）记录站点运行期的事件、错误与安全事件，Drush 提供了免登录后台直接查看的命令组。

9.1 watchdog:show：按条数/类型过滤查看

最近 6 条（本文实测站点，日志恰好记录了前几节的全部操作）：

drush watchdog:show --count=6

实测回显：

 ----- -------------- -------- ---------- ------------------------------------
  ID    Date           Type     Severity   Message
 ----- -------------- -------- ---------- ------------------------------------
  124   23/Oct 13:40   system   Info       syslog module uninstalled.
  123   23/Oct 13:40   system   Info       syslog module installed.
  122   23/Oct 13:39   user     Notice     Deleted user: farmtest .
  121   23/Oct 13:39   user     Notice     Blocked user: farmtest .
  120   23/Oct 13:39   user     Notice     Blocked user: farmtest .
  119   23/Oct 13:39   mail     Error      Error sending email (from
                                           admin@example.com to
                                           farmtest@example.com with reply-to
                                           admin@example.com).
 ----- -------------- -------- ---------- ------------------------------------

按日志类型过滤（--type=user）：

drush watchdog:show --type=user --count=3

实测回显：

 ----- -------------- ------ ---------- --------------------------
  ID    Date           Type   Severity   Message
 ----- -------------- ------ ---------- --------------------------
  122   23/Oct 13:39   user   Notice     Deleted user: farmtest .
  121   23/Oct 13:39   user   Notice     Blocked user: farmtest .
  120   23/Oct 13:39   user   Notice     Blocked user: farmtest .
 ----- -------------- ------ ---------- --------------------------

常用过滤选项：--severity=Error（按级别）、--type=<类型>（user/system/php/mail 等，类型名即表中 Type 列）。排障时先 --severity=Error 扫一遍错误是标准动作。

9.2 watchdog:show-one：查看单条详情

drush watchdog:show-one 124

实测回显（YAML 格式，含位置与来源主机）：

wid: '124'
uid: '0'
type: system
message: 'syslog module uninstalled.'
severity: Info
location: 'http://default/'
hostname: 127.0.0.1
date: '23/Oct 13:40'
username: Anonymous

9.3 watchdog:list 与 watchdog:tail

watchdog:list（wd-list）以交互式过滤器逐条翻看日志，适合人在终端时用；watchdog:tail（wt）持续滚动输出新日志（tail -f 的日志版）。drush help watchdog:tail 的官方示例（实测帮助文本）：

Tail watchdog messages.

Examples:
 drush watchdog:tail   Continuously tail watchdog messages.
 drush watchdog:tail   Continuously tail watchdog messages, filtering on
"cron run successful"  the string cron run successful.
 drush watchdog:tail   Continuously tail watchdog messages, filtering
--severity=Notice      severity of notice.
 drush watchdog:tail   Continuously tail watchdog messages, filtering for a
--severity-min=Warning severity of warning or higher.
 drush watchdog:tail   Continuously tail watchdog messages, filtering on
--type=php             type equals php.

两个都是交互/常驻型命令，适合 SSH 终端实时盯日志，不适合写进脚本。

十、模块管理命令

10.1 pm:list：列出模块

drush pm:list --status=enabled

实测输出节选（首部 40 行，完整清单含表头共 104 行；farmOS 包及 farm 前缀模块 45 个）：

 --------------- ------------------------------------- --------- --------------
  Package         Name                                  Status    Version
 --------------- ------------------------------------- --------- --------------
  Core            Block (block)                         Enabled   11.3.19
  Core            Breakpoint (breakpoint)               Enabled   11.3.19
  Core            Configuration Manager (config)        Enabled   11.3.19
  Core            Database Logging (dblog)              Enabled   11.3.19
  Core            Field (field)                         Enabled   11.3.19
  Field types     File (file)                           Enabled   11.3.19
  Core            Filter (filter)                       Enabled   11.3.19
  Core            Help (help)                           Enabled   11.3.19
  Field types     Image (image)                         Enabled   11.3.19
  Core            Layout Discovery (layout_discovery)   Enabled   11.3.19
  Field types     Options (options)                     Enabled   11.3.19
  Core            Path alias (path_alias)               Enabled   11.3.19
  Core            PostgreSQL (pgsql)                    Enabled   11.3.19
  Web services    RESTful Web Services (rest)           Enabled   11.3.19
  Web services    Serialization (serialization)         Enabled   11.3.19
  Core            System (system)                       Enabled   11.3.19
  Core            Taxonomy (taxonomy)                   Enabled   11.3.19
  Field types     Text (text)                           Enabled   11.3.19
  Core            Toolbar (toolbar)                     Enabled
  Core            Update Status (update)                Enabled   11.3.19
  Core            User (user)                           Enabled   11.3.19
  Core            Views (views)                         Enabled   11.3.19
  Asset           Asset (asset)                         Enabled
  farmOS          farmOS Entity (farm_entity)           Enabled
  farmOS          farmOS Entity Access                  Enabled
                  (farm_entity_access)
  farmOS          farmOS Entity Fields                  Enabled
                  (farm_entity_fields)
  farmOS          farmOS Entity Views                   Enabled
                  (farm_entity_views)
  farmOS          farmOS Field (farm_field)             Enabled
  farmOS          farmOS Flags (farm_flag)              Enabled
  farmOS          farmOS Forms (farm_form)              Enabled
  farmOS          farmOS Text Format (farm_format)      Enabled
  farmOS          farmOS Geo (farm_geo)                 Enabled
  farmOS          farmOS ID Tag (farm_id_tag)           Enabled
  farmOS          farmOS Image (farm_image)             Enabled

括号里是模块机器名，pm:install/pm:uninstall 都用机器名。

10.2 pm:install：启用模块

以核心的 Database Logging 同族的 syslog 模块为例（实测启用）：

drush pm:install syslog

实测回显：

 [success] Module syslog has been installed. (Configure)

启用后立即生效，无需重启 Web 服务；个别模块会提示跑 drush cr。

10.3 pm:uninstall：卸载模块

drush pm:uninstall syslog

实测回显：

 [success] Successfully uninstalled: syslog

⚠️ 注意：pm:uninstall 会清空该模块的数据（区别于禁用），生产环境对 farmOS 业务模块（farm_asset、farm_log 等）执行前务必先备份（见第十一节）。

十一、数据库与备份命令

11.1 sql:query / sql:connect：执行 SQL 与连接串

执行任意 SQL（走站点配置的数据库连接，无需自己输密码）：

drush sql:query "SELECT 1"

实测回显：

打印底层连接命令（可用于脚本或手动进入数据库客户端）：

drush sql:connect

实测回显：

psql -q ON_ERROR_STOP=1  --dbname=farm --host=127.0.0.1 --port=5432 --username=farm --no-align --field-separator="      " --pset tuples_only=on

farmOS 用的 PostgreSQL，drush sql:cli（sqlc）会以站点凭据直接进入 psql 交互终端。

11.2 sql:dump：备份数据库

drush sql:dump --gzip --result-file=/tmp/farm-db-dump.sql

实测回显：

 [success] Database dump saved to /tmp/farm-db-dump.sql.gz

验证产物：

ls -lh /tmp/farm-db-dump.sql.gz

实测回显：

-rw-r--r-- 1 root root 326K Oct 23 13:41 /tmp/farm-db-dump.sql.gz

⚠️ 注意：--result-file 写 /tmp/farm-db-dump.sql，加 --gzip 后 Drush 自动改存为 .sql.gz；该参数应指向 Drupal 根之外的目录（示例用 /tmp），备份文件请及时转移到备份存储，不要留在站点所在磁盘。

11.3 archive:dump：代码+文件+数据库一键归档

archive:dump 把代码库、公共/私有文件和数据库打包成单个 tar.gz。直接执行会命中一条保护性报错（实测）：

drush archive:dump --destination=/tmp/farm-site-archive.tar.gz


In ArchiveDumpCommands.php line 617:

  Found database connection settings in web/sites/default/settings.php. It is
   risky to include them to the archive. Please move the database connection
   settings into a setting.*.php file or exclude them from the archive with "-
  -exclude-code-paths=web/sites/default/settings.php".

按报错提示排除含数据库凭据的 settings.php 后执行：

drush archive:dump --destination=/tmp/farm-site-archive.tar.gz --exclude-code-paths=web/sites/default/settings.php

实测回显（成功时输出即目标路径）：

/tmp/farm-site-archive.tar.gz

验证产物：

ls -lh /tmp/farm-site-archive.tar.gz

-rw-r--r-- 1 root root 595K Oct 23 13:41 /tmp/farm-site-archive.tar.gz

重复覆盖同一目标文件需加 --overwrite（否则报 The destination file already exists. Use "--overwrite" option for overwritting an existing file.，实测）。

十二、更新与部署命令

代码升级（如 farmOS 4.0.9 → 4.0.x 后续补丁）后的标准动作序列：备份数据库 → drush updatedb -y → drush cr → drush farm_update:rebuild。

12.1 updatedb:status / updatedb：数据库更新

先查有没有待执行的数据库更新：

drush updatedb:status

实测回显：

 [success] No database updates required.

实际执行更新（updatedb 自动进入维护模式、跑完再退出）：

drush updatedb -y

实测回显：

 [success] No pending updates.

12.2 deploy 群：部署钩子

代码部署后除数据库更新外还有 deploy hook（一次性部署任务）。查看待执行的部署钩子：

drush deploy:hook-status

实测回显：

 -------- ------ -------------
  Module   Hook   Description
 -------- ------ -------------

空表表示无待执行钩子。配套命令：drush deploy（一键跑完更新+部署钩子+清缓存）、drush deploy:hook（只跑钩子）、drush deploy:mark-complete（把钩子标记为已执行，用于跳过失败钩子）。

12.3 farm_update:rebuild：farmOS 专属重建

drush farm_update:rebuild -y

实测回显（成功时静默、退出码 0）：

该命令按 farmOS 各模块声明的配置定义重建/修补站点配置（官方更新流程的一部分）。farmOS 补丁版本升级后执行；执行后再跑一次 drush cr 收尾。

十三、维护模式、state 与 PHP 调试

13.1 maint 群：维护模式

查询当前状态（1=开启，0=关闭）：

drush maint:get

实测回显：

maint:set 1 开启 / maint:set 0 关闭（两条均静默成功，无输出）；maint:status 用于脚本判断——维护模式开启时以非零退出码失败（可作 CI 闸门）。升级、批量导入前建议开维护模式，完成后关闭并 drush cr。

13.2 state 群：运行时键值

state 是站点运行时的键值存储（非配置、不进导出）。写入、读取、删除三连实测：

drush state:set my_test_key hello -y

实测回显（静默无输出）；读取：

drush state:get my_test_key

hello

删除（同样静默）：

drush state:delete my_test_key

13.3 php:eval / php:cli：PHP 调试

php:eval 在完整 Drupal 引导环境里执行一段 PHP 代码（表达式有输出需显式 echo）：

drush php:eval "echo \Drupal::VERSION;"

实测回显：

11.3.19

再来一个实用例子——统计站点注册的实体类型数量：

drush php:eval "echo count(\Drupal::entityTypeManager()->getDefinitions());"

实测回显：

php:cli（php）打开交互式 PHP shell（已引导 Drupal），php:script（scr）执行完整脚本文件，三者是排查数据问题、验证 API 行为的工具箱。

13.4 jn:get：JSON:API 请求

drush jn:get /jsonapi

实测回显（farmOS 默认未启用 jsonapi 模块时）：

 [error]  The following modules are required: jsonapi

farmOS 默认发行不启用 JSON:API 模块（farmOS API 场景按需在后台启用），启用后方可通过 jn:get 在命令行调试 API 响应。

十四、注意事项

执行位置：所有命令需在 /opt/drupal（或其子目录）下执行，Drush 靠目录定位站点；多站点部署时还需 -l <站点URI> 指定站点。
参数顺序坑：user:role:add/user:role:remove 是「角色在前、用户在后」，写反报 Unable to load the user_role: <用户名>（见 7.3 节实测）。
-y 的使用：config:set、updatedb、core:cron、config:export 等命令加 -y 可跳过交互确认，脚本中必须携带。
时区差异：watchdog 的 Date 列与 state:get system.cron_last 换算均为服务器本地时区（本文实测服务器为 UTC），与浏览器后台显示可能相差时差。
user:cancel 语义：默认禁用账户不删除；彻底删除加 --delete-content，内容转匿名用户用 --reassign-content（见 7.3 节）。
备份先行：模块卸载、账户删除、数据库更新等破坏性操作前先 sql:dump 或 archive:dump。
drush status 的 Site URI：默认 http://default，uli 生成的链接需替换域名部分；生产可在 settings.php 配置 $options['uri'] 或执行时加 --uri=https://你的域名 修正。

十五、常见问题（FAQ）

Q1：drush core:cron 报 sendmail: not found / Error sending email？ 站点没有安装本地邮件代理（MTA），CRON 顺带发送的通知邮件投递失败，CRON 本身已完成（用 8.2 节的时间戳验证）。解决：安装并配置 MTA（如 apt install postfix 选「Internet Site」），或改用外部 SMTP 模块发送；仅测试环境可暂忽略该报错。

Q2：命令跑完没有任何输出？ Drush 大部分「写操作」成功时静默（如 role:create、user:cancel --delete-content、state:set、farm_update:rebuild），用配套验证命令确认结果：角色看 role:list、用户看 user:information、state 看 state:get。本文档各节已给出成对的「执行+验证」命令。

Q3：drush user:login 的链接打开 404？ 链接域名部分是 http://default（Site URI 默认值）。把域名换成真实站点地址（如 https://farm.example.com），路径与参数原样保留即可打开（见 7.2 节与 14.7 条）。

Q4：user:role:add 报 Unable to load the user_role: farmtest？ 参数顺序写反了——Drush 把用户名当角色去找。正确写法 drush user:role:add <角色机器名> <用户名>，角色在前（见 7.3 节实测报错）。

Q5：archive:dump 报 settings.php 有风险？ 归档会包含数据库凭据，Drush 要求显式排除：加 --exclude-code-paths=web/sites/default/settings.php（见 11.3 节实测）；恢复站点时再把该文件单独拷回。

Q6：cache:get render 报 The render object in the default bin was not found.？ cache:get 的参数是缓存键名而不是 bin 名。清缓存用 cr/cc 即可，cache:get 仅用于按已知键调试单条缓存。

Q7：改了配置不生效？ settings.php/services.yml 文件参数改完要 drush cr；config:set 改的活动配置立即生效。两者的分工与查看方式见《farmOS 4.0.9 配置参数详解》第三章。

十六、参考链接

Drush 官方文档（命令与配置）：https://www.drush.org/
farmOS 官方托管文档（CRON 触发）：https://farmos.org/hosting/
farmOS Docker 文档（命令执行方式差异）：https://farmos.org/hosting/docker
Drupal cron 说明：https://www.drupal.org/docs/administering-a-site/cron
watchdog 日志说明：https://www.drupal.org/docs/administering-a-site/logging

farmOS 4.0.9 常用 CLI 命令与工具详解

farmOS 4.0.9 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

2.1 Drush 与 farmOS 的关系

2.2 命令体系总览

2.3 farmOS 专属命令

三、前置条件

四、站点状态与环境检查命令

4.1 drush status：环境总览

4.2 status 字段过滤

4.3 core:requirements（rq）：健康检查

4.4 site:alias：站点别名

五、缓存管理命令

5.1 cache:rebuild（cr）：重建全部缓存

5.2 cache:clear（cc）：清除指定缓存

5.3 cache:warm：预热缓存

六、配置管理命令

6.1 config:get：读配置

6.2 config:set：改配置

6.3 config:status：核对文件库差异

6.4 config:export：导出配置到文件

七、用户与角色管理命令

7.1 user:information：查用户信息

7.2 user:login（uli）：生成一次性登录链接

7.3 用户创建 → 删除全流程

7.4 角色管理命令

八、CRON 与队列命令

8.1 core:cron：手动执行 CRON

8.2 用 state:get 验证 CRON 已执行

8.3 queue:list / queue:run：队列管理

九、日志查看命令（watchdog）

9.1 watchdog:show：按条数/类型过滤查看

9.2 watchdog:show-one：查看单条详情

9.3 watchdog:list 与 watchdog:tail

十、模块管理命令

10.1 pm:list：列出模块

10.2 pm:install：启用模块

10.3 pm:uninstall：卸载模块

十一、数据库与备份命令

11.1 sql:query / sql:connect：执行 SQL 与连接串

11.2 sql:dump：备份数据库

11.3 archive:dump：代码+文件+数据库一键归档

十二、更新与部署命令

12.1 updatedb:status / updatedb：数据库更新

12.2 deploy 群：部署钩子

12.3 farm_update:rebuild：farmOS 专属重建

十三、维护模式、state 与 PHP 调试

13.1 maint 群：维护模式

13.2 state 群：运行时键值

13.3 php:eval / php:cli：PHP 调试

13.4 jn:get：JSON:API 请求

十四、注意事项

十五、常见问题（FAQ）

十六、参考链接