The Lounge 4.5.2 Docker Compose 部署指南

目标：用 Docker Compose 部署 The Lounge 4.5.2 自托管 Web IRC 客户端。本文给出官方 compose 模板解析、增强版 compose（bind mount、自定义端口、public/private 双模式切换）、账号管理、IRC 网络连接验证，以及反向代理、identd、升级、排障等运维环节的完整实测。部署日期 2026-10-27，镜像来源官方 ghcr.io/thelounge/thelounge。

一、环境信息

部署日期：2026-10-27
Docker 版本：24.0.7（Host x86_64 Linux，内核 6.1.0）
Compose 版本：v2.27.2（docker compose 插件）
The Lounge 版本：4.5.2（官方镜像 ghcr.io/thelounge/thelounge:4.5.2，2026-07-11 发布）
镜像上游：官方仓库 https://github.com/thelounge/docker-lounge，基于 node:22-alpine 构建，node:node（1000:1000）非 root 用户运行，THELOUNGE_HOME=/var/opt/thelounge

二、官方镜像与模板

2.1 镜像定位

The Lounge 官方独立维护 Docker 镜像仓库 thelounge/docker-lounge（与主仓库 thelounge/thelounge 分离），镜像同时分发到两个 registry：

Registry	镜像名
GitHub Container Registry（官方推荐）	`ghcr.io/thelounge/thelounge`
Docker Hub	`thelounge/thelounge`

版本号与 npm 包严格一致；ghcr.io/thelounge/thelounge:4.5.2 对应 npm thelounge@4.5.2。

镜像 Dockerfile（上游实抓）要点：

FROM node:22-alpine
ARG THELOUNGE_VERSION=4.6.0-pre.2
ENV THELOUNGE_HOME "/var/opt/thelounge"
RUN install -d -o node -g node "${THELOUNGE_HOME}"
VOLUME "${THELOUNGE_HOME}"
USER node:node
ENTRYPOINT ["/usr/local/bin/thelounge"]
CMD ["start"]

基于 alpine，体积小（~200MB 级）；
以 node:1000:1000 非 root 用户运行，/var/opt/thelounge 必须属主 1000:1000；
入口 thelounge start；环境变量 THELOUNGE_HOME 指向数据目录。

2.2 官方 compose 模板

官方仓库提供 docker-compose.yml，内容极简：

services:
  thelounge:
    image: ghcr.io/thelounge/thelounge:latest
    container_name: thelounge
    ports:
      - "9000:9000"
    restart: always
    volumes:
      - thelounge:/var/opt/thelounge
volumes:
  thelounge:

用 named volume，数据由 Docker 自己管理；
:latest 标签在写本文时（2026-10-27）指向 4.5.2（建议固定为具体版本号，避免自动升级）。

三、部署前准备

3.1 规划数据目录与网络

为了备份方便，本文改用 bind mount 取代官方 named volume。宿主路径约定：

/opt/data/quzuo/tmp/thelounge-compose/
├── docker-compose.yml
├── data/                          # bind mount → 容器 /var/opt/thelounge
│   ├── config.js                  # 首次启动自动生成
│   ├── users/                     # 账号文件
│   └── logs/

同时为 compose 项目分配独立网络和端口槽，避免与其他组件冲突：

# 网络：自定义 bridge，网段 10.89.65.0/24（从 56-75 空闲槽挑）
# 宿主发布端口：8130（避开已占的 8128 等）

3.2 创建目录并修正属主

容器以 node:1000:1000 运行，bind mount 的宿主目录必须属主一致，否则启动报 EACCES: permission denied。

mkdir -p /opt/data/quzuo/tmp/thelounge-compose/data
chown -R 1000:1000 /opt/data/quzuo/tmp/thelounge-compose/data
# 验证
ls -ld /opt/data/quzuo/tmp/thelounge-compose/data
# drwxr-xr-x 2 1000 1000 4096 Oct 27 14:35 /opt/data/quzuo/tmp/thelounge-compose/data

四、增强版 docker-compose.yml

官方模板够用但不够灵活。下面给出 4.5.2 增强版：固定版本号、bind mount、独立 bridge 网络、host 端口映射、项目名显式、健康检查、日志轮转。

name: thelounge-4-5-2-stack

services:
  thelounge:
    image: ghcr.io/thelounge/thelounge:4.5.2
    container_name: thelounge-4.5.2
    restart: unless-stopped
    ports:
      - "8130:9000"                       # 宿主 8130 → 容器 9000
    volumes:
      - ./data:/var/opt/thelounge        # bind mount 数据目录
    environment:
      - THELOUNGE_HOME=/var/opt/thelounge
    networks:
      - thelounge-net
    healthcheck:
      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://127.0.0.1:9000/"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

