把跑着的书签服务从一台 VPS 平滑搬到另一台：一次跨机迁移实录

摘要：我的书签服务 Karakeep 原本跑在一台 2 核 2GB 的香港云服务器上，随着书签和附件越来越多，这台机器开始吃紧。正好新到手一台新加坡的 2 核 4GB 机器，我把整个服务——三个容器、全部书签数据、证书和备份任务——平滑搬了过去，全程书签一条没少，旧机器停机保留当回滚。这篇文章记录迁移的顺序、两个真实踩到的坑，以及搬完的验收清单。

一、为什么要搬

先交代背景。我的书签服务是一个自托管的稍后读工具：看到好文章点一下收藏，服务自动抓取正文、截图，还会调 AI 给每条书签打标签。它跑在 Docker 里，一共三个容器，数据存在数据卷里。这套东西最开始落在香港那台 2 核 2GB 的机器上，因为当时只有那台机器有空位，而且它和我的 AI 网关在同一台机器上，打标签的调用走内网就能到网关，延迟低。

但 2GB 内存的机器上同时跑的东西不少：书签服务、AI 网关、还有几个小服务。平时还行，一到 AI 批量打标签或者浏览器容器抓取重页面的时候，内存就绷得很紧。之前我已经给这台机器加了 Swap、做了 Nginx 入口和备份，稳定性是稳住了，但天花板就在那里，再往上加东西没空间了。

新到手的新加坡机器是 2 核 4GB，系统盘实测 59GB，带宽 30Mbps，每月 2TB 流量，每月不到七十块钱，还是用成长中心的代金券抵的。配置翻了一倍，价格没涨。更关键的一点是：这台新机器是我手里唯一一台 AI 三家服务全部可达的华为云机器，书签打标签要调的模型都能直连。于是决定搬：书签服务去新加坡，AI 网关继续留在香港机，两边分工，香港机也顺带减了负。

迁移之前我给自己定了三条原则：第一，迁移当天不升级、不改配置，只搬家，出了问题才知道是搬家的问题还是升级的问题；第二，旧机器不删，停机保留，随时能回滚；第三，搬完要有一张验收清单，逐项打勾才算完，不能凭感觉说“好像能用了”。

二、搬之前先想清楚的五件事

动手之前，我先把这五件事想明白，写在纸上——迁移最容易翻车的地方从来不是命令敲错，而是有一件前置工作漏了。

第一，备份先行。 迁移本质上就是一次异地恢复：数据卷整个搬过去，容器拉起来，服务恢复原样。所以动手前先做一次完整备份，而且备份脚本本身就是现成的——每天跑的那套，SQLite 一致性快照加对象存储双写。这次手动触发一次，确认备份文件新鲜、哈希对得上，再开始搬。备份在手，后面每一步都有底气。

第二，数据到底在哪。 三个容器里，真正不能丢的是数据卷：书签记录、附件、正文快照都在里面。容器本身是可以重建的，镜像重新拉一份就行；数据卷丢了就真丢了。所以迁移清单上第一行就是数据卷的路径和大小，先 du 看一眼，心里有数——几百 MB 还是几个 GB，决定了传输要多久、中间要不要压缩。

第三，DNS 和证书怎么处理。 书签服务的域名解析指向旧机器，搬完之后要把 A 记录切到新机。证书我选择直接复制过去：Let’s Encrypt 的证书文件连同续期定时器一起搬，到期日是明年一月，复制过去之后续期照常走，不用重新签发。重新签发也不是不行，但复制更稳——迁移当天少一个变量就少一分风险。

第四，AI 打标签的链路不动。 打标签走的是我自建的 AI 网关，网关在香港机上，这次不搬。也就是说新机上的书签服务打标签时，要跨机器调网关。这条链路本来就是通的，迁移后只需要确认新机到网关的连通性，不用改任何配置。网关不动，也意味着迁移的影响面被锁死在书签服务自己身上。

第五，新机器先入网、再接活。 新机到手先做入网标配：装监控 agent 进统一监控面板、按 fleet 政策关掉 MPTCP、加进内网组网。4GB 内存够用，这次没加 Swap——Swap 是给 2GB 机器削峰用的，4GB 没必要先上，等真吃紧再说。入网做完、监控面板里能看到新机在线，才开始搬服务。顺序反了的话，服务搬过去了却没人盯着，等于裸奔。

三、搬的顺序：七步

顺序是我这次实际走的流程，每一步做完确认没问题再走下一步：

1. 停旧服务，冻结写入。 先把旧机器上的三个容器停掉。这一步是必须的：数据卷在容器运行时是活的，直接打包可能抓到一半写入一半的状态。停容器就是给数据一个静止的切面。停之前顺手记下书签总数——这是搬完验收时要对的第一个数。

2. 打包数据卷。 把数据卷目录打包压缩。数据量不大，压缩后传起来更快。包打好之后算个哈希，传过去再算一次，对不上就重传，别等容器起来才发现数据是坏的。

3. 传到新机，解开。 用 rsync 之类的工具把包传到新机对应目录。示例只是示意，实际按自己的目录来：

rsync -avz karakeep-data.tar.gz 新机:/opt/karakeep/

