Prosody IM 13.0.7 配置参数详解

逐节讲透 Prosody IM 13.0.7 主配置文件 prosody.cfg.lua 的核心参数：admins/VirtualHost/Component/认证与存储后端/模块管理/连接加密/限速/证书/日志，每项配修改、重启、验证的实测闭环，附生产配置模板与 6 条排障实录。

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

Prosody IM 13.0.7 配置参数详解

目标：逐节讲透 Prosody IM 13.0.7 唯一主配置文件 /etc/prosody/prosody.cfg.lua 的核心参数，每个关键参数组都配「修改 → 重载/重启 → 验证生效」的实测闭环，并给出可直接套用的生产配置模板。已在 Ubuntu 22.04 + Prosody 13.0.7（安装方法见 《Ubuntu 22.04 安装 Prosody IM 13.0.7 指南》）实测通过，全部命令与回显均为真实执行记录。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）；
  • 软件版本：Prosody IM 13.0.7（包版本 13.0.7-1~jammy2）；
  • 配置文件：/etc/prosody/prosody.cfg.lua（安装包默认共 254 行，含注释）；
  • 示例 XMPP 域名：xmpp.example.com，MUC 组件域名：chat.example.com；
  • 示例管理员：admin@xmpp.example.com，密码 q1w2e3r4；
  • 相关路径：数据 /var/lib/prosody/、日志 /var/log/prosody/、证书 /etc/prosody/certs/、模块目录 /usr/lib/prosody/modules/。

二、前置条件

  • 已按部署篇完成 Prosody 13.0.7 安装并修正 Lua 解释器（lua -v 应显示 5.4）；
  • 已有可用的 VirtualHost 域名与证书（自签即可跑通本文全部实验）；
  • 建议动手前备份配置：cp /etc/prosody/prosody.cfg.lua /etc/prosody/prosody.cfg.lua.orig。

三、参数查看与修改方式

3.1 配置文件形态

Prosody 的主配置就是一个 Lua 脚本——全局参数写在文件顶部，VirtualHost/Component 段落在文件尾部，段内缩进的参数只作用于该段。有效参数行提取（默认安装，去掉全部注释与空行后）：

grep -vE "^\s*--" /etc/prosody/prosody.cfg.lua | grep -vE "^\s*$" | head -60

实测回显（节选）：

admins = { }
modules_enabled = {
                "disco"; -- Service discovery
                "roster"; -- Allow users to have a roster. Recommended ;)
                "saslauth"; -- Authentication for clients and servers. Recommended if you want to log in.
                "tls"; -- Add support for secure TLS on c2s/s2s connections
                "blocklist"; -- Allow users to block communications with other users
                "bookmarks"; -- Synchronise the list of open rooms between clients
                "carbons"; -- Keep multiple online clients in sync
                "dialback"; -- Support for verifying remote servers using DNS
                "limits"; -- Enable bandwidth limiting for XMPP connections
                "pep"; -- Allow users to store public and private data in their account
                "private"; -- Legacy account storage mechanism (XEP-0049)
                "smacks"; -- Stream management and resumption (XEP-0198)
                "vcard4"; -- User profiles (stored in PEP)
                "vcard_legacy"; -- Conversion between legacy vCard and PEP Avatar, vcard
                "account_activity"; -- Record time when an account was last used
                "cloud_notify"; -- Push notifications for mobile devices
                "csi_simple"; -- Simple but effective traffic optimizations for mobile devices
                "invites"; -- Create and manage invites
                "invites_adhoc"; -- Allow admins/users to create invitations via their client
                "invites_register"; -- Allows invited users to create accounts
                "ping"; -- Replies to XMPP pings with pongs
                "register"; -- Allow users to register on this server using a client and change passwords
                "time"; -- Let others know the time here on this server
                "uptime"; -- Report how long server has been running
                "version"; -- Replies to server version requests
                "admin_adhoc"; -- Allows administration via an XMPP client that supports ad-hoc commands
                "admin_shell"; -- Allow secure administration via 'prosodyctl shell'
}
modules_disabled = {
}
s2s_secure_auth = true
limits = {
        c2s = {
                rate = "10kb/s";
        };
        s2sin = {
                rate = "30kb/s";
        };
}
pidfile = "/var/run/prosody/prosody.pid"
authentication = "internal_hashed"
archive_expires_after = "1w" -- Remove archived messages after 1 week
log = {
        info = "/var/log/prosody/prosody.log"; -- Change 'info' to 'debug' for verbose logging
        error = "/var/log/prosody/prosody.err";
}
certificates = "certs"
VirtualHost "localhost"

