Добавлено описание команд и улучшено логирование в документации. Включены команды диагностики и тестирования для проверки 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/

 ---

--- a/docs/en/CHEATSHEET_EN.md
+++ b/docs/en/CHEATSHEET_EN.md
@@ -48,16 +48,40 @@ sudo make renew

 ## 📋 Main Commands

-| Command | Description | Limits |
-|---------|-------------|--------|
-| `make test-cert` | Test certificate | ✅ None |
-| `make obtain` | New Let's Encrypt | ⚠️ 5/week |
-| `make renew` | Renew existing | ⚠️ 5/week |
-| `make run` | Auto mode | ⚠️ 5/week |
+### letsencrypt-regru Commands
+
+| Command | Description | Limits | Use Case |
+|---------|-------------|--------|----------|
+| `--check` | Check certificate expiration | - | Monitoring |
+| `--obtain` | Obtain new certificate | ⚠️ 5/week | Initial creation |
+| `--renew` | Renew existing certificate | ⚠️ 5/week | Renewal |
+| `--auto` | Auto-check and renewal | ⚠️ 5/week | Cron/systemd |
+| `--test-cert` | Test certificate | ✅ None | Development |
+| `--test-api` | Check API reg.ru access | - | Diagnostics |
+| `--test-dns` | Test DNS record creation | - | Pre-SSL check |
+| `--help` | Show help | - | Help |
+| `-v` | Verbose output | - | Debugging |
+
+### Makefile Commands
+
+| Command | Description | Equivalent |
+|---------|-------------|------------|
+| `make test-cert` | Test certificate | `letsencrypt-regru --test-cert` |
+| `make obtain` | New Let's Encrypt | `letsencrypt-regru --obtain` |
+| `make renew` | Renew existing | `letsencrypt-regru --renew` |
+| `make run` | Auto mode | `letsencrypt-regru --auto` |
 | `make status` | System status | - |
-| `make logs` | Show logs | - |
+| `make logs` | Show logs | `journalctl -u letsencrypt-regru` |
 | `make check-config` | Check configuration | - |

+### letsencrypt_regru.sh Commands
+
+| Command | Description |
+|---------|-------------|
+| `sudo bash letsencrypt_regru.sh install` | Install application |
+| `sudo bash letsencrypt_regru.sh update` | Update application |
+| `sudo bash letsencrypt_regru.sh uninstall` | Uninstall application |
+
 ---

 ## 📝 Configuration
--- a/docs/en/INSTALL_GUIDE_EN.md
+++ b/docs/en/INSTALL_GUIDE_EN.md
@@ -100,7 +100,9 @@ During installation, the script will ask for:

 ## Using letsencrypt-regru Command

-After installation, a convenient command is available:
+After installation, a convenient global command with multiple functions is available:
+
+### 🔧 Main Commands

 ```bash
 # Check current certificate expiration
@@ -117,11 +119,59 @@ letsencrypt-regru --auto

 # Create test self-signed certificate
 letsencrypt-regru --test-cert
-
-# Show help
-letsencrypt-regru --help
 ```

+### 🧪 Diagnostic and Testing Commands
+
+```bash
+# Check API access to reg.ru
+# - Shows current IP address
+# - Tests API connection
+# - Displays account balance
+letsencrypt-regru --test-api
+
+# Test DNS TXT record creation
+# - Full SSL certification process simulation
+# - Creates temporary _acme-challenge TXT record
+# - Waits for DNS propagation (60 seconds)
+# - Verifies via public DNS servers
+# - Automatically removes test record
+letsencrypt-regru --test-dns
+
+# Show help for all commands
+letsencrypt-regru --help
+
+# Enable verbose output
+letsencrypt-regru --obtain -v
+letsencrypt-regru --check -v
+```
+
+### ⚙️ Service Commands (internal use)
+
+```bash
+# Certbot authentication hook (used by certbot automatically)
+letsencrypt-regru --auth-hook
+
+# Certbot cleanup hook (used by certbot automatically)
+letsencrypt-regru --cleanup-hook
+```
+
+### 📋 Command Reference
+
+| Command | Description | Use Case |
+|---------|-------------|----------|
+| `--check` | Check certificate expiration | Regular monitoring |
+| `--obtain` | Obtain new certificate from Let's Encrypt | Initial creation |
+| `--renew` | Renew existing certificate | Renewal |
+| `--auto` | Automatic check and renewal | For cron/systemd |
+| `--test-cert` | Create test self-signed certificate | Development/testing |
+| `--test-api` | Check API access to reg.ru | Connection diagnostics |
+| `--test-dns` | Test DNS record creation | Pre-SSL verification |
+| `--auth-hook` | Certbot hook (DNS creation) | Internal |
+| `--cleanup-hook` | Certbot hook (DNS deletion) | Internal |
+| `--help` | Show help | Help |
+| `-v` | Verbose output | Debugging |
+
 ## Automatic Renewal

 The installer configures a systemd timer for automatic checks:
--- a/docs/ru/CHEATSHEET.md
+++ b/docs/ru/CHEATSHEET.md
@@ -48,16 +48,40 @@ sudo make renew

 ## 📋 Основные команды

-| Команда | Описание | Лимиты |
-|---------|----------|--------|
-| `make test-cert` | Тестовый сертификат | ✅ Нет |
-| `make obtain` | Let's Encrypt новый | ⚠️ 5/неделю |
-| `make renew` | Обновить существующий | ⚠️ 5/неделю |
-| `make run` | Авто-режим | ⚠️ 5/неделю |
+### Команды letsencrypt-regru
+
+| Команда | Описание | Лимиты | Использование |
+|---------|----------|--------|---------------|
+| `--check` | Проверить срок действия | - | Мониторинг |
+| `--obtain` | Получить новый сертификат | ⚠️ 5/неделю | Первое создание |
+| `--renew` | Обновить существующий | ⚠️ 5/неделю | Продление |
+| `--auto` | Авто-проверка и обновление | ⚠️ 5/неделю | Cron/systemd |
+| `--test-cert` | Тестовый сертификат | ✅ Нет | Разработка |
+| `--test-api` | Проверить API reg.ru | - | Диагностика |
+| `--test-dns` | Тест создания DNS записи | - | Проверка перед SSL |
+| `--help` | Справка | - | Помощь |
+| `-v` | Подробный вывод | - | Отладка |
+
+### Команды Makefile
+
+| Команда | Описание | Эквивалент |
+|---------|----------|------------|
+| `make test-cert` | Тестовый сертификат | `letsencrypt-regru --test-cert` |
+| `make obtain` | Let's Encrypt новый | `letsencrypt-regru --obtain` |
+| `make renew` | Обновить существующий | `letsencrypt-regru --renew` |
+| `make run` | Авто-режим | `letsencrypt-regru --auto` |
 | `make status` | Статус системы | - |
-| `make logs` | Показать логи | - |
+| `make logs` | Показать логи | `journalctl -u letsencrypt-regru` |
 | `make check-config` | Проверить конфигурацию | - |

+### Команды letsencrypt_regru.sh
+
+| Команда | Описание |
+|---------|----------|
+| `sudo bash letsencrypt_regru.sh install` | Установить приложение |
+| `sudo bash letsencrypt_regru.sh update` | Обновить приложение |
+| `sudo bash letsencrypt_regru.sh uninstall` | Удалить приложение |
+
 ---

 ## 📝 Конфигурация
--- a/docs/ru/INSTALL_GUIDE.md
+++ b/docs/ru/INSTALL_GUIDE.md
@@ -100,7 +100,9 @@ sudo ./letsencrypt_regru.sh

 ## Использование команды letsencrypt-regru

-После установки доступна удобная команда:
+После установки доступна удобная глобальная команда с множеством функций:
+
+### 🔧 Основные команды

 ```bash
 # Проверить срок действия текущего сертификата
@@ -117,11 +119,59 @@ letsencrypt-regru --auto

 # Создать тестовый самоподписанный сертификат
 letsencrypt-regru --test-cert
-
-# Показать справку
-letsencrypt-regru --help
 ```

+### 🧪 Команды диагностики и тестирования
+
+```bash
+# Проверить доступ к API reg.ru
+# - Показывает текущий IP
+# - Тестирует подключение к API
+# - Отображает баланс аккаунта
+letsencrypt-regru --test-api
+
+# Тестовое создание DNS записи TXT
+# - Полная симуляция процесса SSL сертификации
+# - Создает временную TXT запись _acme-challenge
+# - Ожидает распространения DNS (60 секунд)
+# - Проверяет через публичные DNS серверы
+# - Автоматически удаляет тестовую запись
+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
+```
+
+### 📋 Описание команд
+
+| Команда | Описание | Использование |
+|---------|----------|---------------|
+| `--check` | Проверяет срок действия сертификата | Регулярная проверка |
+| `--obtain` | Получает новый сертификат от Let's Encrypt | Первое создание |
+| `--renew` | Обновляет существующий сертификат | Продление срока |
+| `--auto` | Автоматическая проверка и обновление | Для cron/systemd |
+| `--test-cert` | Создает тестовый самоподписанный сертификат | Разработка/тестирование |
+| `--test-api` | Проверяет доступ к API reg.ru | Диагностика подключения |
+| `--test-dns` | Тестирует создание DNS записи | Проверка перед SSL |
+| `--auth-hook` | Hook для certbot (создание DNS) | Внутреннее |
+| `--cleanup-hook` | Hook для certbot (удаление DNS) | Внутреннее |
+| `--help` | Показывает справку | Помощь |
+| `-v` | Подробный вывод | Отладка |
+
 ## Автоматическое обновление

 Установщик настраивает systemd timer для автоматической проверки: