Files
SHiNE-server/deploy/SOLANA_USERS_SYNC_SERVER_SETUP.md
T

156 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Интеграция Solana users sync в сервер SHiNE
Этот документ фиксирует серверную конфигурацию модуля синхронизации `shine_users`
и базовую инициализацию новой PostgreSQL runtime-схемы сервера.
## Что уже есть
- основной сервер сначала инициализирует полную PostgreSQL runtime-схему SHiNE, затем запускает `SolanaUsersSyncStartupService` до продолжения startup;
- модуль синхронизации держит актуальными таблицы:
- `solana_sync_state`
- `solana_sync_tx_history`
- `solana_user_pda_current`
- `user_access_servers_current`
- `solana_user_pda_history`
- источник истины по пользовательским PDA: `solana_user_pda_current`.
- в `solana_user_pda_current` хранятся оба варианта логина:
- `login` — display-логин из PDA;
- `normalized_login` — канонический lower-case для runtime lookup и части FK;
- `user_access_servers_current` — это вторичная локальная проекция для быстрого роутинга DM по access servers;
она автоматически пересобирается из `solana_user_pda_current`, включая backfill для уже существующих пользователей.
## Что должно быть настроено в `application.properties`
Для текущих production-значений `shineup.me` и `server2.shineup.me` смотреть `deploy/PRODUCTION_SERVERS.md`.
Ниже универсальный пример для нового контура.
```properties
solana.users.sync.enabled=true
solana.users.sync.rpcUrl=https://devnet.helius-rpc.com/?api-key=0614c894-52d8-4ddc-bbbc-0947ce5ec3a4
solana.users.sync.wsUrl=wss://devnet.helius-rpc.com/?api-key=0614c894-52d8-4ddc-bbbc-0947ce5ec3a4
solana.users.sync.databaseUrl=jdbc:postgresql://127.0.0.1:5432/<APP_DB>
solana.users.sync.dbUser=<APP_DB_USER>
solana.users.sync.dbPassword=CHANGE_ME
solana.users.sync.pollIntervalSeconds=300
```
Замечания:
- `solana.users.sync.enabled=true` обязателен, иначе сервер пропустит startup sync.
- `solana.users.sync.databaseUrl` должен указывать на ту же PostgreSQL БД, где создана серверная runtime-схема.
- `solana.users.sync.wsUrl` задаётся явно, автоматически из `rpcUrl` не строится.
## Как создать пустую PostgreSQL runtime БД
SQL-скрипт инициализации лежит в:
```text
SHiNE-server/shine-server-db/src/main/resources/postgres/schema_v1.sql
```
Пример запуска:
```bash
psql \
"postgresql://<APP_DB_USER>:CHANGE_ME@127.0.0.1:5432/<APP_DB>" \
-f SHiNE-server/shine-server-db/src/main/resources/postgres/schema_v1.sql
```
Скрипт предназначен **только для полностью пустой PostgreSQL схемы**. На старой/непустой базе он завершится ошибкой и не выполняет in-place migration. При обычном первом запуске вручную выполнять его не нужно: сервер сам первым создаёт полную runtime-схему, и только затем стартует Solana sync; это не даёт sync-таблицам ошибочно выглядеть как legacy-БД.
Скрипт:
- создаёт жёсткий маркер поколения БД `shine_database_metadata`: `SHiNE_DB_V2`, generation `2`;
- создаёт таблицу версии runtime-схемы `db_schema_version` и ставит `schema_version=29`;
- создаёт таблицы sync-модуля Solana users;
- создаёт server runtime tables;
- создаёт триггеры и функции автоматической актуализации `user_access_servers_current`;
- не создаёт удалённые legacy-таблицы старого runtime для пользователей и DM;
- использует `signed_messages` как единственную таблицу серверных DM.
## Как поднять PostgreSQL в Docker
Шаблоны лежат в:
```text
deploy/postgres/docker-compose.yml.example
deploy/postgres/.env.example
```
Минимальная последовательность:
```bash
mkdir -p /home/player/SHiNE/postgres
cp deploy/postgres/.env.example /home/player/SHiNE/postgres/.env
cp deploy/postgres/docker-compose.yml.example /home/player/SHiNE/postgres/docker-compose.yml
cd /home/player/SHiNE/postgres
docker compose up -d
```
Шаблон `deploy/postgres/docker-compose.yml.example` рассчитан на `postgres:18`.
Для `postgres:18+` он монтирует host-каталог в `/var/lib/postgresql`, это важно для корректного старта контейнера.
После старта контейнера:
```bash
cp /path/to/SHiNE-product/application.properties ./application.properties
# задать db.url/db.user/db.password и запустить сервер
```
Сложность тут низкая:
- сам Docker Postgres поднимается просто;
- сервер сам создаёт runtime schema v1, если БД пустая и в ней нет `db_schema_version`;
- основная аккуратность нужна в паролях, bind-mount каталоге и backup;
- для SHiNE важно не открывать `5432` наружу, только `127.0.0.1:5432`.
## Что пока остаётся как есть
- runtime-сервер работает с PostgreSQL;
- межсерверная доставка DM остаётся отдельным механизмом и не связана с blockchain sync;
- прямой blockchain sync через `sync_servers` отключён: пользовательские блоки синхронизируются через Arweave.
## Совместимость с user PDA 1.2
После обновления `shine_users` серверный модуль `shine-server-solana-users-sync` должен обновляться вместе с программой: текущий codec принимает только PDA 1.2. Legacy PDA 1.0 не мигрируются; тестовые legacy-записи можно закрыть временной инструкцией `close_legacy_pda`.
Миграция PostgreSQL v25 добавляет `blockchain_forks_json`. Старые compatibility-колонки продолжают содержать активный (последний) fork, а полный список ключей fork сохраняется отдельно и используется для поиска владельца Arweave-записей по любому историческому blockchain key.
## PostgreSQL migration v26: key rotation runtime state
Migration v26 добавляет server-local поля `rotation_status` / `rotation_session_id` в `solana_user_pda_current` и таблицу `key_rotation_sessions`.
Это локальное состояние длительной смены ключей, а не часть Solana PDA. Solana users sync продолжает обновлять только PDA-поля и не должен затирать rotation-state. После обновления сервера миграция применяется стандартным `DatabaseInitializer` автоматически.
## Миграции key rotation
При обновлении сервера DatabaseInitializer последовательно применяет migration v26 (state machine смены ключей) и v27 (отдельные candidate-блоки будущего fork). Ручного создания таблиц не требуется. Candidate-блоки не входят в текущую таблицу `blocks` до финального переключения fork.
## Этапы регистрации V2 4–7: подготовка тестового окружения (23.10.2026)
Перед запуском новой синхронизации нужен тестовый `shine_users` (opcode 7, namespace accounts), применённая PostgreSQL v33, бэкап и отдельная БД. Только после этого разрешён импорт namespace в отдельный регистр `shine_namespace_current`. Не совмещать с существующим UI/production. `freeRegistration.enabled` по умолчанию false; `freeRegistration.registrarSeedFile` — локальный secret path (Base64 seed32) вне Git. При несоответствии регистратора публичному ключу on-chain namespace выдача сертификата прекращается. Нет Arweave importer до этапа 8, API/UI до этапов 9–10. Сначала прогоните чистый snapshot, историю, restart/replay, FK и ключевую ротацию на тестовом контуре.
## DB v35: единый платный статус (26.10.2026)
`DatabaseInitializer` при запуске сервера последовательно обновляет схему до v35. Старые
`PAID_DIRECT` и `PAID_UPGRADED` преобразуются в единый `PAID`; `FREE_CERT` не изменяется.
Любой новый пользователь с настоящей PDA Solana получает `PAID` независимо от способа регистрации.
Данные аккаунтов, Arweave-сертификаты, начальная дата регистрации и ключи не удаляются.
Порядок на тестовом контуре: резервная копия БД → обновление серверного кода с `migration_v35.sql`
→ перезапуск и проверка `db_schema_version=35` → обновление UI → пробная регистрация и upgrade.
До обновления сервера или при неудачной миграции оставьте существующий UI: новое значение `PAID`
должно приходить только от сервера с применённой v35. На production — отдельное согласование.
Для проверки статусов после миграции:
```sql
SELECT registration_status, count(*) FROM user_identity_current GROUP BY registration_status;
SELECT schema_version FROM db_schema_version WHERE id=1;
```
## Регистронезависимый логин (2026-10-28)
Для новых баз важно совместное обновление программы `shine_users`, Java Solana sync/архива и UI. После обновления `login` внутри PDA сохраняет регистр, а адрес и `normalized_login` используют lowercase. Перед проверкой смешанного регистра заново инициализируйте **тестовую** БД и разверните обновлённую Solana-программу в devnet; сам ZIP её не разворачивает.