OTOBO 11.0.18 常用 CLI 命令与工具详解

OTOBO 11.0.18 常用 CLI 命令与工具详解

OTOBO工单系统服务管理自托管Perl2026/10/24

OTOBO 11.0.18 常用 CLI 命令与工具详解

目标：系统梳理 OTOBO 11.0.18 服务端命令行工具（核心是 bin/otobo.Console.pl 管理控制台），按「元命令 / Admin 域 / Maint 域 / Dev 域」给出每条常用命令的用法与实测回显，覆盖账号、队列、工单、会话、日志、缓存、数据库、邮件、包管理九大运维场景。全部命令与输出均在 Docker Compose 部署的 OTOBO 11.0.18 实测采集（2026-10-24），逐行照抄。

一、环境信息

  • OTOBO 版本：11.0.18（Docker 镜像 rotheross/otobo:rel-11_0_18），部署见 《OTOBO 11.0.18 Docker Compose 部署指南》
  • 执行位置：所有命令在 OTOBO 应用目录（/opt/otobo）下执行；Docker 形态通过 docker compose exec web bash 进入后执行，下文命令统一省略该进入步骤
  • 控制台规模：bin/otobo.Console.pl List 实测共 155 行输出，命令分布在 Admin、Dev、Maint、Znuny4OTOBO 四个域
  • 实测账号：root@localhost；示例队列 Support、示例工单 TN 2026102438000013

二、工具概览

OTOBO 服务器端 CLI 工具清单（位于 /opt/otobo/bin/，实测目录列表）：

bin/
├── otobo.Console.pl        # 管理控制台（本篇主角，155 条子命令）
├── otobo.Daemon.pl         # 后台守护进程管理（start/stop/status）
├── otobo.CheckModules.pl   # Perl 依赖体检
├── otobo.CheckSum.pl       # 文件校验和核对
├── otobo.SetPermissions.pl # 文件属主与权限设置
├── backup.pl               # 全量备份（数据库+应用+配置）
└── restore.pl              # 备份恢复

职责分工：otobo.Console.pl 是日常运维 95% 的入口（账号/队列/工单/缓存/日志/包）；otobo.Daemon.pl 只管守护进程生命周期；backup.pl/restore.pl 独立于控制台负责备份恢复；otobo.CheckModules.pl 在升级或报缺模块时使用。

otobo.Console.pl 全局选项（实测 --help 回显节选）：

Usage:
 otobo.Console.pl command [options] [arguments]

Options:
 [--help|h]                     - Display help for this command.
 [--no-ansi]                    - Do not perform ANSI terminal output coloring.
 [--quiet]                      - Suppress informative output, only retain error messages.

三、前置条件

  1. 系统已完成安装（SecureMode=1），否则部分 Maint 命令行为受限（Daemon 无法常驻等，排障实录见部署指南第十一章 Q4）。
  2. 执行者需进入应用容器/服务器 shell 且对 /opt/otobo 有读写权限（Docker 形态容器内默认以 otobo 用户运行，权限已就绪）。
  3. 命令输出使用 ANSI 着色，采集到文件或脚本消费时建议加 --quiet 或 --no-ansi。

四、各工具详解

4.1 元命令：List / Search / Help

List——列出全部可用命令（实测 155 行，节选首尾）：

bin/otobo.Console.pl List

实测回显（节选）：

OTOBO 11 (11.0.18)

Usage:
 otobo.Console.pl command [options] [arguments]

Available commands:
 Help                                     - Display help for an existing command or search for commands.
 List                                     - List available commands.
 Search                                   - Search for commands.
Admin
 Admin::FixTranslationImportColumn        - Rename column import of table translation_item to import_param if neccessary.
 ...
Maint
 Maint::Cache::Delete                     - Delete cache files created by OTOBO.
 Maint::Ticket::Dump                      - Print a ticket and its articles to the console.
 ...
Znuny4OTOBO
 Znuny4OTOBO::DefaultColumnsScreen::Add   - Updates the 'DynamicField' config of all DefaultColumnsScreens configs accordingly

Search——按关键词模糊搜命令，实测：

bin/otobo.Console.pl Search session

实测回显：

Searching for commands similar to 'session'...
Maint
 Maint::Session::DeleteAll                - Delete all sessions.
 Maint::Session::DeleteExpired            - Delete expired sessions.
 Maint::Session::ListAll                  - List all sessions.
 Maint::Session::ListExpired              - List expired sessions.

Help——查看某命令的完整用法，实测：

bin/otobo.Console.pl Help Admin::Queue::Add

实测回显（节选）：

Create a new queue.

Usage:
 otobo.Console.pl Admin::Queue::Add --name ... --group ... [--system-address-id ...] [--system-address-name ...] [--comment ...] [--unlock-timeout ...] [--first-response-time ...] [--update-time ...] [--solution-time ...] [--calendar ...]

Options:
 --name ...                     - Queue name for the new queue.
 --group ...                    - Group which should be assigned to the new queue.

⚠️ 注意：不存在 ListCommands 命令（实测报 Error: Could not find Kernel::System::Console::Command::ListCommands.），枚举命令一律用 List。

