LedgerSMB 1.13.8 配置参数详解

目标：讲清 LedgerSMB 1.13.8 的配置体系——配置文件从哪里读、按什么顺序合并、环境变量如何接线，并逐组解读全部配置键。所有默认值与行为均取自实测实例（1.13.8）与实例内置的官方带注释配置样例，实测日期 2026-10-24。

一、环境信息

说明：LedgerSMB 自 1.9 起配置从旧版 ledgersmb.conf（INI 格式）迁移到 ledgersmb.yaml（YAML 格式），1.13 仍保留对旧 INI 的兼容读取（加载顺序里排在最后），但官方样例与本文均以 YAML 为准。

二、配置体系与加载顺序

实测源码（bin/ledgersmb-server.psgi）给出的解析与合并规则如下：

第 1 步：确定主配置文件（按顺序取第一个存在的，相对应用目录 /srv/ledgersmb）：

1. 环境变量 LSMB_CONFIG_FILE 指定的路径
2. ledgersmb.yaml（推荐）
3. ledgersmb.yml
4. ledgersmb.conf（旧版 INI，仅兼容）
5. 全都不存在 → 使用程序内置默认配置（与 doc/conf/ledgersmb.yaml 同内容）

第 2 步：逐层合并（后合并者覆盖先合并者，同键后者胜）：

内置默认配置
  ← 主配置文件（ledgersmb.yaml）
  ← 同目录下所有 ledgersmb.NNN.yaml 递增编号片段，按编号从大到小依次合并
     （即编号越小越后合并、优先级越高；镜像默认片段为 000/001/002/003）

镜像启动时的自动生成：容器启动时 config.sh 检查 /srv/ledgersmb/local/conf/（不存在则创建），若主文件缺失则按环境变量生成 ledgersmb.yaml，并按邮件变量生成 ledgersmb.000.yaml（SMTP 主机）、ledgersmb.001.yaml（端口）、ledgersmb.002.yaml（helo）、ledgersmb.003.yaml（SASL 认证）。因此把宿主目录挂载到 /srv/ledgersmb/local/conf 是官方推荐的配置外置方式：自己的片段放进去、重启即生效，生成文件也会写进同一目录。

实测验证（本专栏部署篇实例，追加片段 ledgersmb.100.yaml）：

# /srv/ledgersmb/local/conf/ledgersmb.100.yaml（实测）
logging:
  level: DEBUG
login_settings:
  default_db: demo1

重启后不带 company 参数登录，实测登录接口直接落到 demo1 公司库：

curl -s -X POST 'http://localhost:8130/login.pl?__action=authenticate' \
  -H 'Content-Type: application/json' \
  -d '{"login":"admin","password":"q1w2e3r4"}'
# { "target":  "e368b9938746fa090d6afd3628355133/erp.pl?user=admin" }

返回 target 路径为 e368b9938746fa090d6afd3628355133 = md5("demo1")（实测 echo -n demo1 | md5sum 一致），证明片段中的 login_settings.default_db: demo1 已覆盖内置默认值并生效。

💡 独特之处：应用的配置文件里没有任何数据库口令。LedgerSMB 的数据库连接按"会话用户"认证——业务用户登录用的就是该用户在 PostgreSQL 里的角色口令；数据库管理员（setup.pl）凭据走 HTTP Basic 认证。因此配置文件的敏感面比常见 Web 应用小得多，但仍建议限制 local/conf 目录权限（邮件 SASL 片段 003 里会落 SMTP 口令明文）。

三、配置参数逐组详解

以下键名与默认值实测自实例内置官方样例（doc/conf/ledgersmb.yaml，!book 注释即官方键名标记），括号内为实测默认值：

3.1 cookie — 会话 Cookie

3.2 db — 数据库连接

⚠️ 官方样例默认 sslmode: disable：应用与数据库同机/同内网时常见，但跨网络部署务必改 require 及以上级别。

3.3 default_locale — 界面语言

实测示例：默认实例登录页 HTML 带 lang="es-ve"（镜像构建语言协商的实测结果），说明未显式配置时由 Accept-Language 决定；中文界面把该头设为 zh 系即可命中随附翻译（项目自称 45 种语言）。

3.4 environment_variables — 子进程环境白名单

实测默认：PATH: /bin:/usr/bin:/usr/local/bin:/usr/local/pgsql/bin。应用把执行环境整体清空、只放行白名单变量（LedgerSMB::EnvVarSetter），这是模板 LaTeX/打印机命令执行的安全边界，一般无需改动。

3.5 extra_middleware — 中间件扩展点

实测默认 []。可插入 Plack::Middleware 实现定制请求处理；官方在 doc/conf/ledgersmb.yaml.debug 给了带调试中间件的完整样例。

3.6 logging — 日志

3.7 login_settings — 登录默认值

3.8 mail — 发信

官方样例给出两种 mail.transport：

• Sendmail 方式（样例默认）：$class: Email::Sender::Transport::Sendmail，可用 path 指定 sendmail 兼容二进制（注释示例 /usr/bin/ssmtp）
• SMTP 方式：$class: Email::Sender::Transport::SMTP + host/port/ssl/sasl_authenticator（$class: Authen::SASL、mechanism: PLAIN、callback user/pass）

实测实例生成结果（镜像默认环境变量驱动）：

# /srv/ledgersmb/local/conf/ledgersmb.000.yaml（实测）
mail:
  transport:
    host: 10.89.72.1      # __CONTAINER_GATEWAY__ 特殊值被解析为默认网关 IP
# /srv/ledgersmb/local/conf/ledgersmb.yaml（实测，节选）
mail:
  transport:
    $class: Email::Sender::Transport::SMTP
    ssl: none

3.9 miscellaneous — 杂项

3.10 output_formatter — 输出格式插件链

实测默认插件链（顺序即官方样例）：LaTeX→PDF、LaTeX→PS、XLSX→XLS、XLSX→XLSX、ODS、CSV、TXT、HTML、External（外部命令自定义转换，样例 command: /bin/true %d %f %o）。这是发票/报表多格式导出的引擎；默认以 LaTeX 为 PDF 源，也允许 HTML→PDF 类自定义插件替换。

3.11 paths — 路径中枢

实测默认（相对 /srv/ledgersmb）：locale: ./locale/po、sql: ./sql、sql_data: ./locale、templates: ./templates、UI: ./UI、UI_cache: lsmb_templates、workflows: [./workflows, ./custom_workflows]。其他配置组用 $ref 引用这里，改路径一处生效。

3.12 printers — 服务器侧打印机

实测默认：Laser: lpr -Plaser、Epson: lpr -PEpson、fallback: Laser。定义系统内"打印"动作可用的管道命令。

3.13 reconciliation_importer — 银行流水导入解析器

实测默认四套配置：OFX、ISO 20022 CAMT.053、PayPal CSV（按列名）与 PayPal CSV（按列号），CSV 解析器支持 first_row（headers/data）、mapping（source/amount/type/date 到列的映射）、金额格式（如 1'000.00）与日期格式（如 DD/MM/YYYY）。对账导入其他银行流水照此结构新增片段即可。

3.14 setup_settings — setup.pl 专用

3.15 ui — 界面模板

实测默认：ui.class: LedgerSMB::Template::UI、method: new_UI、lifecycle: eager、args.cache: $ref paths/UI_cache、args.root: $ref paths/UI；注释项 ui.stylesheet（默认 ledgersmb.css）可全局换肤。

3.16 workflows — 工作流定义

实测默认：LedgerSMB::Workflow::Loader（eager），directories: [./workflows, ./custom_workflows]——排前者同名覆盖排后者，业务审批流（如销售单审批）自定义定义文件放 custom_workflows。

四、容器环境变量（与配置文件的接线关系）

以下为官方镜像（ledgersmb/ledgersmb:1.13.8，镜像内实测 Config.Env + config.sh 源码）提供的环境变量及其落地位置：

兼容说明：镜像对旧 ssmtp 系变量（SSMTP_MAILHUB、SSMTP_AUTH_USER 等）保留自动映射并输出 deprecated 告警（实测 config.sh 逻辑），新部署直接用 LSMB_MAIL_* 即可。

五、生产配置要点（基于上述参数的组合建议)

1. TLS 与代理：前置反代终结 HTTPS 后，把 miscellaneous.proxy_ip 改为反代实际地址段（镜像默认 172.17.0.1/12 只适配默认网桥场景），否则客户端 IP 与协议判断失真；Safari 用户全靠 HTTPS。
2. 数据库传输安全：db.connect_data.sslmode 生产改 require 及以上；跨主机连库同时核对 host/port。
3. 会话稳定：多进程/多实例部署显式设置 cookie.secret，避免动态 secret 造成会话互踢；同一域名多版本并行用 cookie.name 区分。
4. 上传与导出：max_upload_size 默认 4 MiB；PDF 导出依赖 output_formatter 的 LaTeX 插件链，服务器需保证 LaTeX 工具链可用（官方镜像已含）。
5. 日志排障：logging.level 调 DEBUG 重启即生效（本文实测），精细控制用 logging.file 指向独立 Log4perl 配置；生产常态保持 ERROR 减噪。
6. 配置变更路径：改配置 → 重启应用进程即可，无需动数据库；片段编号法便于叠加第三方集成配置而不碰主文件。

六、快速排障对照

七、参考

• 官方带注释配置样例（1.13.8 源码内）：https://github.com/ledgersmb/LedgerSMB/blob/1.13.8/doc/conf/ledgersmb.yaml
• 官方镜像环境变量文档：https://github.com/ledgersmb/ledgersmb-docker/blob/1.13/README.md
• libpq 连接参数官方文档：https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS
• 本专栏同系列：部署实操见《LedgerSMB 1.13.8 Docker Compose 部署指南》；产品认知见《LedgerSMB 1.13.8 介绍与选型指南》；接口调用见《LedgerSMB 1.13.8 API 使用详解》。