Ubuntu 22.04 安装 Prosody IM 13.0.7 指南

Ubuntu 22.04 从零安装 Prosody IM 13.0.7 实战：官方 packages.prosody.im 仓库添加、Lua 5.1→5.4 解释器修正、自签证书与证书归位、systemd 托管、端口验证与管理员账号 XMPP 登录全链路实测，含 7 条排障实录。

Prosody IM即时通信Prosody IM2026/10/21

Ubuntu 22.04 安装 Prosody IM 13.0.7 指南

目标：在一台 Ubuntu 22.04 服务器上从零安装 Prosody IM 13.0.7（官方 packages.prosody.im 仓库主线方案），完成证书签发、管理员账号注册、systemd 服务托管与 XMPP 客户端登录的全链路验证。已在 Ubuntu 22.04.5 LTS（x86_64）实测通过，全部命令与回显均为真实执行记录。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64，GNU/Linux 5.15 内核）；
  • 软件版本：Prosody IM 13.0.7（官方仓库包名 13.0.7-1~jammy2，安装时 dpkg -s prosody 显示 Version: 13.0.7-1~jammy2）；
  • 运行时：Lua 5.4.4（Ubuntu 22.04 jammy 仓库版本）；
  • 示例 XMPP 域名：xmpp.example.com（正文统一以此域演示，实际部署替换为你的真实域名）；
  • 示例管理员账号：admin@xmpp.example.com，密码 q1w2e3r4；
  • 服务端口：5222（客户端 c2s）、5269（服务器互联 s2s）、5280（HTTP/BOSH，可选启用）；
  • 关键路径：配置 /etc/prosody/prosody.cfg.lua、数据 /var/lib/prosody/、日志 /var/log/prosody/、证书目录 /etc/prosody/certs/；
  • 网络前提：服务器可访问 archive.ubuntu.com 与 packages.prosody.im；若从国内访问缓慢，可为 apt 配置代理或使用镜像仓库（本文按可直连环境实录）。

💡 说明：xmpp.example.com 需要有 DNS A 记录指向本服务器 IP 才能被客户端与联邦服务器访问；无 DNS 的测试环境可在服务器 /etc/hosts 中加一行 127.0.0.1 xmpp.example.com 模拟解析，本文实测即采用此方式。

二、前置条件

2.1 系统与权限

  • 一台 Ubuntu 22.04 服务器（物理机/云主机均可），具有 root 或 sudo 权限；
  • 开放防火墙端口：5222/TCP（客户端连接）、5269/TCP（服务器联邦，可选）、5280/TCP（HTTP 绑定，可选）。使用 ufw 的话：
ufw allow 5222/tcp   # 放行客户端 c2s 端口

2.2 基础工具

最小化安装的 Ubuntu 缺少下载与证书工具，先补齐（缺 wget 直接做后面步骤会报错，见第九章 FAQ-1）：

apt-get update && apt-get install -y wget ca-certificates gnupg

实测回显（节选末尾）：

Running hooks in /etc/ca-certificates/update.d...
done.

2.3 域名解析

检查域名是否解析到本机（真实环境应有 A 记录）：

getent hosts xmpp.example.com || echo "127.0.0.1 xmpp.example.com" >> /etc/hosts

实测回显（无 DNS 环境追加 hosts 后）：

127.0.0.1 xmpp.example.com

三、版本选型说明

Ubuntu 22.04 上有两条安装来源，版本差异明显（2026-10-21 实测 apt 索引）：

apt-cache policy prosody

发行版仓库初始索引下回显：

prosody:
  Installed: (none)
  Candidate: 0.11.13-1
  Version table:
     0.11.13-1 500
        500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages

添加官方仓库后（见第四章）再查：

prosody:
  Installed: (none)
  Candidate: 13.0.7-1~jammy2
  Version table:
     13.0.7-1~jammy2 500
        500 http://packages.prosody.im/debian jammy/main amd64 Packages
     0.11.13-1 500
        500 http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages

关键差异：Ubuntu jammy 官方仓库停留在 0.11.13（2020 年代的旧线，Prosody 13 的诸多新能力——内置 invites 邀请注册体系、prosodyctl shell 管理外壳、SMACKS v3 流恢复增强等——均不可用），而官方 packages.prosody.im 仓库与上游同步，jammy 套件直供 13.0.7-1~jammy2。本文主线采用官方仓库方案（B），发行版仓库方案（A）仅作无外网策略下的兜底。

官方仓库同时提供两类包（来源：prosody.im/download/package_repository）：

包名内容适用策略
prosody始终对齐最新稳定版，含跨大版本升级追新，配合 apt-mark hold 控制升级节奏
prosody-13.0锁定 13.0 分支的 nightly 构建，只收 bug 修复求稳，避免自动升级引入大版本变更

四、安装方案 A：Ubuntu 发行版仓库（兜底）

本方案直接使用 Ubuntu 自带仓库，适合无法添加第三方仓库的环境，但版本老（0.11.13），仅作兜底，不推荐生产使用。

apt-get install -y prosody

安装后确认版本：

dpkg -s prosody | grep ^Version

预期回显（该方案下版本为发行版自带）：

Version: 0.11.13-1

⚠️ 注意：0.11.x 与 13.0.x 的配置项与模块生态存在代差（如 13.0 起不再兼容 Lua 5.1、默认启用 invites 模块族）。若从 0.11 升级到 13.0，请先阅读官方版本说明再迁移配置。

五、安装方案 B：官方 packages.prosody.im 仓库（推荐主线）

本方案是官方推荐路径：一条 wget 命令引入官方仓库定义文件（签名公钥内置于该文件，无需 apt-key），随后照常 apt 安装即可获得与上游同步的最新版。

5.1 添加官方仓库

wget https://prosody.im/downloads/repos/$(lsb_release -sc)/prosody.sources -O /etc/apt/sources.list.d/prosody.sources

实测回显：

--2026-10-21 10:05:42--  https://prosody.im/downloads/repos/jammy/prosody.sources
Resolving prosody.im (prosody.im)... 176.126.242.74, 2a00:1098:3a0::1
Connecting to prosody.im (prosody.im)|176.126.242.74|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 6678 (6.5K) [application/octet-stream]
Saving to: '/etc/apt/sources.list.d/prosody.sources'

     0K ......                                                100% 7.77G=0s

查看仓库定义文件头部的关键信息（完整文件内嵌 Prosody 官方签名公钥）：

head -5 /etc/apt/sources.list.d/prosody.sources

实测回显：

Suites: jammy
Types: deb
Architectures: amd64 armhf arm64
Components: main
Uris: http://packages.prosody.im/debian

💡 技术拓展：prosody.sources 是 Debian 新版 deb822 格式（区别于旧的 deb http://... main 单行格式）。密钥管理方式对比——

方式原理现状
apt-key add（旧）密钥装入全局信任库Debian 11+/Ubuntu 22.04 已弃用，apt 会告警
signed-by 独立密钥文件每仓库独立密钥，互不放大信任面当前推荐
deb822 内嵌 Signed-By密钥直接写进 .sources 文件官方仓库采用，一份文件即全部

官方自 2025-08-04 起切换到新签名密钥，prosody.sources 文件已内嵌新钥；旧系统若沿用旧 key 会在 apt update 时报 NO_PUBKEY F7A37EB33D0B25D7（解决方法见 FAQ-3）。

5.2 刷新索引并确认版本

apt-get update

实测回显（节选 prosody 仓库相关行）：

Get:4 http://packages.prosody.im/debian jammy InRelease [7739 B]
Get:6 http://packages.prosody.im/debian jammy/main armhf Packages [1823 B]
Get:7 http://packages.prosody.im/debian jammy/main arm64 Packages [1830 B]
Get:8 http://packages.prosody.im/debian jammy/main amd64 Packages [1832 B]

