Что откату позволено удалять
«Откати проект на вчера» звучит как одна операция. Это не так. Проект на этой платформе разнесён по трём хранилищам с совершенно разными моделями надёжности и идентичности:
- Исходники — файлы в отдельном git-репозитории проекта
(
/data/projects/{id}), одно рабочее дерево, содержащее каждое приложение подapps/{slug}/. - Рантайм — Kubernetes Deployments, Services и правила Ingress в неймспейсе проекта, сгенерированные из спеки.
- Данные — ветка Postgres с копированием при записи на общем хранилище Neon,
плюс реляционные строки (
project_apps, ревизии плана), описывающие, что вообще существует.
Откат должен заставить все три хранилища сойтись на одном и том же моменте прошлого. Само восстановление — сделать checkout этого коммита, форкнуть таймлайн Neon на нужном LSN — это лёгкая половина. Половина, которая реально решает, можно ли доверять путешествию во времени, — это снос: когда вы откатываетесь к точке, где фичи ещё не было, что именно вы физически удаляете и как гарантируете, что снова сможете двинуться вперёд?
Ошибитесь в одну сторону — и откат окажется ложью: спека говорит, что фичи нет, но её код всё ещё лежит на диске, а её контейнер всё ещё обслуживает трафик. Ошибитесь в другую сторону — и откат окажется разрушительным: вы удалите то, что не сможете вернуть, и «обратимое путешествие во времени» тихо перестанет быть обратимым.
Этот пост — правило, к которому мы пришли, и почему каждое хранилище ему подчиняется.
Форма задачи
Конкретно: проект — это todo-приложение. Позже у него вырастает второе
приложение — блог — со своими исходниками под apps/blog/, своим Deployment и
Service app-blog, правилом маршрутизации на общем превью-Ingress и несколькими
строками в Postgres. Затем пользователь откатывается к снапшоту, снятому до
того, как блог появился.
Что значит «до блога» для каждого хранилища:
target snapshot now
git source ───────────●──────────────────────● blog files committed after ●
k8s runtime ───────────●──────────────────────● app-blog Deployment running
neon data ───────────●──────────────────────● blog tables written after ●
project_apps ───────────●──────────────────────● blog app row created after ●
Каждое хранилище должно оказаться в левой точке. Но откатываются они по-разному, и наивная операция «по хранилищу» неверна для двух из трёх.
Исходники: «восстановить файлы» — это не «совпасть с коммитом»
Первый инстинкт — git checkout <target> -- .. Он ошибочен, причём неочевидно.
git checkout <commit> -- <pathspec> обновляет рабочее дерево для путей, которые
существуют в <commit>. Файл, добавленный после целевой точки — любой
исходник блога, — в целевом дереве отсутствует, поэтому checkout его просто не
упоминает. Он остаётся на диске. Дальше вы делаете git add -A и коммит, и
коммит-«восстановление» добросовестно фиксирует дерево, в котором блог всё ещё
есть. Откат отработал, дифф выглядел правдоподобно, и ничего не удалилось.
Решение — заставить рабочее дерево совпасть с целевым точь-в-точь, включая удаления. Мы вычисляем набор путей, добавленных между target и HEAD, и удаляем их явно:
// project-git.js — restoreVersion()
await snapshotWorkingTree(dir, `restore: working-tree snapshot before reverting to ${short}`);
// Files present in HEAD but absent in the target tree (added after the target).
const addedSince = await git(dir, ["diff", "--name-only", "--diff-filter=A", target, "HEAD"]);
await git(dir, ["checkout", target, "--", "."]); // restore modified/deleted paths
if (addedSince.length) {
await git(dir, ["rm", "-f", "--ignore-unmatch", "--", ...addedSince]); // remove added-since
}
await git(dir, ["add", "-A"]);
await git(dir, ["commit", "-m", `restore: reverted to ${short}`]);
(git read-tree -u --reset <target> делает то же самое в один ход; мы оставляем
явный checkout-плюс-удаление, потому что баг, который он чинит, ровно про то,
какие файлы не упомянуты, и код читается именно как это намерение.)
Одна деталь здесь чрезвычайно важна, и мы к ней ещё вернёмся: восстановление — это новый коммит поверх HEAD. Мы никогда не двигаем указатель ветки и не переписываем историю. Коммит до отката — тот, что с блогом, — по-прежнему полностью достижим в графе объектов. Именно этот факт делает удаление файлов безопасным: они не исчезли, до них один коммит.
Тот же checkout заодно ведёт и обслуживание индекса. Каждый изменившийся путь —
включая только что удалённые — передаётся в reindexFiles, который убирает
исчезнувшие файлы из графа кода и векторного индекса, вместо того чтобы оставлять
висячие эмбеддинги:
// file-sync.js — reindexFiles()
if (content === null) { // file gone after the checkout
await fanoutSyncRemove(projectId, projectRelPath);
scheduleVectorFlush(projectId, projectRelPath, null);
}
Итак, хранилище исходников достигает цели удалением, которое восстановимо из истории. Запомните эту мысль.
Рантайм: не восстанавливать его, а регенерировать
Deployment app-blog всё ещё работает. Можно было бы попробовать «откатить
Kubernetes» — но откатывать-то не к чему; у K8s нет истории. И она не нужна,
потому что рантайм — это не хранилище-источник истины. Каждый Deployment,
Service и правило Ingress производны — генерируются из спеки проекта
генератором манифестов при каждом старте.
Это меняет вопрос с «как мне восстановить рантайм» на «как сделать так, чтобы вывод перестал включать блог». Спека строится из живого списка приложений, и этот запрос фильтруется:
-- listProjectApps(): the spec only ever sees live apps
SELECT id, slug, is_primary, fs_dir_name
FROM project_apps
WHERE project_id = $1 AND archived_at IS NULL;
Так что в момент, когда строка блога заархивирована, она выпадает из спеки, и
следующая генерация манифестов просто не выдаёт ни app-blog, ни его правило
Ingress. Рантайм сходится через регенерацию, а не восстановление.
Остаётся один явный шаг: архивация строки убирает приложение из будущих манифестов, но Deployment, который уже запущен, продолжает работать, пока что-нибудь его не удалит. Поэтому reconcile после восстановления архивирует каждое приложение, созданное после целевой точки, а затем за один проход заново применяет спеку. При этом применении удаляется каждый принадлежащий платформе объект, которого в спеке больше нет:
// db-restore-reconcile.js — reconcileAfterRestore()
const postAppIds = selectPostTargetAppIds(appRows, targetMs); // never the primary app
for (const id of postAppIds) {
// files and data are already reverted by the git and branch restores
await appAdmin.archiveApp(projectId, id, { deleteFiles: false, dropData: false, rebuild: false, actor: "restore" });
}
if (out.appsArchived) {
// re-apply the spec; owned objects it no longer names are pruned:
// the archived apps' Deployments, Services, Secrets and Ingress rules
await reconcileLocked(projectId, { reason: "restore" });
}
Здесь всё держится на двух предохранителях. Выборка никогда не включает основное приложение: якорное приложение проекта восстановление не архивирует, а значит, и не удаляет. И демонтаж — это не набор удалений, прописанных вручную, а то же применение желаемого состояния, что выполняется при каждом старте. Поэтому его безопасно запускать повторно, и удаляет он ровно то, что из спеки исчезло. Остальные приложения продолжают работать. При удалении производного рантайма ничего не теряется: следующее применение заново сгенерирует манифесты по тому, что указано в спеке.
Данные: восстановление ветки уже всё сделало
Блог записал таблицы в Postgres. Но приложения делят одну базу Neon на проект, и совмещённый откат восстанавливает эту базу, форкая ветку на LSN снапшота. DDL и DML после этого LSN — таблицы блога и их строки — просто оказываются по другую сторону форка. Никаких данных уровня приложения удалять не надо, потому что point-in-time и есть удаление. (Именно поэтому восстановление только данных сначала обязано проверить расхождение схемы — откат ветки откатывает и схему. Но это отдельный пост.)
Что не удаляется жёстко — это реляционный якорь, строка project_apps. Мы её
мягко архивируем (archived_at = now()) и никогда не удаляем через
DELETE. Эта строка — та самая идентичность, которая связывает три хранилища.
Её сохраняют, а не удаляют, поэтому идентичность приложения и всё, что на неё
ссылается, переживают откат. Жёсткое удаление оставило бы без опоры всю историю,
которая на неё ссылалась.
Инвариант
Отступите на шаг — и три хранилища подчиняются одному правилу. Откат может физически удалить нечто, только если это нечто:
- Восстановимо из истории git — исходные файлы. Коммит до отката остаётся достижимым, поэтому отмена удаления — всего один указатель.
- Регенерируемо из спеки — Kubernetes Deployments, Services, правила
Ingress и сервисы-дополнения из каталога. Это производное состояние: удалять
его ничего не стоит, потому что следующее применение спеки соберёт его заново.
(Дополнения подчиняются восстановленному
spec.json: дополнение, подключённое после целевой точки, отключается, а его ресурсы освобождаются.)
Всё остальное мягко архивируется, а не уничтожается — строка project_apps,
прежние ревизии плана. А общие данные не удаляются вовсе; они откатываются
форком ветки, который сам по себе обратим (состояние до отката сохраняется как
снапшот для наката вперёд ещё до форка).
Обратимость — это не фича, прикрученная сверху: это свойство, которое вообще определяет, что безопасно удалять. Если вы не можете вернуть что-то — вы это не удаляете; вы это архивируете или откатываете, а не стираете.
Граница правила
Правило работает только для состояния, которое либо лежит в git, либо выводится из спеки. То, что не относится ни к тому, ни к другому, откат не должен удалять вслепую. У самой границы находятся два вида состояния, и с каждым обходятся осознанно:
- Файлы, которые никогда не коммитились — правка или загруженный ассет,
которые ещё не зафиксировала ни одна генерация. Прежде чем трогать дерево,
restoreVersionкоммитит рабочее дерево в отдельный коммит-снапшот (restore: working-tree snapshot before reverting to …), а если такой коммит создать не удаётся, отказывается восстанавливать версию. Незакоммиченная работа становится точкой наката вперёд, поэтому последующее удаление, как и всё остальное, можно отменить по истории. - Объекты в медиа-бакете проекта — файлы, которые пользователи загружали в работающее приложение и которые оно записывало прямо в S3. Форк ветки Neon откатывает базу проекта, но ничего не знает о содержимом бакета, поэтому откат оставляет бакет как есть, вместо того чтобы гадать. Медиа-объект, на который откаченная строка больше не ссылается, ничему не мешает. А удаление объекта, который ещё нужен, отменить было бы невозможно.
Приём тот же, что и для реляционной строки: сначала сохранить, потом удалять — или не трогать вовсе. Инвариант чётко очерчивает собственную границу: восстановимо или производно. Если какая-то часть состояния не относится ни к тому, ни к другому, её делают восстановимой до того, как откат её коснётся, — либо откат её не трогает.
Почему именно такая форма
Глубинная причина, почему всё это работает, — в том, что мы держим строгое разделение между хранилищами-источниками истины и производным состоянием и никогда не позволяем откату их перепутать. Исходники и реляционный якорь — это записи; они откатываются с сохранением истории. Рантайм Kubernetes производен — он регенерируется. Общие данные — это запись со своим собственным примитивом путешествия во времени; они откатываются форком ветки. Единственная задача отката — передвинуть каждое хранилище в один и тот же момент с помощью его собственной обратимой операции и отказаться уничтожать что-либо, что он не сможет реконструировать.
Сделайте это — и «вернуться на вчера» перестаёт быть наивным однострочником и становится тем, чем должно: согласованным, обратимым перемещением через три хранилища, каждое из которых помнит прошлое по-своему.