---
url: https://kernelsu.org/ru_RU/guide/metamodule.md
---
# Метамодуль

Метамодули — это революционная функция в KernelSU, которая передает критически важные возможности модульной системы от основного демона к подключаемым модулям. Это архитектурное изменение сохраняет стабильность и безопасность KernelSU, одновременно раскрывая больший потенциал для инноваций в экосистеме модулей.

## Что такое Метамодуль?

Метамодуль — это специальный тип модуля KernelSU, который предоставляет основную инфраструктурную функциональность для модульной системы. В отличие от обычных модулей, которые модифицируют системные файлы, метамодули контролируют *способ* установки и монтирования обычных модулей.

Метамодули — это механизм расширения на основе плагинов, который позволяет полностью настраивать инфраструктуру управления модулями KernelSU. Делегируя логику монтирования и установки метамодулям, KernelSU избегает превращения в уязвимую точку обнаружения, одновременно поддерживая различные стратегии реализации.

**Ключевые характеристики:**

* **Роль инфраструктуры**: Метамодули предоставляют сервисы, от которых зависят обычные модули
* **Единственный экземпляр**: Одновременно может быть установлен только один метамодуль
* **Приоритетное выполнение**: Скрипты метамодулей выполняются перед скриптами обычных модулей
* **Специальные хуки**: Предоставляет три скрипта-хука для установки, монтирования и очистки

## Зачем нужны Метамодули?

Традиционные решения для получения root встраивают логику монтирования в свое ядро, что делает их более легко обнаруживаемыми и сложными для развития. Архитектура метамодулей KernelSU решает эти проблемы через разделение ответственности.

**Стратегические преимущества:**

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

**Гибкость монтирования:**

* **Без монтирования**: Для пользователей с модулями только без монтирования полностью избегайте накладных расходов на монтирование
* **Монтирование OverlayFS**: Традиционный подход с поддержкой слоя чтения-записи (через `meta-overlayfs`)
* **Magic mount**: Монтирование, совместимое с Magisk, для лучшей совместимости с приложениями
* **Пользовательские реализации**: Наложения на основе FUSE, пользовательские монтирования VFS или совершенно новые подходы

**Помимо монтирования:**

* **Расширяемость**: Добавляйте функции, такие как поддержка модулей ядра, без изменения основного KernelSU
* **Модульность**: Обновляйте реализации независимо от выпусков KernelSU
* **Настройка**: Создавайте специализированные решения для конкретных устройств или случаев использования

::: warning ВАЖНО
Без установленного метамодуля модули **НЕ** будут смонтированы. Свежие установки KernelSU требуют установки метамодуля (например, `meta-overlayfs`) для работы модулей.
:::

## Для Пользователей

### Установка Метамодуля

Установите метамодуль так же, как обычные модули:

1. Загрузите ZIP-файл метамодуля (например, `meta-overlayfs.zip`)
2. Откройте приложение KernelSU Manager
3. Нажмите на плавающую кнопку действия (➕)
4. Выберите ZIP-файл метамодуля
5. Перезагрузите устройство

Метамодуль `meta-overlayfs` — это официальная эталонная реализация, которая обеспечивает традиционное монтирование модулей на основе overlayfs с поддержкой образов ext4.

### Проверка Активного Метамодуля

Вы можете проверить, какой метамодуль в настоящее время активен, на странице модулей приложения KernelSU Manager. Активный метамодуль будет отображаться в вашем списке модулей со своим специальным обозначением.

### Удаление Метамодуля

::: danger ПРЕДУПРЕЖДЕНИЕ
Удаление метамодуля повлияет на **ВСЕ** модули. После удаления модули больше не будут монтироваться, пока вы не установите другой метамодуль.
:::

Для удаления:

1. Откройте KernelSU Manager
2. Найдите метамодуль в списке модулей
3. Нажмите удалить (вы увидите специальное предупреждение)
4. Подтвердите действие
5. Перезагрузите устройство

После удаления вы должны установить другой метамодуль, если хотите, чтобы модули продолжали работать.

### Ограничение Единственного Метамодуля

Одновременно может быть установлен только один метамодуль. Если вы попытаетесь установить второй метамодуль, KernelSU предотвратит установку, чтобы избежать конфликтов.

Для переключения метамодулей:

1. Удалите все обычные модули
2. Удалите текущий метамодуль
3. Перезагрузите
4. Установите новый метамодуль
5. Переустановите обычные модули
6. Перезагрузите снова

