Koha 26.05 配置参数详解

目标：系统梳理 Koha 26.05 的三层配置体系——实例系统文件 koha-conf.xml、编排环境变量（.env）、数据库系统参数（systempreferences，实测 918 条）——讲清每一层的作用域、查看与修改方式、生效机制，并按分类逐项详解核心参数，最后给出生产配置模板。全部取值与回显来自本地实测环境。

一、环境信息

本篇基于《Koha 26.05 Docker Compose 部署指南》的实测栈展开，环境摘要：

配置文件实测位置（实例 koha）：

在 Docker Compose 部署形态下，/etc/koha/sites 与 /var/lib/koha 都是宿主机 bind 挂载（分别为 compose 目录下 data/etc、data/instance），因此在宿主机上直接编辑 data/etc/koha/koha-conf.xml 与在实例环境内查看同一文件是等价的。实例初始化状态由 data/instance/ 下的标记文件记录（实测存在 koha、koha-bootstrapped、koha-sysprefs-applied 三项）。

二、前置条件

• 已按《Koha 26.05 Docker Compose 部署指南》完成部署并通过 web 安装器与 onboarding 初始化；
• 拥有后台超级管理员账号（实测为 root）；
• 可使用实例管理命令 koha-shell、koha-mysql、koha-passwd（详见《Koha 26.05 常用 CLI 命令与工具详解》）。

三、参数查看与修改方式

3.1 三层配置模型

Koha 的配置分三层，作用域、修改入口与生效机制各不相同：

分工原则：连接外部组件（数据库、Elasticsearch、memcached、SMTP）与文件系统路径、密钥类参数在 koha-conf.xml；业务开关（是否启用 REST 基本认证、检索引擎选择、统计上报等）在系统参数；.env 只是 koha-docker 初始化时喂给 koha-create 的原料。

3.2 koha-conf.xml 的查看与修改

实例配置文件行数实测：

$ wc -l /etc/koha/sites/koha/koha-conf.xml
581 /etc/koha/sites/koha/koha-conf.xml

配置文件由 Perl 进程在启动时读取，修改后需重启应用侧进程（plack、apache、worker、es-indexer 等）才会生效。用实例环境跑 Perl 代码验证配置读取结果（C4::Context 是 Koha 的配置访问入口）：

$ koha-shell koha -c "perl -MC4::Context -e 'print C4::Context->preference(q{SearchEngine}), qq{\n}'"
Elasticsearch

3.3 系统参数（systempreferences）的查看与修改

系统参数存在数据库里，总量与关键项实测：

$ echo "select count(*) from systempreferences;" | koha-mysql koha
count(*)
918
$ echo "select variable,value from systempreferences where variable in ('SearchEngine','RESTBasicAuth','UsageStats');" | koha-mysql koha
variable	value
RESTBasicAuth	1
SearchEngine	Elasticsearch
UsageStats	2

三种修改途径：

1. 后台 UI（推荐）：Administration → Global system preferences，逐项搜索修改，界面写明语义与可选值；
2. koha-mysql 直改表：适合批量或脚本化，如实测将 REST 基本认证打开：update systempreferences set value=1 where variable='RESTBasicAuth';；
3. REST API：/api/v1/preferences（需先满足认证条件）。

关键机制：系统参数经 memcached 缓存。直改数据库后不重启 memcached，新值不会生效——实测修改 RESTBasicAuth 后 API 仍 401，重启 memcached 后返回 200（排障过程见《Koha 26.05 Docker Compose 部署指南》10.4）。走后台 UI 修改则由 Koha 自己负责刷新缓存，无此问题。

3.4 环境变量层

.env 中的变量只在 init 阶段被消费：koha-docker 的入口脚本把它们翻译成 koha-create 命令行参数（--marcflavor、--elasticsearch-server、--memcached-servers、--timezone 等，实测 koha-create usage 见 CLI 详解篇），生成 koha-conf.xml 与 Apache vhost，随后写入 koha-bootstrapped 标记、不再重复执行。因此对已建成的实例，改 .env 不会改变任何现状，要调参请直接改 koha-conf.xml（系统参数层则用 UI）。

四、参数总览

4.1 koha-conf.xml 结构总览

实测文件（581 行）根元素为 <yazgfs>，内含两个世界：前半（第 1250 行）是 Zebra 检索引擎的 server 定义块，后半（第 252580 行）<config> 元素才是实例主配置。主要块与实测行号：

