OTOBO 11.0.18 配置参数详解

目标：梳理 OTOBO 11.0.18 的三层配置体系（环境变量 → Config.pm → SysConfig 数据库），逐项给出核心参数的含义、实测默认值与修改方式，为部署调优与日常运维提供参数字典。全部参数值与命令回显已在 Docker Compose 部署的 OTOBO 11.0.18 系统上实测采集（实测日期 2026-10-24）。

一、环境信息

OTOBO 版本：11.0.18（官方 Docker 镜像 rotheross/otobo:rel-11_0_18）
部署形态：官方 Docker Compose（web / daemon / db / elastic / redis 五服务，部署过程见《OTOBO 11.0.18 Docker Compose 部署指南》）
数据库：MariaDB（镜像 mariadb:lts-noble）
配置量级：bin/otobo.Console.pl Maint::Config::DumpAll 全量导出实测 13343 行 JSON（约数千个配置项）
实测账号：root@localhost（超级管理员）

二、前置条件

OTOBO 已完成安装（安装器执行完毕、SecureMode=1、可正常登录 Agent 后台）。
能进入服务器 shell 并执行 OTOBO 控制台命令（Docker 形态通过 docker compose exec web bash 进入；传统源码形态直接在 /opt/otobo 下执行）。
理解 OTOBO 的三层配置体系（本篇主线索）：

第 1 层：环境变量（Docker 部署期，.env 文件）
   └─ 决定容器启动参数、数据库 root 口令、端口、镜像版本
第 2 层：Kernel/Config.pm（应用引导配置，安装器生成）
   └─ 决定数据库连接串、应用根路径、日志模块等「框架级」参数
第 3 层：SysConfig（数据库存储，管理界面/控制台修改）
   └─ 数千个业务参数（工单、会话、邮件、界面），修改即生效并持久化

💡 技术拓展：配置热加载机制——第 3 层 SysConfig 修改后立即写入数据库并清缓存生效；第 2 层 Config.pm 修改后需重启 Web/Daemon 进程；第 1 层环境变量改动需重建容器（docker compose up -d）。三层优先级：Config.pm 中显式写的值 > SysConfig 数据库值 > 代码内置默认值；环境变量只在容器/进程启动链上起作用。

三、参数查看与修改方式

3.1 查看参数值：Maint::Config::Dump / Admin::Config::Read

方式一：Maint::Config::Dump（只回显值，适合脚本化取值），实测：

bin/otobo.Console.pl Maint::Config::Dump SecureMode

实测回显：

"1"

注意参数名是位置参数，写成 --setting-name SecureMode 会报错（实测回显）：

Error: found unknown arguments on the command line ('SecureMode').

方式二：Admin::Config::Read（带元数据流程输出，适合人工确认），实测：

bin/otobo.Console.pl Admin::Config::Read --setting-name SystemID

实测回显：

Gathering setting value...

Setting: SystemID
38

Done.

方式三：全量导出 Maint::Config::DumpAll（用于备份/比对，实测 13343 行），建议定期导出留存：

bin/otobo.Console.pl Maint::Config::DumpAll > /opt/otobo/var/backup-sysconfig-$(date +%F).json

3.2 修改参数值：Admin::Config::Update（含完整实测闭环）

以修改 FQDN 为例，实测「改值 → 验证 → 还原」闭环：

# 改值
bin/otobo.Console.pl Admin::Config::Update --setting-name FQDN --value demo.example.com

实测回显：

Updating setting value...

Done.

# 验证生效
bin/otobo.Console.pl Maint::Config::Dump FQDN

实测回显：

"demo.example.com"

# 还原
bin/otobo.Console.pl Admin::Config::Update --setting-name FQDN --value localhost

实测回显：

Updating setting value...

Done.

⚠️ 注意：Admin::Config::Update 会把配置置为「修改态」，等价于管理界面 SysConfig 中的修改；如需批量还原可执行 bin/otobo.Console.pl Admin::Config::UnlockAll（解锁全部修改态设置）与 Admin::Config::FixInvalid（修复非法值）。

3.3 管理界面方式

浏览器登录 Agent 后台（http://<服务器IP>:<端口>/otobo/index.pl），进入「管理 → 系统配置（SysConfig）」，支持按组/导航树检索参数、查看修改历史、导出/导入配置集（YAML）。与控制台方式等效，数据同源。

四、参数总览

按三层体系与功能域归纳本篇实测覆盖的核心参数：

