Libervia 0.9.0 配置参数详解

目标：系统讲解 Libervia 0.9.0 后端的配置体系——配置文件搜索路径与优先级、INI 节与参数域（目录、XMPP、桥接、PubSub、邮件、TLS、日志、前端节）的逐项说明与默认值，并给出参数生效验证实录。本文参数定义溯源自发行包源码（sat/core/constants.py 等），行为均经真实服务器实测（实测日期：2026-10-26），命令与回显逐行照抄。

一、环境信息

本篇实测环境：

二、配置体系总览

2.1 文件格式与命名沿革

Libervia 0.9.0 使用 INI 格式配置文件，按「节（section）+ 键 = 值」组织。v0.8.0 起（2021-11-30）主配置文件更名为 libervia.conf，旧名 sat.conf 仍被读取兼容（官方 CHANGELOG："libervia.conf is now used for settings (but sat.conf is still usable, at least for now)"）；同版起配置节按前端类型命名（web、cli、tui 等）。

2.2 配置文件搜索路径与优先级（实测）

后端按固定清单依次读取所有存在的配置文件，清单顺序即优先级（升序），后读入的文件覆盖先读入的同类参数。以下为在 root 用户、已创建 ~/.config/libervia/ 目录环境下的完整搜索清单（实测命令与回显）：

PYTHONPATH=/usr/share/libervia python3 -c "
from sat.core.constants import Const
for p in Const.CONFIG_FILES: print(p)
"

/etc/_libervia.conf
/etc/libervia.conf
/root/libervia.conf
/root/.libervia.conf
/root/.config/libervia/libervia.conf
/usr/share/libervia/libervia.conf
/etc/_sat.conf
/etc/sat.conf
/root/sat.conf
/root/.sat.conf
/root/.config/libervia/sat.conf
/usr/share/libervia/sat.conf

清单结构解读：

⚠️ 两条实测得出的优先级结论（容易踩坑）：

1. 旧名 sat.conf 覆盖新名 libervia.conf：同名参数同时出现在两类文件时，sat.conf 系列排在清单后段、读取更晚，最终生效（实测见第七节）；
2. ~/.config/libervia/ 目录需先创建：搜索清单中 XDG 路径仅在目录存在时才会出现（XDG BaseDirectory 行为）。全新系统首次部署时先执行 mkdir -p ~/.config/libervia，否则清单里看不到它。

2.3 环境变量覆盖

部分参数支持环境变量覆盖，前缀为 SAT_（源码 sat/core/constants.py 定义 ENV_PREFIX = "SAT_"，改名后沿用旧前缀）。日志参数即走此机制（见 5.7 节），如 SAT_LOG_LEVEL=debug。

三、参数查看与修改方式

3.1 查看当前生效配置

后端不提供 config dump 类子命令。两种实用查看方式：

方式一：直接读配置文件内容（INI 本身即真相）：

cat ~/.config/libervia/libervia.conf

[DEFAULT]
xmpp_domain = srv.lan

方式二：用后端自带的解析函数打印合并后的生效值（等价于后端启动时的读取结果，改配置前预检推荐）：

PYTHONPATH=/usr/share/libervia python3 -c "
from sat.tools import config as tc
c = tc.parseMainConf()
print('xmpp_domain =', tc.getConfig(c, None, 'xmpp_domain'))
print('bridge      =', tc.getConfig(c, '', 'bridge', 'dbus'))
"

xmpp_domain = srv.lan
bridge      = dbus

3.2 修改后的生效方式

配置在后端启动时一次性读入，修改后需重启后端生效：

sudo systemctl restart libervia-backend.service

systemd 托管部署时也可先做语法与解析预检（3.1 节方式二），确认无解析异常再重启，避免配置错误导致服务启动失败。

四、参数总览

源码扫描（/usr/share/libervia/sat/ 全量 getConfig 调用点汇总）得出的参数域全景：

💡 说明：Libervia 是「客户端侧平台」，除可选的组件/网关监听端口外不对外监听网络端口，因此没有传统服务端软件的监听地址/端口参数域；TLS 参数用于组件（如 ActivityPub 网关）对外提供 HTTPS 服务的场景。

五、核心参数分类详解

5.1 [DEFAULT] 数据目录五件套

