Debian 12 安装 Libervia 0.9.0 后端与 CLI 指南

目标：在一台 Debian 12 服务器上从零完成 Libervia 0.9.0 后端（libervia-backend）与命令行前端（libervia-cli）的安装、systemd 托管、对接 XMPP 服务器（Prosody 对端）、profile 创建与连接验证，并完成首条消息收发实测。本文全部命令与回显均来自真实服务器环境实测（实测日期：2026-10-26），逐行照抄。

一、环境信息

本指南实测环境如下：

项目	内容
操作系统	Debian 12（bookworm），内核自带 systemd
Python 运行时	Python 3.11.2（系统自带，`python3 --version` 实测）
Libervia 版本	0.9.0~hg3993-4+deb12u1（backend / cli / tui 三包同版本）
XMPP 对端服务器	Prosody 0.12.3-1+deb12u1（Debian 12 仓库）
服务器主机名 / XMPP 域名	srv / srv.lan
测试账户	admin@srv.lan、user1@srv.lan，密码均为 q1w2e3r4
软件源	deb.debian.org（官方源，实测直连可用）

实测基准命令回显：

python3 --version

Python 3.11.2

💡 说明：Debian 12 自带 Python 3.11，Libervia 后端直接使用系统 Python 运行，安装发行包时依赖会一并带入，无需手工准备 Python 环境，也无需 pip。

二、前置条件

一台 Debian 12 服务器：具备 root 或 sudo 权限；systemd 正常运行（systemctl is-system-running 返回 running 或 degraded 均可）；
可用的软件源：官方源 deb.debian.org 实测直连可用，无需额外配置软件源；
一个 XMPP 账户：Libervia 是 XMPP 客户端侧平台，后端必须以某个 XMPP 账户（JID）身份连接服务器运行。若尚无 XMPP 服务器，本指南第九节将从零搭建 Prosody 对端并注册账户；
D-Bus：后端与前端通过 D-Bus 会话总线通信，Debian 12 桌面环境天然具备；最小化服务器需要手工启动会话总线（第七节实测）。

三、版本选型说明

Debian Package Tracker 与本机 apt-cache policy 实查（查询日期 2026-10-26）：

apt-cache policy libervia-backend libervia-cli

libervia-backend:
  Installed: 0.9.0~hg3993-4+deb12u1
  Candidate: 0.9.0~hg3993-4+deb12u1
  Version table:
 *** 0.9.0~hg3993-4+deb12u1 500
        500 http://deb.debian.org/debian bookworm/main amd64 Packages
        100 /var/lib/dpkg/status
libervia-cli:
  Installed: 0.9.0~hg3993-4+deb12u1
  Candidate: 0.9.0~hg3993-4+deb12u1
  Version table:
 *** 0.9.0~hg3993-4+deb12u1 500
        500 http://deb.debian.org/debian bookworm/main amd64 Packages
        100 /var/lib/dpkg/status

版本选择结论：

Debian 12 仓库提供的 0.9.0~hg3993-4+deb12u1 即当前 0.9.0 稳定线，包名中的 hg3993 表示由官方 Mercurial 版本库第 3993 号变更集快照构建；
发行包按前端拆分：libervia-backend（后端）、libervia-cli（命令行前端）、libervia-tui（终端前端），另有依赖包 libervia-templates（模板引擎，0.8.0+hg354.cac1a96f3df8+dfsg-1）随装带入；
不要走 pip：PyPI 上的 libervia-backend 停在 0.8.0（2021-11-30 上传后未再更新），且不存在独立的 libervia-cli Python 包——0.9.0 线的主要分发渠道就是发行版仓库；
Debian 12 仓库没有 libervia-doc 包（该包仅在 Debian 13/testing 之后的仓库提供）。

四、安装方案 A：发行版仓库在线安装（推荐主线）

4.1 方案说明

直接使用 Debian 12 官方仓库在线安装，一条命令完成后端、CLI 与全部依赖（Python 库、D-Bus、GTK 组件、OMEMO 加密库等）的部署，后续随系统 apt upgrade 获得安全更新。这是本指南推荐的主线方案。

