Language / Язык

[🇷🇺 Russian] | 🇺🇸 English

🚀 OpenWrtFW Builder (Image + Source) + ipk injection

Наверняка многие хотели иметь персональный бинарник роутера на OpenWrt с полным конфигом и кастомными пакетами. Не просто резервная копия, а прямой откат версии в чистый .bin!

Теперь этот проект вырос в Универсальный комбайн, объединяющий два подхода: быстрая сборка (ImageBuilder) и полная компиляция (SourceBuilder).

В версии 3.0+ произошел глобальный рефакторинг: старые скрипты _Image_Builder.bat и _Source_Builder.bat были удалены и заменены единым _Builder, который управляет обоими режимами в двух OS Windows и Linux.

---

📥 Установка и Скачивание (Download)

Весь проект — это один интернациональный самораспаковывающийся файл _unpacker. Вам не нужно качать zip-архивы или клонировать репозиторий.

• Подготовка: Скачайте и установите Docker Desktop.

Выберите способ получения:

• 🔥 Скачать _unpacker.bat (Актуальная версия) — Самый свежий Windows код.
• 🔥 Скачать _unpacker.sh (Актуальная версия) — Самый свежий Linux код.
• 📦 Раздел Releases — Проверенные версии с описанием изменений.

Как запустить:

1. Поместите _unpacker. в пустую папку (например, \OpenWrtBuilder), где нет кириллицы в пути.
2. Запустите его — он развернет структуру проекта.
3. Запустите появившийся _Builder.

• Интернациональность: Весь процесс подготовки ресурсов и логи теперь переведены на английский язык, что делает сборщик доступным для пользователей по всему миру.
• Простота: Поместите файл в пустую папку и запустите. Скрипт сам создаст структуру и скачает необходимые компоненты.

🖥 Интерфейс

Внешний вид: Главное окно

Внешний вид: Множественная сборка

---

📊 Система индикаторов профиля

В главном меню реализована "хирургическая" панель ресурсов [F P S M H | OI OS], позволяющая мгновенно оценить состав профиля:

• F (Files) — Наличие файлового оверлея (custom_files).
• P (Packages) — Наличие сторонних .ipk пакетов.
• S (Source) — Наличие исходного кода пакетов (src_packages).
• M (Manual Config) — [NEW] Обнаружен активный файл ручной настройки Menuconfig.
• H (Hooks) — [NEW] Обнаружен скрипт автоматизации hooks.sh.
• OI / OS — Наличие готовых прошивок (Image / Source Builder).

📖 Документация и Обучение

Для проекта создана расширенная база знаний, которая поможет вам пройти путь от новичка до профи.

👉 ОТКРЫТЬ ПОЛНОЕ РУКОВОДСТВО (DOCS)

Внутри вы найдете:

• Уроки 1-3: Основы, настройка конфигов и быстрый старт.
• Урок 4 (Advanced): Продвинутый Source-режим: внедрение сторонних программ из исходников, применение патчей и глубокая кастомизация.
• Troubleshooting: Решение частых проблем компиляции и Docker.

---

⚡ О проекте

Сборка происходит в изолированных Docker-контейнерах. Система не мусорит в Системе и удаляется одним кликом.

Два режима работы:

1. 🐇 Image Builder (Быстрый)

• Скорость: 1-2 минуты.
• Для чего: Добавить пакеты (luci, vpn), зашить конфиги Wi-Fi/PPPoE.
• Фишки: Atomic Downloads (защита от сбоев сети), умный кэш (повторная сборка ~30 сек), интеграция сторонних .ipk (папка custom_packages).

2. 🐢 Source Builder (Мощный)

• Скорость: Первый запуск ~20-60 мин, повторные ~3-5 мин (благодаря CCache).
• Для чего: 16MB мод, патчи ядра, компиляция программ из исходников.
• Фишки:
  • Vermagic Hack: Официальные драйверы (kmod-) ставятся без ошибок.
  • Persistence: Изолированные папки и кэши для каждого профиля.
  • Binary-to-Source Import: Позволяет встраивать готовые .ipk пакеты (даже без исходников) прямо в прошивку, компилируемую из исходного кода.
  • Работа с любыми Git-ветками и форками (ImmortalWrt, Padavan).

---

🧹 Система очистки (Maintenance Mode)

Кнопка [C] CLEAN вызывает мастер гранулярной очистки:

Опция	Описание	Когда использовать?
Soft Clean	Выполняет make clean.	Если ошибки в линковке пакетов.
Hard Reset	Удаляет src-workdir, сохраняя dl.	Если сломан Toolchain или Git-дерево.
Clean DL	Удаляет архив исходников.	Если нужно освободить место на диске.
Clean Ccache	Сбрасывает кэш компилятора.	При смене архитектуры или версии GCC.
Factory Reset	Удаляет ВСЁ для профиля.	Полный сброс в "заводское" состояние.

---

🧙 Мастер профилей (Profile Wizard)

Забыли архитектуру своего роутера или боитесь ошибиться в синтаксисе? Используйте пункт меню [W] Profile Wizard.

• Пошаговый выбор: Релиз, платформа и модель роутера выбираются из списков.
• Умные настройки: Просто жмите Enter для выбора стандартных значений (LuCI, системные имена).
• Валидация: Мастер сам исправит пробелы в названиях и защитит файлы от случайной перезаписи.
• Готовый результат: На выходе — чистый .conf с полезными комментариями и примерами оптимизации.

---

📂 Структура папок

• docs/ — Оффлайн-копия базы знаний.
• profiles/ — Ваши универсальные .conf файлы.
• custom_files/имя_профиля/ — Файловый оверлей (всё отсюда попадет в корень роутера).
• custom_packages/имя_профиля/ — Папка для .ipk пакетов. Используется в ImageBuilder (прямое включение) и как источник для импорта в SourceBuilder.
• src_packages/имя_профиля/ — Для исходников. Используется для сторонних пакетов с GitHub и как выходная папка для .ipk, обработанных импортером.
• firmware_output/ — Готовые прошивки и логи сборки.
• system/ — Папка с докерфайлами, скриптами - и ядром сборщика.

---

⚙️ Универсальные профили (.conf)

Вам не нужно настраивать каждый режим сборки отдельно. Система использует единый файл конфигурации для управления всем процессом:

• Один список программ: управляйте всеми пакетами (VPN, AdGuard, Luci) в одной строке для обоих режимов.
• Гибкое управление: в одном месте задаются и модель роутера, и количество ядер процессора для сборки, и размеры разделов памяти.
• Порядок: один файл — одно устройство. Легко редактировать, легко делиться с другими.

👉 Подробный разбор структуры профиля и пошаговое создание «идеального рецепта» читайте в Уроке №2: Цифровой двойник вашего роутера.

---

🎛️ Управление ресурсами (SRC_CORES Source Builder)

Настройка нагрузки на CPU в файле профиля (.conf):

• SRC_CORES="safe" — использует все ядра минус одно ($N-1$). Система остается отзывчивой.
• Не задано (по умолчанию) — использует все доступные ядра ($N$). Максимальная скорость.
• SRC_CORES="4" — фиксированное количество потоков сборки.

# Пример: оставить одно ядро свободным
SRC_CORES="safe"

---

🪝 Smart Hooks и Vermagic Hack

В комплекте идет умный скрипт scripts/hooks.sh. При помещении в папку custom_files/ваш_профиль/ он активирует несколько мощных функций:

1. Авто-включение Wi-Fi при первой загрузке: Скрипт автоматически создает uci-defaults сценарий, который включает все радиомодули при первом запуске роутера. Это избавляет от необходимости подключаться по кабелю для первоначальной настройки.
2. Git-Safe Patching: Безопасное изменение исходного кода перед сборкой. Позволяет менять DTS, Makefiles (например, для 16MB мода). Автоматические бэкапы защищают от поломки дерева исходников при смене версий.
3. Vermagic Hack (Совместимость с репозиторием):
   • Проблема: Обычно, когда вы собираете свое ядро (SourceBuilder), его "отпечаток" (vermagic) отличается от официального. Из-за этого вы не можете установить пакеты kmod-* (драйверы) из официального репозитория.
   • Решение: Скрипт автоматически скачивает официальный манифест для вашей версии OpenWrt, выдергивает оттуда правильный хэш и "обманывает" систему сборки.
   • Итог: Вы получаете кастомную прошивку, на которую можно ставить официальные драйверы (USB, Wireguard, FS) без ошибок!

   💡 Логика "самовосстановления": Модуль SourceBuilder обладает встроенным механизмом отката.

Сценарий: Вы использовали профиль с hooks.sh (для Vermagic или других патчей), а затем убрали этот хук. Результат: Система сама обнаружит "грязное" состояние сборки и проведет полную автоматическую очистку: восстановит оригинальные файлы сборки, выполнит глубокую очистку кэша ядра и полностью сбросит CCACHE. Это предотвращает труднодиагностируемые ошибки и делает систему гораздо более надежной.