apt-cache policy prosody | head -5

实测回显：

prosody:
  Installed: (none)
  Candidate: 13.0.7-1~jammy2
  Version table:
     13.0.7-1~jammy2 500

5.3 安装

DEBIAN_FRONTEND=noninteractive apt-get install -y prosody

实测回显（节选依赖设置末尾部分）：

Setting up liblua5.1-0-dev:amd64 (5.1.5-8.1build4) ...
Setting up libtool (2.4.6-15build2) ...
Setting up luarocks (3.8.0+dfsg1-1) ...
Setting up gcc (4:11.2.0-1ubuntu1~22.04.3) ...
Processing triggers for libc-bin (2.35-0ubuntu3.14) ...

确认包版本：

dpkg -s prosody | grep ^Version

实测回显：

Version: 13.0.7-1~jammy2

⚠️ 注意：依赖链中出现的 luarocks/gcc/liblua5.1-0-dev 是官方包 Recommends 拉入的模块构建工具链（便于后续编译安装社区模块）。若想最小化安装，可加 --no-install-recommends，代价是 prosodyctl plugins install 安装社区模块时需要手动补齐构建工具。

六、安装后必做：修正默认 Lua 解释器

这是 Ubuntu 22.04 上安装 Prosody 13 的第一个必踩坑。安装完成后直接运行 prosody --version 或启动服务会报错：

prosody --version

实测回显：

Prosody is no longer compatible with Lua 5.1
See https://prosody.im/doc/depends#lua for more information

6.1 定位

/usr/bin/prosody 的首行 shebang 是 #!/usr/bin/env lua，即使用系统默认 lua 命令。查看系统内 Lua 解释器候选与优先级：

update-alternatives --display lua-interpreter | head -8

实测回显：

lua-interpreter - auto mode
  link best version is /usr/bin/lua5.1
  link currently points to /usr/bin/lua5.1
  link lua-interpreter is /usr/bin/lua
  slave lua-manual is /usr/share/man/man1/lua.1.gz
/usr/bin/lua5.1 - priority 110
  slave lua-manual: /usr/share/man/man1/lua5.1.1.gz
/usr/bin/lua5.4 - priority 20

根因：apt-get install prosody 会按包依赖装入 lua5.4（Depends: lua5.4），但随 luarocks 引入的 lua5.1 在 alternatives 机制中优先级更高（110 对 20），auto 模式下 /usr/bin/lua 被解析到 lua5.1，而 Prosody 13.x 启动脚本检测到 _VERSION < "Lua 5.2" 即退出。

6.2 修复：把默认 Lua 切到 5.4

update-alternatives --set lua-interpreter /usr/bin/lua5.4

实测回显：

update-alternatives: using /usr/bin/lua5.4 to provide /usr/bin/lua (lua-interpreter) in manual mode
update-alternatives: warning: skip creation of /usr/share/man/man1/lua.1.gz because associated file /usr/share/man/man1/lua5.4.1.gz (of link group lua-interpreter) doesn't exist

验证（man 页警告可忽略，不影响运行）：

lua -v

实测回显：

Lua 5.4.4  Copyright (C) 1994-2022 Lua.org, PUC-Rio

再次确认 prosody 以 Lua 5.4 正常加载（用 prosodyctl about，root 直跑 prosody 会触发官方 root 保护而拒绝执行）：

prosodyctl about | head -2

实测回显：

Prosody 13.0.7
Lua version:                    Lua 5.4

⚠️ 注意：以 root 运行 prosody --version 会得到官方保护告警并以退出码 1 结束（实测回显如下），这是官方防呆设计，不代表安装失败；版本确认一律用 prosodyctl about 或 dpkg -s prosody。

Danger, Will Robinson! Prosody doesn't need to be run as root, so don't do it!
For more information on running Prosody as root, see https://prosody.im/doc/root

七、服务托管与首次启动

7.1 systemd 服务管理