4.2 安装命令与实测回显

sudo apt update
sudo apt install -y libervia-backend libervia-cli

apt install 实测回显（全新安装，节选）：

Reading package lists...
Building dependency tree...
Reading state information...
The following NEW packages will be installed:
  adwaita-icon-theme at-spi2-common at-spi2-core bzip2 ca-certificates dbus
  dbus-bin dbus-daemon dbus-session-bus-common dbus-system-bus-common dbus-x11
  dconf-gsettings-backend dconf-service file fontconfig fontconfig-config
  fonts-dejavu-core gir1.2-glib-2.0 gsettings-desktop-schemas
  gtk-update-icon-cache hicolor-icon-theme krb5-locales libapparmor1
  libatk-bridge2.0-0 libatk1.0-0 libatspi2.0-0 libavahi-client3
  libavahi-common-data libavahi-common3 libbrotli1 libbsd0 libcairo-gobject2
  libcairo2 libcolord2 libcups2 libdatrie1 libdbus-1-3 libdconf1 libdeflate0
  libepoxy0 libervia-backend libervia-cli libervia-templates libexpat1
  libfontconfig1 libfreetype6 libfribidi0 libgdbm-compat4 libgdbm6
  libgdk-pixbuf-2.0-0 libgdk-pixbuf2.0-bin libgdk-pixbuf2.0-common
  libgirepository-1.0-1 libglib2.0-0 libglib2.0-data libgomp1 libgpm2
  libgraphite2-3 libgssapi-krb5-2 libgtk-3-0 libgtk-3-bin libgtk-3-common
  libharfbuzz0b libicu72 libimagequant0 libjbig0 libjpeg62-turbo libk5crypto3
  libkeyutils1 libkrb5-3 libkrb5support0 liblcms2-2 liblerc4 libmagic-mgc
  libmagic1 libminiupnpc17 libncursesw6 libnsl2 libopenjp2-7 libpango-1.0-0
  libpangocairo-1.0-0 libpangoft2-1.0-0 libperl5.36 libpixman-1-0 libpng16-16
  libproc2-0 libprotobuf32 libpython3-stdlib libpython3.11-minimal
  libpython3.11-stdlib libraqm0 libreadline8 librsvg2-2 librsvg2-common
  libsodium23 libsqlite3-0 libssl3 libthai-data libthai0 libtiff6
  libtirpc-common libtirpc3 libwayland-client0 libwayland-cursor0
  libwayland-egl1 libwebp7 libwebpdemux2 libwebpmux3 libx11-6 libx11-data
  libxau6 libxcb-render0 libxcb-shm0 libxcb1 libxcomposite1 libxcursor1
  libxdamage1 libxdmcp6 libxeddsa2 libxext6 libxfixes3 libxi6 libxinerama1
  libxkbcommon0 libxml2 libxrandr2 libxrender1 libxslt1.1 libxtst6 libyaml-0-2
  mailcap media-types mime-support netbase openssl perl perl-modules-5.36
  procps psmisc python-babel-localedata python-tinycss2-common python3
  python3-aiosqlite python3-alembic python3-attr python3-automat python3-babel
  python3-bcrypt python3-bs4 python3-cairocffi python3-cairosvg
  python3-certifi python3-cffi python3-cffi-backend python3-chardet
  python3-charset-normalizer python3-click python3-colorama python3-constantly
  python3-cryptography python3-cssselect2 python3-dateutil python3-dbus
  python3-defusedxml python3-doubleratchet python3-elementpath
  python3-feedparser python3-gi python3-greenlet python3-hamcrest
  python3-html2text python3-html5lib python3-hyperlink python3-idna
  python3-incremental python3-jinja2 python3-lxml python3-mako
  python3-markdown python3-markupsafe python3-minimal python3-miniupnpc
  python3-mutagen python3-nacl python3-netifaces python3-oldmemo
  python3-olefile python3-omemo python3-openssl python3-pil
  ……（中段为其余 python3-* 依赖与字体、图标组件，篇幅所限节选）
