Continuwuity 26.9.1 Docker Compose 部署指南

目标：用 Docker Compose 一键部署 Continuwuity（Matrix homeserver，容器内进程名 conduwuit），跑通「拉镜像 → 起栈 → 取注册令牌 → 注册管理员 → 验证 API」全流程，并掌握数据持久化、环境变量、升级回滚与 Kubernetes 形态。本文基于官方 OCI 镜像 forgejo.ellis.link/continuwuation/continuwuity:v26.9.1 全量实测（实测日 2026-10-25）。

一、环境信息

• 宿主操作系统：Ubuntu 22.04.5 LTS（x86_64），Docker 29 + Compose v2
• 组件版本：Continuwuity v26.9.1（CalVer，2026-09-28 发布，commit 046074b）
• 镜像：forgejo.ellis.link/continuwuation/continuwuity:v26.9.1（实测体积 149MB）
• 容器内监听：0.0.0.0:8008；宿主映射示例：127.0.0.1:8144:8008（宿主端口可按需改）
• 数据卷：命名卷 db → 容器内 /var/lib/continuwuity（RocksDB + 媒体）
• 演示账号：admin + 密码 q1w2e3r4（示例口令，生产请替换）

二、镜像选型说明

官方维护四个镜像标签（主源 Forgejo 注册表）：

主源拉不动时，官方同步镜像到三个镜像站（官方注明可能滞后）：ghcr.io/continuwuity/continuwuity、docker.io/jadedblueeyes/continuwuity、registry.gitlab.com/continuwuity/continuwuity。

💡 技术拓展：同一组件多注册表分发是自托管生态的常见做法，各注册表差异——

注册表	特点
Forgejo（forgejo.ellis.link）	官方主源，版本最全最快
GHCR（ghcr.io）	GitHub 生态，国内直连一般较慢
Docker Hub	最易用但有拉取限流
GitLab Registry	GitLab 生态镜像

本文以主源 Forgejo 为准实测，拉取顺利未降级；若你的网络不通主源，按需替换镜像前缀为任一镜像站。

三、前置条件

1. 已安装 Docker 与 Compose v2（docker compose version 能输出版本即可）；
2. 决定好 Matrix 域名（server_name），首启写库后不可更改；
3. 生产环境需另备反向代理终结 TLS（Caddy/Traefik/Nginx），本文聚焦 homeserver 本体，反代配置见官方文档链接。

四、部署步骤

4.1 编写 compose 文件

建项目目录并写入 docker-compose.yml：

mkdir -p /opt/continuwuity && cd /opt/continuwuity

name: continuwuity-26.9.1-stack
services:
  homeserver:
    image: forgejo.ellis.link/continuwuation/continuwuity:v26.9.1
    restart: unless-stopped
    command: /sbin/conduwuit
    ports:
      - 127.0.0.1:8144:8008
    volumes:
      - db:/var/lib/continuwuity
    environment:
      CONTINUWUITY_SERVER_NAME: example.org
      CONTINUWUITY_DATABASE_PATH: /var/lib/continuwuity
      CONTINUWUITY_ADDRESS: 0.0.0.0
      CONTINUWUITY_PORT: 8008
volumes:
  db:

逐项说明：

• command: /sbin/conduwuit：镜像内二进制路径（官方 compose 示例固定写法）；
• ports：把容器 8008 映射到宿主回环 8144，供本机反向代理回源；宿主端口可改为任意空闲端口；
• environment：Continuwuity 支持全量环境变量配置（CONTINUWUITY_ 前缀，见六、环境变量表），容器形态下不配配置文件也能跑；
• volumes.db：唯一持久化需求，RocksDB 与媒体全在这一个目录。

4.2 拉取镜像并启动

docker compose pull
docker compose up -d

实测回显：

 Image forgejo.ellis.link/continuwuation/continuwuity:v26.9.1 Pulled 
 Container continuwuity-2691-stack-homeserver-1  Started 