五个目录参数的默认值定义于源码 sat/core/constants.py 的 DEFAULT_CONFIG（Linux 分支）：

实测 local_dir 与 log_dir 落位：

ls ~/.local/share/libervia/ | head -6

cache
libervia.db
libervia.log
libervia.log.1
libervia.log.10
libervia.log.2

• libervia.db：后端 SQLite 主数据库（profile、缓存、状态数据）；
• libervia.log 及 .1~.10 轮转序列：后端运行日志（log_dir 未显式配置时落在 local_dir）。

自定义示例（改变全部落盘位置）：

[DEFAULT]
local_dir = /var/lib/libervia

pid_dir/log_dir 默认值写作 %(local_dir)s——INI 插值语法，跟随 local_dir 变化，无需逐个修改。

5.2 [DEFAULT] XMPP 与账户参数

• xmpp_domain：后端默认使用的 XMPP 域名。未设置时每次启动打印提醒日志（实测）：

  xmpp_domain needs to be set in sat.conf. Using "example.net" meanwhile
  

  设置后提醒消失（完整闭环见第七节）。按 profile 连接时实际使用的域名取决于 profile 绑定的 JID，本参数主要服务组件/默认域场景；

• new_account_domain：账户注册类功能（XEP-0077 In-Band Registration）默认注册域名；

• reserved_list：保留账户名列表，注册功能拒绝创建其中的用户名。

5.3 [DEFAULT] 桥接参数

后端启动时以该前缀在 D-Bus 会话总线上注册服务，前端据此发现并调用。这也解释了后端依赖会话总线的部署前置（见《Debian 12 安装 Libervia 0.9.0 后端与 CLI 指南》第七节）。

5.4 [DEFAULT] PubSub 参数

• pubsub_service：指定默认 PubSub 服务 JID（如组件 pubsub.srv.lan）；不设时使用账户自身服务；
• pubsub_cache_strategy：PubSub 缓存策略。源码逻辑（plugin_pubsub_cache.py）：设为 no_cache 时完全禁用缓存（启动日志打印 "Pubsub cache won't be used due to pubsub_cache_strategy=..."），其余取值或不设置均启用缓存。

禁用缓存示例：

[DEFAULT]
pubsub_cache_strategy = no_cache

5.5 [DEFAULT] 邮件通知参数

服务器通知类邮件（账户邀请、管理员通知等）使用以下参数（源码 tools/common/email.py）：

最小可用示例（对接内网 Postfix 中继）：

[DEFAULT]
email_server = mail.srv.lan
email_port = 25
email_from = libervia@srv.lan
email_admins_list = admin@srv.lan

5.6 TLS 参数

TLS 证书三元组（源码 tools/common/tls.py，逐项读取）：

该组参数用于对外监听的组件/网关服务（如 ActivityPub 网关组件的 HTTPS 端口）。配置节可全局（[DEFAULT]）或按组件节单独指定。示例：

[DEFAULT]
tls_certificate = /etc/libervia/certs/srv.lan.crt
tls_private_key = /etc/libervia/certs/srv.lan.key
tls_chain = /etc/libervia/certs/chain.pem

⚠️ 注意区分：Libervia 作为 XMPP 客户端连接服务器时的 TLS 由 XMPP 层自动协商，证书信任走系统 CA（/etc/ssl/certs），与本组参数无关。自建服务器使用自签证书时的信任配置见安装指南 9.3 节。

5.7 日志参数

日志参数位于 [DEFAULT] 节，键名以 log_ 前缀（源码 LOG_OPT_SECTION = "DEFAULT"、LOG_OPT_PREFIX = "log_"）：

全部支持环境变量覆盖，变量名为 SAT_LOG_<参数大写>（如 SAT_LOG_LEVEL=debug），且环境变量优先于配置文件（源码 log_config.py 先读环境、回落配置）。

调试排障示例（临时提级，不改文件）：

SAT_LOG_LEVEL=debug libervia-cli profile connect -p admin --pwd q1w2e3r4 -c

5.8 前端节参数

v0.8.0 起各前端的自有参数放在以其类型命名的节里（[web]、[cli]、[tui]）。源码中可见的前端公共参数：