4.2 Admin 域：管理对象操作

Admin::User::SetPassword——修改客服账号密码（实测，见部署指南 4.4）：

bin/otobo.Console.pl Admin::User::SetPassword admin q1w2e3r4

实测回显：

Successfully set password for user 'admin'.

⚠️ 内置超级管理员的登录名是 root@localhost（不是 root），误用报 Error: No user found with login 'root'!。

Admin::Queue::Add——创建队列（实测）：

bin/otobo.Console.pl Admin::Queue::Add --name Support --group users --comment "一级支持队列"

实测回显：

Adding a new queue...
Done.

Admin::Queue::List——列出队列（实测）：

bin/otobo.Console.pl Admin::Queue::List

实测回显：

Listing Queues...
  Postmaster
  Raw
  Junk
  Misc
  Support
Done.

前四个为系统内置队列（Raw 是默认收件队列），Support 为 4.2 上一条命令实测创建。

Admin::Package::List——列出已安装扩展包（实测）：

bin/otobo.Console.pl Admin::Package::List

实测回显：

Listing all installed packages...
There are no packages installed.

Admin::Package::RepositoryList——查看在线包仓库（实测节选）：

bin/otobo.Console.pl Admin::Package::RepositoryList

实测回显（节选）：

|    Install:     https://ftp.otobo.org/pub/otobo/packages-thirdparty/:Freicon-KanbanBoard-11.0.5.opm
+----------------------------------------------------------------------------+

Done.

Admin::WebService::List——列出集成 Web 服务（实测）：

bin/otobo.Console.pl Admin::WebService::List

实测回显：

Listing all web services...
  Elasticsearch (1)
Done.

Elasticsearch (1) 为部署时 --activate-elasticsearch 自动创建的内置 Web 服务；自建 REST/SOAP 集成也落在这一域（Admin::WebService::Add/Dump/Update/Delete）。

4.3 Maint 域：运维与数据维护

数据库连通性检查（实测）：

bin/otobo.Console.pl Maint::Database::Check

实测回显：

Check OTOBO database connectivity.
Succeeded.

会话管理（实测）：

bin/otobo.Console.pl Maint::Session::ListAll

实测回显：

Listing all sessions...
  gG2QUITvlpbpO2MkFiuE9xKO1Pgmhdap
  xeHHnoqRWE6kdu9VYuptIbieoquJ4HDJ
Done.

配套命令：Maint::Session::DeleteAll（登出全部在线客服）、Maint::Session::DeleteExpired（清过期会话）。

守护进程状态摘要（实测节选）：

bin/otobo.Console.pl Maint::Daemon::Summary

实测回显（节选）：

Gathering summary for all daemons...

  System configuration sync:
    Daemon is active.

  Tasks to be executed in future:
    There are currently no tasks to be executed in future.

  Recurrent cron tasks:
  +---------------------------------+---------------------+-------------+---------------+---------------------+
  | Name                            | Last Execution      | Last Status | Last Duration | Next Execution      |

缓存清理（实测）：

bin/otobo.Console.pl Maint::Cache::Delete

实测回显：

Deleting cache...
Done.

日志查看与清理（实测）：

bin/otobo.Console.pl Maint::Log::Print

实测回显（节选，恰为上一节建单操作的日志行）：

Sat Oct 24 05:26:53 2026;;info;;OTOBO-otobo.Console.pl-Maint::PostMaster::Read-38;;New Ticket [2026102438000013/Demo ticket via] created (TicketID=2,Queue=Raw,Priority=3 normal,State=new)

日志行格式为 时间;;级别;;来源;;消息 四段式。清空日志：bin/otobo.Console.pl Maint::Log::Clear。

邮件入单：Maint::PostMaster::Read——从 stdin 读邮件原文创建工单（邮件管道对接的标准入口），实测：

printf "From: customer@example.com\nTo: otobo@example.com\nSubject: Demo ticket via PostMaster\n\nThis is a test ticket body created via Maint::PostMaster::Read.\n" | bin/otobo.Console.pl Maint::PostMaster::Read

实测回显：无输出（静默成功），但系统已建单——日志（上一条 Maint::Log::Print）与工单导出均可证实。

工单导出：Maint::Ticket::Dump（实测）：

bin/otobo.Console.pl Maint::Ticket::Dump 2

实测回显（完整）：

=====================================================================
TicketNumber:        2026102438000013
TicketID:            2
Title:               Demo ticket via PostMaster
Created:             2026-10-24 05:26:53
Queue:               Raw
State:               new
Priority:            3 normal
Lock:                unlock
CustomerID:          customer@example.com
CustomerUserID:      customer@example.com
---------------------------------------------------------------------
ArticleID:           2
CreateTime:          2026-10-24 05:26:53
SenderType:          customer
Channel:             Email
From:                customer@example.com
To:                  otobo@example.com
Sender:              customer@example.com
Subject:             Demo ticket via PostMaster
---------------------------------------------------------------------
This is a test ticket body created via Maint::PostMaster::Read.

