Перенести документацию в docs и добавить социальный граф

2026-07-13 12:58:41 +04:00
parent c9cfb394d7
commit af12d7b954
91 changed files with 653 additions and 2 deletions
@@ -0,0 +1,109 @@
+# Деплой SHiNE (шаблон)
+
+Этот раздел хранит актуальные инструкции по деплою.
+
+## Базовый сервер
+
+- SSH: `player@shineup.me`
+- Домен: `shineup.me`
+- Базовый путь: `/home/player`
+
+Для всех рабочих инструкций и скриптов использовать доменное имя `shineup.me`, а не фиксированный IP:
+
+- актуальный IP должен браться через DNS-резолв на момент подключения;
+- ручное дублирование IP в документации и deploy-скриптах не поддерживать.
+
+## Контуры деплоя
+
+- Production:
+  - SSH: `player@shineup.me`
+  - Домен: `shineup.me`
+  - IP: `185.229.109.118`
+- Main test:
+  - SSH: `player@193.8.215.70`
+  - Домен: `t.shineup.me`
+  - IP: `193.8.215.70`
+- Reserve test:
+  - SSH: `player@93.170.12.154`
+  - Домен: `test.shineup.me`
+  - IP: `93.170.12.154`
+
+## Локальные команды
+
+- Default server deploy: `./gradlew deployServer` или `./gradlew deployServerTest2`
+- Default UI deploy: `./gradlew deployUI` или `./gradlew deployUITest2`
+- Production server deploy: `./gradlew deployServerProduction`
+- Production UI deploy: `./gradlew deployUIProduction`
+- Reserve test server deploy: `./gradlew deployServerTest`
+- Reserve test UI deploy: `./gradlew deployUITest`
+- Локальный запуск: `./gradlew startLocal`
+
+## Отдельные тестовые VPS
+
+- Отдельный стенд с 4 devnet-серверами на одном VPS описан в:
+  - `Dev_Docs/deploy/test-server/README.md`
+
+## Политика подтверждений
+
+- `shineup.me` — production.
+- Любые изменения на `shineup.me`, включая deploy сервера, deploy UI, конфиги, перезапуски и миграции, делать только после отдельного явного подтверждения пользователя.
+- Если пользователь пишет просто `задеплой` без уточнения, по умолчанию это означает deploy на `t.shineup.me`.
+
+## Main test deploy (`t.shineup.me`)
+
+- Это основной сервер для тестов.
+- `deployServer` и `deployUI` по умолчанию направлены именно сюда.
+- Серверный deploy не запускает JUnit/IT-тесты на удалённом сервере.
+- `deployServer` / `deployServerTest2` делают:
+  - сборку fat-jar локально;
+  - синхронизацию `data/` и `shine.sqlite` с production `shineup.me`;
+  - перенос `application.properties` с production с поправкой `server.ui.indexPath` на `/home/player/SHiNE/shine-ui/index.html`;
+  - установку `systemd` unit на `193.8.215.70`;
+  - перезапуск `shine-server.service`;
+  - установку/проверку Caddy для `t.shineup.me`.
+- `deployUI` / `deployUITest2` публикуют UI в `/home/player/SHiNE/shine-ui` на `193.8.215.70`.
+
+## Reserve test deploy (`test.shineup.me`)
+
+- `test.shineup.me` считается резервным тестовым сервером.
+- Его настройки и адрес не менять без отдельной задачи.
+- Задачи `deployServerTest` и `deployUITest` считаются резервными и требуют отдельной причины.
+
+## UI-деплой и Caddy (обязательно)
+
+- Целевая директория UI-деплоя: `/home/player/SHiNE/shine-ui`.
+- `Caddyfile` на сервере должен смотреть в ту же директорию через `root * /home/player/SHiNE/shine-ui`.
+- В `deploy_shine-PWA.sh` добавлена проверка: скрипт ищет блок `shineup.me { ... }` (или значение `EXPECTED_CADDY_SITE`) и проверяет `root` внутри этого блока.
+- Если `root` внутри целевого блока не совпадает, деплой прерывается с ошибкой.
+- Для ручного обхода проверки (только осознанно): `ALLOW_CADDY_MISMATCH=1 ./gradlew deployUI`.
+- При необходимости можно явно переопределить путь деплоя:
+  - `REMOTE_UI_DIR=/нужный/путь ./gradlew deployUI`
+  - `EXPECTED_CADDY_UI_ROOT=/нужный/путь ./gradlew deployUI`
+  - `EXPECTED_CADDY_SITE=example.com ./gradlew deployUI`
+
+## Временные тестовые сайты Solana tickets
+
+- Для HTML UI программы `shine_payments` используется отдельный временный тестовый сайт.
+- Основной каталог публикации:
+  - `/home/player/sites/test-solana-tickets.shineup.me`
+- Рабочие домены:
+  - `https://test-solana-tickets.shineup.me`
+  - `https://test-solana-tickets.shiningpeople.ru`
+- Назначение:
+  - ручная проверка сценариев покупки билетов;
+  - проверка DAO-инструментов и лимитов менеджеров;
+  - проверка ручного добавления билетов и `step_payout`.
+- Эти сайты не считать основным UI SHiNE; это отдельная тестовая публикация под Solana-часть.
+
+### Важно для локального UI (history-router / Ctrl+F5)
+
+- Локальный UI **обязательно** поднимать только через `./gradlew startLocal`.
+- Эта задача запускает `scripts/local_spa_server.py`, который делает SPA fallback: любой неизвестный путь (`/m/...`, `/channel/...`) возвращает `index.html`.
+- Это обязательно для корректной работы `Ctrl+F5` на внутренних роутов без `404`.
+- Рабочий URL выводится задачей в консоль в формате: `http://localhost:<WEB_PORT>/?localWsPort=<WS_PORT>`.
+
+## Обязательные правила
+
+1. Перед серверным деплоем проверить локально.
+2. При нестандартном деплое (другой хост, другая структура, ручные шаги) обязательно уточнить у пользователя, нужно ли обновить этот шаблон.
+3. Если деплой-процесс изменился, этот файл и файлы в `servers/` обновлять в том же коммите.
@@ -0,0 +1,36 @@
+# Локальный деплой SHiNE-agent-bot-coder (systemd, пользователь ai)
+
+## Где находится сервис
+- Папка сервиса: `SHiNE-agent-bot-coder/`
+- Systemd unit: `SHiNE-agent-bot-coder/scripts/systemd/shine-agent-bot-coder.service`
+- Скрипт установки: `SHiNE-agent-bot-coder/scripts/systemd/install-local-systemd.sh`
+
+## Предусловия
+1. Заполнен `.env` на основе `.env.example`.
+2. Доступен рабочий Codex CLI:
+   - `/home/ai/.cache/JetBrains/IntelliJIdea2026.1/aia/codex/bin/codex-x86_64-unknown-linux-musl`
+3. На машине установлен `systemd --user`.
+
+## Установка
+Из корня репозитория:
+
+```bash
+bash SHiNE-agent-bot-coder/scripts/systemd/install-local-systemd.sh
+```
+
+Скрипт:
+1. проверяет наличие `python3`;
+2. копирует unit в `~/.config/systemd/user/`;
+3. делает `systemctl --user daemon-reload`;
+4. включает автозапуск и стартует сервис.
+
+## Проверка
+```bash
+systemctl --user status shine-agent-bot-coder --no-pager
+journalctl --user -u shine-agent-bot-coder -f
+```
+
+## Перезапуск после изменений
+```bash
+systemctl --user restart shine-agent-bot-coder
+```
@@ -0,0 +1,43 @@
+# Сервер `193.8.215.70` — основной test (`t.shineup.me`)
+
+- Пользователь: `player`
+- Домен: `t.shineup.me`
+- Логин сервера: `tshineupme`
+- Каталог SHiNE: `/home/player/SHiNE`
+- UI публикация для Caddy: `/home/player/SHiNE/shine-ui`
+- Сервер: `/home/player/SHiNE/shine-server/shine-server.jar`
+- Данные: `/home/player/SHiNE/shine-server/data/`
+  - `shine.sqlite`
+  - `*.bch`
+- Логи сервера: `/home/player/SHiNE/shine-server/logs/app.log`
+
+## Сервисы
+
+- `shine-server.service` (systemd)
+- `caddy.service` (systemd)
+
+## Статус
+
+- Это основной сервер для тестов SHiNE.
+- Default deploy по умолчанию должен идти сюда.
+- Источник данных для тестовой БД: production `shineup.me`.
+
+## Caddy
+
+- Конфиг: `/etc/caddy/Caddyfile`
+- Сайты:
+  - `t.shineup.me`
+  - `agent.shiningpeople.ru`
+- Для `t.shineup.me`:
+  - `root * /home/player/SHiNE/shine-ui`
+  - `try_files {path} /index.html`
+  - `reverse_proxy /ws* -> 127.0.0.1:7070`
+
+## Deploy
+
+- Default server deploy:
+  - `./gradlew deployServer`
+  - `./gradlew deployServerTest2`
+- Default UI deploy:
+  - `./gradlew deployUI`
+  - `./gradlew deployUITest2`
@@ -0,0 +1,40 @@
+# Сервер `93.170.12.154` — резервный test (`test.shineup.me`)
+
+- Пользователь: `player`
+- Каталог SHiNE: `/home/player/SHiNE`
+- Домен: `test.shineup.me`
+- Роль: резервный тестовый сервер
+- UI публикация для Caddy: `/home/player/SHiNE/shine-ui`
+- Сервер: `/home/player/SHiNE/shine-server/shine-server.jar`
+- Данные: `/home/player/SHiNE/shine-server/data/`
+  - `shine.sqlite`
+  - `*.bch`
+- Логи сервера: `/home/player/SHiNE/shine-server/logs/app.log`
+
+## Сервисы
+
+- `shine-server.service` (systemd)
+- `caddy.service` (systemd)
+
+## Статус
+
+- Резервный тестовый сервер для SHiNE.
+- Источник данных для тестовой БД: production `shineup.me`.
+- Пока не использовать для обычного deploy.
+- Основной прод-сервер: `shineup.me` (`185.229.109.118`).
+
+## Caddy
+
+- Конфиг: `/etc/caddy/Caddyfile`
+- Настройки:
+  - `no-store/no-cache` заголовки;
+  - `try_files {path} /index.html` (SPA fallback);
+  - `reverse_proxy /ws* -> 127.0.0.1:7070`;
+  - целевой сайт: `test.shineup.me`.
+
+## Deploy
+
+- Резервные задачи:
+  - `./gradlew deployServerTest`
+  - `./gradlew deployUITest`
+- Эти задачи пока не использовать без отдельной причины.
@@ -0,0 +1,47 @@
+# Сервер `shineup.me` — основной
+
+- SSH: `player@shineup.me`
+- Определение IP: через DNS-резолв домена `shineup.me` на момент подключения
+- Пользователь: `player`
+- Базовый путь: `/home/player`
+- Каталог SHiNE: `/home/player/SHiNE`
+- UI публикация: `/home/player/SHiNE/shine-ui`
+- Сервер: `/home/player/SHiNE/shine-server/shine-server.jar`
+- Данные: `/home/player/SHiNE/shine-server/data/`
+- Логи сервера: `/home/player/SHiNE/shine-server/logs/app.log`
+
+## Сервисы
+
+- `shine-server.service` (systemd)
+- `caddy.service` (systemd)
+
+## Caddy
+
+- Активный конфиг (через systemd `ExecStart`): `/home/player/SHiNE/caddy/Caddyfile`
+- Для UI:
+  - `root * /home/player/SHiNE/shine-ui`
+  - `try_files {path} /index.html` (SPA fallback)
+  - no-cache заголовки
+  - `reverse_proxy /ws* -> 127.0.0.1:7070`
+
+## Дополнительно
+
+- Для отдельной админки `shine_payments` используется каталог:
+  - `/home/player/sites/test-solana-tickets.shineup.me`
+- Эта публикация используется как временный тестовый сайт для сценариев покупки билетов и выплат `shine_payments`.
+- Домены этой публикации:
+  - `https://test-solana-tickets.shineup.me`
+  - `https://test-solana-tickets.shiningpeople.ru`
+- Для всех deploy-скриптов и инструкций использовать именно `player@shineup.me`, без жёсткой фиксации IP.
+
+## Правило изменений
+
+- `shineup.me` — production.
+- Любые изменения на этом сервере делать только после отдельного явного подтверждения пользователя.
+
+## Deploy
+
+- Production deploy-задачи:
+  - `./gradlew deployServerProduction`
+  - `./gradlew deployUIProduction`
+- Default deploy-задачи `./gradlew deployServer` и `./gradlew deployUI` сюда больше не относятся.
@@ -0,0 +1,173 @@
+# VPS `178.208.90.249` (`player`) — 4 тестовых SHiNE-сервера на devnet
+
+## Назначение
+
+Этот VPS используется как отдельный тестовый стенд для одновременного запуска 4 SHiNE-серверов:
+- `server_t1` → `https://t1.shineup.me`
+- `server_t2` → `https://t2.shineup.me`
+- `server_t3` → `https://t3.shineup.me`
+- `server_t4` → `https://t4.shineup.me`
+
+Все 4 инстанса работают через Solana `devnet`.
+
+## Каталоги
+
+Структура в домашней папке пользователя `player`:
+- `/home/player/t1/server`
+- `/home/player/t1/UI`
+- `/home/player/t2/server`
+- `/home/player/t2/UI`
+- `/home/player/t3/server`
+- `/home/player/t3/UI`
+- `/home/player/t4/server`
+- `/home/player/t4/UI`
+
+Дополнительно:
+- подробная памятка на самом сервере: `/home/player/Agents.md`
+
+## Порты и systemd
+
+Соответствие инстансов:
+- `t1` → localhost `7101` → `shine-t1.service`
+- `t2` → localhost `7102` → `shine-t2.service`
+- `t3` → localhost `7103` → `shine-t3.service`
+- `t4` → localhost `7104` → `shine-t4.service`
+
+Каждый unit запускает один и тот же jar:
+- `/home/player/tX/server/shine-server.jar`
+
+Рабочая директория каждого unit:
+- `/home/player/tX/server`
+
+Это важно, потому что сервер читает внешний `application.properties` именно из текущей рабочей директории.
+
+## Конфиги сервера
+
+У каждого инстанса свой файл:
+- `/home/player/tX/server/application.properties`
+
+Ключевые параметры в нём:
+- `server.port=710X`
+- `server.SHiNE.login=server_tX`
+- `db.path=data/shine.sqlite`
+- `solana.cluster=devnet`
+- `solana.rpcUrl=https://api.devnet.solana.com`
+- `server.ui.indexPath=/home/player/tX/UI/index.html`
+- `server.info.url=https://tX.shineup.me`
+- `server.info.origin=devnet`
+
+Важно:
+- Program ID SHiNE одинаковые для mainnet и devnet.
+- Поэтому для перевода инстанса на devnet достаточно правильных `solana.cluster` и `solana.rpcUrl`.
+
+## Конфиги UI
+
+У каждого домена лежит отдельная копия `shine-UI`.
+
+В каждой копии меняется `js/deploy-config.js`:
+- `defaultServerLogin=server_tX`
+- `defaultServerAddress=tX.shineup.me`
+- `defaultSolanaCluster=devnet`
+- `defaultSolanaEndpoint=https://api.devnet.solana.com`
+
+За счёт этого:
+- UI по умолчанию открывает именно свой сервер
+- `server-ui` формы по умолчанию используют именно `devnet`
+
+## Caddy
+
+Конфиг:
+- `/etc/caddy/Caddyfile`
+
+Логика по каждому сайту одинаковая:
+- статические файлы берутся из `/home/player/tX/UI`
+- путь `/ws` проксируется на `127.0.0.1:710X`
+
+Права доступа:
+- каталог `/home/player` и `/home/player/tX` должен быть доступен на `+x` для чтения через Caddy
+- все каталоги и файлы в `/home/player/tX/UI` должны быть читаемы пользователем `caddy`
+
+## Что уже проверено
+
+После настройки было подтверждено:
+- `https://t1.shineup.me` отвечает `HTTP 200`
+- `https://t2.shineup.me` отвечает `HTTP 200`
+- `https://t3.shineup.me` отвечает `HTTP 200`
+- `https://t4.shineup.me` отвечает `HTTP 200`
+- `Caddy` успешно выпустил сертификаты Let's Encrypt на все 4 домена
+- все 4 процесса Java слушают свои порты `7101..7104`
+- в логах есть строка `WS сервер запущен на ws://localhost:710X/ws`
+
+## Важный operational-нюанс
+
+Официальный `https://api.devnet.solana.com` может отдавать `HTTP 429`, если несколько инстансов одновременно делают bootstrap PDA/sync-серверов на старте.
+
+На практике это уже проявилось:
+- `t3` и `t4` подтянули `sync_servers` сразу
+- `t1` и `t2` на первом одновременном старте словили `429`
+- после последовательного рестарта `shine-t1` и `shine-t2` они тоже успешно сохранили `sync_servers`
+
+Если после очередного деплоя какой-то инстанс не подтянул `sync_servers`, сначала делать не массовый рестарт, а по одному:
+
+```bash
+sudo systemctl restart shine-t1
+sleep 8
+sudo systemctl restart shine-t2
+sleep 8
+sudo systemctl restart shine-t3
+sleep 8
+sudo systemctl restart shine-t4
+```
+
+## Как обновлять сервер
+
+1. Локально собрать jar:
+
+```bash
+./gradlew shadowJar
+```
+
+2. Залить `SHiNE-server/build/libs/shine-server.jar` в каждый нужный каталог:
+- `/home/player/t1/server/shine-server.jar`
+- `/home/player/t2/server/shine-server.jar`
+- `/home/player/t3/server/shine-server.jar`
+- `/home/player/t4/server/shine-server.jar`
+
+3. Если менялся runtime-конфиг, обновить соответствующий `application.properties`.
+
+4. Перезапускать сервисы лучше по одному, с паузой, чтобы снизить шанс `429` от devnet RPC.
+
+## Как обновлять UI
+
+1. Взять свежую локальную папку `shine-UI/`.
+2. Для каждой копии подставить свой `deploy-config.js`.
+3. Скопировать файлы в `/home/player/tX/UI/`.
+4. Проверить права чтения для Caddy.
+
+## Полезные команды на VPS
+
+Проверка сервисов:
+
+```bash
+sudo systemctl --no-pager --full status caddy shine-t1 shine-t2 shine-t3 shine-t4
+```
+
+Перезапуск одного инстанса:
+
+```bash
+sudo systemctl restart shine-t1
+```
+
+Логи одного инстанса:
+
+```bash
+tail -n 200 /home/player/t1/server/logs/app.log
+sudo journalctl -u shine-t1 -n 200 --no-pager
+```
+
+Проверка Caddy:
+
+```bash
+sudo caddy validate --config /etc/caddy/Caddyfile
+curl -I https://t1.shineup.me
+```
@@ -0,0 +1,12 @@
+# Тестовый VPS с 4 SHiNE-серверами
+
+В этой папке описан отдельный тестовый VPS `178.208.90.249`, на котором подняты 4 независимых SHiNE-инстанса под доменами `t1.shineup.me` ... `t4.shineup.me`.
+
+Текущая основная схема:
+- пользователь на VPS: `player`
+- все 4 инстанса работают через `devnet`
+- каждый инстанс имеет свой каталог `server`, свой каталог `UI`, свой `systemd` unit и свой localhost-порт
+- внешний HTTPS и маршрутизацию `/ws` обслуживает один общий `Caddy`
+
+Детальное описание:
+- [178.208.90.249_quad_devnet.md](/home/ai/work/SHiNE/SHiNE-server-sha256/Dev_Docs/deploy/test-server/178.208.90.249_quad_devnet.md)