From 333870d287e346a1e7f3b1be7dd929ccdded3b84 Mon Sep 17 00:00:00 2001 From: Nikolay Unuchek Date: Sat, 17 Oct 2026 17:02:53 +0300 Subject: [PATCH] =?UTF-8?q?docs:=20=D1=88=D0=B0=D0=B1=D0=BB=D0=BE=D0=BD?= =?UTF-8?q?=D1=8B=20=D1=81=D1=81=D1=8B=D0=BB=D0=BE=D0=BA=20=D0=B4=D0=BB?= =?UTF-8?q?=D1=8F=20=D0=94=D0=B8=D1=80=D0=B5=D0=BA=D1=82=D0=B0=20=D0=B8=20?= =?UTF-8?q?Instagram,=20=D0=B8=D0=BD=D1=81=D1=82=D1=80=D1=83=D0=BA=D1=86?= =?UTF-8?q?=D0=B8=D1=8F=20=D0=BF=D0=BE=20=D0=B4=D0=B5=D0=BF=D0=BB=D0=BE?= =?UTF-8?q?=D1=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/deploy.md | 40 ++++++++++++++++++++++++++++++++++++++++ docs/links.md | 40 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+) create mode 100644 docs/deploy.md create mode 100644 docs/links.md diff --git a/docs/deploy.md b/docs/deploy.md new file mode 100644 index 0000000..2372e6a --- /dev/null +++ b/docs/deploy.md @@ -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://: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, старт и бэкапы. diff --git a/docs/links.md b/docs/links.md new file mode 100644 index 0000000..cb58824 --- /dev/null +++ b/docs/links.md @@ -0,0 +1,40 @@ +# Ссылки для рекламы + +Лендинг сохраняет `utm_*`, `yclid`, `fbclid`, referrer, страницу входа и страницу отправки. Первое касание живёт 30 дней в localStorage, последнее — в sessionStorage; в заявку и в Telegram попадают оба (см. `GLOSSARY.md`). + +## Яндекс Директ + +В поле «Ссылка» объявления (макросы Директ подставит сам, `yclid` добавляется автоматически при включённой разметке ссылок для Метрики): + +``` +https://kvarta.unuchak.com/?utm_source=yandex&utm_medium=cpc&utm_campaign={campaign_id}&utm_content={ad_id}&utm_term={keyword} +``` + +Для РСЯ вместо `cpc` удобно различать площадку: `utm_medium={source_type}` (`search` / `context`). + +## Instagram + +Реклама через Ads Manager — поле «Параметры URL» (макросы Meta, `fbclid` Meta добавит сама): + +``` +utm_source=instagram&utm_medium=paid_social&utm_campaign={{campaign.name}}&utm_content={{ad.name}} +``` + +Ссылка в профиле: + +``` +https://kvarta.unuchak.com/?utm_source=instagram&utm_medium=social&utm_campaign=bio +``` + +Сторис со стикером-ссылкой: + +``` +https://kvarta.unuchak.com/?utm_source=instagram&utm_medium=social&utm_campaign=stories +``` + +## Как это выглядит у менеджера + +``` +Источник: yandex / cpc / 12345678 (первый визит: instagram, 9 дн. назад) +Страница: /?utm_source=yandex&… → /#catalog +```