[web] 节的端口、连接参数等属于 libervia-web 前端包。Debian 12 仓库未提供 libervia-web 包（仅 backend/cli/tui），Web 前端参数需部署 Web 前端后按其文档配置；本篇不展开。

六、生产配置模板

一台自建服务器上推荐的最小生产配置（/etc/libervia/libervia.conf，多用户共享全局参数）：

[DEFAULT]
; XMPP 默认域名（与服务器 VirtualHost 一致）
xmpp_domain = srv.lan

; PubSub 数据层服务（自建 pubsub 组件时指定）
pubsub_service = pubsub.srv.lan

; 通知邮件中继
email_server = mail.srv.lan
email_port = 25
email_from = libervia@srv.lan
email_admins_list = admin@srv.lan

; 日志
log_level = info

用户级个性配置放 ~/.config/libervia/libervia.conf（只放差异项，如前端参数），全局与用户级同参数时注意第七节的优先级规则。

七、生效验证实录

7.1 xmpp_domain 设置闭环

第一步：未配置时，后端启动日志含提醒（实测）：

Oct 26 07:26:15 srv libervia-backend[21605]: 2026-10-26T07:26:15+0000 xmpp_domain needs to be set in sat.conf. Using "example.net" meanwhile

第二步：写入用户级配置并重启：

printf "[DEFAULT]\nxmpp_domain = srv.lan\n" > /root/.config/libervia/libervia.conf
sudo systemctl restart libervia-backend.service

第三步：验证提醒消失、服务正常：

journalctl -u libervia-backend.service --since "-30s" --no-pager | grep -c "xmpp_domain needs"
systemctl is-active libervia-backend.service

0
active

7.2 多文件覆盖优先级实测

三个配置文件同时设置不同 xmpp_domain 值（~/.config/libervia/libervia.conf = from-user-config.lan、~/libervia.conf = from-home-conf.lan、~/sat.conf = from-legacy-sat.lan），用后端解析函数读取生效值：

--- effective xmpp_domain: from-legacy-sat.lan

结论：~/sat.conf（旧名兼容文件）胜出，印证 2.2 节「sat.conf 系列整体优先级高于 libervia.conf 系列」。部署时若发现配置「改了不生效」，先排查各搜索路径下是否残留旧 sat.conf。

八、常见问题（FAQ）

Q1：改了 libervia.conf 但参数不生效。 三点排查：① 是否重启了后端（配置仅启动时读取）；② 各搜索路径下是否有同名参数的旧 sat.conf（优先级更高，实测见 7.2 节）；③ 是否写错了节名（日志参数必须在 [DEFAULT] 节且带 log_ 前缀）。

Q2：~/.config/libervia/libervia.conf 写了却不在搜索清单里。 XDG 路径仅在目录存在时进入清单。先 mkdir -p ~/.config/libervia 再查看（2.2 节实测）。

Q3：启动日志一直提示 xmpp_domain needs to be set in sat.conf。 按 7.1 节闭环设置 xmpp_domain；提示中提到的 "sat.conf" 是日志文案沿用旧名，写入 libervia.conf 同样有效。

Q4：日志文件在哪？能改位置吗？ 默认 ~/.local/share/libervia/libervia.log（log_dir 跟随 local_dir）。设置 [DEFAULT] log_dir 可独立指定；systemd 部署时日志同时进 journal（journalctl -u libervia-backend.service）。

Q5：环境变量能覆盖配置文件吗？ 日志参数可以：SAT_LOG_LEVEL 等优先于文件（5.7 节）。注意前缀是 SAT_ 而非 LIBERVIA_（源码 ENV_PREFIX = "SAT_"）。

Q6：pid_dir/log_dir 的 %(local_dir)s 是什么意思？ INI 插值引用：跟随 local_dir 的值。改 local_dir 即整体迁移落盘位置，无需逐项重复配置。

九、参考链接

• 源码配置定义（sat/core/constants.py）：https://repos.goffi.org/libervia/file/tip/sat/core/constants.py
• 官方主站与文档站：https://libervia.org 、https://libervia.org/documentation
• 本站相关篇目：
  • 《Libervia 0.9.0 介绍与选型指南》
  • 《Debian 12 安装 Libervia 0.9.0 后端与 CLI 指南》