上半段是工单属性、下半段是文章（邮件正文）全文；--format JSON 可输出机器可读格式，--article-limit 限制文章数。

⚠️ 注意：ticket-id 是位置参数，写 --ticket-id 2 会报错（实测回显 Error: please provide a valid value for argument 'ticket-id'.），与 --setting-name 类选项型参数不同。

全文索引状态（实测）：

bin/otobo.Console.pl Maint::Ticket::FulltextIndex --status

实测回显：

Indexed Articles: 100.0% (1/1)

💡 说明：该百分比统计的是启用 Elasticsearch 前的「数据库后备索引」覆盖度；ES 侧的连接与迁移验证用下一条命令。

Elasticsearch 连接测试（实测）：

bin/otobo.Console.pl Maint::Elasticsearch::TestConnection

实测回显：

Connection could be established!

配置读取与导出：Maint::Config::Dump <参数名> / Maint::Config::DumpAll（实测用法与参数字典见 《OTOBO 11.0.18 配置参数详解》第三章）。

4.4 Dev 域：开发与测试辅助

实测清单中 Dev 域可用命令（节选自 List 输出）：

命令用途
Dev::UnitTest::Run跑系统自带单元测试（TAP 输出）
Dev::Tools::Shell交互式 Perl REPL，直接调 OTOBO API
Dev::Tools::Database::RandomDataInsert灌随机测试数据（压测/演示前造数）
Dev::Package::Build把 sopm 源打包成 .opm 安装包
Dev::Code::CPANAudit扫描 CPAN 依赖已知漏洞
Dev::Tools::Migrate::OTRSToOTOBOOTRS 6.0.x 配置迁移辅助

生产服务器一般不使用 Dev 域命令，此处仅作能力索引。

4.5 配套工具：otobo.Daemon.pl 与 backup.pl

otobo.Daemon.pl——守护进程生命周期（实测）：

bin/otobo.Daemon.pl status

实测回显：

Manage the OTOBO Daemon process.

Daemon not running

（安装完成前 SecureMode=0 时 daemon 自行退出即为此状态；正常运行时该命令回显 Daemon running。）启停：bin/otobo.Daemon.pl start / stop。容器形态下 daemon 由编排独立服务承载，宿主侧运维只需盯 docker compose ps 的 healthy 状态。

backup.pl——全量备份（--help 实测节选）：

bin/backup.pl --help

实测回显（节选）：

Backup script for OTOBO.
Usage: backup.pl -d /data_backup_dir [-c/--compress (gzip|bzip2)] [--max-hours <hours>|--max-days <days>]

标准用法：bin/backup.pl -d /opt/otobo_backup -c gzip，产出数据库 SQL dump + 应用目录 tar 包；恢复用 bin/restore.pl --backupdir <目录> --restart。

五、注意事项

  1. 参数形态两类：Maint::Config::Dump、Maint::Ticket::Dump 用位置参数；Admin::Config::Update、Admin::Queue::Add 用 --key value 选项。拿不准先 Help <命令>（实测入口见 4.1）。
  2. 写操作即时生效：Admin::Queue::Add、Admin::User::SetPassword 等直接落库，无 dry-run；对配置的修改可用 Admin::Config::UnlockAll/Admin::Config::FixInvalid 批量善后。
  3. 缓存一致性：改配置/改库后如界面行为未更新，先 Maint::Cache::Delete（实测回显见 4.3）。
  4. 容器形态的执行入口：本篇命令统一在 docker compose exec web bash 进入后执行；docker compose exec daemon bash 内也能执行同一套命令（共享卷 /opt/otobo），但建议固定用 web 执行，避免并行写冲突。
  5. 审计留痕：Maint::Log::Print 会记录所有通过控制台触发的关键事件（如建单、改配置），重要操作前后各打一次日志便于回溯。

六、常见问题

Q1：命令敲下去报 Could not find Kernel::System::Console::Command::xxx.

命令名拼错或该域无此命令。先用 bin/otobo.Console.pl Search <关键词> 确认真实命令名（实测案例：Admin::User::List 不存在、ListCommands 不存在，正确入口分别是 Search user 与 List）。

Q2：命令卡住或报 Redis/DB 连接错误？

控制台命令依赖应用配置中的 db、redis 服务连通。实测排障案例：web 服务网络挂接丢失时 Admin::User::SetPassword 连环报 Redis error: Could not connect to Redis server at redis:6379 与 Unknown server host 'db' (-3)，全栈重建后恢复（处置细节见部署指南第十一章 Q3）。

Q3：Maint::Ticket::Dump 报 please provide a valid value for argument 'ticket-id'？

该命令的 ticket-id 是位置参数（Maint::Ticket::Dump 2），不支持 --ticket-id 选项形态（实测两种写法对比见 4.3）。

Q4：想在 shell 脚本里消费命令输出？

加 --quiet 只保留错误输出，加 --no-ansi 去掉颜色码；取配置值用 Maint::Config::Dump（单值 JSON 形态，实测见配置篇 3.1），避免解析 List 的表格输出。

七、参考链接