别让用户在迁移中途写数据：vibe 项目的维护模式与只读窗口实战

__MEDIA_1__

一句话先把道理讲透：维护模式不是“一块‘正在维护’的牌子”，而是一套“在你动数据库和计费逻辑的时候，保证用户写进来的数据不会丢、不会错、不会写一半”的机制。牌子谁都会挂，难的是牌子挂上去之后，后台的写请求、定时任务、队列、Webhook 一个都不能漏网。这篇讲的就是这套机制怎么做才算做全。

文中示例产品“云杉记账”与创始人“陆遥”均为虚构，仅用于讲清流程，不对应真实产品。

先划界：这篇和状态页、故障手册不是一回事

站内已有状态页指南和故障处理手册，它们讲的是“出事了怎么对外沟通、怎么排查恢复”。本篇讲的是相反的场景：事情是你主动安排的——数据库迁移、计费系统切换、大版本结构调整，你提前知道要停一段时间。与之相邻的还有灰度发布和功能开关指南：灰度是“让一部分用户先用新版本”，功能开关是“某个功能单独开合”；而维护模式是“全站或整类写操作先停下来”，三者解决的问题不同，别互相替代。

判断要不要上维护模式，只看一个标准：这次变更进行中，用户如果继续写数据，会不会产生事后无法自动修复的脏数据？数据库字段重命名、账单表结构调整、权限模型重构，答案都是会，那就必须上。反之，纯前端改版、只加字段不改旧字段、加一张新表，大多不需要停写，别为了仪式感挂牌子——每次不必要的停机，都是在消耗用户对你的信任。

三档模式：别一上来就全站关停

维护模式不是只有“开”和“关”两个状态。一人团队最常用的其实是中间两档，提前定好，变更当天不用临时拍脑袋：

• 全站维护：所有页面只显示维护页，所有写请求一律拒绝。只用于数据库迁移、机房级切换这种“动一下就可能全乱”的变更。窗口要最短，能 20 分钟做完就别拖到 2 小时。
• 只读模式：用户能看、能导出、不能写。这是最被低估的一档：大多数迁移其实只需要“别再有新数据进来”，旧数据随便看。只读能把用户的不满降到最低，因为“我要查个旧账单”这种需求不会被挡在门外。
• 部分功能关闭：只关受影响的功能，比如只关“新建账单”，但查看、导出、设置都正常。适合计费切换、某个模块重构。实现成本最高，因为每个入口都要单独判断，但用户体验最好。

云杉记账（虚构）第一次做账单表迁移时直接上了全站维护，用户正在对账却被踢出门，客服邮箱炸了一晚上。第二次改成只读模式：能查不能记，提前一周在应用内发通知，迁移当晚的投诉是零。档位选对，效果差别就是这么大。

技术实现：一处开关，全链路都要认

维护模式最常见的翻车方式，是“前端挂了牌子，后端还在接单”。用户看到维护页，转头用旧 App 版本、浏览器插件、甚至直接调 API 照样把数据写进来，迁移完一对账全是幽灵数据。所以开关必须放在后端，而且是所有写路径都认同一个开关。

最小可行的实现是四件套：第一，一个服务端可读的配置开关（环境变量或配置表都行，别只存在前端代码里），所有写接口在入口处先查它；第二，写请求被拒绝时返回 503 状态码并带上 Retry-After 头，告诉调用方“过多久再来”，而不是 200 加一句“系统维护中”——前者能让客户端和重试逻辑正确处理，后者会被当成成功；第三，静态维护页要脱离主应用部署（对象存储上放一个纯 HTML 页即可），这样即使主应用正在重启，用户也能看到维护页而不是连接超时；第四，管理员要有绕过通道（比如带特定 Header 的内部账号），否则你自己都进不去验证迁移结果。

开关之外，还有四条容易漏的链路，变更前必须逐一关掉或排空：定时任务（迁移期间跑起来的对账、扣费、发信任务，写进的可能是旧结构数据）；消息队列（队列里躺着的任务会在迁移后继续执行，执行前要确认它读的是新结构）；第三方 Webhook（支付成功回调在维护期间到达时不能丢，要先接住、存下来、恢复后重放，而不是直接返回失败让对方放弃）；以及客户端缓存的“离线写操作”（App 端攒着的离线提交会在恢复后一股脑涌进来，恢复后第一小时要盯着写量曲线）。

沟通节奏：提前说、进行中说、恢复了还要说