4.3 确认容器状态

docker compose ps

实测回显：

NAME                                   IMAGE                                                    COMMAND             SERVICE      STATUS         PORTS
continuwuity-2691-stack-homeserver-1   forgejo.ellis.link/continuwuation/continuwuity:v26.9.1   "/sbin/conduwuit"   homeserver   Up 6 seconds   127.0.0.1:8144->8008/tcp

4.4 取首次注册令牌

首次启动日志会打印一次性注册令牌（首个账户用它注册后，自由注册即关闭）：

docker compose logs homeserver | grep -E "Welcome|Listening|registration token"

实测回显：

 INFO conduwuit_router::serve::plain: Listening on [0.0.0.0:8008]
Welcome to Continuwuity 26.9.1 (046074b)!
Open your Matrix client of choice and register an account on example.org using the registration token sCzJ2e0MI4AVyrIh . Pick your own username and password!

4.5 验证 API 并注册管理员

curl -s http://127.0.0.1:8144/_continuwuity/server_version

实测回显：

{"name":"continuwuity","version":"26.9.1 (046074b)"}

curl -s -X POST http://127.0.0.1:8144/_matrix/client/v3/register \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"q1w2e3r4","auth":{"type":"m.login.registration_token","token":"sCzJ2e0MI4AVyrIh"}}'

实测回显：

{"access_token":"uiYpMEw29Lq0Xs2usQVvyx1V","user_id":"@admin:example.org","device_id":"pmSv5Ng6jw"}

@admin:example.org 自动成为管理员并加入 #admin:example.org 管理房间。更多接口调用（登录、建房、发消息、管理命令）见本专栏的 API 使用详解篇。

五、数据持久化说明

唯一需要持久化的是命名卷 db（容器内 /var/lib/continuwuity）。验证重启不丢数据：

docker compose restart
curl -s -X POST http://127.0.0.1:8144/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{"type":"m.login.password","user":"admin","password":"q1w2e3r4"}'

实测回显（重启后管理员可正常登录，数据完好）：

{"user_id":"@admin:example.org","access_token":"d3zrwcAF9D2TFehr0nz8sTbc","home_server":"example.org","device_id":"adzEO..."}

卷在宿主上的实际位置可用 docker inspect continuwuity-2691-stack_db --format '{{.Mountpoint}}' 查看，备份时停机打包该目录，或配置 database_backup_path 启用 RocksDB 在线热备（见《Continuwuity 26.9 配置参数详解》）。

六、环境变量表

Continuwuity 配置键与环境变量的换算规则：键名大写 + CONTINUWUITY_ 前缀；子段用双下划线（如 CONTINUWUITY_WELL_KNOWN__SERVER）。compose 场景常用项：

七、配置参数说明与配置文件挂载

环境变量适合起步；配置项一多建议改挂配置文件。把本地 ./continuwuity.toml 挂入并指定 CONTINUWUITY_CONFIG：

    volumes:
      - db:/var/lib/continuwuity
      - ./continuwuity.toml:/etc/continuwuity.toml
    environment:
      CONTINUWUITY_CONFIG: /etc/continuwuity.toml

continuwuity.toml 最小内容：

[global]
server_name = "example.org"
database_path = "/var/lib/continuwuity"
address = "0.0.0.0"
port = 8008

⚠️ 注意：容器内 address 必须为 0.0.0.0，否则宿主映射端口访问不通（conduwuit 检测到回环监听会按预期给出告警日志）。全量 200+ 参数逐项说明见《Continuwuity 26.9 配置参数详解》。

八、等价 docker run

不便于用 compose 时，等价的单命令启动形态：