🛡️ Архитектура надежности (v4.09+)

Начиная с версии 4.09, архитектура сборщика была значительно переработана с фокусом на предсказуемость и стабильность.

• Механизм "самовосстановления" (Source Builder):

  • Проблема: Использование патчей (hooks.sh) для изменения исходного кода (например, для Vermagic Hack) оставляет "грязный" след в среде сборки. Если затем собрать прошивку без этих патчей, остаточные изменения могли приводить к ошибкам.
  • Решение: Теперь сборщик автоматически определяет такое состояние. Если hooks.sh отсутствует, но система была изменена, он запускает полный цикл отката: восстанавливает чистые Makefiles, сбрасывает кэш ядра и CCACHE. Это гарантирует, что каждая сборка начинается в предсказуемо чистом окружении.

• Стабильность Docker на WSL/Linux:

  • Проблема: Взаимодействие Docker с файловой системой Windows (через WSL) могло приводить к ошибкам блокировки файлов, срывая сборку.
  • Решение: Реализован новый, более надежный цикл управления контейнерами. Перед запуском сборки система принудительно останавливает и удаляет старые контейнеры, давая файловой системе "продышаться". Это практически полностью устраняет данный класс ошибок.

---

🎛️ Интерактивная настройка (Menuconfig)

В версии 3.3 появилась возможность тонкой настройки ядра и пакетов через стандартное графическое меню OpenWrt (make menuconfig). Это доступно только в режиме Source Builder.

Как это работает:

1. Запуск меню: В главном меню выберите пункт [K] MENUCONFIG.
2. Настройка: Если это первый запуск то после подготовки откроется классический синий интерфейс Linux Kernel Configuration. Выберите нужные модули ядра, драйверы или пакеты.
3. Сохранение: Нажмите <Save> (оставьте имя .config) и <Exit>.
4. Результат: Скрипт перехватит конфиг и сохранит его как мастер-файл в папку: firmware_output/sourcebuilder/<имя_профиля>/manual_config

⚠️ Приоритет конфигурации (Manual Config)

Система сборки теперь автоматически определяет стратегию конфигурации:

• Автоматический режим (по умолчанию): Если файла manual_config нет в папке выходных файлов с прошивками, сборщик генерирует .config на лету, используя переменные из вашего профиля (SRC_PACKAGES, SRC_EXTRA_CONFIG, COMMON_LIST).
• Ручной режим (Приоритетный): Если файл manual_config обнаружен в папке вывода прошивок, сборщик ИГНОРИРУЕТ списки пакетов и опции ядра из .conf файла. Вместо этого он применяет ваш сохраненный конфиг "как есть" (добавляя только настройки кэширования).

Как вернуться к авто-сборке? Просто удалите или переименуйте файл manual_config в папке firmware_output.

🎛️ Интерактивная настройка и Синхронизация (v4.03)

В режиме Source Builder (пункт [K] MENUCONFIG) теперь реализован полный цикл синхронизации:

1. Настройка: Вы вносите изменения в графическом интерфейсе MenuConfig.
2. Синхронизация: При выходе скрипт автоматически предлагает перенести ваши изменения прямо в файл профиля (.conf).
3. Чистый синтаксис: Параметры записываются в переменную SRC_EXTRA_CONFIG в многострочном формате. Это позволяет сохранять даже комментарии вида # ... is not set и полностью исключает ошибки парсинга.
4. Архивация: Оригинальные правки сохраняются в папку applied_config_*.bak с меткой времени.

💡 Преимущество: Вам больше не нужно хранить тяжелые файлы .config. Весь ваш уникальный "рецепт" теперь живет внутри одного маленького .conf файла.

---

⚡ Быстрый старт Source Builder (Холодный запуск)

Если вы используете специфические репозитории со своим набором драйверов (например, для MT798x), используйте стратегию manual_config:

1. Инициализация: Настройте SRC_REPO и запустите [K] Menuconfig, чтобы система создала структуру папок.
2. Подмена: Возьмите минимальный defconfig от автора исходников (~15 КБ), переименуйте его в manual_config и положите в папку вывода профиля.
3. Развертывание: Снова запустите [K] Menuconfig — система сама разрешит зависимости и расширит файл до полного .config (~400 КБ).

👉 Подробная инструкция по глубокой настройке и работе с кастомными ядрами: docs/04-adv-source-build.md.