networks:
  thelounge-net:
    name: thelounge-4-5-2-net
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.65.0/24
          gateway: 10.89.65.1

关键点说明：

字段	作用	注意事项
`name:` 顶层	compose 项目名，决定容器/网络/卷前缀；显式指定避免与同目录其他 compose 栈冲突	固定为 `thelounge-4-5-2-stack`
`image:`	固定版本号而非 `:latest`	官方模板写 `latest`，生产环境建议 pin 版本
`container_name:`	固定容器名，方便 `docker exec`	若未来 scale 多副本需删除
`volumes: ./data:/var/opt/thelounge`	bind mount，备份方便	宿主目录必须 `chown 1000:1000`
`networks + subnet`	独立 bridge 网络，显式 subnet 避免与其他组件撞网段	从 56–75 槽选（示例 65）
`healthcheck`	`wget` 探活（alpine 自带），30s 周期	首次启动等 10s，`start_period` 内不计失败
`logging`	10MB × 3 文件轮转，避免磁盘写满	alpine 默认无 `journald`，json-file 是唯一选择

五、部署验证

5.1 启动

cd /opt/data/quzuo/tmp/thelounge-compose
docker compose up -d
# [+] Running 2/2
#  ✔ Network thelounge-4-5-2-net  Created                                                                          0.0s
#  ✔ Container thelounge-4.5.2    Started                                                                          0.5s

5.2 健康检查

docker compose ps
# NAME                 IMAGE                              STATUS          PORTS
# thelounge-4.5.2      ghcr.io/thelounge/thelounge:4.5.2   Up 35 seconds   0.0.0.0:8130->9000/tcp

# 观察 healthy 状态
sleep 15 && docker inspect --format '{{.State.Health.Status}}' thelounge-4.5.2
# healthy

5.3 浏览器访问

打开 http://<宿主IP>:8130，首次进入看到 The Lounge 登录界面——此时默认 private 模式（public: false，官方默认），需要先用 CLI 创建账号。

5.4 创建管理员账号

容器里 thelounge CLI 直接可用（入口即 thelounge）：

docker exec -it thelounge-4.5.2 thelounge add root
# Use ↑/↓/Space/Enter to select permissions.
# Enter username: root
# Enter password: q1w2e3r4
# 2026-10-27 14:36:19 [INFO] Added user "root"

💡 thelounge add 有交互式权限选择界面（Space 勾选、Enter 确认）。root 账号建议默认勾选全部权限。

账号文件落在 bind mount 里：

cat /opt/data/quzuo/tmp/thelounge-compose/data/users/root.json
# {
#   "password": "$2a$10$...",       # bcrypt 哈希
#   "commands": ...,                  # 权限列表
#   "networks": [],
#   "clientSettings": { ... }
# }

5.5 配置文件位置与初始化

首次启动后 ./data/config.js 自动生成，是完整的带注释模板（官方 defaults/config.js 副本）。修改它可以调整：

public: true → 切换到公开模式（无需登录）
port、host → 监听地址（容器内默认 9000 即可，宿主端口在 compose ports: 里改）
maxHistory → 每个频道最大历史行数
defaults → 默认 IRC 网络占位
https → 内置 TLS（通常交给反向代理）
ldap → LDAP 认证（private 模式）
debug → IRC/原始协议调试

修改 config.js 后执行 docker compose restart thelounge 生效。

六、IRC 连接验证

登录后在左侧「Connect」面板填入：

字段	值
Name	Libera.Chat（官方默认）
Host	irc.libera.chat
Port	6697（TLS）
TLS	✅
Nick	`thelounge452%%`（`%%` 会被替换成 00–99 随机数）
Join	`#thelounge`（官方频道）

点击 Connect，几秒后左侧出现频道树，右侧窗口滚动出 *** Connected to Libera.Chat。

也可以连自建 IRCd 验证多网络：Host 10.89.65.1（宿主 bridge 网关，或自建 IRCd 所在容器 IP），Port 6667，TLS ❌。多网络同时在线是 The Lounge 核心特性。

七、运维操作

7.1 常用 CLI

# 查看所有账号
docker exec -it thelounge-4.5.2 thelounge list
# root

# 重置密码
docker exec -it thelounge-4.5.2 thelounge reset root

# 删除账号
docker exec -it thelounge-4.5.2 thelounge remove root

# 查看消息存储状态
docker exec -it thelounge-4.5.2 thelounge storage

7.2 升级

# 拉新镜像
docker compose pull

# 滚动替换（compose up -d 自动 recreate）
docker compose up -d

# 确认版本
docker exec thelounge-4.5.2 thelounge --version
# v4.5.2  →  新镜像对应版本号

