418 строки
11 KiB
XML
418 строки
11 KiB
XML
# WSChat development state snapshot
|
|
|
|
Project: WSChat
|
|
Repository: https://github.com/viktor138irk/chat
|
|
Default branch: main
|
|
|
|
## Mandatory rule
|
|
|
|
Always update this `.sw` file after meaningful code, deployment, architecture, or debugging changes.
|
|
|
|
Never store secrets in this file: no Telegram tokens, proxy passwords, API keys, SSH credentials, or similar values. Use `[REDACTED]`.
|
|
|
|
## Product
|
|
|
|
Self-hosted live chat similar to Jivo/Tidio. Website widget sends visitor messages to Telegram operators. Operators reply in Telegram, and replies return back into the website widget through WebSocket.
|
|
|
|
MVP is currently functional:
|
|
|
|
```text
|
|
website -> widget.js -> backend -> Telegram operator -> backend -> WebSocket -> website widget
|
|
```
|
|
|
|
## Deployment
|
|
|
|
```text
|
|
widget/test page: https://widget.stackworks.ru/
|
|
admin panel: https://widget.stackworks.ru/admin/
|
|
backend API: https://api.stackworks.ru/health
|
|
backend local: http://127.0.0.1:3000
|
|
PM2 process: wschat-backend
|
|
source: /opt/ws-chat/source
|
|
data: /opt/ws-chat/data
|
|
SQLite: /opt/ws-chat/data/chat.sqlite
|
|
webroot: /var/www/widget_stack_usr/data/www/widget.stackworks.ru
|
|
```
|
|
|
|
MVP architecture is VPS-only. Raspberry Pi was removed from MVP because of Node.js/OS/DPKG instability.
|
|
|
|
## Working domains/sites
|
|
|
|
Known working sites:
|
|
|
|
```text
|
|
widget.stackworks.ru -> site_default
|
|
stackworks.ru -> site_stackworks
|
|
```
|
|
|
|
Known Telegram operator:
|
|
|
|
```text
|
|
telegram_user_id: 833333156
|
|
```
|
|
|
|
This operator is linked to both:
|
|
|
|
```text
|
|
site_default
|
|
site_stackworks
|
|
```
|
|
|
|
## Database and settings
|
|
|
|
Correct DB path:
|
|
|
|
```text
|
|
/opt/ws-chat/data/chat.sqlite
|
|
```
|
|
|
|
Production fallback DB path was fixed to the same value even if `.env` is not loaded.
|
|
|
|
`/health` must show:
|
|
|
|
```text
|
|
dbPath=/opt/ws-chat/data/chat.sqlite
|
|
telegram.running=true
|
|
telegram.hasBot=true
|
|
wsClients=<number>
|
|
```
|
|
|
|
Settings come from SQLite table `settings`, not from frontend.
|
|
|
|
Important keys:
|
|
|
|
```text
|
|
telegram.bot_token
|
|
telegram.proxy.enabled
|
|
telegram.proxy.type
|
|
telegram.proxy.host
|
|
telegram.proxy.port
|
|
telegram.proxy.username
|
|
telegram.proxy.password
|
|
```
|
|
|
|
Diagnostics:
|
|
|
|
```bash
|
|
sqlite3 /opt/ws-chat/data/chat.sqlite "select id,name,domain,widget_key,is_active from sites;"
|
|
sqlite3 /opt/ws-chat/data/chat.sqlite "select id,name,telegram_user_id,is_active from operators;"
|
|
sqlite3 /opt/ws-chat/data/chat.sqlite "select * from site_operators;"
|
|
sqlite3 /opt/ws-chat/data/chat.sqlite "select key, value from settings where key like 'telegram.proxy.%';"
|
|
sqlite3 /opt/ws-chat/data/chat.sqlite "select key, length(value) as len from settings where key='telegram.bot_token';"
|
|
```
|
|
|
|
If a DB exists inside `/opt/ws-chat/source/backend/data/`, that was a wrong fallback DB from older code.
|
|
|
|
## Current endpoints
|
|
|
|
```text
|
|
GET /health
|
|
GET /api/config/public
|
|
GET /api/admin/stats
|
|
GET /api/admin/messages?limit=50
|
|
GET /api/admin/sites
|
|
POST /api/admin/sites
|
|
GET /api/admin/operators
|
|
POST /api/admin/site-operators
|
|
DELETE /api/admin/site-operators
|
|
GET /api/admin/telegram/settings
|
|
POST /api/admin/telegram/settings
|
|
POST /api/admin/telegram/test-proxy
|
|
POST /api/admin/telegram/restart
|
|
POST /api/widget/message
|
|
GET /ws
|
|
```
|
|
|
|
## WebSocket architecture
|
|
|
|
Widget opens:
|
|
|
|
```text
|
|
/ws?siteId=<siteId>&visitorId=<visitorId>
|
|
```
|
|
|
|
Backend stores WebSocket clients by:
|
|
|
|
```text
|
|
siteId:visitorId
|
|
```
|
|
|
|
Telegram replies are delivered from:
|
|
|
|
```text
|
|
telegram.js -> operatorMessageNotifier -> server.js broadcastToVisitor()
|
|
```
|
|
|
|
Payload format:
|
|
|
|
```json
|
|
{
|
|
"type": "operator_message",
|
|
"conversationId": "conv_xxx",
|
|
"message": {
|
|
"id": "msg_xxx",
|
|
"direction": "operator",
|
|
"body": "text"
|
|
}
|
|
}
|
|
```
|
|
|
|
Nginx for `api.stackworks.ru` must proxy `/ws` with upgrade headers. Includes file used:
|
|
|
|
```text
|
|
/etc/nginx/fastpanel2-sites/api_stackwor_usr/api.stackworks.ru.includes
|
|
```
|
|
|
|
Required block:
|
|
|
|
```nginx
|
|
location /ws {
|
|
proxy_pass http://127.0.0.1:3000/ws;
|
|
proxy_http_version 1.1;
|
|
proxy_set_header Upgrade $http_upgrade;
|
|
proxy_set_header Connection "upgrade";
|
|
proxy_set_header Host $host;
|
|
proxy_read_timeout 86400;
|
|
}
|
|
```
|
|
|
|
Check:
|
|
|
|
```bash
|
|
wscat -c "wss://api.stackworks.ru/ws?siteId=site_default&visitorId=test"
|
|
```
|
|
|
|
Expected:
|
|
|
|
```json
|
|
{"type":"connected","siteId":"site_default","visitorId":"test"}
|
|
```
|
|
|
|
## Telegram bridge
|
|
|
|
Runtime file:
|
|
|
|
```text
|
|
backend/src/telegram.js
|
|
```
|
|
|
|
Dependencies:
|
|
|
|
```text
|
|
telegraf
|
|
socks-proxy-agent
|
|
node-fetch
|
|
```
|
|
|
|
Implemented:
|
|
|
|
- bridge startup from SQLite settings;
|
|
- SOCKS5 proxy support;
|
|
- `socks5h://` proxy URL so DNS resolves through proxy;
|
|
- `/start` registers operator;
|
|
- `/status` replies with bridge state and active dialog;
|
|
- visitor messages go to active Telegram operators;
|
|
- Telegram reply to notification still works;
|
|
- inline button `Ответить в этот чат` selects active conversation;
|
|
- after selecting active conversation, normal Telegram messages are sent to that website visitor without reply;
|
|
- inline button `Сбросить активный диалог` clears selected dialog;
|
|
- Telegram replies are saved as operator messages;
|
|
- Telegram replies are delivered back to widget through WebSocket.
|
|
|
|
Important: only one polling instance may run per Telegram bot token.
|
|
|
|
Old observed Telegram error:
|
|
|
|
```text
|
|
409 Conflict: terminated by other getUpdates request; make sure that only one bot instance is running
|
|
```
|
|
|
|
Fix on VPS:
|
|
|
|
```bash
|
|
pkill -f "/opt/ws-chat/source/backend/src/server.js" || true
|
|
pkill -f "node src/server.js" || true
|
|
pm2 delete wschat-backend || true
|
|
cd /opt/ws-chat/source/backend
|
|
pm2 start src/server.js --name wschat-backend --update-env
|
|
pm2 save
|
|
sleep 5
|
|
curl -s http://127.0.0.1:3000/health | jq
|
|
```
|
|
|
|
## Widget
|
|
|
|
Runtime file:
|
|
|
|
```text
|
|
widget/src/widget.js
|
|
```
|
|
|
|
Production build now emits stable:
|
|
|
|
```text
|
|
https://widget.stackworks.ru/widget.js
|
|
```
|
|
|
|
Embed code example for `stackworks.ru`:
|
|
|
|
```html
|
|
<script
|
|
src="https://widget.stackworks.ru/widget.js?v=20"
|
|
data-site-id="site_stackworks"
|
|
data-api-url="https://api.stackworks.ru"
|
|
data-ws-url="wss://api.stackworks.ru"
|
|
></script>
|
|
```
|
|
|
|
Current widget implementation uses Shadow DOM for full style isolation. This was required because CSS on `stackworks.ru` broke the chat layout even with `!important` rules.
|
|
|
|
Current widget features:
|
|
|
|
- floating chat button;
|
|
- close button in header;
|
|
- mobile close works;
|
|
- header fixed height;
|
|
- form fixed at bottom;
|
|
- messages area fills remaining height;
|
|
- WebSocket auto-connect;
|
|
- automatic reconnect message;
|
|
- operator replies open chat automatically;
|
|
- Shadow DOM prevents host-site CSS from breaking input/button/form/layout.
|
|
|
|
## Admin panel
|
|
|
|
Admin URL:
|
|
|
|
```text
|
|
https://widget.stackworks.ru/admin/
|
|
```
|
|
|
|
Admin current features:
|
|
|
|
- dashboard stats;
|
|
- recent messages;
|
|
- Telegram/SOCKS5 settings;
|
|
- test proxy;
|
|
- restart Telegram bridge;
|
|
- list sites;
|
|
- add site;
|
|
- show widget key;
|
|
- show/copy embed code;
|
|
- list Telegram operators;
|
|
- bind/unbind operators to sites.
|
|
|
|
Admin UI was compacted, but visual polish is postponed.
|
|
|
|
Important deployment caveat: admin lives inside the same webroot as widget. Running this command deletes `/admin/` and causes 404:
|
|
|
|
```bash
|
|
rsync -av --delete /opt/ws-chat/source/widget/dist/ /var/www/widget_stack_usr/data/www/widget.stackworks.ru/
|
|
```
|
|
|
|
Do not use `--delete` when deploying widget into the shared webroot unless `/admin` is excluded.
|
|
|
|
Safe widget deploy:
|
|
|
|
```bash
|
|
cp -a /opt/ws-chat/source/widget/dist/. /var/www/widget_stack_usr/data/www/widget.stackworks.ru/
|
|
```
|
|
|
|
or:
|
|
|
|
```bash
|
|
rsync -av /opt/ws-chat/source/widget/dist/ /var/www/widget_stack_usr/data/www/widget.stackworks.ru/
|
|
```
|
|
|
|
Safe admin deploy:
|
|
|
|
```bash
|
|
mkdir -p /var/www/widget_stack_usr/data/www/widget.stackworks.ru/admin
|
|
rsync -av --delete /opt/ws-chat/source/admin-panel/dist/ /var/www/widget_stack_usr/data/www/widget.stackworks.ru/admin/
|
|
chown -R widget_stack_usr:widget_stack_usr /var/www/widget_stack_usr/data/www/widget.stackworks.ru
|
|
```
|
|
|
|
## Deployment commands
|
|
|
|
Backend update:
|
|
|
|
```bash
|
|
cd /opt/ws-chat/source
|
|
git pull --ff-only origin main
|
|
cd backend
|
|
npm install
|
|
pm2 restart wschat-backend --update-env
|
|
```
|
|
|
|
Frontend build:
|
|
|
|
```bash
|
|
cd /opt/ws-chat/source
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
Safe frontend publish:
|
|
|
|
```bash
|
|
cp -a /opt/ws-chat/source/widget/dist/. /var/www/widget_stack_usr/data/www/widget.stackworks.ru/
|
|
mkdir -p /var/www/widget_stack_usr/data/www/widget.stackworks.ru/admin
|
|
rsync -av --delete /opt/ws-chat/source/admin-panel/dist/ /var/www/widget_stack_usr/data/www/widget.stackworks.ru/admin/
|
|
chown -R widget_stack_usr:widget_stack_usr /var/www/widget_stack_usr/data/www/widget.stackworks.ru
|
|
```
|
|
|
|
Health/logs:
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:3000/health | jq
|
|
curl -s https://api.stackworks.ru/health | jq
|
|
pm2 logs wschat-backend --lines 100
|
|
```
|
|
|
|
Check public assets:
|
|
|
|
```bash
|
|
curl -I https://widget.stackworks.ru/widget.js
|
|
curl -I https://widget.stackworks.ru/admin/
|
|
```
|
|
|
|
## FastPanel safety rules
|
|
|
|
Never edit global FastPanel/nginx configs from project scripts. Never bind project services directly to ports 80/443. Never run `rsync --delete` against `/var/www` or parent directories. Copy static files only into exact domain webroots.
|
|
|
|
`widget.stackworks.ru` currently uses Apache backend under FastPanel, but DocumentRoot is correct:
|
|
|
|
```text
|
|
/var/www/widget_stack_usr/data/www/widget.stackworks.ru
|
|
```
|
|
|
|
## Important recent commits
|
|
|
|
```text
|
|
4b46aabc8210158f97c3c6e9274b8f703f7a8aa2 - Telegram proxy changed to socks5h
|
|
6f14353cd403f351c89e4274d189808951dcf940 - production DB fallback fixed
|
|
be004fd14ab16e3b1262980fe044356d2efbe806 - health endpoint includes dbPath
|
|
ec2eeeea66047dcd982a4c0258d1338314e25c29 - WebSocket delivery from Telegram replies implemented
|
|
49f502f84c8e2d2979481d71010908457fb0ce84 - widget connected to WebSocket backend
|
|
258d5285382e9038167881fd6eccead02f3d6457 - stable Vite widget.js build
|
|
5ba7bd846b19bc2ea76c7610e16d2b00aa7b838a - admin API for sites/operators
|
|
5fb492ef7b6aa94374929d2a90caf71a4881c59d - Telegram inline answer button and active dialog mode
|
|
ccda416945d3608c5945e7adc3ce5502abf9a707 - compact admin CSS pass
|
|
bfdc9f091c1990a04b0c62593dfb94c4ec600f72 - widget moved to Shadow DOM
|
|
```
|
|
|
|
## Current next steps
|
|
|
|
Highest priority:
|
|
|
|
1. Add admin auth/login. Current admin is public and must not remain public.
|
|
2. Add web admin conversations page with selected conversation and full history.
|
|
3. Add conversation status: open/closed.
|
|
4. Add operator assignment / `take in work` flow.
|
|
5. Add offline mode: visitor name/phone/email + Telegram ticket.
|
|
6. Add sound notifications and unread counters.
|
|
7. Improve widget customization from admin: title, subtitle, color, position.
|
|
8. Later: split admin to separate subdomain, for example `admin.widget.stackworks.ru`, to avoid shared-webroot deploy collisions.
|
|
9. Later: replace SQLite with PostgreSQL for production scale.
|
|
10. Later: Docker compose / installer.
|
© 2026 StackWorks