Добавлено описание команд и улучшено логирование в документации. Включены команды диагностики и тестирования для проверки API и DNS, а также обновлены основные команды в руководствах.

2025-10-30 09:18:05 +03:00
parent 87f9f2b67a
commit b3955fb1cc
5 changed files with 474 additions and 33 deletions
--- a/README.md
+++ b/README.md
@@ -97,6 +97,8 @@ sudo bash letsencrypt_regru.sh

 После установки доступна глобальная команда `letsencrypt-regru`:

+#### 🔧 Основные команды
+
 ```bash
 # Проверить срок действия сертификата
 letsencrypt-regru --check
@@ -114,6 +116,40 @@ letsencrypt-regru --test-cert
 letsencrypt-regru --auto
 ```

+#### 🧪 Команды диагностики и тестирования
+
+```bash
+# Проверить доступ к API reg.ru
+# - Тестирует подключение к API
+# - Показывает текущий IP адрес
+# - Отображает баланс аккаунта reg.ru
+letsencrypt-regru --test-api
+
+# Тестовое создание DNS записи TXT
+# - Полная симуляция процесса SSL сертификации
+# - Создает временную TXT запись _acme-challenge
+# - Проверяет распространение DNS (60 секунд)
+# - Автоматически удаляет тестовую запись
+letsencrypt-regru --test-dns
+
+# Показать справку по всем доступным командам
+letsencrypt-regru --help
+
+# Включить подробный вывод (verbose mode)
+letsencrypt-regru --obtain -v
+letsencrypt-regru --check -v
+```
+
+#### ⚙️ Служебные команды (внутреннее использование)
+
+```bash
+# Certbot authentication hook (используется certbot)
+letsencrypt-regru --auth-hook
+
+# Certbot cleanup hook (используется certbot)
+letsencrypt-regru --cleanup-hook
+```
+
 ### Автоматическое обновление

 Скрипт установки настраивает автоматическую проверку сертификатов каждые 12 часов:
@@ -135,8 +171,11 @@ tail -f /var/log/letsencrypt-regru/letsencrypt_regru.log
 # Обновить приложение до последней версии
 sudo bash letsencrypt_regru.sh update

-# Полностью удалить приложение
+# Полностью удалить приложение (из репозитория)
 sudo bash letsencrypt_regru.sh uninstall