0 upgraded, 234 newly installed, 0 to remove and 1 not upgraded.
Need to get 84.2 MB of archives.
After this operation, 381 MB of additional disk space will be used.
Get:1 http://deb.debian.org/debian bookworm/main amd64 libervia-backend all 0.9.0~hg3993-4+deb12u1 [592 kB]
Get:2 http://deb.debian.org/debian bookworm/main amd64 libervia-cli all 0.9.0~hg3993-4+deb12u1 [109 kB]
……（各依赖包依次下载，节选）
Unpacking libervia-backend (0.9.0~hg3993-4+deb12u1) ...
Unpacking libervia-cli (0.9.0~hg3993-4+deb12u1) ...
Unpacking libervia-templates (0.8.0+hg354.cac1a96f3df8+dfsg-1) ...
……（各依赖包依次 Unpacking，节选）
Setting up python3-cairocffi (1.4.0-1) ...
Setting up python3-cairosvg (2.5.2-1.1+deb12u1) ...
Setting up libervia-backend (0.9.0~hg3993-4+deb12u1) ...
Setting up libervia-cli (0.9.0~hg3993-4+deb12u1) ...
Setting up libervia-templates (0.8.0+hg354.cac1a96f3df8+dfsg-1) ...
Processing triggers for libc-bin (2.36-9+deb12u14) ...
Processing triggers for ca-certificates (20250419~deb12u2) ...
Updating certificates in /etc/ssl/certs...
0 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

要点：全新安装共引入 234 个包（84.2 MB 下载、381 MB 磁盘占用），其中 python3-omemo、python3-oldmemo、python3-doubleratchet、python3-xeddsa 等是 OMEMO 端到端加密的依赖，dbus 全家桶是前后端桥接的依赖。

4.3 安装结果验证

查看二进制落位与包版本：

which libervia-backend libervia-cli libervia-tui
dpkg -l | grep libervia

/usr/bin/libervia-backend
/usr/bin/libervia-cli
/usr/bin/libervia-tui
ii  libervia-backend    0.9.0~hg3993-4+deb12u1           all  Libervia XMPP-based communication and sharing tool (core)
ii  libervia-cli        0.9.0~hg3993-4+deb12u1           all  Libervia XMPP-based communication and sharing tool (command-line interface)
ii  libervia-templates  0.8.0+hg354.cac1a96f3df8+dfsg-1  all  collection of templates for Libervia
ii  libervia-tui        0.9.0~hg3993-4+deb12u1           all  Libervia XMPP-based communication and sharing tool (console interface)

查看版本与后端子命令（实测回显逐行照抄）：

libervia-cli --version
libervia-backend --version

Libervia CLI 0.9.0a0 Copyright (C) 2009-2021 Jérôme Poisson, Adrien Cossa
usage: libervia-backend [-h] {background,bg,foreground,fg,debug,dbg,stop,status}

⚠️ 注意：libervia-backend 不响应 --version，其参数表只有运行方式子命令 {background,bg,foreground,fg,debug,dbg,stop,status}——版本信息从 libervia-cli --version 或 dpkg -l 获取。

4.4 包内文件布局

dpkg -L libervia-backend | grep -E '^/usr/bin|^/usr/share/dbus|^/usr/share/man'

/usr/bin/libervia-backend
/usr/share/dbus-1/services/org.libervia.Libervia.service
/usr/share/man/man1/libervia-backend.1.gz

命令行前端的 man 手册与二进制在 cli 包内：

dpkg -L libervia-cli | grep -E '^/usr/bin|^/usr/share/man'

/usr/bin/libervia-cli
/usr/share/man/man1/libervia-cli.1.gz

/usr/share/dbus-1/services/org.libervia.Libervia.service 是 D-Bus 激活文件：任何前端调用后端时，会话总线会按该文件自动拉起后端进程；
后端程序代码位于 /usr/share/libervia/（Python 模块名仍是历史名 sat，属正常现象）；
发行包不含 systemd 服务单元：dpkg -L libervia-backend | grep -i systemd 无任何输出，后端的常驻托管需按第八节自行配置。

