SHA256
198 lines
16 KiB
Markdown
198 lines
16 KiB
Markdown
# Интеграция 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=YOUR_HELIUS_API_KEY
|
||
solana.users.sync.wsUrl=wss://devnet.helius-rpc.com/?api-key=YOUR_HELIUS_API_KEY
|
||
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` не строится.
|
||
- `YOUR_HELIUS_API_KEY` — плейсхолдер. Замените его в приватном серверном `application.properties`, а не в Git. Ключи из репозитория и прежних UI-деплоев рекомендуется перевыпустить.
|
||
|
||
## Как создать пустую 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 её не разворачивает.
|
||
|
||
## 2026-10-28 — Неизменяемый регистр логина (PostgreSQL v37)
|
||
|
||
- В `user_identity_current.login` хранится **написание первой регистрации**, включая заглавные буквы. В `normalized_login` — его lowercase-форма для поиска и уникальности.
|
||
- v37 добавляет BEFORE INSERT/UPDATE-проверку: `normalized_login = lower(btrim(login))`, а после создания идентичности оба поля неизменяемы.
|
||
- `shine_sync_identity_from_solana()` отклоняет PDA, если для того же нормализованного имени его `login` не совпадает **точно** с Arweave-сертификатом или предыдущей регистрацией. При FREE_CERT → PAID нельзя изменять только регистр.
|
||
- Сервер перед первым `AddBlock` сверяет HEADER с точным `user_identity_current.login`; нормализованное имя цепочки этому не противоречит.
|
||
- Никакого преобразования существующих signed-блоков нет; новая тестовая эпоха создаётся с чистой БД и без старых HEADER.
|
||
|
||
## PostgreSQL v38: ключ blockchain state
|
||
|
||
После обновления сервера `DatabaseInitializer` автоматически применит migration v38 и при старте нормализует `blockchain_state_store.blockchain_key` из исторического Base58 в Base64(32). Ручной SQL-апдейт для free-пользователей не нужен. После запуска проверьте, что первый `AddBlock` нового free-пользователя проходит без `BAD_BLOCKCHAIN_KEY_LEN`.
|
||
|
||
### Обновление namespace registration_fee / currency_code
|
||
|
||
Серверная БД мигрирует v39→v40 (колонка `shine_namespace_current.currency_code`). Перед активацией нового контракта следует установить совместимый сервер-sync: новый opcode 8 индексируется через историю economy PDA, namespace 1.0/1.1 читаются совместимо, `UPSERT` обновляет цену вместо прежней ошибочной проверки `raw_data_base64 = EXCLUDED.raw_data_base64`. Проверить `GetNamespaces` и `CheckRegistrationLogin` после подтверждения транзакции; при задержке history polling информация может обновиться не мгновенно.
|
||
|
||
|
||
## Кеш статистики поддержки профилей (12.11.2026)
|
||
|
||
Новых настроек и отдельных сервисов нет. При `solana.users.sync.enabled=true`
|
||
существующий `SupportHistoryIndexer` использует прежнее Solana RPC/Helius и
|
||
PostgreSQL подключение. При первом запуске обновлённой версии автоматически
|
||
создаёт таблицу `solana_support_user_stats` и пересчитывает прошлые донаты из
|
||
`solana_support_transfers`. После этого новые финализированные переводы
|
||
увеличивают готовые счётчики инкрементально. При первом восстановлении
|
||
с нуля `GetSupportStats` возвращает `ready=false` до конца сканирования.
|
||
|
||
Для диагностики (вручную выполнять при установке **не требуется**):
|
||
|
||
```sql
|
||
SELECT history_complete, stats_cache_ready, last_signature, updated_at
|
||
FROM solana_support_sync_state WHERE id=1;
|
||
|
||
SELECT normalized_login, support_sent, support_received, dao_direct
|
||
FROM solana_support_user_stats ORDER BY support_received DESC LIMIT 20;
|
||
```
|
||
|
||
В случае подозрения на рассогласование кеша остановить синхронизатор,
|
||
выполнить `UPDATE solana_support_sync_state SET stats_cache_ready=FALSE WHERE id=1`
|
||
и вновь запустить. Журнал финансовых операций при этом сохраняется.
|