4.2 .env 变量总览

实测 .env（koha-docker defaults 派生）关键变量：

4.3 系统参数总览

systempreferences 实测 918 条，覆盖检索、流通、编目、OPAC/后台界面、邮件、API 等全部业务域。后台 UI 按域分组呈现并附官方说明；本篇不逐条罗列（体量过大），第五章只展开与部署运维直接相关、且实测验证过的参数。

五、核心参数分类详解

5.1 数据库连接（DB 块）

实测片段（koha-conf.xml 第 253~262 行）：

 <db_scheme>mysql</db_scheme>
 <database>koha_koha</database>
 <hostname>db</hostname>
 <port>3306</port>
 <user>koha_koha</user>
 <pass>q1w2e3r4</pass>
 <tls>__DB_USE_TLS__</tls>
 <ca>__DB_TLS_CA_CERTIFICATE__</ca>
 <cert>__DB_TLS_CLIENT_CERTIFICATE__</cert>
 <key>__DB_TLS_CLIENT_KEY__</key>

• hostname 指向 compose 服务名 db（容器网络内 DNS），不是宿主机地址；
• <user>/<pass> 同时是 web 安装器的登录凭据（实测：安装器提示语明确说用 koha-conf.xml 中的用户名口令登录）；
• 查看实例库口令可用 koha-passwd koha（实测输出即 q1w2e3r4）；
• TLS 四项是模板占位符（__DB_USE_TLS__ 等），默认未启用 DB 加密连接；生产接 TLS 数据库时按官方注释替换为 1/证书路径。

5.2 Elasticsearch 检索引擎块

实测片段（第 361~389 行，节选）：

 <elasticsearch>
     <server>es:9200</server>
     <index_name>koha_koha</index_name>
     <cxn_pool>Static</cxn_pool>
 </elasticsearch>
 <es_indexer_batch_size>10</es_indexer_batch_size>

是否真正使用 ES 由系统参数 SearchEngine 决定（实测值 Elasticsearch；若为 Zebra 则走 5.3 的引擎）。实测重建索引后的索引状态：

$ curl -s "http://es:9200/_cat/indices?v"
health status index                 uuid                   pri rep docs.count docs.deleted store.size pri.store.size dataset.size
yellow open   koha_koha_authorities EZmegIlbS_ilbg_623Cvwg   5   1          0            0      1.2kb          1.2kb        1.2kb
yellow open   koha_koha_biblios     MuTtX0kMRv2dl0PxLqDPbg   5   1          0            0      1.2kb          1.2kb        1.2kb

单节点 yellow 属正常（副本无处安放）。

5.3 Zebra 引擎配置块（旧检索引擎）

文件前半（第 3~174 行）是 Zebra 的 <listen>/<server> 定义，实测要点：

<listen id="biblioserver" >unix:/var/run/koha/koha/bibliosocket</listen>
<listen id="authorityserver" >unix:/var/run/koha/koha/authoritysocket</listen>
<server id="biblioserver"  listenref="biblioserver">
    <directory>/var/lib/koha/koha/biblios</directory>
    <config>/etc/koha/sites/koha/zebra-biblios-dom.cfg</config>

• 书目/规范两个引擎各用 unix 套接字通信，索引数据落在 /var/lib/koha/koha/{biblios,authorities}（bind 挂载于宿主 data/instance）；
• 引擎凭据为 kohauser + 随机口令（同文件 <password>，明文存储于实例配置目录）；
• <config> 元素内另有 Zebra 杂项：zebra_lockdir、use_zebra_facets 1、zebra_max_record_size 1024、zebra_connection_timeout 30；
• 本实测选 Elasticsearch，此块保留但不承载检索流量；koha-zebra --status 报 not running 属预期（见 7.6）。

5.4 缓存（memcached）

实测（第 301~302 行）：

 <memcached_servers>memcached:11211</memcached_servers>
 <memcached_namespace>koha_koha</memcached_namespace>

• memcached_servers 可逗号分隔多实例；compose 形态指向 memcached 服务；
• memcached_namespace 以实例名为前缀做键空间隔离，多实例共用一个 memcached 时互不串扰；
• 系统参数、会话、部分检索上下文都经此缓存——这解释了 3.3 的「直改库需重启 memcached」现象。

5.5 时区与语言