五、安装方案 B：离线 deb 包安装

5.1 方案说明

适用于目标服务器不能直连外网、但内网有可用的传输通道（跳板机、U 盘、内网软件源）的场景。先在能上网的同架构同版本环境下载 deb 包，再拷贝到目标机安装。

5.2 在联网机下载 deb 包

cd /tmp
apt-get download libervia-backend libervia-cli libervia-tui

实测回显：

Get:1 http://deb.debian.org/debian bookworm/main amd64 libervia-backend all 0.9.0~hg3993-4+deb12u1 [592 kB]
Get:2 http://deb.debian.org/debian bookworm/main amd64 libervia-cli all 0.9.0~hg3993-4+deb12u1 [109 kB]
Get:3 http://deb.debian.org/debian bookworm/main amd64 libervia-tui all 0.9.0~hg3993-4+deb12u1 [58.2 kB]
Fetched 773 kB in 2s (482 kB/s)

确认产物：

ls -lh libervia*.deb

-rw-r--r-- 1 root root 592K Dec  2  2023 libervia-backend_0.9.0~hg3993-4+deb12u1_all.deb
-rw-r--r-- 1 root root 107K Dec  2  2023 libervia-cli_0.9.0~hg3993-4+deb12u1_all.deb
-rw-r--r-- 1 root root  57K Dec  2  2023 libervia-tui_0.9.0~hg3993-4+deb12u1_all.deb

5.3 拷贝到目标机并安装

sudo apt install -y ./libervia-backend_0.9.0~hg3993-4+deb12u1_all.deb \
                    ./libervia-cli_0.9.0~hg3993-4+deb12u1_all.deb \
                    ./libervia-tui_0.9.0~hg3993-4+deb12u1_all.deb

安装后验证：

dpkg -l | grep libervia | awk '{print $2, $3}'

libervia-backend 0.9.0~hg3993-4+deb12u1
libervia-cli 0.9.0~hg3993-4+deb12u1
libervia-templates 0.8.0+hg354.cac1a96f3df8+dfsg-1
libervia-tui 0.9.0~hg3993-4+deb12u1

⚠️ 限制说明：apt-get download 只下载 Libervia 自身的 3 个包（共 773 kB），不含 234 个依赖包。目标机若完全没有依赖，apt install ./xxx.deb 仍会尝试从源补齐依赖——完全离线的环境需先在联网机执行 apt-get install --download-only 整包下载依赖后统一拷贝。

六、方案对比与选择建议

维度	方案 A：在线仓库安装	方案 B：离线 deb 包安装
依赖处理	自动补齐全部 234 个依赖	仅自带 3 个包，依赖需目标机可补齐
适用场景	可直连 deb.debian.org 的服务器	内网隔离、经跳板机/U 盘投放
升级方式	`apt upgrade` 随仓库更新	需重新下载新 deb 包
推荐度	推荐主线	特定场景备用

另说明源码安装路线：官方源码托管于 repos.goffi.org（Mercurial 版本库），上游最新正式 tag 为 v0.8.0，0.9.0 线以版本库快照形态存在，需要 Mercurial 工具链与手工依赖管理。对 Debian 12 用户而言发行包已提供同版本产物，源码路线仅建议参与上游开发时使用。

七、安装后必做：D-Bus 会话总线

Libervia 的前后端通信依赖 D-Bus 会话总线（session bus）。桌面环境登录后天然存在；最小化服务器（无桌面）需要手工启用，这是 Libervia 在服务器上最常见的首个故障点。

7.1 启动系统总线与用户会话

sudo systemctl start dbus
sudo systemctl start user@0.service

user@0.service 是 root 用户（UID 0）的用户级 systemd 管理器，启动后其会话总线套接字位于 /run/user/0/bus。

7.2 声明会话总线地址

export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/0/bus

建议将该行写入 /root/.bashrc（或对应用户的 .bashrc），保证每次登录会话都生效：

echo 'export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/0/bus' >> ~/.bashrc
source ~/.bashrc

7.3 不做这一步的后果（实测报错）

未设置会话总线时执行任何 CLI 命令都会报：