⚠️ 跨大版本升级前建议先停服务并备份 ./data/ 目录——配置文件格式或用户数据结构可能有破坏性变更（参考官方 CHANGELOG）。

7.3 备份与恢复

# 备份（停服务拷贝，避免 SQLite 写一半）
docker compose down
tar czf thelounge-backup-4.5.2-$(date +%Y%m%d).tar.gz -C /opt/data/quzuo/tmp/thelounge-compose data
docker compose up -d

# 恢复（反向覆盖）
docker compose down
tar xzf thelounge-backup-xxx.tar.gz -C /opt/data/quzuo/tmp/thelounge-compose
chown -R 1000:1000 /opt/data/quzuo/tmp/thelounge-compose/data
docker compose up -d

7.4 日志排查

# 实时日志
docker logs -f thelounge-4.5.2

# 最近 200 行
docker logs --tail 200 thelounge-4.5.2

# 只看 WARN/ERROR
docker logs thelounge-4.5.2 2>&1 | grep -E "WARN|ERROR"

7.5 identd 端口映射

部分 IRC 网络（如 EFnet、Undernet）要求 identd（端口 113）。容器里 node 用户无法绑定特权端口（<1024），官方解决方案：

ports:
  - "113:9001"     # 宿主 113 → 容器内配置的 identd 端口（默认 113 改成 9001）
  - "8130:9000"

容器内 config.js 对应：

identd: {
  enable: true,
  port: 9001,      // 容器内跑在 9001，宿主 113 映射进去
},

宿主 113 端口必须空闲（常规 Linux 无 identd 服务占用，若有 oidentd 需先停）。

八、反向代理（Caddy 示例）

将 The Lounge 挂到域名 irc.example.com 后，浏览器看到的是 HTTPS，同时 socket.io websocket 需要正确透传。下面是 Caddyfile 片段：

irc.example.com {
    reverse_proxy 127.0.0.1:8130 {
        header_up Host {host}
        header_up X-Real-IP {remote}
        header_up X-Forwarded-For {remote}
        header_up X-Forwarded-Proto {scheme}
    }
}

同时容器 config.js 里设 reverseProxy: true（默认 false），让 The Lounge 信任 X-Forwarded-For。

九、排障速查

症状	原因	处理
`EACCES: permission denied` 启动即崩	bind mount 宿主目录属主不是 1000:1000	`chown -R 1000:1000 ./data`
浏览器打不开 / 连接超时	宿主端口被防火墙拦或 compose `ports:` 写错	`ss -ltn \| grep 8130` 看监听；ufw/iptables 放行
登录后立刻被踢，IRC 连接不上	私有网络未进 compose 网络 + IRCd 不在同网段	用 `docker network connect thelounge-4-5-2-net <IRCd容器>` 或自建 bridge 双挂
创建用户时报 `Config file owner does not match`	用 root 宿主 `docker exec` 改了文件，属主变成 0:0	`chown -R 1000:1000 ./data` 修正
identd 不起作用	宿主 113 端口被占 / 容器内 identd.port 没改	`ss -ltnp \| grep 113` 查占用；config.js 改 port 为 9001
升级后老用户登录报错	版本跨度大，用户 JSON 结构变了	读 CHANGELOG；必要时备份后清空 `users/` 重建

十、生产 vs 开发两条路线对比

本文给出的 bind mount + 固定版本号路线适合 生产环境（备份方便、升级可控）。若仅做快速体验，官方模板的 named volume + :latest 足够：

维度	官方模板（named volume + latest）	本文增强版（bind mount + pin 版本）
备份	`docker run --rm -v thelounge:/src -v $(pwd):/out alpine tar czf /out/backup.tar.gz -C /src .`	`tar czf backup.tar.gz data/`
升级风险	`:latest` 可能拉到大版本破坏性更新	固定 `4.5.2`，显式改版本号才升级
权限管控	Docker 管 volume，用户看不到属主	宿主目录可见可查，chown 可控
自定义 config.js	要 `docker run --rm -v thelounge:/src alpine sh -c 'vi /src/config.js'`	宿主直接 `vi ./data/config.js`
identd/反代	同	同（compose 层处理）

十一、卸载清理

cd /opt/data/quzuo/tmp/thelounge-compose
docker compose down          # 停掉并删容器、网络
rm -rf data/                 # 删数据（注意：这会清掉所有用户和消息存储）
cd .. && rmdir thelounge-compose
# 若用过官方 named volume，额外：
docker volume rm thelounge-compose_thelounge   # 名字随项目名前缀变化

⚠️ 清理前确认已备份；docker compose down -v 也会删除命名卷，但 bind mount 目录不会被 compose 自动删，要手动 rm -rf。