fofanov.dmitry/configure_nginx_manager
1
0
Fork 0
Code Actions Releases Activity
Files
b3955fb1cc7ea05d21bf6f4a20c30eab899a29e7
configure_nginx_manager/docs/ru/BUILD_GUIDE.md

13 KiB
Raw Blame History

🔨 Руководство по сборке исполняемых файлов

Данное руководство описывает процесс компиляции Python-скрипта letsencrypt_regru_api.py в исполняемые файлы для Linux и Windows с использованием PyInstaller.

📋 Содержание

✅ Преимущества исполняемых файлов

Плюсы:

  • ✅ Один файл - легко распространять и развертывать
  • ✅ Автономность - не требует установленного Python на целевой системе
  • ✅ Все зависимости включены - requests, cryptography и certbot модули упакованы
  • ✅ Простота запуска - просто скачать и запустить

Минусы:

  • ❌ Большой размер - ~40-60 MB (включая Python runtime и библиотеки)
  • ❌ Certbot зависимость - системный certbot все равно требуется
  • ❌ Медленный первый запуск - распаковка занимает несколько секунд
  • ❌ Требуется пересборка - при изменении кода нужно пересобирать

🚀 Быстрый старт

Сборка для текущей ОС:

make build

Сборка для всех платформ:

make build-all

Полный релиз (сборка + пакеты):

make release

📖 Подробные инструкции

1. Установка зависимостей

Вариант А: Автоматическая установка

make install-pyinstaller

Вариант Б: Ручная установка

pip install pyinstaller
pip install -r requirements.txt

2. Сборка для Linux

На Linux системе:

make build-linux

Результат:

  • Файл: dist/letsencrypt-regru
  • Размер: ~45-55 MB
  • Формат: ELF 64-bit executable

Тестирование:

./dist/letsencrypt-regru --help
sudo ./dist/letsencrypt-regru --check -c /etc/letsencrypt-regru/config.json

3. Сборка для Windows

На Windows системе (PowerShell/CMD):

make build-windows

Результат:

  • Файл: dist/letsencrypt-regru.exe
  • Размер: ~40-50 MB
  • Формат: PE32+ executable (Windows)

Тестирование:

.\dist\letsencrypt-regru.exe --help

4. Создание пакетов для распространения

Linux пакет (tar.gz):

make package-linux

Содержимое пакета:

  • letsencrypt-regru - исполняемый файл
  • README.md - документация
  • systemd/ - systemd unit файлы
  • config.json.example - пример конфигурации

Результат: dist/letsencrypt-regru-linux-x86_64.tar.gz

Windows пакет (zip):

make package-windows

Результат: dist/letsencrypt-regru-windows-x86_64.zip

5. Полный цикл релиза

Создание релиза со всеми артефактами:

make release

Что происходит:

  1. Очистка старых артефактов (clean-build)
  2. Установка/обновление PyInstaller
  3. Сборка для Linux (build-linux)
  4. Сборка для Windows (build-windows)
  5. Создание пакета для Linux (package-linux)
  6. Создание пакета для Windows (package-windows)
  7. Генерация SHA256 контрольных сумм

Результат в dist/:

letsencrypt-regru              # Linux executable
letsencrypt-regru.exe          # Windows executable
letsencrypt-regru-linux-x86_64.tar.gz
letsencrypt-regru-windows-x86_64.zip

🔄 Кросс-компиляция

⚠️ Важные замечания

Не рекомендуется:

  • Собирать Linux версию на Windows
  • Собирать Windows версию на Linux
  • Собирать macOS версию на других ОС

Причины:

  • Несовместимость системных библиотек
  • Разные форматы исполняемых файлов
  • Проблемы с путями и разделителями

Рекомендации

Для Linux сборки:

  1. Используйте Ubuntu 20.04+ или Debian 10+
  2. Установите build-essential
  3. Используйте виртуальное окружение Python
sudo apt-get update
sudo apt-get install -y python3 python3-pip build-essential
make build-linux

Для Windows сборки:

  1. Используйте Windows 10/11
  2. Установите Python 3.8+
  3. Используйте PowerShell или CMD
python -m pip install --upgrade pip
make build-windows

Для обеих платформ:

Используйте CI/CD (GitHub Actions, GitLab CI):

# .github/workflows/build.yml
name: Build Releases

on:
  push:
    tags:
      - 'v*'

jobs:
  build-linux:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build Linux
        run: make build-linux

  build-windows:
    runs-on: windows-latest
    steps:
      - uses: actions/checkout@v3
      - name: Build Windows
        run: make build-windows

🛠️ Все команды Makefile

Основные команды:

Команда Описание
make build Собрать для текущей ОС
make build-linux Собрать для Linux
make build-windows Собрать для Windows
make build-all Собрать для всех платформ
make package-linux Создать tar.gz пакет
make package-windows Создать zip пакет
make release Полный цикл релиза

