docs: подробный README (разбор проекта при переносе в Gitea)
Старый README сохранён как README.upstream.md.
Этот коммит содержится в:
+100
-279
@@ -1,317 +1,138 @@
|
||||
# Raspi Telegram Live Chat
|
||||
# WSChat
|
||||
|
||||
Self-hosted live chat system for Raspberry Pi with embeddable website widget, web admin panel, Telegram as the operator interface, and a separate VPS-hosted frontend.
|
||||
Self-hosted онлайн-консультант для сайта (аналог Jivo/Tidio) с Telegram в роли интерфейса оператора. Посетитель пишет через встраиваемый виджет, сообщение попадает в бэкенд, оттуда рассылается назначенным операторам в Telegram; ответ оператора возвращается в виджет по WebSocket. Предназначен для владельца одного или нескольких сайтов, который не хочет платить за SaaS-чат и держит инфраструктуру на своём VPS с FastPanel.
|
||||
|
||||
## Goal
|
||||
## Стек
|
||||
|
||||
Build a lightweight Jivo-like chat platform where visitors write through a website widget and only Telegram operators configured in the admin panel receive and answer messages.
|
||||
- Node.js 20+, ESM.
|
||||
- Backend: Fastify 5, `@fastify/cors`, `@fastify/rate-limit`, `@fastify/websocket`.
|
||||
- БД: SQLite через `better-sqlite3` (WAL, foreign keys), схема создаётся кодом при старте.
|
||||
- Telegram: `telegraf` 4, опционально через SOCKS5 (`socks-proxy-agent`, схема `socks5h://`).
|
||||
- Админ-панель: React + Vite, `lucide-react`.
|
||||
- Виджет: ванильный JS, сборка Vite, изоляция через Shadow DOM.
|
||||
- Деплой: npm workspaces, PM2, FastPanel (nginx/Apache под управлением панели), rsync.
|
||||
|
||||
## Target deployment
|
||||
## Структура
|
||||
|
||||
Primary target for MVP:
|
||||
| Путь | Назначение |
|
||||
|---|---|
|
||||
| `package.json` | Корневой workspace: `backend`, `admin-panel`, `widget`, `deploy/deploy-agent`; скрипты сборки и деплоя |
|
||||
| `backend/src/server.js` | Fastify-приложение: HTTP API, CORS по списку сайтов, rate limit, WebSocket `/ws`, старт Telegram-моста |
|
||||
| `backend/src/db.js` | Подключение к SQLite, миграция схемы (`sites`, `operators`, `site_operators`, `visitors`, `conversations`, `messages`, `settings`), запросы и работа с настройками |
|
||||
| `backend/src/telegram.js` | Telegraf-мост: рассылка сообщений операторам, разбор ответов (reply и inline-кнопка выбора диалога), команда `/status`, перезапуск бота на лету |
|
||||
| `backend/src/config.js` | Чтение `.env`, значения по умолчанию, production-путь к базе |
|
||||
| `backend/.env.example` | Шаблон переменных окружения бэкенда |
|
||||
| `admin-panel/src/main.jsx` | Панель: статистика, список сайтов и операторов, embed-код, настройки Telegram/SOCKS5, лента последних сообщений, диагностика `/health` |
|
||||
| `admin-panel/vite.config.js` | Сборка с `base: '/admin/'` |
|
||||
| `widget/src/widget.js` | Встраиваемый виджет: Shadow DOM, localStorage-идентификатор посетителя, POST сообщения и WebSocket-подписка на ответы |
|
||||
| `widget/vite.config.js` | Сборка с фиксированным именем артефакта `widget.js` |
|
||||
| `deploy/vps/install.sh` | Установщик VPS: пакеты, Node.js, PM2, `npm install`, сборка фронтенда, запуск бэкенда |
|
||||
| `deploy/vps/bootstrap.sh`, `deploy/raspberry/bootstrap.sh` | Первичная подготовка VPS и Raspberry Pi |
|
||||
| `deploy/deploy-agent/src/deploy-frontend.js` | Агент обновления фронтенда: `git pull`, `npm ci`, сборка, rsync в webroot FastPanel с проверкой безопасности пути |
|
||||
| `docs/` | Инструкции: `INSTALL.md`, `VPS_ONLY_INSTALL.md`, `FASTPANEL.md`, `FASTPANEL_MANUAL_FRONTEND.md`, `RASPBERRY_PI.md`, `UPDATE_BUNDLE.md` |
|
||||
| `.sw` | Журнал разработки: текущее состояние, продовые пути, диагностика, список нерешённых задач |
|
||||
| `README.upstream.md` | Исходное техническое задание проекта (сохранено при пересборке README) |
|
||||
|
||||
- Raspberry Pi 3 Model B at home
|
||||
- Raspberry Pi OS Lite 32-bit
|
||||
- Backend API on Raspberry Pi
|
||||
- Telegram bot on Raspberry Pi
|
||||
- SQLite database on Raspberry Pi
|
||||
- VPS with FastPanel for admin panel, widget.js, static assets, HTTPS, and public reverse proxy
|
||||
- WireGuard between VPS and Raspberry Pi
|
||||
- Domain/site management through FastPanel where possible
|
||||
## Как запустить
|
||||
|
||||
Cloudflare must not be required for this project.
|
||||
|
||||
Recommended OS for Raspberry Pi 3B MVP:
|
||||
|
||||
- Raspberry Pi OS Lite 32-bit for maximum RAM economy and stability on 1 GB RAM
|
||||
- Raspberry Pi OS Lite 64-bit can be tested later if specific ARM64 packages are needed
|
||||
|
||||
## Core components
|
||||
|
||||
```text
|
||||
website widget -> VPS FastPanel/Nginx/API proxy -> WireGuard -> Raspberry Pi backend -> SQLite -> Telegram bot -> operators
|
||||
|
||||
VPS also serves:
|
||||
- admin panel
|
||||
- widget.js
|
||||
- static assets
|
||||
```
|
||||
|
||||
## MVP modules
|
||||
|
||||
- Backend API
|
||||
- WebSocket gateway
|
||||
- Telegram bot bridge
|
||||
- Embeddable website widget
|
||||
- Web admin panel
|
||||
- SQLite storage
|
||||
- Operator/site access rules
|
||||
- SOCKS5 proxy settings for Telegram connectivity
|
||||
- Frontend deployment management from admin panel
|
||||
- FastPanel-safe frontend publishing on VPS
|
||||
|
||||
## Required admin settings
|
||||
|
||||
### Telegram bot
|
||||
|
||||
- Bot token
|
||||
- Webhook or polling mode
|
||||
- Allowed operators
|
||||
- Operator-to-site mapping
|
||||
|
||||
### SOCKS5 proxy
|
||||
|
||||
The system must support optional SOCKS5 configuration for Telegram requests:
|
||||
|
||||
```env
|
||||
TELEGRAM_PROXY_ENABLED=false
|
||||
TELEGRAM_PROXY_TYPE=socks5
|
||||
TELEGRAM_PROXY_HOST=127.0.0.1
|
||||
TELEGRAM_PROXY_PORT=9050
|
||||
TELEGRAM_PROXY_USERNAME=
|
||||
TELEGRAM_PROXY_PASSWORD=
|
||||
```
|
||||
|
||||
Admin panel should expose:
|
||||
|
||||
- Enable/disable SOCKS5
|
||||
- Proxy host
|
||||
- Proxy port
|
||||
- Username
|
||||
- Password
|
||||
- Test connection button
|
||||
|
||||
Sensitive fields must be stored encrypted or kept in environment variables for MVP.
|
||||
|
||||
### FastPanel-safe frontend hosting
|
||||
|
||||
The frontend server uses FastPanel. The project deployment must not break, overwrite, restart, or bypass FastPanel-managed services.
|
||||
|
||||
Hard rules:
|
||||
|
||||
- Do not edit global FastPanel configs directly
|
||||
- Do not overwrite `/etc/nginx/nginx.conf`
|
||||
- Do not overwrite FastPanel-generated virtual host configs
|
||||
- Do not run broad `systemctl restart nginx` from the deploy script
|
||||
- Do not install packages that replace FastPanel web stack components
|
||||
- Do not run frontend as root
|
||||
- Do not bind frontend services to ports `80` or `443`
|
||||
- Prefer static build publishing into a FastPanel-created site directory
|
||||
- Use `nginx -t` before any reload if reload is unavoidable
|
||||
- Prefer no reload at all for static frontend updates
|
||||
|
||||
Recommended FastPanel model:
|
||||
|
||||
```text
|
||||
FastPanel creates domains/sites:
|
||||
- admin.example.ru
|
||||
- widget.example.ru
|
||||
- api.example.ru
|
||||
|
||||
Deploy script only updates files inside the allowed web root:
|
||||
- admin panel build files
|
||||
- widget.js
|
||||
- widget assets
|
||||
```
|
||||
|
||||
Recommended FastPanel-safe paths:
|
||||
|
||||
```text
|
||||
/var/www/<fastpanel-user>/data/www/admin.example.ru
|
||||
/var/www/<fastpanel-user>/data/www/widget.example.ru
|
||||
/opt/raspi-chat/source
|
||||
/opt/raspi-chat/releases/<timestamp>
|
||||
/opt/raspi-chat/current -> /opt/raspi-chat/releases/<timestamp>
|
||||
```
|
||||
|
||||
Deployment should copy or rsync built static files into the FastPanel site directories:
|
||||
|
||||
```text
|
||||
admin-panel/dist/* -> /var/www/<fastpanel-user>/data/www/admin.example.ru/
|
||||
widget/dist/* -> /var/www/<fastpanel-user>/data/www/widget.example.ru/
|
||||
```
|
||||
|
||||
The API reverse proxy for `api.example.ru` should be configured through FastPanel custom Nginx directives if available, or through a separate include file that FastPanel will not overwrite.
|
||||
|
||||
FastPanel compatibility must be treated as a deployment requirement, not an afterthought.
|
||||
|
||||
### Frontend deployment updates
|
||||
|
||||
The admin panel must include a deployment section for updating the VPS-hosted frontend.
|
||||
|
||||
Required modes:
|
||||
|
||||
1. Manual update by button
|
||||
2. Automatic update by webhook from GitHub
|
||||
3. Optional scheduled update check
|
||||
|
||||
Admin panel should expose:
|
||||
|
||||
- Current frontend version
|
||||
- Current commit hash
|
||||
- Last deployment time
|
||||
- Last deployment status
|
||||
- Update branch, default: `main`
|
||||
- Button: `Check for updates`
|
||||
- Button: `Update frontend now`
|
||||
- Deployment logs
|
||||
- Rollback to previous frontend build
|
||||
- Lock to prevent parallel deployments
|
||||
- FastPanel compatibility status
|
||||
- Target FastPanel web root paths
|
||||
|
||||
Frontend deployment flow:
|
||||
|
||||
```text
|
||||
Admin clicks update button
|
||||
-> backend validates admin permissions
|
||||
-> backend calls deploy agent on VPS
|
||||
-> VPS pulls latest repository changes
|
||||
-> VPS builds admin-panel and widget
|
||||
-> VPS verifies FastPanel-safe target paths
|
||||
-> VPS publishes new static build atomically
|
||||
-> backend stores deployment result
|
||||
-> admin panel shows status and logs
|
||||
```
|
||||
|
||||
Recommended deploy command on VPS:
|
||||
Локально:
|
||||
|
||||
```bash
|
||||
git fetch origin main
|
||||
npm ci
|
||||
npm run build --workspace admin-panel
|
||||
npm run build --workspace widget
|
||||
npm install
|
||||
cp backend/.env.example backend/.env # заполнить значения
|
||||
npm run dev:backend # node --watch backend/src/server.js
|
||||
npm run dev:admin # Vite, админка
|
||||
npm --workspace widget run dev # Vite, виджет на порту 5174
|
||||
```
|
||||
|
||||
Publishing must be atomic and FastPanel-safe:
|
||||
Сборка фронтенда:
|
||||
|
||||
```text
|
||||
build new release directory
|
||||
verify build artifacts
|
||||
verify target directories are inside allowed FastPanel web roots
|
||||
copy files with rsync --delete only inside those roots
|
||||
never delete parent web root directories
|
||||
never touch FastPanel system configs
|
||||
```bash
|
||||
npm run build # build:admin + build:widget
|
||||
```
|
||||
|
||||
Admin deployment permissions:
|
||||
Отдельных миграций нет: схема SQLite создаётся функцией `migrate()` при старте бэкенда, база и каталог создаются автоматически по `DATABASE_PATH`.
|
||||
|
||||
- Only users with role `admin` can trigger frontend updates
|
||||
- Deployment endpoint must require JWT auth
|
||||
- Deployment webhook must require secret token validation
|
||||
- All deployment attempts must be logged
|
||||
Установка на VPS (скрипт ставит пакеты, Node.js, PM2, собирает фронтенд и поднимает бэкенд под PM2):
|
||||
|
||||
Environment variables:
|
||||
|
||||
```env
|
||||
FRONTEND_DEPLOY_ENABLED=true
|
||||
FRONTEND_DEPLOY_MODE=local-vps
|
||||
FRONTEND_DEPLOY_BRANCH=main
|
||||
FRONTEND_DEPLOY_SOURCE_PATH=/opt/raspi-chat/source
|
||||
FRONTEND_DEPLOY_RELEASES_PATH=/opt/raspi-chat/releases
|
||||
FRONTEND_DEPLOY_ADMIN_WEBROOT=/var/www/example_user/data/www/admin.example.ru
|
||||
FRONTEND_DEPLOY_WIDGET_WEBROOT=/var/www/example_user/data/www/widget.example.ru
|
||||
FRONTEND_DEPLOY_WEBHOOK_SECRET=
|
||||
FASTPANEL_SAFE_MODE=true
|
||||
```bash
|
||||
cp deploy/vps/.env.example deploy/vps/.env
|
||||
sudo bash deploy/vps/install.sh
|
||||
```
|
||||
|
||||
MVP implementation should run the deployment agent directly on the VPS. The deploy agent must have permissions only for the project source, release directory, and specific FastPanel web roots.
|
||||
Публикация фронтенда в webroot FastPanel:
|
||||
|
||||
## Website widget
|
||||
```bash
|
||||
npm run deploy:frontend # deploy/deploy-agent, требует свой .env
|
||||
```
|
||||
|
||||
Example embed code:
|
||||
Проверка:
|
||||
|
||||
```bash
|
||||
curl -s http://127.0.0.1:3000/health
|
||||
pm2 logs wschat-backend --lines 100
|
||||
```
|
||||
|
||||
Встраивание виджета на сайт:
|
||||
|
||||
```html
|
||||
<script src="https://widget.example.ru/widget.js" data-site-id="site_xxxxx"></script>
|
||||
<script src="https://widget.example.ru/widget.js"
|
||||
data-site-id="site_xxxxx"
|
||||
data-api-url="https://api.example.ru"></script>
|
||||
```
|
||||
|
||||
The widget must connect to the public API endpoint on VPS:
|
||||
## Конфигурация
|
||||
|
||||
```text
|
||||
https://api.example.ru
|
||||
wss://api.example.ru/ws
|
||||
```
|
||||
### `backend/.env`
|
||||
|
||||
## Message flow
|
||||
| Переменная | Назначение | Пример |
|
||||
|---|---|---|
|
||||
| `APP_ENV` | Режим работы; в `production` меняется путь к базе по умолчанию и отключается pino-pretty | `production` |
|
||||
| `APP_HOST` | Адрес прослушивания бэкенда | `127.0.0.1` |
|
||||
| `APP_PORT` | Порт бэкенда | `3000` |
|
||||
| `PUBLIC_API_URL` | Публичный URL API, отдаётся виджету через `/api/config/public` | `https://api.example.ru` |
|
||||
| `PUBLIC_WS_URL` | Публичный WebSocket URL | `wss://api.example.ru/ws` |
|
||||
| `TRUST_PROXY` | Доверять заголовкам reverse proxy | `true` |
|
||||
| `DATABASE_PATH` | Путь к файлу SQLite | `/opt/ws-chat/data/chat.sqlite` |
|
||||
| `ADMIN_ORIGIN` | Origin админки для CORS | `https://admin.example.ru` |
|
||||
| `WIDGET_ORIGIN` | Origin виджета для CORS и домен сайта по умолчанию | `https://widget.example.ru` |
|
||||
| `TELEGRAM_BOT_TOKEN` | Токен бота; при первом старте копируется в таблицу `settings`, дальше редактируется из админки | см. `.env` |
|
||||
| `TELEGRAM_PROXY_ENABLED` | Включить SOCKS5 для Telegram | `false` |
|
||||
| `TELEGRAM_PROXY_TYPE` | Тип прокси; в коде поддерживается только `socks5` | `socks5` |
|
||||
| `TELEGRAM_PROXY_HOST` / `TELEGRAM_PROXY_PORT` | Адрес и порт прокси | `127.0.0.1` / `9050` |
|
||||
| `TELEGRAM_PROXY_USERNAME` / `TELEGRAM_PROXY_PASSWORD` | Учётные данные прокси | см. `.env` |
|
||||
| `JWT_SECRET` | Объявлен в конфиге, но нигде не используется — авторизации нет | см. `.env` |
|
||||
| `FRONTEND_DEPLOY_ENABLED`, `FRONTEND_DEPLOY_MODE`, `FASTPANEL_SAFE_MODE` | Объявлены в `.env.example`, бэкендом не читаются | `false` |
|
||||
|
||||
```text
|
||||
Visitor sends message on website
|
||||
-> widget sends message to VPS api.example.ru
|
||||
-> VPS proxies request through WireGuard to Raspberry Pi backend
|
||||
-> backend validates site_id and origin domain
|
||||
-> backend stores message
|
||||
-> backend finds active operators assigned to this site
|
||||
-> Telegram bot sends message only to those operators
|
||||
-> operator replies in Telegram
|
||||
-> backend maps reply to conversation
|
||||
-> message is delivered back to website widget through WebSocket
|
||||
```
|
||||
Приоритет источников: значения Telegram/SOCKS5 после первого запуска хранятся в таблице `settings` SQLite и правятся через админку; `.env` задаёт только начальные значения.
|
||||
|
||||
## Future Android app
|
||||
### `deploy/vps/.env`
|
||||
|
||||
The backend must expose stable REST and WebSocket APIs so an Android app can later work as another operator interface.
|
||||
`PROJECT_ROOT`, `SOURCE_PATH`, `DATA_PATH`, `LOGS_PATH`, `BACKUPS_PATH`, `UPDATES_PATH`, `ADMIN_WEBROOT`, `WIDGET_WEBROOT`, `BACKEND_HOST`, `BACKEND_PORT`, `PUBLIC_API_URL`, `PUBLIC_WS_URL`, `FASTPANEL_SAFE_MODE`, `PM2_PROCESS_NAME`, `NODE_MAJOR`.
|
||||
|
||||
Planned Android-ready API concepts:
|
||||
### `deploy/deploy-agent/.env`
|
||||
|
||||
- JWT auth
|
||||
- refresh tokens
|
||||
- operator sessions
|
||||
- conversation list
|
||||
- message history
|
||||
- push-ready notification events
|
||||
- WebSocket live updates
|
||||
`FRONTEND_DEPLOY_BRANCH`, `FRONTEND_DEPLOY_SOURCE_PATH`, `FRONTEND_DEPLOY_ADMIN_WEBROOT`, `FRONTEND_DEPLOY_WIDGET_WEBROOT`, `FASTPANEL_SAFE_MODE`. При `FASTPANEL_SAFE_MODE != false` webroot обязан лежать внутри `/var/www/<user>/data/www/<domain>`, иначе деплой прерывается.
|
||||
|
||||
## Initial stack
|
||||
## Состояние
|
||||
|
||||
- Node.js
|
||||
- Fastify
|
||||
- WebSocket
|
||||
- SQLite
|
||||
- React + Vite admin panel
|
||||
- Vanilla JS widget
|
||||
- Telegram Bot API
|
||||
- WireGuard
|
||||
- FastPanel-managed web server on VPS
|
||||
- PM2 preferred for Raspberry Pi 3B MVP
|
||||
Рабочий MVP, разработка остановлена. 106 коммитов, все от 2026-05-08, последний коммит — 2026-05-08. По записям `.sw` система была развёрнута и работала: виджет и админка на `widget.stackworks.ru`, API на `api.stackworks.ru`, бэкенд под PM2, SQLite в `/opt/ws-chat/data/chat.sqlite`.
|
||||
|
||||
## Development phases
|
||||
Сквозной сценарий реализован полностью: виджет → API → Telegram-оператор → ответ → WebSocket → виджет. Управление сайтами, операторами и настройками Telegram/SOCKS5 работает из админки.
|
||||
|
||||
### Phase 1
|
||||
Raspberry Pi (изначальная цель проекта, см. `README.upstream.md` и `docs/RASPBERRY_PI.md`) из MVP исключён — в `.sw` указана причина: нестабильность Node.js/ОС на Pi.
|
||||
|
||||
- Website widget
|
||||
- Backend API
|
||||
- Telegram message forwarding
|
||||
- Reply from Telegram back to website
|
||||
- SQLite persistence
|
||||
## Что не доделано
|
||||
|
||||
### Phase 2
|
||||
Явных `TODO`/`FIXME` в коде нет; список ниже собран из кода и раздела «Current next steps» в `.sw`.
|
||||
|
||||
- Admin login
|
||||
- Site management
|
||||
- Operator management
|
||||
- Site/operator permissions
|
||||
- Widget embed code generator
|
||||
- SOCKS5 proxy settings
|
||||
|
||||
### Phase 3
|
||||
|
||||
- FastPanel-safe VPS frontend deployment scripts
|
||||
- Admin button for frontend update
|
||||
- Deployment logs
|
||||
- GitHub webhook auto-update
|
||||
- Frontend rollback support
|
||||
|
||||
### Phase 4
|
||||
|
||||
- Conversation history
|
||||
- Dialog statuses
|
||||
- Rate limiting
|
||||
- Origin/domain validation
|
||||
- Backup script
|
||||
- Deployment guide for Raspberry Pi, VPS, FastPanel, and WireGuard
|
||||
|
||||
### Phase 5
|
||||
|
||||
- Android app API preparation
|
||||
- Push notification model
|
||||
- Multi-device operator sessions
|
||||
- Нет авторизации в админ-панели. Все эндпоинты `/api/admin/*` открыты без проверки; `JWT_SECRET` объявлен, но не используется. Это главный незакрытый риск, зафиксированный и в самом `.sw`.
|
||||
- Нет страницы диалогов в админке: есть только лента последних сообщений, нельзя открыть переписку целиком.
|
||||
- Не реализованы статусы диалогов (`open`/`closed`) и назначение оператора «взять в работу» — поля `status` и `assigned_operator_id` в БД есть, UI и API для них нет.
|
||||
- Нет удаления/редактирования сайтов и операторов: реализованы только `GET`/`POST` сайтов и привязка/отвязка операторов.
|
||||
- Не реализована обещанная в ТЗ система деплоя из админки: нет ни кнопки обновления, ни GitHub-вебхука, ни откатов, ни логов деплоя. Есть только CLI-агент `deploy-frontend.js`.
|
||||
- `test-proxy` не проверяет соединение — функция `validateSocks5Settings` только валидирует поля формы.
|
||||
- Нет офлайн-режима (сбор имени/телефона/email посетителя), звуковых уведомлений и счётчиков непрочитанного.
|
||||
- Нет кастомизации виджета из админки (заголовок, цвет, позиция) — параметры зашиты в `widget.js`.
|
||||
- Нет тестов и CI: тестовых файлов, конфигов линтера и workflow в репозитории нет.
|
||||
- Планы, отмеченные в `.sw` как отложенные: перенос админки на отдельный поддомен, переход с SQLite на PostgreSQL, Docker Compose/установщик, JWT и API под будущее Android-приложение.
|
||||
|
||||
@@ -0,0 +1,317 @@
|
||||
# Raspi Telegram Live Chat
|
||||
|
||||
Self-hosted live chat system for Raspberry Pi with embeddable website widget, web admin panel, Telegram as the operator interface, and a separate VPS-hosted frontend.
|
||||
|
||||
## Goal
|
||||
|
||||
Build a lightweight Jivo-like chat platform where visitors write through a website widget and only Telegram operators configured in the admin panel receive and answer messages.
|
||||
|
||||
## Target deployment
|
||||
|
||||
Primary target for MVP:
|
||||
|
||||
- Raspberry Pi 3 Model B at home
|
||||
- Raspberry Pi OS Lite 32-bit
|
||||
- Backend API on Raspberry Pi
|
||||
- Telegram bot on Raspberry Pi
|
||||
- SQLite database on Raspberry Pi
|
||||
- VPS with FastPanel for admin panel, widget.js, static assets, HTTPS, and public reverse proxy
|
||||
- WireGuard between VPS and Raspberry Pi
|
||||
- Domain/site management through FastPanel where possible
|
||||
|
||||
Cloudflare must not be required for this project.
|
||||
|
||||
Recommended OS for Raspberry Pi 3B MVP:
|
||||
|
||||
- Raspberry Pi OS Lite 32-bit for maximum RAM economy and stability on 1 GB RAM
|
||||
- Raspberry Pi OS Lite 64-bit can be tested later if specific ARM64 packages are needed
|
||||
|
||||
## Core components
|
||||
|
||||
```text
|
||||
website widget -> VPS FastPanel/Nginx/API proxy -> WireGuard -> Raspberry Pi backend -> SQLite -> Telegram bot -> operators
|
||||
|
||||
VPS also serves:
|
||||
- admin panel
|
||||
- widget.js
|
||||
- static assets
|
||||
```
|
||||
|
||||
## MVP modules
|
||||
|
||||
- Backend API
|
||||
- WebSocket gateway
|
||||
- Telegram bot bridge
|
||||
- Embeddable website widget
|
||||
- Web admin panel
|
||||
- SQLite storage
|
||||
- Operator/site access rules
|
||||
- SOCKS5 proxy settings for Telegram connectivity
|
||||
- Frontend deployment management from admin panel
|
||||
- FastPanel-safe frontend publishing on VPS
|
||||
|
||||
## Required admin settings
|
||||
|
||||
### Telegram bot
|
||||
|
||||
- Bot token
|
||||
- Webhook or polling mode
|
||||
- Allowed operators
|
||||
- Operator-to-site mapping
|
||||
|
||||
### SOCKS5 proxy
|
||||
|
||||
The system must support optional SOCKS5 configuration for Telegram requests:
|
||||
|
||||
```env
|
||||
TELEGRAM_PROXY_ENABLED=false
|
||||
TELEGRAM_PROXY_TYPE=socks5
|
||||
TELEGRAM_PROXY_HOST=127.0.0.1
|
||||
TELEGRAM_PROXY_PORT=9050
|
||||
TELEGRAM_PROXY_USERNAME=
|
||||
TELEGRAM_PROXY_PASSWORD=
|
||||
```
|
||||
|
||||
Admin panel should expose:
|
||||
|
||||
- Enable/disable SOCKS5
|
||||
- Proxy host
|
||||
- Proxy port
|
||||
- Username
|
||||
- Password
|
||||
- Test connection button
|
||||
|
||||
Sensitive fields must be stored encrypted or kept in environment variables for MVP.
|
||||
|
||||
### FastPanel-safe frontend hosting
|
||||
|
||||
The frontend server uses FastPanel. The project deployment must not break, overwrite, restart, or bypass FastPanel-managed services.
|
||||
|
||||
Hard rules:
|
||||
|
||||
- Do not edit global FastPanel configs directly
|
||||
- Do not overwrite `/etc/nginx/nginx.conf`
|
||||
- Do not overwrite FastPanel-generated virtual host configs
|
||||
- Do not run broad `systemctl restart nginx` from the deploy script
|
||||
- Do not install packages that replace FastPanel web stack components
|
||||
- Do not run frontend as root
|
||||
- Do not bind frontend services to ports `80` or `443`
|
||||
- Prefer static build publishing into a FastPanel-created site directory
|
||||
- Use `nginx -t` before any reload if reload is unavoidable
|
||||
- Prefer no reload at all for static frontend updates
|
||||
|
||||
Recommended FastPanel model:
|
||||
|
||||
```text
|
||||
FastPanel creates domains/sites:
|
||||
- admin.example.ru
|
||||
- widget.example.ru
|
||||
- api.example.ru
|
||||
|
||||
Deploy script only updates files inside the allowed web root:
|
||||
- admin panel build files
|
||||
- widget.js
|
||||
- widget assets
|
||||
```
|
||||
|
||||
Recommended FastPanel-safe paths:
|
||||
|
||||
```text
|
||||
/var/www/<fastpanel-user>/data/www/admin.example.ru
|
||||
/var/www/<fastpanel-user>/data/www/widget.example.ru
|
||||
/opt/raspi-chat/source
|
||||
/opt/raspi-chat/releases/<timestamp>
|
||||
/opt/raspi-chat/current -> /opt/raspi-chat/releases/<timestamp>
|
||||
```
|
||||
|
||||
Deployment should copy or rsync built static files into the FastPanel site directories:
|
||||
|
||||
```text
|
||||
admin-panel/dist/* -> /var/www/<fastpanel-user>/data/www/admin.example.ru/
|
||||
widget/dist/* -> /var/www/<fastpanel-user>/data/www/widget.example.ru/
|
||||
```
|
||||
|
||||
The API reverse proxy for `api.example.ru` should be configured through FastPanel custom Nginx directives if available, or through a separate include file that FastPanel will not overwrite.
|
||||
|
||||
FastPanel compatibility must be treated as a deployment requirement, not an afterthought.
|
||||
|
||||
### Frontend deployment updates
|
||||
|
||||
The admin panel must include a deployment section for updating the VPS-hosted frontend.
|
||||
|
||||
Required modes:
|
||||
|
||||
1. Manual update by button
|
||||
2. Automatic update by webhook from GitHub
|
||||
3. Optional scheduled update check
|
||||
|
||||
Admin panel should expose:
|
||||
|
||||
- Current frontend version
|
||||
- Current commit hash
|
||||
- Last deployment time
|
||||
- Last deployment status
|
||||
- Update branch, default: `main`
|
||||
- Button: `Check for updates`
|
||||
- Button: `Update frontend now`
|
||||
- Deployment logs
|
||||
- Rollback to previous frontend build
|
||||
- Lock to prevent parallel deployments
|
||||
- FastPanel compatibility status
|
||||
- Target FastPanel web root paths
|
||||
|
||||
Frontend deployment flow:
|
||||
|
||||
```text
|
||||
Admin clicks update button
|
||||
-> backend validates admin permissions
|
||||
-> backend calls deploy agent on VPS
|
||||
-> VPS pulls latest repository changes
|
||||
-> VPS builds admin-panel and widget
|
||||
-> VPS verifies FastPanel-safe target paths
|
||||
-> VPS publishes new static build atomically
|
||||
-> backend stores deployment result
|
||||
-> admin panel shows status and logs
|
||||
```
|
||||
|
||||
Recommended deploy command on VPS:
|
||||
|
||||
```bash
|
||||
git fetch origin main
|
||||
npm ci
|
||||
npm run build --workspace admin-panel
|
||||
npm run build --workspace widget
|
||||
```
|
||||
|
||||
Publishing must be atomic and FastPanel-safe:
|
||||
|
||||
```text
|
||||
build new release directory
|
||||
verify build artifacts
|
||||
verify target directories are inside allowed FastPanel web roots
|
||||
copy files with rsync --delete only inside those roots
|
||||
never delete parent web root directories
|
||||
never touch FastPanel system configs
|
||||
```
|
||||
|
||||
Admin deployment permissions:
|
||||
|
||||
- Only users with role `admin` can trigger frontend updates
|
||||
- Deployment endpoint must require JWT auth
|
||||
- Deployment webhook must require secret token validation
|
||||
- All deployment attempts must be logged
|
||||
|
||||
Environment variables:
|
||||
|
||||
```env
|
||||
FRONTEND_DEPLOY_ENABLED=true
|
||||
FRONTEND_DEPLOY_MODE=local-vps
|
||||
FRONTEND_DEPLOY_BRANCH=main
|
||||
FRONTEND_DEPLOY_SOURCE_PATH=/opt/raspi-chat/source
|
||||
FRONTEND_DEPLOY_RELEASES_PATH=/opt/raspi-chat/releases
|
||||
FRONTEND_DEPLOY_ADMIN_WEBROOT=/var/www/example_user/data/www/admin.example.ru
|
||||
FRONTEND_DEPLOY_WIDGET_WEBROOT=/var/www/example_user/data/www/widget.example.ru
|
||||
FRONTEND_DEPLOY_WEBHOOK_SECRET=
|
||||
FASTPANEL_SAFE_MODE=true
|
||||
```
|
||||
|
||||
MVP implementation should run the deployment agent directly on the VPS. The deploy agent must have permissions only for the project source, release directory, and specific FastPanel web roots.
|
||||
|
||||
## Website widget
|
||||
|
||||
Example embed code:
|
||||
|
||||
```html
|
||||
<script src="https://widget.example.ru/widget.js" data-site-id="site_xxxxx"></script>
|
||||
```
|
||||
|
||||
The widget must connect to the public API endpoint on VPS:
|
||||
|
||||
```text
|
||||
https://api.example.ru
|
||||
wss://api.example.ru/ws
|
||||
```
|
||||
|
||||
## Message flow
|
||||
|
||||
```text
|
||||
Visitor sends message on website
|
||||
-> widget sends message to VPS api.example.ru
|
||||
-> VPS proxies request through WireGuard to Raspberry Pi backend
|
||||
-> backend validates site_id and origin domain
|
||||
-> backend stores message
|
||||
-> backend finds active operators assigned to this site
|
||||
-> Telegram bot sends message only to those operators
|
||||
-> operator replies in Telegram
|
||||
-> backend maps reply to conversation
|
||||
-> message is delivered back to website widget through WebSocket
|
||||
```
|
||||
|
||||
## Future Android app
|
||||
|
||||
The backend must expose stable REST and WebSocket APIs so an Android app can later work as another operator interface.
|
||||
|
||||
Planned Android-ready API concepts:
|
||||
|
||||
- JWT auth
|
||||
- refresh tokens
|
||||
- operator sessions
|
||||
- conversation list
|
||||
- message history
|
||||
- push-ready notification events
|
||||
- WebSocket live updates
|
||||
|
||||
## Initial stack
|
||||
|
||||
- Node.js
|
||||
- Fastify
|
||||
- WebSocket
|
||||
- SQLite
|
||||
- React + Vite admin panel
|
||||
- Vanilla JS widget
|
||||
- Telegram Bot API
|
||||
- WireGuard
|
||||
- FastPanel-managed web server on VPS
|
||||
- PM2 preferred for Raspberry Pi 3B MVP
|
||||
|
||||
## Development phases
|
||||
|
||||
### Phase 1
|
||||
|
||||
- Website widget
|
||||
- Backend API
|
||||
- Telegram message forwarding
|
||||
- Reply from Telegram back to website
|
||||
- SQLite persistence
|
||||
|
||||
### Phase 2
|
||||
|
||||
- Admin login
|
||||
- Site management
|
||||
- Operator management
|
||||
- Site/operator permissions
|
||||
- Widget embed code generator
|
||||
- SOCKS5 proxy settings
|
||||
|
||||
### Phase 3
|
||||
|
||||
- FastPanel-safe VPS frontend deployment scripts
|
||||
- Admin button for frontend update
|
||||
- Deployment logs
|
||||
- GitHub webhook auto-update
|
||||
- Frontend rollback support
|
||||
|
||||
### Phase 4
|
||||
|
||||
- Conversation history
|
||||
- Dialog statuses
|
||||
- Rate limiting
|
||||
- Origin/domain validation
|
||||
- Backup script
|
||||
- Deployment guide for Raspberry Pi, VPS, FastPanel, and WireGuard
|
||||
|
||||
### Phase 5
|
||||
|
||||
- Android app API preparation
|
||||
- Push notification model
|
||||
- Multi-device operator sessions
|
||||
Ссылка в новой задаче
Block a user
© 2026 StackWorks