The Lounge 4.5.2 配置参数详解

目标：详解 The Lounge 4.5.2 的全部配置参数。配置文件 config.js 是 CommonJS 模块，所有参数在对象里按层级组织；首次启动时 The Lounge 在 THELOUNGE_HOME 下自动生成带完整注释的模板。本文以官方 defaults/config.js 为源，所有参数标注默认值、数据类型、影响范围与改法示例；实测基线 4.5.2（2026-07-11 发布）。

一、环境信息

• 版本：The Lounge 4.5.2（Node.js ≥ 22）
• 配置文件路径：
  • 包管理器（.deb / Yarn / npm）安装：THELOUNGE_HOME 环境变量指定（默认 /etc/thelounge）
  • 自托管进程：THELOUNGE_HOME=/var/opt/thelounge（4.5.2 官方镜像路径）
• 配置文件格式：config.js（CommonJS module.exports = { ... }，完整 JavaScript 语法，不是 JSON——可以写注释、条件逻辑、函数）
• 修改生效：改完重启 The Lounge 进程（systemd systemctl restart thelounge、或前台进程 Ctrl+C 重启）
• 本文所有示例片段均来自 4.5.2 默认模板，实测环境：Ubuntu 22.04 + Node.js 22.18.0

二、顶层结构速览

module.exports = {
    public: false,              // 服务器模式：public / private
    host: undefined,            // Web 监听地址
    port: 9000,                 // Web 监听端口
    bind: undefined,            // 出站 IRC 连接绑定地址
    reverseProxy: false,        // 是否 behind 反代
    maxHistory: 10000,          // 每频道最大历史行数
    https: { ... },             // 内置 TLS
    theme: "default",           // 客户端默认主题
    prefetch: false,            // URL 预览抓取
    disableMediaPreview: false, // 媒体预览
    prefetchStorage: false,      // 代理缓存
    prefetchMaxImageSize: 2048, prefetchMaxSearchSize: 50, prefetchTimeout: 5000,
    fileUpload: { ... },       // 文件上传
    transports: ["polling", "websocket"],  // socket.io 传输
    leaveMessage: "The Lounge - https://thelounge.chat",
    defaults: { ... },          // 默认 IRC 网络占位
    lockNetwork: false,         // 锁定默认网络
    messageStorage: ["sqlite", "text"],
    storagePolicy: { ... },    // SQLite 清理策略
    useHexIp: false,            // IPv4 hex 编码进 username
    webirc: null,               // WEBIRC 密码映射
    identd: { enable: false, port: 113 },
    oidentd: null,              // oidentd 配置文件路径
    ldap: { ... },              // LDAP 认证
    debug: { ircFramework: false, raw: false },
};

三、Server settings 服务器参数

3.1 public — 公开/私有模式

• public: false（私有模式）：用户必须先注册/登录才能用，IRC 连接持久——浏览器关掉、重开、换设备，连接和频道都还在，消息滚动历史在；
• public: true（公开模式）：无需账号，任何人直接进首页就有现成的 IRC 连接。代价：浏览器关 = 连接断 = 频道历史清空 = 消息滚动丢失。适合公共电脑/展厅场景。

💡 技术拓展：Shout（The Lounge 前身）默认 public，The Lounge v2 起翻转默认值为 private。这个翻转反映了社区使用场景的变化——早期多作临时公共聊天墙，后期多作 7×24 常驻个人 IRC 终端。两者都仍保留，没有被废弃。

改法示例（切成公开模式）：

public: true,

3.2 host — Web 服务监听地址

• "127.0.0.1"：只本机可访问；若前面有反向代理（Caddy/Nginx），建议 host 绑 127.0.0.1，反代对外——安全隔离；
• "0.0.0.0" 或 undefined：所有网卡；
• "unix:/absolute/path/to/file.sock"：UNIX domain socket，Caddy/Nginx 等反代可以直接连 socket，省 TCP 开销。

host: "127.0.0.1",   // 只本机 + 反代可访问

3.3 port — Web 服务端口

纯数字端口。若用 unix socket 则忽略。

3.4 bind — 出站 IRC 连接的本地 IP

多网卡/多出口服务器上可以强制 IRC 连接从哪个本地 IP 发出。例如双 WAN：

bind: "10.0.1.50",   // 强制 IRC 连接走这块网卡

3.5 reverseProxy — 反向代理信任开关

• false：The Lounge 自己处理连接，IP 从 socket 取；
• true：The Lounge 信任 X-Forwarded-For / X-Forwarded-Proto 头，从反代拿真实 IP 和协议。

用 Caddy/Nginx 反代 The Lounge 时必须设 true，否则所有客户端 IP 都显示成 127.0.0.1，且 WebSocket 升级可能失败。