Prosody 安装后注册为 systemd 服务（unit：prosody.service，开机自启默认 enabled）：

systemctl enable prosody

实测回显（已处于自启状态时）：

Synchronizing state of prosody.service with SysV service script with /lib/systemd/systemd-sysv-install.

启动服务：

systemctl start prosody
systemctl is-active prosody

实测回显：

active

日常管理命令（逐条）：

systemctl status prosody      # 查看服务状态与最近日志
systemctl restart prosody     # 重启（加载全新进程）
systemctl reload prosody      # 平滑重载配置（对支持热加载的配置项生效）
journalctl -u prosody -n 20   # 查看 systemd 视角最近 20 行日志

7.2 监听端口验证

ss -ltnp | grep -E "5222|5269"

实测回显：

LISTEN 0      128          0.0.0.0:5222       0.0.0.0:*    users:(("lua",pid=4272,fd=16))
LISTEN 0      128          0.0.0.0:5269       0.0.0.0:*    users:(("lua",pid=4272,fd=14))
LISTEN 0      128             [::]:5222          [::]:*    users:(("lua",pid=4272,fd=15))
LISTEN 0      128             [::]:5269          [::]:*    users:(("lua",pid=4272,fd=13))

💡 说明：5222（c2s 客户端接入）与 5269（s2s 服务器互联）默认开启；5280（HTTP 绑定）默认未监听，启用方法见配置篇。进程名显示为 lua 是因为 Prosody 以 Lua 解释器运行，属正常现象。

八、域名、证书与管理员账号

8.1 配置示例域名

编辑 /etc/prosody/prosody.cfg.lua（Prosody 的唯一主配置文件，语法为 Lua），做两处修改：

  1. 将 admins = { } 改为（第 25 行附近）：
admins = { "admin@xmpp.example.com" }
  1. 将文件末尾的 VirtualHost "localhost" 改为：
VirtualHost "xmpp.example.com"

修改后核对生效行：

grep -nE "^admins|^VirtualHost" /etc/prosody/prosody.cfg.lua

实测回显：

25:admins = { "admin@xmpp.example.com" }
216:VirtualHost "xmpp.example.com"

8.2 生成自签证书

内网或无 Let's Encrypt 条件的环境，用内置命令为域名签发一年期自签证书：

prosodyctl cert generate xmpp.example.com

实测回显（交互式，直接回车取默认值）：

Choose key size (2048): Key written to /var/lib/prosody/xmpp.example.com.key
Please provide details to include in the certificate config file.
Leave the field empty to use the default value or '.' to exclude the field.
countryName (GB): localityName (The Internet): organizationName (Your Organisation): organizationalUnitName (XMPP Department): commonName (xmpp.example.com): emailAddress (xmpp@xmpp.example.com):
Config written to /var/lib/prosody/xmpp.example.com.cnf
Certificate written to /var/lib/prosody/xmpp.example.com.crt

💡 技术拓展：生产服务器证书来源对比——

来源原理适用
自签（prosodyctl cert generate）本地自签发，客户端需信任或忽略校验内网、测试
Let's Encrypt（certbot）ACME 域名验证自动签发，90 天滚动续期公网域名，标准选择
商业 CA 证书购买签发，有效期长有合规要求的企业

自签证书仅服务端 TLS 可用（联邦 s2s 场景对端会校验失败）；公网生产建议 certbot 签发后将证书路径配置到 Prosody（见配置篇）。

8.3 证书归位与健康检查

prosodyctl check 的证书检查只扫描 /etc/prosody/certs/ 目录，而 cert generate 把证书写在 /var/lib/prosody/，需复制归位：

cp /var/lib/prosody/xmpp.example.com.crt /var/lib/prosody/xmpp.example.com.key /etc/prosody/certs/
chown root:prosody /etc/prosody/certs/xmpp.example.com.*
chmod 640 /etc/prosody/certs/xmpp.example.com.*

