Conduwuit迁移Continuwuity：数据兼容、联邦密钥与回滚

1. 迁移这件事，先想清楚到底在搬什么

Conduwuit 切到 Continuwuity，很多人第一反应是：换个二进制、改两行配置、重启完事。真在线上跑过一年以上的人不会这么想。一个自建通信服务最贵的资产从来不是程序本身，而是那几百 GB 的 RocksDB、几万条历史事件、一整套联邦签名密钥，还有一群已经习惯消息不断线的用户。程序可以随时换，这些换一次就是事故。

先把结论摆前面：Conduwuit 到 Continuwuity 的迁移，技术上可行，但"可行"和"平滑"之间隔着大量细节。如果你只是在自己机器上跑个小实例、用户数不超过十个、历史数据无所谓，那确实可以随便折腾。但只要你承担了别人的通信，迁移就得按"有明确回滚点、有验证手段、有最小停机窗口"的方式来设计。

这篇文章面向三类人：一是已经跑着 Conduwuit、想跟进 Continuwuity 新特性的运维；二是被旧分支的维护节奏拖得难受、想找个长期落点的自建用户；三是刚接手别人留下的实例、需要做一次架构梳理的新负责人。内容会覆盖数据兼容性边界、三条升级路径的取舍、完整实操流程、故障排查速查表，以及我从几次迁移里踩出来的经验。涉及具体配置项名称的部分，我会说明哪些来自公开文档、哪些是基于同类项目常见实践的合理推断，你落地时以自己所用版本的文档为准。

1.1 两个项目的关系，决定了迁移难度

要判断迁移是"换壳"还是"换内脏"，得先弄清两个项目在血统上的位置。Conduwuit 本身是 Conduit 的一个下游分支，围绕性能、可观测性和配置体验做了大量改造；Continuwuity 又是在这条线上继续演进的分支。这种"下游的下游"关系带来一个非常实际的后果：它们共享同一套核心概念模型——房间、事件、PDU、联邦签名、设备密钥——但各自在上面叠了不同的 schema 演进和配置命名。

共享概念模型意味着数据可以搬，字段语义能对上；各自的演进意味着不能简单地把数据库文件拷过去就启动。真正决定迁移难度的不是代码相似度，而是三个东西：数据库 schema 版本号、媒体存储的布局、签名密钥的延续性。前两个决定能不能启动，第三个决定启动之后能不能和外面的世界说话。

我在第一次迁移时犯过的错，是把"能启动"当成了"迁移完成"。服务起来了，本地用户互相发消息也正常，看起来很成功。直到第二天有外部实例的用户反馈"加不上你们的房间"，才发现签名密钥换了新文件，联邦侧缓存了旧公钥，需要等缓存过期或者主动触发 key 重新获取。那段时间窗口里，所有跨实例的加入请求全部失败，而本地测试完全测不出来。

注意：本地功能正常不等于联邦功能正常。任何涉及签名密钥、well-known 声明、server_name 的变更，都必须单独设计跨实例验证步骤，不能靠"发条消息试试"来确认。

所以迁移的准备工作里，第一件事不是备份数据库，而是画出你的实例和外部世界的接触面：有几个对外域名、well-known 指向哪里、TLS 证书由谁签发、server_name 是什么、有没有做反向代理、代理层有没有改写过路径。这些接触面在迁移中任意一个发生变化，都会牵出一串排查工作。

1.2 迁移能换来的收益，和它带走的成本

先说收益，这是推动迁移的正当理由。Continuwuity 作为后续分支，通常在几个方向上有实质改进：数据库层面对 RocksDB 的调优更细、配置项命名更接近直觉、可观测性接口更完整、对新版本协议特性的跟进更快。如果你的实例已经跑了几十万条事件，RocksDB 的压缩策略和写入放大就是绕不开的痛点，新分支在这块的默认参数往往比老分支合理。另外维护节奏也是考量——一个活跃维护的分支意味着安全更新能及时拿到。