## Для Разработчиков Модулей

Если вы разрабатываете обычные модули KernelSU, вам не нужно слишком беспокоиться о метамодулях. Ваши модули будут работать, пока у пользователей установлен совместимый метамодуль (например, `meta-overlayfs`).

**Что вам нужно знать:**

* **Монтирование требует метамодуль**: Директория `system` в вашем модуле будет смонтирована только если у пользователя установлен метамодуль, предоставляющий функциональность монтирования
* **Изменения кода не требуются**: Существующие модули продолжают работать без изменений

::: tip
Если вы знакомы с разработкой модулей Magisk, ваши модули будут работать точно так же в KernelSU при установленном метамодуле, так как он предоставляет монтирование, совместимое с Magisk.
:::

## Для Разработчиков Метамодулей

Создание метамодуля позволяет вам настроить, как KernelSU обрабатывает установку модулей, монтирование и удаление.

### Базовые Требования

Метамодуль идентифицируется специальным свойством в `module.prop`:

```txt
id=my_metamodule
name=My Custom Metamodule
version=1.0
versionCode=1
author=Your Name
description=Custom module mounting implementation
metamodule=1
```

Свойство `metamodule=1` (или `metamodule=true`) помечает это как метамодуль. Без этого свойства модуль будет рассматриваться как обычный модуль.

### Структура Файлов

Структура метамодуля:

```txt
my_metamodule/
├── module.prop              (должен включать metamodule=1)
│
│      *** Специфичные хуки метамодуля ***
├── metamount.sh             (опционально: пользовательский обработчик монтирования)
├── metainstall.sh           (опционально: хук установки для обычных модулей)
├── metauninstall.sh         (опционально: хук очистки для обычных модулей)
│
│      *** Стандартные файлы модуля (все опциональные) ***
├── customize.sh             (настройка установки)
├── post-fs-data.sh          (скрипт этапа post-fs-data)
├── service.sh               (скрипт late_start service)
├── boot-completed.sh        (скрипт завершения загрузки)
├── uninstall.sh             (скрипт удаления самого метамодуля)
├── system/                  (системные модификации, если необходимо)
└── [любые дополнительные файлы]
```

Метамодули могут использовать все стандартные функции модулей (скрипты жизненного цикла и т. д.) в дополнение к своим специальным хукам метамодуля.

### Скрипты-Хуки

Метамодули могут предоставлять до трех специальных скриптов-хуков:

#### 1. metamount.sh - Обработчик Монтирования

**Назначение**: Контролирует способ монтирования модулей во время загрузки.

**Когда выполняется**: Во время этапа `post-fs-data`, перед выполнением любых скриптов модулей.

**Переменные окружения:**

* `MODDIR`: Путь к директории метамодуля (например, `/data/adb/modules/my_metamodule`)
* Все стандартные переменные окружения KernelSU

**Обязанности:**

* Монтировать все включенные модули системно
* Проверять флаги `skip_mount`
* Обрабатывать специфичные требования монтирования модулей

::: danger КРИТИЧЕСКОЕ ТРЕБОВАНИЕ
При выполнении операций монтирования вы **ДОЛЖНЫ** установить имя источника/устройства в `"KSU"`. Это идентифицирует монтирования как принадлежащие KernelSU.

**Пример (правильный):**

```sh
mount -t overlay -o lowerdir=/lower,upperdir=/upper,workdir=/work KSU /target
```

**Для современных API монтирования** установите строку источника:

```rust
fsconfig_set_string(fs, "source", "KSU")?;
```

Это необходимо для правильной идентификации и управления монтированиями KernelSU.
:::

**Пример скрипта:**

```sh
#!/system/bin/sh
MODDIR="${0%/*}"

# Пример: Простая реализация bind mount
for module in /data/adb/modules/*; do
    if [ -f "$module/disable" ] || [ -f "$module/skip_mount" ]; then
        continue
    fi

    if [ -d "$module/system" ]; then
        # Монтирование с source=KSU (ОБЯЗАТЕЛЬНО!)
        mount -o bind,dev=KSU "$module/system" /system
    fi
done
```

#### 2. metainstall.sh - Хук Установки

**Назначение**: Настроить способ установки обычных модулей.

**Когда выполняется**: Во время установки модуля, после извлечения файлов, но до завершения установки. Этот скрипт **подключается** (не выполняется) встроенным установщиком, аналогично работе `customize.sh`.