复制后必须重启服务，新证书才会被 TLS 层加载（否则 TLS 握手报 no shared cipher，见 FAQ-2）：

systemctl restart prosody
systemctl is-active prosody

实测回显：

active

运行官方健康检查：

prosodyctl check

实测回显（节选，省略 DNS 建议之前的配置检查段）：

Checking DNS for host xmpp.example.com...
    Host xmpp.example.com does not seem to resolve to this server (IPv4/IPv6)

Checking certificates...
Checking certificate for xmpp.example.com
  Certificate: /etc/prosody/certs/xmpp.example.com.crt

All checks passed, congratulations!

💡 说明：DNS 检查项提示域名未解析到本机，是因为本文实验环境用 /etc/hosts 模拟（prosodyctl check 走 DNS 解析对比公网记录）；公网服务器配好 A 记录后该项自然通过。证书项已由警告（FAQ-2 场景）变为明确路径加载。

8.4 注册管理员账号

prosodyctl register admin xmpp.example.com q1w2e3r4

实测回显：

usermanager         info        User account created: admin@xmpp.example.com

8.5 端到端登录验证

用任一标准 XMPP 客户端（Gajim、Conversations、Dino 等）以 admin@xmpp.example.com / q1w2e3r4 登录 xmpp.example.com（5222 端口）。本文用 Python 标准库脚本模拟客户端完成 STARTTLS→SASL→资源绑定→服务发现全链路，实测关键回显：

[tls] 协议=TLSv1.3 密码套件=TLS_AES_256_GCM_SHA384
[auth] << <success xmlns='urn:ietf:params:xml:ns:xmpp-sasl'/>
[bind] << <iq type='result' id='b1'><bind xmlns='urn:ietf:params:xml:ns:xmpp-bind'><jid>admin@xmpp.example.com/pytest</jid></bind></iq>
[done] 登录+bind+disco 全链路完成

其中 disco#info 响应含服务器身份宣告（节选）：

<identity type='im' name='Prosody' category='server'/>

登录、TLSv1.3 加密、SASL 认证、资源绑定全部通过，部署验证完成。

九、常见问题（FAQ）

FAQ-1：wget: command not found

现象：执行仓库添加命令报 bash: line 1: wget: command not found。

定位：Ubuntu 22.04 最小安装不带 wget。

解决：

apt-get update && apt-get install -y wget ca-certificates

FAQ-2：TLS 握手失败 no shared cipher

现象：客户端连 5222 报握手失败，服务日志 /var/log/prosody/prosody.log 出现 Client disconnected: no shared cipher。

定位：证书复制到 /etc/prosody/certs/ 后未重启服务，TLS 层仍持有旧的证书上下文；或 prosodyctl check 报 No 'certificate' found for xmpp.example.com 时放任未处理。

解决：按 8.3 节把 crt/key 复制进 certs 目录并 chown root:prosody、chmod 640，然后 systemctl restart prosody。重启后日志出现 xmpp.example.com:tls info Certificates loaded，握手恢复 TLSv1.3。

FAQ-3：apt update 报 NO_PUBKEY F7A37EB33D0B25D7

现象：

W: An error occurred during the signature verification. The repository is not updated and the previous index files will be used. GPG error: http://packages.prosody.im/debian jammy InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY F7A37EB33D0B25D7

定位：官方 2025-08-04 切换包签名密钥，旧系统沿用的旧 key 不再受信（来源：prosody.im/download/package_repository）。

解决：删除旧的 prosody source 条目与旧 key，重新下载内置新钥的 prosody.sources（官方推荐做法）：

rm -f /etc/apt/sources.list.d/prosody.list
wget https://prosody.im/downloads/repos/$(lsb_release -sc)/prosody.sources -O /etc/apt/sources.list.d/prosody.sources
apt-get update

FAQ-4：启动报 Prosody is no longer compatible with Lua 5.1