层	参数	实测值	域
SysConfig	`SecureMode`	`1`	系统安全
SysConfig	`SystemID`	`38`	系统标识
SysConfig	`FQDN`	`localhost`	网络
SysConfig	`HttpType`	`http`	网络
SysConfig	`SessionModule`	`Kernel::System::AuthSession::DB`	会话
SysConfig	`SessionMaxIdleTime`	`7200`	会话
SysConfig	`SessionCheckRemoteIP`	`1`	会话
SysConfig	`LogModule`	`Kernel::System::Log::File`	日志
SysConfig	`LogModule::LogFile`	`/opt/otobo/var/log/otobo.log`	日志
SysConfig	`SendmailModule`	`Kernel::System::Email::Sendmail`	邮件
SysConfig	`SendmailModule::Host`	`mail.example.com`	邮件
SysConfig	`Ticket::Hook`	`Ticket#`	工单
SysConfig	`Ticket::NumberGenerator`	`Kernel::System::Ticket::Number::DateChecksum`	工单
SysConfig	`Home`	`/opt/otobo`	框架
Config.pm	`DatabaseHost` / `Database` / `DatabaseUser`	`db` / `otobo` / `otobo`	数据库
Config.pm	`DatabaseDSN`	`DBI:mysql:database=otobo;host=db;`	数据库
环境变量	`OTOBO_DB_ROOT_PASSWORD`	安装时设置	Docker 部署
环境变量	`OTOBO_WEB_HTTP_PORT`	`8138`（实测部署）	Docker 部署
环境变量	`OTOBO_ELASTICSEARCH_ES_JAVA_OPTS`	`-Xms512m -Xmx512m`	Docker 部署

各域参数逐项详解见第六章；Docker 部署环境变量全表见《OTOBO 11.0.18 Docker Compose 部署指南》第六章。

五、Kernel/Config.pm 框架级参数详解

Config.pm 是安装器生成的应用引导文件（Docker 形态位于卷内 /opt/otobo/Kernel/Config.pm），决定「应用连哪里、在哪、怎么记日志」。实测关键段落：

5.1 数据库连接参数（安装后一般不动）

$Self->{'DatabaseHost'} = 'db';
$Self->{Database} = 'otobo';
$Self->{DatabaseUser} = 'otobo';
$Self->{DatabasePw} = 'otobo-docker-databasepw';
$Self->{DatabaseDSN} = "DBI:mysql:database=$Self->{Database};host=$Self->{DatabaseHost};";

逐项说明：

DatabaseHost：数据库主机。Docker 形态固定为编排服务名 db（内网 DNS 解析）；传统形态填数据库服务器 IP。
Database：库名，安装器创建为 otobo。
DatabaseUser：应用专用数据库账号（非 root），安装器创建。
DatabasePw：应用账号口令，安装器随机生成并写入；若需加密存储，官方提供 bin/otobo.Console.pl Maint::Database::PasswordCrypt 把明文转为加密形态。
DatabaseDSN：Perl DBI 连接串，库名与主机从中引用。

⚠️ 排障实录：Config.pm 中的 DatabaseHost 与实际网络不一致时报 DBI connect(...) failed: Unknown server host 'db' (-3)——该错误在本次部署中曾因 web 服务网络挂接丢失出现，重建容器解决（见部署指南第十一章 Q3）。遇到此错先确认 Config.pm 的主机名与实际部署拓扑一致，再查 DNS/网络。

5.2 应用根与日志参数（实测原文行）

$Self->{Home} = '/opt/otobo';
$Self->{'LogModule'}          = 'Kernel::System::Log::File';
$Self->{'LogModule::LogFile'} = '/opt/otobo/var/log/otobo.log';

Home：应用根目录，传统安装默认 /opt/otobo，与 Docker 卷挂载点一致。
LogModule：日志后端，可选 Kernel::System::Log::File（写文件）或 Kernel::System::Log::SysLog（交系统 syslog）。
LogModule::LogFile：文件日志路径；容器形态下该路径在卷内，docker compose logs web 看到的是进程 stdout，排障时两处都要看。

5.3 修改生效方式

Config.pm 属进程启动时加载的静态配置：修改后需重启 web 与 daemon 两个服务（Docker 形态 docker compose restart web daemon；传统形态重启 Web 服务进程与 Daemon）。除数据库连接与路径类需求外，日常参数修改一律走 SysConfig（3.2），不要手改 Config.pm。

六、SysConfig 核心参数分类详解

以下每项均给出实测读值命令与回显、含义、修改建议。

6.1 系统与安全域

SecureMode（实测值 1）

bin/otobo.Console.pl Maint::Config::Dump SecureMode

"1"

含义：系统安全开关。0 时安装/迁移类操作可用，Daemon 拒绝常驻（实测部署排障实录：安装完成前 daemon 容器 unhealthy 并刷日志 Stopping the OTOBO Daemon as SecureMode is not activated.）；安装器完成后自动置 1，Daemon 才正常运行。
运维要点：生产必须为 1；若手工从备份恢复数据库后系统异常，检查该值是否被还原为 0。

SystemID（实测值 38）