💡 说明：配置语法为 Lua——字符串用双引号、列表用花括号、行尾分号可省（官方风格保留）。modules_enabled 内每一项即 /usr/lib/prosody/modules/ 下的一个模块文件（mod_ 前缀在配置中省略）。

3.2 修改后的两种生效方式：reload 与 restart

规则：改配置后，能 reload 就 reload（不中断在线会话），结构性变更（增删模块、改 VirtualHost/Component、换存储）必须 restart。

systemctl reload prosody    # 平滑重载（SIGHUP），进程 PID 不变
systemctl restart prosody   # 完整重启，进程 PID 变化

实测验证 reload 不换进程且日志级别立即生效（把 log.info 改为 log.debug 后 reload）：

P1=$(systemctl show prosody -p MainPID --value); echo "reload 前 PID=$P1"
sed -i 's/info = "\/var\/log\/prosody\/prosody.log"/debug = "\/var\/log\/prosody\/prosody.log"/' /etc/prosody/prosody.cfg.lua
systemctl reload prosody && sleep 2
P2=$(systemctl show prosody -p MainPID --value); echo "reload 后 PID=$P2"

实测回显：

reload 前 PID=5663
reload 后 PID=5663

日志文件立即出现 debug 级输出（级别热载生效）：

Oct 21 10:13:53 certmanager     debug   Automatically locating certs for host xmpp.example.com
Oct 21 10:13:53 certmanager     debug   Using cert "/etc/prosody/certs/xmpp.example.com.crt" from index for host "xmpp.example.com"

3.3 改配置前先做语法检查

配置是 Lua 脚本，语法错误会让服务无法启动。官方 prosodyctl check 可在改动后先行校验（故意写坏实验，见第七章 FAQ-1）：

prosodyctl check

语法正确时输出以如下结尾（实测）：

All checks passed, congratulations!

四、参数总览

全局级核心参数速查（默认值为 13.0.7 安装默认配置实测值）：

参数默认值作用
admins{ }服务器管理员 JID 列表，可执行 ad-hoc 管理、shell 管理
modules_enabled27 项基础集全局启用的模块列表（各 VirtualHost 可再叠加）
modules_disabled{ }显式禁用的模块（优先级高于 enabled）
authentication"internal_hashed"认证后端（见 5.4）
storage（未设=internal）存储后端（见 5.5）
s2s_secure_authtrue服务器互联要求对端证书强认证
limitsc2s 10kb/s、s2sin 30kb/s各连接方向带宽限速
pidfile/var/run/prosody/prosody.pid主进程 PID 文件
archive_expires_after"1w"消息归档保留期
loginfo/error 双文件日志输出级别与去向
certificates"certs"证书目录（相对 /etc/prosody/）
c2s_require_encryptiontrue（默认内置）客户端连接强制 STARTTLS
http_ports/https_ports{5280}/{5281}HTTP/HTTPS 绑定端口（启用 http 模块后生效）
http_interfaces{"127.0.0.1","::1"}HTTP 监听接口（默认仅本机）

段级结构：文件尾部按域名划分作用域——

VirtualHost "xmpp.example.com"      -- 每个虚拟主机一段
Component "chat.example.com" "muc"  -- 每个外部服务组件一段

五、核心参数分类详解

5.1 管理员列表 admins

