From ad14d0e6e3906362c3ff7072a3a6e69524dde5d9 Mon Sep 17 00:00:00 2001 From: Vladimir Bryzgalov Date: Wed, 22 Apr 2026 00:12:18 +0500 Subject: [PATCH] docs: add deploy-to-sites guide for juniors Installing/updating the plugin on client sites. Covers the two scenarios (first-time manual install vs. auto-update after 1.2.0), SSH/admin install paths, smoke tests, and common troubleshooting. --- docs/deploy-to-sites.md | 162 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 docs/deploy-to-sites.md diff --git a/docs/deploy-to-sites.md b/docs/deploy-to-sites.md new file mode 100644 index 0000000..cc755bd --- /dev/null +++ b/docs/deploy-to-sites.md @@ -0,0 +1,162 @@ +# Развёртывание CF7 Spam → Telegram на сайт + +Инструкция для того, кто устанавливает/обновляет плагин на WP-сайтах клиентов. +Разработчик (я) выпускает новые версии через `release.sh` — тебе этот процесс трогать не нужно. + +## Как вообще обновляется плагин + +Есть два разных сценария: + +### Сценарий A: сайт уже работает на версии 1.2.0 или новее + +**Ничего делать не надо.** WordPress сам раз в 12 часов проверяет Gitea, и если появилась новая версия — показывает «Доступно обновление» в списке плагинов. Клиент (или ты) нажимает «Обновить» — и всё. + +### Сценарий B: плагин ставится впервые, или на сайте версия старше 1.2.0 + +В этом случае **первый раз** нужно установить вручную (один раз). После этого сайт перейдёт в сценарий A и дальше обновляется сам. + +--- + +## Как понять, в каком сценарии сайт + +1. Зайди в админку сайта → «Плагины». +2. Найди строку «CF7 Spam → Telegram». +3. Посмотри версию справа от названия. + - **≥ 1.2.0** → сценарий A. Дальше не читай, просто жди когда WP покажет обновление, или нажми «Проверить обновления» сверху списка. + - **< 1.2.0** или плагина нет → сценарий B, читай ниже. + +--- + +## Сценарий B: первая ручная установка / переход на 1.2.0+ + +### Шаг 1. Скачай свежий релиз + +1. Открой https://git.netranking.ru/bryzgalov/cf7-spam-to-telegram/releases +2. В списке релизов возьми самый верхний (последняя версия). +3. В разделе **Downloads** этого релиза скачай файл `cf7-spam-to-telegram-X.Y.Z.zip` (где X.Y.Z — номер версии). + +Никаких логинов на Gitea не нужно — репозиторий публичный. + +### Шаг 2. Установи плагин на сайт + +Есть два способа — выбирай тот, к которому есть доступ. + +#### Способ 1 (проще) — через админку WordPress + +1. Логин в админку сайта (данные — в корпоративном менеджере паролей / у разработчика). +2. Плагины → **Добавить новый** → кнопка **Загрузить плагин** сверху. +3. Выбери скачанный `cf7-spam-to-telegram-X.Y.Z.zip` → **Установить**. +4. Если WordPress ругается «Плагин уже установлен» и предлагает заменить — соглашайся, нажимай **Заменить текущей версией**. +5. Активируй плагин (кнопка **Активировать**, если сам не активировался). + +#### Способ 2 — через SSH / FTP (если в админку не пускает или хочется контроля) + +1. Подключись по SSH к серверу. +2. Найди папку плагина: обычно `<корень-сайта>/wp-content/plugins/cf7-spam-to-telegram/`. +3. Переименуй старую папку в бэкап (на случай отката): + + ```bash + cd <путь-к-сайту>/wp-content/plugins + mv cf7-spam-to-telegram cf7-spam-to-telegram.bak-$(date +%s) + ``` + +4. Загрузи скачанный zip на сервер (через `scp`, `rsync` или панель хостинга в домашнюю директорию). +5. Распакуй zip в `wp-content/plugins/`: + + ```bash + cd <путь-к-сайту>/wp-content/plugins + unzip ~/cf7-spam-to-telegram-X.Y.Z.zip + ``` + + Должна появиться папка `cf7-spam-to-telegram/` рядом с бэкапом. +6. Проверь, что плагин подхватился: в админке WP → Плагины → должен висеть с новой версией и статусом «Активен» (если был активен до замены — останется активным). + +### Шаг 3. Проверь, что ничего не сломалось + +1. Админка → Настройки → **CF7 Spam → TG** (или похожий пункт меню). +2. Убедись, что заполнены **Bot Token** и **Chat ID**. После обновления они должны сохраниться — если пусто, это плохой знак, пиши разработчику. +3. Нажми **Отправить тестовое сообщение** — в Telegram-группе должно появиться тестовое сообщение. +4. Через 10–20 минут заполни тестовый спам на одной из форм Contact Form 7 сайта (любой бессмысленный текст в поле сообщения, невалидный email) — убедись, что сообщение пришло в TG. + +### Шаг 4. (Только для Сценария B) Убедись, что автообновление теперь включено + +После того как установлена версия 1.2.0 или выше, WP должен начать сам следить за обновлениями. Проверим это сразу, не ждать 12 часов: + +1. Плагины → наверху страницы ссылка **Проверить обновления** (или аналогично) → нажать. +2. WordPress опросит Gitea. Если установленная версия совпадает с последней на Gitea — всё хорошо, обновлений нет (норма). +3. Если вдруг появилась плашка «Доступно обновление» — значит на Gitea уже есть более свежая версия (редкий случай: релиз вышел пока ты устанавливал). Нажми **Обновить**, всё должно пройти автоматически. + +### Шаг 5. Зачисти бэкап (через 1-2 дня) + +Если ты использовал Способ 2 (SSH) и создал папку `cf7-spam-to-telegram.bak-/` — оставь её на 1-2 дня на всякий случай. Если всё работает — удали: + +```bash +rm -rf <путь-к-сайту>/wp-content/plugins/cf7-spam-to-telegram.bak-* +``` + +--- + +## Как работают автообновления (для понимания) + +После установки 1.2.0+ в плагине есть библиотека [Plugin Update Checker v5.6](https://github.com/YahnisElsts/plugin-update-checker), которая: + +1. Раз в 12 часов (или при нажатии «Проверить обновления») ходит по URL: + `https://git.netranking.ru/bryzgalov/cf7-spam-to-telegram/raw/branch/main/wp-plugin-info.json` +2. Сверяет версию в JSON с версией установленного плагина. +3. Если в JSON версия новее — показывает WP-админке «Доступно обновление». +4. Когда клиент нажимает «Обновить», WP скачивает zip по URL из поля `download_url` в JSON (это zip с Gitea релиза) и распаковывает поверх. + +Поэтому сайт должен иметь исходящий HTTPS-доступ на `git.netranking.ru`. Большинство хостингов это не блокируют, но **Beget** (и некоторые российские shared-хостинги) иногда ограничивают исходящие соединения — если обновления не приходят, это первое, что надо проверить. + +--- + +## Типовые проблемы + +### «Сайт не видит обновление, хотя на Gitea новая версия есть» + +1. Плагины → **Проверить обновления** — нажми принудительно. +2. Если всё равно не видит, зайди на сайт по SSH и открой: + `<путь-к-сайту>/wp-content/debug.log` (если он включён) или error.log хостинга. + Ищи строки со словами `plugin-update-checker`, `PucFactory`, `cf7stg`, `wp-plugin-info`. Пришли их мне. +3. Проверь, что сайт достучится до Gitea. На сервере: + ```bash + curl -I https://git.netranking.ru/bryzgalov/cf7-spam-to-telegram/raw/branch/main/wp-plugin-info.json + ``` + Ожидается `HTTP/2 200`. Если `404` или `timeout` — хостинг блокирует исходящий HTTPS или не пускает на `git.netranking.ru`. Пиши мне. + +### «При обновлении ошибка, плагин не активируется» + +1. Если плагин реально сломался, откати через SSH: + + ```bash + cd <путь-к-сайту>/wp-content/plugins + rm -rf cf7-spam-to-telegram + mv cf7-spam-to-telegram.bak- cf7-spam-to-telegram + ``` + + (Имя бэкап-папки увидишь через `ls`). +2. Если бэкапа нет (после автообновления — WP обычно не оставляет бэкап) — напиши мне, пришлю zip предыдущей версии вручную. +3. Проверь PHP-версию хостинга: плагин требует **PHP 7.4+**. Если PHP 7.3 или ниже — обновляй PHP на панели хостинга. +4. Плагин требует установленные **Contact Form 7** и **Flamingo**. Если их отключили — активация нашего плагина упадёт. + +### «После обновления пропали настройки (Bot Token / Chat ID)» + +Это не должно случиться — настройки хранятся в WP-опциях, а не в файлах плагина. Если всё-таки произошло, напиши мне сразу: возможно, активация сработала со сбоем. Временное решение — заново вбить токен и Chat ID из менеджера паролей и сохранить. + +### «Я установил плагин руками, но в админке плашки про автообновление нет» + +Это нормально: WP не пишет «теперь у меня есть автообновление». Плашка появится только когда реально **появится** новая версия на Gitea. Сейчас просто дождись (или попроси разработчика сделать тестовый релиз — он сможет выпустить, скажем, 1.2.1 с одним фиксом, чтобы ты проверил, что update приходит). + +--- + +## Куда писать, если что-то не так + +- Разработчик: **Владимир Брызгалов**, email `vladimir.bryzgalov@gmail.com` / Telegram (уточни у руководителя). +- Исходники плагина: https://git.netranking.ru/bryzgalov/cf7-spam-to-telegram +- Все релизы: https://git.netranking.ru/bryzgalov/cf7-spam-to-telegram/releases + +При обращении приложи: +- Адрес сайта +- Версию WP, версию PHP (Админка → Инструменты → Здоровье сайта → Информация) +- Скрин ошибки или содержимое `error.log` за момент проблемы +- Что именно делал (шаг инструкции, на котором споткнулся)