SWChat/README.md

# SWChat Core (Pulse)

Серверная часть собственного мессенджера StackWorks на базе Matrix/Synapse. Продуктовое имя — Pulse, техническое имя репозитория — SWChat. Репозиторий содержит не приложение, а инфраструктуру ядра: Docker Compose со Synapse и PostgreSQL, автоустановщик, скрипты диагностики и firewall, push-шлюз для Android и документацию по схеме split-server (публичный HTTPS через отдельный сервер с FastPanel → приватная сеть → Core с Matrix). Клиент (Android/Flutter на базе FluffyChat) ведётся в отдельном репозитории `SWChat-App`.

## Стек

- 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).

## Структура

| Путь | Назначение |
|---|---|
| `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 (сохранён при пересборке) |

## Как запустить

Установка Core на чистом Ubuntu-сервере:

```bash
sudo mkdir -p /opt/swchat
sudo git clone <repo-url> /opt/swchat/source
cd /opt/swchat/source
sudo SERVER_NAME=matrix.example.ru bash scripts/install.sh
```

Установщик создаёт `/opt/swchat/.env` со сгенерированными секретами (`POSTGRES_PASSWORD`, `REGISTRATION_SHARED_SECRET`, `MACAROON_SECRET_KEY`, `FORM_SECRET`), генерирует конфиг Synapse и поднимает контейнеры.

Ручной запуск и перезапуск стека:

```bash
cd /opt/swchat/source
sudo docker compose --env-file /opt/swchat/.env up -d
```

Проверка:

```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
```

Ограничение доступа к Matrix только с прокси-сервера:

```bash
sudo FASTPANEL_PROXY_IP=192.168.0.221 MATRIX_PORT=8008 bash scripts/firewall_private_proxy.sh
```

Push Gateway (на Core-сервере, вне Docker):

```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
```

Клиентское приложение в этом репозитории отсутствует: сборка и запуск Android-клиента не восстанавливаются из этого кода, они относятся к отдельному репозиторию `SWChat-App`.

## Конфигурация

`/opt/swchat/.env` создаётся установщиком; в репозитории файла-шаблона нет.

| Переменная | Назначение | Пример |
|---|---|---|
| `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`.

Переменные `firewall_private_proxy.sh`: `FASTPANEL_PROXY_IP`, `MATRIX_PORT`, `ALLOW_SSH`, `SSH_PORT`, `APPLY_UFW_DEFAULTS` (по умолчанию `no`, чтобы не отрезать себе доступ).

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.