D-Bus is not launched, please see README to see instructions on how to launch it
Can't init bridge

按 7.1/7.2 两步处理后即恢复正常。

八、systemd 托管后端

发行包不含服务单元，推荐自写一个单元实现开机自启与崩溃拉起。

8.1 编写服务单元

创建 /etc/systemd/system/libervia-backend.service：

sudo tee /etc/systemd/system/libervia-backend.service > /dev/null <<'EOF'
[Unit]
Description=Libervia backend daemon
After=network.target dbus.service user@0.service
Wants=user@0.service

[Service]
Type=simple
Environment=DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/0/bus
ExecStart=/usr/bin/libervia-backend fg
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF

设计说明：

ExecStart 用 libervia-backend fg（前台模式），日志直接进 systemd journal；
Environment 内嵌会话总线地址，服务进程不依赖登录 shell 的环境变量；
Wants=user@0.service 确保 root 用户会话总线随服务启动。

8.2 启动与自启

sudo systemctl daemon-reload
sudo systemctl start libervia-backend.service
systemctl is-active libervia-backend.service

active

sudo systemctl enable libervia-backend.service

Created symlink /etc/systemd/system/multi-user.target.wants/libervia-backend.service → /etc/systemd/system/libervia-backend.service.

8.3 状态与日志验证

systemctl status libervia-backend.service --no-pager -n 4

● libervia-backend.service - Libervia backend daemon
     Loaded: loaded (/etc/systemd/system/libervia-backend.service; enabled; preset: enabled)
     Active: active (running) since Mon 2026-10-26 07:26:13 UTC; 3s ago
   Main PID: 21605 (python3)
      Tasks: 2 (limit: 2932)
     Memory: 134.2M
        CPU: 920ms
     CGroup: /system.slice/libervia-backend.service
             └─21605 python3 /usr/bin/libervia-backend fg

Oct 26 07:26:15 srv libervia-backend[21605]: 2026-10-26T07:26:15+0000 importing plugin: Ad-Hoc Commands - D-Bus
Oct 26 07:26:15 srv libervia-backend[21605]: 2026-10-26T07:26:15+0000 plugin Ad-Hoc D-Bus initialization
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
Oct 26 07:26:15 srv libervia-backend[21605]: 2026-10-26T07:26:15+0000 Backend is ready

末行 Backend is ready 即后端就绪标志；xmpp_domain needs to be set in sat.conf 是未做配置文件前的正常提示（见第十二节），不影响按 profile 使用。

8.4 备选：手工前台/后台运行

不打算用 systemd 的场景，可用自带的运行方式子命令：

libervia-backend background   # 后台守护运行
libervia-backend status       # 查看运行状态
libervia-backend stop         # 停止
libervia-backend fg           # 前台运行（Ctrl+C 结束）

status 实测回显（systemd 托管中）：

Libervia is running (pid: 21605)

注意：libervia-backend background 启动后再执行一次会报 Another twistd server is running, PID xxxx——先用 status 判断是否已在运行，避免重复拉起。

九、对接 XMPP 服务器（Prosody 对端）并注册账户

Libervia 自身不是 XMPP 服务器，需要一个对端。本节在一台 Debian 12 服务器上同步部署 Prosody 0.12.3 作为对端（单机自测形态：服务器与 Libervia 同机，域名 srv.lan）。若使用既有 XMPP 服务器，可跳到 9.4 注册账户。

9.1 安装 Prosody

sudo apt install -y prosody
sudo prosodyctl about | head -1

Prosody 0.12.3

9.2 域名解析与服务器配置

单机自测将域名指回本机，在 /etc/hosts 追加：

echo '127.0.1.1 srv.lan' | sudo tee -a /etc/hosts

编辑 /etc/prosody/prosody.cfg.lua：

admins = { "admin@srv.lan" }

在 modules_enabled 列表中确认启用以下模块（去掉行首 -- 注释即可）：

        "mam";         -- 消息归档（历史消息回查必需）
        "pubsub";      -- 发布/订阅（博客、列表等功能数据层）