admins 是拥有服务级管理权限的账号（XMPP 客户端 ad-hoc 命令、部分 shell 命令以 JID 鉴权）。JID 必须写成「用户@域名」全称，且该账号须真实存在于对应 VirtualHost：

admins = { "admin@xmpp.example.com" }

修改后 restart 生效。验证方式：以该账号登录后，支持 ad-hoc 的客户端能看到服务管理命令（如「Send announcement to all users」）。

5.2 VirtualHost 虚拟主机段

一个 Prosody 实例可同时服务多个 XMPP 域，每个域一个 VirtualHost 段。本文实验环境的主段（域名+组件发现配置）：

VirtualHost "xmpp.example.com"
        disco_items = { { "chat.example.com" } };

⚠️ 注意：disco_items 的正确语法是子数组形式 { { "组件域名" } }，写成字符串数组 { "chat.example.com" } 会被 prosodyctl check 判定 invalid 并连带组件无法被发现（排障实录见 FAQ-3）。

验证配置段生效：

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

实测回显：

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

5.3 Component 组件段（以 MUC 聊天室为例）

Component 段声明附加服务，「组件域名」「组件类型」双参数。在配置末尾添加 MUC（多用户聊天室，XEP-0045）组件：

Component "chat.example.com" "muc"

restart 后确认组件激活：

systemctl restart prosody && sleep 2
grep -i "chat.example.com" /var/log/prosody/prosody.log | tail -2

实测回显：

Oct 21 10:12:09 chat.example.com:tls    info    Certificates loaded

💡 技术拓展：Prosody 常用组件类型一览——

组件类型模块用途
mucmod_muc多用户聊天室（群聊）
pubsubmod_pubsub发布/订阅节点（实时通知、IoT）
http_uploadmod_http_uploadHTTP 文件上传中转
proxy65mod_proxy65文件传输 SOCKS 代理
外部组件mod_component任意第三方程序经 5347 端口以组件协议接入

组件是否可被客户端自动发现有讲究：组件域名是某 VirtualHost 的直接子域（如 chat.xmpp.example.com）时自动关联；平级域名（本文的 chat.example.com）需在 VirtualHost 段内用 disco_items 显式链接（见 5.2）。本文实测采用后者。

5.4 authentication 认证后端

默认 internal_hashed：账号密码以 SCRAM 哈希形式存于内部存储，服务端不存明文。可选项对比：

💡 技术拓展：认证后端选型——

取值原理适用
internal_hashed（默认）SCRAM-SHA-1 哈希存储，支持 SCRAM 机制通用推荐
internal_plain明文存储（便于迁移出密码）仅过渡/迁移期
ldap绑定 LDAP 目录（需 mod_auth_ldap，社区模块）企业统一目录
cyrus对接 SASL 库（Kerberos 等）特殊企业环境

本文默认 internal_hashed，与 13.0 流特性宣告的 SCRAM-SHA-1/PLAIN 机制配合（认证机制实测见部署篇登录验证节）。

5.5 storage 与 sql：存储后端

默认未显式配置即 internal（纯 Lua 文件存储，数据落 /var/lib/prosody/<域名>/）。切换到 SQL 的配置：

storage = "sql"
sql = { driver = "SQLite3", database = "prosody.sqlite3" }

💡 技术拓展：存储后端选型——

后端原理适用
internal（默认）每域名一个目录、每类数据一个文件中小规模、零依赖
sql经 LuaDBI 驱动接 SQLite3/MySQL/PostgreSQL大规模、需外部备份/报表
memory纯内存（重启即失）临时测试

可按数据类型混搭：storage = { accounts = "sql", archive = "internal" }。

实测切换全流程（含两段真实排障）：

① 写入配置后 restart，服务 active 但注册报错（SQLite 驱动缺失）：

xmpp.example.com:storage_sql  error   Please install at least one of LuaDBI and LuaSQLite3. See https://prosody.im/doc/depends

② 安装发行版驱动包后仍然报同样错误：

apt-get install -y lua-dbi-sqlite3

查看包内库文件定位真因：