含义：系统标识，参与工单号生成与会话命名（实测登录后的会话 URL 参数名 OTOBOAgentInterface_38 即含此 ID）。多套环境共用一个浏览器时用不同 SystemID 避免会话串扰。
修改：安装时通过 --system-id 指定；装后可经 SysConfig 修改，但会引起工单号格式变化，不建议装后改动。

FQDN（实测值 localhost）

含义：系统对外主机名，用于生成邮件中的链接、重定向 URL。生产应改为真实域名（如 helpdesk.example.com）。
修改：bin/otobo.Console.pl Admin::Config::Update --setting-name FQDN --value <域名>（实测闭环见 3.2）。

HttpType（实测值 http）

含义：对外协议标识，http 或 https。由安装器 --http-type 参数写入；生产启用 TLS 反向代理后改为 https，否则邮件模板与重定向会生成 http 链接。

6.2 会话域

SessionModule（实测值 Kernel::System::AuthSession::DB）

💡 技术拓展：会话存储后端不止一种——Kernel::System::AuthSession::DB（存数据库，默认）、Kernel::System::AuthSession::FS（存文件系统）。DB 后端多实例部署时天然共享会话；FS 后端性能略高但要求共享存储。本系统启用 Redis 缓存后，会话热数据由 Redis 加速（Kernel::System::Cache::Redis 实测在改密操作中出现过其调用栈），存储层仍为 DB，属于「DB 存储 + Redis 缓存」组合。

SessionMaxIdleTime（实测值 7200）

含义：Agent 会话最大空闲时间（秒），默认 2 小时。超时自动登出。按企业安全策略调整（如内网可放宽至 14400）。
修改：bin/otobo.Console.pl Admin::Config::Update --setting-name SessionMaxIdleTime --value 14400。

SessionCheckRemoteIP（实测值 1）

含义：校验会话 IP 一致性。1 时客户端 IP 变化即踢出会话。经 NAT/代理出口 IP 不固定的环境改为 0（以降低误踢率，需评估安全代价）。

6.3 日志域

LogModule / LogModule::LogFile（实测值见 5.2）

运维要点：排障顺序——先 docker compose logs web（进程级 stdout/stderr，实测启动与安装器输出都在此），再看 /opt/otobo/var/log/otobo.log（应用级日志，含 SQL 错误、邮件收发记录）。应用日志清理命令：bin/otobo.Console.pl Maint::Log::Clear；实时查看：bin/otobo.Console.pl Maint::Log::Print。

6.4 邮件域

SendmailModule（实测值 Kernel::System::Email::Sendmail）

💡 技术拓展：外发邮件后端可选 Kernel::System::Email::Sendmail（调用本地 sendmail/qmail 二进制）、Kernel::System::Email::SMTP（直连 SMTP 服务器，多容器环境推荐）、Kernel::System::Email::DoNotSendEmail（纯测试不发送）。Docker 形态容器内一般无 MTA，生产应改为 SMTP 后端并配置 SendmailModule::Host、SendmailModule::Port、SendmailModule::AuthUser、SendmailModule::AuthPassword。

SendmailModule::Host（实测值 mail.example.com）

含义：SMTP 后端的目标服务器（默认示例值）。改用 SMTP 时必须改为真实邮件服务器；实测确认该参数独立于 SendmailModule 生效（仅 SMTP 后端读取）。
收件侧：邮件账户不存 SysConfig，存数据库 mail_account 表，通过管理界面「管理 → 通信通道 → 邮件账户」添加（POP3/IMAP），由 Daemon 周期收取；手工触发收取命令：bin/otobo.Console.pl Maint::PostMaster::MailAccountFetch。

6.5 工单域

Ticket::Hook（实测值 Ticket#）

含义：工单号显示前缀。常见改法为 Call#、ITSM# 等业务化前缀。

Ticket::NumberGenerator（实测值 Kernel::System::Ticket::Number::DateChecksum）

💡 技术拓展：工单号生成策略四选一——DateChecksum（日期+校验位，如 2026102438xxxx，默认）、Date（纯日期序）、Random（随机数）、AutoIncrement（自增，存在撞号风险，官方不推荐）。DateChecksum 兼顾可读性与防伪造，保持默认即可；切换策略只影响新工单。

6.6 框架域

Home（实测值 /opt/otobo）

含义：应用安装根路径，几乎所有模块以它定位文件。装后不可改（与卷挂载点绑定）。

6.7 全量参数清单与增删

全量导出（实测 13343 行 JSON）：bin/otobo.Console.pl Maint::Config::DumpAll。
配置校验：bin/otobo.Console.pl Admin::Config::ListInvalid 列出非法值；Admin::Config::FixInvalid 自动修复。
缓存清理（改参后异常时）：bin/otobo.Console.pl Maint::Cache::Delete（实测回显 Deleting cache... Done.）。