成本这边要说透。迁移不是零成本操作：你要准备停机窗口（哪怕只有十几分钟）、要做数据快照（磁盘占用翻倍）、要重跑一遍配置映射（配置项改名是高频坑）、要在迁移后观察至少一周的联邦健康度。更隐性的成本是知识成本——新分支的配置项、日志格式、管理命令都可能变，值班的人得重新熟悉一遍。

我的建议是做一个简单的成本收益对照，别凭感觉拍板：

1.3 什么情况下，我建议先别动

有一种情况我见得最多：实例本身就跑得不稳，日志里天天有报错，用户偶发掉线，这时候主人想着"迁到新版本应该能解决"。这个逻辑很危险。迁移会把已有的不稳定放大，而不是消除。schema 迁移过程中对数据库的读写压力、新版本对资源占用的变化、配置项语义的细微差异，任何一个都会让原本潜伏的问题集中爆发。

判断标准很简单：迁移前先把现有实例的日志清一遍，跑满 72 小时，统计错误类型和频率。如果这 72 小时里出现超过个位数的数据库相关错误、联邦请求超时、内存持续上涨，那就先解决这些，再谈迁移。另一个明确的"暂缓信号"是：你手上没有一份经过验证可恢复的备份。所谓验证，不是"我备份了"，而是"我在另一台机器上用这份备份成功启动过一次，并且抽查了历史消息和媒体文件"。

2. 数据兼容性：数据库里到底存了什么

聊兼容性绕不开一个具体问题：Conduwuit 的数据库目录，Continuwuity 能不能直接认。答案取决于后端类型和 schema 版本两个变量，而这两个变量在真实环境里往往是组合出现的。

2.1 后端类型是第一道分水岭

Conduit 系的项目普遍支持两种后端：SQLite 和 RocksDB。SQLite 单文件、便于备份和搬运，适合小规模；RocksDB 走 LSM 树、写入吞吐高，适合事件量大的实例。两个后端在迁移里的表现差异极大。

SQLite 的情况相对友好。它的 schema 是显式的关系表结构，版本演进靠迁移脚本推进。从 Conduwuit 迁到 Continuwuity，如果两者都基于同一套核心表定义，那么理论上只存在"新版本追加了列/表"的情况，迁移脚本能自动补齐。风险点在于迁移脚本的执行顺序和外键约束——有些项目为了简化，关闭了外键检查再批量改表，中途失败会留下半迁移状态，这时候数据库既不是旧版本也不是新版本，只能从快照恢复。

RocksDB 这边麻烦一些。它是键值存储，表结构是应用层用前缀模拟出来的，所谓"schema 版本"通常以一个特殊的 key 存在库里。如果新版本要求的 schema 版本高于库里记录的版本，程序会在启动时触发迁移；如果低于，有些实现会直接拒绝启动。这就要求你在迁移前明确查清两边的 schema 版本号，而不是赌它能自动处理。

查版本的方式各项目不同，常见做法是启动日志里会打印当前 schema 版本，或者提供一个数据库管理子命令。如果找不到现成命令，一个稳妥的替代方案是：用旧版本启动一次，记录日志中的版本行；再用新版本以只读或 dry-run 模式启动一次，看它报什么。这一步在影子实例上做，不要碰生产库。

2.2 核心表结构与事件模型

无论哪个后端，逻辑上的数据结构是相似的。理解这几张核心表的作用，能帮你在迁移后快速定位问题：

这张表里最需要盯的是"事件"和"认证链"。一个房间的历史消息不是孤立存的，每条事件都依赖一条认证链来证明"这条事件在当时是合法的"。认证链只要断一环，整个房间可能加载不出来，表现出来就是客户端一直转圈或者报"无法加载房间历史"。迁移过程中如果事件表被部分重写、或者认证链的引用关系被新版本的序列化格式改变，就会出现这个问题。

我的经验是：迁移完成后，不要只测新消息，一定要挑三个老房间，往前翻至少两百条历史。这个动作能覆盖认证链的完整性检查，比任何日志分析都直接。

2.3 媒体文件：索引能重建，文件不能