dpkg -L lua-dbi-sqlite3 | grep "\.so"

实测回显（节选）：

/usr/lib/x86_64-linux-gnu/lua/5.1/dbd/sqlite3.so
/usr/lib/x86_64-linux-gnu/lua/5.2/dbd/sqlite3.so
/usr/lib/x86_64-linux-gnu/lua/5.3/dbd/sqlite3.so

发行版 lua-dbi 只构建到 Lua 5.3，而 Prosody 13 运行于 Lua 5.4——路径不匹配，库存在但不可见。

③ 用 luarocks 为 Lua 5.4 编译安装驱动（需头文件与 sqlite3 开发库）：

apt-get install -y liblua5.4-dev libsqlite3-dev
luarocks --lua-version 5.4 install luadbi-sqlite3

实测回显（节选末尾）：

gcc -shared -o dbd/sqlite3.so dbd/common.o dbd/sqlite3/main.o dbd/sqlite3/statement.o dbd/sqlite3/connection.o -L/usr/lib -Wl,-rpath,/usr/lib -lsqlite3
luadbi-sqlite3 0.7.5-1 is now installed in /usr/local (license: MIT/X11)

④ restart 后注册用户验证落库：

systemctl restart prosody && sleep 3
prosodyctl register tester xmpp.example.com q1w2e3r4
ls -la /var/lib/prosody/*.sqlite3

实测回显：

usermanager         info        User account created: tester@xmpp.example.com
-rw-r----- 1 prosody prosody 36864 Oct 21 10:11 /var/lib/prosody/prosody.sqlite3

验证通过后，本文环境改回默认 internal（删除 storage/sql 两行再 restart），后续章节基于 internal 展开。

5.6 modules_enabled / modules_disabled：模块管理

modules_enabled 是 Prosody 功能开关的总闸。增删模块属结构性变更，必须 restart 而非 reload。实测启用 HTTP 服务族（BOSH，Web 客户端接入通道）：

在 modules_enabled 列表中追加两行：

                "http"; -- Enable HTTP services (BOSH/WebSocket/admin)
                "bosh"; -- Enable BOSH clients (XEP-0124)

restart 后验证端口与端点：

systemctl restart prosody && sleep 2
ss -ltnp | grep 528

实测回显：

LISTEN 0      128        127.0.0.1:5280       0.0.0.0:*    users:(("lua",pid=5183,fd=18))
LISTEN 0      128            [::1]:5280          [::]:*    users:(("lua",pid=5183,fd=17))
LISTEN 0      128        0.0.0.0:5281        0.0.0.0:*    users:(("lua",pid=5183,fd=17))

对应服务日志：

Oct 21 10:08:44 portmanager     info    Activated service 'http' on [::1]:5280, [127.0.0.1]:5280
Oct 21 10:08:44 portmanager     info    Activated service 'https' on [::]:5281, [*]:5281

⚠️ 注意两个默认行为：5280（明文 HTTP）默认只监听本机回环接口（http_interfaces 默认值），外部 Web 客户端无法直连，生产需改 http_interfaces 或前置 Nginx 反代；5281（HTTPS）默认监听全部接口。只启用 http 而不启用 bosh 时，访问 /http-bind 返回 404（端点未注册），两模块需成对启用。

验证 BOSH 端点（GET 请求）：

wget -S -O /dev/null http://127.0.0.1:5280/http-bind 2>&1 | grep "HTTP/"

实测回显：

  HTTP/1.1 200 OK

（200 响应体为 "Prosody BOSH endpoint" 说明页，BOSH 会话由 POST 建立。）

modules_disabled 用于关停不想全局存在的模块（如禁用 in-band 注册：modules_disabled = { "register" }），优先级高于 modules_enabled。

5.7 c2s/s2s：连接与加密参数

c2s（客户端）默认强制加密——13.0 流特性实测宣告 <starttls><required/>（见部署篇登录回显），对应内置参数：

c2s_require_encryption = true   -- 默认，可省略

s2s（服务器互联）默认 s2s_secure_auth = true：对端服务器必须通过证书强认证（SASL EXTERNAL 直连证书验证），否则拒收其消息流。

💡 技术拓展：s2s 服务器间认证机制对比——

机制原理前提
Dialback（XEP-0185 一族）回拨 DNS 域名所有权验证只需 DNS 可达
SASL EXTERNAL（直连 TLS）双方互验 X.509 证书建立信任双方均有受信证书

s2s_secure_auth = true 时优先直连证书验证、拒绝弱认证对端；内网/测试联邦可设 false 放宽为 dialback。

端口定制示例（默认 5222/5269 冲突时改用高位端口）：

c2s_ports = { 15222 }
s2s_ports = { 15269 }

5.8 limits：连接限速

默认配置即启用每连接带宽限制（limits 段由 mod_limits 提供）：

limits = {
        c2s = {
                rate = "10kb/s";
        };
        s2sin = {
                rate = "30kb/s";
        };
}

逐项说明：c2s.rate 限制单个客户端连接的上行带宽 10kb/s；s2sin 限制单个对端服务器入站 30kb/s。文件传输等大流量场景可按需上调（如 "100kb/s"），修改后 restart 生效。

5.9 certificates：证书配置

certificates = "certs"

指向 /etc/prosody/certs/ 目录，文件名须为「域名.crt/域名.key」且属主 root:prosody、权限 640（部署篇 8.3 节实测过完整归位流程）。prosodyctl check 只检查此目录；服务实际加载顺序为先此目录、后数据目录。Let's Encrypt 签发的证书可用软链接归位：

ln -s /etc/letsencrypt/live/xmpp.example.com/fullchain.pem /etc/prosody/certs/xmpp.example.com.crt
ln -s /etc/letsencrypt/live/xmpp.example.com/privkey.pem /etc/prosody/certs/xmpp.example.com.key

5.10 log：日志级别与去向

log = {
        info = "/var/log/prosody/prosody.log";
        error = "/var/log/prosody/prosody.err";
}

级别键决定输出粒度（debug/info/warn/error），值决定去向（文件路径或 "*syslog"、"*console"）。排障时临时切 debug（reload 即生效，见 3.2 节实测）；日志滚动由系统 logrotate 托管（包自带 /etc/logrotate.d/prosody）。

5.11 archive_expires_after 与 pidfile

archive_expires_after = "1w"   -- 消息归档保留 1 周
pidfile = "/var/run/prosody/prosody.pid"

archive_expires_after 支持 "1d"/"1w"/"never" 等取值，由 mod_cron 周期清理（日志可见 "Running periodic tasks"）。pidfile 一般无需改动；手动停止服务若残留 PID 文件会导致启动异常，删除后重启即可。

六、生产配置模板

适用场景：4GB 内存 / NVMe SSD / 100 用户规模的企业内部通信（单域名 + MUC 群聊 + BOSH 接入，消息归档 4 周）。可直接套用后按需微调：

-- Prosody IM 13.0.7 生产模板：4GB 内存 / 100 用户内部通信
admins = { "admin@xmpp.example.com" }

modules_enabled = {
        -- 必选基础（保持默认集）
        "disco"; "roster"; "saslauth"; "tls"; "blocklist"; "bookmarks";
        "carbons"; "dialback"; "limits"; "pep"; "private"; "smacks";
        "vcard4"; "vcard_legacy"; "account_activity"; "cloud_notify";
        "csi_simple"; "invites"; "invites_adhoc"; "invites_register";
        "ping"; "time"; "uptime"; "version";
        -- 管理通道
        "admin_adhoc"; "admin_shell";
        -- Web 接入
        "http"; "bosh";
}

modules_disabled = {
        "register"   -- 关闭客户端自助注册，账号一律管理员创建
}

authentication = "internal_hashed"
storage = "sql"
sql = { driver = "SQLite3", database = "prosody.sqlite3" }

s2s_secure_auth = true          -- 仅与可信 XMPP 服务器联邦；纯内网可改 false
c2s_require_encryption = true

limits = {
        c2s = { rate = "50kb/s" };     -- 内网放宽限速，支持文件消息
        s2sin = { rate = "100kb/s" };
}

archive_expires_after = "4w"    -- 归档保留 4 周
pidfile = "/var/run/prosody/prosody.pid"

log = {
        info = "/var/log/prosody/prosody.log";
        error = "/var/log/prosody/prosody.err";
}

certificates = "certs"

VirtualHost "xmpp.example.com"

Component "chat.xmpp.example.com" "muc"   -- 直接子域，自动可被发现
        muc_log_by_default = true;        -- 房间默认留档

逐段要点：模板将 MUC 组件用直接子域命名（chat.xmpp.example.com），免除 disco_items 配置；关闭 in-band 注册（register）后账号只能经 prosodyctl register 创建；storage = "sql" 需先完成 5.5 节的 Lua 5.4 驱动安装，否则回退 internal。

七、常见问题（FAQ）

FAQ-1：配置语法错误导致服务 failed

现象：改完配置 restart 后 systemctl is-active prosody 显示 failed，prosodyctl check 精确报 Lua 语法错误。

实测排障（故意在配置尾部追加不闭合的 admins = { "broken"）：

Error: /etc/prosody/prosody.cfg.lua:261: '}' expected (to close '{' at line 260) near <eof>

systemd 侧同样显示（systemctl status prosody）：

Active: failed (Result: exit-code) since Wed 2026-10-21 10:13:40 UTC; 1s ago
Oct 21 10:13:40 prosody-lab prosody[5653]: A problem occurred while reading the config file /etc/prosody/prosody.cfg.lua

解决：按报错行号修正语法（本文实验中删除坏行后 start 恢复 active）。养成习惯：每次改配置先 prosodyctl check 再 restart。

FAQ-2：改了模块列表但 reload 后不生效

现象：往 modules_enabled 加模块后 systemctl reload prosody，端口/端点无变化。

定位：模块加载发生在进程启动期，reload（SIGHUP）只热载日志级别、TLS 缓存等运行参数，不重扫模块列表。

解决：改模块、VirtualHost、Component、存储后端一律 systemctl restart prosody。

FAQ-3：check 报 invalid 'disco_items' option 且组件 unreferenced

现象：在 VirtualHost 段写 disco_items = { "chat.example.com" }，check 报：

Some hosts in your configuration file have an invalid 'disco_items' option.
This may cause further errors, such as unreferenced components.

定位：disco_items 的合法语法是子数组（每项为 { "域名" } 或 { "域名", "描述" }），纯字符串数组不被接受。

解决：

disco_items = { { "chat.example.com" } };

修正 restart 后 check 中两项警告均消失（实测复检输出无 invalid/unreferenced 行）。或者直接采用第六章模板的子域组件命名方案。

FAQ-4：storage = "sql" 后注册报 No SQL library available

完整排障链见 5.5 节实测：先装 lua-dbi-sqlite3（发行版包），若仍报错则按 dpkg -L 确认库只到 Lua 5.3，用 luarocks --lua-version 5.4 install luadbi-sqlite3 补 5.4 驱动，restart 后以 prosodyctl register 触发建库、ls /var/lib/prosody/*.sqlite3 验证。

FAQ-5：启用 http 模块后 /http-bind 返回 404

现象：5280 已监听但 GET /http-bind 为 404。

定位：BOSH 端点由 mod_bosh 注册，仅启用 mod_http 只开了 HTTP 框架。

解决：modules_enabled 同时加 "bosh"，restart 后 GET 返回 200（实测见 5.6 节）。

FAQ-6：外部设备无法访问 5280

定位：http_interfaces 默认 {"127.0.0.1","::1"} 仅本机（实测 ss -ltnp 显示 5280 只在回环地址）。解决方案二选一：配置 http_interfaces = { "*", "::" } 放开全接口（注意配合防火墙），或保持默认、由 Nginx 反向代理对外暴露。

八、参考链接