docker run -d \
  --name continuwuity \
  --restart unless-stopped \
  -p 127.0.0.1:8144:8008 \
  -v continuwuity_db:/var/lib/continuwuity \
  -e CONTINUWUITY_SERVER_NAME="example.org" \
  -e CONTINUWUITY_DATABASE_PATH="/var/lib/continuwuity" \
  -e CONTINUWUITY_ADDRESS="0.0.0.0" \
  -e CONTINUWUITY_PORT="8008" \
  forgejo.ellis.link/continuwuation/continuwuity:v26.9.1 \
  /sbin/conduwuit

九、常用运维命令

docker compose logs -f homeserver     # 跟踪日志
docker compose ps                     # 容器状态
docker compose restart                # 重启
docker compose down                   # 停栈（保留数据卷）
docker compose pull && docker compose up -d   # 升级：拉新镜像重建
docker compose down -v                # 停栈并删数据卷（危险，清库重来）

升级建议把 image: 钉在具体版本（如 v26.9.1），升级 = 改版本号 + pull + up -d；回滚 = 改回旧版本号 + up -d（大版本降级前先读 Release Notes 确认数据库迁移可逆）。

十、常见问题（FAQ）

Q1：起栈后宿主 curl 127.0.0.1:8144 不通？ 优先查容器内监听地址：CONTINUWUITY_ADDRESS 必须是 0.0.0.0；再 docker compose logs homeserver 看是否打印 Listening on [0.0.0.0:8008]。

Q2：日志里的注册令牌没找到？ 只有「尚无任何本地用户」时启动才打印；已有用户后由管理员在 #admin 房间用 !admin token 命令签发新令牌。

Q3：联邦加入房间超时？ Docker 内置 DNS 解析器对 Matrix 联邦的 SRV 查询性能差，官方建议挂载自定义 resolv.conf（如 nameserver 1.1.1.1）或为宿主部署本地缓存 DNS，详见官方 DNS 调优指南。

Q4：想在 443 单端口同时承载客户端与联邦？ 配 CONTINUWUITY_WELL_KNOWN（或配置文件的 [global.well_known] 段）做委派，反代只需转发 443，详见官方 Delegation 指南。

Q5：镜像拉取失败？ 主源为 Forgejo（forgejo.ellis.link）；不通时换官方镜像站前缀（GHCR/Docker Hub/GitLab，见二、镜像选型说明），注意镜像站同步可能有延迟。

十一、附：Kubernetes 部署形态

Continuwuity 不支持水平扩展（有状态单体），但天然适合以 StatefulSet（replicas=1）+ PVC + Service + Ingress 形态跑在 k8s 上——配置全走环境变量即可。官方部署文档已给出完整 StatefulSet 样例（https://continuwuity.org/deploying/kubernetes.html ，要点：image: forgejo.ellis.link/continuwuation/continuwuity:latest、command: ["/sbin/conduwuit"]、CONTINUWUITY_DATABASE_PATH=/data/db、readinessProbe 打 /_matrix/federation/v1/version、资源参考 requests: 2C/512Mi、limits: 4C/2048Mi）。

另有社区维护的 Helm Chart（conduwuit 时代产物，兼容 Continuwuity 但需把镜像引用改为 Continuwuity 官方镜像）：https://gitlab.cronce.io/charts/conduwuit

⚠️ 注意：该 Chart 非 Continuwuity 官方维护；k8s 集群内的完整实测（PV 供给、Ingress 委派、联邦联通）将在后续 K1 批次专题展开，本节仅给出形态与路径指引。

十二、参考链接

• 官方 Docker 部署文档：https://continuwuity.org/deploying/docker.html
• 官方 Kubernetes 部署文档：https://continuwuity.org/deploying/kubernetes.html
• 镜像版本列表：https://forgejo.ellis.link/continuwuation/-/packages/container/continuwuity/versions
• 社区 Helm Chart：https://gitlab.cronce.io/charts/conduwuit
• 站内相关：《Continuwuity 介绍与选型指南》、《Ubuntu 22.04 安装 Continuwuity 26.9 指南》、《Continuwuity 26.9 配置参数详解》