• timezone（第 419 行）实测 Asia/Shanghai，由 .env 的 TIMEZONE 初始化写入；它决定流通截止日期、逾期计算等时间语义，建库后修改属高风险操作（历史数据按旧时区解释）；
• 语言：.env 的 KOHA_LANGS 为空，实测 koha-translate --list 无输出，init 日志出现 No locale installed WARN；界面语言由系统参数 language 控制，默认英语。需要中文界面须先装语言包（koha-translate --install zh-Hans，见 CLI 详解篇）。

5.6 路径与存储

实测 <config> 内路径项（第 267~278、303 行）与 compose 卷的对应关系：

intranetdir/opacdir/htdocs/includes/docdir 指向 /usr/share/koha 只读安装树（镜像内容，无需持久化）。

5.7 安全密钥与凭据

5.8 邮件与消息队列

SMTP（第 472~480 行）实测：

 <smtp_server>
    <host>localhost</host>
    <port>25</port>
    <timeout>120</timeout>
    <ssl_mode>disabled</ssl_mode>
    <user_name></user_name>
    <password></password>
    <debug>0</debug>
 </smtp_server>

默认指向 localhost:25——容器形态内没有本地 MTA，不配置就发不出催还/挂架通知邮件（见 7.7）。message_broker 块（482488 行）默认 localhost:61613 guest/guest，仅在使用 RabbitMQ 消息通道（koha-create --mb-* 系列参数启用）时有意义。message_domain_limits（501507 行）支持按收件域限速（如 outlook.com 每 1 分钟 30 封），防批量通知被对方退信。

5.9 插件与开发开关

• enable_plugins（268 行）实测 0：插件总开关，置 1 并重启后后台出现 Plugin management；
• plugins_restricted/plugins_restart（437~438 行）实测均 1：限制仅超管可装、装后需重启；
• plugin_repos（439~462 行）：官方示例注释了 ByWater/Theke/Open Fifth/inLibro 四个 GitHub 插件源；
• git_install/debug_mode/strict_sql_modes（430~435 行）实测均 0，官方注释明确 strict_sql_modes 不应用于生产。

5.10 日志（log4perl.conf）