媒体是迁移里最容易被低估的部分。大多数实现把媒体分成两半：实际文件按哈希散布在目录里，索引存在数据库中。这个设计的好处是去重，坏处是索引和文件如果对不上，客户端就会看到一堆裂图。

迁移时有两种处理策略。第一种是索引和文件一起搬，保持目录结构完全一致，这样迁移后不需要重建。这是推荐做法，前提是新旧版本的存储布局没有变化。第二种是只搬文件、让新版本重建索引，适合布局变更的情况，但代价是重建过程可能很长，且重建期间媒体访问会变慢。

判断布局有没有变，看两点就够了：文件是不是按哈希的前几位分桶存放、缩略图是独立文件还是内嵌。这两点在新旧版本间不一致的话，老老实实走重建路径，别硬搬。

注意：媒体文件是唯一"丢了就找不回来"的数据类型。数据库坏了还能从联邦侧重新拉取部分事件，媒体文件没有这个退路。备份时务必确认媒体目录被完整包含，并且做过抽样校验（随机挑几个文件，比对哈希）。

2.4 签名密钥与联邦身份的连续性

这是我认为整个迁移中最需要谨慎对待的部分，因为它直接决定你的实例在联邦网络里的"身份"是否延续。

联邦通信的基础是每个实例有一对签名密钥，公钥通过一个公开端点发布出去，其他实例缓存它。只要 server_name 不变、密钥文件不变，你在别人眼里还是同一个实例，历史事件的签名依然可验证。一旦密钥换了，所有已发出的历史事件签名就对不上，外部实例在验证旧事件时会失败。

所以迁移原则很清晰：把旧实例的密钥文件原样复制到新实例，配置文件里指向同一个路径，不要生成新密钥。密钥文件通常是一个文本文件，内容包含版本号、密钥 ID 和私钥，格式上 Conduit 系基本一致。复制过去后，先做个只读校验：用新版本启动，看日志里密钥 ID 是否和旧实例一致。

如果因为某些原因必须换密钥（比如旧文件丢失），那要做好心理准备：历史事件的可验证性会受损，部分外部实例可能拒绝你发出的旧事件，需要时间让网络重新接受。这种情况下的正确姿势是保留旧密钥做验证、新增密钥做签发，也就是密钥轮换而不是替换。具体是否支持多密钥共存，取决于版本实现，这点需要在影子环境里实测确认。

3. 三条升级路径，怎么选

路径选择本质上是在停机时间、风险暴露面、人力投入三个维度上做权衡。没有最优解，只有匹配你当前约束的解。

3.1 原地升级：停机最短，窗口最窄

做法很直接：停服务、备份、替换二进制、改配置、启动。整个过程可能只要十几分钟，用户体验接近"服务重启"。

优点是快、操作简单、不需要额外机器。缺点同样明显：一旦新版本启动失败或者数据迁移出错，你手上只有一份刚做的备份，恢复时间完全取决于备份体积。几百 GB 的 RocksDB，从快照恢复到可用状态，慢的话要按小时算。

这条路适合的场景是：实例规模小（数据量几十 GB 以内）、用户对短暂停机不敏感、你有信心在半小时内完成恢复演练。前提是你真的演练过——在影子环境里完整走一遍"备份→升级→启动→回滚"，把每步耗时记下来。

3.2 影子实例验证：多花一台机器，换确定性

这是我最推荐的路径，尤其对生产实例。核心思路是先不碰生产，用生产数据的副本在另一台机器上把新版跑起来。

具体做法：从生产快照恢复到影子机，配好新版程序，用不同的端口、不同的 server_name 或不同的对外入口启动，让它完全不干扰生产。然后在影子实例上做全套验证：老房间能否加载、历史能否翻页、媒体能否访问、联邦能否收发（用测试房间验证，不要用真实房间发消息）。

这套流程的价值在于，它把"未知问题"提前暴露在了一个没有任何损失的环境里。我在一次迁移中就是靠影子实例发现新版本对某个配置项的默认值改了，导致媒体访问路径拼接出错，所有图片 404。这个问题如果发生在生产停机窗口里，足够把十几分钟的迁移拖成两小时的故障。