七、生产配置模板

以「200 Agent、日均 500 工单、16 GB 内存 / 4 vCPU / NVMe」为基准的推荐配置（逐项给出来源与理由）：

层	参数	推荐值	理由
环境变量	`OTOBO_ELASTICSEARCH_ES_JAVA_OPTS`	`-Xms1g -Xmx1g`	官方默认 512m；200 Agent 检索量下 1g 堆更稳（官方样例支持该变量覆盖）
环境变量	`OTOBO_WEB_HTTP_PORT`	`80`/`443` 或反代后端口	标准端口 + 官方 HTTPS override 编排
MariaDB（编排 command）	`--max-allowed-packet`	`136314880`（官方默认）	官方编排预设值，满足附件入库
MariaDB（编排 command）	`--innodb-log-file-size`	`268435456`（官方默认）	官方预设，平衡写入吞吐与恢复时间
MariaDB（编排 command）	`--character-set-server` / `--collation-server`	`utf8mb4` / `utf8mb4_unicode_ci`（官方默认）	全量 Unicode 支持，勿降级 utf8mb3
SysConfig	`SecureMode`	`1`	安全基线
SysConfig	`FQDN`	真实域名	邮件链接与重定向正确性
SysConfig	`HttpType`	`https`	启用 TLS 后必须改
SysConfig	`SendmailModule`	`Kernel::System::Email::SMTP`	容器无 MTA，直连 SMTP
SysConfig	`SessionMaxIdleTime`	`7200`–`14400`	按安全策略
SysConfig	`SessionCheckRemoteIP`	`1`（固定出口 IP）/`0`（移动办公）	误踢率与安全权衡
SysConfig	`Ticket::NumberGenerator`	`DateChecksum`（默认）	防撞防伪造
缓存	Redis（编排 caching/redis.yml）	启用	降低 DB 会话与缓存压力，官方内置编排

配套模板文件（生产 .env 参考）：

COMPOSE_PROJECT_NAME=otobo
COMPOSE_PATH_SEPARATOR=:
COMPOSE_FILE=docker-compose/otobo-base.yml:docker-compose/otobo-override-http.yml:docker-compose/caching/redis.yml
OTOBO_DB_ROOT_PASSWORD=<强口令，安装时使用>
OTOBO_WEB_HTTP_PORT=80
OTOBO_ELASTICSEARCH_ES_JAVA_OPTS=-Xms1g -Xmx1g
OTOBO_IMAGE_OTOBO=rotheross/otobo:rel-11_0_18
OTOBO_IMAGE_OTOBO_ELASTICSEARCH=rotheross/otobo-elasticsearch:rel-11_0_18

⚠️ 上表中 <强口令> 为系统级真实密钥，按安全规范不入库不入文，仅在安装现场注入；应用内示例账号（root@localhost/admin）口令遵循本平台演示口径 q1w2e3r4。

八、常见问题

Q1：改了参数页面没生效？

三步排查：① 确认改对层——SysConfig 参数用 Maint::Config::Dump 实测读值（而非看界面缓存）；② 清缓存 bin/otobo.Console.pl Maint::Cache::Delete；③ 仍无效则重启 web/daemon。实测 Admin::Config::Update 后 Dump 即时反映新值（3.2 闭环）。

Q2：Maint::Config::Dump 报 The config setting xxx could not be found.

说明参数名不存在或属于「仅设置组/节点参数」。实测案例：LogDir（正确名是 LogModule::LogFile）、DatabaseHome（不存在，属臆造名）、PostMasterMailAccount（邮件账户在数据库表而非 SysConfig）。用 Maint::Config::DumpAll 全量导出后 grep 确认真实参数名。

Q3：Admin::Config::Update 传位置参数报 found unknown arguments on the command line？

Admin::Config::Update 只认 --setting-name/--value 选项形态；位置参数形态只有 Maint::Config::Dump <name> 支持。两者易混，实测均在 3.1。

Q4：数据库口令想加密存储？

用官方命令生成密文后替换 Config.pm 中的 DatabasePw：bin/otobo.Console.pl Maint::Database::PasswordCrypt（命令清单实测存在，见《OTOBO 11.0.18 常用 CLI 命令与工具详解》）。

九、参考链接

官方 SysConfig 手册：https://doc.otobo.org/manual/administration/11.0/en/content/manual/administration.html
官方 Docker 安装手册（环境变量来源）：https://doc.otobo.org/manual/installation/11.0/en/content/installation/installation-docker.html
官方部署仓库（编排文件与 .env 样例）：https://github.com/RotherOSS/otobo-docker
本专栏相关文档：《OTOBO 11.0.18 介绍与选型指南》、《OTOBO 11.0.18 Docker Compose 部署指南》、《OTOBO 11.0.18 常用 CLI 命令与工具详解》