SWChat/.sw

# SWChat Core — серверный журнал проекта

Дата старта: 2026-05-08
Дата обновления: 2026-05-09
Репозиторий Core/backend/docs: https://github.com/viktor138irk/SWChat
Репозиторий Android/client: https://github.com/viktor138irk/SWChat-App
Публичное имя продукта: Pulse
Техническое имя серверного проекта: SWChat Core
Брендовая формула: Pulse by StackWorks
Проект: серверная часть собственного мессенджера Android/Web на базе Matrix/Synapse.

---

## Разделение журналов

С 2026-05-09 разработка ведётся как единый комбайн Pulse/SWChat в одном рабочем чате, но журналы разделены по репозиториям.

- `viktor138irk/SWChat/.sw` — только сервер, Core, Synapse, PostgreSQL, reverse proxy, firewall, домены, backend/API/admin.
- `viktor138irk/SWChat-App/.sw` — Android/Flutter-клиент, FluffyChat, UI/UX Pulse, package/applicationId, APK, локализации, иконки, deep links.

Правило: в серверный `.sw` не заносить клиентские детали SWChat-App/Pulse UI, кроме ссылок на клиентский репозиторий и общей схемы интеграции.

---

## Главное правило проекта

Не ломать существующие проекты на сервере.

Защищённые production-активы:
- ArtistFlow / artistflow.ru;
- основной виджет StackWorks / https://widget.stackworks.ru/;
- текущие сайты и домены FastPanel.

Запрещено без отдельной явной команды пользователя:
- менять настройки FastPanel;
- менять vhost/config доменов FastPanel;
- применять proxy-настройки в FastPanel;
- перезаписывать nginx-конфиги, которыми управляет FastPanel;
- перезапускать/переустанавливать FastPanel;
- ставить новый Nginx поверх FastPanel;
- менять SSL-сертификаты через FastPanel;
- менять webroot существующих сайтов;
- трогать production-домены;
- менять vhost/config домена widget.stackworks.ru;
- менять webroot виджета;
- затирать файлы виджета;
- интегрировать widget.stackworks.ru с Matrix;
- создавать новый параллельный виджет для Pulse;
- менять vhost/config домена artistflow.ru;
- трогать MySQL/БД ArtistFlow.

Разрешено:
- готовить инструкции;
- готовить шаблоны proxy-конфигов;
- готовить безопасные команды проверки;
- готовить backup/firewall-скрипты;
- описывать, что пользователь может сделать вручную в FastPanel.

---

## Постоянное правило ведения .sw

Файл `.sw` является главным журналом соответствующего репозитория и ведётся постоянно.

Обязательно записывать в `.sw`:
- каждый значимый шаг разработки;
- архитектурные решения;
- запреты и ограничения;
- защищённые домены и сервисы;
- изменения версий;
- что было создано или изменено;
- текущий статус;
- следующий шаг;
- важные ошибки и выводы после исправлений.

В новом диалоге продолжение серверной части начинается с чтения `viktor138irk/SWChat/.sw`.
Для Android-клиента начинать с чтения `viktor138irk/SWChat-App/.sw`.

---

## Решение по названию

2026-05-09 зафиксировано публичное имя продукта:

```text
Pulse
```

Брендовая формула:

```text
Pulse by StackWorks
```

Важно: технические репозитории остаются прежними:
- Core/backend/docs: `viktor138irk/SWChat`;
- Android/client: `viktor138irk/SWChat-App`.

Серверные директории `/opt/swchat/*` пока не переименовывать без отдельного этапа server rename.

---

## Принятая серверная архитектура

Core разворачивается на отдельном сервере.

Базовая схема:
- Matrix Synapse — отдельный сервис на приватном IP:8008;
- PostgreSQL — отдельная база для Matrix/Pulse;
- backend/API Pulse — отдельный локальный сервис в будущем;
- админка Pulse — отдельный защищённый модуль поверх Synapse Admin API в будущем;
- web-client — на FastPanel-сервере в будущем;
- Android-приложение — отдельный клиент из репозитория `SWChat-App`;
- FastPanel/Nginx reverse proxy — основной публичный HTTPS слой.

Основная публичная схема:

```text
пользователь → FastPanel/Nginx HTTPS → Core-сервер Matrix Synapse по private IP
```

