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.
This commit is contained in:
Vladimir Bryzgalov
@@ -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-<timestamp>/` — оставь её на 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-<timestamp> 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` за момент проблемы
|
||||
- Что именно делал (шаг инструкции, на котором споткнулся)
|
||||
Reference in New Issue
Block a user