技术做对了，沟通没跟上，用户照样觉得你不靠谱。维护沟通分三段，每段缺了都会出问题：

提前通知至少提前一周、在用户每天都会看到的地方发：应用内横幅、登录后弹窗、邮件三选一即可，但不要只发在没人看的博客上。通知要写清四件事：开始和结束时间（带时区）、影响范围（是全站不能用，还是只能看不能写）、用户需要提前做什么（比如“请在周五 22 点前完成本周对账”）、以及恢复后会有什么变化。别写“系统升级，敬请期待”这种空话，用户要的是“我会不会丢数据”，不是你的升级口号。

进行中的维护页同样要写清四件事：现在是什么状态、预计什么时候恢复（给一个具体时间点，而不是“尽快”）、恢复后用户需要做什么（通常是“什么都不用做”）、以及紧急联系方式（邮箱即可）。如果预计时间推迟了，维护页上的时间也要同步改——用户可以接受维护变长，不能接受页面上的时间一动不动、像没人管一样。

恢复后还要发一次简短公告：维护已完成、持续了多久、有没有需要用户注意的变化。如果迁移中发现并修复了个别用户的数据问题，要单独通知受影响的用户，而不是在公告里轻描淡写带过。信任就是这样一次次攒起来的。

只读模式下的五个坑

只读模式听起来简单，实际有五个坑专门坑第一次做的人：第一，搜索与导出功能可能内部也写数据（比如记录搜索历史、生成导出文件），这些“看起来是读、实际是写”的操作要单独放行或临时关闭；第二，页面上的“写按钮”不能只是变灰，前端变灰挡不住直接调 API 的人，后端接口必须同样拒绝；第三，登录与注册要想清楚：只读期间新用户能不能注册？通常应该允许注册、但注册后同样只读，否则新用户第一印象就是一扇关着的门；第四，缓存：维护期间 CDN 和应用缓存里可能还留着旧页面，恢复后要主动清一次关键页缓存，否则用户看到的还是维护页；第五，恢复后不要立刻全量放开，先放 10 分钟观察写量、错误率、队列堆积，确认曲线正常再宣布恢复完成。

一份可以直接抄的执行清单

变更前一周：定档位（全站/只读/部分关闭）、写通知文案、发应用内横幅与邮件、准备静态维护页、确认管理员绕过通道可用、列出所有定时任务与队列并定好暂停与排空方案。变更当天：提前 30 分钟再发一次提醒、到点开开关、验证写请求确实返回 503、验证维护页可访问、暂停定时任务、开始迁移。迁移完成：先内部验证读写、清关键缓存、放开 10 分钟观察、确认无异常后发恢复公告、恢复定时任务与 Webhook 重放、第二天复盘写量与错误日志。

最后一句提醒：维护模式的真正成本从来不是那块牌子，而是你有没有在动手之前，把“谁还可能写进来”这个问题问全。问全了，20 分钟的迁移就是 20 分钟；问漏了一条，恢复后你要花一个周末去修脏数据——而用户只会记得那一次。

开关放哪里：三种存放方式的取舍

维护开关听起来就是一个布尔值，但放在哪里直接决定了变更当天的操作体验。三种常见方式各有利弊，一人团队按下面这张对照选：环境变量最简单，改一次要重启应用，适合“变更窗口固定、重启本身就是计划一部分”的场景，缺点是改动慢、改错了回滚也要重启；配置表最灵活，后台改一行立即生效，还能记录“谁在什么时候开了关”，适合需要“先开 10 分钟观察、随时能关回去”的场景，缺点是配置表本身如果正在迁移，就成了“用要迁移的库来控制迁移”的循环依赖——这时要把开关表单独放在不受迁移影响的库或配置服务里；功能开关服务最省心，但要多接一个外部服务、多一份账单，对一年只做两三次维护的一人团队来说通常过重。

云杉记账（虚构）的做法值得抄：开关放在独立的配置表里，表结构只有四列——键、值、更新人、更新时间；维护开关的键单独命名，不与任何业务表同库迁移；后台管理页上这个开关有二次确认弹窗，防止手滑点错。变更当天，陆遥（虚构）一个人就能在管理页上开关，不用改代码、不用重启、不用求助任何人——这才是一人团队要的维护开关。

迁移当天的分钟级时间表