log4perl_conf（295 行）指向 /etc/koha/sites/koha/log4perl.conf。实测该文件为 intranet/opac/z3950/api 等 logger 各配一个 WARN 级 File appender，落盘 /var/log/koha/koha/*.log（如 intranet-error.log、opac-error.log、api-error.log）；SIP logger 默认 DEBUG。排障时把对应 logger 调成 DEBUG/INFO 即可加密度，无需改代码。

5.11 Apache vhost 与端口

init 阶段生成 vhost 存入命名卷（/etc/apache2/sites-available/koha.conf），实测要点：*:8080 为 OPAC（ServerName koha.myDNSname.org），*:8081 为 Intranet（koha-intra.myDNSname.org），两站分别 SetEnv KOHA_CONF 指向实例配置，AssignUserID koha-koha 走 mpm-itk 降权；反代规则 Include 自 apache-shared{,-opac-plack,-intranet-plack}.conf。宿主端口 8140/8142 由 compose ports: 映射，与 vhost 内的 8080/8081 是两层概念。vhost 兜底允许 IP 直访，故实测用 http://<host>:8142 即可完成安装器流程。

六、生产配置模板

适用场景声明：以下模板按 16GB 内存、NVMe SSD、单馆或小型联盟（≤50 万书目、≤10 万读者）、Docker Compose 单机部署 给出；更大规模建议将 ES/DB 拆独立主机并参考官方硬件建议。

6.1 .env 生产片段

# 版本钉到不可变标签（完整版本含 -N 修订号，保证可复现）
KOHA_VERSION=26.05.04-1
KOHA_INSTANCE=koha
KOHA_DOMAIN=.lib.example.org

# 数据库：强随机口令，长度≥16，与 compose 的 db 服务同步
DB_ROOT_PASSWORD=<强随机>
DB_PASSWORD=<强随机>

# 业务基线
KOHA_MARC_FLAVOUR=marc21
SEARCH_ENGINE=Elasticsearch
ELASTICSEARCH_SERVER=es:9200
TIMEZONE=Asia/Shanghai
KOHA_LANGS=zh-Hans
WORKER_MAX_PROCESSES=2

# 生产不要用 mana 测试服
MANA_URL=https://mana-kb.koha-community.org

6.2 koha-conf.xml 生产要点

在实例配置上相对默认值做以下调整（均为第五章讲过的项）：

<!-- 队列积压时调大（官方注释），16GB 内存场景建议 50 -->
<es_indexer_batch_size>50</es_indexer_batch_size>

<!-- ES 开启认证时 -->
<elasticsearch>
    <server>es.example.org:9200</server>
    <index_name>koha_koha</index_name>
    <userinfo>elastic:<强随机></userinfo>
    <use_https>1</use_https>
    <cxn_pool>Static</cxn_pool>
</elasticsearch>

<!-- 出站邮件指向真实中继 -->
<smtp_server>
    <host>smtp.example.org</host>
    <port>587</port>
    <ssl_mode>STARTTLS</ssl_mode>
    <user_name>koha-noreply@example.org</user_name>
    <password><强随机></password>
</smtp_server>

<!-- 保持 0：禁止从后台工具下载数据库/配置 -->
<backup_db_via_tools>0</backup_db_via_tools>
<backup_conf_via_tools>0</backup_conf_via_tools>

compose 侧同步：ES 堆按内存预算上调（默认 -Xms512m -Xmx512m 仅够演示）；api_secret_passphrase、encryption_key、DB 口令、备份产物一律纳入密钥管理，.env 与 data/etc 目录权限收紧（实测备份文件属主 root:koha-koha、权限 640，保持即可）。

6.3 系统参数基线（实测存在的项）

其余业务参数（逾期、流通规则、OPAC 界面）在后台 UI 按馆情逐项配置，均有官方说明。

6.4 生效操作

改 koha-conf.xml/.env 重建后：重启 plack 与 apache；改系统参数走 UI 即时生效，直改库则重启 memcached。

七、常见问题

7.1 改了 koha-conf.xml 不生效

配置在进程启动时读取：改文件后需重启 plack/apache（以及 worker、es-indexer 等用到该配置的进程），见 6.4。

7.2 直改 systempreferences 表不生效

系统参数经 memcached 缓存，直改数据库后重启 memcached 才生效；实测 RESTBasicAuth 置 1 后 API 仍 401，重启 memcached 后 200（完整过程见《Koha 26.05 Docker Compose 部署指南》10.4）。走后台 UI 修改无此问题。

7.3 改了 .env 里 TIMEZONE/ELASTICSEARCH_SERVER，实例没变化

.env 只在 init 阶段消费一次（koha-bootstrapped 标记后不再执行）。对已建成实例：直接编辑 koha-conf.xml 对应项并重启，或删实例重建（会丢数据，慎用）。

7.4 忘了实例数据库口令

koha-passwd <实例名> 直接打印（实测输出 q1w2e3r4）。该口令同时用于 web 安装器登录。

7.5 OPAC 搜索永远无结果

按链检查：系统参数 SearchEngine 是否为 Elasticsearch（3.3 实测查询法）→ ES 块 <server> 连通性 → 索引是否存在（_cat/indices，5.2 实测回显）→ 跑一次 koha-elasticsearch --rebuild <实例> 重建（回显见 CLI 详解篇）。

7.6 koha-zebra --status 报 failed

用 ES 时 Zebra 引擎本就不运行；且拆分服务形态下各 koha-* --status 查不到前台进程的 PID，一律报 failed，属预期噪音（见《Koha 26.05 Docker Compose 部署指南》10.3），以 HTTP 探活与日志为准。

7.7 催还/挂架通知邮件发不出去

默认 SMTP 块指向 localhost:25，容器形态内没有本地 MTA。按 6.2 配置真实中继（host/port/ssl_mode/user_name/password），并确认系统参数中邮件相关开关（如 EnhancedMessagingPreferences）已按需打开。

参考链接

• 《Koha 介绍与选型指南》：https://www.quzuo.net/document/EZ5oAd2sENzd
• 《Koha 26.05 Docker Compose 部署指南》：https://www.quzuo.net/document/UVjA2ji6fxcH
• Koha 官方手册系统参数章节：https://koha-community.org/manual/latest/en/html/preferences.html（查询日期 2026-11-01）
• koha-docker 项目（compose 编排与入口脚本）：https://gitlab.com/koha-community/docker/koha-docker
• Search::Elasticsearch 连接池说明：https://metacpan.org/pod/Search::Elasticsearch#cxn_pool