3.6 maxHistory — 每频道内存历史上限

• 单个频道/私聊窗口内存里保留的消息数，超过即顶掉最老的；
• -1：无限；
• 设小可以减内存，但切换频道回滚到顶会看不到更早的消息。

⚠️ maxHistory 只管 内存 里的实时窗口；磁盘落盘由 messageStorage 控制，两者独立。

maxHistory: 5000,   // 每频道内存留 5000 行

3.7 https — 内置 TLS（不推荐）

官方推荐 交给反向代理做 TLS（Caddy 自动续签、certbot 一键）。内置 TLS 只适合不想搞反代的极简场景。示例：

https: {
    enable: true,
    key: "/etc/letsencrypt/live/irc.example.com/privkey.pem",
    certificate: "/etc/letsencrypt/live/irc.example.com/fullchain.pem",
    ca: "",
},

四、Client settings 客户端参数

4.1 theme — 默认主题

• 两个内置主题："default"（深色）、"morning"（浅色）；
• 也可以装社区主题（npm install thelounge-theme-solarized 之类），值写包名；
• 每个用户登录后可以在自己的客户端设置里覆盖这个默认值。

4.2 prefetch — URL 预览抓取

频道/私聊里有人发 URL 时，The Lounge 自动请求目标站点抓 Open Graph 元标签（标题、描述、缩略图），在频道里渲染卡片。开了以后服务器会对外发很多 HTTP 请求——要注意被封、隐私策略、和 prefetchMax* 配合限流。

4.3 disableMediaPreview — 媒体预览禁用

• true：图片/视频/音频只显示链接，不内嵌预览；
• 只在 prefetch: true 时有意义；
• 开它的好处：客户端浏览器不会向第三方站点发请求（隐私），且跳过混合内容警告（HTTP 图片在 HTTPS 页面里）。

4.4 prefetchStorage — 代理式图片缓存

• true：The Lounge 自己去抓缩略图和图片，存到 ${THELOUNGE_HOME}/storage/，然后自己当代理给客户端下发；
• 主要目的：解决混合内容警告（页面 HTTPS、图片 HTTP）；
• 视频/音频不缓存，只走 HTTPS 原链接。

4.5 prefetchMaxImageSize / prefetchMaxSearchSize / prefetchTimeout

prefetchMaxImageSize: 4096,   // 允许更大的缩略图
prefetchTimeout: 8000,         // 网络慢时多等 3 秒

4.6 fileUpload — 文件上传

上传文件落 ${THELOUNGE_HOME}/uploads/，不会被 The Lounge 自动清理——磁盘自己盯紧。

fileUpload: {
    enable: true,
    maxFileSize: 20480,      // 允许 20MB
    baseUrl: null,           // 默认相对路径
},

4.7 transports — socket.io 传输层

socket.io 提供两种传输：polling（长轮询，兼容性最好）和 websocket（实时、高效）。默认都开，浏览器自动协商——能用 websocket 就上 websocket，不能再回退 polling。

反代场景若能确保 websocket 透传（Caddy/Nginx 默认都能），可以只留 websocket：

transports: ["websocket"],   // 强制 websocket，省 polling 开销

4.8 leaveMessage — 默认 quit/part 消息

用户退出 IRC 或离开频道时，自己没写 part/quit message 的话用这个当默认。每个用户也可以在自己的客户端设置里改。

五、Default network 默认 IRC 网络

5.1 defaults — Connect 窗口占位

改法（指向自建 IRCd）：

defaults: {
    name: "Local IRCd",
    host: "127.0.0.1",
    port: 6667,
    password: "",
    tls: false,
    rejectUnauthorized: false,
    nick: "lounge%%",
    username: "lounge",
    realname: "My Lounge User",
    join: "#lounge,#test",
},

5.2 lockNetwork — 锁定默认网络

• true：Connect 面板里 host、port、TLS 全部灰掉，用户只能连 defaults 里配置的那个网络；
• 适合把 The Lounge 作为单一 IRC 网络的网关（只放某个内网 IRCd 给用户用）。

六、User management 用户管理参数

6.1 messageStorage — 消息落盘方式

• "sqlite"：每个用户一个 SQLite 文件，自动加载历史（private 模式关键）；
• "text"：纯文本日志，不落回滚历史，只作审计；
• []：完全关闭落盘（内存模式，重启丢全部）。

messageStorage: ["sqlite"],   // 只留 SQLite

⚠️ private 模式下建议 不要 关掉 SQLite——否则重启后频道全部要重连、历史全空，跟 public 模式没区别了。

6.2 storagePolicy — SQLite 自动清理

storagePolicy: {
    enabled: true,
    maxAgeDays: 180,
    deletionPolicy: "statusOnly",
},