+
+# Удалить приложение одной командой (без клонирования)
+sudo bash -c "$(curl -fsSL https://github.com/DFofanov/configure_nginx_manager/raw/refs/heads/master/letsencrypt_regru.sh)" -- uninstall
 ```

 ### Расположение файлов
@@ -1558,12 +1597,254 @@ server {

 ---

+## 📚 Полное описание всех команд
+
+### Команда `--check`
+
+**Назначение**: Проверяет срок действия текущего SSL сертификата.
+
+**Что делает:**
+- Проверяет наличие сертификата в `/etc/letsencrypt/live/[домен]/`
+- Читает дату истечения из `cert.pem`
+- Показывает сколько дней осталось до истечения
+- Рекомендует обновление если осталось < 30 дней
+
+**Пример использования:**
+```bash
+letsencrypt-regru --check
+# Выход: "Certificate expires in 45 days" или "Certificate needs renewal (15 days left)"
+```
+
+---
+
+### Команда `--obtain`
+
+**Назначение**: Получает новый SSL сертификат от Let's Encrypt.
+
+**Что делает:**
+1. Проверяет доступ к API reg.ru
+2. Запускает certbot с DNS-01 challenge
+3. Автоматически создает TXT запись `_acme-challenge` через API reg.ru
+4. Ожидает распространения DNS (60 секунд)
+5. Let's Encrypt проверяет DNS запись
+6. Получает сертификат и сохраняет в `/etc/letsencrypt/live/`
+7. Автоматически удаляет временную TXT запись
+8. (Опционально) Загружает сертификат в Nginx Proxy Manager
+
+**Пример использования:**
+```bash
+letsencrypt-regru --obtain
+letsencrypt-regru --obtain -v  # с подробным выводом
+```
+
+**Поддержка wildcard:**
+- Для `*.example.com` создается одна TXT запись для основного домена
+- Сертификат покрывает все поддомены
+
+---
+
+### Команда `--renew`
+
+**Назначение**: Обновляет существующий SSL сертификат.
+
+**Что делает:**
+1. Проверяет наличие существующего сертификата
+2. Использует `certbot renew` для обновления
+3. Автоматически создает новые TXT записи через API
+4. Получает обновленный сертификат
+5. (Опционально) Обновляет сертификат в Nginx Proxy Manager
+
+**Пример использования:**
+```bash
+letsencrypt-regru --renew
+```
+
+**Когда использовать:**
+- Сертификат скоро истекает (< 30 дней)
+- Автоматически запускается systemd timer
+
+---
+
+### Команда `--auto`
+
+**Назначение**: Автоматическая проверка и обновление при необходимости.
+
+**Что делает:**
+1. Запускает `--check` для проверки срока действия
+2. Если осталось < 30 дней - запускает `--renew`
+3. Если сертификата нет - запускает `--obtain`
+4. Логирует все действия
+
+**Пример использования:**
+```bash
+letsencrypt-regru --auto
+```
+
+**Идеально для:**
+- Запуска через cron или systemd timer
+- Полностью автоматического управления сертификатами
+
+---
+
+### Команда `--test-cert`
+
+**Назначение**: Создает тестовый самоподписанный сертификат.
+
+**Что делает:**
+1. Генерирует приватный ключ RSA 2048 бит
+2. Создает самоподписанный сертификат на 365 дней
+3. Сохраняет в `/etc/letsencrypt/live/[домен]/`
+4. (Опционально) Загружает в Nginx Proxy Manager
+
+**Пример использования:**
+```bash
+letsencrypt-regru --test-cert
+```
+
+**Преимущества:**
+- ✅ Не требует интернет соединения
+- ✅ Мгновенное создание
+- ✅ Нет лимитов Let's Encrypt (5 сертификатов/неделя)
+- ✅ Идеально для разработки и тестирования
+
+**⚠️ Внимание:**
+- Браузеры покажут предупреждение "сертификат не доверенный"
+- Не использовать в production!
+
+---
+
+### Команда `--test-api`
+
+**Назначение**: Проверяет доступ к API reg.ru.
+
+**Что делает:**
+1. Определяет текущий публичный IP адрес (через ipinfo.io)
+2. Выполняет тестовый запрос к API reg.ru
+3. Показывает баланс аккаунта
+4. Проверяет авторизацию
+
+**Пример использования:**
+```bash
+letsencrypt-regru --test-api
+
+# Вывод:
+# ✓ Ваш текущий IP: 178.218.115.80
+# ✓ API reg.ru доступен
+# ✓ Баланс аккаунта: 1234.56 руб.
+```
+
+**Используйте когда:**
+- Первая настройка (проверка учетных данных)
+- Ошибки "Access to API from this IP denied"
+- Нужно узнать текущий IP для whitelist
+
+---
+
+### Команда `--test-dns`
+
+**Назначение**: Полная симуляция процесса SSL сертификации с тестовой DNS записью.
+
+**Что делает:**
+1. **Шаг 1**: Проверяет доступ к API reg.ru (`--test-api`)
+2. **Шаг 2**: Создает временную TXT запись `_acme-challenge.[домен]` со случайным значением
+3. **Шаг 3**: Ожидает распространения DNS (60 секунд с прогресс-баром)
+4. **Шаг 4**: Проверяет DNS запись через публичные DNS серверы (8.8.8.8, 1.1.1.1)
+5. **Шаг 5**: Автоматически удаляет тестовую запись
+
+**Пример использования:**
+```bash
+letsencrypt-regru --test-dns
+
+# Вывод:
+# ✓ API reg.ru доступен
+# ✓ TXT запись создана: _acme-challenge.example.com
+# ⏳ Ожидание распространения DNS: [===>    ] 30/60 секунд
+# ✓ DNS запись обнаружена через Google DNS
+# ✓ DNS запись обнаружена через Cloudflare DNS
+# ✓ Тестовая запись удалена
+```
+
+**Используйте для:**
+- Проверки что API reg.ru работает корректно
+- Проверки что DNS записи распространяются
+- Тестирования перед реальным получением сертификата
+- Диагностики проблем с DNS
+
+**Преимущества:**
+- Не влияет на лимиты Let's Encrypt
+- Безопасное тестирование (создает временную запись)
+- Показывает весь процесс пошагово
+
+---
+
+### Команда `--auth-hook` (служебная)
+
+**Назначение**: Используется certbot для создания DNS записи во время валидации.
+
+**Что делает:**
+1. Читает переменные окружения certbot (`CERTBOT_DOMAIN`, `CERTBOT_VALIDATION`)
+2. Создает TXT запись `_acme-challenge.[домен]` через API reg.ru
+3. Ожидает распространения DNS (60 секунд)
+4. Возвращает управление certbot
+
+**Используется автоматически:** Certbot вызывает этот hook при запуске `--obtain` или `--renew`
+
+---
+
+### Команда `--cleanup-hook` (служебная)
+
+**Назначение**: Используется certbot для удаления DNS записи после валидации.
+
+**Что делает:**
+1. Читает переменные окружения certbot
+2. Удаляет TXT запись `_acme-challenge.[домен]` через API reg.ru
+3. Очищает временные данные
+
+**Используется автоматически:** Certbot вызывает этот hook после завершения валидации
+
+---
+
+### Команда `--help`
+
+**Назначение**: Показывает справку по всем доступным командам.
+
+**Пример использования:**
+```bash
+letsencrypt-regru --help
+```
+
+---
+
+### Флаг `-v` (verbose)
+
+**Назначение**: Включает подробный вывод для диагностики.
+
+**Что показывает:**
+- Все HTTP запросы к API reg.ru
+- Ответы API (JSON)
+- Шаги выполнения certbot
+- Детали проверки DNS
+- Подробные ошибки
+
+**Пример использования:**
+```bash
+letsencrypt-regru --obtain -v
+letsencrypt-regru --test-dns -v
+letsencrypt-regru --check -v
+```
+
+---
+
 ## Дополнительная документация

- 📘 **[TESTING_GUIDE.md](TESTING_GUIDE.md)** - Полное руководство по созданию и использованию тестовых сертификатов
- <EFBFBD> **[GITEA_SYNC.md](GITEA_SYNC.md)** - Настройка автоматической синхронизации Gitea → GitHub
- 📘 **[CHEATSHEET.md](CHEATSHEET.md)** - Быстрая шпаргалка по командам
- <20>🚀 **[Makefile](Makefile)** - Автоматизация установки и управления
+- 📘 **[TESTING_GUIDE.md](docs/ru/TESTING_GUIDE.md)** - Полное руководство по созданию и использованию тестовых сертификатов
+- 🔄 **[GITEA_SYNC.md](docs/ru/GITEA_SYNC.md)** - Настройка автоматической синхронизации Gitea → GitHub
+- 📘 **[CHEATSHEET.md](docs/ru/CHEATSHEET.md)** - Быстрая шпаргалка по командам
+- <20> **[API_TROUBLESHOOTING.md](docs/ru/API_TROUBLESHOOTING.md)** - Устранение проблем с API reg.ru
+- <20>🚀 **[BUILD_GUIDE.md](docs/ru/BUILD_GUIDE.md)** - Сборка исполняемых файлов с PyInstaller
+- 📦 **[INSTALL_GUIDE.md](docs/ru/INSTALL_GUIDE.md)** - Подробное руководство по установке
+- 🛠️ **[MAKEFILE_COMMANDS.md](docs/ru/MAKEFILE_COMMANDS.md)** - Все команды Makefile
+- 🏗️ **[PROJECT_STRUCTURE.md](docs/ru/PROJECT_STRUCTURE.md)** - Структура проекта
 - 📝 **[config.json.example](config.json.example)** - Пример конфигурации

 ---
@@ -1572,12 +1853,24 @@ server {

 При возникновении проблем:

-1. Проверьте логи: `/var/log/letsencrypt_regru.log`
-2. Проверьте логи certbot: `/var/log/letsencrypt/letsencrypt.log`
-3. Используйте подробный режим: `-v` для Python скрипта
-4. Проверьте документацию reg.ru API: https://www.reg.ru/support/api
-5. Проверьте документацию Let's Encrypt: https://letsencrypt.org/docs/
-6. **Для тестирования**: См. [TESTING_GUIDE.md](TESTING_GUIDE.md)
+1. **Проверьте логи**: 
+   ```bash
+   journalctl -u letsencrypt-regru -f
+   tail -f /var/log/letsencrypt-regru/letsencrypt_regru.log
+   ```
+
+2. **Используйте команды диагностики**:
+   ```bash
+   letsencrypt-regru --test-api    # Проверка API
+   letsencrypt-regru --test-dns    # Проверка DNS
+   letsencrypt-regru --check -v    # Проверка сертификата
+   ```
+
+3. **Проверьте документацию**:
+   - [API_TROUBLESHOOTING.md](docs/ru/API_TROUBLESHOOTING.md) - Решение проблем с API
+   - [TESTING_GUIDE.md](docs/ru/TESTING_GUIDE.md) - Руководство по тестированию
+   - Документация reg.ru API: https://www.reg.ru/support/api
+   - Документация Let's Encrypt: https://letsencrypt.org/docs/

 ---