diff --git a/README.md b/README.md index 99269d9..3f27ce0 100644 --- a/README.md +++ b/README.md @@ -1,212 +1,118 @@ -# Pulse / SWChat +# SWChat Core (Pulse) -Pulse — self-hosted Android/Web мессенджер на базе Matrix для экосистемы StackWorks. +Серверная часть собственного мессенджера StackWorks на базе Matrix/Synapse. Продуктовое имя — Pulse, техническое имя репозитория — SWChat. Репозиторий содержит не приложение, а инфраструктуру ядра: Docker Compose со Synapse и PostgreSQL, автоустановщик, скрипты диагностики и firewall, push-шлюз для Android и документацию по схеме split-server (публичный HTTPS через отдельный сервер с FastPanel → приватная сеть → Core с Matrix). Клиент (Android/Flutter на базе FluffyChat) ведётся в отдельном репозитории `SWChat-App`. -Техническое имя репозитория пока остаётся SWChat. Пользовательский бренд продукта — `Pulse by StackWorks`. +## Стек -Проект строится как собственная платформа связи: -- Matrix Core на отдельном сервере; -- PostgreSQL; -- FastPanel reverse proxy как публичный HTTPS слой; -- официальный Matrix/Element-клиент для первого тестирования; -- будущий web-клиент; -- будущий Android-клиент; -- будущая админ-панель; -- безопасная архитектура без вмешательства в существующий production. +- Matrix Synapse (образ `matrixdotorg/synapse:latest`), PostgreSQL 16, Caddy 2 — в Docker Compose. +- Bash: автоустановщик, healthcheck, настройка UFW. +- Push Gateway: Python, FastAPI 0.115, Uvicorn, `firebase-admin` 6.6 (Firebase Cloud Messaging), systemd-unit. +- Внешние сервисы и зависимости: Firebase FCM, FastPanel на отдельном сервере как публичный reverse proxy, Let's Encrypt через Caddy (в варианте с прямым HTTPS). -## Текущая стратегия +## Структура -Сначала поднимаем и проверяем серверное ядро через официальные Matrix-клиенты. +| Путь | Назначение | +|---|---| +| `docker-compose.yml` | Стек Core: PostgreSQL, Synapse, Caddy. Порт Synapse привязывается к `MATRIX_BIND_HOST` (по умолчанию только localhost), данные — в `/opt/swchat/data` | +| `scripts/install.sh` | Автоустановщик Core: ставит Docker, создаёт `/opt/swchat`, генерирует `.env` с случайными секретами, генерирует и правит `homeserver.yaml`, поднимает контейнеры. FastPanel не трогает | +| `scripts/healthcheck.sh` | Диагностика: переменные, список контейнеров, локальный и приватный endpoint Matrix, публичный HTTPS endpoint, статус UFW | +| `scripts/firewall_private_proxy.sh` | UFW: открыть порт Matrix (8008) только с IP FastPanel-прокси и закрыть прямой публичный доступ | +| `deploy/caddy/Caddyfile` | Reverse proxy Caddy на `synapse:8008` с автоматическим TLS для `SERVER_NAME` | +| `push-gateway/main.py` | FastAPI-шлюз: принимает `POST /_matrix/push/v1/notify` от Synapse и пересылает уведомления в Firebase FCM; `GET /health` | +| `push-gateway/requirements.txt` | Зависимости шлюза | +| `deploy/systemd/pulse-push-gateway.service` | systemd-unit шлюза: uvicorn на `0.0.0.0:8509` | +| `docs/ARCHITECTURE.md` | Архитектура ядра и требования изоляции от существующего production | +| `docs/FASTPANEL_PROXY.md`, `docs/FASTPANEL_REVERSE_PROXY.md`, `docs/DEPLOY_FASTPANEL_PROXY_STEPS.md`, `docs/PRIVATE_NETWORK_BETWEEN_SERVERS.md` | Схема публикации Matrix через FastPanel и приватную сеть между серверами | +| `docs/PUSH_NOTIFICATIONS.md`, `docs/PULSE_PUSH_GATEWAY.md` | Архитектура и установка push-уведомлений | +| `docs/ADMIN_PANEL.md` | Проект будущей админ-панели Pulse поверх Synapse Admin API (только замысел, кода нет) | +| `docs/RESET_ADMIN_PASSWORD.md` | Сброс пароля администратора Matrix | +| `.sw` | Главный журнал проекта: решения, версии, запреты, защищённые production-активы, следующий шаг | +| `VERSION` | Версия — `0.2.0` | +| `README.upstream.md` | Исходный README (сохранён при пересборке) | -Порядок: +## Как запустить -1. Поднять Pulse/SWChat Core на отдельном сервере. -2. Проверить Matrix/Synapse локально. -3. Настроить публичный домен `matrix.stackworks.ru` через FastPanel reverse proxy. -4. Проверить работу через официальные клиенты Matrix/Element. -5. Только после стабильной проверки продолжать глубокий ребрендинг собственного Android/Web-клиента. - -Это нужно, чтобы не путать проблемы сервера с проблемами будущего собственного UI. - -## Архитектура - -Pulse/SWChat работает по split-server архитектуре. - -### Новый сервер: Core - -На новом сервере размещаются: -- Matrix Synapse; -- PostgreSQL; -- media storage; -- будущий TURN/STUN; -- будущий backend API; -- backups; -- diagnostics. - -Текущие private IP: - -```text -FastPanel proxy: 192.168.0.221 -Matrix/Core: 192.168.0.141 -``` - -Рекомендуемые домены: - -```text -matrix.stackworks.ru -> Matrix API / Synapse через FastPanel reverse proxy -turn.stackworks.ru -> новый Core сервер, позже -api-chat.stackworks.ru -> будущий backend API -admin-chat.stackworks.ru -> будущая Pulse Admin Panel -chat.stackworks.ru -> будущий web-клиент -``` - -### Старый сервер с FastPanel - -Старый сервер с FastPanel используется как публичный HTTPS/reverse proxy слой и для будущего frontend/web-клиента. - -На нём остаются отдельно: -- ArtistFlow; -- widget.stackworks.ru; -- текущие сайты StackWorks/FastPanel. - -Installer не меняет FastPanel, не меняет vhost, не меняет SSL и не трогает существующие сайты. - -## Что нельзя трогать - -Защищённые production-активы: -- `artistflow.ru`; -- `widget.stackworks.ru`; -- текущие сайты FastPanel; -- настройки FastPanel без отдельной явной команды. - -`widget.stackworks.ru` на текущем этапе никак не связан с Matrix/Pulse. Новый виджет Pulse не планируется. - -## Установка Core - -На новом сервере Ubuntu: +Установка Core на чистом Ubuntu-сервере: ```bash sudo mkdir -p /opt/swchat -sudo git clone https://github.com/viktor138irk/SWChat.git /opt/swchat/source +sudo git clone /opt/swchat/source cd /opt/swchat/source -sudo SERVER_NAME=matrix.stackworks.ru bash scripts/install.sh +sudo SERVER_NAME=matrix.example.ru bash scripts/install.sh ``` -Installer: -- создаёт структуру `/opt/swchat`; -- устанавливает Docker, если он отсутствует; -- создаёт `.env`; -- генерирует Synapse config; -- настраивает PostgreSQL для Synapse; -- запускает контейнеры; -- не трогает FastPanel. +Установщик создаёт `/opt/swchat/.env` со сгенерированными секретами (`POSTGRES_PASSWORD`, `REGISTRATION_SHARED_SECRET`, `MACAROON_SECRET_KEY`, `FORM_SECRET`), генерирует конфиг Synapse и поднимает контейнеры. -## Настройка private reverse proxy - -По умолчанию Matrix endpoint слушает только localhost: - -```text -MATRIX_BIND_HOST=127.0.0.1 -``` - -Для схемы FastPanel reverse proxy → Core нужно на Core-сервере в `/opt/swchat/.env` указать private IP Core: - -```text -MATRIX_BIND_HOST=192.168.0.141 -``` - -Затем перезапустить stack: +Ручной запуск и перезапуск стека: ```bash cd /opt/swchat/source sudo docker compose --env-file /opt/swchat/.env up -d ``` -И закрыть прямой публичный доступ к Matrix, разрешив порт 8008 только FastPanel proxy: - -```bash -sudo FASTPANEL_PROXY_IP=192.168.0.221 MATRIX_PORT=8008 bash /opt/swchat/source/scripts/firewall_private_proxy.sh -``` - -Проверка с FastPanel proxy: - -```bash -curl http://192.168.0.141:8008/_matrix/client/versions -``` - -Проверка публичного HTTPS endpoint: - -```bash -curl https://matrix.stackworks.ru/_matrix/client/versions -``` - -## Проверка после установки +Проверка: ```bash sudo bash /opt/swchat/source/scripts/healthcheck.sh curl http://127.0.0.1:8008/_matrix/client/versions +curl https://matrix.example.ru/_matrix/client/versions ``` -Ожидаемый результат `curl` — JSON с версиями Matrix API. +Ограничение доступа к Matrix только с прокси-сервера: -## Тестирование официальными клиентами - -До разработки собственного клиента проверяем сервер через: -- Element Web; -- Element Desktop; -- Element Android; -- любые совместимые Matrix-клиенты. - -Проверяем: -- регистрацию/логин; -- личные сообщения; -- комнаты; -- отправку файлов; -- стабильность Synapse; -- работу публичного домена. - -## Android-клиент - -Клиентский репозиторий: - -```text -https://github.com/viktor138irk/SWChat-App +```bash +sudo FASTPANEL_PROXY_IP=192.168.0.221 MATRIX_PORT=8008 bash scripts/firewall_private_proxy.sh ``` -Важное правило staged-ребрендинга: -- пользовательские тексты и UI можно переводить на Pulse; -- `pubspec.yaml name` пока должен оставаться `fluffychat`, пока импорты используют `package:fluffychat/...`; -- Android applicationId сейчас принят как `ru.stackworks.swchat`; -- массовая миграция Dart package/imports — отдельный этап. +Push Gateway (на Core-сервере, вне Docker): -## Структура проекта - -```text -.sw главный журнал проекта -docker-compose.yml Matrix/PostgreSQL stack -scripts/install.sh автоустановщик Core-сервера -scripts/healthcheck.sh диагностика -scripts/firewall_private_proxy.sh безопасное ограничение 8008 под FastPanel proxy -docs/ документация -VERSION версия проекта +```bash +cd /opt/swchat/push-gateway +python3 -m venv venv +venv/bin/pip install -r requirements.txt +# положить рядом firebase-service-account.json +sudo cp deploy/systemd/pulse-push-gateway.service /etc/systemd/system/ +sudo systemctl enable --now pulse-push-gateway +curl http://127.0.0.1:8509/health ``` -## Правило `.sw` +Клиентское приложение в этом репозитории отсутствует: сборка и запуск Android-клиента не восстанавливаются из этого кода, они относятся к отдельному репозиторию `SWChat-App`. -Файл `.sw` — главный журнал проекта. +## Конфигурация -В него обязательно записываются: -- архитектурные решения; -- изменения версий; -- текущий статус; -- следующий шаг; -- ошибки и исправления; -- запреты и защищённые production-активы. +`/opt/swchat/.env` создаётся установщиком; в репозитории файла-шаблона нет. -Новый диалог по проекту начинается с чтения `.sw`. +| Переменная | Назначение | Пример | +|---|---|---| +| `SERVER_NAME` | Доменное имя Matrix-сервера, попадает в `homeserver.yaml` и Caddyfile | `matrix.example.ru` | +| `REPORT_STATS` | Отправка статистики в matrix.org | `no` | +| `MATRIX_BIND_HOST` | Адрес привязки порта 8008. `127.0.0.1` — только локально; приватный IP — для reverse proxy по локальной сети | `127.0.0.1` | +| `POSTGRES_DB` / `POSTGRES_USER` | База и пользователь Synapse | `synapse` / `synapse` | +| `POSTGRES_PASSWORD` | Пароль PostgreSQL, генерируется установщиком | см. `.env` | +| `REGISTRATION_SHARED_SECRET` | Секрет для `register_new_matrix_user` | см. `.env` | +| `MACAROON_SECRET_KEY`, `FORM_SECRET` | Секреты Synapse | см. `.env` | -## Текущий статус +Переменные установщика (задаются перед вызовом `install.sh`): `INSTALL_DIR`, `SOURCE_DIR`, `DATA_DIR`, `BACKUP_DIR`, `ENV_FILE`, `COMPOSE_FILE`, `AUTO_START`, `AUTO_INSTALL_DOCKER`. -Версия: `0.1.2` +Переменные `firewall_private_proxy.sh`: `FASTPANEL_PROXY_IP`, `MATRIX_PORT`, `ALLOW_SSH`, `SSH_PORT`, `APPLY_UFW_DEFAULTS` (по умолчанию `no`, чтобы не отрезать себе доступ). -Core работает на отдельном сервере, публичный HTTPS endpoint `https://matrix.stackworks.ru/_matrix/client/versions` уже был проверен через FastPanel reverse proxy. Текущий этап — закрепление private proxy/firewall схемы и staged-ребрендинг Android-клиента в Pulse без поломки FluffyChat imports. +Push Gateway: `FIREBASE_SERVICE_ACCOUNT` — путь к JSON сервисного аккаунта Firebase (по умолчанию `/opt/swchat/push-gateway/firebase-service-account.json`). Сам файл в репозитории отсутствует и должен добавляться на сервере. + +## Состояние + +Прототип инфраструктуры, работа остановлена. 68 коммитов, даты 2026-05-08 и 2026-05-09, последний коммит — 2026-05-09. Версия `0.2.0`. + +По журналу `.sw`: Core был поднят на отдельном сервере, публичный HTTPS endpoint `https://matrix.example.ru/_matrix/client/versions` проверялся и отвечал через FastPanel reverse proxy, вход через Element работал. То есть серверное ядро функционировало, но собственного продукта поверх него (клиент, backend API, админка) в этом репозитории нет. + +Отдельно зафиксированы жёсткие ограничения: установщик и скрипты не должны трогать FastPanel, домены `artistflow.ru` и `widget.stackworks.ru` и их конфигурацию. + +## Что не доделано + +- Нет backend API Pulse (регистрация из приложения, профили, поиск людей без ввода Matrix-домена) — только описание требований в `.sw`. +- Нет админ-панели: `docs/ADMIN_PANEL.md` описывает планируемый стек (PHP 8.3 / Laravel либо lightweight backend, Blade + Alpine.js), кода нет. +- Push Gateway минимален: текст уведомления захардкожен (`Pulse` / `Новое сообщение`), нет аутентификации входящего запроса от Synapse, ошибки отправки только печатаются в stdout, массив `rejected` всегда пустой (невалидные pushkey не возвращаются Synapse), нет batch-отправки. Unit запускает сервис от `root` и слушает `0.0.0.0:8509` без TLS. +- Не описано и не автоматизировано подключение pusher со стороны Synapse к шлюзу — только текстовая инструкция в `docs/`. +- Нет backup-скриптов, TURN/STUN, мониторинга — они значатся в архитектуре как будущие компоненты. +- Нет тестов, CI и линтеров. +- В `docker-compose.yml` используется `matrixdotorg/synapse:latest` без фиксации версии. +- Часть документации отстала от продукта: `docs/ARCHITECTURE.md` написан ещё под старым именем WSMessenger. diff --git a/README.upstream.md b/README.upstream.md new file mode 100644 index 0000000..99269d9 --- /dev/null +++ b/README.upstream.md @@ -0,0 +1,212 @@ +# Pulse / SWChat + +Pulse — self-hosted Android/Web мессенджер на базе Matrix для экосистемы StackWorks. + +Техническое имя репозитория пока остаётся SWChat. Пользовательский бренд продукта — `Pulse by StackWorks`. + +Проект строится как собственная платформа связи: +- Matrix Core на отдельном сервере; +- PostgreSQL; +- FastPanel reverse proxy как публичный HTTPS слой; +- официальный Matrix/Element-клиент для первого тестирования; +- будущий web-клиент; +- будущий Android-клиент; +- будущая админ-панель; +- безопасная архитектура без вмешательства в существующий production. + +## Текущая стратегия + +Сначала поднимаем и проверяем серверное ядро через официальные Matrix-клиенты. + +Порядок: + +1. Поднять Pulse/SWChat Core на отдельном сервере. +2. Проверить Matrix/Synapse локально. +3. Настроить публичный домен `matrix.stackworks.ru` через FastPanel reverse proxy. +4. Проверить работу через официальные клиенты Matrix/Element. +5. Только после стабильной проверки продолжать глубокий ребрендинг собственного Android/Web-клиента. + +Это нужно, чтобы не путать проблемы сервера с проблемами будущего собственного UI. + +## Архитектура + +Pulse/SWChat работает по split-server архитектуре. + +### Новый сервер: Core + +На новом сервере размещаются: +- Matrix Synapse; +- PostgreSQL; +- media storage; +- будущий TURN/STUN; +- будущий backend API; +- backups; +- diagnostics. + +Текущие private IP: + +```text +FastPanel proxy: 192.168.0.221 +Matrix/Core: 192.168.0.141 +``` + +Рекомендуемые домены: + +```text +matrix.stackworks.ru -> Matrix API / Synapse через FastPanel reverse proxy +turn.stackworks.ru -> новый Core сервер, позже +api-chat.stackworks.ru -> будущий backend API +admin-chat.stackworks.ru -> будущая Pulse Admin Panel +chat.stackworks.ru -> будущий web-клиент +``` + +### Старый сервер с FastPanel + +Старый сервер с FastPanel используется как публичный HTTPS/reverse proxy слой и для будущего frontend/web-клиента. + +На нём остаются отдельно: +- ArtistFlow; +- widget.stackworks.ru; +- текущие сайты StackWorks/FastPanel. + +Installer не меняет FastPanel, не меняет vhost, не меняет SSL и не трогает существующие сайты. + +## Что нельзя трогать + +Защищённые production-активы: +- `artistflow.ru`; +- `widget.stackworks.ru`; +- текущие сайты FastPanel; +- настройки FastPanel без отдельной явной команды. + +`widget.stackworks.ru` на текущем этапе никак не связан с Matrix/Pulse. Новый виджет Pulse не планируется. + +## Установка Core + +На новом сервере Ubuntu: + +```bash +sudo mkdir -p /opt/swchat +sudo git clone https://github.com/viktor138irk/SWChat.git /opt/swchat/source +cd /opt/swchat/source +sudo SERVER_NAME=matrix.stackworks.ru bash scripts/install.sh +``` + +Installer: +- создаёт структуру `/opt/swchat`; +- устанавливает Docker, если он отсутствует; +- создаёт `.env`; +- генерирует Synapse config; +- настраивает PostgreSQL для Synapse; +- запускает контейнеры; +- не трогает FastPanel. + +## Настройка private reverse proxy + +По умолчанию Matrix endpoint слушает только localhost: + +```text +MATRIX_BIND_HOST=127.0.0.1 +``` + +Для схемы FastPanel reverse proxy → Core нужно на Core-сервере в `/opt/swchat/.env` указать private IP Core: + +```text +MATRIX_BIND_HOST=192.168.0.141 +``` + +Затем перезапустить stack: + +```bash +cd /opt/swchat/source +sudo docker compose --env-file /opt/swchat/.env up -d +``` + +И закрыть прямой публичный доступ к Matrix, разрешив порт 8008 только FastPanel proxy: + +```bash +sudo FASTPANEL_PROXY_IP=192.168.0.221 MATRIX_PORT=8008 bash /opt/swchat/source/scripts/firewall_private_proxy.sh +``` + +Проверка с FastPanel proxy: + +```bash +curl http://192.168.0.141:8008/_matrix/client/versions +``` + +Проверка публичного HTTPS endpoint: + +```bash +curl https://matrix.stackworks.ru/_matrix/client/versions +``` + +## Проверка после установки + +```bash +sudo bash /opt/swchat/source/scripts/healthcheck.sh +curl http://127.0.0.1:8008/_matrix/client/versions +``` + +Ожидаемый результат `curl` — JSON с версиями Matrix API. + +## Тестирование официальными клиентами + +До разработки собственного клиента проверяем сервер через: +- Element Web; +- Element Desktop; +- Element Android; +- любые совместимые Matrix-клиенты. + +Проверяем: +- регистрацию/логин; +- личные сообщения; +- комнаты; +- отправку файлов; +- стабильность Synapse; +- работу публичного домена. + +## Android-клиент + +Клиентский репозиторий: + +```text +https://github.com/viktor138irk/SWChat-App +``` + +Важное правило staged-ребрендинга: +- пользовательские тексты и UI можно переводить на Pulse; +- `pubspec.yaml name` пока должен оставаться `fluffychat`, пока импорты используют `package:fluffychat/...`; +- Android applicationId сейчас принят как `ru.stackworks.swchat`; +- массовая миграция Dart package/imports — отдельный этап. + +## Структура проекта + +```text +.sw главный журнал проекта +docker-compose.yml Matrix/PostgreSQL stack +scripts/install.sh автоустановщик Core-сервера +scripts/healthcheck.sh диагностика +scripts/firewall_private_proxy.sh безопасное ограничение 8008 под FastPanel proxy +docs/ документация +VERSION версия проекта +``` + +## Правило `.sw` + +Файл `.sw` — главный журнал проекта. + +В него обязательно записываются: +- архитектурные решения; +- изменения версий; +- текущий статус; +- следующий шаг; +- ошибки и исправления; +- запреты и защищённые production-активы. + +Новый диалог по проекту начинается с чтения `.sw`. + +## Текущий статус + +Версия: `0.1.2` + +Core работает на отдельном сервере, публичный HTTPS endpoint `https://matrix.stackworks.ru/_matrix/client/versions` уже был проверен через FastPanel reverse proxy. Текущий этап — закрепление private proxy/firewall схемы и staged-ребрендинг Android-клиента в Pulse без поломки FluffyChat imports.