见第六章：update-alternatives --set lua-interpreter /usr/bin/lua5.4 切换默认解释器后重启服务即可。补充说明：该坑源于 jammy 的 alternatives 打包优先级（lua5.1 为 110、lua5.4 仅 20），未来 Ubuntu 版本可能修正；升级 Prosody 前先跑 lua -v 核对版本可提前规避。

FAQ-5：prosodyctl cert generate 提示 .cnf exists, do you want to replace it? 后卡住

现象：重复生成证书时交互询问 y/n，脚本化调用（stdin 关闭）会中断退出，证书未生成。

解决：删除旧的三件套后重新生成：

rm -f /var/lib/prosody/xmpp.example.com.crt /var/lib/prosody/xmpp.example.com.key /var/lib/prosody/xmpp.example.com.cnf
prosodyctl cert generate xmpp.example.com

FAQ-6：老客户端（sendxmpp 等）登录失败

现象：Perl 系老客户端 sendxmpp 登录时输出大量 Use of uninitialized value $sid 警告并以 Error 'AuthSend' 失败。

定位：sendxmpp 依赖的 Net::XMPP 库年代久远，对 Prosody 13 默认要求的 STARTTLS（流特性中宣告 <required/>）与现代 SCRAM 认证兼容性差。

解决：改用现代客户端（Gajim/Conversations/Dino）或脚本化场景用 Python（slixmpp/aioxmpp）或标准库自实现流；服务端不建议为兼容老客户端而关闭 TLS 强制（c2s_require_encryption = false），安全代价过高。

FAQ-7：卸载时报 userdel: user prosody is currently used by process

现象：服务运行中直接 apt-get remove --purge prosody，末尾出现：

Purging configuration files for prosody (13.0.7-1~jammy2) ...
userdel: user prosody is currently used by process 4769
groupdel: cannot remove the primary group of user 'prosody'
dpkg: warning: while removing prosody, directory '/var/lib/prosody' not empty so not removed
dpkg: warning: while removing prosody, directory '/etc/prosody/certs' not empty so not removed

定位：卸载时服务进程仍持有 prosody 用户与数据目录。

解决：先停服务再卸载（见第十章标准卸载流程）；残留目录可手动确认后删除。

十、升级、多版本与卸载

10.1 升级

官方仓库方案下升级随系统更新完成：

apt-get update && apt-get upgrade prosody

跨大版本（如 0.12→13.0）前务必阅读官方发布说明（prosody.im/doc/release），13.0 起有配置项与模块变更（如不再兼容 Lua 5.1）。

10.2 锁定版本（防止自动升级引入大版本变更）

官方对 prosody 包「始终跟随最新稳定版」的提示性建议（来源：prosody.im/download/package_repository）：

apt-mark hold prosody     # 锁定
apt-mark showhold         # 查看锁定列表
apt-mark unhold prosody   # 解锁

实测回显：

prosody set on hold.
prosody
Canceled hold on prosody.

若希望只收 13.0 分支的修复而完全规避跨大版本自动升级，可改装分支包 prosody-13.0（每夜构建、无破坏性变更）。

10.3 已安装版本与文件清单核对

apt-cache madison prosody

实测回显：

   prosody | 13.0.7-1~jammy2 | http://packages.prosody.im/debian jammy/main amd64 Packages
   prosody |  0.11.13-1 | http://archive.ubuntu.com/ubuntu jammy/universe amd64 Packages

dpkg -L prosody | wc -l

实测回显：

745

10.4 卸载与清理

标准卸载流程（先停服务，避免 FAQ-7）：

systemctl stop prosody
apt-get remove --purge -y prosody
apt-get autoremove -y

残留数据与配置目录（purge 不删除非空目录，卸载后按需清理）：

rm -rf /var/lib/prosody /var/log/prosody /etc/prosody
rm -f /etc/apt/sources.list.d/prosody.sources

⚠️ 注意：rm -rf /var/lib/prosody 会删除全部账号数据与消息归档，生产环境执行前必须先备份。

十一、参考链接