SHA256
116 lines
6.2 KiB
Markdown
116 lines
6.2 KiB
Markdown
# Интеграция Solana users sync в сервер SHiNE
|
||
|
||
Этот документ фиксирует серверную конфигурацию модуля синхронизации `shine_users`
|
||
и базовую инициализацию новой PostgreSQL runtime-схемы сервера.
|
||
|
||
## Что уже есть
|
||
|
||
- основной сервер запускает `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
|
||
```
|
||
|
||
Скрипт:
|
||
|
||
- создаёт таблицу версии схемы `db_schema_version`;
|
||
- ставит актуальный `schema_version`;
|
||
- создаёт таблицы 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.
|