传完先对哈希，再解开。哈希对不上、解压报错，都在这是拦下来，别往下走。

4. 起容器，查状态。 新机上的编排文件和旧机保持一致，镜像名写全名加标签再起容器——这是我之前翻车换来的教训，镜像引用一定要写完整形式，不能只写短名或裸 ID（论坛不允许出现外部域名，镜像地址里的点号两侧加了空格，实际配置里没有空格）：

services:
  karakeep:
    image: ghcr . io/karakeep/karakeep:latest
    restart: unless-stopped

容器起来后先看状态：三个容器是不是都 healthy，有没有反复重启的。状态不对先看日志，别急着切流量。

5. 本地验证。 在新机上先不切 DNS，直接用内网地址或临时端口访问：登录能不能进、书签总数和旧机记的数对不对得上、随手点几条书签看正文和附件在不在、触发一次 AI 打标签看跨机器调网关通不通。这一步全绿，才值得往下走。

6. 切 DNS，搬证书。 把域名解析的 A 记录切到新机，证书文件复制过去，Nginx 入口配置里的域名用占位写法，实际填自己的域名：

server {
    listen 443 ssl;
    server_name karakeep.example.com;
    location / {
        proxy_pass http://127.0.0.1:3000;
    }
}

切完等解析生效，用手机流量和家里宽带各测一次——两种网络看到的解析结果一致、证书正常、登录正常，才算切过去了。解析这东西有缓存，别只在自己的电脑上测一次就下结论。

7. 备份改指，试跑一次。 每天跑的那套备份脚本，把目标主机改指新机，然后手动触发一次完整备份，确认对象存储双写都成功。这一步最容易忘：服务搬走了，备份还指着旧机器，等于新数据没人兜底。试跑成功之后，迁移才算真正收尾。

走完这七步，旧机器上的三个容器保持停机状态，不删除——这就是回滚方案。万一新机出问题，DNS 切回去、旧容器起起来，十分钟就能回到迁移前。

四、两个真实踩到的坑

坑一：新机器的出厂 DNS 有问题。 新机刚到手就发现解析不太对劲：有些域名解析慢，有些直接失败。查下来是云厂商 VPC 默认的解析器不太可靠。这不是迁移特有的问题，是新机入网的出厂坑，但它偏偏在迁移当天冒出来，差点让我以为是服务搬坏了。

解决办法是把 DNS 写死：netplan 里锁定两个公共解析地址，并且设为持久配置，重启也不丢；同时把内网组网的接受 DNS 关掉，防止组网客户端把解析器又覆盖回去：

network:
  version: 2
  ethernets:
    eth0:
      nameservers:
        addresses: [1.1.1.1, 223.5.5.5]

教训是：新机器到手先跑一轮基础自查——解析、时间同步、出站连通性——再接活。基础环境的问题越早发现，定位成本越低；等服务搬上去了再查，排查范围就大得多。

坑二：线路实测结果决定了这台机器的定位。 搬之前我测了新机的线路：到香港约 40ms，到我另一台国内云服务器约 164ms 且非常稳定，但到广州联通约 412ms 还有丢包。结论很清楚：这台机器国际方向优秀，回国方向不适合当直连入口。书签服务是后台型服务，我自己偶尔打开看看，412ms 的回程完全可以接受；但如果以后想把面向国内用户的服务放上来，这台机器就不合适。

这个坑的价值在于：机器的定位应该由实测决定，而不是由配置决定。2 核 4GB、30Mbps 这些数字看着不错，但线路才是决定它能干什么的硬约束。迁移前花十分钟测一轮，比搬完发现访问慢再搬一次强得多。

五、搬完的验收清单

迁移收尾不是“服务能打开了”就结束，我按这张清单逐项打勾：

• 三个容器状态全部 healthy，没有反复重启；
• 书签总数和迁移前记的数一致，随机抽查的正文、附件都能打开；
• 登录正常，注册保持关闭；
• 触发一次 AI 打标签，新机到香港网关的调用成功，标签正常落库；
• 域名解析在两种网络下都指向新机，证书有效、续期定时器在位；
• 备份脚本已改指新机，手动试跑一次双写成功；
• 监控面板里新机在线，旧机三个容器停机保留，未删除。

七项全绿，才算搬完。任何一项不过，就停在那一项修，不往下赶进度。

总结

这次迁移拆开看并不复杂，核心就三句话：先备份、再小步、留回滚。备份是底气，小步是每一步都可验证，留回滚是给自己留后路。迁移当天不升级、不改配置，只搬家——把变量减到最少，出问题也好定位。

另外两个体会：第一，新机器先入网、做基础自查再接活，出厂 DNS 这种坑在空载时发现只需要十分钟，在满载时发现可能就是一晚上；第二，机器的定位由线路实测决定，配置数字只是参考，搬之前测一轮线路，搬完就不用为访问慢返工。

书签服务在新机器上跑到现在，三个容器一直 healthy，书签一条没少，备份每天正常双写。旧机器停机保留着，香港机上的网关也没动过——分工比迁移前更清晰了，这大概就是这次搬家最大的收获。