Принято решение использовать:

```text
FastPanel reverse proxy → Core
```

---

## Приватная сеть между серверами

FastPanel proxy сервер и Core объединены в локальную сеть.

Текущие private IP:
- FastPanel proxy: `192.168.0.221`;
- Matrix/Core: `192.168.0.141`.

Рекомендованная схема:
- FastPanel proxy имеет public IP;
- Core-сервер использует private IP `192.168.0.141`;
- `proxy_pass` идёт на `http://192.168.0.141:8008`;
- прямой доступ к Core:8008 из интернета закрыт;
- доступ к Core:8008 разрешён только с `192.168.0.221`.

В docker-compose с версии 0.1.2 порт Synapse настраивается через `.env`:

```text
MATRIX_BIND_HOST=127.0.0.1
```

Для private proxy схемы надо ставить:

```text
MATRIX_BIND_HOST=192.168.0.141
```

После изменения `.env` перезапуск:

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

Для ограничения прямого доступа использовать:

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

---

## DNS и wildcard-поддомены

Если домен `stackworks.ru` и все его поддомены уже направлены wildcard-записью на FastPanel-сервер, отдельную DNS A-запись для `matrix.stackworks.ru` можно не создавать.

Достаточно:
- убедиться, что `*.stackworks.ru` указывает на публичный IP FastPanel;
- создать отдельный сайт `matrix.stackworks.ru` внутри FastPanel;
- выпустить SSL для `matrix.stackworks.ru`;
- настроить для этого сайта reverse proxy на `http://192.168.0.141:8008`.

---

## Домены проекта

Рекомендуемая безопасная схема:
- `matrix.stackworks.ru` — Matrix API / Synapse через FastPanel reverse proxy;
- `turn.stackworks.ru` — TURN/STUN, новый Core сервер;
- `api-chat.stackworks.ru` — backend API, новый Core сервер, если понадобится;
- `admin-chat.stackworks.ru` — будущая Pulse Admin Panel;
- `chat.stackworks.ru` или `messenger.stackworks.ru` — web-клиент на FastPanel-сервере;
- `widget.stackworks.ru` — отдельный production-виджет StackWorks, не часть Matrix/Pulse на текущем этапе.

---

## Предварительные директории Core-сервера

- `/opt/swchat/source` — исходники GitHub;
- `/opt/swchat/app` — backend/API/админка;
- `/opt/swchat/matrix` — Matrix/Synapse;
- `/opt/swchat/data` — данные контейнеров;
- `/opt/swchat/backups` — резервные копии;
- `/opt/swchat/logs` — логи.

До отдельного этапа server rename директории `/opt/swchat/*` не менять.

---

## MVP серверной части

Минимальные серверные функции:
- стабильный Matrix/Synapse homeserver;
- PostgreSQL для Synapse;
- публичный HTTPS endpoint через FastPanel reverse proxy;
- закрытый прямой доступ к Core:8008 из интернета;
- регистрация пользователей через controlled registration или будущий backend;
- интеграция Android-клиента с `https://matrix.stackworks.ru`;
- личные сообщения;
- групповые чаты;
- отправка файлов/изображений;
- backend/API для профилей, поиска людей и регистрации;
- админка управления пользователями;
- диагностика состояния Synapse/PostgreSQL/proxy;
- журнал состояния проекта в этом файле `.sw`.

---

## Регистрация и поиск людей — серверная схема

Пользовательский UX реализуется в клиенте, но сервер должен обеспечить нормальную механику:

- backend создаёт Matrix-пользователя через Synapse Admin/Register API;
- backend хранит публичный профиль Pulse: display_name, username, phone/email optional, avatar, статус;
- поиск людей лучше делать через свой backend/index, а не напрямую через сырой Matrix room/user lookup;
- Matrix user_id и домен остаются внутренней технической деталью;
- direct room создаётся автоматически клиентом/серверной логикой при первом сообщении контакту.

---

## Админка Pulse

Админка нужна обязательно и должна быть отдельным модулем поверх Matrix/Synapse Admin API.