代价是需要额外机器和存储。但你可以算一笔账：一台中等配置的云主机跑一天的成本，远低于一次两小时的生产故障带来的信任损失。

3.3 停机快照迁移：最稳，成本最高

第三种是彻底的"搬家式"迁移：停生产、做全量快照、把快照恢复到新机器/新目录、在新环境里配好新版、验证通过后再切流量。

它和原地升级的区别在于新旧环境物理隔离。旧环境原封不动地保留着，随时可以切回去。这给了你一个非常宝贵的缓冲：新环境哪怕跑了一周才发现问题，切回旧环境的成本依然很低（只要旧环境的数据没被新环境写入过）。

代价是磁盘占用翻倍、切流需要改 DNS 或反向代理配置、切流本身也有缓存和 TTL 的问题。适合数据量大、用户多、不能接受长时间故障的实例。

3.4 三条路径怎么选：一张对照表

我的实际选择通常是组合：先做影子验证，再用原地升级的方式在生产上执行。影子阶段解决"能不能跑"，生产阶段只需要重复一遍已验证的步骤，风险被压到最低。

4. 实操全流程：从快照到切流

下面这条流程以"影子验证 + 原地升级"为主线，每一步都说明意图。命令和配置项是示意性的，你需要替换成自己环境的实际路径和名称。

4.1 迁移前的基线记录

这一步最容易被跳过，但它决定了出问题时你能不能判断"是不是迁移导致的"。要记录的东西包括：当前数据目录总大小、事件数量级、用户数、房间数、当前版本号、当前配置文件的完整内容、当前对外域名和 well-known 内容。

# 记录数据目录体积与文件数 du -sh /var/lib/conduwuit find /var/lib/conduwuit -type f | wc -l # 记录当前版本与启动参数 /usr/local/bin/conduwuit --version systemctl cat conduwuit > /root/baseline-systemd.txt cp /etc/conduwuit/conduwuit.toml /root/baseline-config.toml # 记录对外 well-known 内容 curl -s https://your-domain/.well-known/matrix/server curl -s https://your-domain/.well-known/matrix/client

这些文件的用途很实际：迁移后如果发现用户登录异常，你可以立刻比对配置里认证相关的项有没有被改；如果发现联邦不通，可以直接对比 well-known 的输出有没有变。没有基线，所有排查都变成猜。

同时把当前日志的最后 500 行存档。迁移后如果出现新错误，能快速判断是新问题还是老问题延续。

4.2 停服与快照：顺序不能错

正确顺序是先停服务，再打快照。反过来的话，快照里会包含正在写入的数据，RocksDB 这类存储在有写入的情况下做文件级复制，恢复出来大概率是损坏的。

# 1. 停止服务，确认进程完全退出 systemctl stop conduwuit sleep 5 pgrep -a conduwuit || echo "已停止" # 2. 做一致性快照（文件系统级或存储级均可） # 这里用 rsync 到独立磁盘作为示例，生产建议用存储层快照 rsync -aHAX --delete /var/lib/conduwuit/ /backup/conduwuit-snap-$(date +%F)/ # 3. 校验快照体积与源基本一致 du -sh /var/lib/conduwuit /backup/conduwuit-snap-*

如果用的是支持快照的存储（LVM、ZFS、云盘快照），优先用存储层快照，速度和一致性都更好。文件级复制在数据量大时可能耗时很久，这段时间停机窗口会拉长。

注意：RocksDB 有一个 WAL 目录，里面是尚未落盘的写入。正常关闭会触发 flush，但如果你用 kill -9 强杀，WAL 里可能还有数据。所以停服务一定要用 systemd stop 或发送 SIGTERM，等进程自己退出，别图快直接 kill。

4.3 配置文件映射：改名是高频坑

配置项改名是迁移中最琐碎也最容易出错的部分。两个分支各自演进，同一个语义的配置项可能叫不同名字，或者默认值被调整。

