Интеграция 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.
user_access_servers_current — это вторичная локальная проекция для быстрого роутинга DM по access servers; она автоматически пересобирается из solana_user_pda_current, включая backfill для уже существующих пользователей.

Что должно быть настроено в `application.properties`

Для текущих production-значений shineup.me и server2.shineup.me смотреть deploy/PRODUCTION_SERVERS.md. Ниже универсальный пример для нового контура.

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-скрипт инициализации лежит в:

SHiNE-server/shine-server-db/src/main/resources/postgres/schema_v1.sql

Пример запуска:

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 = 2;
создаёт таблицы sync-модуля Solana users;
создаёт server runtime tables;
создаёт триггеры и функции автоматической актуализации user_access_servers_current;
не создаёт удалённые legacy-таблицы старого runtime для пользователей и DM;
использует signed_messages как единственную таблицу серверных DM.

Как поднять PostgreSQL в Docker

Шаблоны лежат в:

deploy/postgres/docker-compose.yml.example
deploy/postgres/.env.example

Минимальная последовательность:

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, это важно для корректного старта контейнера.

После старта контейнера:

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.

Что пока остаётся как есть

sync_servers сервер по-прежнему загружает из server PDA в Solana;
runtime-сервер уже работает только с PostgreSQL;
дальнейшим отдельным шагом остаются зачистка legacy-документации, переименования и перенос оставшихся прямых SQL-запросов в DAO/service.

5.1 KiB Raw Blame History