Добавить тестовые каналы и Arweave-синхронизацию

tools/test-publisher/v2/CODEX_VPS_SETUP.md

@@ -0,0 +1,87 @@
+# CODEX_VPS_SETUP.md — развернуть автономный SHiNE test publisher
+
+Цель: установить test publisher на Ubuntu VPS так, чтобы он постоянно работал через systemd, переживал reboot/сбой сети, публиковал в несколько каналов одного тестового пользователя и не требовал ручного запуска.
+
+## Что агент должен получить от оператора
+Никогда не печатай приватные ключи в лог.
+1. Реальный `blockchain_name` тестового пользователя.
+2. Solana-format JSON blockchain key → `keys/blockchain.json`.
+3. Arweave JWK → `keys/arweave-wallet.json` (нужен только для prepare).
+4. Для каждого канала реальный `channel_root_block_number` CREATE_CHANNEL.
+5. Подтверждение WebSocket URL сервера (example: `wss://t3.shineup.me/ws`).
+
+## Установка
+Предполагаемый каталог: `/opt/shine-test-publisher/v2`, Linux user: `shine`.
+
+```bash
+sudo useradd --system --home /opt/shine-test-publisher --shell /usr/sbin/nologin shine 2>/dev/null || true
+sudo mkdir -p /opt/shine-test-publisher
+sudo chown -R shine:shine /opt/shine-test-publisher
+# скопировать содержимое tools/test-publisher/v2 в /opt/shine-test-publisher/v2
+
+cd /opt/shine-test-publisher
+sudo -u shine python3 -m venv .venv
+sudo -u shine .venv/bin/pip install -r v2/requirements.txt
+sudo chmod 700 v2/keys
+sudo chmod 600 v2/keys/*.json
+```
+
+`requirements.txt` должен содержать зависимости publisher и prepare (`cryptography`, `websockets`, `requests`, `arweave-python-client`).
+
+## Конфиги
+Скопировать:
+- `config.multi.example.json` → `config.multi.json`
+- `prepare.multi.example.json` → `prepare.multi.json`
+
+Заменить placeholders. Не угадывать CREATE_CHANNEL block numbers.
+
+Расписание по умолчанию:
+- jokes: случайно 1–3 активных часа;
+- остальные: случайно 3–7 активных часов;
+- timezone: Europe/Warsaw;
+- quiet: 22:00–08:00.
+
+Quiet hours НЕ расходуют интервал. Если из 5 часов до ночи прошло 2 часа, после 08:00 должно остаться 3 часа.
+
+## Подготовка media
+Один раз и затем после добавления новых картинок:
+```bash
+cd /opt/shine-test-publisher/v2
+../.venv/bin/python prepare/prepare_all_channels.py --config prepare.multi.json
+```
+Скрипт обязан пройти ВСЕ channels. Известный Arweave ID сначала проверяется через gateway. Существующий файл повторно не загружается. Отсутствующий — загружается и state обновляется атомарно.
+
+После успешной подготовки JWK не нужен постоянному publisher. Для минимизации риска можно перенести JWK в защищённое offline-хранилище; тогда повторный prepare потребует вернуть его.
+
+## Проверка до systemd
+```bash
+../.venv/bin/python publisher/publisher_multi.py status --config config.multi.json
+../.venv/bin/python publisher/publisher_multi.py publish-now --channel jokes --config config.multi.json
+```
+Проверить появление блока на SHiNE server и затем в Viewer. Не запускать два экземпляра publisher для одного blockchain key.
+
+## systemd
+```bash
+sudo cp systemd/shine-test-publisher-multi.service /etc/systemd/system/
+sudo systemctl daemon-reload
+sudo systemctl enable --now shine-test-publisher-multi
+sudo systemctl status shine-test-publisher-multi
+journalctl -u shine-test-publisher-multi -f
+```
+
+Unit использует `Restart=on-failure`; publisher хранит pending/state на диске и после рестарта сверяет global head перед продолжением. При конфликте global head он обязан остановиться, а не создавать форк.
+
+## После настройки
+Проверить:
+- `systemctl is-enabled` = enabled;
+- `systemctl is-active` = active;
+- `multi-state.json` создаётся и меняется;
+- в quiet hours нет публикаций;
+- reboot VPS → service возвращается в active;
+- приватные JSON имеют mode 600;
+- prepared queues существуют для всех пяти каналов.
+
+## Запреты
+Не коммитить/архивировать реальные keys, JWK, `multi-state.json`, `upload-state.json`.
+Не запускать параллельно v1/v2 single publisher и multi publisher с одним ключом.
+Не сбрасывать state ради устранения ошибки chain-head: сначала выяснить расхождение.