把“变更当天”写成一张分钟级时间表，贴在团队文档里（哪怕团队只有你一个人），能避免一半的手忙脚乱。下面是 22:00 开始、预计 40 分钟的只读迁移示例，时间点按你的实际情况调整，但结构可以直接抄：21:30 发最后提醒（应用内横幅 + 邮件），提醒用户“22:00 起只能查看、不能记账”；21:55 确认队列已排空、定时任务已暂停、Webhook 接收端已切换为“存下来、暂不处理”；22:00 开只读开关，立即用普通账号验证“查看正常、写操作返回 503”，再用管理员账号验证绕过通道可用；22:05 开始迁移，迁移过程中每 10 分钟在维护页上更新一次进度（“正在迁移账单表，预计 22:40 恢复”）；22:35 迁移完成，先内部验证读写、再清关键缓存；22:40 放开 10 分钟观察写量与错误率；22:50 确认正常后发恢复公告、恢复定时任务、开始重放 Webhook；次日上午复盘错误日志与写量曲线。

时间表里最容易漏掉的两项是“验证写操作确实被拒绝”和“验证管理员绕过通道可用”。前者漏掉，等于牌子挂了、门没锁；后者漏掉，等于把自己也锁在门外、迁移结果没法验证。这两项验证加起来不到 2 分钟，但能挡住最尴尬的两种翻车。

恢复后复盘：写一份下次能直接用的记录

维护结束后的复盘不用写成长篇大论，记好六项就够：计划窗口与实际窗口各是多久、实际影响了多少用户（只读期间的访问量、被拒绝的写请求数）、有没有脏数据、脏数据怎么发现、怎么修复的、有没有用户投诉、投诉集中在哪个环节、下次同类变更要改什么。云杉记账（虚构）第二次迁移的复盘只有半页纸，但第三次做计费切换时，陆遥（虚构）直接照着复盘里的“Webhook 重放顺序”一条条执行，零事故——复盘的价值不在写得漂亮，而在下次能直接照着做。

复盘里还要单独记一笔“沟通是否到位”：提前通知的打开率、维护页的访问量、恢复公告发出后有没有用户继续问“怎么还不能用”。如果恢复公告发出 1 小时后仍有用户反馈看到维护页，八成是缓存没清干净，下次复盘里就要把“清缓存”从“迁移完成”一项里拆出来、单独列为恢复步骤，而不是事后才想起来。

常见问题：上线前一定会被问到的五个

“能不能不做维护模式、直接在线迁移？”——很多时候可以：只加字段、只加表、双写过渡，都是在线迁移的成熟做法。本篇的立场不是“每次变更都要挂牌子”，而是“当你判断在线迁移会产生无法自动修复的脏数据时，别硬撑”。双写过渡本身也是成本，要算清楚再选。

“维护期间用户正在填的表单怎么办？”——表单页在开关打开前就要提示“22:00 起将进入只读，请提前提交”。已经打开表单的用户，提交时会收到 503 与明确文案“系统正在维护，您的内容未保存，请在恢复后重新提交”。更体贴的做法是：只读开关打开前 10 分钟，前端对未提交的表单做一次本地暂存提示，让用户把内容先复制出来——但不要承诺“恢复后自动提交”，那会把简单问题变复杂。

“App 用户不升级旧版本怎么办？”——旧版本 App 不认维护开关、继续调写接口时，后端 503 是最后一道防线。所以维护开关必须在后端、而不是只在前端判断。旧版本用户看到的可能是通用错误提示，这时要在错误文案里写清“系统正在维护，请稍后再试”，而不是冷冰冰的错误码。

“维护窗口选在什么时候最好？”——看你的用户活跃曲线，而不是拍脑袋定凌晨。云杉记账（虚构）的用户晚上 22 点后活跃度最低，窗口就定在 22:00；如果你的用户遍布多个时区，就没有“所有人都不活跃”的时段，那就选“影响最小”的时段、并把窗口压到最短，同时用只读模式代替全站关闭。

“一年要做很多次维护，怎么办？”——如果一年超过四次，说明你的变更方式本身需要改进：把大迁移拆成多次小迁移、能在线做的就在线做、双写过渡代替停机。维护模式是安全带，不是常规操作；安全带一年用四次是保护，天天系着就是流程有问题。

补充一句：如果你是第一次做维护模式，别把第一次就押在最重要的迁移上。先找一次影响小的变更练一遍完整流程——发通知、开只读、验证拒绝、恢复、发公告、复盘——全套走下来不过半天，但能让你在真正关键的迁移夜里，每一步都知道下一步该干什么。