6.3 useHexIp — IPv4 hex 编码

• true：用户的 IPv4 地址被转成 hex（如 192.168.1.50 → c0a80132）塞进 IRC username 字段；
• 作用：让 IRC 网络按真实 IP 做 host masking（如 nick!c0a80132@*.ircnet）；
• 只支持 IPv4，IPv6 不处理。

七、WEBIRC 支持

IRC 网络（如 Libera.Chat）可以给 The Lounge 发 WEBIRC 密码，The Lounge 把用户真实 IP 转给 IRCd，nick 就能拿到网络赋予的 cloak/host。两种写法：

7.1 Basic — 主机名 → 密码

webirc: {
    "irc.libera.chat": "lounge-webirc-password-libera",
    "irc.example.com": "another-password",
},

7.2 Advanced — 函数，自定义加工

可以对 WEBIRC 对象（hostname、username、realname、password）做任意加工：

webirc: {
    "irc.example.com": (webircObj, network) => {
        webircObj.password = "thisiswebircpassword";
        webircObj.hostname = `webirc/${webircObj.hostname}`;
        return webircObj;
    },
},

八、identd / oidentd

8.1 identd — 内置 identd

IRC 网络连接前可能发 ident 查询（RFC 1413），看 The Lounge 自称是什么用户。identd 开了以后 The Lounge 自己回 ident 请求。

特权端口问题：Linux 下 bind < 1024 需要 root。若 The Lounge 以非 root 用户跑（推荐），identd.port 改成 1130 之类的高位端口，再在宿主 iptables/反代层把 113 → 1130 映射回去。

8.2 oidentd — 委托给 oidentd

如果系统里已经跑着 oidentd（成熟的 identd 守护进程，比内置功能强），把 oidentd 配置文件路径给它，The Lounge 就不再管 identd：

oidentd: "/etc/oidentd.conf",

identd.enable 和 oidentd 二选一，冲突时 oidentd 优先。

九、LDAP 认证（private 模式）

只有 public: false 时 LDAP 才生效。The Lounge 先 bind 进 LDAP 搜索用户 DN，再用用户提供的密码 bind 验证。

9.1 参数表

9.2 两种模式

baseDN 简单模式：直接假设用户 DN = <bindDN>,<primaryKey>=<username>：

ldap: {
    enable: true,
    url: "ldaps://ldap.example.com:636",
    baseDN: "ou=users,dc=example,dc=com",   // 最终 DN: uid=alice,ou=users,dc=example,dc=com
    primaryKey: "uid",
},

searchDN 高级模式：先用一个只读 bind 用户搜索用户 DN，再验证：

ldap: {
    enable: true,
    url: "ldaps://ldap.example.com:636",
    searchDN: {
        rootDN: "cn=thelounge-service,ou=system,dc=example,dc=com",
        rootPassword: "service-bind-password",
        filter: "(&(objectClass=person)(memberOf=ou=irc-users,dc=example,dc=com))",
        base: "dc=example,dc=com",
        scope: "sub",
    },
    primaryKey: "uid",
},

• rootDN/rootPassword：有权读用户条目的服务账号；
• filter：附加过滤，比如「只允许某 OU 里的 person」；
• scope：base / one / sub（只搜当前节点 / 下一层 / 整棵子树）。

9.3 tlsOptions

当 url 用 ldaps:// 时生效，可以覆盖默认 TLS 行为（比如强制 IPv6）：

ldap: {
    tlsOptions: {
        host: "::1",
        servername: "ldap.example.com",
    },
},

十、Debugging settings 调试

10.1 debug 对象

debug: {
    ircFramework: true,   // 开发 IRC 插件/新网络适配时开
    raw: true,            // 频道里直接能看到 ":irc.libera.chat 001 nick :Welcome ..."
},

⚠️ debug.raw 直接污染频道滚动区，只在排障开，开完记得关。

十一、环境变量覆盖

除了 config.js，两个环境变量影响行为：

CLI 也可以单次覆盖任意配置键（不改文件）：

thelounge start -c public=true -c port=8000
# 多个 -c 覆盖多个键；对象深层用点号 -c https.enable=true

十二、实测：改 public 重启生效

以 4.5.2 为例，把 public: false 改成 true：

# 1. 改文件
$ vim /etc/thelounge/config.js    # THELOUNGE_HOME=
#   public: true,                  ← 原来是 false

# 2. 重启
$ systemctl restart thelounge
$ systemctl status thelounge
# ● thelounge.service - The Lounge IRC Client
#    Active: active (running) since ...

# 3. 验证：直接浏览器打开不需要登录了
$ curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9000
# 200

切回 private 同理——public: false → 重启 → 浏览器打开会被送到 /login。

十三、安全建议速查