处理方式建议是不要在新旧配置之间做增量修改，而是以旧配置为清单，逐项在新版本的配置模板里找对应。做法是先把新版本的示例配置完整拉下来，然后拿旧配置的每一项去对照，在表格里记录"对应项 / 是否改名 / 默认值是否变化"。

# 旧配置中常见的几类项，迁移时逐项核对 [global] server_name = "example.org" # 联邦身份，绝对不能改 database_path = "/var/lib/conduwuit" database_backend = "rocksdb" # 与数据目录内容必须匹配 port = 8008 # 密钥相关，必须指向原有文件 key_path = "/var/lib/conduwuit/conduwuit_key.pem" # 媒体相关，路径变化会导致全部 404 media_path = "/var/lib/conduwuit/media" # 联邦与代理 [global.well_known] client = "https://example.org" server = "example.org:443"

几个必须死守的原则：server_name 不变、密钥文件不变、媒体路径指向原目录、database_backend 与数据实际格式匹配。这四项任意一项搞错，症状都很明显但排查方向完全不同——server_name 错会表现为联邦全面失败，backend 错会表现为启动即崩，媒体路径错表现为图片全裂。

配置里还有一类是性能参数，比如 RocksDB 的写缓冲大小、块缓存大小。这些可以迁移后再调，先用接近旧配置的值保证行为一致，稳定跑几天再做优化。不要在同一次变更里既换程序又调参数，出问题时你分不清是谁的锅。

4.4 数据库拉起与 schema 迁移

这一步是整个流程里最需要盯日志的环节。新版程序启动时会检查 schema 版本，需要迁移就自动执行。执行期间可能有大量日志输出，也可能耗时几分钟到几十分钟不等。

# 前台启动，方便观察迁移过程 /usr/local/bin/continuwuity --config /etc/conduwuit/conduwuit.toml # 关注日志中的关键字 # schema / migrate / version / upgrade / error / panic

启动过程中如果看到panic，基本可以判定失败，直接停掉、从快照恢复、回去查原因。如果只是 WARN 级别，先记下来，等启动完成再逐条评估。

schema 迁移完成后，做一轮快速健康检查：

• 用管理员账号登录，确认能进
• 列出房间列表，确认数量与基线一致
• 随机进三个房间，往前翻页
• 检查一个有媒体的房间，图片能否加载

这几项全过，说明核心数据没问题。任何一项失败，都建议先回滚再分析，不要在部分可用的状态下继续往下走。

4.5 联邦验证与灰度切流

联邦验证必须用独立的测试房间，不要拿真实用户房间做实验。做法是在测试房间里加入一个外部实例的测试账号（或者反过来，从外部实例加入你的测试房间），观察加入流程是否走通。

验证点包括：外部实例能否解析你的 server_name、能否获取你的签名公钥、加入请求是否被正确签名、事件能否双向同步。如果加入成功但事件不同步，问题通常在出站队列；如果加入直接失败，问题在签名或 well-known。

切流阶段的灰度策略取决于你的入口结构。如果是单机部署、DNS 直接指向，那切流就是改记录，注意 TTL 要提前调低（比如迁移前 24 小时把 TTL 从 3600 改成 300），避免缓存让部分用户长时间连到旧地址。如果有反向代理层，切流就是改 upstream，更可控，还能做按比例分流。

切流后 24 小时是观察重点期。要盯的指标：错误日志中联邦相关条目的数量、出站队列是否堆积、内存和 CPU 是否在正常区间、客户端重连频率。

5. 常见故障与排查速查表

下面这些是我和同行在迁移中真实遇到过的类型，按症状归类，附上定位思路。

5.1 启动即崩：先看后端和版本

最常见的启动失败是数据库后端不匹配。配置里写sqlite，但数据目录里是 RocksDB 的目录结构，程序找不到预期的文件，直接退出。反过来也一样。

第二常见的是schema 版本高于程序支持。这种情况通常发生在你从快照恢复了新版本写过的数据，然后又用旧版本启动。程序检测到版本超前，拒绝启动是对的，硬降级会损坏数据。