Вспомогательные команды:

Команда Описание
make install-pyinstaller Установить PyInstaller
make test-build Протестировать собранный файл
make clean-build Очистить артефакты сборки
make build-info Показать информацию о среде

🐛 Troubleshooting

Проблема: PyInstaller не найден

Ошибка:

make: pyinstaller: Command not found

Решение:

make install-pyinstaller
# или
pip install pyinstaller

Проблема: Импорт модулей не работает

Ошибка:

ModuleNotFoundError: No module named 'requests'

Решение:

pip install -r requirements.txt
# или добавьте в PyInstaller команду:
--hidden-import requests
--hidden-import certbot
--hidden-import cryptography

Проблема: Большой размер файла

Размер ~100+ MB вместо 40-60 MB

Причины:

  • Включены лишние модули
  • Не используется --onefile
  • Включены debug символы

Решение:

# Используйте флаги оптимизации:
pyinstaller --onefile \
  --strip \
  --exclude-module tkinter \
  --exclude-module matplotlib \
  letsencrypt_regru_api.py

Проблема: Certbot не работает в исполняемом файле

Ошибка:

certbot: command not found

Решение:

Certbot вызывается через subprocess и должен быть установлен в системе:

Linux:

sudo apt-get install certbot

Windows:

  • Не поддерживается напрямую
  • Используйте WSL или Docker

Проблема: Права доступа к файлам

Ошибка:

Permission denied: /etc/letsencrypt/

Решение:

# Linux/macOS
sudo ./dist/letsencrypt-regru --check

# Или установите правильные права:
sudo chmod +x ./dist/letsencrypt-regru
sudo chown root:root ./dist/letsencrypt-regru

Проблема: Медленный запуск

Первый запуск занимает 5-10 секунд

Причина: PyInstaller распаковывает файлы во временную директорию при каждом запуске.

Решение:

  • Это нормальное поведение для --onefile
  • Используйте --onedir для более быстрого запуска (но будет много файлов)
  • Кэшируйте временную директорию (автоматически)

Проблема: Антивирус блокирует файл

Windows Defender помечает .exe как вирус

Причины:

  • Самораспаковывающийся архив похож на вредоносное ПО
  • Отсутствие цифровой подписи
  • Малоизвестный исполняемый файл

Решение:

  1. Добавьте в исключения:

    • Windows Defender → Settings → Exclusions

  2. Подпишите файл цифровой подписью:

    # Требуется сертификат Code Signing
signtool sign /f cert.pfx /p password dist/letsencrypt-regru.exe

  3. Проверьте на VirusTotal:

    • Загрузите файл на virustotal.com
    • Добавьте результаты в README

📊 Сравнение: Python vs Исполняемый файл

Характеристика Python скрипт Исполняемый файл
Размер ~50 KB ~40-60 MB
Зависимости Требует Python + pip Автономный
Скорость запуска Быстро (~1 сек) Медленно (~5-10 сек)
Обновление Просто заменить .py Требуется пересборка
Совместимость Любая ОС с Python Только для целевой ОС
Установка Требует venv setup Скачать и запустить
Certbot Через subprocess Через subprocess

🎯 Рекомендации

Используйте Python скрипт если:

  • ✅ Python уже установлен в системе
  • ✅ Нужны частые обновления кода
  • ✅ Используете виртуальное окружение
  • ✅ Работаете на серверах (production)

Используйте исполняемый файл если:

  • ✅ Python не установлен
  • ✅ Нужна простота развертывания
  • ✅ Распространяете для конечных пользователей
  • ✅ Тестирование на чистых системах

📦 Пример использования собранного файла

Linux:

# Скачать и распаковать
wget https://github.com/user/repo/releases/download/v1.0/letsencrypt-regru-linux-x86_64.tar.gz
tar -xzf letsencrypt-regru-linux-x86_64.tar.gz

# Установить
sudo mv letsencrypt-regru /usr/local/bin/
sudo chmod +x /usr/local/bin/letsencrypt-regru

# Использовать
sudo letsencrypt-regru --help
sudo letsencrypt-regru --check -c /etc/letsencrypt-regru/config.json

Windows:

# Скачать и распаковать
Invoke-WebRequest -Uri "https://github.com/user/repo/releases/download/v1.0/letsencrypt-regru-windows-x86_64.zip" -OutFile "letsencrypt-regru.zip"
Expand-Archive -Path letsencrypt-regru.zip -DestinationPath "C:\Program Files\LetsEncrypt-RegRu"

# Использовать
cd "C:\Program Files\LetsEncrypt-RegRu"
.\letsencrypt-regru.exe --help

📝 Дополнительные ресурсы

📄 Лицензия

Этот проект использует лицензию согласно основному README.md.

Автор: Фофанов Дмитрий
Дата обновления: 28.10.2025