Назначение админки:
- управление пользователями;
- создание/блокировка/разблокировка пользователей;
- сброс паролей;
- назначение и снятие admin-флага;
- просмотр профилей и устройств;
- управление чатами/группами;
- модерация жалоб;
- просмотр базовой статистики;
- настройки регистрации;
- настройки homeserver;
- управление TURN/STUN после добавления звонков;
- диагностика состояния Synapse/PostgreSQL/proxy.

---

## Стратегия тестирования Core

Сначала Core тестируется через официальные Matrix-клиенты.
Собственный клиент развивается отдельно в `SWChat-App`, но сервер должен оставаться проверяемым через стандартные Matrix endpoint.

Проверять:
- регистрацию/логин;
- личные сообщения;
- групповые чаты;
- отправку файлов;
- стабильность Synapse;
- работу публичного домена;
- доступность `/_matrix/client/versions`;
- firewall-ограничение прямого доступа к 8008;
- совместимость с Android-клиентом Pulse.

---

## Правила ведения серверного проекта

1. Каждый заметный серверный шаг записывать в этот файл `.sw`.
2. Новые версии фиксировать в `VERSION` и changelog/журнале.
3. Не плодить мусорные директории.
4. Все сервисы Pulse держать отдельно от ArtistFlow и widget.stackworks.ru.
5. Не вносить изменения в существующие домены без явной команды.
6. Для FastPanel давать точные proxy-конфиги, но не затирать чужие.
7. Перед потенциально опасными действиями добавлять backup/firewall-скрипт.
8. Любые действия с widget.stackworks.ru только после отдельной явной команды.
9. Ведение `.sw` обязательно на протяжении всего проекта.
10. Всё, что касается текущего production FastPanel, не трогать самостоятельно: только инструкции/шаблоны до отдельной команды пользователя.
11. Клиентские Android/Flutter задачи записывать в `viktor138irk/SWChat-App/.sw`, а не в серверный журнал.
12. Серверный журнал хранит только интеграционные требования к клиенту: endpoint, API, регистрация, поиск, push/backend, admin.
13. Публичный бренд продукта — Pulse, но серверный технический проект остаётся SWChat Core до отдельной миграции.

---

## История разработки

### 2026-05-08

- Репозиторий переименован в `viktor138irk/SWChat`.
- Создан файл `.sw`.
- Созданы `VERSION`, `README.md` и базовый `docker-compose.yml`.
- Созданы `docs/ARCHITECTURE.md` и `docs/FASTPANEL_PROXY.md`.
- Созданы `scripts/healthcheck.sh` и `scripts/install.sh`.
- Подготовлен автоустановщик.
- Принято решение ставить Core на отдельный сервер.
- Старый FastPanel-сервер использовать только для frontend/web-client в будущем.
- Принято решение сначала тестировать Core официальными Matrix-клиентами.
- Исправлен `docker-compose.yml`: контейнеры переименованы в `swchat-*`, убран obsolete `version`, добавлены переменные `.env`.
- Исправлена PostgreSQL locale для Synapse: добавлены `POSTGRES_INITDB_ARGS` с locale `C`.
- Исправлена проблема compose down без env: `POSTGRES_PASSWORD` получил безопасный fallback.
- Core успешно поднялся на новом сервере: `swchat-synapse healthy`, `swchat-postgres up`.
- Локальный Matrix endpoint успешно отвечает: `curl http://127.0.0.1:8008/_matrix/client/versions` вернул HTTP 200 OK и JSON версий Matrix API.

### 2026-05-09 — v0.1.1

- Версия проекта повышена до 0.1.1.
- В `docker-compose.yml` добавлен отдельный контейнер `swchat-caddy`.
- Создан `deploy/caddy/Caddyfile`.
- Обновлён `scripts/healthcheck.sh`.
- Принято финальное решение использовать схему FastPanel reverse proxy → Core.
- Создан `docs/FASTPANEL_REVERSE_PROXY.md`.
- Создан `docs/PRIVATE_NETWORK_BETWEEN_SERVERS.md`.
- Уточнены реальные private IP: FastPanel proxy `192.168.0.221`, Matrix/Core `192.168.0.141`.
- Проверено с FastPanel proxy: `curl http://192.168.0.141:8008/_matrix/client/versions` успешно вернул JSON Matrix API.
- Проверено: `https://matrix.stackworks.ru/_matrix/client/versions` через FastPanel reverse proxy успешно вернул Matrix API JSON.
- Публичный HTTPS endpoint Matrix через FastPanel работает.
- Проверено: `registration_shared_secret` присутствует в `/opt/swchat/data/synapse/homeserver.yaml`.
- Зафиксировано: bootstrap-регистрация администратора через `register_new_matrix_user` разрешена.
- При входе в Element пойман `M_LIMIT_EXCEEDED` после нескольких попыток авторизации.
- Зафиксирована необходимость Admin Panel для управления пользователями и модерации.
- Принято требование: регистрация прямо из приложения и поиск людей без необходимости вводить Matrix-домен.
- Зафиксировано публичное имя продукта: Pulse.

