From f6ccb5ecf2ea996d43245f639f8654e9fde83c9d Mon Sep 17 00:00:00 2001 From: vitya Date: Fri, 28 Aug 2026 22:36:17 +0300 Subject: [PATCH] =?UTF-8?q?docs(runbook):=20mappa=200.30.0=20deployed=20(t?= =?UTF-8?q?ask:1469)=20=E2=80=94=20v0.30.0/GIT=5FSHA=202528e57;=20core-PAT?= =?UTF-8?q?CH=20=D0=BF=D1=80=D0=BE=D0=B3=D1=80=D0=B0=D0=BC=D0=BC=D0=BD?= =?UTF-8?q?=D1=8B=D0=B9=20(1466=20live,=20source=3Dadmin)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .wiki/concepts/mappa-vds-deploy-runbook.md | 7 +-- .wiki/concepts/runbooks-index.md | 2 +- .../concepts/skills-catalog-deploy-runbook.md | 53 +++++++++---------- 3 files changed, 28 insertions(+), 34 deletions(-) diff --git a/.wiki/concepts/mappa-vds-deploy-runbook.md b/.wiki/concepts/mappa-vds-deploy-runbook.md index f77552f..0b40034 100644 --- a/.wiki/concepts/mappa-vds-deploy-runbook.md +++ b/.wiki/concepts/mappa-vds-deploy-runbook.md @@ -22,7 +22,7 @@ mappa (#985). Не делать чужую часть. - **Образ:** `registry.kzntsv.site/mappa:` — тег = version из package.json, GIT_SHA передаётся `--build-arg GIT_SHA=` (Dockerfile в корне репо, multi-stage node:22-alpine; **обязательный COPY `src/lib/schema.sql` → `dist/src/lib/schema.sql`** — tsc не копирует .sql, - без него migrate() падает «schema.sql not found»). Прод на 2026-08-28 = **v0.29.0** (GIT_SHA 4e013bd). + без него migrate() падает «schema.sql not found»). Прод на 2026-08-28 = **v0.30.0** (GIT_SHA 2528e57, digest 8475558edbf1). Deploy-паттерн: релизная ветка `deploy/vX.Y.Z` из батч-tip → бамп package.json → merge в master. - **Стек Portainer:** `mappa` (Id 27, endpoint 1). Source-of-truth compose: `admin/host-stacks/vds-kzntsv/mappa.compose.yml`. @@ -119,7 +119,4 @@ ssh vds.kzntsv.site 'docker ps --filter name=mappa --format "{{.Status}}"' (`----lv0290`). Плюс: curl на Windows (mingw) шлёт multipart с LF-разделителями — серверный парсер ждёт CRLF; надёжно — собрать multipart с CRLF вручную (`--data-binary`). Кандидат на фикс в mappa: не lowercasing'ить boundary / матчить регистронезависимо. -8. **Одноразовый ре-индекс tsvec при создании конфига токенизатора (v0.28.0, 2026-08-28)** — - миграция создаёт PG-конфиг `mappa` (гейт newly_created) и перестраивает tsvec ВСЕХ сущностей - (~13.5k коммитов). Старт после деплоя дольше обычного; health может отвечать 404/не стартовать - до ~1 мин — это ожидаемо, не паника. Проверять `docker ps` (health: starting) + повторять /health. +10. **Контролируемый апдейт core-скилов (v0.30.0, 2026-08-28)** — PATCH `/skills` kind=core больше НЕ 403: требуется `source=admin` (event-аудит skill.core_update, task:1466). deploy-catalog.mjs шлёт source=admin → core-обновления применяются программно (пробел закрыт). DELETE core — по-прежнему 403. diff --git a/.wiki/concepts/runbooks-index.md b/.wiki/concepts/runbooks-index.md index d03b3f6..4a11c50 100644 --- a/.wiki/concepts/runbooks-index.md +++ b/.wiki/concepts/runbooks-index.md @@ -47,7 +47,7 @@ updated: 2026-08-26 | Операция | Ранбук | Что покрывает | |---|---|---| | Создание Gitea-репо (проект в Gitea) | [`gitea-project-create-runbook.md`](gitea-project-create-runbook.md) | private-репо: admin POST /user/repos → transfer к владельцу; pre-flight; verify; rollback; gotchas (SSH-порт 2222, pass-рефы) | -| Деплой каталога скилов на сервер mappa | [`skills-catalog-deploy-runbook.md`](skills-catalog-deploy-runbook.md) | синк репо-каталогов (mappa-skills/mappa-vitya-skills) → /skills на mappa.vds.kzntsv.site; deploy-catalog.mjs (dry-run → apply); стоящее правило «деплой при каждом изменении исходников» (письмо от держателя каталога); core-immutable interim до mappa task:1466/1467 | +| Деплой каталога скилов на сервер mappa | [`skills-catalog-deploy-runbook.md`](skills-catalog-deploy-runbook.md) | синк репо-каталогов (mappa-skills/mappa-vitya-skills) → /skills на mappa.vds.kzntsv.site; deploy-catalog.mjs (dry-run → apply); стоящее правило «деплой при каждом изменении исходников» (письмо от держателя каталога); core-PATCH программный (1466 live с 0.30.0, source=admin) | | books VDS — оптимизация памяти (OOM → ECONNREFUSED) | [`books-vds-memory-optimize-runbook.md`](books-vds-memory-optimize-runbook.md) | mongo wiredTiger 0.25 / ES heap / CI-остатки buildx; files-compose (НЕ Portainer-kzntsv); verify; rollback; Manticore-задел | | MinIO split (books-vds + CMS-media) | [`minio-split-cutover-runbook.md`](minio-split-cutover-runbook.md) | cutover Track A/B, rollback | | Общий Portainer-канон VDS kzntsv | [`portainer-stack-management-vds.md`](portainer-stack-management-vds.md) | JWT auth, gotchas 1-10, redeploy-рецепт, инвентарь стеков | diff --git a/.wiki/concepts/skills-catalog-deploy-runbook.md b/.wiki/concepts/skills-catalog-deploy-runbook.md index 6069c96..4009972 100644 --- a/.wiki/concepts/skills-catalog-deploy-runbook.md +++ b/.wiki/concepts/skills-catalog-deploy-runbook.md @@ -13,10 +13,10 @@ updated: 2026-08-28 > Из проекта не выносить: не копировать в другие вики, не пересказывать, не публиковать. > Нужен деплой или прод-операция по этому ранбуку — **поставить задачу админу (`.admin`) и написать письмо**. Админ выполняет, остальные верифицируют. -> ✅ **Финализирован (2026-08-28, task:1462).** Команды деплоя — из README каталогов -> (deploy-catalog.mjs, task:1461 done). Core-immutable — **interim** (ручной шаг только -> с согласования оператора) до доработки /skills (mappa task:1466/1467): финальный -> механизм программный, ранбук обновится после их деплоя. +> ✅ **Финализирован (2026-08-28, task:1462); core-путь обновлён 2026-08-28 (деплой 0.30.0, task:1469).** +> Команды деплоя — из README каталогов (deploy-catalog.mjs, task:1461 done). **Core-immutable — ЗАКРЫТ:** +> с mappa **0.30.0** PATCH /skills kind=core работает (source=admin, task:1466 live); deploy-catalog +> (149ca36) применяет core программно. Ранбук отражает программный путь. ## Scope @@ -42,8 +42,8 @@ updated: 2026-08-28 - **Deploy-скрипт (task:1461 done):** `scripts/deploy-catalog.mjs` в каждом каталоге-репо (синк изменений вместо oneshot-засева seed-skills.ts, task:1448; kind по имени репо или `--kind`). Тесты: `scripts/deploy-catalog.test.mjs` (`node --test scripts/`). - Семантика: отсутствующие → POST (create); изменённые methodology → PATCH (update); - изменённый core → `! immutable` (не применяется). + Семантика: отсутствующие → POST (create); изменённые → PATCH (update); core — PATCH + с source=admin (1466 live с 0.30.0, deploy-catalog 149ca36); DELETE core — 403. - **Обратное направление (НЕ этот ранбук):** `scripts/sync-skills.ts` (task:1381) — синк каталога mappa → диск харнесса (pi/CC). Разделять: здесь деплой исходников в mappa. @@ -66,11 +66,10 @@ updated: 2026-08-28 ``` Применяет create + update (**methodology** PATCH). Изменённый **core** — `! immutable`, НЕ применяется (см. interim, п.4). -4. **core-immutable (interim, до деплоя mappa task:1466/1467):** если в плане есть - `! immutable` — правки core не применены. Путь: согласование с оператором → - обновление сущности вне API (админ-операция .admin / пересоздание) → повторный - dry-run подтверждает. **Финал — программный** (после 1466/1467); ручной шаг — - только с согласования оператора, не «ограничение навсегда». +4. **core-обновление (программный путь, 1466 live с 0.30.0):** если в плане есть + `~ (core, source=admin)` — правки core применяются PATCH-ом (source=admin, + event-аудит skill.core_update). Ручной шаг НЕ нужен. DELETE core — по-прежнему 403 + (удаление — только фикс исходника / пересоздание каталога-сущности). 5. **Verify** (см. ниже). 6. **Фиксация:** письмо-отчёт проекту-держателю (verify-таблица) + закрытие ops-таски. @@ -101,25 +100,25 @@ updated: 2026-08-28 PATCH применён; изменённый core — остался без применения (interim, зафиксировать в письме). - Потребительская сторона: `sync-skills.ts` подхватит обновления на дисках харнессов (после `/reload`, спека wiki:3300 п.11) — verify-контур, не часть деплоя. +- **База (первый прогон 2026-08-28 после деплоя 0.30.0):** mappa-skills — 8 up-to-date + + 2 updated (mappa-bootstrap, mappa-brainstorm-promote — через core-PATCH source=admin); + mappa-vitya-skills — 2 up-to-date. ## Rollback - **Откат содержимого (methodology):** revert коммита в репо-источнике → повторный `--apply` (PATCH вернёт прежнее тело). -- **Откат (core):** до деплоя 1466/1467 — только админ-операция вне API (revert - исходника → ручной шаг с согласования оператора); после — программный путь из - ранбука-апдейта. -- **Удаление ошибочного скила:** methodology — DELETE /skills; core — 403 (до - 1466/1467 — админ-операция, после — контролируемый путь). +- **Откат (core):** revert коммита в репо-источнике → повторный `--apply` — PATCH с + source=admin вернёт прежнее тело (программный путь). +- **Удаление ошибочного скила:** methodology — DELETE /skills; core — DELETE 403 (только + фикс исходника / пересоздание каталога-сущности). ## Gotchas -1. **`kind=core` immutable (interim)** — PATCH/DELETE `/skills` → 403, deploy-catalog - помечает правки core как `! immutable` и НЕ применяет. Это **пробел сервера** - (решение оператора inbox:2620: «ДОДЕЛАТЬ»): доработка /skills — mappa - **task:1466/1467** (ready; в README репо — 1466, в письме inbox:2625 — 1467 — - проверить дедуп). До её деплоя — ручной шаг только с согласования оператора. - Не пытаться PATCH'ить core напрямую. (2026-08-28) +1. **`kind=core` PATCH — закрыт (1466 live с 0.30.0)** — PATCH /skills kind=core с source=admin + работает (event-аудит skill.core_update; deploy-catalog шлёт source=admin, 149ca36). + Без source=admin — 403 (иммутабельность core для обычных агентов сохраняется). DELETE core — + 403 всегда. (2026-08-28) 2. **422 secret-scan** — тело SKILL.md с секретом (token/password/… ≥6 симв.) → `POST /skills` → 422. Перед деплоем прогон `mcp__mappa__admin_secret_scan` (0 hits). 3. **Направление не путать** — репо → mappa (этот ранбук, deploy) vs mappa → диск @@ -137,10 +136,8 @@ updated: 2026-08-28 Проект, пушащий изменения в каталог-репо, шлёт письмо в .admin. Сейчас: mappa (core), skills (methodology); сменится владелец каталога — сменится адресант. 3. **Обновление core (immutable)** — ДОДЕЛАТЬ: core должны обновляться деплоем по - определённому пути. 403 = пробел сервера → доработка /skills (follow-up mappa - **task:1466/1467**, ready; дедуп проверить), не «ограничение + ручной шаг» как финал. - До деплоя доработки — **interim**: ручной шаг только с согласования оператора. + определённому пути. **ВЫПОЛНЕНО (2026-08-28, деплой 0.30.0, task:1469):** доработка + /skills — task:1466 → PATCH core с source=admin; deploy-catalog применяет core программно. -**Статус (2026-08-28):** task:1461 done → команды деплоя в ранбуке, task:1462 -финализирована; ранбук-апдейт финального core-механизма — после деплоя 1466/1467 -(штатный WRITE-апдейт). +**Статус (2026-08-28):** core-путь программный (1466 live); ранбук актуален; первый прогон +после деплоя: 2 core-скила обновлены через core-PATCH (mappa-bootstrap, mappa-brainstorm-promote).