文件末尾追加虚拟主机段：

VirtualHost "srv.lan"

9.3 证书生成与信任

Prosody 对 c2s 连接要求 TLS。为 srv.lan 生成自签证书并纳入系统信任：

sudo prosodyctl cert generate srv.lan
sudo cp /var/lib/prosody/srv.lan.crt /etc/prosody/certs/
sudo cp /var/lib/prosody/srv.lan.key /etc/prosody/certs/
sudo chown prosody:prosody /etc/prosody/certs/srv.lan.*
sudo cp /var/lib/prosody/srv.lan.crt /usr/local/share/ca-certificates/srv.lan.crt
sudo update-ca-certificates

Updating certificates in /etc/ssl/certs...
1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

启动并确认服务：

sudo systemctl restart prosody
systemctl is-active prosody

active

9.4 注册 XMPP 账户

prosodyctl adduser 交互式输入两次密码（实测记录，输入不回显）：

sudo prosodyctl adduser admin@srv.lan

Enter new password: 
Retype new password:

同样方式注册第二个账户用于收发对测：

sudo prosodyctl adduser user1@srv.lan

9.5 连通性验证

在完成第十节 profile 创建后，可用 CLI 对服务器 JID 做连通探测：

libervia-cli ping -p admin -c srv.lan

PONG (0.02831745147705078 s)

⚠️ ping 目标请使用服务器 JID（如 srv.lan）。对未在线的普通用户 JID（如未连接的 user1@srv.lan）执行 ping 会得到 service-unavailable 错误，这是 XMPP ping 语义的正常行为，并非故障。

十、CLI profile 创建与连接验证

Libervia CLI 通过 profile 管理账户身份：一个 profile 绑定一个 XMPP 账户（JID + 密码），profile 自身另有独立密码用于本地加密存储。

10.1 创建 profile

libervia-cli profile create admin -j admin@srv.lan -p q1w2e3r4

成功时命令静默（退出码 0，仅可能伴随 jinja2 告警行，见 FAQ）。重复创建已存在的 profile 会报：

Profile admin already exists.

创建第二个 profile 用于对测：

libervia-cli profile create user1 -j user1@srv.lan -p q1w2e3r4

10.2 查看 profile 列表与信息

libervia-cli profile list

admin
user1

libervia-cli profile info -p admin

jid: admin@srv.lan
autoconnect (backend): false

10.3 连接 profile

libervia-cli profile connect -p admin --pwd q1w2e3r4 -c

成功时静默退出（退出码 0）。参数说明：-p 指定 profile 名，--pwd 提供 profile 密码，-c（--connect）表示连接前先让后端接入 XMPP 网络。

⚠️ 交互陷阱：若省略 --pwd，CLI 会在终端交互提示输入密码；在非交互环境（脚本、无人值守终端）会因读取不到输入而抛出 termios.error: (25, 'Inappropriate ioctl for device')。脚本场景务必显式带 --pwd。

10.4 连接排障实录

首次连接若报 TLS 相关错误，按以下两步排查（实测案例）：

sslv3 alert handshake failure：对端服务器没有可用证书。执行 9.3 节的证书生成，并确认 /etc/prosody/certs/ 下存在 srv.lan.crt 与 srv.lan.key（prosodyctl cert generate 在部分环境下不会自动把文件放入 certs 目录，需手工复制并修正属主）；
证书身份无法校验（InvalidCertificate）：自签证书未被系统信任。执行 9.3 节的 cp 到 /usr/local/share/ca-certificates/ 并 update-ca-certificates 后重试。

十一、首条消息收发实测

以 admin@srv.lan 向 user1@srv.lan 发送首条消息。message send 的消息正文从 stdin 读入（不接受正文作为位置参数）：

echo '你好，这是 Libervia 0.9.0 的第一条 CLI 消息' | libervia-cli message send -p admin -c user1@srv.lan

发送成功时命令静默退出。由于对端 user1 此刻未在线，消息由服务器侧 MAM（消息归档）留存。用 user1 身份回读归档验证送达：

libervia-cli message mam -p user1 -c -W admin@srv.lan

