Tiki 30.1 常用 CLI 命令与工具详解

目标：把 Tiki 30.1 的 console.php 命令行工具按运维场景讲透——版本巡检、缓存清理、用户管理、索引重建、Tracker 重算、备份、偏好读写、安装器锁定与站点健康检查，命令与回显均来自 Ubuntu 26.04.1 + PHP 8.4.27 环境实测（2026-11-02）。部署见本专栏《Tiki Docker Compose 部署指南》篇，参数含义见《Tiki 30.1 配置参数详解》篇。

一、环境信息

部署宿主：Ubuntu 26.04.1 LTS，x86_64
应用版本：Tiki 30.1，PHP 8.4.27
数据库：MariaDB 10.11.19
CLI 入口：应用根目录下的 console.php（Symfony Console 封装）
执行身份：www-data 或具备应用目录读权限的账号
演示管理账号：admin / q1w2e3r4

二、工具概览

Tiki 的 CLI 不是独立二进制，而是应用内的 PHP 入口：

cd /var/www/html
php console.php <command> [arguments] [options]

查看全部命令：

php console.php list

命令按能力域分组（节选）：

Available commands:
  help
  list
 2fa
  api-tokens
  attachments
  backup
  cache
  calendar
  database
  dev
  files
  forum
  index
  installer
  mail-in
  profile
  preferences
  scheduler
  security
  sitemap
  tracker
  translation
  users
  tokens
  vcs
  webmail

全局选项对排障很有用：

选项	作用
`--site=SITE`	多站点（Multi-Tiki）环境指定站点
`--as-user=AS-USER`	以指定用户身份执行命令
`-n, --no-interaction`	非交互模式，适合 cron/自动化
`-v / -vv / -vvv`	提升日志详细度
`-q, --quiet`	只输出错误

命令帮助：

php console.php help users:create

Usage:
  users:create [options] [--] <login>

Arguments:
  login                      User login

Options:
      --email=EMAIL          User email (ignored if login_is_email is enabled)
  -p, --password[=PASSWORD]  User password
  -G, --groups=GROUPS        List of supplementary groups of the new account

三、前置条件

php console.php tiki:info
PHP version: 8.4.27
Tiki version: 30.1

数据库连接正常（否则大部分命令会在启动阶段失败）。
执行备份类命令前确认目标目录存在且可写；执行索引/缓存类命令前确认磁盘余量充足。

⚠️ 注意：Tiki CLI 会加载完整的应用初始化流程，执行耗时通常在秒级。不要把它当成轻量脚本频繁调用；批量任务应合并执行或交给 cron 调度。

四、各工具详解

4.1 版本与站点健康检查：tiki:info / tiki:stats

php console.php tiki:info

PHP version: 8.4.27
Tiki version: 30.1

php console.php tiki:stats

+-------------------------------+---------------------------------------------+-----------------------------+
| KPI                           | Label                                       | Value                       |
+-------------------------------+---------------------------------------------+-----------------------------+
| last_admin_user_login         | Last login from users in "Admins group"     | 2026-11-02 17:07:24 (admin) |
| last_user_login               | Last user login                             |                             |
| days_since_last_object_change | Days passed since last object create/change | 0                           |
+-------------------------------+---------------------------------------------+-----------------------------+

用途：升级后确认版本；巡检时确认管理员最近登录与内容活跃度。last_user_login 为空表示除管理员外没有普通用户登录过。

4.2 缓存与令牌清理：cache:clear / tokens:clear

php console.php cache:clear

Clearing all caches

php console.php tokens:clear

Expired tokens were removed.

cache:clear 是改主题、改偏好、改模块后的标准动作；tokens:clear 清理过期 API/OAuth 令牌，适合安全事件后的例行清理。

4.3 用户管理：users:list / users:create / users:password

列出用户：

php console.php users:list

+-------+-------+------------------+------------------+-----------------------+
| User  | Email | Last Login       | Registered       | Groups                |
+-------+-------+------------------+------------------+-----------------------+
| admin |       | 2026-11-02 17:11 | 2026-11-02 15:11 | Admins, Registered    |
| s9ops |       | Never            | 2026-11-02 17:11 | Registered, Anonymous |
+-------+-------+------------------+------------------+-----------------------+