5.2 联邦不通：三个检查点

联邦问题排查有个固定顺序，按这个顺序走基本能定位：先查 server_name，再查密钥，最后查 well-known 和网络出口。

server_name 决定别人怎么找你，它在配置里变了但 DNS 和证书没跟着变，就会全面失败。密钥决定别人信不信你，密钥文件被替换或者路径指错，表现是别人拒绝接收你的事件。well-known 决定客户端怎么连，它错了本地用户可能都登录不了。

可以用几个公开的诊断手段辅助：检查你对外暴露的密钥端点返回内容是否与本地密钥匹配；从外部视角检查 well-known 的解析结果；查看出站队列是否有大量重试。多数实现会提供一个联邦相关的管理命令，能查某个目标实例的可达性和密钥状态，有的话优先用它。

5.3 媒体 404：先分清索引问题还是文件问题

媒体打不开分两种情况，处理方式完全不同。

文件在、索引没了：新版本没找到元数据，但文件目录里的文件还在。这种可以触发索引重建，多数实现有对应的管理命令或配置开关。重建期间访问会变慢，但不丢数据。

索引在、文件没了：这是真丢数据。原因通常是迁移时只搬了数据库没搬媒体目录，或者媒体路径配错指向了空目录。检查方式很直接：去配置的 media_path 下看有没有文件，文件数量和数据目录体积是否合理。

还有一种隐蔽情况：文件在、索引也在，但目录分桶规则变了。旧版本按哈希前 2 位分桶，新版本按前 3 位，索引里存的路径对不上实际路径。这种只能重建索引。

5.4 性能回退：别急着调参

迁移后感觉变慢，先别动配置。按这个顺序看：操作系统层面的 IO 是否打满、内存是否被 RocksDB 的块缓存吃掉、是否有后台任务在跑（比如索引重建、事件压缩）。

新版程序如果默认开启了某些后台优化任务，前几个小时性能波动是正常的。等任务跑完再评估。真正需要调的场景是：稳定运行三天后，P99 延迟仍明显高于迁移前，且 IO 和内存都不是瓶颈——这时候才去比对两边的性能参数默认值。

6. 回滚边界与长期维护

6.1 明确"过了哪个点就回不去了"

回滚不是永远可行的。新版本一旦开始写入数据，特别是执行了 schema 迁移之后，旧版本通常无法再读这份数据。这个点就是你的不可逆边界。

所以回滚策略要围绕这个边界设计：在 schema 迁移完成并验证通过之前，快照是你唯一的退路；验证通过、服务稳定运行之后，回滚的成本就变成"从快照恢复 + 丢失迁移后产生的新数据"，通常不再划算。

实操上的建议是：把不可逆点尽量往后推。具体做法是先在新环境里跑只读验证（加载房间、翻历史、看媒体），确认数据能被正确解读，再让它开始接受写入。这个顺序能让你在不产生任何新数据的情况下发现问题。

6.2 迁移之后，运维习惯要跟着改

程序换了，一些日常习惯也得调整。日志格式可能变了，原来的 grep 关键字失效；管理命令可能有增删，脚本里的调用要更新；配置项的默认值变了，某些原本靠默认值工作的行为可能悄悄改变。

我的做法是迁移完成后立刻做三件事：把新的日志关键字整理成一份速查表贴在值班文档里；把常用的管理命令重新跑一遍并记录输出格式；把配置文件里所有依赖默认值的项显式写出来，避免以后升级时被默认值变更坑到。

最后分享一个我觉得最值的小技巧：给迁移前后的实例都加一个每日自动检查任务，内容是登录测试账号、发一条消息到测试房间、访问一个媒体文件、检查出站队列长度。这个任务跑起来之后，任何数据层的渐进式损坏都会在 24 小时内暴露，而不是等到用户投诉。这套检查我在几次迁移里都保留了，成本几乎为零，但救过两次——一次是媒体索引在后台任务里被意外清理，一次是出站队列因为某个目标实例不可达而持续堆积。