---

⚙️ Автоматический импорт .ipk пакетов (Binary-to-Source)

Это одна из ключевых возможностей Source Builder v3.8+, решающая сложную проблему: как встроить в прошивку готовый .ipk пакет, для которого у вас нет исходного кода.

Проблема: Обычно для добавления пакета в Source-сборку требуется написать сложный Makefile. Если у вас есть только бинарный .ipk (например, закрытый драйвер или старая программа), его интеграция превращается в кошмар: нужно вручную распаковывать архивы, прописывать пути, исправлять права доступа и надеяться, что система сборки не повредит готовые файлы.

Решение в Билдере — полная автоматизация: Вместо ручной работы, вы просто используете встроенный импортер:

1. Кладете .ipk в папку custom_packages/имя_вашего_профиля/.
2. Выбираете [I] Import IPK в главном меню.
3. Готово!

Скрипт сам выполнит всю грязную работу:

• Создаст Makefile-обертку: Вам больше не нужно писать их вручную.
• Сохранит симлинки и права: Распаковка происходит внутри Linux-контейнера, что решает проблемы с файловой системой.
• Защитит бинарники: Отключит strip и patchelf, чтобы система сборки не трогала ваши файлы.
• Проверит архитектуру: Предупредит, если вы пытаетесь импортировать mips пакет в aarch64 сборку.
• Интегрирует в Menuconfig: После импорта пакет появится в menuconfig в категории Custom-Packages, готовый для включения в прошивку.

Эта функция превращает интеграцию закрытого ПО из сложной инженерной задачи в трехшаговый процесс.

---

🛠 FAQ: Полезные советы и решение проблем

❓ ImageBuilder или SourceBuilder? Что выбрать?

Выбор зависит от ваших целей:

• ImageBuilder: (1–3 минуты). Идеален, если нужно просто добавить LuCI, VPN, настроить Wi-Fi или изменить состав пакетов.
• SourceBuilder: (20–60+ минут). Необходим для глубокого моддинга: создание прошивок для 4MB флешек (сжатие), изменение настроек ядра (Kernel), интеграция специфических драйверов или создание прошивки с нестандартным размером разделов (например, 16MB мод).

❓ Безопасна ли параллельная сборка нескольких профилей?

Да, полностью. В системе реализована технология Atomic Downloads и Global Locks.

• Если вы запускаете 5 сборок одновременно, использующих один и тот же SDK, скачивать его будет только первый процесс.
• Остальные дождутся завершения загрузки и используют готовый кэш. Конфликты «файл занят» или повреждение архивов исключены.

❓ Что делать при ошибках сети (wget error 4)?

Система адаптирована под нестабильные каналы связи благодаря Smart Retries:

• Внутри контейнеров настроен агрессивный wgetrc (5 попыток на каждый файл).
• Если сборка прервется из-за критической ошибки сети, основной скрипт автоматически выполнит до 3 полных перезапусков процесса.

---

🔍 Быстрые решения (Troubleshooting)

• Ошибка Package not found?
  • Убедитесь, что вы положили нужные .ipk файлы в папку custom_packages или проверьте правильность написания имен пакетов в вашем .conf файле.
• Как проверить работу Vermagic Hack?
  • После прошивки роутера попробуйте установить любой модуль ядра из официального репозитория, например: opkg update && opkg install kmod-fs-btrfs. Если установка прошла без ошибки Exec format error, значит, хак активен.
• Конфликт зависимостей (например, dnsmasq)?
  • При установке расширенных версий пакетов (full/crypto) всегда сначала удаляйте базовую версию.
  • Пример в конфиге: -dnsmasq dnsmasq-full.
• Ошибка The system cannot find the drive specified?
  • Обычно возникает, если путь к проекту содержит спецсимволы или пробелы. Рекомендуется размещать папку проекта ближе к корню диска (например, C:\OpenWrt_Build\).

---

🔧 Служебные скрипты (/scripts)

• hooks.sh — Шаблон для патчей и Vermagic.
• diag.sh — Создание отчета для диагностики роутера через ИИ.
• upgrade.sh — Массовое обновление всех пакетов на роутере.
• packager.sh — Генерация чистого списка только установленных пользователем пакетов.
• show_pkgs.sh - Альтернативный вариант получить список пакетов из уроков.
• 99-permissions.sh — Авто-фикс прав доступа для файлов (Dropbear/SSH).

---

Аудит проекта https://github.com/iqubik/routerFW/blob/main/audit.md