创建用户（参数是 <login> 加选项，不是“登录名邮箱密码”三个位置参数）：

php console.php users:create s9ops --email=s9ops@example.com --password=q1w2e3r4 -G Registered

实测返回用户对象的 JSON（节选）：

{
    "userId": 2,
    "email": "s9ops@example.com",
    "login": "s9ops",
    "registrationDate": 1793613565,
    "hash": "$2y$12$YiHg2EyNcmDfrIZb3upI7un7FbRpHvdp2Rdjbb1kp6uBbM.3gcuui",
    "avatarLibName": "dicebear/initials",
    "groups": ["Registered", "Anonymous"],
    "editable": true
}

修改密码：

php console.php users:password s9ops q1w2e3r4

Password changed successfully.

⚠️ 注意：users:create 的位置参数只有 login。若按“login email password”三个位置参数传，会报 Too many arguments to "users:create" command, expected arguments "login"。这是本次实测踩到的第一个坑。

4.4 索引维护：index:rebuild

php console.php index:rebuild

实测输出（节选）：

[2026-11-02 18:11] Started rebuilding index...

Unified search
--------------

Engine: MySQL, version 10.11.19-MariaDB-ubu2204
Indexed
  trackeritem: 2
  tracker: 1
  trackerfield: 2
  file: 0
  file gallery: 4
  comment: 0
  user: 2
  group: 3
  wiki page: 3
  category: 0
  total tiki fields indexed: 59
Rebuilding index done
Index: index_6ae861e6688bb

Unused Indexes Detected
------------------------

 * index_6ae85ef3a3076_stopwords
 * index_pref_en_stopwords

 ! [NOTE] If you don't need them (for debugging), run the following command:

php console.php index:cleanup (Delete unused indexes)

尾部统计：

Execution Statistics
---------------------

Execution time: 2 secs
Current Memory usage: 47.3 MiB
Memory peak usage before indexing: 21.8 MiB
Memory peak usage after indexing: 47.5 MiB
Number of queries: 7256

解读：Indexed 是各对象类型的入库数量；total tiki fields indexed: 59 与偏好项 unified_field_count 一致；Unused Indexes Detected 是提示，不是错误，按需执行 index:cleanup。

命令	用途
`index:rebuild`	全量重建统一索引，内容变更大或索引损坏时用
`index:catch-up`	增量补齐，适合高频 cron
`index:cleanup`	删除未使用索引，释放空间
`index:optimize`	优化索引结构

4.5 Tracker 维护：tracker:recalc / tracker:export

Tracker 有数学字段时，批量重算：

php console.php tracker:recalc --trackerId=1

TrackerId 1
-----------

> Math fields not found

没有数学字段时输出 Math fields not found，属于正常结果，不是失败。

导出 Tracker 条目：

php console.php tracker:export 1 /tmp/qoder-export.csv

Exporting tracker...
An error was encountered while running a command
trackerId parameter must be present on line 56 of /var/www/html/lib/core/Tracker/Definition.php

原因：tracker:export 的第一个参数是后台创建的 Import-Export 格式 ID（tabularId），不是 trackerId。需要在“Trackers → Import/Export Formats”里先建一个格式并绑定 Tracker，再用该格式 ID 导出。没有格式时命令会走到错误分支。

4.6 备份：database:backup / backup:files

数据库备份：

php console.php database:backup /tmp

实测回显：

sh: 1: mysqldump: not found
Database backup completed: /tmp/tiki_2026-11-02_18-00-03.sql.gz

检查产物：

ls -lh /tmp/tiki_2026-11-02_18-00-03.sql.gz
-rw-r--r-- 1 root root 20 Nov  2 10:00 /tmp/tiki_2026-11-02_18-00-03.sql.gz

这是本次实测最重要的排障点：命令提示“completed”，但运行环境没有 mysqldump，产物只有 20 字节，等于空备份。Tiki 的 database:backup 只是调用系统 mysqldump，不会自带备份工具。修复方式是在主机安装 mariadb-client 或 mysql-client，并确认 mysqldump 在 PATH 中；备份后必须校验文件大小与可解压性。