**Переменные окружения и функции:**

Этот скрипт наследует все переменные и функции из встроенного `install.sh`:

* **Переменные**: `MODPATH`, `TMPDIR`, `ZIPFILE`, `ARCH`, `API`, `IS64BIT`, `KSU`, `KSU_VER`, `KSU_VER_CODE`, `KSU_UAPI_VER`, `KSU_RUNTIME_MODE`, `KSU_LATE_LOAD`, `BOOTMODE` и т. д.
* **Функции**:
  * `ui_print <msg>` - Вывести сообщение в консоль
  * `abort <msg>` - Вывести ошибку и завершить установку
  * `set_perm <target> <owner> <group> <permission> [context]` - Установить права доступа к файлу
  * `set_perm_recursive <directory> <owner> <group> <dirpermission> <filepermission> [context]` - Установить права рекурсивно
  * `install_module` - Вызвать встроенный процесс установки модуля

**Случаи использования:**

* Обработка файлов модуля до или после встроенной установки (вызовите `install_module`, когда готово)
* Перемещение файлов модуля
* Проверка совместимости модуля
* Настройка специальных структур каталогов
* Инициализация специфичных для модуля ресурсов

**Примечание**: Этот скрипт **НЕ** вызывается при установке самого метамодуля.

#### 3. metauninstall.sh - Хук Очистки

**Назначение**: Очистить ресурсы при удалении обычных модулей.

**Когда выполняется**: Во время удаления модуля, перед удалением каталога модуля.

**Переменные окружения:**

* `MODULE_ID`: ID удаляемого модуля

**Случаи использования:**

* Обработка файлов
* Очистка символических ссылок
* Освобождение выделенных ресурсов
* Обновление внутреннего отслеживания

**Пример скрипта:**

```sh
#!/system/bin/sh
# Вызывается при удалении обычных модулей
MODULE_ID="$1"
IMG_MNT="/data/adb/metamodule/mnt"

# Удалить файлы модуля из образа
if [ -d "$IMG_MNT/$MODULE_ID" ]; then
    rm -rf "$IMG_MNT/$MODULE_ID"
fi
```

### Порядок Выполнения

Понимание порядка выполнения загрузки критически важно для разработки метамодулей:

```txt
этап post-fs-data:
  1. Выполняются общие скрипты post-fs-data.d
  2. Очистка модулей, restorecon, загрузка sepolicy.rule
  3. Выполняется post-fs-data.sh метамодуля (если существует)
  4. Выполняются post-fs-data.sh обычных модулей
  5. Загружается system.prop
  6. Выполняется metamount.sh метамодуля
     └─> Монтирует все модули системно
  7. Выполняется этап post-mount.d
     - Общие скрипты post-mount.d
     - post-mount.sh метамодуля (если существует)
     - post-mount.sh обычных модулей

этап service:
  1. Выполняются общие скрипты service.d
  2. Выполняется service.sh метамодуля (если существует)
  3. Выполняются service.sh обычных модулей

этап boot-completed:
  1. Выполняются общие скрипты boot-completed.d
  2. Выполняется boot-completed.sh метамодуля (если существует)
  3. Выполняются boot-completed.sh обычных модулей
```

**Ключевые моменты:**

* `metamount.sh` выполняется **ПОСЛЕ** всех скриптов post-fs-data (как метамодуля, так и обычных модулей)
* Скрипты жизненного цикла метамодуля (`post-fs-data.sh`, `service.sh`, `boot-completed.sh`) всегда выполняются перед скриптами обычных модулей
* Общие скрипты в каталогах `.d` выполняются перед скриптами метамодуля
* Этап `post-mount` выполняется после завершения монтирования

### Механизм Символических Ссылок

При установке метамодуля KernelSU создает символическую ссылку:

```sh
/data/adb/metamodule -> /data/adb/modules/<metamodule_id>
```

Это обеспечивает стабильный путь для доступа к активному метамодулю независимо от его ID.

**Преимущества:**

* Постоянный путь доступа
* Простое обнаружение активного метамодуля
* Упрощение конфигурации

### Реальный Пример: meta-overlayfs

Метамодуль `meta-overlayfs` является официальной эталонной реализацией. Он демонстрирует лучшие практики разработки метамодулей.

#### Архитектура

`meta-overlayfs` использует **архитектуру с двумя каталогами**:

1. **Каталог метаданных**: `/data/adb/modules/`
   * Содержит `module.prop`, `disable`, маркеры `skip_mount`
   * Быстро сканируется во время загрузки
   * Малый объем хранения

2. **Каталог содержимого**: `/data/adb/metamodule/mnt/`
   * Содержит фактические файлы модулей (system, vendor, product и т. д.)
   * Хранится в образе ext4 (`modules.img`)
   * Оптимизировано по пространству с функциями ext4

#### Реализация metamount.sh

Вот как `meta-overlayfs` реализует обработчик монтирования:

```sh
#!/system/bin/sh
MODDIR="${0%/*}"
IMG_FILE="$MODDIR/modules.img"
MNT_DIR="$MODDIR/mnt"

# Монтировать образ ext4, если он еще не смонтирован
if ! mountpoint -q "$MNT_DIR"; then
    mkdir -p "$MNT_DIR"
    mount -t ext4 -o loop,rw,noatime "$IMG_FILE" "$MNT_DIR"
fi

# Установить переменные окружения для поддержки двух каталогов
export MODULE_METADATA_DIR="/data/adb/modules"
export MODULE_CONTENT_DIR="$MNT_DIR"

# Выполнить бинарный файл монтирования
# (Фактическая логика монтирования находится в бинарном файле Rust)
"$MODDIR/meta-overlayfs"
```

#### Ключевые Особенности

**Монтирование Overlayfs:**

* Использует kernel overlayfs для настоящих системных модификаций
* Поддерживает несколько разделов (system, vendor, product, system_ext, odm, oem)
* Поддержка слоя чтения-записи через `/data/adb/modules/.rw/`

**Идентификация источника:**

```rust
// Из meta-overlayfs/src/mount.rs
fsconfig_set_string(fs, "source", "KSU")?;  // ОБЯЗАТЕЛЬНО!
```

Это устанавливает `dev=KSU` для всех overlay монтирований, обеспечивая правильную идентификацию.

### Лучшие Практики

При разработке метамодулей:

1. **Всегда устанавливайте источник в "KSU"** для операций монтирования - размонтированию ядра и zygisksu нужно это для правильного размонтирования
2. **Обрабатывайте ошибки корректно** - процессы загрузки чувствительны ко времени
3. **Уважайте стандартные флаги** - поддерживайте `skip_mount` и `disable`
4. **Логируйте операции** - используйте `echo` или логирование для отладки
5. **Тщательно тестируйте** - ошибки монтирования могут вызвать циклы загрузки
6. **Документируйте поведение** - ясно объясняйте, что делает ваш метамодуль
7. **Предоставляйте пути миграции** - помогайте пользователям переключаться с других решений

### Тестирование Вашего Метамодуля

Перед выпуском:

1. **Тестируйте установку** на чистой настройке KernelSU
2. **Проверяйте монтирование** с различными типами модулей
3. **Проверяйте совместимость** с распространенными модулями
4. **Тестируйте удаление** и очистку
5. **Проверяйте производительность загрузки** (metamount.sh блокирует!)
6. **Обеспечьте правильную обработку ошибок** для избежания циклов загрузки

## Часто Задаваемые Вопросы

### Нужен ли мне метамодуль?

**Для пользователей**: Только если вы хотите использовать модули, требующие монтирования. Если вы используете только модули, которые запускают скрипты без изменения системных файлов, вам не нужен метамодуль.

**Для разработчиков модулей**: Нет, вы разрабатываете модули как обычно. Пользователям нужен метамодуль только если ваш модуль требует монтирования.

**Для продвинутых пользователей**: Только если вы хотите настроить поведение монтирования или создать альтернативные реализации монтирования.

### Могу ли я иметь несколько метамодулей?

Нет. Одновременно может быть установлен только один метамодуль. Это предотвращает конфликты и обеспечивает предсказуемое поведение.

### Что произойдет, если я удалю свой единственный метамодуль?

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

### Обязателен ли meta-overlayfs?

Нет. Он обеспечивает стандартное монтирование overlayfs, совместимое с большинством модулей. Вы можете создать свой собственный метамодуль, если вам нужно другое поведение.

## См. Также

* [Руководство по Модулям](module.md) - Общая разработка модулей
* [Разница с Magisk](difference-with-magisk.md) - Сравнение KernelSU и Magisk
* [Как Собрать](how-to-build.md) - Сборка KernelSU из исходного кода