实测回显（时间戳为服务器时区时刻）：

[06:48] admin> 你好，这是 Libervia 0.9.0 的第一条 CLI 消息

⚠️ 若 message mam 报 service-unavailable，说明对端服务器未启用 MAM 模块——回到 9.2 节确认 modules_enabled 中 "mam" 已启用并 systemctl restart prosody。

十二、配置说明

安装完成后即可按 profile 正常使用，配置文件不是必需项；需要调整行为时按以下路径放置配置：

路径	作用域	说明
`~/.config/libervia/libervia.conf`	当前用户	推荐的用户级配置
`/etc/libervia/libervia.conf`	全局	服务器多用户场景
`/etc/_libervia.conf`	发行版定制	发行包专用覆盖层（0.8.0 起支持）
`~/.config/libervia/sat.conf`	当前用户	旧名，仍兼容

最小配置示例（消除第八节日志中的 xmpp_domain 提示）：

[DEFAULT]
xmpp_domain = srv.lan

重启后端后，journal 日志中不再出现 xmpp_domain needs to be set in sat.conf 提示。配置文件的完整参数（数据目录、bridge、各前端节、TLS 等）见本专栏《Libervia 0.9.0 配置参数详解》。

十三、常见问题（FAQ）

Q1：任何 CLI 命令都报 D-Bus is not launched / Can't init bridge。 按第七节顺序执行：systemctl start dbus → systemctl start user@0.service → export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/0/bus。仅启动系统总线（dbus.service）不够，前端调用的是用户会话总线。

Q2：CLI 输出前有一行 Can't import sat_frontends.jp.output_template plugin, ignoring it: cannot import name 'Markup' from 'jinja2'。 这是 Debian 12 打包的 jinja2 版本与 CLI 输出模板插件的兼容告警，仅提示该插件未加载，所有命令功能不受影响，可忽略。

Q3：profile connect 在脚本中报 termios.error: (25, 'Inappropriate ioctl for device')。 非交互终端无法响应密码输入提示。显式加 --pwd <profile密码> 即可（见 10.3 节）。

Q4：连接时报 sslv3 alert handshake failure 或证书校验失败。 对端服务器证书缺失或不受信任，按 9.3 节生成证书、复制到 certs 目录并纳入系统信任链。

Q5：message mam 报 service-unavailable。 服务器未启用 MAM 消息归档模块。在 /etc/prosody/prosody.cfg.lua 的 modules_enabled 中启用 "mam" 后重启 prosody。

Q6：日志反复出现 xmpp_domain needs to be set in sat.conf. Using "example.net" meanwhile。 未设置全局 XMPP 域名的提示。按第十二节在配置文件 [DEFAULT] 节写入 xmpp_domain 即可消除；不设置时按 profile 里的 JID 域名连接，功能不受影响。

Q7：ping 某个用户 JID 报 service-unavailable。 XMPP ping 对普通用户实体需要对端客户端在线响应。改用服务器 JID（如 srv.lan）探测连通性。

十四、升级与卸载清理

14.1 升级

在线安装方案随系统升级即可获得 0.9.0 线内的安全更新：

sudo apt update && sudo apt upgrade libervia-backend libervia-cli

升级后重启服务单元：

sudo systemctl restart libervia-backend.service

14.2 卸载

sudo apt purge -y libervia-backend libervia-cli libervia-tui libervia-templates
sudo apt autoremove -y

清除用户数据（profile、本地 SQLite 数据库、缓存）：

rm -rf ~/.local/share/libervia ~/.config/libervia ~/.cache/libervia

对端 Prosody 如需一并清理：

sudo apt purge -y prosody
rm -rf /var/lib/prosody

十五、参考链接

Debian Package Tracker（libervia-backend 版本矩阵）：https://tracker.debian.org/pkg/libervia-backend
Libervia 官方主站：https://libervia.org
Libervia 官方文档站：https://libervia.org/documentation
官方源码仓库（Mercurial）：https://repos.goffi.org/libervia
Prosody 官方站：https://prosody.im
本站相关篇目：