文件备份：

php console.php backup:files /tmp --storageonly

Error: No backup sources found.

原因：没有配置文件库/附件等 storage 源。先在后台建立文件库或附件目录，或去掉 --storageonly 备份主目录。

⚠️ 注意：备份命令的“成功”字样不等于文件可用。生产环境必须加校验：gzip -t、文件大小下限、恢复演练。数据库备份建议同时保留 mariadb-dump 的 stderr 到日志。

4.7 安装器锁定：installer:lock / installer:unlock

php console.php installer:lock

Installer locked

php console.php installer:unlock

Installer unlocked

上线后保持 locked；需要重新安装或修复 schema 时才临时 unlock，操作完立即 lock。

4.8 Profile 应用：profile:apply

Tiki 的 Profile 是 YAML 描述的“站点蓝图”，可批量创建 Tracker、字段、条目、页面、菜单等。命令格式：

php console.php profile:apply <profile> <repository>

repository 可以是 profiles.tiki.org、HTTP 地址或本地目录。本次实测把 YAML 放到应用内 profiles/ 目录后执行：

php console.php profile:apply qoder /var/www/html/profiles

Profile applied.

实测该 Profile 创建了 1 个 Tracker、2 个字段、1 条条目：

trackerId  name         description
1          Qoder Tasks  Task tracker created via Tiki profile during S9 verification
itemId  trackerId  status  created
1       1          o       1793612144
2       1          o       1793613530

💡 说明：profile:apply 的第一个参数是 YAML 文件名（不含 .yml），第二个参数是目录路径；直接把 YAML 文件路径当第一个参数会报 Profile not found.。本次实测先用 /tmp/qoder.yml 直接传路径失败，改为“目录 + 文件名”后成功。

4.9 偏好读写：preferences:get / preferences:set

php console.php preferences:get feature_wiki
Preference feature_wiki has value y

php console.php preferences:get session_lifetime
Preference session_lifetime has value 10080

php console.php preferences:get wikiHomePage
Preference wikiHomePage has value HomePage

关闭功能（实测成功）：

php console.php preferences:set feature_search n
Preference feature_search was successfully set to n in the database.

开启功能（实测异常）：

php console.php preferences:set feature_search y
echo exit=$?
exit=1

无输出、exit=1、数据库未写入。需要开启 flag 类偏好时，走 Web 后台，或写库后 cache:clear。详细说明见《Tiki 30.1 配置参数详解》篇。

4.10 调度器：scheduler:stats / scheduler:run

php console.php scheduler:stats

+-----------------------------------+--------+
| Scheduler Tasks Statistics        | Values |
+-----------------------------------+--------+
| Minutes since last run            |        |
| Tasks executed in the last hour   | 0      |
| Tasks executed in the last 7 days | 0      |
+-----------------------------------+--------+

调度执行：

php console.php scheduler:run --no-interaction

建议用 cron 每分钟触发一次，让 Tiki 的定时任务（通知、索引、清理）按时执行。

4.11 站点文件生成：sitemap:generate / security:generate

生成 sitemap：

php console.php sitemap:generate http://127.0.0.1:8138

Preference "sitemap_enable" is not enabled.

需先在后台开启 sitemap_enable，且站点 URL 必须能被外部访问；内网/回环地址生成的 sitemap 对搜索引擎无意义。

生成 security.txt：

php console.php security:generate -c mailto:security@example.com --expires=2027-12-31

WARNING: Using email as contact may lead to spam.
.well-known directory is missing.

需先创建 Web 根目录下的 .well-known/ 目录并确保可写；--expires 必须是未来日期，否则报 Expiry days must be greater than 0。

4.12 翻译统计：translation:percentage

php console.php translation:percentage

实测输出先列出 54 种语言，随后报错：

54 Languages: ar bg ca cn cs cy da de el en en-uk es fa fi fj fr fy-NL gl he hr hu id is it iu iu-iq iu-ro ja ko lt nds nl no pl pt pt-br rm ro ru sb si sk sl sq sr-latn sv sw th tr tv tw uk ur vi
An error was encountered while running a command
Call to a member function read() on false on line 497 of /var/www/html/lib/language/GetStrings.php