### 2026-05-09 — v0.1.2

- Версия проекта повышена до 0.1.2.
- `VERSION` обновлён до `0.1.2`.
- `README.md` актуализирован под бренд Pulse, split-server архитектуру и private reverse proxy схему.
- В `docker-compose.yml` порт Synapse сделан настраиваемым через переменную `MATRIX_BIND_HOST`.
- По умолчанию Matrix endpoint остаётся безопасным localhost-only: `127.0.0.1:8008`.
- Для схемы FastPanel proxy → Core теперь можно указать `MATRIX_BIND_HOST=192.168.0.141` в `/opt/swchat/.env`.
- `scripts/install.sh` обновлён: добавлена переменная `MATRIX_BIND_HOST`, автоматическое добавление отсутствующей переменной в существующий `.env`, уточнены next steps.
- `scripts/healthcheck.sh` расширен: показывает `SERVER_NAME`, `MATRIX_BIND_HOST`, контейнеры компактной таблицей, проверяет local endpoint, private bound endpoint, публичный HTTPS endpoint и UFW status.
- Создан `scripts/firewall_private_proxy.sh`.
- `scripts/firewall_private_proxy.sh` разрешает доступ к Matrix 8008 только с FastPanel proxy IP и закрывает публичный прямой доступ к 8008.
- По умолчанию firewall-скрипт не меняет default policy UFW, чтобы не запереть сервер случайно; для чистого Core можно запускать с `APPLY_UFW_DEFAULTS=yes`.
- Зафиксировано правило: прямой доступ к Core:8008 из интернета должен быть закрыт, публичный вход только через `https://matrix.stackworks.ru`.

### 2026-05-09 — разделение журналов

- Серверный `.sw` очищен от подробной клиентской информации SWChat-App/Pulse UI.
- Клиентская информация теперь должна храниться в `viktor138irk/SWChat-App/.sw`.
- В серверном `.sw` оставлены только Core/Synapse/PostgreSQL/proxy/firewall/backend/admin и интеграционные требования к клиенту.
- Зафиксировано правило: разработка идёт в одном чате как единый комбайн, но журналы ведутся отдельно по репозиториям.

---

## Текущий этап установки

Core локально работает на новом отдельном сервере.

Публичный HTTPS endpoint через FastPanel reverse proxy ранее был проверен и работал:

```text
https://matrix.stackworks.ru/_matrix/client/versions
```

В Core-репозитории подготовлен безопасный механизм для private proxy bind и firewall-ограничения порта 8008.

Клиентский Android-проект и его текущие задачи ведутся отдельно в:

```text
https://github.com/viktor138irk/SWChat-App/.sw
```

---

## Следующий шаг Core

Следующий серверный этап:
- на Core-сервере проверить `.env`;
- выставить `MATRIX_BIND_HOST=192.168.0.141`, если FastPanel reverse proxy ходит к Core по private IP;
- выполнить `sudo docker compose --env-file /opt/swchat/.env up -d`;
- выполнить `sudo bash /opt/swchat/source/scripts/healthcheck.sh`;
- с FastPanel proxy проверить `curl http://192.168.0.141:8008/_matrix/client/versions`;
- применить firewall-ограничение: `sudo FASTPANEL_PROXY_IP=192.168.0.221 MATRIX_PORT=8008 bash /opt/swchat/source/scripts/firewall_private_proxy.sh`;
- ещё раз проверить `https://matrix.stackworks.ru/_matrix/client/versions`;
- начать проектирование backend/API для регистрации, профилей и поиска людей;
- отдельным этапом поднять готовую Synapse Admin UI или начать Pulse Admin Panel.