docs: шаблоны ссылок для Директа и Instagram, инструкция по деплою

2026-10-17 17:02:53 +03:00
parent 38356c2a7d
commit 333870d287
2 changed files with 80 additions and 0 deletions
@@ -0,0 +1,40 @@
+# Деплой и эксплуатация
+
+```
+Интернет → nginx на VPS (kvarta.unuchak.com, certbot)
+             /      → 127.0.0.1:13120  kvarta-landing (Next.js standalone)
+             /api/  → 127.0.0.1:13121  kvarta-api (Hono + SQLite в volume kvarta-data)
+kvarta-api → Tailscale → домашний сервер :8788 kvarta-tg-relay (nginx) → api.telegram.org
+```
+
+С VPS `api.telegram.org` недоступен, поэтому Bot API идёт через ретранслятор на домашнем сервере (`deploy/tg-relay`). Он пропускает только запросы нашего бота и только из tailnet; токена на домашнем сервере нет.
+
+## Первый запуск
+
+1. `CERTBOT_EMAIL=… deploy/setup-nginx.sh` — конфиг nginx, `nginx -t`, reload, сертификат. Повторный запуск безопасен.
+2. `deploy/deploy.sh` — сборка образов `linux/amd64` локально (JS собирается нативно, нативные модули — под целевую платформу), `docker save | ssh docker load`, `docker-compose up -d`, проверка `/api/health`. Требует чистого дерева git.
+3. На VPS заполнить `/root/kvarta_site/api.env` (chmod 600, скрипты его не трогают): `TELEGRAM_BOT_TOKEN`, `TELEGRAM_ADMIN_ID`, `TELEGRAM_API_BASE=http://<tailscale-ip-домашнего>:8788`.
+4. `TELEGRAM_BOT_ID=<цифры токена до двоеточия> deploy/tg-relay/deploy.sh` — ретранслятор на домашнем сервере (оба узла должны быть в Tailscale; на VPS — `tailscale up --accept-dns=false`, чтобы не задеть DNS соседних сайтов).
+5. Telegram: администратор пишет боту `/start`; в группе включить «Темы», сделать бота админом с правом «Управление темами»; написать в группе `/setup`. Бот создаст «Kvarta Cafe: Заявки» и «Kvarta Cafe: Система» и пришлёт в личку `TELEGRAM_CHAT_ID`, `TELEGRAM_LEADS_THREAD_ID`, `TELEGRAM_SYSTEM_THREAD_ID` — вписать в `api.env` и перезапустить api:
+
+```
+cd /root/kvarta_site && KVARTA_TAG=$(sed -n 's/^current=//p' .deployed) \
+  docker-compose -f docker-compose_vps.yml -p kvarta up -d --force-recreate api
+```
+
+Пока Telegram не настроен, заявки копятся в базе со статусом `pending` и уходят после настройки.
+
+## Обновление и откат
+
+- `deploy/deploy.sh` — новая версия; на сервере остаются текущий и предыдущий образы `kvarta-*`, чужие образы не трогаются.
+- `deploy/deploy.sh --rollback` — вернуть предыдущую версию.
+
+## Бэкапы
+
+- Каждый день в 03:00 по Минску и при старте, если за сегодня копии нет: `db.backup()` → gzip → `/data/backups/` в volume, 14 копий. Каждая копия уходит администратору в личку, итог — в «Систему».
+- Бот в личке администратора: `/backups` — список с кнопками восстановления, `/backup` — копия сейчас, присланный `.sqlite.gz` — восстановление из файла. Перед восстановлением бот показывает, какие заявки пропадут, и сохраняет текущую базу как `pre-restore-…`.
+
+## Где смотреть, если что-то не так
+
+- `docker-compose -f docker-compose_vps.yml -p kvarta logs api` — в том числе сбои связи с Telegram (раз в 10 минут).
+- Тема «Kvarta Cafe: Система» — 500, неотправленные после 10 попыток заявки, ошибки Telegram, старт и бэкапы.