这是本次实测发现的一个 CLI 缺陷：语言文件统计在缺少语言包文件时会触发空对象调用。需要统计时改用 --page 参数输出到 Wiki 页面，或先补齐语言包。

五、注意事项

所有命令都要在应用根目录执行：php console.php 依赖相对路径加载 lib/、vendor/、db/local.php。
flag 类偏好开启走后台：30.1 的 preferences:set ... y 实测失败，不要把它写进自动化脚本。
备份必须校验：database:backup 依赖系统 mysqldump，缺失时仍打印 completed，但产物为空。
索引重建有开销：内容量大时耗时与内存显著上升，安排在低峰期并加超时保护。
Profile 是批量变更：profile:apply --dry-run 可先预览；生产应用前先备份数据库。
多站点加 --site：Multi-Tiki 环境下不带 --site 会作用到默认站点。

六、常见问题

6.1 `Too many arguments to "users:create" command`

users:create 只接受一个位置参数 <login>，邮箱与密码是选项：

php console.php users:create s9ops --email=s9ops@example.com --password=q1w2e3r4 -G Registered

6.2 `Profile not found.`

两种原因：Profile 名不存在，或 repository 参数写错。正确形式是“文件名（不含 .yml）+ 目录”：

php console.php profile:apply qoder /var/www/html/profiles

6.3 `trackerId parameter must be present`

tracker:export 的第一个参数是 Import-Export 格式 ID，不是 Tracker ID。先在后台创建格式，或用 --filter 指定过滤条件。

6.4 数据库备份文件只有几十字节

系统缺少 mysqldump。安装 mariadb-client 或 mysql-client，确认 which mysqldump 有输出，再重跑备份并用 gzip -t 校验。

6.5 `preferences:get` 返回 `Preference not found.`

偏好名不是后台显示名。以 lib/prefs/*.php 的数组键为准，例如“Wiki”对应 feature_wiki。

6.6 命令卡住或超时

先看 -vvv 详细日志；索引/备份类命令加 --no-interaction 避免交互等待；PHP 侧 max_execution_time 对 CLI 不生效，但数据库锁与网络请求仍可能阻塞，需结合 SHOW PROCESSLIST 排查。

七、参考链接

Tiki 官方文档：https://doc.tiki.org/
Tiki 30 变更日志：https://doc.tiki.org/Tiki30.0
Tiki Profile 说明：https://doc.tiki.org/Profiles
Tiki 命令行工具源码（命令定义事实源）：https://gitlab.com/tikiwiki/tiki/-/tree/master/lib/core/Tiki/Command
Tiki 官方源码仓库：https://gitlab.com/tikiwiki/tiki

Tiki 30.1 常用 CLI 命令与工具详解

Tiki 30.1 常用 CLI 命令与工具详解

一、环境信息

二、工具概览

三、前置条件

四、各工具详解

4.1 版本与站点健康检查：tiki:info / tiki:stats

4.2 缓存与令牌清理：cache:clear / tokens:clear

4.3 用户管理：users:list / users:create / users:password

4.4 索引维护：index:rebuild

4.5 Tracker 维护：tracker:recalc / tracker:export

4.6 备份：database:backup / backup:files

4.7 安装器锁定：installer:lock / installer:unlock

4.8 Profile 应用：profile:apply

4.9 偏好读写：preferences:get / preferences:set

4.10 调度器：scheduler:stats / scheduler:run

4.11 站点文件生成：sitemap:generate / security:generate

4.12 翻译统计：translation:percentage

五、注意事项

六、常见问题

6.1 Too many arguments to "users:create" command

6.2 Profile not found.

6.3 trackerId parameter must be present

6.4 数据库备份文件只有几十字节

6.5 preferences:get 返回 Preference not found.

6.6 命令卡住或超时

七、参考链接

6.1 `Too many arguments to "users:create" command`

6.2 `Profile not found.`

6.3 `trackerId parameter must be present`

6.5 `preferences:get` 返回 `Preference not found.`