docs: подробный README (разбор проекта при переносе в Gitea)
Старый README сохранён как README.upstream.md.
Этот коммит содержится в:
@@ -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