architecture/deployment.md

@@ -12,12 +12,18 @@ Development дополнительно требует checkout `frontend/` и `b
   доступ к registry и достаточно свободного диска для non-root UID 1000.
   Локально проверены Engine 29.8.0, Compose 5.5.1, Linux arm64.
   Другую архитектуру проверяют отдельно; multi-platform images не обещаны.
-- Gitea Container Registry; проверяемая версия сервера — 1.27.3.
+- Nexus Docker hosted repository `docker-hosted`, доступный через
+  `https://nexus.ksv741.keenetic.pro/v2/`. Docker Bearer Token Realm включён;
+  reverse proxy передаёт исходные host и HTTPS scheme. Адрес token realm
+  в `WWW-Authenticate` также должен начинаться с `https://`.
+  Deployment policy запрещает redeploy существующих release tags.
   Runner label — `ubuntu-latest`, runner должен иметь Docker CLI, buildx и daemon.
   Наличие label само по себе не доказывает Docker capability.
-- В Actions каждого component repo нужны `REGISTRY_USERNAME` и
+- В Actions каждого component repo нужны `NEXUS_USERNAME` и
-  `REGISTRY_TOKEN` отдельной identity с package write permission. Server
+  `NEXUS_PASSWORD` пользователя `wealthledger-ci`. Эта же учётная запись
-  использует другую identity только с package read permission. Built-in
+  используется сервером для загрузки образов. Для публикации нужны
+  browse/read/add/edit на `docker-hosted`; фактически выданный набор прав
+  настраивается в Nexus. Built-in
   workflow token не заменяет эту настройку.
 - На сервере Caddy уже завершает TLS и передаёт весь домен на
   `127.0.0.1:8080` (или выбранный frontend port). Отдельного `/api` upstream нет.
@@ -63,7 +69,7 @@ Project `wealthledger-dev` хранит SQLite в `development-data`. Обычн
 version, затем выполняет `npm ci`, `npm run verify`; backend дополнительно
 выполняет `npm run test:e2e`. У каждого image OCI version/revision labels.
 
-Images публикуются как `git.personal.ksv741.ru/wealthledger/frontend:X.Y.Z`
+Images публикуются как `nexus.ksv741.keenetic.pro/wealthledger/frontend:X.Y.Z`
 и `.../backend:X.Y.Z`. `latest` не создаётся.
 Workflow отказывается перезаписывать существующие release tags;
 защита release tags и запрет параллельных publishers обязательны. Если одна
@@ -73,9 +79,45 @@ Workflow отказывается перезаписывать существу
 Выберите опубликованные version tags, выполните pull и сравните OCI revision
 с release commit. Выполните smoke с disposable data/config до первого server
 rollout. В production env хранится пара полных image references, например
-`git.personal.ksv741.ru/wealthledger/frontend:0.1.0`. Сохраните versions/revisions
+`nexus.ksv741.keenetic.pro/wealthledger/frontend:0.2.0`. Сохраните versions/revisions
 в deployment record. Release tags не должны переназначаться другим images.
 
+## Перенос существующих images из Gitea
+
+До переключения CI и server references проверьте HTTPS token realm и настройте
+пользователя `wealthledger-ci`. В Actions добавьте `NEXUS_USERNAME`/`NEXUS_PASSWORD`; прежние
+`REGISTRY_USERNAME`/`REGISTRY_TOKEN` сохраните для отката старого workflow.
+Пароли вводятся интерактивно или через `--password-stdin`, не через аргументы.
+
+Скопируйте каждый опубликованный release без пересборки. Например, для `0.2.0`
+с установленным Skopeo и доступом чтения Gitea/записи Nexus:
+
+```bash
+skopeo login git.personal.ksv741.ru
+skopeo login nexus.ksv741.keenetic.pro
+for component in frontend backend; do
+  skopeo copy --all --preserve-digests \
+    "docker://git.personal.ksv741.ru/wealthledger/$component:0.2.0" \
+    "docker://nexus.ksv741.keenetic.pro/wealthledger/$component:0.2.0" || exit 1
+done
+```
+
+`--all` переносит весь image index, включая платформы и вложенные attestation
+manifests; `--preserve-digests` прерывает перенос при изменении digest.
+До копирования проверьте наличие destination tag: если он уже существует,
+сравните исходный и целевой index digest и вложенные manifests. Совпадающий
+artifact повторно не публикуйте; несовпадение требует расследования, не удаления
+или перезаписи tag. Частичный перенос не считается завершённым.
+
+После копирования сравните digests через `skopeo inspect --raw` и SHA-256,
+выполните `docker pull` обоих images пользователем `wealthledger-ci` на сервере приложения,
+проверьте OCI revision и container smoke на disposable data.
+Только после этого меняйте production image references и запускайте обычную
+последовательность обновления ниже. Старые Gitea packages и references сохраните:
+откат registry возвращает прежние адреса тех же artifacts, не восстанавливает
+SQLite и не меняет encryption keys. Не переносите Git release tags и не
+запускайте заново старый tag workflow для копирования существующего image.
+
 ## Первая установка
 
 Создайте restricted environment file и data directory:
@@ -103,10 +145,10 @@ backup directory и Docker. Заполните env локальным защищ
 если переименовываете, согласуйте также WAL/SHM companion names до старта.
 Не запускайте старый и новый backend на одной базе одновременно.
 
-Войдите в registry server identity без помещения token в командную строку:
+Войдите в registry пользователем `wealthledger-ci` без помещения пароля в командную строку:
 
 ```bash
-docker login git.personal.ksv741.ru --username SERVER_PULL_USER
+docker login nexus.ksv741.keenetic.pro --username wealthledger-ci
 export COMPOSE_FILE=compose.yaml
 export COMPOSE_PROJECT_NAME=wealthledger
 export COMPOSE_ENV_FILES=/srv/wealthledger/production.env