RAMBA Wiki - Вклад [ru]

Git komand

2026-09-30T13:12:45Z

Artem: Новая страница: «'''Git''' — система контроля версий. Она позволяет сохранять историю изменений, работать с ветками и обмениваться кодом через удалённый репозиторий, например GitLab или GitHub. На этой странице собраны команды из памятки ''Git_useful_commands.pdf'' с уточнёнными описаниям...»

'''Git''' — система контроля версий. Она позволяет сохранять историю изменений, работать с ветками и обмениваться кодом через удалённый репозиторий, например GitLab или GitHub.

На этой странице собраны команды из памятки ''Git_useful_commands.pdf'' с уточнёнными описаниями и практическими примерами.

__TOC__

== Как устроена работа с Git ==

{| class="wikitable" style="width:100%;"
! Понятие !! Что означает
|-
| Рабочая папка || Файлы проекта, которые вы редактируете.
|-
| Индекс (staging area) || Подготовленные изменения для следующего коммита. В индекс попадает состояние файла на момент выполнения <code>git add</code>.
|-
| Коммит || Сохранённая версия подготовленных изменений в локальной истории Git.
|-
| Ветка || Отдельная линия разработки, например <code>main</code> или <code>feature/new-command</code>.
|-
| Удалённый репозиторий || Репозиторий на другом компьютере или сервере. Обычно его короткое имя — <code>origin</code>.
|}

Обычная последовательность: '''изменить файлы → проверить изменения → git add → git commit → git push'''.

'''Важно:''' коммит сохраняет изменения локально. Чтобы отправить коммиты на сервер, нужна отдельная команда <code>git push</code>.

== Проверка и создание репозитория ==

=== git --version — версия Git ===

Показывает установленную версию Git.

<syntaxhighlight lang="bash">
git --version
</syntaxhighlight>

=== git init — создать локальный репозиторий ===

Инициализирует репозиторий в текущей папке. Создаёт служебный каталог <code>.git</code>, в котором Git хранит историю и настройки. Файлы проекта автоматически в коммит не попадают.

<syntaxhighlight lang="bash">
cd my-project
git init
</syntaxhighlight>

=== Дополнительно: git clone — скачать существующий проект ===

Создаёт локальную копию удалённого репозитория и обычно настраивает для него имя <code>origin</code>. Замените адрес на URL своего проекта.

<syntaxhighlight lang="bash">
git clone https://gitlab.example.com/team/my-project.git
cd my-project
</syntaxhighlight>

После <code>git clone</code> выполнять <code>git init</code> не требуется.

== Проверка изменений ==

=== git status — состояние проекта ===

Показывает текущую ветку, подготовленные изменения, изменения вне индекса и новые неотслеживаемые файлы. Игнорируемые файлы по умолчанию не выводятся.

<syntaxhighlight lang="bash">
git status
</syntaxhighlight>

Краткий вариант:

<syntaxhighlight lang="bash">
git status -sb
</syntaxhighlight>

=== git diff — посмотреть изменения ===

Показывает разницу между рабочей папкой и индексом: изменения в отслеживаемых файлах, которые ещё не подготовлены к коммиту.

<syntaxhighlight lang="bash">
git diff
</syntaxhighlight>

Посмотреть изменения, уже подготовленные к следующему коммиту:

<syntaxhighlight lang="bash">
git diff --staged
</syntaxhighlight>

Посмотреть изменения конкретного файла вне индекса:

<syntaxhighlight lang="bash">
git diff -- README.md
</syntaxhighlight>

'''Обратите внимание:''' обычный <code>git diff</code> не показывает содержимое новых неотслеживаемых файлов. Если изменения уже добавлены через <code>git add</code>, смотрите их через <code>git diff --staged</code>.

== Подготовка и сохранение изменений ==

=== git add — подготовить изменения ===

Добавляет в индекс новые файлы, изменения и удаления в указанной области.

Все изменения в текущей папке и её подпапках, кроме игнорируемых неотслеживаемых файлов:

<syntaxhighlight lang="bash">
git add .
</syntaxhighlight>

Только выбранный файл:

<syntaxhighlight lang="bash">
git add README.md
</syntaxhighlight>

Несколько файлов:

<syntaxhighlight lang="bash">
git add README.md bot/main.py
</syntaxhighlight>

Если после <code>git add</code> снова отредактировать файл, новые правки нужно добавить повторно. Перед массовым добавлением проверьте <code>git status</code>, чтобы в коммит не попали пароли, токены или ненужные файлы.

=== git commit -m — сохранить коммит ===

Создаёт локальный коммит из изменений в индексе. Параметр <code>-m</code> задаёт сообщение с описанием изменений.

<syntaxhighlight lang="bash">
git commit -m "Добавлена команда просмотра статистики"
</syntaxhighlight>

Пишите, что именно изменилось. Например: <code>Исправлено переподключение к Telegram</code> вместо <code>update</code>.

== Работа с удалённым репозиторием ==

=== git remote — список подключений ===

Показывает короткие имена настроенных удалённых репозиториев, например <code>origin</code> и <code>upstream</code>.

<syntaxhighlight lang="bash">
git remote
</syntaxhighlight>

=== git remote -v — адреса репозиториев ===

Показывает имена и URL для получения изменений (<code>fetch</code>) и отправки (<code>push</code>).

<syntaxhighlight lang="bash">
git remote -v
</syntaxhighlight>

Для нового проекта, созданного через <code>git init</code>, подключение можно добавить отдельно. Репозиторий на сервере должен уже существовать:

<syntaxhighlight lang="bash">
git remote add origin https://gitlab.example.com/team/my-project.git
</syntaxhighlight>

=== git push — отправить коммиты на сервер ===

Отправляет локальные коммиты и обновляет соответствующие ветки на сервере согласно параметрам команды и настройкам Git. Незакоммиченные правки не отправляются.

Если для текущей ветки уже настроена связь с удалённой веткой:

<syntaxhighlight lang="bash">
git push
</syntaxhighlight>

При первой отправке новой ветки:

<syntaxhighlight lang="bash">
git push -u origin feature/new-command
</syntaxhighlight>

Здесь <code>-u</code> настраивает отслеживаемую удалённую ветку для последующих команд. Замените <code>feature/new-command</code> на имя своей ветки.

=== git pull — получить и включить изменения ===

Получает изменения с сервера и включает их в текущую ветку. Способ включения зависит от параметров и настроек: слияние, rebase или только fast-forward.

<syntaxhighlight lang="bash">
git pull
</syntaxhighlight>

Для обычного обновления без автоматического создания коммита слияния:

<syntaxhighlight lang="bash">
git pull --ff-only
</syntaxhighlight>

Если локальная и удалённая истории разошлись, <code>--ff-only</code> остановит обновление. Перед обновлением проверьте <code>git status</code> и сохраните текущую работу коммитом или через <code>git stash</code>.

== Просмотр истории ==

=== git log — история коммитов ===

Показывает коммиты, доступные из текущей точки истории: идентификатор, автора, дату и сообщение. Это не только ваши коммиты и не обязательно история всех веток.

<syntaxhighlight lang="bash">
git log
</syntaxhighlight>

Последние десять коммитов в кратком виде:

<syntaxhighlight lang="bash">
git log --oneline -10
</syntaxhighlight>

Граф истории по всем локально известным веткам:

<syntaxhighlight lang="bash">
git log --oneline --graph --decorate --all
</syntaxhighlight>

Если вывод открылся в просмотрщике, для выхода обычно используется клавиша '''q'''.

== Работа с ветками ==

=== git branch — локальные ветки ===

Показывает локальные ветки. Текущая ветка отмечена символом <code>*</code>.

<syntaxhighlight lang="bash">
git branch
</syntaxhighlight>

=== git branch -a — локальные и удалённые ветки ===

Показывает локальные ветки и локально сохранённые ссылки на удалённые ветки. Команда сама не обращается к серверу.

<syntaxhighlight lang="bash">
git branch -a
</syntaxhighlight>

Обновить сведения с <code>origin</code> и убрать устаревшие ссылки на удалённые ветки:

<syntaxhighlight lang="bash">
git fetch origin --prune
git branch -a
</syntaxhighlight>

=== git branch NAME — создать ветку ===

Создаёт новую ветку от текущего коммита, но не переключается на неё.

<syntaxhighlight lang="bash">
git branch feature/new-command
</syntaxhighlight>

=== git checkout NAME — переключиться на ветку ===

Переключает текущую ветку и обновляет файлы рабочей папки.

<syntaxhighlight lang="bash">
git checkout feature/new-command
</syntaxhighlight>

Альтернатива для переключения веток:

<syntaxhighlight lang="bash">
git switch feature/new-command
</syntaxhighlight>

Создать ветку и сразу переключиться на неё одной командой:

<syntaxhighlight lang="bash">
git switch -c feature/new-command
</syntaxhighlight>

Используйте либо создание через <code>git branch</code> с последующим переключением, либо <code>git switch -c</code>. Повторно создавать уже существующую ветку не нужно.

=== git branch -D NAME — принудительно удалить ветку ===

Удаляет локальную ветку без проверки того, что её коммиты уже включены в другую историю.

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

<syntaxhighlight lang="bash">
git branch -d feature/old-task
</syntaxhighlight>

Принудительный вариант из исходной памятки:

<syntaxhighlight lang="bash">
git branch -D feature/old-task
</syntaxhighlight>

'''Важно:''' <code>-D</code> может удалить последнюю ветку, ссылающуюся на нужные коммиты. Используйте его только если содержимое ветки больше не требуется или сохранено в другом месте. Нельзя удалить ветку, которая сейчас используется в рабочем дереве; сначала переключитесь на другую. На сервере ветка этой командой не удаляется.

== Временное сохранение работы ==

=== git stash — отложить незакоммиченные изменения ===

Временно сохраняет изменения отслеживаемых файлов, включая индекс, и возвращает эти файлы к состоянию текущего коммита.

<syntaxhighlight lang="bash">
git stash
</syntaxhighlight>

Сохранить также новые неотслеживаемые файлы и добавить описание:

<syntaxhighlight lang="bash">
git stash push -u -m "Незавершённая работа над статистикой"
</syntaxhighlight>

Посмотреть список сохранений:

<syntaxhighlight lang="bash">
git stash list
</syntaxhighlight>

Вернуть последнее сохранение:

<syntaxhighlight lang="bash">
git stash pop
</syntaxhighlight>

После успешного применения <code>pop</code> удаляет запись из stash. Если возник конфликт, запись сохраняется. Вариант <code>git stash apply</code> применяет изменения, оставляя запись в списке.

'''Примечание:''' обычный <code>git stash</code> не включает новые неотслеживаемые файлы; для них нужен <code>-u</code>. Игнорируемые файлы с <code>-u</code> также не сохраняются. Stash хранится локально и не отправляется обычным <code>git push</code>.

== Пример повседневной работы ==

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

'''1. Перейти в проект и проверить состояние:'''

<syntaxhighlight lang="bash">
cd my-project
git status
</syntaxhighlight>

'''2. При чистой рабочей папке получить обновления:'''

<syntaxhighlight lang="bash">
git pull --ff-only
</syntaxhighlight>

'''3. Изменить файлы, затем проверить правки:'''

<syntaxhighlight lang="bash">
git status
git diff
</syntaxhighlight>

'''4. Подготовить нужные файлы и проверить будущий коммит:'''

<syntaxhighlight lang="bash">
git add README.md
git diff --staged
</syntaxhighlight>

Замените <code>README.md</code> на нужные файлы. Если нужны все изменения, можно выполнить <code>git add .</code> из корня проекта.

'''5. Сохранить и отправить:'''

<syntaxhighlight lang="bash">
git commit -m "Обновлена документация проекта"
git push
git status
</syntaxhighlight>

== Частые вопросы ==

; Почему после git add команда git diff ничего не показывает?
: Изменения уже находятся в индексе. Выполните <code>git diff --staged</code>.

; Почему изменения не появились в GitLab или GitHub после коммита?
: <code>git commit</code> сохраняет изменения локально. Для отправки нужен успешный <code>git push</code> в нужный удалённый репозиторий и ветку.

; Почему новая ветка не стала текущей после git branch?
: Эта команда только создаёт ветку. Переключитесь через <code>git switch</code> или <code>git checkout</code>.

; Почему push сообщает, что нет upstream-ветки?
: Для новой ветки настройте отслеживание командой <code>git push -u origin ИМЯ_ВЕТКИ</code>, заменив имя на фактическое.

; Почему push отклонён с сообщением non-fast-forward?
: На сервере есть история, которой нет в вашей отправляемой ветке. Получите изменения через <code>git fetch</code>, изучите расхождение и согласуйте истории перед повторной отправкой.

== Источник ==

Подготовлено на основе памятки ''Git_useful_commands.pdf''. Описания переведены и уточнены; дополнительные варианты команд, примеры и ответы на частые вопросы добавлены для практического использования.

[[Категория:Git]]
[[Категория:Полезные команды]]

Sis admin linux

2026-09-28T18:52:22Z

Artem:

Небольшие инструкции, полезные команды и практические приёмы администрирования Linux.

'''Все IP-адреса, имена и идентификаторы приведены для примера. Заменяйте их значениями своей инфраструктуры.'''

__TOC__

== SSH-доступ с macOS к LXC-контейнеру Proxmox по ключу ==

=== Назначение ===

Подключение с Mac к LXC-контейнеру по SSH без ввода пароля root.

Публичный ключ добавляется через консоль Proxmox. Знать или создавать пароль root контейнера для этого не требуется.

{| class="wikitable"
! Параметр !! Значение для примера
|-
| ID контейнера || 123
|-
| IP-адрес контейнера || 192.168.2.2
|-
| Пользователь SSH || root
|-
| Клиент || Mac с macOS
|-
| Тип ключа || Ed25519
|}

=== Что необходимо ===

* Административный доступ к консоли узла Proxmox.
* Запущенный LXC-контейнер с работающим SSH-сервером.
* Сетевая доступность контейнера с Mac — через локальную сеть или VPN.
* Разрешённый на SSH-сервере вход root по публичному ключу.

=== 1. Создание ключа на Mac ===

Открыть '''Терминал на Mac''' и выполнить:

<syntaxhighlight lang="bash">
if [ ! -f ~/.ssh/id_ed25519 ]; then
ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519
else
echo "SSH-ключ уже существует."
fi
</syntaxhighlight>

Существующий ключ не перезаписывается.

При создании нового ключа появляются два файла:

{| class="wikitable"
! Файл !! Назначение
|-
| <code>~/.ssh/id_ed25519</code>
| Приватный ключ. Остаётся на Mac. Его нельзя публиковать или передавать.
|-
| <code>~/.ssh/id_ed25519.pub</code>
| Публичный ключ. Добавляется на сервер.
|}

'''Важно:''' параметр <code>-N ""</code> создаёт ключ без парольной фразы. Получивший приватный ключ сможет использовать его для подключения к серверам, где разрешён соответствующий публичный ключ.

Если нужна защита ключа парольной фразой, при отсутствии ключа вместо команды выше выполнить:

<syntaxhighlight lang="bash">
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519
</syntaxhighlight>

Парольную фразу такого ключа можно сохранить в связке ключей macOS — порядок приведён ниже.

=== 2. Копирование публичного ключа ===

'''На Mac''' выполнить:

<syntaxhighlight lang="bash">
cat ~/.ssh/id_ed25519.pub
</syntaxhighlight>

Скопировать всю выведенную строку, начинающуюся с <code>ssh-ed25519</code>.

'''Нужен именно публичный ключ:'''

* Копировать строку целиком, без добавления переносов.
* Не копировать отпечаток <code>SHA256:...</code>.
* Не копировать графический рисунок ключа.
* Не передавать содержимое приватного файла <code>id_ed25519</code>.

Если приватный ключ существует, но файл <code>.pub</code> отсутствует, восстановить публичный ключ:

<syntaxhighlight lang="bash">
ssh-keygen -y -f ~/.ssh/id_ed25519 > ~/.ssh/id_ed25519.pub
</syntaxhighlight>

=== 3. Вход в контейнер через Proxmox ===

В веб-интерфейсе Proxmox открыть '''Shell узла, на котором запущен контейнер'''.

Выполнить, заменив <code>123</code> фактическим ID контейнера:

<syntaxhighlight lang="bash">
pct enter 123
</syntaxhighlight>

Следующие команды выполняются '''внутри контейнера от имени root'''.

=== 4. Добавление ключа в контейнер ===

Подготовить каталог и файл:

<syntaxhighlight lang="bash">
mkdir -p /root/.ssh
touch /root/.ssh/authorized_keys
chown root:root /root/.ssh /root/.ssh/authorized_keys
chmod 700 /root/.ssh
chmod 600 /root/.ssh/authorized_keys
</syntaxhighlight>

В следующей команде заменить <code>ВСТАВЬ_ПУБЛИЧНЫЙ_КЛЮЧ</code> скопированной строкой с Mac, сохранив одинарные кавычки:

<syntaxhighlight lang="bash">
printf '\n%s\n' 'ВСТАВЬ_ПУБЛИЧНЫЙ_КЛЮЧ' >> /root/.ssh/authorized_keys
</syntaxhighlight>

Оператор <code>>></code> добавляет запись в конец файла и сохраняет ранее добавленные ключи.

Начальный перенос строки не позволяет новому ключу склеиться с предыдущей записью. Пустые строки в файле допустимы.

'''Перезапуск SSH после добавления ключа не требуется.'''

=== 5. Проверка подлинности сервера ===

При первом подключении Mac может запросить подтверждение ключа сервера.

Чтобы узнать отпечаток ключа ED25519, выполнить '''внутри контейнера через консоль Proxmox''':

<syntaxhighlight lang="bash">
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

Сравнить отпечаток <code>SHA256:...</code> с тем, который покажет Mac при подключении.

'''Сравнивать нужно ключи одного типа''': в этом примере ED25519.

=== 6. Подключение с Mac ===

'''В Терминале на Mac''' выполнить:

<syntaxhighlight lang="bash">
ssh root@192.168.2.2
</syntaxhighlight>

Заменить адрес на IP своего контейнера.

Если появился запрос подтверждения ключа сервера и отпечаток совпадает с проверенным, ввести:

<syntaxhighlight lang="text">
yes
</syntaxhighlight>

При успешной настройке откроется оболочка контейнера без запроса пароля root.

Для завершения подключения:

<syntaxhighlight lang="bash">
exit
</syntaxhighlight>

=== 7. Сохранение парольной фразы ключа в macOS ===

'''Этот шаг нужен только для ключа, защищённого парольной фразой.'''

Запрос <code>Enter passphrase for key</code> относится к приватному ключу на Mac, а не к паролю root контейнера.

На Mac выполнить:

<syntaxhighlight lang="bash">
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
</syntaxhighlight>

Ввести парольную фразу ключа.

Для автоматического использования связки ключей добавить настройки из следующего раздела.

=== 8. Короткая команда подключения ===

Можно назначить подключению понятное имя, например <code>my-container</code>.

'''На Mac''' открыть файл настроек SSH:

<syntaxhighlight lang="bash">
mkdir -p ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/config
</syntaxhighlight>

Добавить блок, заменив адрес на нужный:

<syntaxhighlight lang="text">
Host my-container
HostName 192.168.2.2
User root
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
AddKeysToAgent yes
UseKeychain yes
</syntaxhighlight>

Если блок <code>Host my-container</code> уже существует, изменить его вместо создания дубликата. Если в файле есть общий блок <code>Host *</code>, этот отдельный блок разместить перед ним.

Сохранить файл в nano:

# Нажать <code>Control + O</code>.
# Нажать <code>Enter</code>.
# Нажать <code>Control + X</code>.

Установить права:

<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/config
</syntaxhighlight>

Теперь подключение выполняется короткой командой:

<syntaxhighlight lang="bash">
ssh my-container
</syntaxhighlight>

=== Диагностика ===

==== Запрашивается пароль root ====

Авторизация по ключу не завершилась успешно.

На Mac выполнить подключение с явным указанием ключа и подробным выводом:

<syntaxhighlight lang="bash">
ssh -v -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.2.2
</syntaxhighlight>

Внутри контейнера через консоль Proxmox проверить:

<syntaxhighlight lang="bash">
ls -ld /root/.ssh
ls -l /root/.ssh/authorized_keys
</syntaxhighlight>

Ожидаемые параметры:

{| class="wikitable"
! Объект !! Права !! Владелец
|-
| <code>/root/.ssh</code>
| <code>700</code> — <code>drwx------</code>
| root
|-
| <code>/root/.ssh/authorized_keys</code>
| <code>600</code> — <code>-rw-------</code>
| root
|}

Проверить, что:

* В файле находится публичный ключ с нужного Mac.
* Ключ записан одной строкой.
* Указаны правильные IP-адрес и пользователь.
* SSH-сервер разрешает авторизацию по ключу и вход root по ключу.

==== Connection refused ====

Соединение отклонено.

Проверить правильность адреса, работу SSH-сервера и порт подключения. Также причиной может быть правило межсетевого экрана, отклоняющее соединение.

==== Connection timed out ====

Сервер не ответил за отведённое время.

Проверить:

* Запущен ли контейнер.
* Доступна ли его сеть с Mac.
* Подключён ли нужный VPN.
* Не блокируется ли SSH-порт межсетевым экраном.

==== REMOTE HOST IDENTIFICATION HAS CHANGED ====

Сохранённый на Mac ключ сервера отличается от текущего.

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

Сначала проверить новый отпечаток через доверенную консоль Proxmox. Не удалять старую запись без проверки причины изменения.

=== Примечания ===

* Настройка сохраняется после перезагрузки Mac и контейнера.
* Для каждого дополнительного компьютера можно создать собственный ключ и добавить его публичную часть отдельной строкой в <code>authorized_keys</code>.
* Чтобы отозвать доступ конкретного ключа, удалить соответствующую строку из <code>authorized_keys</code>. Уже открытые SSH-сеансы при этом не завершаются.
* Добавление ключа само по себе не отключает парольную авторизацию SSH.
* Приватные ключи, пароли и другие секреты не должны попадать в публичную документацию.



== Создание службы systemd: автозапуск и перезапуск программы ==

=== Что такое юнит ===

Юнит — объект, которым управляет systemd. Юнит с расширением <code>.service</code> описывает службу: какую программу запустить, под каким пользователем и что делать при её завершении.

Служба позволяет:

* Запускать программу при загрузке системы.
* Продолжать работу после отключения от SSH.
* Автоматически перезапускать программу после сбоя.
* Просматривать состояние и журналы стандартными командами.

Ниже приведён рабочий учебный пример для Debian и Ubuntu с systemd. Служба будет записывать сообщение в журнал каждые 30 секунд.

'''Команды выполняются на том сервере или внутри того контейнера, где должна работать программа, от имени root.'''

=== 1. Создание пользователя службы ===

Для программы, которой не нужны административные права, создать отдельного системного пользователя:

<syntaxhighlight lang="bash">
id demo-service >/dev/null 2>&1 || useradd \
--system \
--user-group \
--home-dir /opt/demo-service \
--no-create-home \
--shell /usr/sbin/nologin \
demo-service
</syntaxhighlight>

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

Создать каталог программы:

<syntaxhighlight lang="bash">
install -d -o root -g root -m 755 /opt/demo-service
</syntaxhighlight>

=== 2. Создание программы для проверки ===

Открыть файл:

<syntaxhighlight lang="bash">
nano /opt/demo-service/run.sh
</syntaxhighlight>

Вставить:

<syntaxhighlight lang="bash">
#!/bin/bash

while true; do
printf '%s — служба работает\n' "$(date --iso-8601=seconds)"
sleep 30
done
</syntaxhighlight>

Сохранить: <code>Ctrl + O</code>, <code>Enter</code>, <code>Ctrl + X</code>.

Установить права:

<syntaxhighlight lang="bash">
chown root:root /opt/demo-service/run.sh
chmod 755 /opt/demo-service/run.sh
</syntaxhighlight>

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

=== 3. Создание юнита ===

Открыть новый файл:

<syntaxhighlight lang="bash">
nano /etc/systemd/system/demo-service.service
</syntaxhighlight>

Вставить:

<syntaxhighlight lang="ini">
[Unit]
Description=Example background service
StartLimitIntervalSec=60
StartLimitBurst=5

[Service]
Type=exec
User=demo-service
Group=demo-service
WorkingDirectory=/opt/demo-service
ExecStart=/bin/bash /opt/demo-service/run.sh
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

=== Пояснение параметров ===

{| class="wikitable"
! Параметр !! Назначение
|-
| <code>[Unit]</code>
| Описание службы, зависимости и ограничения запуска.
|-
| <code>Description</code>
| Название, которое отображается в состоянии службы.
|-
| <code>StartLimitIntervalSec=60</code>
| Интервал учёта частых запусков — 60 секунд.
|-
| <code>StartLimitBurst=5</code>
| Допускается до пяти запусков за указанный интервал. Ограничивает бесконечные попытки запуска при ошибке.
|-
| <code>[Service]</code>
| Параметры процесса.
|-
| <code>Type=exec</code>
| systemd ожидает успешного запуска исполняемого файла. Это ещё не означает, что приложение полностью готово обслуживать запросы.
|-
| <code>User</code> и <code>Group</code>
| Пользователь и группа процесса.
|-
| <code>WorkingDirectory</code>
| Рабочий каталог программы. Должен существовать и быть доступен пользователю службы.
|-
| <code>ExecStart</code>
| Команда запуска с абсолютными путями.
|-
| <code>Restart=on-failure</code>
| Перезапуск после ошибки или аварийного завершения. Штатное завершение с кодом 0 не вызывает перезапуск.
|-
| <code>RestartSec=5</code>
| Пауза перед перезапуском — пять секунд.
|-
| <code>StandardOutput=journal</code>
| Обычный вывод программы направляется в журнал.
|-
| <code>StandardError=journal</code>
| Ошибки программы направляются в журнал.
|-
| <code>[Install]</code>
| Настройки включения автозапуска.
|-
| <code>WantedBy=multi-user.target</code>
| Позволяет включить службу в обычный многопользовательский режим загрузки.
|}

=== 4. Проверка и запуск ===

Проверить юнит:

<syntaxhighlight lang="bash">
systemd-analyze verify /etc/systemd/system/demo-service.service
</syntaxhighlight>

Если обнаружены ошибки в созданном файле — исправить их до запуска.

Перечитать юниты, включить автозапуск и сразу запустить службу:

<syntaxhighlight lang="bash">
systemctl daemon-reload
systemctl enable --now demo-service.service
</syntaxhighlight>

Посмотреть состояние:

<syntaxhighlight lang="bash">
systemctl status demo-service.service --no-pager -l
</syntaxhighlight>

Ожидаемое состояние:

<syntaxhighlight lang="text">
Active: active (running)
</syntaxhighlight>

=== 5. Просмотр журнала ===

Последние 50 записей:

<syntaxhighlight lang="bash">
journalctl -u demo-service.service -n 50 --no-pager
</syntaxhighlight>

Наблюдение за новыми записями:

<syntaxhighlight lang="bash">
journalctl -u demo-service.service -f
</syntaxhighlight>

Нажатие <code>Ctrl + C</code> завершает просмотр журнала, но не останавливает службу.

=== Основные команды управления ===

{| class="wikitable"
! Команда !! Действие
|-
| <code>systemctl start demo-service</code>
| Запустить.
|-
| <code>systemctl stop demo-service</code>
| Остановить. Настройка Restart не отменяет ручную остановку.
|-
| <code>systemctl restart demo-service</code>
| Перезапустить.
|-
| <code>systemctl status demo-service</code>
| Посмотреть состояние.
|-
| <code>systemctl enable demo-service</code>
| Включить автозапуск, не запуская службу немедленно.
|-
| <code>systemctl disable demo-service</code>
| Отключить автозапуск, не останавливая текущий процесс.
|-
| <code>systemctl disable --now demo-service</code>
| Отключить автозапуск и остановить службу.
|-
| <code>systemctl cat demo-service</code>
| Показать юнит и дополнительные настройки.
|}

=== Как адаптировать под свою программу ===

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

Например, для Python-приложения с виртуальным окружением:

<syntaxhighlight lang="ini">
WorkingDirectory=/opt/my-app
ExecStart=/opt/my-app/.venv/bin/python -u /opt/my-app/main.py
</syntaxhighlight>

Виртуальное окружение и файл программы должны существовать. Активировать окружение командой <code>source</code> не требуется.

Параметр <code>-u</code> отключает буферизацию стандартных потоков Python, чтобы сообщения быстрее попадали в журнал.

'''Особенности:'''

* Программа должна работать на переднем плане: не добавляйте <code>&</code>, <code>nohup</code> или собственный переход в фон.
* <code>ExecStart</code> не является обычной командной строкой оболочки: конструкции <code>|</code>, <code>></code> и <code>&&</code> не выполняются как в Bash.
* Сложную последовательность команд удобнее оформить отдельным скриптом.
* Пользователю службы нужны права чтения программы и записи только в необходимые каталоги данных.
* Переменные из интерактивного SSH-сеанса автоматически в службу не передаются.

Для программы, которой при запуске нужна настроенная сеть, в секцию <code>[Unit]</code> можно добавить:

<syntaxhighlight lang="ini">
Wants=network-online.target
After=network-online.target
</syntaxhighlight>

Это не гарантирует доступность Интернета или внешнего API. Приложение должно самостоятельно повторять неудачные подключения.

=== Применение изменений ===

После изменения юнита:

<syntaxhighlight lang="bash">
systemd-analyze verify /etc/systemd/system/demo-service.service
systemctl daemon-reload
systemctl restart demo-service.service
systemctl status demo-service.service --no-pager -l
</syntaxhighlight>

Если изменён только код программы, обычно достаточно перезапуска службы.

Если сработало ограничение частых запусков, сначала исправить причину по журналу, затем выполнить:

<syntaxhighlight lang="bash">
systemctl reset-failed demo-service.service
systemctl start demo-service.service
</syntaxhighlight>

== Отключение парольного входа по SSH ==

=== Назначение ===

Разрешить новые SSH-подключения только по публичному ключу.

Имя пользователя по-прежнему указывается, например <code>root@192.168.2.2</code>. Меняется способ подтверждения доступа.

Настройка не удаляет системные пароли и не меняет правила входа через локальную консоль или использования sudo.

'''Пример предназначен для Debian и Ubuntu с OpenSSH. Команды сервера выполняются от имени root.'''

=== 1. Проверка входа по ключу ===

'''Не закрывайте текущий сеанс до завершения всех проверок.''' Держите доступной консоль Proxmox или другую независимую консоль сервера.

В новом терминале Mac проверить вход с запретом перехода к парольной авторизации:

<syntaxhighlight lang="bash">
ssh \
-o ControlMaster=no \
-o ControlPath=none \
-o PreferredAuthentications=publickey \
-o PasswordAuthentication=no \
-o KbdInteractiveAuthentication=no \
-o IdentitiesOnly=yes \
-i ~/.ssh/id_ed25519 \
root@192.168.2.2
</syntaxhighlight>

Если вход не работает, сначала исправить авторизацию по ключу.

Если сервером пользуются несколько администраторов, заранее настроить ключи для каждого.

=== 2. Резервная копия конфигурации ===

На сервере выполнить:

<syntaxhighlight lang="bash">
cp -a /etc/ssh/sshd_config \
"/etc/ssh/sshd_config.backup-$(date +%Y%m%d-%H%M%S)"
</syntaxhighlight>

=== 3. Изменение настроек ===

Открыть:

<syntaxhighlight lang="bash">
nano /etc/ssh/sshd_config
</syntaxhighlight>

Добавить в самое начало файла, перед директивами <code>Include</code> и блоками <code>Match</code>:

<syntaxhighlight lang="text">
PubkeyAuthentication yes
PasswordAuthentication no
KbdInteractiveAuthentication no
AuthenticationMethods publickey
</syntaxhighlight>

{| class="wikitable"
! Параметр !! Значение
|-
| <code>PubkeyAuthentication yes</code>
| Разрешить авторизацию по публичному ключу.
|-
| <code>PasswordAuthentication no</code>
| Запретить обычную парольную авторизацию.
|-
| <code>KbdInteractiveAuthentication no</code>
| Запретить интерактивную авторизацию, которая также может запрашивать пароль или одноразовый код.
|-
| <code>AuthenticationMethods publickey</code>
| Оставить только авторизацию по публичному ключу.
|}

'''Этот вариант также исключает другие способы входа и схемы «ключ плюс одноразовый код».'''

Для большинства параметров OpenSSH используется первое полученное значение. Блоки <code>Match</code> могут задавать отдельные правила для пользователей и адресов, поэтому нужна проверка итоговой конфигурации.

Параметр <code>PermitRootLogin</code> без необходимости не менять. Значение <code>no</code> запрещает root любой SSH-вход; <code>prohibit-password</code> допускает вход root по ключу.

=== 4. Проверка перед применением ===

Проверить синтаксис:

<syntaxhighlight lang="bash">
/usr/sbin/sshd -t
</syntaxhighlight>

Отсутствие вывода при успешном завершении означает, что проверка пройдена. При ошибке конфигурацию не применять.

Посмотреть общие итоговые параметры:

<syntaxhighlight lang="bash">
/usr/sbin/sshd -T | grep -E '^(pubkeyauthentication|passwordauthentication|kbdinteractiveauthentication|authenticationmethods) '
</syntaxhighlight>

Ожидаемые значения:

<syntaxhighlight lang="text">
pubkeyauthentication yes
passwordauthentication no
kbdinteractiveauthentication no
authenticationmethods publickey
</syntaxhighlight>

При наличии <code>Match</code> дополнительно проверить конкретное подключение:

<syntaxhighlight lang="bash">
/usr/sbin/sshd -T \
-C user=root,addr=192.168.2.50,host=mac-client,laddr=192.168.2.2,lport=22 \
| grep -E '^(pubkeyauthentication|passwordauthentication|kbdinteractiveauthentication|authenticationmethods|permitrootlogin) '
</syntaxhighlight>

В примере:

* <code>user</code> — пользователь сервера.
* <code>addr</code> — адрес клиента, видимый серверу.
* <code>host</code> — имя клиента для правил Match Host.
* <code>laddr</code> и <code>lport</code> — адрес и порт сервера.

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

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

=== 5. Применение ===

Для стандартной службы SSH в Debian и Ubuntu:

<syntaxhighlight lang="bash">
/usr/sbin/sshd -t && systemctl reload ssh.service
</syntaxhighlight>

В системах, где служба называется <code>sshd.service</code>, использовать:

<syntaxhighlight lang="bash">
/usr/sbin/sshd -t && systemctl reload sshd.service
</syntaxhighlight>

Выполняется только вариант с фактическим именем службы.

Перечитывание конфигурации штатно сохраняет открытые сеансы.

=== 6. Проверка нового подключения ===

Не закрывая старый сеанс, в новом терминале Mac повторить команду проверки входа по ключу из первого шага.

Затем проверить отказ для парольных способов:

<syntaxhighlight lang="bash">
ssh \
-o ControlMaster=no \
-o ControlPath=none \
-o PubkeyAuthentication=no \
-o PreferredAuthentications=password,keyboard-interactive \
root@192.168.2.2
</syntaxhighlight>

Ожидаемый результат — отказ, обычно:

<syntaxhighlight lang="text">
Permission denied (publickey).
</syntaxhighlight>

Пароль учётной записи запрашиваться не должен.

'''Старый сеанс можно закрыть после успешного нового входа по ключу и проверки отказа для пароля.'''

=== Восстановление при ошибке ===

Использовать оставленный открытым сеанс или консоль Proxmox.

Найти резервную копию:

<syntaxhighlight lang="bash">
ls -lt /etc/ssh/sshd_config.backup-*
</syntaxhighlight>

Восстановить нужную копию, указав её фактическое имя:

<syntaxhighlight lang="bash">
cp -a /etc/ssh/sshd_config.backup-YYYYMMDD-HHMMSS /etc/ssh/sshd_config
</syntaxhighlight>

Проверить и применить:

<syntaxhighlight lang="bash">
/usr/sbin/sshd -t && systemctl reload ssh.service
</syntaxhighlight>

Если служба называется <code>sshd.service</code>, заменить её имя в команде.

=== Важно помнить ===

* Парольная фраза приватного ключа на Mac может запрашиваться и после отключения паролей на сервере — это отдельная защита самого ключа.
* Настройка распространяется также на SFTP и SCP через этот SSH-сервер.
* Не удаляйте пароль пользователя и не блокируйте учётную запись ради отключения парольного SSH-входа: достаточно настроек SSH.

== Проверка версии и обновление программы из GitLab ==

=== Назначение ===

Проверить, появились ли новые изменения в GitLab, сравнить их с установленным на сервере кодом и обновить программу.

Инструкция предназначена для приложения, которое уже установлено из Git-репозитория и запускается через systemd.

'''Все пути, имена и адреса приведены для примера.'''

{| class="wikitable"
! Параметр !! Пример
|-
| Каталог программы || <code>/opt/my-app</code>
|-
| Репозиторий || <code>git@gitlab.example.com:team/my-app.git</code>
|-
| Удалённый репозиторий || <code>origin</code>
|-
| Рабочая ветка || <code>main</code>
|-
| Служба || <code>my-app.service</code>
|}

Команды Git выполнять от имени владельца рабочей копии. Для управления системной службой нужны права root или sudo.

'''Команды выполняются поэтапно. При ошибке не переходить к следующему шагу.'''

=== Основные понятия ===

{| class="wikitable"
! Термин !! Значение
|-
| Коммит
| Зафиксированное состояние кода с уникальным идентификатором.
|-
| Ветка
| Последовательность разработки, например <code>main</code> или <code>stable</code>.
|-
| HEAD
| Текущий коммит рабочей копии.
|-
| origin
| Обычно так называется подключённый удалённый репозиторий.
|-
| origin/main
| Последнее полученное локально состояние ветки main из origin. До fetch сведения могут быть устаревшими.
|-
| Тег
| Именованная отметка версии, например <code>v1.4.0</code>.
|-
| Release
| Опубликованный выпуск в GitLab, обычно связанный с тегом и описанием изменений.
|}

'''Новый коммит в ветке не обязательно означает новый стабильный выпуск.''' Перед установкой проверить назначение ветки, описание выпуска и результаты CI в GitLab.

=== 1. Проверка каталога и службы ===

Перейти в каталог программы:

<syntaxhighlight lang="bash">
cd /opt/my-app
</syntaxhighlight>

Убедиться, что открыт нужный репозиторий:

<syntaxhighlight lang="bash">
pwd
git rev-parse --show-toplevel
git remote -v
</syntaxhighlight>

Проверить, откуда systemd запускает программу:

<syntaxhighlight lang="bash">
sudo systemctl show my-app.service --no-pager \
-p WorkingDirectory \
-p ExecStart \
-p User
</syntaxhighlight>

Пути должны соответствовать обновляемому приложению.

Если служба запускает Docker-контейнер, установленный пакет или собранный файл из другого каталога, одного обновления исходников недостаточно. Нужна предусмотренная проектом сборка и установка.

'''Не публикуйте вывод git remote -v, если в адрес репозитория встроен токен доступа.'''

=== 2. Определение текущей версии ===

Выполнить:

<syntaxhighlight lang="bash">
git branch --show-current
git log -1 --format='%h %ci %s'
git rev-parse HEAD
git status --short --branch
</syntaxhighlight>

Команды показывают:

* Текущую ветку.
* Последний коммит, дату и описание.
* Полный идентификатор коммита.
* Состояние рабочей копии.

Если имя ветки не выводится, репозиторий находится в состоянии detached HEAD — например, после установки определённого тега. Основной сценарий ниже рассчитан на ветку main.

'''Коммит в каталоге не доказывает, что запущенный процесс уже использует этот код.''' После обновления обычно требуется перезапуск или отдельный этап развёртывания.

=== 3. Проверка локальных изменений ===

Выполнить:

<syntaxhighlight lang="bash">
git status --porcelain
</syntaxhighlight>

Пустой вывод означает отсутствие отслеживаемых изменений и неотслеживаемых файлов. Игнорируемые файлы, например .env, эта команда не показывает.

Типичные обозначения:

{| class="wikitable"
! Обозначение !! Значение
|-
| <code>M</code>
| Файл изменён.
|-
| <code>A</code>
| Новый файл добавлен в индекс.
|-
| <code>D</code>
| Файл удалён.
|-
| <code>??</code>
| Файл не отслеживается Git.
|}

Если есть изменения, сначала выяснить их назначение:

<syntaxhighlight lang="bash">
git diff
git diff --cached
</syntaxhighlight>

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

'''Не использовать git reset --hard или git clean -fd как универсальное исправление: они могут уничтожить нужные изменения и файлы.'''

=== 4. Получение сведений из GitLab ===

Для примера с веткой main выполнить:

<syntaxhighlight lang="bash">
git fetch origin refs/heads/main:refs/remotes/origin/main
</syntaxhighlight>

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

Если GitLab недоступен или авторизация завершилась ошибкой, остановиться: сравнение со старым origin/main не подтверждает актуальность сервера.

Для приватного репозитория на сервере нужен доступ на чтение, например отдельный SSH Deploy Key. Ключ для входа с Mac на сервер сам по себе не предоставляет серверу доступ к GitLab.

=== 5. Сравнение сервера с GitLab ===

Показать количество уникальных коммитов с каждой стороны:

<syntaxhighlight lang="bash">
git rev-list --left-right --count HEAD...origin/main
</syntaxhighlight>

{| class="wikitable"
! Результат !! Значение !! Действие
|-
| <code>0 0</code>
| История совпадает.
| Обновление кода не требуется.
|-
| <code>0 3</code>
| В GitLab есть три новых коммита.
| Можно изучать обновление.
|-
| <code>2 0</code>
| На сервере есть два коммита, которых нет в origin/main.
| Выяснить происхождение локальных коммитов.
|-
| <code>2 3</code>
| Истории разошлись.
| Разобраться с ветками; обычное обновление не выполнять.
|}

Первое число относится к HEAD сервера, второе — к origin/main.

'''Продолжать основной сценарий следует только при результате 0 N, где N больше нуля, и при текущей ветке main.'''

=== 6. Просмотр состава обновления ===

Зафиксировать идентификатор проверяемой версии:

<syntaxhighlight lang="bash">
UPDATE_COMMIT=$(git rev-parse origin/main)
printf '%s\n' "$UPDATE_COMMIT"
</syntaxhighlight>

Следующие шаги выполнять в том же терминале. После переподключения переменную нужно задать снова.

Посмотреть новые коммиты:

<syntaxhighlight lang="bash">
git --no-pager log --oneline HEAD.."$UPDATE_COMMIT"
</syntaxhighlight>

Посмотреть список и объём изменений:

<syntaxhighlight lang="bash">
git --no-pager diff --stat HEAD "$UPDATE_COMMIT"
git --no-pager diff --name-status HEAD "$UPDATE_COMMIT"
</syntaxhighlight>

Посмотреть изменения кода:

<syntaxhighlight lang="bash">
git diff HEAD "$UPDATE_COMMIT"
</syntaxhighlight>

Для выхода из просмотра нажать <code>q</code>.

Перед установкой проверить:

* Изменения зависимостей и требования к версии языка.
* Новые настройки и переменные окружения.
* Изменения юнита systemd.
* Необходимость сборки.
* Миграции базы данных.
* Инструкцию обновления и совместимость со старой версией.

Обновляться будем до сохранённого UPDATE_COMMIT — именно до просмотренной версии.

=== 7. Подготовка отката ===

Создать локальную ветку, сохраняющую текущий коммит:

<syntaxhighlight lang="bash">
BACKUP_BRANCH="backup/before-update-$(date +%Y%m%d-%H%M%S)"
git branch "$BACKUP_BRANCH" HEAD
printf 'Ветка для отката: %s\n' "$BACKUP_BRANCH"
</syntaxhighlight>

Записать её имя.

'''Эта ветка сохраняет только версию кода в Git.''' Она не является резервной копией базы данных, загруженных файлов, .env или виртуального окружения.

До обновления отдельно обеспечить восстановление:

* Конфигурации и секретов.
* Базы данных штатными средствами используемой СУБД.
* Пользовательских файлов.
* Зависимостей приложения.

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

=== 8. Остановка и обновление кода ===

Этот способ предполагает короткий простой приложения.

Ещё раз проверить:

<syntaxhighlight lang="bash">
git branch --show-current
git status --porcelain
</syntaxhighlight>

Ожидается ветка main и пустой вывод второй команды.

Остановить службу:

<syntaxhighlight lang="bash">
sudo systemctl stop my-app.service
sudo systemctl is-active my-app.service
</syntaxhighlight>

Ожидаемый ответ — <code>inactive</code>. Для неактивной службы команда is-active возвращает ненулевой код, это нормально.

Если приложение запускается также таймером, сокетом или внешним монитором, на время обновления приостановить и этот механизм.

Обновить рабочую копию:

<syntaxhighlight lang="bash">
git merge --ff-only "$UPDATE_COMMIT"
</syntaxhighlight>

Параметр <code>--ff-only</code> разрешает только прямое продвижение по истории без создания merge-коммита. При расхождении веток команда откажется выполнять слияние.

'''При ошибке не продолжать установку и не запускать непроверенную версию.'''

=== 9. Зависимости, сборка и проверки ===

Выполнить шаги, предусмотренные документацией проекта. Универсальной команды установки для всех программ нет.

Например, для Python-проекта, использующего виртуальное окружение и requirements.txt:

<syntaxhighlight lang="bash">
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m pip check
</syntaxhighlight>

Для проверки синтаксиса Python, если исходники находятся в каталоге app:

<syntaxhighlight lang="bash">
.venv/bin/python -m compileall -q app
</syntaxhighlight>

Заменить каталог app реальным каталогом исходников.

Проверка синтаксиса не заменяет тестирование функций программы. Если проект использует lock-файл или другой менеджер зависимостей, применять его штатную процедуру.

'''При ошибке установки, сборки, тестов или миграции остановиться.'''

Миграции базы выполнять только по инструкции проекта и после резервного копирования.

Если изменился установленный юнит systemd, проверить и применить его отдельно:

<syntaxhighlight lang="bash">
sudo systemd-analyze verify /etc/systemd/system/my-app.service
sudo systemctl daemon-reload
</syntaxhighlight>

Изменение копии юнита в Git-репозитории само по себе не обновляет файл в /etc/systemd/system.

=== 10. Запуск и проверка ===

После успешного выполнения подготовительных шагов запустить приложение:

<syntaxhighlight lang="bash">
sudo systemctl start my-app.service
sudo systemctl status my-app.service --no-pager -l
</syntaxhighlight>

Посмотреть свежие журналы:

<syntaxhighlight lang="bash">
sudo journalctl -u my-app.service --since "5 minutes ago" --no-pager
</syntaxhighlight>

Сравнить установленный коммит с выбранным:

<syntaxhighlight lang="bash">
git rev-parse HEAD
printf '%s\n' "$UPDATE_COMMIT"
</syntaxhighlight>

Идентификаторы должны совпасть.

Проверить программу по назначению:

* Для бота — отправить тестовую команду.
* Для сайта — открыть страницу и проверить основную операцию.
* Для API — выполнить предусмотренную проверку состояния.
* Для фоновой службы — убедиться, что она обрабатывает задания.

'''Состояние active (running) подтверждает наличие процесса, но не гарантирует работоспособность приложения.'''

=== 11. Откат к предыдущему коду ===

Откат выполнять только после оценки совместимости старого кода с текущей базой и зависимостями.

Остановить службу:

<syntaxhighlight lang="bash">
sudo systemctl stop my-app.service
</syntaxhighlight>

Найти сохранённую ветку:

<syntaxhighlight lang="bash">
git branch --list 'backup/before-update-*'
git status --porcelain
</syntaxhighlight>

При наличии новых локальных изменений сначала сохранить и изучить их.

Переключиться на фактическую резервную ветку:

<syntaxhighlight lang="bash">
git switch backup/before-update-YYYYMMDD-HHMMSS
</syntaxhighlight>

Подставить имя из списка. Команда меняет рабочие файлы на сохранённую версию, не переписывая ветку main.

Затем:

# Восстановить совместимые зависимости и конфигурацию.
# При необходимости выполнить предусмотренное восстановление базы.
# Проверить приложение.
# Запустить службу и посмотреть журнал.

<syntaxhighlight lang="bash">
sudo systemctl start my-app.service
sudo systemctl status my-app.service --no-pager -l
sudo journalctl -u my-app.service -n 50 --no-pager
</syntaxhighlight>

'''После отката текущей становится резервная ветка.''' Перед следующим обновлением нужно осознанно выбрать дальнейшую ветку или выпуск.

Повторная установка старого requirements.txt не гарантирует точное восстановление окружения: новые лишние пакеты могут остаться, а незакреплённые версии — измениться.

=== Если новая версия опубликована тегом ===

Если проект выпускает стабильные версии тегами, ориентироваться на указанный в GitLab Release тег, а не на последний коммит main.

Получить теги:

<syntaxhighlight lang="bash">
git fetch origin --tags
git tag --list --sort=-version:refname
</syntaxhighlight>

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

Для выбранного примера:

<syntaxhighlight lang="bash">
git show --no-patch v1.4.0
git diff --stat HEAD v1.4.0
git log --oneline HEAD..v1.4.0
</syntaxhighlight>

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

<syntaxhighlight lang="bash">
git switch --detach v1.4.0
</syntaxhighlight>

Это отдельный вариант установки. После него выполнить зависимости, сборку и проверки согласно выпуску.

Состояние detached HEAD здесь ожидаемо: сервер закреплён за конкретным коммитом версии.

=== Частые ошибки ===

==== not a git repository ====

Команда выполнена не в каталоге репозитория:

<syntaxhighlight lang="bash">
cd /opt/my-app
git status
</syntaxhighlight>

==== Permission denied (publickey) при fetch ====

GitLab не принял SSH-ключ сервера.

Проверить адрес origin и доступ серверного ключа к нужному проекту. Не переносить приватный ключ с личного компьютера без необходимости.

==== Your local changes would be overwritten ====

На сервере есть изменения файлов, которым мешает обновление.

Посмотреть git status и git diff. Не применять принудительный сброс без понимания, какие данные будут потеряны.

==== Not possible to fast-forward ====

Истории разошлись. Проверить:

<syntaxhighlight lang="bash">
git log --oneline --graph --decorate --max-count=30 HEAD origin/main
</syntaxhighlight>

Разобраться с локальными коммитами и изменениями ветки в GitLab до обновления.

==== Код обновлён, поведение старое ====

Проверить:

* Был ли перезапущен нужный процесс.
* Из какого каталога запускается служба.
* Не требуется ли сборка.
* Не работает ли другая копия приложения.
* Не запускается ли приложение из Docker-образа или установленного пакета.

=== Короткая проверка наличия обновлений ===

Следующий блок только получает сведения и сравнивает версии. Он не обновляет рабочие файлы и не перезапускает программу:

<syntaxhighlight lang="bash">
(
cd /opt/my-app || exit 1

git status --short --branch
git log -1 --oneline

git fetch origin refs/heads/main:refs/remotes/origin/main || exit 1

git rev-list --left-right --count HEAD...origin/main
git --no-pager log --oneline HEAD..origin/main
git --no-pager diff --stat HEAD origin/main
)
</syntaxhighlight>

== Автоматическое обновление программы из GitLab каждые 3 минуты ==

=== Назначение ===

Сервер периодически проверяет выбранную ветку GitLab и устанавливает новые коммиты.

Если изменений нет, программа продолжает работать без перезапуска.

При наличии обновления выполняются:

# Проверка состояния репозитория.
# Проверка допустимости изменений.
# Сохранение предыдущего коммита.
# Остановка приложения.
# Обновление кода.
# Проверка синтаксиса Python.
# Запуск и проверка работоспособности.
# Попытка отката при ошибке.

'''Пример предназначен для Debian и Ubuntu с systemd.'''

=== Область применения ===

Этот вариант обновляет код Python-приложения в существующем каталоге. Во время установки будет короткий простой.

Он не устанавливает зависимости, не выполняет миграции базы, не пересобирает Docker-образы и не меняет системные настройки.

Изменения за пределами разрешённых файлов требуют ручного обновления.

'''Откат кода не отменяет изменения данных, которые успела сделать программа.''' Автоматизировать таким способом следует только совместимые обновления без изменения формата данных и обязательных миграций.

=== Пример конфигурации ===

{| class="wikitable"
! Параметр !! Значение
|-
| Каталог приложения || <code>/opt/my-app</code>
|-
| Владелец репозитория || <code>myapp</code>
|-
| Ветка для установки || <code>main</code>
|-
| Удалённый репозиторий || <code>origin</code>
|-
| Служба приложения || <code>my-app.service</code>
|-
| Виртуальное окружение || <code>/opt/my-app/.venv</code>
|-
| Исходники Python || <code>app/</code> и необязательный <code>main.py</code>
|-
| Проверка состояния || <code>http://127.0.0.1:8000/health</code>
|-
| Интервал || 3 минуты после завершения предыдущей проверки
|}

'''Все значения условные. Пользователь myapp, репозиторий, виртуальное окружение и служба должны уже существовать.'''

Ветка для автоматической установки должна содержать только одобренные изменения. В GitLab следует ограничить прямую запись в неё и настроить прохождение CI перед слиянием.

Сам скрипт не проверяет статус pipeline GitLab: публикация коммита в выбранной ветке считается разрешением на установку.

=== 1. Подготовка ===

Команды настройки выполнять от имени root на сервере приложения.

Установить необходимые инструменты:

<syntaxhighlight lang="bash">
apt update
apt install -y git curl util-linux
</syntaxhighlight>

Проверить службу:

<syntaxhighlight lang="bash">
systemctl show my-app.service --no-pager \
-p User \
-p WorkingDirectory \
-p ExecStart

systemctl status my-app.service --no-pager -l
</syntaxhighlight>

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

Проверить репозиторий от имени его владельца:

<syntaxhighlight lang="bash">
runuser -u myapp -- git -C /opt/my-app status --short --branch
runuser -u myapp -- git -C /opt/my-app branch --show-current
</syntaxhighlight>

Ожидается ветка main без локальных изменений и неотслеживаемых файлов.

Логи, виртуальное окружение и локальные настройки должны находиться вне отслеживаемого кода либо быть корректно исключены через .gitignore.

=== 2. Доступ сервера к GitLab ===

У пользователя myapp должен быть настроен доступ на чтение репозитория.

Для SSH можно использовать отдельный Deploy Key с правами только на чтение. Ключ сервера GitLab должен быть заранее проверен и сохранён в known_hosts этого пользователя.

Проверить доступ без интерактивного запроса пароля:

<syntaxhighlight lang="bash">
runuser -u myapp -- env \
GIT_TERMINAL_PROMPT=0 \
GIT_SSH_COMMAND="ssh -o BatchMode=yes -o ConnectTimeout=10" \
git -C /opt/my-app ls-remote --exit-code origin refs/heads/main
</syntaxhighlight>

Команда должна вывести идентификатор ветки и завершиться успешно.

Не отключать проверку ключа SSH-сервера ради автоматизации.

=== 3. Проверка состояния приложения ===

В примере приложение предоставляет адрес:

<syntaxhighlight lang="text">
http://127.0.0.1:8000/health
</syntaxhighlight>

Проверить:

<syntaxhighlight lang="bash">
curl --noproxy '*' --max-time 5 \
-sS -o /dev/null -w '%{http_code}\n' \
http://127.0.0.1:8000/health
</syntaxhighlight>

Ожидается HTTP 200.

'''Этот endpoint должен существовать в приложении и отражать его готовность к работе.''' Не подставляйте произвольную страницу только потому, что она отвечает кодом 200.

Для Telegram-бота без HTTP endpoint функцию проверки в скрипте нужно заменить реальной проверкой готовности бота. Одного состояния active недостаточно.

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

Открыть:

<syntaxhighlight lang="bash">
nano /usr/local/sbin/my-app-update
</syntaxhighlight>

Вставить:

<syntaxhighlight lang="bash">
#!/bin/bash
set -Eeuo pipefail

export PATH=/usr/sbin:/usr/bin:/sbin:/bin

APP_DIR="/opt/my-app"
APP_USER="myapp"
APP_SERVICE="my-app.service"
BRANCH="main"
REMOTE="origin"
HEALTH_URL="http://127.0.0.1:8000/health"

STATE_DIR="/var/lib/my-app-updater"
PAUSE_FILE="$STATE_DIR/PAUSED"

old_commit=""
new_commit=""
deployment_started=0

log() {
printf '%s %s\n' "$(date --iso-8601=seconds)" "$*"
}

as_app() {
runuser -u "$APP_USER" -- "$@"
}

git_app() {
as_app env \
GIT_TERMINAL_PROMPT=0 \
GIT_SSH_COMMAND="ssh -o BatchMode=yes -o ConnectTimeout=10" \
git -C "$APP_DIR" "$@"
}

health_once() {
local http_code

systemctl is-active --quiet "$APP_SERVICE" || return 1

http_code=$(
as_app curl --noproxy '*' \
--connect-timeout 2 --max-time 5 \
-sS -o /dev/null -w '%{http_code}' \
"$HEALTH_URL"
) || return 1

[[ "$http_code" == "200" ]]
}

wait_healthy() {
local attempt

for attempt in {1..12}; do
if health_once; then
return 0
fi
sleep 5
done

return 1
}

finish() {
local result=$?
trap - EXIT
set +e

if (( result != 0 && deployment_started == 1 )); then
log "Ошибка установки. Пытаемся вернуть $old_commit."
log "Автообновление останется на паузе."

if systemctl stop "$APP_SERVICE"; then
if git_app switch --no-overwrite-ignore \
--detach "$old_commit"; then

if systemctl start "$APP_SERVICE" && wait_healthy; then
log "Предыдущий код восстановлен, проверка пройдена."
else
log "КРИТИЧНО: после отката приложение не прошло проверку."
fi
else
log "КРИТИЧНО: вернуть код не удалось. Нужна ручная проверка."
fi
else
log "КРИТИЧНО: остановка не удалась; файлы не переключаем."
fi
fi

exit "$result"
}

trap finish EXIT

install -d -m 700 "$STATE_DIR"

exec 9>/run/lock/my-app-update.lock
if ! flock -n 9; then
log "Другой запуск уже выполняется."
exit 0
fi

if [[ -e "$PAUSE_FILE" ]]; then
log "Автообновление на паузе: $PAUSE_FILE"
exit 0
fi

cd "$APP_DIR"

current_branch=$(git_app branch --show-current)
if [[ "$current_branch" != "$BRANCH" ]]; then
log "Ожидалась ветка $BRANCH, получена: $current_branch"
exit 1
fi

working_changes=$(git_app status --porcelain --untracked-files=all)
if [[ -n "$working_changes" ]]; then
log "Есть локальные изменения или неотслеживаемые файлы."
exit 1
fi

# Если приложение было остановлено администратором,
# обновлятор не должен сам запускать его.
if ! systemctl is-active --quiet "$APP_SERVICE"; then
log "Приложение не активно. Обновление пропущено."
exit 0
fi

log "Проверяем $REMOTE/$BRANCH."

as_app env \
GIT_TERMINAL_PROMPT=0 \
GIT_SSH_COMMAND="ssh -o BatchMode=yes -o ConnectTimeout=10" \
timeout 60 git -C "$APP_DIR" fetch "$REMOTE" \
"refs/heads/$BRANCH:refs/remotes/$REMOTE/$BRANCH"

old_commit=$(git_app rev-parse HEAD)
new_commit=$(git_app rev-parse "refs/remotes/$REMOTE/$BRANCH")

if [[ "$old_commit" == "$new_commit" ]]; then
log "Новых коммитов нет."
exit 0
fi

if ! git_app merge-base --is-ancestor "$old_commit" "$new_commit"; then
log "Истории разошлись или удалённая ветка отстаёт."
exit 1
fi

# Разрешены только перечисленные пути.
# Зависимости, конфигурация, юниты и прочее требуют ручной установки.
changed_files=$(git_app diff --no-renames --name-only \
"$old_commit" "$new_commit")

while IFS= read -r changed_path; do
case "$changed_path" in
migrations/*|*/migrations/*|alembic/*|*/alembic/*)
log "Миграции требуют ручного обновления."
exit 1
;;
app/*.py|main.py|tests/*|docs/*|README.md)
;;
*)
log "Есть изменения вне разрешённых путей. Нужна ручная установка."
exit 1
;;
esac
done <<< "$changed_files"

# Не начинать установку поверх уже неисправного приложения.
if ! health_once; then
log "Текущая версия не проходит проверку состояния."
exit 1
fi

# Повторная проверка перед изменением файлов.
working_changes=$(git_app status --porcelain --untracked-files=all)
if [[ -n "$working_changes" ]] ||
[[ "$(git_app rev-parse HEAD)" != "$old_commit" ]]; then
log "Рабочая копия изменилась во время проверки."
exit 1
fi

backup_branch="backup/auto-$(date +%Y%m%d-%H%M%S)"
git_app branch "$backup_branch" "$old_commit"

printf 'old=%s\nnew=%s\nbackup=%s\n' \
"$old_commit" "$new_commit" "$backup_branch" > "$PAUSE_FILE"

# Маркер удаляется только после успешного обновления.
# При обрыве или перезагрузке следующий запуск не продолжит установку.
deployment_started=1

log "Устанавливаем $new_commit. Резервная ветка: $backup_branch"

systemctl stop "$APP_SERVICE"

if systemctl is-active --quiet "$APP_SERVICE"; then
log "Приложение не остановилось."
exit 1
fi

git_app merge --ff-only --no-overwrite-ignore "$new_commit"

# Проверка синтаксиса без создания файлов __pycache__.
# Пути нужно адаптировать под структуру проекта.
as_app "$APP_DIR/.venv/bin/python" - "$APP_DIR" <<'PY'
import pathlib
import sys

root = pathlib.Path(sys.argv[1])
files = list((root / "app").rglob("*.py"))

entry = root / "main.py"
if entry.is_file():
files.append(entry)

if not files:
raise SystemExit("Не найдены исходники для проверки")

for path in files:
compile(path.read_bytes(), str(path), "exec")

print(f"Проверен синтаксис файлов: {len(files)}")
PY

systemctl start "$APP_SERVICE"

if ! wait_healthy; then
log "Новая версия не прошла проверку состояния."
exit 1
fi

rm -- "$PAUSE_FILE"
deployment_started=0
log "Обновление завершено: $new_commit"
</syntaxhighlight>

Установить владельца, права и проверить синтаксис Bash:

<syntaxhighlight lang="bash">
chown root:root /usr/local/sbin/my-app-update
chmod 750 /usr/local/sbin/my-app-update
bash -n /usr/local/sbin/my-app-update
</syntaxhighlight>

Отсутствие вывода при успешном завершении bash -n означает, что синтаксис Bash корректен. Это не проверка работоспособности всей процедуры.

=== Как устроена защита ===

{| class="wikitable"
! Механизм !! Назначение
|-
| <code>flock</code>
| Не позволяет двум экземплярам скрипта одновременно менять приложение.
|-
| <code>git status</code>
| Останавливает обновление при локальных изменениях.
|-
| <code>fetch</code> с ограничением времени
| Проверяет GitLab без остановки программы.
|-
| <code>merge --ff-only</code>
| Отказывается объединять разошедшиеся истории.
|-
| <code>--no-overwrite-ignore</code>
| Не разрешает перезаписывать мешающие обновлению игнорируемые файлы.
|-
| Разрешённые пути
| Отправляет изменения зависимостей и конфигурации на ручную установку.
|-
| Резервная ветка
| Сохраняет ссылку на предыдущий коммит.
|-
| Проверка синтаксиса и HTTP
| Проверяет код и ответ запущенного приложения.
|-
| Файл <code>PAUSED</code>
| Блокирует дальнейшие установки после ошибки или прерванного обновления.
|}

Git, Python и HTTP-проверка выполняются от имени myapp. Root используется для управления службой и служебными файлами обновлятора.

'''Список разрешённых путей не анализирует смысл кода.''' Даже изменение одного Python-файла может оказаться несовместимым с данными. Поэтому проверка изменений и CI перед публикацией в рабочую ветку обязательны.

Во время работы обновлятора не выполнять ручные Git-операции в этом каталоге. Блокировка flock действует только на процессы, которые используют тот же файл блокировки.

=== 5. Создание службы обновления ===

Открыть:

<syntaxhighlight lang="bash">
nano /etc/systemd/system/my-app-update.service
</syntaxhighlight>

Вставить:

<syntaxhighlight lang="ini">
[Unit]
Description=Update my-app from GitLab
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
User=root
UMask=0077
ExecStart=/usr/local/sbin/my-app-update
TimeoutStartSec=15min
StandardOutput=journal
StandardError=journal
</syntaxhighlight>

Это отдельная служба обновлятора. Существующую my-app.service заменять не нужно.

TimeoutStartSec ограничивает длительность всей операции. При принудительном завершении откат не гарантирован: файл PAUSED сохраняется для ручного восстановления.

=== 6. Создание таймера ===

Открыть:

<syntaxhighlight lang="bash">
nano /etc/systemd/system/my-app-update.timer
</syntaxhighlight>

Вставить:

<syntaxhighlight lang="ini">
[Unit]
Description=Check my-app updates every 3 minutes

[Timer]
OnBootSec=2min
OnUnitInactiveSec=3min
AccuracySec=10s
Unit=my-app-update.service

[Install]
WantedBy=timers.target
</syntaxhighlight>

Параметры:

* <code>OnBootSec=2min</code> — первая проверка через две минуты после загрузки. При включении таймера позднее этого момента она может начаться сразу.
* <code>OnUnitInactiveSec=3min</code> — следующая проверка через три минуты после завершения предыдущего запуска.
* <code>AccuracySec=10s</code> — допустимое окно срабатывания таймера.

Для другого интервала заменить:

<syntaxhighlight lang="ini">
OnUnitInactiveSec=2min
</syntaxhighlight>

или:

<syntaxhighlight lang="ini">
OnUnitInactiveSec=5min
</syntaxhighlight>

Это интервал между проверками, а не гарантированный срок установки: сама операция тоже занимает время.

=== 7. Первый запуск вручную ===

До включения расписания адаптировать пути, пользователя, ветку и healthcheck.

Проверить файлы:

<syntaxhighlight lang="bash">
systemd-analyze verify \
/etc/systemd/system/my-app-update.service \
/etc/systemd/system/my-app-update.timer

systemctl daemon-reload
</syntaxhighlight>

Запустить одну проверку:

<syntaxhighlight lang="bash">
systemctl start my-app-update.service
journalctl -u my-app-update.service -n 100 --no-pager
</syntaxhighlight>

'''Этот запуск уже устанавливает новые коммиты, если они есть.''' Выполнять в согласованное время обслуживания.

Сначала проверить весь сценарий на тестовой копии, включая успешное обновление и отказ проверки с откатом.

После успешного выполнения oneshot-служба обычно имеет состояние inactive (dead). Для неё это нормально.

Результат последнего запуска:

<syntaxhighlight lang="bash">
systemctl show my-app-update.service \
-p Result \
-p ExecMainStatus
</syntaxhighlight>

Ожидается:

<syntaxhighlight lang="text">
Result=success
ExecMainStatus=0
</syntaxhighlight>

=== 8. Включение расписания ===

После проверки включить таймер:

<syntaxhighlight lang="bash">
systemctl enable --now my-app-update.timer
systemctl list-timers --all my-app-update.timer
</syntaxhighlight>

В таблице будут показаны последнее и следующее срабатывания.

=== Просмотр журналов ===

Журнал обновлятора:

<syntaxhighlight lang="bash">
journalctl -u my-app-update.service -n 100 --no-pager
</syntaxhighlight>

Наблюдение в реальном времени:

<syntaxhighlight lang="bash">
journalctl -u my-app-update.service -f
</syntaxhighlight>

Журнал самого приложения:

<syntaxhighlight lang="bash">
journalctl -u my-app.service -n 100 --no-pager
</syntaxhighlight>

Пример штатной проверки:

<syntaxhighlight lang="text">
Проверяем origin/main.
Новых коммитов нет.
</syntaxhighlight>

=== Изменение интервала ===

Изменить OnUnitInactiveSec в файле таймера, затем выполнить:

<syntaxhighlight lang="bash">
systemctl daemon-reload
systemctl restart my-app-update.timer
systemctl list-timers --all my-app-update.timer
</syntaxhighlight>

=== Временное отключение ===

Остановить расписание и отключить его автозапуск:

<syntaxhighlight lang="bash">
systemctl disable --now my-app-update.timer
</syntaxhighlight>

Это не останавливает приложение и не прерывает уже выполняющееся обновление.

Перед ручными работами проверить:

<syntaxhighlight lang="bash">
systemctl status my-app-update.service --no-pager
</syntaxhighlight>

Дождаться завершения текущей операции.

=== Что делать после ошибки обновления ===

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

<syntaxhighlight lang="text">
/var/lib/my-app-updater/PAUSED
</syntaxhighlight>

Отключить таймер и изучить состояние:

<syntaxhighlight lang="bash">
systemctl disable --now my-app-update.timer

cat /var/lib/my-app-updater/PAUSED

journalctl -u my-app-update.service -n 150 --no-pager
systemctl status my-app.service --no-pager -l

runuser -u myapp -- git -C /opt/my-app status
runuser -u myapp -- git -C /opt/my-app log -1 --oneline
</syntaxhighlight>

После успешного отката репозиторий находится в detached HEAD на старом коммите. Ветка main может по-прежнему указывать на неудачное обновление.

'''Не переключаться обратно на main и не удалять PAUSED вслепую.'''

Для восстановления:

# Исправить или отменить проблемное изменение в GitLab.
# Вручную установить и проверить исправленную версию по процедуре ручного обновления.
# Убедиться, что текущая ветка main, рабочая копия чистая и приложение исправно.
# Только после этого снять паузу.

<syntaxhighlight lang="bash">
rm /var/lib/my-app-updater/PAUSED
systemctl reset-failed my-app-update.service
systemctl enable --now my-app-update.timer
</syntaxhighlight>

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

=== Изменение зависимостей или базы данных ===

Если в GitLab изменились requirements.txt, lock-файл, юнит, конфигурация или файлы миграций, обновлятор откажется устанавливать такой коммит.

В этом случае:

# Отключить таймер.
# Дождаться завершения обновлятора.
# Сделать необходимые резервные копии.
# Выполнить ручное обновление по инструкции проекта.
# Проверить приложение.
# Снова включить таймер.

Не добавлять автоматическую установку зависимостей или миграций без отдельного плана восстановления.

=== Ограничения ===

* Резервная ветка сохраняет только код, а не базу и пользовательские файлы.
* Успешный HTTP 200 не заменяет полноценные функциональные тесты.
* Скрипт не поддерживает развёртывание Git LFS и submodules без дополнительной адаптации.
* Приложение не должно самостоятельно менять отслеживаемые файлы.
* На время обновления не должно быть внешнего механизма, который снова запускает остановленную службу.
* Ошибки записываются в журнал; уведомления администратору здесь не настроены.
* Резервные ветки постепенно накапливаются. Их удаление следует выполнять отдельно после проверки стабильности и наличия резервных копий.

Sis admin linux

2026-09-28T18:36:19Z

Artem:

Sis admin linux

2026-09-28T18:29:17Z

Artem: /* SSH-доступ с macOS к LXC-контейнеру Proxmox по ключу */

Sis admin linux

2026-09-28T18:25:55Z

Artem:

Sis admin linux

2026-09-28T18:20:14Z

Artem:

Заглавная страница

2026-09-28T18:18:59Z

Artem:

<div class="portal-header">
<h1>📚 База знаний</h1>
<p>Документация по инфраструктуре, Linux и игровым серверам.</p>
</div>

<div class="portal-grid">

<div class="portal-card">

=== 🖥️ Инфраструктура ===
''Серверы и виртуализация''

* [[Proxmox]]
* [[PBS]]
* [[iLO]]
* [[BrainyCP]]
* [[Сетевое оборудование]]
* [[RAMBA Matrix]]
* [[RAMBA AI Router]]
* [[Happ-gateway|HAPP Gateway]]
* [[Kuzya2-0|Телеграм бот Кузя 2.0]]

</div>

<div class="portal-card">

=== 🐧 Linux ===
''Системное администрирование''

* [[Ubuntu]]
* [[Debian]]
* [[Nginx]]
* [[Docker]]
* [[Bash]]
* [[Sis admin linux|Хитрости администрирования Linux]]

</div>

<div class="portal-card">

=== 🎮 Игровые серверы ===
''Игровая инфраструктура''

* [[Rust]]
* [[LGSM]]
* [[SteamCMD]]
* [[Резервное копирование]]
* [[Мониторинг]]

</div>

</div>

<div class="portal-card">

== ⭐ Избранные статьи ==

* [[Установка Proxmox VE]]
* [[Настройка Proxmox Backup Server]]
* [[Настройка BrainyCP]]
* [[Создание LXC-контейнеров]]
* [[Настройка Rust-сервера через LGSM]]
* [[Minecraft_в_2026_году]]

</div>

<div class="portal-card">

== 🕒 Последние изменения ==

* [[Special:RecentChanges|Посмотреть все последние изменения]]

</div>

<div class="portal-card">

== 🔗 Полезные ссылки ==

* [[Special:AllPages|Все статьи]]
* [[Special:Categories|Все категории]]
* [[Special:WantedPages|Нужные страницы]]
* [[Special:Random|🎲 Случайная статья]]

</div>

Заглавная страница

2026-09-28T18:17:16Z

Artem:

<div class="portal-header">
<h1>📚 База знаний</h1>
<p>Документация по инфраструктуре, Linux и игровым серверам.</p>
</div>

<div class="portal-grid">

<div class="portal-card">

=== 🖥️ Инфраструктура ===
''Серверы и виртуализация''

* [[Proxmox]]
* [[PBS]]
* [[iLO]]
* [[BrainyCP]]
* [[Сетевое оборудование]]
* [[RAMBA Matrix]]
* [[RAMBA AI Router]]
* [[Happ-gateway|HAPP Gateway]]
* [[Kuzya2-0|Телеграм бот Кузя 2.0]]

</div>

<div class="portal-card">

=== 🐧 Linux ===
''Системное администрирование''

* [[Ubuntu]]
* [[Debian]]
* [[Nginx]]
* [[Docker]]
* [[Bash]]
* [[Sis admin linux|SSH-доступ с Mac по ключу]]

</div>

<div class="portal-card">

=== 🎮 Игровые серверы ===
''Игровая инфраструктура''

* [[Rust]]
* [[LGSM]]
* [[SteamCMD]]
* [[Резервное копирование]]
* [[Мониторинг]]

</div>

</div>

<div class="portal-card">

== ⭐ Избранные статьи ==

* [[Установка Proxmox VE]]
* [[Настройка Proxmox Backup Server]]
* [[Настройка BrainyCP]]
* [[Создание LXC-контейнеров]]
* [[Настройка Rust-сервера через LGSM]]
* [[Minecraft_в_2026_году]]

</div>

<div class="portal-card">

== 🕒 Последние изменения ==

* [[Special:RecentChanges|Посмотреть все последние изменения]]

</div>

<div class="portal-card">

== 🔗 Полезные ссылки ==

* [[Special:AllPages|Все статьи]]
* [[Special:Categories|Все категории]]
* [[Special:WantedPages|Нужные страницы]]
* [[Special:Random|🎲 Случайная статья]]

</div>

Sis admin linux

2026-09-28T18:16:09Z

Artem: Новая страница: «= SSH-доступ с macOS к LXC-контейнеру Proxmox по ключу = == Назначение == Инструкция позволяет настроить подключение с Mac к LXC-контейнеру Proxmox по SSH без ввода пароля пользователя root. Публичный ключ добавляется через консоль Proxmox, поэтому знать или создавать пароль roo...»

= SSH-доступ с macOS к LXC-контейнеру Proxmox по ключу =

== Назначение ==

Инструкция позволяет настроить подключение с Mac к LXC-контейнеру Proxmox по SSH без ввода пароля пользователя root.

Публичный ключ добавляется через консоль Proxmox, поэтому знать или создавать пароль root контейнера для этой настройки не требуется.

'''Все адреса и идентификаторы приведены для примера. Замените их значениями своей инфраструктуры.'''

{| class="wikitable"
! Параметр !! Пример
|-
| ID контейнера || 123
|-
| IP-адрес контейнера || 192.168.2.2
|-
| Пользователь SSH || root
|-
| Клиент || Mac с macOS
|-
| Тип ключа || Ed25519
|}

__TOC__

== Перед началом ==

Для выполнения инструкции необходимы:

* Доступ к терминалу macOS.
* Административный доступ к консоли узла Proxmox, на котором запущен контейнер.
* Установленный и работающий SSH-сервер внутри контейнера.
* Сетевая доступность контейнера с Mac — напрямую через локальную сеть либо через VPN.

SSH-сервер контейнера должен разрешать авторизацию по публичному ключу и вход root по ключу.

== 1. Создание SSH-ключа на Mac ==

Открыть приложение '''Терминал''' на Mac.

Выполнить:

<syntaxhighlight lang="bash">
if [ ! -f ~/.ssh/id_ed25519 ]; then
ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_ed25519
else
echo "SSH-ключ уже существует."
fi
</syntaxhighlight>

Команда создаёт новый ключ только при отсутствии файла <code>~/.ssh/id_ed25519</code>. Существующий ключ не перезаписывается.

После создания появляются два файла:

{| class="wikitable"
! Файл !! Назначение
|-
| <code>~/.ssh/id_ed25519</code>
| Приватный ключ. Остаётся на Mac и не передаётся другим пользователям.
|-
| <code>~/.ssh/id_ed25519.pub</code>
| Публичный ключ. Добавляется на сервер, к которому требуется доступ.
|}

'''Важно:''' параметр <code>-N ""</code> создаёт новый ключ без парольной фразы. Получивший этот приватный ключ сможет использовать его для доступа к серверам, на которых разрешён соответствующий публичный ключ.

Если нужна защита ключа парольной фразой, при отсутствии ключа вместо команды выше используйте:

<syntaxhighlight lang="bash">
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519
</syntaxhighlight>

== 2. Получение публичного ключа ==

'''На Mac''' выполнить:

<syntaxhighlight lang="bash">
cat ~/.ssh/id_ed25519.pub
</syntaxhighlight>

Скопировать всю строку, начинающуюся с <code>ssh-ed25519</code>.

Ключ нужно копировать целиком, одной строкой.

'''Не следует копировать:'''

* Приватный ключ из файла без расширения <code>.pub</code>.
* Отпечаток вида <code>SHA256:...</code>.
* Графический рисунок, показанный при создании ключа.

Если приватный ключ существует, а соответствующий файл <code>.pub</code> отсутствует, публичный ключ можно восстановить на Mac:

<syntaxhighlight lang="bash">
ssh-keygen -y -f ~/.ssh/id_ed25519 > ~/.ssh/id_ed25519.pub
</syntaxhighlight>

== 3. Вход в контейнер через Proxmox ==

В веб-интерфейсе Proxmox выбрать '''узел, на котором запущен контейнер''', и открыть его '''Shell'''.

Выполнить, заменив <code>123</code> фактическим ID контейнера:

<syntaxhighlight lang="bash">
pct enter 123
</syntaxhighlight>

После выполнения команды откроется оболочка контейнера.

'''Все команды следующего раздела выполняются внутри контейнера от имени root.'''

== 4. Добавление публичного ключа ==

Подготовить каталог:

<syntaxhighlight lang="bash">
mkdir -p /root/.ssh
chmod 700 /root/.ssh
</syntaxhighlight>

В следующей команде заменить <code>ВСТАВЬ_ПУБЛИЧНЫЙ_КЛЮЧ</code> полной строкой публичного ключа с Mac. Одинарные кавычки сохранить:

<syntaxhighlight lang="bash">
printf '%s\n' 'ВСТАВЬ_ПУБЛИЧНЫЙ_КЛЮЧ' >> /root/.ssh/authorized_keys
</syntaxhighlight>

Установить владельца и права:

<syntaxhighlight lang="bash">
chown root:root /root/.ssh /root/.ssh/authorized_keys
chmod 600 /root/.ssh/authorized_keys
</syntaxhighlight>

Оператор <code>>></code> добавляет ключ в конец файла, сохраняя существующие записи.

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

'''Перезапуск SSH-сервера после добавления ключа не требуется.'''

== 5. Проверка ключа сервера ==

При первом подключении Mac может запросить подтверждение подлинности сервера.

Чтобы проверить отпечаток ключа ED25519, выполнить '''внутри контейнера через консоль Proxmox''':

<syntaxhighlight lang="bash">
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

Сравнить полученный отпечаток <code>SHA256:...</code> с отпечатком, который покажет Mac при подключении.

Сравнивать нужно ключи одного типа: в данном случае ED25519.

== 6. Подключение с Mac ==

'''В Терминале на Mac''' выполнить, подставив адрес своего контейнера:

<syntaxhighlight lang="bash">
ssh root@192.168.2.2
</syntaxhighlight>

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

<syntaxhighlight lang="text">
yes
</syntaxhighlight>

При успешной настройке откроется оболочка контейнера без запроса пароля root.

Для завершения сеанса:

<syntaxhighlight lang="bash">
exit
</syntaxhighlight>

== Если ключ защищён парольной фразой ==

Запрос <code>Enter passphrase for key</code> означает, что macOS просит парольную фразу приватного ключа, а не пароль root контейнера.

Чтобы добавить ключ в SSH-агент и сохранить парольную фразу в связке ключей macOS, выполнить '''на Mac''':

<syntaxhighlight lang="bash">
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
</syntaxhighlight>

Ввести парольную фразу ключа.

Для её дальнейшего использования можно добавить параметры в файл <code>~/.ssh/config</code>, как показано в следующем разделе.

== Короткая команда подключения ==

Вместо IP-адреса можно использовать удобное имя, например <code>my-container</code>.

'''На Mac''' открыть файл настроек:

<syntaxhighlight lang="bash">
mkdir -p ~/.ssh
chmod 700 ~/.ssh
nano ~/.ssh/config
</syntaxhighlight>

Добавить отдельный блок. Если блок с таким именем уже есть, изменить его вместо создания дубликата:

<syntaxhighlight lang="text">
Host my-container
HostName 192.168.2.2
User root
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yes
AddKeysToAgent yes
UseKeychain yes
</syntaxhighlight>

Сохранить файл в nano:

# Нажать <code>Control + O</code>.
# Нажать <code>Enter</code>.
# Нажать <code>Control + X</code>.

Установить права:

<syntaxhighlight lang="bash">
chmod 600 ~/.ssh/config
</syntaxhighlight>

Теперь подключаться можно командой:

<syntaxhighlight lang="bash">
ssh my-container
</syntaxhighlight>

== Диагностика ==

=== Сервер запрашивает пароль root ===

Это означает, что авторизация по ключу не завершилась успешно.

На Mac явно указать нужный ключ и включить подробный вывод:

<syntaxhighlight lang="bash">
ssh -v -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 root@192.168.2.2
</syntaxhighlight>

Через консоль Proxmox проверить внутри контейнера:

<syntaxhighlight lang="bash">
ls -ld /root/.ssh
ls -l /root/.ssh/authorized_keys
</syntaxhighlight>

Ожидаемые параметры:

{| class="wikitable"
! Объект !! Права !! Владелец
|-
| <code>/root/.ssh</code> || 700 — <code>drwx------</code> || root
|-
| <code>/root/.ssh/authorized_keys</code> || 600 — <code>-rw-------</code> || root
|}

Также проверить:

* В файле записан публичный ключ именно с нужного Mac.
* Ключ не разбит на несколько строк.
* Подключение выполняется к правильному IP-адресу и пользователю.
* SSH-сервер разрешает авторизацию по ключу.
* Вход root по ключу не запрещён настройками SSH.

=== Соединение отклонено: Connection refused ===

Проверить правильность адреса, работу SSH-сервера и порт, на котором он принимает подключения.

=== Сервер не отвечает: Connection timed out ===

Проверить:

* Запущен ли контейнер.
* Доступна ли его подсеть с Mac.
* Подключён ли нужный VPN.
* Не блокируется ли SSH-порт межсетевым экраном.

=== Изменился ключ сервера ===

При предупреждении <code>REMOTE HOST IDENTIFICATION HAS CHANGED</code> сначала проверить причину изменения и новый отпечаток через доверенную консоль Proxmox.

Не удалять сохранённый ключ сервера без проверки: предупреждение может означать как переустановку контейнера, так и подключение к другому устройству.

== Итог ==

После настройки Mac использует приватный ключ для подтверждения доступа, а контейнер проверяет его по публичному ключу из <code>/root/.ssh/authorized_keys</code>.

Настройка сохраняется после перезагрузки Mac и контейнера.

'''Добавление ключа само по себе не отключает парольную авторизацию SSH.''' Настройки разрешённых способов входа управляются отдельно.

Заглавная страница

2026-09-28T18:16:04Z

Artem:

<div class="portal-header">
<h1>📚 База знаний</h1>
<p>Документация по инфраструктуре, Linux и игровым серверам.</p>
</div>

<div class="portal-grid">

<div class="portal-card">

=== 🖥️ Инфраструктура ===
''Серверы и виртуализация''

* [[Proxmox]]
* [[PBS]]
* [[iLO]]
* [[BrainyCP]]
* [[Сетевое оборудование]]
* [[RAMBA Matrix]]
* [[RAMBA AI Router]]
* [[Happ-gateway|HAPP Gateway]]
* [[Kuzya2-0|Телеграм бот Кузя 2.0]]

</div>

<div class="portal-card">

=== 🐧 Linux ===
''Системное администрирование''

* [[Ubuntu]]
* [[Debian]]
* [[Nginx]]
* [[Docker]]
* [[Bash]]
* [[SSH-доступ с macOS к LXC-контейнеру Proxmox по ключу|SSH с Mac по ключу]]

</div>

<div class="portal-card">

=== 🎮 Игровые серверы ===
''Игровая инфраструктура''

* [[Rust]]
* [[LGSM]]
* [[SteamCMD]]
* [[Резервное копирование]]
* [[Мониторинг]]

</div>

</div>

<div class="portal-card">

== ⭐ Избранные статьи ==

* [[Установка Proxmox VE]]
* [[Настройка Proxmox Backup Server]]
* [[Настройка BrainyCP]]
* [[Создание LXC-контейнеров]]
* [[Настройка Rust-сервера через LGSM]]
* [[Minecraft_в_2026_году]]

</div>

<div class="portal-card">

== 🕒 Последние изменения ==

* [[Special:RecentChanges|Посмотреть все последние изменения]]

</div>

<div class="portal-card">

== 🔗 Полезные ссылки ==

* [[Special:AllPages|Все статьи]]
* [[Special:Categories|Все категории]]
* [[Special:WantedPages|Нужные страницы]]
* [[Special:Random|🎲 Случайная статья]]

</div>

Kuzya2-0

2026-09-26T06:24:29Z

Artem:

= Кузя — интеллектуальный администратор Telegram-сообщества =

'''Кузя''' — Telegram-бот для администрирования и сопровождения сообщества. Проект развивается от классического административного бота к интеллектуальному помощнику и AI-модератору, способному анализировать происходящее в чате, помогать участникам и администраторам и самостоятельно выявлять нарушения.

Основная задача проекта — не заменить живых администраторов, а снять с них значительную часть рутинной работы и предоставить дополнительные инструменты для управления сообществом.

== Текущее состояние проекта ==

Кузя уже является рабочим Telegram-ботом и используется для выполнения административных и информационных задач.

На данный момент реализованы следующие возможности:

* выдача мута;
* снятие мута;
* временный и постоянный бан;
* система предупреждений;
* указание причины нарушения;
* хранение истории предупреждений;
* отдельный список администраторов Кузи;
* приветствие новых участников;
* публикация информационных сообщений;
* вывод правил сообщества;
* публикация ссылок;
* приглашения;
* информация о поддержке проекта;
* взаимодействие с публикациями Telegram-канала;
* автоматическая публикация информационного сообщения под новым видео;
* хранение истории сообщений Telegram-чата;
* изменение ряда настроек и текстов через команды администратора;
* базовые функции AI-ассистента.

== База данных сообщества ==

Кузя работает с MySQL и ведёт собственную историю чата.

На август 2026 года в базе сохранено около:

'''497 000 сообщений.'''

Для сообщений сохраняются, в частности:

* дата и время;
* Telegram ID пользователя;
* username;
* отображаемое имя;
* текст сообщения;
* Telegram message ID.

Отдельно существует база предупреждений.

В ней сохраняются:

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

Большинство предупреждений связано с исходным сообщением через '''message_id'''.

Таким образом, за время существования Кузи администраторами фактически был создан первоначальный набор вручную размеченных примеров нарушений.

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

== Концепция дальнейшего развития ==

В перспективе Кузя должен состоять из трёх основных подсистем:

<pre>
КУЗЯ
|
+-------------+-------------+
| | |
v v v
Telegram Admin AI Assistant Guardian
| | |
mute / ban диалог модерация
warnings память антиспам
rules поиск конфликты
channel RAG репутация
| | |
+-------------+-------------+
|
v
RAMBA AI
Local AI Router
</pre>

== Локальный искусственный интеллект ==

Основной AI Кузи планируется сделать '''локальным'''.

Для обработки запросов используется инфраструктура RAMBA AI с несколькими локальными нейронными моделями.

Архитектура предусматривает три специализированные модели, работающие на локальном сервере с NVIDIA GeForce GTX 1080.

<pre>
Telegram
|
v
Кузя
|
v
RAMBA AI Router
|
+------ Model 1
|
+------ Model 2
|
+------ Model 3
|
+------ OpenAI API
дополнительный уровень
</pre>

AI Router определяет, какая модель лучше подходит для конкретной задачи.

OpenAI API при этом не является основным интеллектом Кузи. Он рассматривается как дополнительный инструмент для отдельных сложных задач и сценариев, в которых возможностей локальных моделей недостаточно.

Это также позволяет не передавать всю историю сообщества внешним AI-сервисам.

== Kuzya 2.0 — новая архитектура ==

Первым этапом развития станет создание '''Kuzya 2.0'''.

Главный принцип:

'''Сначала переносим все существующие возможности без потери функциональности, затем добавляем AI.'''

Текущая рабочая версия сохраняется как:

'''Kuzya Legacy Stable'''

Новая версия разрабатывается отдельно.

В Kuzya 2.0 существующий монолитный код планируется разделить на независимые компоненты:

<pre>
kuzya/
|
+-- bot/
| +-- moderation/
| +-- commands/
| +-- channel/
| +-- users/
| +-- handlers/
|
+-- database/
| +-- messages
| +-- warnings
| +-- admins
| +-- settings
|
+-- ai/
| +-- assistant
| +-- moderation
| +-- context
| +-- memory
|
+-- services/
|
+-- config/
|
+-- main.py
</pre>

Это позволит развивать отдельные возможности Кузи независимо друг от друга.

== Kuzya 2.1 — развитие базы данных ==

Существующая MySQL-база сохраняется.

История почти из полумиллиона сообщений является ценным архивом и не должна изменяться или удаляться в процессе модернизации.

Для новой версии предполагается постепенно перейти к единой структуре данных:

* chats;
* users;
* messages;
* warnings;
* moderation_actions;
* admins;
* chat_settings.

Каждое административное действие сможет дополнительно содержать источник решения:

* '''human''' — решение администратора;
* '''ai''' — решение AI;
* '''rule''' — автоматическое правило.

Это позволит впоследствии анализировать качество работы AI.

== Kuzya 2.2 — AI Router ==

Кузя подключается к RAMBA AI Router.

Telegram-бот при этом не запускает и не управляет моделями непосредственно.

<pre>
Кузя
|
| запрос
v
RAMBA AI Router
|
+--> разговорная модель
|
+--> модель сложных задач
|
+--> специализированная модель
|
+--> внешний AI (при необходимости)
</pre>

Это позволит менять модели независимо от Telegram-бота и использовать одну AI-инфраструктуру для нескольких проектов.

== Kuzya 2.3 — полноценный AI-ассистент ==

Кузя сможет поддерживать обычный разговор.

Например:

<pre>
Кузя, что сегодня обсуждали?

Кузя, объясни подробнее.

Кузя, какие правила относятся к публикации ссылок?
</pre>

При ответе AI сможет учитывать:

* текущий вопрос;
* предыдущие сообщения разговора;
* контекст Telegram-чата;
* правила сообщества;
* настройки конкретного чата.

Таким образом появляется краткосрочная память.

== Kuzya 2.4 — долговременная память ==

История сообщений не должна целиком передаваться нейронной модели.

Для этого предполагается использовать технологию RAG.

<pre>
История MySQL
|
v
индексация
|
v
Vector DB
|
v
поиск нужной истории
|
v
AI
</pre>

Например, участник сможет спросить:

<pre>
Кузя, мы раньше обсуждали эту проблему?
</pre>

Кузя найдёт связанные старые обсуждения и использует их при формировании ответа.

Таким образом накопленная история чата становится долговременной памятью сообщества.

= Kuzya Guardian =

'''Kuzya Guardian''' — ключевое направление дальнейшего развития проекта.

Это интеллектуальная система модерации Telegram-чата.

== Анализ сообщений ==

Новые сообщения смогут проходить через несколько уровней проверки:

<pre>
Telegram message
|
v
простые правила
|
v
AI-анализ
|
v
оценка риска
|
v
решение
</pre>

AI сможет определять, например:

* спам;
* флуд;
* нежелательную рекламу;
* оскорбления;
* провокации;
* нарушения правил сообщества;
* эскалацию конфликтов;
* повторные нарушения.

При этом анализироваться сможет не только одно сообщение, но и контекст разговора.

== Shadow Mode ==

На первом этапе AI '''не получает право самостоятельно наказывать пользователей'''.

Кузя работает в теневом режиме — Shadow Mode.

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

<pre>
Кузя обнаружил возможное нарушение.

Пользователь: @username
Тип: оскорбление
Уверенность: 87 %

Предлагаемое действие:
Предупреждение

[Нарушение]
[Не нарушение]
[Мут]
[Бан]
</pre>

Окончательное решение принимает человек.

Решение администратора сохраняется в базе.

== Обучение на решениях администраторов ==

Shadow Mode одновременно позволяет собирать новый качественный набор данных.

Для каждого случая можно сохранять:

<pre>
сообщение
+
контекст
+
решение AI
+
решение администратора
+
причина
+
применённое действие
</pre>

Таким образом Кузя постепенно получает примеры того, '''как именно администрация данного сообщества трактует его правила'''.

Существующая база предупреждений также может использоваться как первоначальный набор размеченных примеров.

== Полуавтоматическая модерация ==

После накопления статистики отдельные очевидные нарушения можно будет обрабатывать автоматически.

Примерная модель:

<pre>
низкая уверенность
|
+--> никаких действий

средняя уверенность
|
+--> запись в журнал

высокая уверенность
|
+--> сообщение администраторам

очень высокая уверенность
+ безопасная категория
|
+--> автоматическое действие
</pre>

Порог автоматизации будет зависеть от типа нарушения.

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

== Репутация пользователей ==

В перспективе Guardian сможет учитывать историю поведения пользователя.

Учитываются:

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

Репутация является внутренним параметром системы и не обязательно должна отображаться участникам.

Она используется только как дополнительный контекст для принятия решения.

== Анализ конфликтов ==

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

Кузя анализирует последовательность сообщений нескольких участников и может определить постепенную эскалацию.

Вместо немедленного наказания бот сначала сможет предложить участникам прекратить спор.

Если конфликт продолжается, информация передаётся администраторам.

Таким образом система должна оценивать не только отдельные слова, но и развитие разговора.

= Аналитика сообщества =

Кузя сможет формировать статистику Telegram-чата.

Например:

<pre>
Статистика за сутки

Сообщений: 2351
Активных участников: 187
Новых участников: 14

Предупреждений: 3
Мутов: 1
Удалено спама: 9
</pre>

Дополнительно AI сможет определять основные темы обсуждения.

== Ежедневный дайджест ==

В перспективе возможно автоматическое формирование краткого отчёта:

<pre>
Что произошло сегодня

Обсудили:
* ...
* ...
* ...

Важные ссылки:
* ...
* ...

Модерация:
* 2 предупреждения
* 1 мут
</pre>

Это особенно полезно участникам и администраторам, которые не могли постоянно следить за чатом.

= Знание правил сообщества =

Правила конкретного сообщества становятся частью базы знаний Кузи.

Участник сможет спросить:

<pre>
Кузя, можно здесь публиковать ссылку на YouTube?
</pre>

Ответ будет основан именно на действующих правилах данного сообщества.

Кузя также сможет объяснять административные решения:

<pre>
Почему сообщение удалено?
</pre>

Например:

<pre>
Сообщение нарушает пункт 2 правил:
ссылка опубликована без необходимого описания.
</pre>

= Этапы разработки =

{| class="wikitable"
! Версия
! Основная задача
|-
| '''Legacy'''
| Текущий рабочий Кузя
|-
| '''2.0'''
| Новая архитектура и полный перенос существующих функций
|-
| '''2.1'''
| Новая структура MySQL и сохранение существующей истории
|-
| '''2.2'''
| Интеграция с RAMBA AI Router
|-
| '''2.3'''
| Полноценные AI-диалоги и краткосрочный контекст
|-
| '''2.4'''
| RAG и долговременная память по истории Telegram-чата
|-
| '''3.0'''
| Kuzya Guardian
|-
| '''3.1'''
| Shadow Mode
|-
| '''3.2'''
| Полуавтоматическая модерация
|-
| '''3.3'''
| Репутационная система
|-
| '''3.4'''
| Анализ конфликтов
|-
| '''4.0'''
| Аналитика сообщества и дайджесты
|-
| '''4.1'''
| Глубокая интеграция AI с правилами сообщества
|-
| '''5.0'''
| Полноценный интеллектуальный Community Guardian
|}

= Принципы проекта =

При разработке Кузи предлагается придерживаться нескольких основных принципов.

'''1. Существующие функции не должны быть потеряны.'''

Новая версия сначала достигает функционального паритета с текущей и только затем заменяет её.

'''2. Решение человека важнее решения AI.'''

Администратор всегда должен иметь возможность отменить или изменить решение системы.

'''3. Автоматизация вводится постепенно.'''

Сначала наблюдение, затем рекомендации и только после проверки качества — автоматические действия.

'''4. История сообщества является ценным активом.'''

Существующая MySQL-база сохраняется и используется для построения памяти и системы модерации.

'''5. Основной AI работает локально.'''

Локальные модели являются основой интеллектуальных функций Кузи. Внешние AI API используются только как дополнительный инструмент.

'''6. Кузя остаётся специализированным ботом.'''

Его основная область ответственности — Telegram-сообщество.

Управление серверами, Proxmox, GitLab, Matrix и другой инфраструктурой RAMBA выносится в отдельный RAMBA Bot.

= Конечная цель =

Конечная цель проекта — превратить Кузю из набора административных Telegram-команд в полноценного интеллектуального помощника сообщества:

<pre>
КУЗЯ
|
+-------------+-------------+
| | |
v v v
Администратор AI-ассистент Guardian
| | |
команды диалог модерация
правила память антиспам
warnings RAG конфликты
канал поиск репутация
| | |
+-------------+-------------+
|
v
RAMBA AI
Local AI Router
GTX 1080
</pre>

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

[[https://wiki.ramba-art.ru/wiki/Kuzya_2-0_lost_patch| Кузя 2.0 последние изменения]]

Kuzya 2-0 lost patch

2026-09-26T06:21:50Z

Artem: Новая страница: «'''Кузя''' — Telegram-бот для администрирования и сопровождения сообщества. Проект развивается от административного бота к интеллектуальному помощнику, способному поддерживать диалог, находить информацию в истории чата и помогать модераторам. Основная з...»

'''Кузя''' — Telegram-бот для администрирования и сопровождения сообщества. Проект развивается от административного бота к интеллектуальному помощнику, способному поддерживать диалог, находить информацию в истории чата и помогать модераторам.

Основная задача Кузи — автоматизировать рутинные действия и предоставить администрации удобные инструменты управления сообществом. Окончательный контроль остаётся у людей.

'''Текущий этап: Kuzya 2.0 — перенос существующих функций на новую архитектуру. Полный функциональный паритет с Legacy пока не подтверждён.'''

Состояние разработки в статье отражает проверку репозитория и результатов тестирования по состоянию на '''18 сентября 2026 года'''. Наличие кода в репозитории не означает, что все возможности уже развёрнуты и проверены в основном сообществе.

== Репозиторий и версии ==

* [https://gitlab.ramba-art.ru/Gans/noprodaction Репозиторий noProdaction]
* [https://gitlab.ramba-art.ru/Gans/noprodaction/-/tree/feature/openai-bot-v2 Ветка разработки Kuzya 2.0]
* [https://gitlab.ramba-art.ru/Gans/noprodaction/-/commits/feature/openai-bot-v2 История изменений Kuzya 2.0]

{| class="wikitable"
! Версия / ветка
! Назначение
! Подтверждённое состояние
|-
| '''Legacy Stable'''
| Существующая версия и эталон поведения при переносе
| Legacy-код сохранён в репозитории; при проверке ветки <code>main</code> и <code>kuzya-1.0</code> указывали на коммит <code>145bc857</code>
|-
| '''Kuzya 2.0'''
| Новая реализация на aiogram 3
| Разрабатывается в <code>feature/openai-bot-v2</code>; часть функций перенесена и проверена
|-
| '''Последняя подтверждённая точка 2.0'''
| Перенос команд модерации
| Коммит <code>b5095f4f</code> от 3 сентября 2026 года
|}

Главный принцип миграции:

'''Новая версия должна сохранить существующие возможности и архив MySQL. Замена Legacy допускается после проверки функционального паритета.'''

Базовые AI-функции уже присутствуют в ветке 2.0. Их наличие не означает завершения миграции или готовности будущего Guardian.

== Возможности Legacy Stable ==

Legacy служит исходной точкой для переноса следующих возможностей:

* выдача и снятие мута;
* временный и постоянный бан;
* предупреждения с указанием причины;
* хранение истории предупреждений;
* внутренний список администраторов Кузи;
* приветствие новых участников;
* информационные команды;
* вывод правил, ссылок и приглашений;
* информация о поддержке проекта;
* взаимодействие с публикациями Telegram-канала;
* информационные сообщения под новыми видео;
* хранение истории сообщений чата;
* изменение настроек и текстов административными командами;
* базовое взаимодействие с AI.

'''Этот список описывает исходную функциональность проекта, а не подтверждённый полный набор возможностей Kuzya 2.0.'''

== Что уже сделано в Kuzya 2.0 ==

=== Новая основа бота ===

В репозитории зафиксированы:

* создание новой версии на '''aiogram 3''';
* разделение обработчиков и сервисов;
* интеграция OpenAI через прокси;
* AI-ответы в личных сообщениях;
* сохранение истории в совместимом с Legacy формате;
* поддержка диалога через reply;
* перенос информационных команд;
* перенос приветствий;
* перенос внутренних администраторов;
* перенос предупреждений;
* перенос команд модерации.

Наличие базового reply-диалога не означает готовности полноценного контекста сообщества, долговременной памяти или RAG.

=== Контрольные коммиты ===

{| class="wikitable"
! Дата
! Коммит
! Изменение
|-
| 26 августа 2026
| <code>b55de2fa</code>
| Создание бота на aiogram 3
|-
| 26 августа 2026
| <code>38472685</code>
| Рабочая интеграция OpenAI через прокси
|-
| 2 сентября 2026
| <code>aa68090b</code>
| AI-ответы в личных сообщениях
|-
| 2 сентября 2026
| <code>476d2895</code>
| Удаление старого кода из ветки разработки и подготовка Kuzya 2.0
|-
| 2 сентября 2026
| <code>e691eb92</code>
| История в Legacy-БД и диалог через reply
|-
| 2 сентября 2026
| <code>da627b0c</code>
| Перенос информационных команд
|-
| 2 сентября 2026
| <code>346f7b69</code>
| Перенос приветствий
|-
| 3 сентября 2026
| <code>2a9a23ea</code>
| Перенос внутренних администраторов
|-
| 3 сентября 2026
| <code>2ae970c5</code>
| Перенос системы предупреждений
|-
| 3 сентября 2026
| <code>b5095f4f</code>
| Перенос команд модерации
|}

Источник: [https://gitlab.ramba-art.ru/Gans/noprodaction/-/commits/feature/openai-bot-v2 история ветки разработки].

=== Внутренние администраторы ===

Перенесена команда:

<pre>
!свой
</pre>

Команда применяется ответом на сообщение пользователя и добавляет его во внутренний список администраторов Кузи.

Подтверждено тестированием:

* распознавание команды;
* проверка инициатора по внутренней таблице администраторов;
* определение пользователя из reply;
* обнаружение уже зарегистрированного администратора;
* добавление нового администратора в MySQL.

При проверке в тестовом чате количество записей увеличилось с двух до трёх.

'''Внутренний администратор Кузи и администратор Telegram-чата — разные роли.''' Команда <code>!свой</code> управляет внутренним списком и сама по себе не выдаёт административные права Telegram.

=== Предупреждения ===

Перенесена команда:

<pre>
!предупреждение причина
</pre>

Команда применяется ответом на сообщение нарушителя.

Реализована цепочка:

# Проверка прав внутреннего администратора Кузи.
# Определение нарушителя и исходного сообщения.
# Запись предупреждения в MySQL.
# Подсчёт предупреждений пользователя.
# Удаление команды и сообщения-нарушения при наличии необходимых прав.
# Публикация уведомления в чате.

Проверено создание предупреждения с причиной <code>тест</code> и сохранение соответствующей записи в MySQL.

Добавлено создание отсутствующей таблицы предупреждений по совместимой схеме, включая поле <code>message_id</code>.

'''Уведомление в отдельном админ-чате и кнопка мута после предупреждения остаются незавершённой частью переноса.'''

=== Мут, размут и бан ===

В новой версии используются команды без старого суффикса <code>1</code>:

{| class="wikitable"
! Команда
! Назначение
! Состояние проверки
|-
| <code>!мут 30</code>
| Ограничить отправку сообщений на указанное число минут
| Временный мут проверен в тестовом чате
|-
| <code>!размут</code>
| Снять ограничения отправки сообщений
| Проверено в тестовом чате
|-
| <code>!бан 60</code>
| Исключить пользователя и запретить возвращение на указанное число минут
| Проверен временный бан на одну минуту
|-
| <code>!бан 0</code>
| Постоянный бан
| Предусмотрен кодом; отдельный live-тест не зафиксирован
|}

Команды применяются ответом на сообщение пользователя.

Инициатор должен иметь права администратора Telegram-чата. Для <code>!размут</code> также добавлена проверка прав, отсутствовавшая в разобранном Legacy-обработчике.

Результаты тестов мута, размута и временного бана подтверждены сообщениями бота и наблюдением за поведением тестового пользователя.

=== Среда разработки ===

По последним зафиксированным результатам новая версия запускалась в следующей среде:

{| class="wikitable"
! Параметр
! Значение
|-
| Узел / контейнер
| <code>noprodaction-v2</code>
|-
| Proxmox CT
| <code>503</code>
|-
| Каталог проекта
| <code>/opt/bots/noprodaction</code>
|-
| Ветка
| <code>feature/openai-bot-v2</code>
|-
| Сервис
| <code>kuzya.service</code>
|-
| Окружение Python
| <code>.venv</code>
|-
| Чат для проверок
| «Панды»
|}

Эти сведения описывают последнюю подтверждённую конфигурацию. Текущее состояние сервиса проверяется отдельно на сервере.

== Текущая точка остановки ==

'''Последний подтверждённый завершённый блок — перенос команд модерации.'''

Он сохранён в репозитории:

[https://gitlab.ramba-art.ru/Gans/noprodaction/-/commit/b5095f4f92f994d07c151fdedf399e27c556eb74 b5095f4f — Migrate legacy moderation commands].

Следующим обсуждалось восстановление действия '''«Мут на 120 минут»''' после предупреждения.

В ходе обсуждения предложено расширить этот механизм:

* создать отдельный служебный админ-чат;
* привязать его к основному сообществу;
* отправлять туда карточки предупреждений;
* принимать решение о муте голосованием внутренних администраторов.

'''Привязка чатов и коллективное голосование находятся на стадии проектирования. Их реализация в проверенном состоянии репозитория не подтверждена.'''

=== Ближайшие задачи ===

# Проверить актуальное состояние ветки, сервиса и соответствие запущенного кода репозиторию.
# Завершить уведомления о предупреждениях и действие мута на 120 минут.
# Согласовать правила привязки админ-чата и коллективного голосования.
# Составить полный список функций Legacy и проверить каждую в Kuzya 2.0.
# Завершить недостающие функции, включая проверку сценариев публикаций канала и изменения настроек.
# Подтвердить сохранность архива и совместимость работы с MySQL.
# После достижения паритета переходить к следующим этапам дорожной карты.

== Планируемая коллективная модерация ==

=== Привязка админ-чата ===

Для основного сообщества предлагается хранить привязку к отдельному служебному чату.

Пример предполагаемой схемы:

<pre>
Основной чат
|
| предупреждение
v
Привязанный админ-чат
|
| карточка нарушения
v
Голосование администраторов
|
v
Исполнение принятого решения
</pre>

В качестве интерфейса обсуждалась двухэтапная привязка:

<pre>
В основном чате:
!кодадминчата

В служебном чате:
!привязать <код>
</pre>

'''Названия команд приведены как предложение и пока не являются документированным рабочим интерфейсом.'''

=== Голосование за мут ===

Предлагаемая карточка:

<pre>
Новое предупреждение

Чат: название сообщества
Пользователь: имя / username
Причина: флуд
Всего предупреждений: 3
Выдал: администратор

Предложение: мут на 120 минут

[За мут] [Против]
</pre>

Предлагаемые правила:

* голосуют внутренние администраторы соответствующего основного чата;
* каждый администратор имеет один голос;
* до завершения голосования голос можно изменить;
* решение принимается при количестве голосов «за» больше половины состава;
* после исполнения решения голосование закрывается;
* обычные команды ручной модерации сохраняются.

Предлагаемая формула большинства:

<pre>
required_votes = admin_count // 2 + 1
</pre>

{| class="wikitable"
! Число администраторов
! Необходимо голосов «за»
|-
| 3
| 2
|-
| 4
| 3
|-
| 5
| 3
|-
| 6
| 4
|}

Перед реализацией необходимо определить:

* окончательный порог голосования;
* срок действия голосования;
* условия закрытия без принятого решения;
* порядок учёта изменений состава администраторов;
* поведение при ручном муте или бане во время голосования;
* защиту от повторного исполнения;
* обработку ошибок Telegram API.

В будущем этот механизм может принимать предложения Guardian. До появления Guardian он должен работать самостоятельно для ручных предупреждений.

== База данных и архив сообщества ==

Кузя использует '''MySQL''' для хранения истории и служебных данных.

По исторической оценке за август 2026 года архив содержал около '''497 000 сообщений'''. Это ориентир за указанный период, а не текущий результат подсчёта строк.

=== История сообщений ===

В Legacy-формате сохраняются, в частности:

* дата и время;
* идентификатор чата;
* Telegram ID пользователя;
* username;
* отображаемое имя;
* текст сообщения;
* Telegram message ID.

При миграции необходимо сохранять существующий архив и связи между записями.

=== Предупреждения ===

Для предупреждений используются отдельные записи, содержащие:

* пользователя;
* идентификатор исходного сообщения;
* причину;
* значение <code>number_of_warnings</code>;
* идентификатор и имя администратора;
* дату и время.

В перенесённой Legacy-логике каждое новое предупреждение создаёт строку со значением:

<pre>
number_of_warnings = 1
</pre>

Общее число предупреждений пользователя определяется суммированием этого поля.

Для связи с исходным сообщением предусмотрено поле <code>message_id</code>. Полноту исторических связей необходимо проверить до использования данных для интеллектуальной модерации.

При сопоставлении сообщений требуется учитывать также чат: одного <code>message_id</code> недостаточно для различения сообщений из разных чатов.

=== Использование архива для AI ===

История предупреждений может стать источником примеров нарушений, но ещё не считается готовым проверенным набором данных.

Перед использованием необходимо:

* проверить наличие исходных сообщений;
* проверить причины и корректность связей;
* восстановить доступный контекст;
* учесть изменения правил сообщества;
* отделить подтверждённые нарушения от спорных случаев;
* добавить примеры сообщений без нарушений.

== Архитектура проекта ==

=== Текущая реализация ===

В разработке используются отдельные обработчики и сервисы. Среди подтверждённых компонентов:

<pre>
main.py
bot/
handlers/
common.py
info.py
ai.py
history.py
admins.py
moderation.py
services/
database.py
</pre>

Схема показывает известные компоненты и не является полным перечнем файлов репозитория.

=== Целевая архитектура ===

В перспективе Кузя объединит три направления:

<pre>
КУЗЯ
|
+-------------+-------------+
| | |
v v v
Telegram Admin AI Assistant Guardian
| | |
mute / ban диалог анализ нарушений
warnings контекст предложения
rules поиск антиспам
channel RAG конфликты
| | |
+-------------+-------------+
|
v
RAMBA AI Router
</pre>

Это целевая схема. Guardian, RAG и подключение Кузи к RAMBA AI Router не относятся к подтверждённым завершённым функциям текущей версии.

== AI: текущая реализация и целевое направление ==

=== Текущая реализация ===

В ветке Kuzya 2.0 зафиксированы интеграция OpenAI через прокси, ответы в личных сообщениях и базовый диалог через reply.

Эти возможности необходимо учитывать при описании текущего состояния: AI уже присутствует, хотя миграция Legacy ещё не завершена.

=== Планируемая интеграция RAMBA AI Router ===

Целевое направление — использование локальной инфраструктуры RAMBA AI.

<pre>
Telegram
|
v
Кузя
|
v
RAMBA AI Router
|
+--> локальная модель для быстрых ответов
|
+--> локальная модель для сложных задач
|
+--> специализированная модель
|
+--> внешний AI при необходимости
</pre>

Telegram-бот должен обращаться к Router через согласованный интерфейс. Выбор и запуск моделей остаются ответственностью AI-инфраструктуры.

Локальные модели планируются как основа интеллектуальных функций, внешние API — как дополнительный инструмент.

'''Развитие RAMBA AI Router и его памяти является отдельной работой. Готовность функции Router не означает её автоматического подключения к Кузе.'''

== Дорожная карта ==

Номера версий ниже обозначают планируемые этапы развития, а не список выпущенных релизов.

{| class="wikitable"
! Этап
! Основная задача
! Статус по последней проверке
|-
| '''Legacy Stable'''
| Существующая функциональность и эталон миграции
| Исходная версия сохранена
|-
| '''2.0'''
| Новая архитектура и полный перенос существующих функций
| В работе; часть функций перенесена и проверена
|-
| '''2.1'''
| Нормализация MySQL с сохранением архива
| Запланировано
|-
| '''2.2'''
| Интеграция с RAMBA AI Router
| Запланировано; подключение Кузи не подтверждено
|-
| '''2.3'''
| Развитие диалогов и краткосрочного контекста
| Запланировано поверх базовых AI-ответов
|-
| '''2.4'''
| RAG по истории Telegram-чата
| Запланировано
|-
| '''3.0'''
| Основа Kuzya Guardian
| Запланировано
|-
| '''3.1'''
| Shadow Mode и оценка качества
| Запланировано
|-
| '''3.2'''
| Полуавтоматическая модерация
| Запланировано
|-
| '''3.3'''
| Репутация пользователей
| Запланировано
|-
| '''3.4'''
| Анализ развития конфликтов
| Запланировано
|-
| '''4.0'''
| Аналитика сообщества и дайджесты
| Запланировано
|-
| '''4.1'''
| Глубокая интеграция AI с правилами сообщества
| Запланировано
|-
| '''5.0'''
| Интеллектуальный Community Guardian
| Долгосрочная цель
|}

=== Kuzya 2.0 — функциональный паритет ===

Этап считается завершённым после проверки переноса всех необходимых возможностей Legacy.

Критерии готовности:

* административные и информационные команды работают;
* приветствия и сценарии публикаций канала проверены;
* настройки и тексты доступны в предусмотренных сценариях;
* история и предупреждения сохраняются корректно;
* права доступа соответствуют назначению команд;
* архив MySQL сохранён;
* известные различия с Legacy документированы;
* подготовлен порядок переключения и возврата к стабильной версии.

=== Kuzya 2.1 — нормализация MySQL ===

Планируется постепенный переход от таблиц отдельных чатов к общей структуре:

* <code>chats</code>;
* <code>users</code>;
* <code>messages</code>;
* <code>warnings</code>;
* <code>moderation_actions</code>;
* <code>admins</code>;
* <code>chat_settings</code>.

Миграция должна сохранять историю, идентификаторы и связи данных.

Для административных действий планируется учитывать источник решения:

* <code>human</code> — администратор;
* <code>ai</code> — AI;
* <code>rule</code> — автоматическое правило.

Для коллективных решений дополнительно потребуется хранить сведения о голосовании.

=== Kuzya 2.2 — RAMBA AI Router ===

Планируется подключение Кузи к общему AI-бэкенду.

Это позволит:

* менять модели независимо от Telegram-бота;
* использовать одну инфраструктуру для нескольких проектов;
* централизованно управлять маршрутизацией запросов;
* определить условия обращения к внешнему AI.

=== Kuzya 2.3 — контекст диалогов ===

Планируется развитие диалога с учётом:

* текущего вопроса;
* предыдущих реплик;
* цепочки reply;
* принадлежности сообщений к конкретному чату и разговору;
* настроек сообщества;
* доступных правил.

Контекст разных пользователей и чатов должен разделяться в соответствии с назначением диалога.

=== Kuzya 2.4 — RAG по истории ===

История чата не должна целиком передаваться модели при каждом запросе.

Планируемая схема:

<pre>
Архив MySQL
|
v
Подготовка и индексация
|
v
Поисковый индекс
|
v
Поиск подходящих фрагментов
|
v
Контекст для ответа AI
</pre>

Конкретный способ поиска и необходимость векторной базы определяются при реализации.

Пример будущего запроса:

<pre>
Кузя, мы раньше обсуждали эту проблему?
</pre>

Бот должен находить связанные обсуждения и, где возможно, показывать ссылки на исходные сообщения.

== Kuzya Guardian ==

'''Kuzya Guardian''' — планируемая система интеллектуальной помощи модераторам.

Она должна анализировать сообщения и контекст, находить возможные нарушения и предлагать действия.

=== Анализ сообщений ===

Предполагаемые категории:

* спам;
* флуд;
* нежелательная реклама;
* оскорбления;
* нарушения правил;
* провокации;
* эскалация конфликтов;
* повторные нарушения.

Планируемая последовательность:

<pre>
Новое сообщение
|
v
Проверки по правилам
|
v
AI-анализ сообщения и контекста
|
v
Оценка и объяснение
|
v
Рекомендация или передача модераторам
</pre>

=== Shadow Mode ===

На первом этапе Guardian работает в режиме наблюдения.

'''AI не получает право самостоятельно наказывать пользователей.'''

Он формирует предложения, а администрация подтверждает или отклоняет их.

Пример будущей карточки:

<pre>
Возможное нарушение

Пользователь: @username
Категория: оскорбление
Основание: пояснение с учётом контекста
Предлагаемое действие: предупреждение

[Нарушение] [Не нарушение] [Рассмотреть действие]
</pre>

Решения модераторов сохраняются для оценки качества системы.

=== Данные для оценки качества ===

Для рассмотренного случая планируется сохранять:

* исходное сообщение;
* доступный контекст;
* версию правил;
* оценку и объяснение AI;
* решение модератора;
* причину решения;
* фактически выполненное действие.

Сбор таких примеров не означает автоматического обучения модели. Обучение и изменение логики должны быть отдельными проверяемыми процедурами.

=== Полуавтоматическая модерация ===

Автоматические действия возможны только после оценки качества на реальных примерах.

Для каждой категории необходимо определить:

* допустимые действия;
* условия передачи решения человеку;
* ограничения автоматизации;
* порядок отмены;
* журнал действий;
* критерии отключения при ошибках.

Числовая оценка уверенности модели сама по себе не является достаточным основанием для наказания.

=== Репутация пользователей ===

В перспективе система сможет учитывать:

* предупреждения;
* подтверждённые муты и баны;
* повторяемость нарушений;
* отменённые решения;
* периоды без нарушений.

Репутация рассматривается как дополнительный контекст. Она не должна автоматически превращать любое сообщение пользователя в нарушение.

=== Анализ конфликтов ===

Планируется анализ последовательности сообщений нескольких участников.

Цель — обнаруживать развитие конфликта и предлагать своевременное вмешательство модераторов.

Возможные действия:

* рекомендация прекратить спор;
* уведомление администрации;
* передача контекста на рассмотрение.

== Аналитика сообщества ==

На последующих этапах Кузя сможет формировать:

* статистику сообщений;
* число активных участников;
* сведения о новых участниках;
* статистику предупреждений и других действий;
* основные темы обсуждения;
* ежедневные дайджесты.

Пример будущего дайджеста:

<pre>
Итоги дня

Основные обсуждения:
...

Полезные ссылки:
...

Модерация:
...

Вопросы, требующие внимания администрации:
...
</pre>

При формировании отчётов необходимо различать фактическую статистику из БД и выводы AI.

== Знание правил сообщества ==

Планируется включение действующих правил конкретного чата в контекст ответов.

Пример:

<pre>
Кузя, можно здесь публиковать ссылку на YouTube?
</pre>

Ответ должен опираться на правила выбранного сообщества.

Для объяснения модерации желательно указывать:

* применённый пункт правил;
* основание решения;
* источник решения — человек, правило или AI;
* возможность пересмотра администрацией.

== Разделение Кузи и RAMBA Bot ==

Кузя специализируется на Telegram-сообществе:

* участники;
* правила;
* диалоги;
* история;
* модерация;
* аналитика.

Управление серверами и инфраструктурой относится к отдельному '''RAMBA Bot'''.

Целевая схема:

<pre>
Кузя RAMBA Bot
| |
| сообщество | инфраструктура
| |
+---------------+---------------+
|
v
RAMBA AI Router
</pre>

Общий AI-бэкенд не означает общие права доступа или смешивание контекста двух ботов.

== Принципы проекта ==

# '''Сохранять существующие функции.''' Завершить и проверить перенос Legacy перед заменой стабильной версии.
# '''Сохранять архив.''' Не терять историю MySQL, предупреждения и связи между данными.
# '''Разделять готовое и запланированное.''' Документировать реализацию, тестирование и развёртывание отдельно.
# '''Сохранять контроль администрации.''' Решения должны быть объяснимыми и доступными для пересмотра.
# '''Вводить автоматизацию постепенно.''' Сначала наблюдение и оценка качества, затем ограниченные действия.
# '''Развивать локальный AI как целевую основу.''' Подключение Router проводить отдельным проверяемым этапом.
# '''Сохранять специализацию Кузи.''' Инфраструктурные задачи выносить в RAMBA Bot.
# '''Фиксировать рабочие этапы.''' Сохранять изменения в Git и обновлять документацию по подтверждённым результатам.

== Конечная цель ==

Кузя должен стать помощником сообщества, который:

* выполняет административные команды;
* помогает участникам;
* находит накопленные знания;
* поддерживает содержательный диалог;
* предлагает модераторам обоснованные решения;
* формирует полезные отчёты;
* оставляет окончательный контроль за администрацией.

'''Ближайшая практическая цель — завершить Kuzya 2.0, подтвердить паритет с Legacy и сохранить существующий архив.'''

[[Категория:RAMBA]]
[[Категория:RAMBA AI]]
[[Категория:Telegram]]
[[Категория:Боты]]

HAPP Gateway

2026-09-16T21:24:22Z

Artem: Новая страница: «{| class="wikitable" style="width:100%;" |- ! style="background:#d9ead3; width:220px;" | Статус | '''PRODUCTION / ACTIVE''' |- ! Текущий режим | Automatic healthcheck + hourly optimization |- ! Основной идентификатор | <code>BYPASS</code> |- ! Автопереключение | Включено |- ! Rollback | Включён |- ! Healthcheck | Каждые ~3 минуты |- ! Optimizer | Примерно 1 раз в ч...»

{| class="wikitable" style="width:100%;"
|-
! style="background:#d9ead3; width:220px;" | Статус
| '''PRODUCTION / ACTIVE'''
|-
! Текущий режим
| Automatic healthcheck + hourly optimization
|-
! Основной идентификатор
| <code>BYPASS</code>
|-
! Автопереключение
| Включено
|-
! Rollback
| Включён
|-
! Healthcheck
| Каждые ~3 минуты
|-
! Optimizer
| Примерно 1 раз в час
|-
! Порог переключения
| 15%
|-
! Последнее документирование
| 17.09.2026
|}

= HAPP Gateway: автоматический выбор сервера и отказоустойчивость =

== Назначение ==

'''HAPP Gateway''' — шлюз для выборочной маршрутизации трафика через HAPP/VLESS.

Система работает в LXC-контейнере и предоставляет одновременно:

* локальный HTTP proxy;
* локальный SOCKS proxy;
* HTTP/SOCKS proxy для устройств локальной сети;
* TUN-интерфейс для policy routing;
* автоматический контроль работоспособности HAPP;
* автоматическое обновление подписки;
* автоматический benchmark доступных серверов;
* автоматическое аварийное переключение;
* периодическую оптимизацию выбора сервера.

{| class="wikitable"
! Параметр !! Значение
|-
| Контейнер || <code>happ-gateway</code>
|-
| IP || <code>192.168.1.52</code>
|-
| ОС || Debian 13
|-
| HAPP CLI || <code>/usr/local/bin/happ</code>
|-
| HAPP home || <code>/root/.config/happ-cli</code>
|-
| HTTP proxy локальный || <code>127.0.0.1:10809</code>
|-
| SOCKS proxy локальный || <code>127.0.0.1:10808</code>
|-
| HTTP proxy LAN || <code>192.168.1.52:11081</code>
|-
| SOCKS proxy LAN || <code>192.168.1.52:11080</code>
|-
| TUN interface || <code>thapp</code>
|-
| Policy routing table || <code>100</code>
|}

Основные задачи системы:

* автоматически контролировать работоспособность текущего HAPP-сервера;
* обновлять список серверов;
* тестировать доступные серверы;
* выбирать наиболее быстрый рабочий сервер;
* автоматически переключаться при отказе;
* не переключаться без необходимости;
* синхронизировать Proxy и TUN;
* сохранять прямой маршрут до upstream HAPP-сервера;
* не допускать рекурсивной маршрутизации HAPP через самого себя;
* автоматически очищать временные маршруты после benchmark;
* выполнять проверку нового сервера после переключения;
* выполнять rollback при неудачном переключении.

----

== Общая схема ==

<pre>
Internet
^
|
HAPP upstream
^
|
direct route table 100
^
|
+-------------------+
| happ-gateway |
| 192.168.1.52 |
+-------------------+
| |
Proxy mode TUN mode
| |
127.0.0.1:10809 thapp
127.0.0.1:10808
|
socat LAN
|
+----------+----------+
| |
HTTP 11081 SOCKS 11080
</pre>

Управление системой выполняют два независимых контура:

<pre>
+----------------------+
| HAPP CONTROL |
+----------------------+
| |
| |
HEALTHCHECK OPTIMIZER
~3 минуты ~1 час
| |
+------+-------+
|
HAPP SWITCH
|
Proxy + TUN
</pre>

----

== Основные systemd-службы ==

=== happ-gateway.service ===

Основной HAPP Proxy.

Файл:

<pre>
/etc/systemd/system/happ-gateway.service
</pre>

Пример текущей команды запуска:

<pre>
ExecStart=/usr/local/bin/happ \
--home /root/.config/happ-cli \
connect 60 \
--mode proxy \
--socks 10808 \
--http 10809
</pre>

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

<pre>
ExecStartPre=/usr/local/sbin/happ-wait-network.sh
ExecStartPre=/usr/local/sbin/happ-prep-routes.sh
</pre>

<code>happ-prep-routes.sh</code> подготавливает прямые маршруты, необходимые HAPP до создания Proxy/TUN.

----

=== happ-tun.service ===

Запускает HAPP в режиме TUN.

Файл:

<pre>
/etc/systemd/system/happ-tun.service
</pre>

Пример:

<pre>
ExecStart=/usr/local/bin/happ \
--home /root/.config/happ-cli \
connect 60 \
--mode tun
</pre>

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

<pre>
ExecStartPre=/usr/local/sbin/happ-wait-network.sh
ExecStartPre=/usr/local/sbin/happ-prep-routes.sh
</pre>

После создания TUN-интерфейса:

<pre>
ExecStartPost=/usr/local/sbin/happ-tun-routes.sh
</pre>

----

=== happ-http.service ===

Публикует HTTP proxy в локальную сеть.

<pre>
192.168.1.52:11081
|
v
127.0.0.1:10809
</pre>

Используется <code>socat</code>.

Служба связана с <code>happ-gateway.service</code>, поэтому при перезапуске основного gateway LAN proxy также перезапускается.

----

=== happ-socat.service ===

Публикует SOCKS proxy:

<pre>
192.168.1.52:11080
|
v
127.0.0.1:10808
</pre>

Также используется <code>socat</code>.

----

== Идентификация серверов ==

'''Важно: HAPP ID нельзя считать постоянным идентификатором сервера.'''

После обновления подписки номера HAPP могут измениться.

Например:

<pre>
ОБХОД №8 -> HAPP #60
</pre>

После следующего обновления подписки тот же сервер теоретически может получить другой ID:

<pre>
ОБХОД №8 -> HAPP #47
</pre>

Поэтому постоянным логическим идентификатором системы является:

<pre>
BYPASS=N
</pre>

HAPP ID считается временным.

----

== Текущее состояние ==

Состояние production хранится в:

<pre>
/var/lib/happ/current
</pre>

Пример:

<pre>
BYPASS=8
ID=60
ENDPOINT=selec180.apruxdomain.website:444
UPDATED=2026-09-16T23:43:32+03:00
</pre>

Здесь:

{| class="wikitable"
! Поле !! Назначение
|-
| <code>BYPASS</code> || Постоянный логический номер обхода
|-
| <code>ID</code> || Текущий временный HAPP ID
|-
| <code>ENDPOINT</code> || Текущий upstream endpoint
|-
| <code>UPDATED</code> || Время последнего изменения production mapping
|}

----

== Почему нельзя использовать только endpoint ==

В подписке могут существовать несколько записей с одним и тем же endpoint.

Например:

<pre>
HAPP #43 selec180.apruxdomain.website:444 АВТО ОБХОД
HAPP #60 selec180.apruxdomain.website:444 ОБХОД №8
</pre>

Поэтому endpoint также не является достаточным идентификатором.

Для production используется именно явный тег:

<pre>
ОБХОД №N
</pre>

Автоматические записи вида:

<pre>
АВТО ОБХОД
</pre>

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

----

== Resolver BYPASS -> HAPP ID ==

Скрипт:

<pre>
/usr/local/sbin/happ-resolve-bypass.sh
</pre>

Назначение:

<pre>
ОБХОД №8
|
v
актуальный список HAPP
|
v
ID / protocol / endpoint
</pre>

Пример:

<pre>
/usr/local/sbin/happ-resolve-bypass.sh 8
</pre>

Результат:

<pre>
BYPASS=8
ID=60
PROTOCOL=vless
ENDPOINT=selec180.apruxdomain.website:444
</pre>

Таким образом остальные компоненты системы работают с постоянным <code>BYPASS</code>, а resolver определяет актуальный HAPP ID.

----

== Подготовка маршрутов ==

Скрипт:

<pre>
/usr/local/sbin/happ-prep-routes.sh
</pre>

Он динамически определяет:

* IP сервера подписки;
* IP текущего HAPP upstream;
* текущий endpoint HAPP;
* необходимые direct routes.

Пример:

<pre>
DIRECT: sub.renawave.space -> 37.9.4.201 via 192.168.1.1 dev eth0 table 100
DIRECT: selec180.apruxdomain.website -> 31.129.42.180 via 192.168.1.1 dev eth0 table 100

Current HAPP server #60 endpoint selec180.apruxdomain.website:444 prepared
</pre>

Это критически важно.

Без direct route может возникнуть рекурсивная маршрутизация:

<pre>
HAPP upstream
^
|
HAPP
^
|
thapp
^
|
HAPP
^
|
thapp
...
</pre>

То есть HAPP пытается подключиться к собственному upstream через собственный TUN.

Результатом становятся timeout, TLS error или полная потеря доступа к upstream.

----

== Policy routing ==

Используется routing table:

<pre>
100
</pre>

Основная схема:

<pre>
0.0.0.0/1 dev thapp
128.0.0.0/1 dev thapp
</pre>

То есть основной интернет-трафик направляется через HAPP TUN.

Локальные/служебные сети обходят TUN.

Пример:

<pre>
10.0.0.0/8 via 192.168.1.1 dev eth0
172.16.0.0/12 via 192.168.1.1 dev eth0
192.168.0.0/16 via 192.168.1.1 dev eth0

10.20.0.0/24 via 192.168.1.53 dev eth0
</pre>

Дополнительно динамически создаются прямые маршруты до:

* текущего HAPP upstream;
* сервера подписки.

Пример состояния на момент документирования:

<pre>
31.129.42.180 via 192.168.1.1 dev eth0
37.9.4.201 via 192.168.1.1 dev eth0
</pre>

Проверка:

<pre>
ip route show table 100
</pre>

'''Важно:''' IP-адреса <code>31.129.42.180</code> и <code>37.9.4.201</code> приведены как пример состояния системы на момент документирования. Они разрешаются динамически и могут измениться.

----

== happ-tun-routes.sh ==

Файл:

<pre>
/usr/local/sbin/happ-tun-routes.sh
</pre>

После финальной очистки конфигурации в нём больше нет IP конкретных HAPP-серверов или сервера подписки.

Сохраняются только инфраструктурные маршруты:

<pre>
192.168.1.0/24
10.20.0.0/24
</pre>

Пример логики:

<pre>
ip route replace table 100 \
192.168.1.0/24 dev eth0 src 192.168.1.52

ip route replace table 100 \
10.20.0.0/24 via 192.168.1.53 dev eth0
</pre>

Таким образом смена HAPP upstream не требует ручного изменения <code>happ-tun-routes.sh</code>.

----

== Обновление подписки ==

Скрипт:

<pre>
/usr/local/sbin/happ-refresh-current.sh
</pre>

Алгоритм:

<pre>
прочитать текущий BYPASS
|
v
direct route к subscription
|
v
happ sub update ramba
|
v
найти тот же ОБХОД №N
|
v
получить актуальный HAPP ID
|
+---- ID/endpoint не изменились
| |
| v
| ничего не перезапускать
|
+---- mapping изменился
|
v
обновить systemd units
|
v
restart
|
v
verify
</pre>

Пример:

<pre>
Current selection: ОБХОД №8
Old ID: #60
New ID: #60
Old endpoint: selec180.apruxdomain.website:444
New endpoint: selec180.apruxdomain.website:444

REFRESH OK: mapping unchanged
</pre>

Если mapping не изменился, production не перезапускается.

----

== Benchmark серверов ==

Скрипт:

<pre>
/usr/local/sbin/happ-benchmark.sh
</pre>

Benchmark проверяет только явно заданные серверы:

<pre>
ОБХОД №1
ОБХОД №2
ОБХОД №3
...
</pre>

Записи:

<pre>
АВТО ОБХОД
</pre>

исключаются.

Протокол <code>hysteria2</code> в текущей реализации benchmark пропускается:

<pre>
SKIP (hysteria2)
</pre>

Тестируются VLESS-кандидаты.

----

== Алгоритм benchmark ==

Для каждого кандидата выполняется:

<pre>
endpoint
|
v
direct /32 route
|
v
temporary HAPP proxy
|
v
warm-up
|
v
Telegram request x3
|
v
median
|
v
WORKING / REJECTED
</pre>

Основная проверка выполняется запросом:

<pre>
https://api.telegram.org
</pre>

Рабочий результат:

<pre>
HTTP 302
</pre>

Ping или обычное TCP-соединение не используются как основной критерий.

Таким образом проверяется не просто доступность IP, а реальное прохождение HTTPS-трафика через конкретный HAPP-сервер.

----

== Расчёт скорости ==

Для каждого кандидата выполняется три теста.

Пример:

<pre>
test 1: 0.201306s OK
test 2: 0.221358s OK
test 3: 5.189619s OK
</pre>

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

<pre>
MEDIAN: 0.221358s
</pre>

Это позволяет уменьшить влияние одиночного всплеска задержки.

Для признания сервера рабочим требуется не менее двух успешных запросов из трёх.

Если условие не выполняется:

<pre>
REJECTED
</pre>

----

== Пример результата benchmark ==

<pre>
WORKING BYPASS SERVERS

ОБХОД №5 HAPP #57 188.225.82.56:7443 0.221358s
ОБХОД №8 HAPP #60 selec180.apruxdomain.website:444 0.223532s
ОБХОД №4 HAPP #56 188.225.58.133:7443 0.366614s
ОБХОД №13 HAPP #65 selec248.apruxdomain.website:444 0.611755s

BEST: BYPASS=5 ID=57 ENDPOINT=188.225.82.56:7443 MEDIAN=0.221358s
</pre>

----

== Очистка временных маршрутов ==

Во время benchmark для каждого upstream создаётся временный direct <code>/32</code> route.

Например:

<pre>
188.225.82.56/32
188.225.58.133/32
...
</pre>

После завершения benchmark временные candidate routes автоматически удаляются.

Cleanup сначала завершает временный HAPP-процесс benchmark, затем удаляет созданные маршруты.

После очистки вызывается:

<pre>
/usr/local/sbin/happ-prep-routes.sh
</pre>

Он повторно создаёт необходимые production routes.

Нормальное состояние после benchmark содержит только необходимые dynamic direct routes.

Пример на момент документирования:

<pre>
31.129.42.180 via 192.168.1.1 dev eth0
37.9.4.201 via 192.168.1.1 dev eth0
</pre>

Временные маршруты других кандидатов после benchmark отсутствуют.

----

== Переключение HAPP-сервера ==

Скрипт:

<pre>
/usr/local/sbin/happ-switch.sh
</pre>

На вход передаётся '''BYPASS''', а не HAPP ID.

Пример:

<pre>
/usr/local/sbin/happ-switch.sh 8
</pre>

Алгоритм:

<pre>
ОБХОД №8
|
v
resolver
|
v
актуальный HAPP ID
|
v
direct route
|
v
backup конфигурации
|
v
обновление gateway + TUN
|
v
restart Proxy
|
v
Telegram readiness check
|
v
restart TUN
|
v
LAN Telegram check
|
+-------- OK --------> сохранить state
|
+-------- FAIL ------> rollback
</pre>

После запуска нового Proxy выполняется readiness-loop.

Пример успешной проверки:

<pre>
HTTP=302
</pre>

Только после успешной проверки Proxy выполняется переключение TUN.

----

== Rollback ==

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

* <code>happ-gateway.service</code>;
* <code>happ-tun.service</code>;
* <code>/var/lib/happ/current</code>.

Если новый сервер не проходит проверку, выполняется автоматический rollback.

При rollback старый BYPASS заново разрешается через актуальный список подписки.

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

Логика:

<pre>
new server
|
v
verification
|
+--+--+
| |
OK FAIL
| |
save resolve old BYPASS
|
v
restore
|
v
restart
</pre>

----

== Healthcheck ==

Скрипт:

<pre>
/usr/local/sbin/happ-healthcheck.sh
</pre>

Systemd timer:

<pre>
happ-healthcheck.timer
</pre>

Период проверки:

<pre>
примерно каждые 3 минуты
</pre>

Проверяется реальный Telegram-запрос через production HTTP proxy.

Пример:

<pre>
HEALTHY: Telegram HTTP=302 TIME=0.212754s
</pre>

Счётчик последовательных ошибок хранится:

<pre>
/var/lib/happ/fail-count
</pre>

При успешной проверке:

<pre>
fail-count = 0
</pre>

----

== Аварийное восстановление ==

Одна ошибка не приводит к немедленному переключению.

Используется защита от случайных кратковременных сбоев.

Алгоритм:

<pre>
Telegram check
|
v
FAIL
|
v
fail-count = 1
|
v
ждать
|
v
следующий healthcheck
|
v
FAIL
|
v
fail-count = 2
|
v
refresh subscription
|
v
benchmark
|
v
best working BYPASS
|
v
switch
</pre>

Таким образом переключение выполняется после двух последовательных ошибок.

----

== Hourly Optimizer ==

Скрипт:

<pre>
/usr/local/sbin/happ-optimizer.sh
</pre>

Systemd timer:

<pre>
happ-optimizer.timer
</pre>

Период:

<pre>
примерно один раз в час
</pre>

Используется также:

<pre>
RandomizedDelaySec=5min
</pre>

Поэтому фактическое время запуска может немного отличаться от ровного часа.

----

== Алгоритм Optimizer ==

Optimizer выполняет:

# обновление подписки;
# синхронизацию текущего BYPASS;
# benchmark доступных серверов;
# определение median текущего сервера;
# определение BEST;
# сравнение производительности;
# принятие решения KEEP/SWITCH.

Схема:

<pre>
sub update
|
v
sync current BYPASS
|
v
benchmark
|
+---------------------+
| |
v v
CURRENT BEST
| |
+----------+----------+
|
v
comparison
|
+-----+-----+
| |
KEEP SWITCH
</pre>

----

== Защита от постоянных переключений ==

Используется порог:

<pre>
MIN_GAIN_PERCENT=15
</pre>

Новый сервер должен быть минимум на 15% быстрее текущего.

Если выигрыш меньше 15%, переключение не выполняется.

Пример:

<pre>
Current: ОБХОД №8
Best: ОБХОД №5 (0.221358s)

Current median: 0.223532s
Improvement: 0.97%
Required: 15%

KEEP: improvement is below threshold.
</pre>

Это предотвращает бессмысленные переключения из-за разницы в несколько миллисекунд.

Если текущий сервер вообще не проходит benchmark, правило 15% не применяется.

В этом случае выполняется аварийное переключение на лучший рабочий BYPASS.

----

== Блокировка параллельных операций ==

Управляющие скрипты используют общий lock-файл:

<pre>
/run/happ-control.lock
</pre>

через:

<pre>
flock
</pre>

Он защищает основные управляющие операции от параллельного выполнения.

При передаче управления в <code>happ-switch.sh</code> вызывающий контроллер освобождает блокировку, после чего <code>happ-switch.sh</code> получает её самостоятельно.

Это существенно снижает риск одновременного выполнения:

* healthcheck;
* optimizer;
* ручного switch.

----

== Текущий production ==

На момент документирования:

<pre>
BYPASS=8
HAPP ID=60
Endpoint=selec180.apruxdomain.website:444
Resolved IP=31.129.42.180
</pre>

Типичная измеренная задержка Telegram:

<pre>
~0.2–0.3 сек
</pre>

'''Важно:'''

<code>HAPP ID=60</code> не является постоянным.

Также IP:

<pre>
31.129.42.180
</pre>

является результатом DNS-разрешения endpoint на момент документирования и может измениться.

Постоянным логическим идентификатором является:

<pre>
BYPASS=8
</pre>

----

== Systemd timers ==

Проверка:

<pre>
systemctl list-timers --all --no-pager | grep happ
</pre>

Нормальное состояние:

<pre>
happ-healthcheck.timer active
happ-optimizer.timer active
happ-autoselect.timer inactive
</pre>

Старый:

<pre>
happ-autoselect.timer
</pre>

оставлен выключенным.

Он не учитывает новую модель:

<pre>
BYPASS -> dynamic HAPP ID
</pre>

и не должен использоваться совместно с новой системой.

----

== Быстрая диагностика ==

=== Проверить production ===

<pre>
/usr/local/sbin/happ-healthcheck.sh
</pre>

Ожидаемый результат:

<pre>
HEALTHY: Telegram HTTP=302 TIME=...
</pre>

----

=== Проверить текущее состояние ===

<pre>
cat /var/lib/happ/current
</pre>

Пример:

<pre>
BYPASS=8
ID=60
ENDPOINT=selec180.apruxdomain.website:444
UPDATED=...
</pre>

----

=== Проверить маршруты ===

<pre>
ip route show table 100
</pre>

----

=== Проверить Proxy из LAN ===

<pre>
curl --max-time 8 \
-x http://192.168.1.52:11081 \
-o /dev/null -sS \
-w 'HTTP=%{http_code} TIME=%{time_total}s\n' \
https://api.telegram.org
</pre>

Ожидается:

<pre>
HTTP=302
</pre>

----

=== Проверить HAPP список ===

<pre>
/usr/local/bin/happ \
--home /root/.config/happ-cli \
list
</pre>

----

=== Проверить конкретный BYPASS ===

Например, ОБХОД №8:

<pre>
/usr/local/sbin/happ-resolve-bypass.sh 8
</pre>

----

=== Обновить подписку и синхронизировать production ===

<pre>
/usr/local/sbin/happ-refresh-current.sh
</pre>

----

=== Запустить benchmark вручную ===

<pre>
/usr/local/sbin/happ-benchmark.sh
</pre>

Benchmark '''не переключает''' production самостоятельно.

----

=== Запустить optimizer вручную ===

<pre>
/usr/local/sbin/happ-optimizer.sh
</pre>

Optimizer уже может принять решение о переключении.

----

=== Переключиться вручную ===

Например, на ОБХОД №5:

<pre>
/usr/local/sbin/happ-switch.sh 5
</pre>

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

----

=== Проверить службы ===

<pre>
systemctl status happ-gateway \
happ-tun \
happ-http \
happ-socat \
--no-pager
</pre>

----

=== Проверить таймеры ===

<pre>
systemctl status happ-healthcheck.timer --no-pager
systemctl status happ-optimizer.timer --no-pager
</pre>

----

=== Последние логи healthcheck ===

<pre>
journalctl -u happ-healthcheck.service -n 50 --no-pager
</pre>

----

=== Последние логи optimizer ===

<pre>
journalctl -u happ-optimizer.service -n 100 --no-pager
</pre>

----

== Основные файлы ==

{| class="wikitable"
! Файл !! Назначение
|-
| <code>/usr/local/sbin/happ-wait-network.sh</code>
| Ожидание готовности сети
|-
| <code>/usr/local/sbin/happ-prep-routes.sh</code>
| Подготовка dynamic direct routes
|-
| <code>/usr/local/sbin/happ-tun-routes.sh</code>
| Базовые маршруты после запуска TUN
|-
| <code>/usr/local/sbin/happ-resolve-bypass.sh</code>
| BYPASS -> ID / protocol / endpoint
|-
| <code>/usr/local/sbin/happ-refresh-current.sh</code>
| Обновление подписки и синхронизация текущего BYPASS
|-
| <code>/usr/local/sbin/happ-benchmark.sh</code>
| Benchmark HAPP-серверов
|-
| <code>/usr/local/sbin/happ-switch.sh</code>
| Безопасное переключение production
|-
| <code>/usr/local/sbin/happ-healthcheck.sh</code>
| Аварийный контроль production
|-
| <code>/usr/local/sbin/happ-optimizer.sh</code>
| Плановый выбор более быстрого сервера
|-
| <code>/var/lib/happ/current</code>
| Текущее production-состояние
|-
| <code>/var/lib/happ/fail-count</code>
| Счётчик последовательных отказов
|-
| <code>/run/happ-control.lock</code>
| Блокировка управляющих операций
|}

----

== Основные systemd units ==

{| class="wikitable"
! Unit !! Назначение
|-
| <code>happ-gateway.service</code>
| Основной HTTP/SOCKS HAPP Proxy
|-
| <code>happ-tun.service</code>
| HAPP TUN
|-
| <code>happ-http.service</code>
| Публикация HTTP proxy в LAN
|-
| <code>happ-socat.service</code>
| Публикация SOCKS proxy в LAN
|-
| <code>happ-healthcheck.service</code>
| Проверка production
|-
| <code>happ-healthcheck.timer</code>
| Запуск healthcheck примерно каждые 3 минуты
|-
| <code>happ-optimizer.service</code>
| Полный цикл оптимизации
|-
| <code>happ-optimizer.timer</code>
| Запуск optimizer примерно раз в час
|-
| <code>happ-autoselect.timer</code>
| Старый механизм — отключён
|}

----

== Логика системы целиком ==

<pre>
HAPP Gateway
|
+-----------------+-----------------+
| |
каждые ~3 мин каждый ~1 час
HEALTHCHECK OPTIMIZER
| |
v v
Telegram через Proxy sub update
| |
+-----+-----+ v
| | sync BYPASS
| | |
HEALTHY FAIL v
| | benchmark
| | |
ничего первый FAIL +-----+-----+
| | |
ждать CURRENT BEST
| | |
следующий check +-----+-----+
| |
FAIL v
| comparison
v |
второй FAIL +-----+-----+
| | |
v < 15% >= 15%
refresh | |
| v v
v KEEP SWITCH
benchmark |
| |
v |
best working BYPASS |
| |
v |
SWITCH <------------------------------+
|
v
resolve BYPASS
|
v
direct route
|
v
restart Proxy
|
v
Telegram verify
|
+-----+-----+
| |
FAIL OK
| |
v v
rollback restart TUN
|
v
LAN verification
|
+----+----+
| |
FAIL OK
| |
v v
rollback SAVE STATE
</pre>

----

== Проверенное production-состояние ==

На момент завершения настройки система прошла полный цикл:

<pre>
refresh subscription OK
BYPASS resolution OK
benchmark OK
temporary route cleanup OK
optimizer decision OK
production healthcheck OK
Telegram HTTP 302 OK
</pre>

Последний контрольный optimizer:

<pre>
Current: ОБХОД №8
Best: ОБХОД №5

Current median: 0.223532s
Best median: 0.221358s

Improvement: 0.97%
Required: 15%

KEEP
</pre>

После benchmark таблица маршрутизации была автоматически очищена от временных candidate routes.

Production после полного цикла:

<pre>
HEALTHY
Telegram HTTP=302
TIME ~0.27s
</pre>

----

== Результат ==

После внедрения новой схемы HAPP Gateway:

* не зависит от постоянства HAPP ID;
* использует <code>BYPASS</code> как постоянный логический идентификатор;
* автоматически обновляет подписку;
* синхронизирует BYPASS с актуальным HAPP ID;
* автоматически восстанавливает direct routes;
* предотвращает рекурсивную маршрутизацию upstream через HAPP TUN;
* контролирует реальную доступность Telegram;
* тестирует серверы через реальный HAPP proxy;
* использует медиану вместо одного измерения;
* требует минимум два успешных теста из трёх;
* не переключается при незначительной разнице скорости;
* автоматически переключается при отказе;
* синхронно обновляет Proxy и TUN;
* выполняет post-switch verification;
* поддерживает автоматический rollback;
* автоматически очищает временные benchmark routes;
* координирует управляющие операции через общий <code>flock</code>;
* автоматически выполняет healthcheck примерно каждые 3 минуты;
* автоматически выполняет полную оптимизацию примерно раз в час.

'''Текущая схема считается production-ready.'''

----

== История конфигурации ==

'''17.09.2026'''

* внедрён постоянный идентификатор <code>BYPASS</code>;
* реализован resolver <code>BYPASS -> HAPP ID</code>;
* реализовано динамическое обновление подписки;
* реализована автоматическая синхронизация HAPP ID;
* реализован benchmark VLESS-серверов;
* основной критерий проверки переведён на реальный HTTPS-запрос к Telegram;
* реализован расчёт median;
* реализован безопасный switch Proxy + TUN;
* реализован rollback;
* добавлен healthcheck timer;
* добавлен hourly optimizer;
* установлен порог переключения 15%;
* добавлена очистка временных <code>/32</code> routes;
* удалены hardcoded upstream IP из <code>happ-tun-routes.sh</code>;
* старый <code>happ-autoselect.timer</code> отключён;
* выполнена финальная production-проверка.

[[Категория:Infrastructure]]
[[Категория:VPN]]
[[Категория:HAPP]]
[[Категория:Networking]]

Мониторинг

2026-09-10T21:56:33Z

Artem:

Мониторинг

2026-09-10T21:27:27Z

Artem:

RAMBA 20Selective VPN Gateway

2026-09-10T21:10:58Z

Artem: Artem переименовал страницу RAMBA 20Selective VPN Gateway в RAMBA Selective VPN Gateway

#перенаправление [[RAMBA Selective VPN Gateway]]

RAMBA Selective VPN Gateway

2026-09-10T21:10:58Z

Artem: Artem переименовал страницу RAMBA 20Selective VPN Gateway в RAMBA Selective VPN Gateway

{{DISPLAYTITLE:RAMBA Selective VPN Gateway}}

= RAMBA Selective VPN Gateway =

'''RAMBA Selective VPN Gateway''' — шлюз селективной маршрутизации трафика на базе
'''WireGuard + nftables + dnsmasq + HAPP/VLESS'''.

Система позволяет подключать мобильные устройства к домашней сети через WireGuard
и отправлять через HAPP только трафик выбранных сервисов.

Остальной интернет-трафик выходит напрямую через основной маршрутизатор.

По состоянию на сентябрь 2026 года через HAPP маршрутизируются:

* YouTube
* Instagram
* Telegram
* OpenAI / ChatGPT

Discord тестировался, однако был исключён из селективной маршрутизации из-за проблем
с голосовым UDP-трафиком.

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

Основная схема:

<pre>
INTERNET
|
Public IP / Router
|
UDP 51821 -> 51820
|
v
+---------------------+
| CT103 vpn-gateway |
| 192.168.1.53 |
| |
| WireGuard |
| dnsmasq |
| nftables |
| policy routing |
+----------+----------+
|
+-----------+-----------+
| |
обычный трафик выбранный трафик
| |
v v
192.168.1.1 192.168.1.52
основной роутер |
v
+--------------------+
| CT502 happ-gateway |
| HAPP / VLESS |
+---------+----------+
|
v
VPN
</pre>

Клиент WireGuard использует:

<pre>
10.20.0.0/24
</pre>

Адрес шлюза:

<pre>
10.20.0.1
</pre>

== Компоненты ==

{| class="wikitable"
! Компонент
! Адрес
! Назначение
|-
| CT103 vpn-gateway
| 192.168.1.53
| WireGuard, DNS, nftables, selective routing
|-
| CT502 happ-gateway
| 192.168.1.52
| HAPP/VLESS VPN gateway
|-
| Основной маршрутизатор
| 192.168.1.1
| Обычный выход в Интернет
|-
| WireGuard
| 10.20.0.1/24
| VPN-сеть клиентов
|}

== WireGuard ==

WireGuard работает внутри LXC-контейнера '''CT103'''.

Основной интерфейс:

<pre>
wg0
</pre>

Адрес:

<pre>
10.20.0.1/24
</pre>

Порт WireGuard внутри сети:

<pre>
UDP 51820
</pre>

На внешнем маршрутизаторе настроен проброс:

<pre>
WAN UDP 51821
|
v
192.168.1.53:51820
</pre>

Клиенты используют:

<pre>
AllowedIPs = 0.0.0.0/0
DNS = 10.20.0.1
</pre>

Таким образом весь IPv4-трафик клиента сначала поступает на '''vpn-gateway''',
а уже там принимается решение о дальнейшем маршруте.

== Принцип селективной маршрутизации ==

Для выбранного трафика устанавливается:

<pre>
fwmark 0x1
</pre>

На CT103 существует отдельная таблица маршрутизации:

<pre>
table 200
</pre>

Правило:

<pre>
100: from all fwmark 0x1 lookup 200
</pre>

Таблица 200:

<pre>
default via 192.168.1.52 dev eth0
192.168.1.0/24 dev eth0 scope link src 192.168.1.53
</pre>

Таким образом:

<pre>
без mark
|
v
192.168.1.1
|
v
обычный Интернет

mark 0x1
|
v
table 200
|
v
192.168.1.52
|
v
HAPP
</pre>

== nftables ==

Основной конфигурационный файл:

<pre>
/etc/nftables.conf
</pre>

Актуальная логика:

<syntaxhighlight lang="text">
table ip selective {
set happ_ipv4 {
type ipv4_addr
}

set telegram_ipv4 {
type ipv4_addr
flags interval
elements = {
91.108.4.0/22,
91.108.8.0/22,
91.108.12.0/22,
91.108.16.0/22,
91.108.56.0/22,
149.154.160.0/20
}
}

chain prerouting {
type filter hook prerouting priority mangle;
policy accept;

iifname "wg0" ip daddr @telegram_ipv4 \
counter meta mark set 0x1

iifname "wg0" ip daddr @happ_ipv4 \
counter meta mark set 0x1
}
}
</syntaxhighlight>

Набор:

<pre>
happ_ipv4
</pre>

заполняется динамически через '''dnsmasq'''.

Telegram использует отдельный статический набор IP-сетей, поскольку мобильное
приложение может устанавливать MTProto-соединения непосредственно с IP-адресами
Telegram.

== DNS-based routing ==

На CT103 работает '''dnsmasq'''.

WireGuard-клиенты используют:

<pre>
DNS = 10.20.0.1
</pre>

Конфигурация:

<pre>
/etc/dnsmasq.d/wireguard.conf
</pre>

Пример:

<syntaxhighlight lang="text">
interface=wg0
listen-address=10.20.0.1
bind-dynamic

no-resolv
server=1.1.1.1
server=1.0.0.1

cache-size=2000
</syntaxhighlight>

Домены сервисов находятся в:

<pre>
/etc/dnsmasq.d/happ-domains.conf
</pre>

При DNS-разрешении IP-адрес автоматически добавляется в nftables set:

<pre>
ip selective happ_ipv4
</pre>

После этого трафик WireGuard-клиента к этому IP получает '''mark 0x1'''.

== YouTube ==

Для YouTube используются:

<syntaxhighlight lang="text">
nftset=/youtube.com/4#ip#selective#happ_ipv4
nftset=/youtu.be/4#ip#selective#happ_ipv4
nftset=/googlevideo.com/4#ip#selective#happ_ipv4
nftset=/ytimg.com/4#ip#selective#happ_ipv4
nftset=/youtubei.googleapis.com/4#ip#selective#happ_ipv4
nftset=/ggpht.com/4#ip#selective#happ_ipv4
</syntaxhighlight>

Особенно важен:

<pre>
googlevideo.com
</pre>

так как через него передаётся значительная часть видеопотока YouTube.

== Instagram ==

Используются:

<syntaxhighlight lang="text">
nftset=/instagram.com/4#ip#selective#happ_ipv4
nftset=/cdninstagram.com/4#ip#selective#happ_ipv4
nftset=/fbcdn.net/4#ip#selective#happ_ipv4
</syntaxhighlight>

Следует учитывать, что '''fbcdn.net''' является общей инфраструктурой Meta.

Поэтому некоторые ресурсы других сервисов Meta также могут попасть через HAPP.

== Telegram ==

Одних DNS-правил для Telegram оказалось недостаточно.

Telegram может подключаться непосредственно к IP-адресам дата-центров.

Поэтому используется статический nftables set:

<syntaxhighlight lang="text">
set telegram_ipv4 {
type ipv4_addr
flags interval

elements = {
91.108.4.0/22,
91.108.8.0/22,
91.108.12.0/22,
91.108.16.0/22,
91.108.56.0/22,
149.154.160.0/20
}
}
</syntaxhighlight>

Трафик маркируется:

<syntaxhighlight lang="text">
iifname "wg0" ip daddr @telegram_ipv4 \
counter meta mark set 0x1
</syntaxhighlight>

Работа правила проверяется счётчиком:

<syntaxhighlight lang="bash">
nft list chain ip selective prerouting
</syntaxhighlight>

== OpenAI / ChatGPT ==

Для OpenAI используется DNS-based routing.

Основные правила:

<syntaxhighlight lang="text">
nftset=/chatgpt.com/4#ip#selective#happ_ipv4
nftset=/openai.com/4#ip#selective#happ_ipv4
nftset=/auth.openai.com/4#ip#selective#happ_ipv4
nftset=/oaistatic.com/4#ip#selective#happ_ipv4
nftset=/oaiusercontent.com/4#ip#selective#happ_ipv4
nftset=/oaistatsig.com/4#ip#selective#happ_ipv4
nftset=/openaimerge.com/4#ip#selective#happ_ipv4
</syntaxhighlight>

При тестировании мобильного приложения ChatGPT после очистки набора:

<syntaxhighlight lang="bash">
nft flush set ip selective happ_ipv4
</syntaxhighlight>

DNS-запросы приложения снова заполняли '''happ_ipv4''', а счётчик правила
селективной маршрутизации увеличивался при отправке сообщений.

Таким образом работа ChatGPT через HAPP была подтверждена непосредственно
трафиком WireGuard-клиента.

== Discord ==

Discord первоначально был добавлен в DNS-based routing.

Тестировались домены:

<pre>
discord.com
discordapp.com
discordapp.net
discordcdn.com
discord.gg
discord.media
</pre>

Обычный HTTPS-трафик успешно попадал в '''happ_ipv4'''.

При тестировании голосового соединения были обнаружены отдельные UDP endpoints.

Примеры:

<pre>
155.212.196.192
155.212.204.196
</pre>

Был создан экспериментальный набор:

<pre>
discord_voice_ipv4
</pre>

и голосовой трафик начал попадать под '''mark 0x1'''.

Однако при реальном голосовом соединении наблюдались проблемы:

* очень небольшой объём трафика попадал под статическое правило;
* voice endpoint мог изменяться;
* входящий голос практически отсутствовал;
* маршрутизация двух отдельных IP не обеспечивала стабильную работу Discord Voice.

Поэтому эксперимент был отменён.

'''Текущее состояние: Discord полностью исключён из selective routing.'''

Discord проходит обычным маршрутом:

<pre>
Android
|
WireGuard
|
CT103 vpn-gateway
|
192.168.1.1
|
Internet
</pre>

Это решение принято намеренно, чтобы не нарушать работу голосовых каналов.

== HAPP Gateway ==

CT502:

<pre>
192.168.1.52
</pre>

работает как отдельный VLESS/HAPP gateway.

Используется TUN-интерфейс:

<pre>
thapp
</pre>

пример адреса:

<pre>
198.18.0.1/30
</pre>

HAPP создаёт отдельную таблицу маршрутизации:

<pre>
table 100
</pre>

Для корректного возврата трафика WireGuard необходимо сохранить маршруты:

<syntaxhighlight lang="bash">
ip route replace table 100 \
192.168.1.0/24 dev eth0 src 192.168.1.52

ip route replace table 100 \
10.20.0.0/24 via 192.168.1.53 dev eth0
</syntaxhighlight>

Иначе широкое правило:

<pre>
192.168.0.0/16
</pre>

может отправить обратный трафик WireGuard-клиента не в CT103.

== HAPP Auto Selector ==

На CT502 работает автоматический выбор HAPP-сервера.

Скрипт:

<pre>
/usr/local/sbin/happ-autoselect.sh
</pre>

Он выполняет реальные HTTP-запросы через тестовый HAPP proxy и сравнивает
время ответа нескольких стран.

Тестовые порты:

<pre>
SOCKS 12080
HTTP 12081
</pre>

Для каждого сервера выполняется несколько запросов и используется медианное
значение времени ответа.

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

Проверка выполняется systemd timer:

<pre>
happ-autoselect.timer
</pre>

== Проверка состояния ==

=== WireGuard ===

<syntaxhighlight lang="bash">
systemctl is-active wg-quick@wg0
wg show
</syntaxhighlight>

=== nftables ===

<syntaxhighlight lang="bash">
systemctl is-active nftables
nft list chain ip selective prerouting
</syntaxhighlight>

=== DNS ===

<syntaxhighlight lang="bash">
systemctl is-active dnsmasq
dnsmasq --test
</syntaxhighlight>

=== Dynamic HAPP set ===

<syntaxhighlight lang="bash">
nft list set ip selective happ_ipv4
</syntaxhighlight>

Очистить набор для диагностики:

<syntaxhighlight lang="bash">
nft flush set ip selective happ_ipv4
</syntaxhighlight>

После открытия нужного приложения набор должен заполниться снова.

=== Policy routing ===

<syntaxhighlight lang="bash">
ip rule show
ip route show table 200
</syntaxhighlight>

Ожидается:

<pre>
100: from all fwmark 0x1 lookup 200
</pre>

и:

<pre>
default via 192.168.1.52 dev eth0
</pre>

=== Проверка конкретного адреса ===

Обычный маршрут:

<syntaxhighlight lang="bash">
ip route get 1.1.1.1
</syntaxhighlight>

Маршрут с HAPP mark:

<syntaxhighlight lang="bash">
ip route get 1.1.1.1 mark 1
</syntaxhighlight>

Второй запрос должен использовать:

<pre>
table 200
via 192.168.1.52
</pre>

== Диагностика трафика ==

Трафик конкретного WireGuard-клиента можно наблюдать:

<syntaxhighlight lang="bash">
tcpdump -ni wg0 host 10.20.0.2
</syntaxhighlight>

HTTPS:

<syntaxhighlight lang="bash">
tcpdump -ni wg0 'host 10.20.0.2 and port 443'
</syntaxhighlight>

UDP:

<syntaxhighlight lang="bash">
tcpdump -ni wg0 'host 10.20.0.2 and udp'
</syntaxhighlight>

DNS и HTTPS одновременно:

<syntaxhighlight lang="bash">
tcpdump -ni wg0 \
'host 10.20.0.2 and (port 53 or port 443)'
</syntaxhighlight>

Это основной способ поиска сервисов, которые используют дополнительные CDN,
UDP endpoints или прямые IP-соединения.

== Автозапуск ==

После перезагрузки CT103 должны быть активны:

<syntaxhighlight lang="bash">
systemctl is-active nftables
systemctl is-active dnsmasq
systemctl is-active wg-quick@wg0
systemctl is-active selective-routing
</syntaxhighlight>

Ожидаемый результат:

<pre>
active
active
active
active
</pre>

Сервис selective routing:

<pre>
selective-routing.service
</pre>

восстанавливает:

* маршрут локальной сети в table 200;
* default route через CT502;
* правило fwmark 0x1.

== Итоговая схема маршрутизации ==

<pre>
WireGuard Client
10.20.0.x
|
v
CT103 vpn-gateway
|
+--------------------------------------+
| |
| обычный destination | selected destination
| |
v v
192.168.1.1 nftables mark 0x1
| |
| v
| table 200
| |
| v
| 192.168.1.52
| |
| v
| HAPP/VLESS
| |
+------------------+-------------------+
|
v
Internet
</pre>

== Текущее состояние ==

{| class="wikitable"
! Сервис
! Маршрут
! Метод
! Статус
|-
| YouTube
| HAPP
| DNS / nftset
| Работает
|-
| Instagram
| HAPP
| DNS / nftset
| Работает
|-
| Telegram
| HAPP
| Статические IP-сети + DNS
| Работает
|-
| ChatGPT / OpenAI
| HAPP
| DNS / nftset
| Работает
|-
| Discord
| Direct WAN
| Исключён из selective routing
| Голос через HAPP отключён
|-
| Остальной трафик
| Direct WAN
| Main routing table
| Работает
|}

== Безопасность ==

Закрытые ключи WireGuard не должны публиковаться в Wiki, Git или конфигурационных
примерах.

В документации допускается указывать:

* IP-адреса;
* порты;
* имена интерфейсов;
* публичные ключи при необходимости;
* архитектуру сети.

Не следует публиковать:

* WireGuard PrivateKey;
* API keys;
* HAPP/VLESS credentials;
* токены;
* пароли.

== Дальнейшее развитие ==

Возможные следующие этапы:

# Добавление новых сервисов через dnsmasq/nftset.
# Автоматическая диагностика новых destination IP.
# Разделение динамических nftables sets по сервисам.
# Статистика трафика отдельно для каждого сервиса.
# Web-интерфейс состояния gateway.
# Автоматическое тестирование HAPP-серверов.
# Мониторинг WireGuard-клиентов.
# Безопасная автоматизация добавления и удаления WireGuard-пользователей.

[[Категория:RAMBA]]
[[Категория:Infrastructure]]
[[Категория:VPN]]
[[Категория:WireGuard]]
[[Категория:Proxmox]]
[[Категория:Networking]]

RAMBA Selective VPN Gateway

2026-09-10T21:10:24Z

Artem: Новая страница: «{{DISPLAYTITLE:RAMBA Selective VPN Gateway}} = RAMBA Selective VPN Gateway = '''RAMBA Selective VPN Gateway''' — шлюз селективной маршрутизации трафика на базе '''WireGuard + nftables + dnsmasq + HAPP/VLESS'''. Система позволяет подключать мобильные устройства к домашней сети через WireGuard и отправлять через HAPP только тра...»

Toonel

2026-09-08T20:54:53Z

Artem:

cd $HOME

git clone -b feature/windows-bridge http://gitlab.ramba-art.ru/Gans/ramba-ai-pilot.git

cd ramba-ai-pilot
git branch --show-current

Toonel

2026-09-08T20:25:24Z

Artem:

[Interface]
PrivateKey = cGxkPcBKvRMgIWJcTkBiJNWZ2bPrdxjkgb+oKuileUc=
Address = 10.77.0.2/24

[Peer]
PublicKey = Q7P81P89NaA9vh23Q/w4Bpnoy4ih01g4xKimDWIxD2g=
AllowedIPs = 10.77.0.1/32
Endpoint = 195.138.232.82:51820
PersistentKeepalive = 25

ZtBK1EoHIPWwzutScj8M8XveoQrLOX2dhegt5/wwaRg=

[Interface]
PrivateKey = <НОВЫЙ WINDOWS PRIVATE KEY>
Address = 10.77.0.2/24

[Peer]
PublicKey = Q7P8lP89NaA9vH23Q/w4Bpnoy4ihO1g4xKimDWIxD2g=
AllowedIPs = 10.77.0.1/32
Endpoint = 195.138.232.82:51820
PersistentKeepalive = 25

Toonel

2026-09-08T20:20:58Z

Artem: Новая страница: «[Interface] PrivateKey = cGxkPcBKvRMgIWJcTkBiJNWZ2bPrdxjkgb+oKuileUc= Address = 10.77.0.2/24 [Peer] PublicKey = Q7P81P89NaA9vh23Q/w4Bpnoy4ih01g4xKimDWIxD2g= AllowedIPs = 10.77.0.1/32 Endpoint = 195.138.232.82:51820 PersistentKeepalive = 25 ZtBK1EoHIPWwzutScj8M8XveoQrLOX2dhegt5/wwaRg=»

RAMBA AI Router

2026-09-07T22:05:04Z

Artem:

<div class="portal-header">
<div class="portal-title">RAMBA AI Router</div>
<div class="portal-subtitle">
Локальный интеллектуальный маршрутизатор LLM для инфраструктуры RAMBA ART
</div>
</div>

<div class="portal-card">
'''RAMBA AI Router''' — собственный локальный маршрутизатор языковых моделей RAMBA ART.

Router принимает запрос пользователя, анализирует его тип и контекст, выбирает подходящую локальную LLM, при необходимости повышает уровень модели, проверяет ответ через Verifier и использует постоянную память между диалогами.

'''Текущая стабильная версия:''' '''v4.7 — Semantic Long-Term Memory'''

<syntaxhighlight lang="text">
Release: v4.7
Commit: 11b18b2
Backend: Ollama
API: FastAPI / Uvicorn
Storage: SQLite
Inference: NVIDIA GPU
</syntaxhighlight>
</div>

__TOC__

= Назначение проекта =

RAMBA AI Router создаётся как центральный интеллектуальный слой локальной AI-инфраструктуры RAMBA ART.

Основная идея проекта:

<syntaxhighlight lang="text">
Пользователь
│
▼
RAMBA AI Router
│
├── анализ запроса
├── выбор модели
├── история диалога
├── долговременная память
├── escalation
└── verification
│
▼
Local LLM
</syntaxhighlight>

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

Основные задачи:

* автоматический выбор подходящей LLM;
* минимизация задержки ответа;
* рациональное использование GPU;
* сохранение контекста разговора;
* постоянная память между сессиями;
* автоматическое повышение уровня модели для сложных запросов;
* проверка потенциально ненадёжных ответов;
* создание основы для будущего AI Agent.

= Инфраструктура =

RAMBA AI Router работает в локальной инфраструктуре RAMBA ART.

Основной AI-хост:

<syntaxhighlight lang="text">
Host: depo
Platform: Proxmox VE
CPU: Xeon E5-2678 v3
GPU: NVIDIA GeForce GTX 1080
</syntaxhighlight>

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

<syntaxhighlight lang="text">
Ollama
http://127.0.0.1:11434
</syntaxhighlight>

Router реализован на:

* Python;
* FastAPI;
* Uvicorn;
* SQLite;
* Ollama API.

= Модели =

В Router используются несколько специализированных моделей.

{| class="wikitable"
! Роль
! Модель
! Назначение
|-
| '''FAST'''
| <code>gemma3:4b</code>
| Быстрые повседневные запросы
|-
| '''INFRA'''
| <code>qwen3:8b</code>
| Linux, Proxmox, Docker, сети, инфраструктура
|-
| '''SMART'''
| <code>qwen3.5:9b</code>
| Более сложный анализ и рассуждение
|}

Общая идея:

<syntaxhighlight lang="text">
Request
│
▼
RAMBA Router
│
┌───────────┼───────────┐
│ │ │
▼ ▼ ▼
FAST INFRA SMART
Gemma 3 4B Qwen3 8B Qwen3.5 9B
</syntaxhighlight>

Такой подход позволяет не использовать самую тяжёлую модель для каждого простого запроса.

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

Текущая архитектура RAMBA AI Router v4.7:

<syntaxhighlight lang="text">
Пользователь
│
▼
┌─────────────────┐
│ RAMBA AI Router │
│ v4.7 │
└────────┬────────┘
│
┌───────────┴───────────┐
│ │
▼ ▼
Session Memory Long-Term Memory
v4.6 v4.7
│ │
messages_json memory_facts
│ │
└───────────┬───────────┘
│
▼
Context + Routing
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
FAST INFRA SMART
Gemma 3 4B Qwen3 8B Qwen3.5 9B
│ │ │
└──────────────┼──────────────┘
│
▼
Escalation
│
▼
Verifier
│
▼
Финальный ответ
</syntaxhighlight>

= Принцип работы =

Обработка одного сообщения в актуальной версии выглядит примерно так:

<syntaxhighlight lang="text">
1. Получение /chat запроса
2. Определение session_id
3. Загрузка Session Memory
4. Поиск Long-Term Memory
5. Анализ запроса
6. Выбор роли модели
7. Выбор FAST / INFRA / SMART
8. Формирование prompt
9. Добавление истории разговора
10. Добавление релевантной долговременной памяти
11. Вызов Ollama
12. Анализ результата
13. При необходимости Escalation
14. При необходимости Verifier
15. Сохранение Session Memory
16. Возврат ответа
</syntaxhighlight>

= История развития =

== Router v1 ==

Первая версия Router была proof-of-concept.

Основная задача заключалась в том, чтобы доказать сам принцип:

'''один API может автоматически направлять разные запросы в разные локальные модели.'''

Маршрутизация в основном основывалась на простых правилах и ключевых словах.

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

<syntaxhighlight lang="text">
Request
│
▼
Keyword Rules
│
├── FAST
├── INFRA
└── SMART
</syntaxhighlight>

Главный результат v1 — подтверждение жизнеспособности идеи локального multi-model Router.

== Router v2 ==

Во второй версии была улучшена логика классификации запросов.

Вместо одного простого совпадения ключевых слов Router начал учитывать несколько признаков запроса.

Появилась более стабильная специализация моделей.

Основная проблема всё ещё сохранялась:

* Router практически не понимал контекст;
* follow-up сообщения могли классифицироваться неправильно;
* история разговора не являлась частью маршрутизации.

== Router v3 ==

Router v3 стал заметным архитектурным шагом вперёд.

Основным изменением стала '''score-based routing'''.

Каждая роль могла получать собственный score.

Пример:

<syntaxhighlight lang="text">
Запрос:
"Как пробросить GPU в Proxmox?"

FAST = 0
INFRA = 8
SMART = 2

Результат:
INFRA
</syntaxhighlight>

Это позволило отказаться от жёсткой схемы:

<syntaxhighlight lang="text">
нашли одно слово → выбрали модель
</syntaxhighlight>

в пользу:

<syntaxhighlight lang="text">
несколько признаков
│
▼
score каждого класса
│
▼
лучший маршрут
</syntaxhighlight>

В поколении v3 были заложены основы дальнейшего Router v4.

= Router v4 =

'''RAMBA AI Router v4''' — текущее поколение системы.

Если v1–v3 в основном решали задачу выбора модели, то серия v4 постепенно превратила Router в полноценный интеллектуальный middleware.

Основные возможности поколения v4:

* context-aware routing;
* session affinity;
* hysteresis;
* история диалога;
* persistent session memory;
* escalation;
* Verifier;
* Semantic Long-Term Memory;
* диагностический API;
* SQLite persistence.

== Версии Router v4 ==

{| class="wikitable"
! Версия
! Основное изменение
! Статус
|-
| '''v4.1'''
| Развитие новой архитектуры Router v4
| Готово
|-
| '''v4.2'''
| Улучшение контекстной маршрутизации
| Готово
|-
| '''v4.3'''
| Стабилизация routing logic
| Готово
|-
| '''v4.4'''
| Escalation
| Готово
|-
| '''v4.5'''
| Verifier и дальнейшее развитие маршрутизации
| Готово
|-
| '''v4.6'''
| Persistent Context / Session Memory
| Готово
|-
| '''v4.7'''
| Semantic Long-Term Memory
| '''Текущая стабильная версия'''
|}

= Context-Aware Routing =

Одной из ключевых проблем ранних версий были короткие follow-up сообщения.

Например:

<syntaxhighlight lang="text">
Пользователь:
В Proxmox vfio-pci не захватывает GTX 1080.

Router:
INFRA

Пользователь:
А как проверить?
</syntaxhighlight>

Если анализировать только вторую фразу:

<syntaxhighlight lang="text">
А как проверить?
</syntaxhighlight>

она почти не содержит информации для классификации.

Router v4 учитывает историю разговора и может сохранить прежнюю специализацию.

Таким образом:

<syntaxhighlight lang="text">
Proxmox / GPU passthrough
│
▼
INFRA
│
▼
"А как проверить?"
│
▼
INFRA
</syntaxhighlight>

= Session Affinity и Hysteresis =

В Router v4 используется концепция session affinity.

Если разговор уже уверенно ведётся одной специализированной моделью, Router не должен переключаться между моделями из-за каждого короткого сообщения.

Hysteresis снижает число ненужных переключений.

Упрощённо:

<syntaxhighlight lang="text">
Current role = INFRA

Новый score:

FAST 3
INFRA 4

Разница небольшая
│
▼
оставить INFRA
</syntaxhighlight>

Это делает разговор стабильнее.

= Escalation =

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

Пример:

<syntaxhighlight lang="text">
Request
│
▼
FAST
│
├── ответ достаточный → вернуть
│
└── требуется усиление
│
▼
SMART
</syntaxhighlight>

Или:

<syntaxhighlight lang="text">
INFRA
│
└── сложный анализ
│
▼
SMART
</syntaxhighlight>

Таким образом Router может начинать с более дешёвой и быстрой модели, а более мощную использовать только тогда, когда это действительно требуется.

= Verifier =

Verifier используется как дополнительная проверка ответа.

Его задача — снизить риск выдачи явно слабого, противоречивого или потенциально ненадёжного результата.

Упрощённая схема:

<syntaxhighlight lang="text">
Primary Model
│
▼
Answer
│
▼
Verifier
│
├── OK
│
└── требуется correction
</syntaxhighlight>

Verifier является частью поколения Router v4.

= Persistent Session Memory — v4.6 =

Версия '''v4.6''' добавила постоянное хранение истории сессий.

До этого часть session state зависела от жизни процесса Router.

Основная SQLite-база:

<syntaxhighlight lang="text">
/home/artem/ramba-router/ramba-context.db
</syntaxhighlight>

Для session memory используется таблица:

<syntaxhighlight lang="text">
sessions
</syntaxhighlight>

Основные поля:

<syntaxhighlight lang="text">
session_id
role
model
messages_json
created_at
updated_at
</syntaxhighlight>

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

<syntaxhighlight lang="text">
Пользователь
│
▼
session_id
│
▼
RAMBA Router
│
▼
SQLite sessions
│
▼
messages_json
│
▼
LLM Context
</syntaxhighlight>

В результате история диалога переживает перезапуск процесса Uvicorn.

После рестарта Router может загрузить session state из SQLite.

= Semantic Long-Term Memory — v4.7 =

Версия '''v4.7''' добавила второй независимый механизм памяти.

Если Session Memory хранит историю конкретного разговора, Long-Term Memory хранит отдельные знания.

Пример:

<syntaxhighlight lang="text">
На сервере depo установлена NVIDIA GeForce GTX 1080.
</syntaxhighlight>

Такой факт не относится к одной конкретной session_id.

Он может использоваться:

* завтра;
* после restart Router;
* в новой сессии;
* в разговоре с другим session_id.

== Два уровня памяти ==

{| class="wikitable"
! Возможность
! Session Memory
! Long-Term Memory
|-
| Версия
| v4.6
| v4.7
|-
| Привязана к session_id
| Да
| Нет
|-
| Хранит историю диалога
| Да
| Нет
|-
| Хранит отдельные знания
| Нет
| Да
|-
| SQLite persistence
| Да
| Да
|-
| Переживает restart
| Да
| Да
|-
| Работает между сессиями
| Нет
| Да
|-
| Tags
| Нет
| Да
|-
| Importance
| Нет
| Да
|-
| Статистика использования
| Нет
| Да
|}

Архитектурно:

<syntaxhighlight lang="text">
RAMBA Router
│
┌──────────┴──────────┐
│ │
▼ ▼
Session Memory Long-Term Memory
│ │
current dialog knowledge
│ │
└──────────┬──────────┘
▼
LLM Context
</syntaxhighlight>

= Таблица memory_facts =

Для долговременной памяти используется отдельная SQLite-таблица:

<syntaxhighlight lang="sql">
CREATE TABLE memory_facts (
id INTEGER PRIMARY KEY AUTOINCREMENT,
scope TEXT NOT NULL,
fact TEXT NOT NULL,
tags TEXT,
importance REAL NOT NULL DEFAULT 0.5,
created_at TEXT NOT NULL,
updated_at TEXT NOT NULL,
last_used_at TEXT,
use_count INTEGER NOT NULL DEFAULT 0
);
</syntaxhighlight>

Поля:

{| class="wikitable"
! Поле
! Назначение
|-
| <code>id</code>
| Уникальный ID факта
|-
| <code>scope</code>
| Область действия
|-
| <code>fact</code>
| Текст знания
|-
| <code>tags</code>
| Поисковые теги
|-
| <code>importance</code>
| Важность
|-
| <code>created_at</code>
| Время создания
|-
| <code>updated_at</code>
| Время изменения
|-
| <code>last_used_at</code>
| Последнее использование
|-
| <code>use_count</code>
| Количество использований
|}

= Пример Memory Fact =

<syntaxhighlight lang="json">
{
"fact": "На сервере depo установлена видеокарта NVIDIA GeForce GTX 1080",
"scope": "global",
"tags": [
"depo",
"gpu",
"nvidia",
"gtx1080"
],
"importance": 0.9
}
</syntaxhighlight>

= Memory Retrieval =

Перед вызовом LLM Router выполняет поиск релевантной долговременной памяти.

Функция:

<syntaxhighlight lang="python">
retrieve_memories()
</syntaxhighlight>

Упрощённая схема:

<syntaxhighlight lang="text">
User message
│
▼
retrieve_memories()
│
▼
memory_facts
│
▼
relevance score
│
▼
top memories
│
▼
System Context
│
▼
LLM
</syntaxhighlight>

В версии v4.7 retrieval основан на:

* совпадениях слов;
* совпадениях тегов;
* importance.

Количество одновременно добавляемых фактов ограничено:

<syntaxhighlight lang="python">
MAX_MEMORY_FACTS = 5
</syntaxhighlight>

Это защищает prompt от чрезмерного разрастания.

Нерелевантная память не добавляется.

= Memory API =

Версия v4.7 предоставляет отдельное API управления памятью.

== Добавление факта ==

Endpoint:

<syntaxhighlight lang="text">
POST /memory
</syntaxhighlight>

Пример:

<syntaxhighlight lang="json">
{
"fact": "На сервере depo установлена видеокарта NVIDIA GeForce GTX 1080",
"scope": "global",
"tags": ["depo", "gpu", "nvidia", "gtx1080"],
"importance": 0.9
}
</syntaxhighlight>

== Просмотр памяти ==

<syntaxhighlight lang="text">
GET /memory
</syntaxhighlight>

== Удаление памяти ==

<syntaxhighlight lang="text">
DELETE /memory/{id}
</syntaxhighlight>

= Почему память пока управляемая =

В v4.7 модель '''не записывает новые факты автоматически'''.

Это намеренное решение.

Если сразу разрешить LLM сохранять любые данные из разговора, могут быстро появиться:

* случайные факты;
* ошибочные утверждения;
* временная информация;
* дубликаты;
* противоречащие друг другу записи;
* слишком большой объём памяти.

Поэтому v4.7 сначала реализует прозрачный жизненный цикл:

<syntaxhighlight lang="text">
explicit add
│
▼
SQLite
│
▼
retrieval
│
▼
usage statistics
│
▼
explicit delete
</syntaxhighlight>

Автоматическое извлечение памяти будет добавляться отдельным этапом.

= Использование Long-Term Memory в /chat =

При поступлении нового сообщения выполняется:

<syntaxhighlight lang="text">
/chat
│
├── get_session()
│
├── load Session Memory
│
├── retrieve Long-Term Memory
│
├── route request
│
├── build prompt
│
├── ask Ollama
│
├── escalation / verifier
│
├── save session
│
└── response
</syntaxhighlight>

Ответ API v4.7 содержит диагностическое поле:

<syntaxhighlight lang="json">
"memory_used": [...]
</syntaxhighlight>

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

= Production-проверка v4.7 =

После реализации v4.7 был выполнен отдельный production-тест.

В Long-Term Memory был добавлен факт:

<syntaxhighlight lang="text">
На сервере depo установлена видеокарта NVIDIA GeForce GTX 1080.
</syntaxhighlight>

Затем была создана новая сессия.

Запрос:

<syntaxhighlight lang="text">
Какая видеокарта установлена на сервере depo?
</syntaxhighlight>

Router нашёл memory fact и ответил:

<syntaxhighlight lang="text">
NVIDIA GeForce GTX 1080.
</syntaxhighlight>

После этого процесс Router был полностью перезапущен.

После restart была создана ещё одна новая сессия.

Запрос:

<syntaxhighlight lang="text">
Что за GPU стоит на depo?
</syntaxhighlight>

Результат:

<syntaxhighlight lang="text">
NVIDIA GeForce GTX 1080.
</syntaxhighlight>

При этом:

<syntaxhighlight lang="text">
history_messages = 0
memory_used = memory #1
use_count = 2
</syntaxhighlight>

Таким образом доказано:

* ответ не зависел от Session Memory;
* память работала в новой сессии;
* память пережила restart Router;
* SQLite persistence работает;
* retrieval правильно нашёл нужный факт.

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

Для каждой версии Router используется regression suite.

Для v4.7:

<syntaxhighlight lang="text">
test-router-v4.7.py
</syntaxhighlight>

Проверяются:

* базовая маршрутизация;
* score routing;
* context routing;
* session affinity;
* hysteresis;
* escalation;
* verifier;
* session history;
* persistent session storage;
* Long-Term Memory;
* add memory;
* list memory;
* retrieve memory;
* no-match retrieval;
* use_count;
* last_used_at;
* delete memory;
* SQLite persistence;
* HTTP Memory API.

Финальный результат regression suite:

<syntaxhighlight lang="text">
=== v4.7 MEMORY REGRESSION OK ===

🎉 ALL TESTS PASSED
</syntaxhighlight>

Memory regression выполняется на временной SQLite-базе и не изменяет production memory.

= Health API =

Для диагностики используется:

<syntaxhighlight lang="text">
GET /health
</syntaxhighlight>

Пример v4.7:

<syntaxhighlight lang="json">
{
"router": "ok",
"version": "4.7",
"ollama_loaded_models": [
"gemma3:4b"
],
"sessions": 2,
"sessions_memory": 0,
"sessions_persistent": 2,
"memory_facts": 1
}
</syntaxhighlight>

Параметр:

<syntaxhighlight lang="text">
memory_facts
</syntaxhighlight>

показывает количество долговременных фактов.

= Файлы проекта =

Основные файлы текущей версии:

<syntaxhighlight lang="text">
/home/artem/ramba-router/router_v47.py
/home/artem/ramba-router/test-router-v4.7.py
/home/artem/ramba-router/ramba-context.db
</syntaxhighlight>

Исторические версии Router сохранены отдельно и доступны через Git history и release tags.

= Production endpoints =

Текущий Router v4.7:

<syntaxhighlight lang="text">
127.0.0.1:8003
</syntaxhighlight>

Дополнительно оставлена резервная контрольная версия v4.5:

<syntaxhighlight lang="text">
127.0.0.1:8002
</syntaxhighlight>

Она используется как fallback при разработке новых версий.

= Git workflow =

Разработка каждой крупной возможности ведётся в отдельной feature-ветке.

Для v4.7 использовалась:

<syntaxhighlight lang="text">
feature/semantic-memory-v4.7
</syntaxhighlight>

Основной commit:

<syntaxhighlight lang="text">
18563ba Add semantic long-term memory for router v4.7
</syntaxhighlight>

После успешных тестов feature-ветка была объединена с main.

Merge commit:

<syntaxhighlight lang="text">
11b18b2 Merge branch 'feature/semantic-memory-v4.7' into 'main'
</syntaxhighlight>

Релиз зафиксирован тегом:

<syntaxhighlight lang="text">
v4.7
</syntaxhighlight>

На момент релиза:

<syntaxhighlight lang="text">
HEAD -> main
origin/main
tag: v4.7
</syntaxhighlight>

указывали на один релизный commit.

= Релизы =

{| class="wikitable"
! Версия
! Основное изменение
! Статус
|-
| v1
| Первый keyword router
| Историческая
|-
| v2
| Улучшенная классификация
| Историческая
|-
| v3
| Score-based routing
| Историческая
|-
| v4.1–v4.3
| Context-aware архитектура
| Стабильные этапы
|-
| v4.4
| Escalation
| Готово
|-
| v4.5
| Verifier
| Готово
|-
| v4.6
| Persistent Session Memory
| Готово
|-
| '''v4.7'''
| '''Semantic Long-Term Memory'''
| '''Current Stable'''
|}

= Ограничения текущей версии =

Версия v4.7 уже имеет persistent long-term memory, но это всё ещё первая управляемая реализация.

Текущие ограничения:

* память записывается через API;
* отсутствует automatic memory extraction;
* отсутствует автоматическое обновление фактов;
* нет автоматической дедупликации;
* нет memory consolidation;
* retrieval основан на словах и тегах;
* embeddings пока не используются;
* vector database отсутствует;
* нет confidence-модели для автоматически полученных фактов.

Это сделано намеренно.

Для текущего оборудования с GTX 1080 приоритетными являются:

* прозрачность;
* стабильность;
* низкие накладные расходы;
* простая диагностика;
* контроль над содержимым памяти.

= Следующий этап =

Следующее поколение RAMBA AI Router должно добавить автоматическое извлечение и управление памятью.

Предварительная архитектура:

<syntaxhighlight lang="text">
Conversation
│
▼
Memory Extractor
│
├── ignore
│
├── create fact
│
├── update fact
│
└── merge duplicate
│
▼
memory_facts
│
▼
Memory Retrieval
│
▼
LLM
</syntaxhighlight>

Основные задачи следующего этапа:

* Automatic Memory Extraction;
* классификация полезности факта;
* защита от случайного запоминания;
* confidence;
* дедупликация;
* обновление изменившихся знаний;
* consolidation;
* conflict detection;
* подготовка к embeddings.

После стабилизации жизненного цикла памяти можно переходить к:

* semantic embeddings;
* vector retrieval;
* RAG;
* внешним knowledge base;
* tool calling;
* AI Agent.

= Перспективная архитектура =

Долгосрочная цель проекта:

<syntaxhighlight lang="text">
User
│
▼
┌─────────────────┐
│ RAMBA AI Agent │
└────────┬────────┘
│
▼
┌─────────────────┐
│ RAMBA Router │
└────────┬────────┘
│
┌─────────────┼─────────────┐
│ │ │
▼ ▼ ▼
Memory RAG Tools
│ │ │
└─────────────┼─────────────┘
│
▼
Model Orchestration
│
┌────────────┼────────────┐
│ │ │
▼ ▼ ▼
FAST INFRA SMART
│
▼
Local GPU
</syntaxhighlight>

В такой архитектуре Router становится не конечным приложением, а центральным AI orchestration layer.

= Статус проекта =

{| class="wikitable"
! Компонент
! Статус
! Версия
|-
| Ollama
| '''Готово'''
| —
|-
| NVIDIA GPU inference
| '''Готово'''
| —
|-
| FAST / Gemma 3 4B
| '''Готово'''
| —
|-
| INFRA / Qwen3 8B
| '''Готово'''
| —
|-
| SMART / Qwen3.5 9B
| '''Готово'''
| —
|-
| Score-based Routing
| '''Готово'''
| v3
|-
| Context-Aware Routing
| '''Готово'''
| v4
|-
| Session Affinity
| '''Готово'''
| v4
|-
| Hysteresis
| '''Готово'''
| v4
|-
| Escalation
| '''Готово'''
| v4.4
|-
| Verifier
| '''Готово'''
| v4.5
|-
| Session Memory
| '''Готово'''
| v4.6
|-
| Persistent Context
| '''Готово'''
| v4.6
|-
| Semantic Long-Term Memory
| '''Готово'''
| '''v4.7'''
|-
| Memory API
| '''Готово'''
| '''v4.7'''
|-
| Automatic Memory Extraction
| Планируется
| Следующий этап
|-
| Memory Consolidation
| Планируется
| Следующий этап
|-
| Embeddings
| Планируется
| Позднее
|-
| Vector Search
| Планируется
| Позднее
|-
| RAG
| Планируется
| Позднее
|-
| Tool Calling
| Планируется
| Позднее
|-
| RAMBA AI Agent
| Планируется
| Будущий этап
|}

= Итог =

'''RAMBA AI Router v4.7''' — текущая стабильная версия локального интеллектуального маршрутизатора RAMBA ART.

Проект прошёл путь:

<syntaxhighlight lang="text">
Keyword Router
│
▼
Score Routing
│
▼
Context Routing
│
▼
Escalation
│
▼
Verifier
│
▼
Persistent Session Memory
│
▼
Semantic Long-Term Memory
</syntaxhighlight>

Текущая система уже умеет:

* автоматически выбирать локальную модель;
* учитывать специализацию запроса;
* сохранять роль в контексте разговора;
* избегать ненужного переключения моделей;
* повышать уровень модели при необходимости;
* проверять ответ;
* сохранять историю сессий в SQLite;
* восстанавливать сессии после restart;
* хранить отдельные долгосрочные знания;
* находить релевантные факты;
* использовать знания в совершенно новой сессии;
* сохранять долговременную память после restart Router.

Ключевой результат v4.7:

'''RAMBA AI получил настоящий persistent knowledge layer, независимый от конкретного диалога.'''

Production-проверка подтвердила полный цикл:

<syntaxhighlight lang="text">
Memory Fact
│
▼
SQLite
│
▼
Router Restart
│
▼
New Session
│
▼
Memory Retrieval
│
▼
Correct LLM Answer
</syntaxhighlight>

Следующий этап проекта — автоматическое извлечение, обновление и консолидация памяти с последующим переходом к semantic retrieval, RAG и полноценному RAMBA AI Agent.

Happ-gateway

2026-09-02T10:41:34Z

Artem:

= HAPP Gateway — централизованный прокси-шлюз RAMBA ART =

'''HAPP Gateway''' — отдельный сетевой шлюз в инфраструктуре RAMBA ART, предназначенный для централизованного доступа внутренних сервисов к внешним ресурсам через VLESS/HAPP.

Шлюз используется, в частности, для работы Telegram-ботов и сервисов, которым требуется стабильный SOCKS5/HTTP-прокси.

Основная идея заключается в том, что настройки HAPP и VLESS не требуется устанавливать отдельно на каждый сервер или контейнер. В инфраструктуре работает один выделенный LXC-контейнер, предоставляющий прокси остальным узлам локальной сети.

== Общая архитектура ==

<pre>
Интернет
│
│ VLESS
▼
┌─────────────────┐
│ HAPP Server │
│ лучший сервер │
└────────┬────────┘
│
│
┌────────▼────────┐
│ happ-gateway │
│ LXC CT 502 │
│ 192.168.1.52 │
│ │
│ HAPP CLI / Xray │
└────────┬────────┘
│
┌─────────────┴─────────────┐
│ │
▼ ▼
SOCKS5 proxy HTTP proxy
192.168.1.52:11080 192.168.1.52:11081
│ │
└─────────────┬─────────────┘
│
локальная сеть RAMBA ART
│
┌──────────────┼──────────────┐
▼ ▼ ▼
Telegram Bot OpenAI API другие сервисы
</pre>

== Параметры шлюза ==

{| class="wikitable"
! Параметр
! Значение
|-
| Контейнер
| CT 502
|-
| Hostname
| <code>happ-gateway</code>
|-
| IP
| <code>192.168.1.52</code>
|-
| ОС
| Debian
|-
| SOCKS5 для LAN
| <code>192.168.1.52:11080</code>
|-
| HTTP Proxy для LAN
| <code>192.168.1.52:11081</code>
|-
| Внутренний SOCKS5
| <code>127.0.0.1:10808</code>
|-
| Внутренний HTTP Proxy
| <code>127.0.0.1:10809</code>
|-
| HAPP subscription
| <code>ramba</code>
|-
| Часовой пояс
| <code>Europe/Moscow</code>
|}

== HAPP CLI ==

Для управления подпиской используется консольный клиент HAPP.

Конфигурация хранится в:

<pre>
/root/.config/happ-cli
</pre>

Просмотр доступных серверов:

<syntaxhighlight lang="bash">
happ --home /root/.config/happ-cli list
</syntaxhighlight>

Обновление подписки:

<syntaxhighlight lang="bash">
happ --home /root/.config/happ-cli sub update ramba
</syntaxhighlight>

Запуск конкретного сервера в режиме локального proxy:

<syntaxhighlight lang="bash">
happ --home /root/.config/happ-cli \
connect "Швеция" \
--mode proxy \
--socks 10808 \
--http 10809
</syntaxhighlight>

Важно: сервер выбирается '''по текстовому тегу страны, а не по его номеру'''.

Это было сделано после обнаружения особенности HAPP: после обновления подписки порядковые номера серверов могут изменяться.

Например:

<pre>
до обновления:

#32 → Нидерланды

после обновления:

#32 → Финляндия
#33 → Нидерланды
</pre>

Поэтому конфигурация вида:

<pre>
connect 32
</pre>

небезопасна.

Используется:

<pre>
connect "Швеция"
</pre>

Таким образом изменение порядка серверов в подписке не приводит к подключению к другой стране.

== Основной systemd-сервис ==

HAPP запускается автоматически через systemd.

Файл:

<pre>
/etc/systemd/system/happ-gateway.service
</pre>

Конфигурация:

<syntaxhighlight lang="ini">
[Unit]
Description=HAPP VLESS Proxy Gateway
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
Environment=HOME=/root
ExecStart=/usr/local/bin/happ --home /root/.config/happ-cli connect "Швеция" --mode proxy --socks 10808 --http 10809
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

Управление:

<syntaxhighlight lang="bash">
systemctl status happ-gateway.service
systemctl restart happ-gateway.service
systemctl stop happ-gateway.service
</syntaxhighlight>

Просмотр журнала:

<syntaxhighlight lang="bash">
journalctl -u happ-gateway.service
</syntaxhighlight>

== Публикация proxy в локальную сеть ==

Сам HAPP создаёт локальные proxy:

<pre>
SOCKS5: 127.0.0.1:10808
HTTP: 127.0.0.1:10809
</pre>

Для использования другими машинами инфраструктуры proxy публикуются в LAN.

В рабочей конфигурации используются:

<pre>
SOCKS5:
192.168.1.52:11080

HTTP:
192.168.1.52:11081
</pre>

Это позволяет другим контейнерам использовать HAPP Gateway без установки HAPP/Xray на каждом из них.

Например:

<syntaxhighlight lang="bash">
curl --proxy socks5h://192.168.1.52:11080 \
https://api.ipify.org
</syntaxhighlight>

Параметр <code>socks5h</code> важен: DNS-разрешение выполняется через proxy, а не локальной машиной.

== Проверка внешнего IP ==

Непосредственно на HAPP Gateway:

<syntaxhighlight lang="bash">
curl -sS --max-time 15 \
--proxy socks5h://127.0.0.1:10808 \
https://api.ipify.org
echo
</syntaxhighlight>

Во время настройки при использовании сервера Швеции был получен внешний IP:

<pre>
87.251.85.130
</pre>

Внешний IP не является постоянным и может измениться при переключении HAPP-сервера.

== Автоматический выбор лучшего сервера ==

Для повышения стабильности был реализован собственный механизм автоматического тестирования HAPP-серверов.

Скрипт:

<pre>
/usr/local/sbin/happ-autoselect.sh
</pre>

Он периодически проверяет доступные серверы и выбирает наиболее быстрый рабочий сервер.

=== Почему не используется обычный ping ===

ICMP ping не всегда отражает реальное качество proxy-соединения.

Для Telegram-ботов значительно важнее фактическое время выполнения HTTPS-запроса через:

<pre>
клиент
↓
HAPP
↓
VLESS
↓
удалённый сервер
↓
Telegram API
</pre>

Поэтому каждый сервер тестируется реальным HTTPS-запросом через временный SOCKS5 proxy.

Тестовая цель:

<pre>
https://api.telegram.org
</pre>

=== Алгоритм проверки ===

Для каждой страны выполняются три запроса.

<pre>
HAPP candidate
│
▼
127.0.0.1:12080
│
│ SOCKS5
▼
api.telegram.org
</pre>

Из трёх результатов рассчитывается '''медиана времени ответа'''.

Использование медианы позволяет уменьшить влияние единичного скачка задержки.

Например:

<pre>
0.19 s
0.21 s
0.85 s

median = 0.21 s
</pre>

Сервер считается рабочим, если успешно выполнено не менее двух из трёх запросов.

=== Серверы с ошибками ===

Если сервер не обеспечивает стабильное соединение:

<pre>
test 1: TIMEOUT/ERROR
test 2: TIMEOUT/ERROR
test 3: TIMEOUT/ERROR

REJECTED
</pre>

он исключается из текущего выбора.

При тестировании, например, некоторые серверы Польши, Эстонии, Франции и Сингапура не обеспечивали соединение с Telegram API и автоматически отбрасывались.

Это не означает, что сервер навсегда исключён: при следующей проверке он тестируется снова.

== Защита от постоянного переключения серверов ==

Выбирать сервер только по минимальной задержке недостаточно.

Например:

<pre>
текущий сервер: 220 ms
другой сервер: 215 ms
</pre>

Переключение ради 5 ms не имеет практического смысла и приводит к ненужным перезапускам HAPP.

Поэтому используется порог:

<pre>
15 %
</pre>

Новый сервер выбирается только если он быстрее текущего как минимум на 15%.

Логика:

<pre>
лучший сервер
│
▼
быстрее текущего ≥ 15% ?
│
┌──┴──┐
│ │
НЕТ ДА
│ │
▼ ▼
ничего изменить
не сервер
делать │
▼
restart HAPP
</pre>

== Результаты тестирования ==

Во время настройки были получены, например, следующие значения:

{| class="wikitable sortable"
! Сервер
! Медиана
! Результат
|-
| Швеция
| ~0.20–0.22 s
| '''Лучший'''
|-
| Финляндия
| ~0.24–0.25 s
| Работает
|-
| Нидерланды
| ~0.25–0.28 s
| Работает
|-
| Литва
| ~0.27–0.29 s
| Работает
|-
| Казахстан
| ~0.64–0.71 s
| Работает
|-
| Канада
| ~0.83–0.84 s
| Работает
|-
| Дубай
| ~0.95–0.96 s
| Работает
|-
| Бразилия
| ~1.50 s
| Работает
|-
| Япония
| ~1.65 s
| Работает
|-
| Германия
| ~1.5–2.1 s
| Работает нестабильно
|-
| США
| ~2.4 s
| Высокая задержка
|-
| Польша
| TIMEOUT
| Отклонён
|-
| Эстония
| TIMEOUT
| Отклонён
|-
| Франция
| TIMEOUT
| Отклонён
|-
| Сингапур
| TIMEOUT
| Отклонён
|}

На момент настройки наиболее быстрым маршрутом оказался сервер:

<pre>
🇸🇪 Швеция
swsq2.aquafinas.org:443
</pre>

== systemd timer автоматической проверки ==

Для автоматического запуска используется:

<pre>
/etc/systemd/system/happ-autoselect.service
</pre>

<syntaxhighlight lang="ini">
[Unit]
Description=HAPP automatic best server selector
After=network-online.target happ-gateway.service
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/sbin/happ-autoselect.sh
</syntaxhighlight>

Таймер:

<pre>
/etc/systemd/system/happ-autoselect.timer
</pre>

<syntaxhighlight lang="ini">
[Unit]
Description=Benchmark HAPP servers every hour

[Timer]
OnBootSec=5min
OnUnitActiveSec=1h
RandomizedDelaySec=2min
Persistent=true

[Install]
WantedBy=timers.target
</syntaxhighlight>

Активация:

<syntaxhighlight lang="bash">
systemctl daemon-reload
systemctl enable --now happ-autoselect.timer
</syntaxhighlight>

Проверка:

<syntaxhighlight lang="bash">
systemctl status happ-autoselect.timer --no-pager
systemctl list-timers --all | grep happ
</syntaxhighlight>

Таким образом benchmark выполняется приблизительно один раз в час.

<code>RandomizedDelaySec=2min</code> добавляет небольшой случайный сдвиг времени запуска.

== Важное решение: не обновлять подписку каждый час ==

Изначально <code>happ-autoselect.sh</code> перед каждым benchmark выполнял:

<syntaxhighlight lang="bash">
happ --home /root/.config/happ-cli sub update ramba
</syntaxhighlight>

Во время тестирования обновление подписки один раз завершилось ошибкой.

В результате список серверов временно не был доступен для скрипта:

<pre>
WARNING: subscription update failed
Skipping США: not found
Skipping Литва: not found
...
ERROR: no working servers found
</pre>

Основной HAPP Gateway при этом продолжил работать на текущем сервере.

После анализа было принято решение '''разделить две независимые операции''':

# обновление подписки;
# benchmark серверов.

Часовой benchmark больше не выполняет <code>sub update</code>.

Он работает с уже имеющейся локальной подпиской.

Это делает автоматический выбор сервера безопаснее: временная недоступность сервера подписки не влияет на уже работающий proxy.

== Отказоустойчивость ==

Система построена по принципу:

<pre>
не удалось провести benchmark
│
▼
НЕ менять сервер
│
▼
оставить работающий HAPP
на текущем сервере
</pre>

То есть ошибка системы мониторинга не должна ломать рабочее соединение.

Это особенно важно для сервисов, которые постоянно используют шлюз.

== Просмотр логов автоматического выбора ==

Последние события:

<syntaxhighlight lang="bash">
journalctl -t happ-autoselect -n 100 --no-pager
</syntaxhighlight>

Наблюдение в реальном времени:

<syntaxhighlight lang="bash">
journalctl -t happ-autoselect -f
</syntaxhighlight>

Типичный успешный результат:

<pre>
Best server: Швеция (0.217001s)
Current Швеция: 0.217001s
Improvement: 0.0%
Already using best server: Швеция
Keeping current server: Швеция
=== HAPP benchmark finished ===
</pre>

Если другой сервер значительно быстрее:

<pre>
Best server: Швеция (0.202160s)
Improvement: 18.4%
Switching ...
Switch successful
</pre>

== Настройка часового пояса ==

Первоначально контейнер использовал UTC:

<pre>
Local time: 07:50 UTC
Time zone: Etc/UTC
</pre>

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

<syntaxhighlight lang="bash">
timedatectl set-timezone Europe/Moscow
</syntaxhighlight>

Проверка:

<syntaxhighlight lang="bash">
timedatectl
date
</syntaxhighlight>

После настройки:

<pre>
Local time: 10:50 MSK
Universal time: 07:50 UTC
Time zone: Europe/Moscow (MSK, +0300)
System clock synchronized: yes
</pre>

После изменения timezone systemd автоматически начал отображать время таймеров и журналов в MSK.

== Использование HAPP Gateway приложениями ==

Для приложений в локальной сети рекомендуется использовать:

<pre>
SOCKS5:

socks5://192.168.1.52:11080
</pre>

или при использовании curl:

<pre>
socks5h://192.168.1.52:11080
</pre>

HTTP Proxy:

<pre>
http://192.168.1.52:11081
</pre>

Таким образом приложение не знает ничего о VLESS, Xray, подписках и конкретном внешнем сервере.

Для него HAPP Gateway является обычным proxy:

<pre>
Приложение
│
│ SOCKS5
▼
192.168.1.52:11080
│
▼
HAPP Gateway
│
│ VLESS
▼
лучший внешний сервер
│
▼
Интернет
</pre>

== Итоговая схема ==

<pre>
RAMBA ART LAN
│
┌─────────────────┼─────────────────┐
│ │ │
▼ ▼ ▼
Telegram Bot Kuzya 2.0 другие сервисы
│ │ │
└─────────────────┼─────────────────┘
│
│ SOCKS5
▼
192.168.1.52:11080
│
┌────────▼────────┐
│ HAPP Gateway │
│ CT 502 │
│ │
│ HAPP CLI + Xray │
└────────┬────────┘
│
│ VLESS
▼
выбранный сервер
│
▼
Internet

Каждый час:

happ-autoselect.timer
│
▼
happ-autoselect.sh
│
▼
проверка серверов
через Telegram HTTPS
│
▼
расчёт median
│
▼
лучший быстрее ≥15% ?
┌──┴───┐
│ │
НЕТ ДА
│ │
▼ ▼
оставить изменить
текущий сервер
│
▼
restart HAPP
</pre>

== Текущее состояние ==

На момент завершения настройки:

* HAPP Gateway работает в отдельном LXC-контейнере;
* SOCKS5 и HTTP proxy доступны другим узлам LAN;
* основной HAPP управляется через systemd;
* сервер задаётся по стабильному текстовому тегу страны;
* реализован автоматический benchmark серверов;
* benchmark выполняется примерно раз в час;
* проверяется реальная доступность Telegram API через proxy;
* используется медиана трёх измерений;
* неработающие серверы автоматически отбрасываются;
* переключение выполняется только при выигрыше не менее 15%;
* ошибка benchmark не отключает рабочий proxy;
* обновление HAPP-подписки отделено от механизма автоматического выбора;
* системное время контейнера отображается в MSK;
* HAPP Gateway готов для использования Telegram-ботами и другими сервисами RAMBA ART.

[[Категория:RAMBA ART]]
[[Категория:Инфраструктура]]
[[Категория:Linux]]
[[Категория:Proxmox]]
[[Категория:Сеть]]

RAMBA Matrix

2026-09-02T10:37:23Z

Artem:

<div class="portal-header">
<div class="portal-title">RAMBA Matrix</div>
<div class="portal-subtitle">
Корпоративный мессенджер RAMBA ART на базе открытого протокола Matrix
</div>
</div>

<div class="portal-card">
'''RAMBA Matrix''' — собственная коммуникационная платформа RAMBA ART на базе открытого протокола Matrix.

Система предоставляет обмен сообщениями, групповые комнаты, сквозное шифрование, веб- и мобильные клиенты, а также аудио- и видеозвонки.

Основная задача проекта — получить независимый корпоративный мессенджер, полностью размещённый на собственной инфраструктуре.
</div>

__TOC__

== Назначение проекта ==

RAMBA Matrix создавался как собственная альтернатива внешним корпоративным мессенджерам.

Основные требования:

* собственный сервер сообщений;
* хранение данных на инфраструктуре RAMBA ART;
* Android и iOS;
* веб-клиент;
* сквозное шифрование;
* личные и групповые комнаты;
* аудио- и видеозвонки;
* собственные Matrix ID;
* закрытая регистрация;
* возможность резервного копирования;
* возможность дальнейшего масштабирования;
* ориентация примерно на 1000 зарегистрированных пользователей.

Matrix ID пользователей имеют вид:

<syntaxhighlight lang="text">
@username:ramba-art.ru
</syntaxhighlight>

Например:

<syntaxhighlight lang="text">
@ivan_ivanov:ramba-art.ru
</syntaxhighlight>

== Архитектура RAMBA Matrix ==

Общая схема:

<syntaxhighlight lang="text">
INTERNET
│
│ HTTPS
▼
┌──────────────────┐
│ BrainyCP │
│ Nginx │
│ Reverse Proxy │
│ SSL │
└────────┬─────────┘
│
│ HTTP
▼
┌─────────────────────┐
│ ramba-chat │
│ │
│ Dendrite │
│ PostgreSQL │
│ Coturn │
└─────────┬───────────┘
│
│
┌─────────┴───────────┐
│ │
▼ ▼
Media Store TURN Relay
│
▼
OMV/NFS
</syntaxhighlight>

Публичный веб-клиент Element работает отдельно и подключается к Matrix homeserver через HTTPS.

== Домены ==

{| class="wikitable"
! Назначение
! Адрес
|-
| Matrix Server Name
| <code>ramba-art.ru</code>
|-
| Homeserver
| <code>chat.ramba-art.ru</code>
|-
| Element Web
| <code>element.ramba-art.ru</code>
|}

При этом серверное имя Matrix остаётся:

<syntaxhighlight lang="text">
ramba-art.ru
</syntaxhighlight>

Благодаря этому пользовательские ID не содержат технический поддомен `chat`.

== Компоненты системы ==

{| class="wikitable"
! Компонент
! Назначение
|-
| '''Dendrite'''
| Matrix homeserver
|-
| '''PostgreSQL'''
| Основная база данных
|-
| '''Element Web'''
| Веб-клиент Matrix
|-
| '''Element Mobile'''
| Клиенты Android и iOS
|-
| '''Coturn'''
| STUN/TURN для WebRTC
|-
| '''BrainyCP / Nginx'''
| Reverse proxy и SSL
|-
| '''OMV / NFS'''
| Хранилище медиафайлов
|-
| '''Proxmox VE'''
| Виртуализация и резервное копирование VM
|}

== Почему выбран Matrix ==

Matrix — открытый федеративный протокол для обмена сообщениями в реальном времени.

Основные преимущества:

* открытая спецификация;
* отсутствие привязки к одному поставщику;
* собственный сервер;
* собственный домен;
* поддержка E2EE;
* федерация;
* множество клиентских приложений;
* интеграции и боты;
* возможность работы полностью на собственной инфраструктуре.

Недостатки:

* инфраструктура сложнее обычного SaaS-мессенджера;
* необходимо обслуживать серверную часть;
* требуется отдельная настройка TURN для звонков;
* необходимо резервировать БД и media store;
* клиенты Matrix требуют корректного управления ключами шифрования.

== Почему Dendrite ==

В качестве Matrix homeserver используется '''Dendrite'''.

Dendrite написан на Go и может работать в компактной монолитной конфигурации.

Для RAMBA ART это позволило разместить Matrix homeserver на одной виртуальной машине без большого количества отдельных сервисов.

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

* компактная архитектура;
* написан на Go;
* сравнительно небольшое потребление ресурсов;
* поддержка PostgreSQL;
* поддержка Matrix Client API;
* федерация;
* E2EE;
* media API;
* интеграция с TURN.

Особенность выбранной архитектуры — Dendrite работает как единый монолитный процесс.

== PostgreSQL ==

PostgreSQL используется для постоянного хранения данных Matrix.

В базе находятся:

* события комнат;
* пользователи;
* состояния комнат;
* устройства;
* ключи;
* данные федерации;
* служебные данные homeserver.

PostgreSQL должен размещаться на локальном быстром диске VM.

<syntaxhighlight lang="text">
Dendrite
│
▼
PostgreSQL
│
▼
Local SSD / VM Disk
</syntaxhighlight>

Размещать активную БД PostgreSQL на NFS не рекомендуется.

== Element ==

'''Element''' используется как основной клиент RAMBA Matrix.

Поддерживаются:

* Element Web;
* Element для Android;
* Element для iOS;
* desktop-клиенты.

Веб-клиент доступен через:

<syntaxhighlight lang="text">
https://element.ramba-art.ru
</syntaxhighlight>

Он заранее настроен на homeserver:

<syntaxhighlight lang="text">
https://chat.ramba-art.ru
</syntaxhighlight>

Поэтому обычному пользователю не требуется вручную указывать сервер.

== Reverse Proxy ==

Публичный HTTPS-трафик проходит через BrainyCP.

Схема:

<syntaxhighlight lang="text">
Client
│
│ HTTPS
▼
BrainyCP / Nginx
│
│ proxy_pass
▼
Dendrite
</syntaxhighlight>

Это позволяет:

* централизованно управлять SSL;
* не публиковать Dendrite напрямую;
* использовать единый внешний веб-уровень;
* независимо переносить backend между VM или узлами Proxmox.

Основные proxy-заголовки:

<syntaxhighlight lang="nginx">
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
</syntaxhighlight>

После изменения конфигурации Nginx:

<syntaxhighlight lang="bash">
nginx -t
systemctl reload nginx
</syntaxhighlight>

== Matrix .well-known ==

Чтобы пользователи имели ID:

<syntaxhighlight lang="text">
@user:ramba-art.ru
</syntaxhighlight>

а физический homeserver находился на `chat.ramba-art.ru`, используется Matrix delegation.

=== Server discovery ===

Адрес:

<syntaxhighlight lang="text">
https://ramba-art.ru/.well-known/matrix/server
</syntaxhighlight>

Ответ:

<syntaxhighlight lang="json">
{
"m.server": "chat.ramba-art.ru:443"
}
</syntaxhighlight>

=== Client discovery ===

Адрес:

<syntaxhighlight lang="text">
https://ramba-art.ru/.well-known/matrix/client
</syntaxhighlight>

Ответ:

<syntaxhighlight lang="json">
{
"m.homeserver": {
"base_url": "https://chat.ramba-art.ru"
}
}
</syntaxhighlight>

Проверка:

<syntaxhighlight lang="bash">
curl -s https://ramba-art.ru/.well-known/matrix/server
curl -s https://ramba-art.ru/.well-known/matrix/client
</syntaxhighlight>

== Проверка Matrix API ==

Основная проверка homeserver:

<syntaxhighlight lang="bash">
curl -s \
https://chat.ramba-art.ru/_matrix/client/versions
</syntaxhighlight>

При исправной конфигурации сервер возвращает JSON со списком поддерживаемых версий Matrix Client API.

== Dendrite ==

Рабочая конфигурация находится в:

<syntaxhighlight lang="text">
/opt/dendrite/dendrite.yaml
</syntaxhighlight>

Основные файлы:

<syntaxhighlight lang="text">
/opt/dendrite/
├── dendrite
├── dendrite.yaml
├── matrix_key.pem
└── media/
</syntaxhighlight>

Ключевой параметр:

<syntaxhighlight lang="yaml">
global:
server_name: ramba-art.ru
</syntaxhighlight>

`server_name` после ввода системы в эксплуатацию менять не следует.

Он является частью Matrix ID пользователей и идентичности homeserver.

== Systemd ==

Dendrite запускается как системная служба.

Управление:

<syntaxhighlight lang="bash">
systemctl start dendrite
systemctl stop dendrite
systemctl restart dendrite
systemctl status dendrite
</syntaxhighlight>

Просмотр журнала:

<syntaxhighlight lang="bash">
journalctl -u dendrite -f
</syntaxhighlight>

Последние записи:

<syntaxhighlight lang="bash">
journalctl -u dendrite -n 100 --no-pager
</syntaxhighlight>

== Регистрация пользователей ==

RAMBA Matrix работает как закрытая корпоративная система.

Публичная регистрация пользователей отключена.

Пользовательские записи создаются администратором.

Общая схема:

<syntaxhighlight lang="text">
Администратор
│
▼
Создание аккаунта
│
▼
@username:ramba-art.ru
│
▼
Первый вход пользователя
</syntaxhighlight>

Такой вариант позволяет контролировать доступ к системе и предотвращает автоматическую регистрацию посторонних пользователей.

== Сквозное шифрование ==

Matrix поддерживает End-to-End Encryption.

В зашифрованной комнате сообщение шифруется на клиенте отправителя и расшифровывается на устройстве получателя.

Упрощённая схема:

<syntaxhighlight lang="text">
Client A
│
│ encrypted event
▼
Matrix Server
│
│ encrypted event
▼
Client B
</syntaxhighlight>

Homeserver хранит зашифрованное содержимое и не должен обладать ключами для расшифровки сообщений пользователей.

Для пользователей особенно важно настроить восстановление ключей и не терять данные безопасного хранилища.

== Media Store ==

Matrix хранит загружаемые изображения, документы, видео и другие вложения отдельно от основной PostgreSQL БД.

Для RAMBA Matrix media store вынесен на отдельное хранилище.

Схема:

<syntaxhighlight lang="text">
Dendrite VM
│
▼
Media directory
│
▼
NFS
│
▼
OMV Storage
</syntaxhighlight>

Это позволяет не увеличивать системный диск VM по мере роста количества вложений.

PostgreSQL при этом остаётся на локальном диске.

== Права на NFS ==

При использовании NFS необходимо обеспечить правильные UID/GID пользователя, под которым работает Dendrite.

После монтирования следует проверить:

<syntaxhighlight lang="bash">
mount | grep matrix
ls -ld /matrix-media
</syntaxhighlight>

И тест записи:

<syntaxhighlight lang="bash">
touch /matrix-media/test
rm /matrix-media/test
</syntaxhighlight>

Тест необходимо выполнять от имени пользователя Dendrite.

== Coturn ==

Coturn используется для STUN/TURN и обеспечивает работу звонков в сложных NAT-сценариях.

Без TURN два клиента могут успешно обмениваться сообщениями, но не иметь возможности установить аудио- или видеосоединение.

Архитектура звонка:

<syntaxhighlight lang="text">
Element A
│
│ WebRTC
▼
STUN / TURN
│
▼
Coturn
│
│ Relay
▼
Element B
</syntaxhighlight>

== TURN-порты ==

В инфраструктуре используется ограниченный диапазон relay-портов:

{| class="wikitable"
! Порт
! Протокол
! Назначение
|-
| 3478
| TCP / UDP
| STUN / TURN
|-
| 5349
| TCP
| TURN over TLS
|-
| 49152–49252
| UDP
| TURN Relay
|}

Этот диапазон должен быть разрешён firewall и корректно проброшен через NAT.

== Пример конфигурации Coturn ==

<syntaxhighlight lang="ini">
listening-port=3478
tls-listening-port=5349

use-auth-secret
realm=ramba-art.ru

fingerprint
lt-cred-mech

min-port=49152
max-port=49252

no-multicast-peers
no-cli
</syntaxhighlight>

Также должны быть корректно настроены:

<syntaxhighlight lang="ini">
listening-ip=
relay-ip=
external-ip=
</syntaxhighlight>

Конкретные значения зависят от текущей сетевой архитектуры.

== TURN в Dendrite ==

В конфигурации Dendrite указываются URI TURN-сервера:

<syntaxhighlight lang="yaml">
client_api:
turn:
turn_user_lifetime: "5m"

turn_uris:
- "turn:turn.ramba-art.ru:3478?transport=udp"
- "turn:turn.ramba-art.ru:3478?transport=tcp"
- "turns:turn.ramba-art.ru:5349?transport=tcp"

turn_shared_secret: "SECRET"
</syntaxhighlight>

`turn_shared_secret` должен совпадать с `static-auth-secret` Coturn.

Секреты не следует публиковать в Wiki.

== Проверка TURN ==

Проверка выдачи временных TURN credentials:

<syntaxhighlight lang="bash">
curl -s \
https://chat.ramba-art.ru/_matrix/client/v3/voip/turnServer
</syntaxhighlight>

В рабочем состоянии сервер возвращает:

* username;
* password;
* TTL;
* список TURN URI.

== Тестирование звонков ==

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

Желательно:

* одно устройство через Wi-Fi;
* второе через мобильную сеть.

Это заставляет WebRTC проходить через реальные NAT-сценарии.

Проверяем:

# текстовые сообщения;
# зашифрованный личный чат;
# аудиозвонок;
# видеозвонок;
# входящий вызов;
# работу после переключения сети.

Успешный звонок через разные сети подтверждает работу:

<syntaxhighlight lang="text">
Element
+
Dendrite
+
WebRTC
+
STUN
+
TURN
+
NAT
+
Firewall
</syntaxhighlight>

== Element Web ==

Element Web работает на отдельном домене:

<syntaxhighlight lang="text">
https://element.ramba-art.ru
</syntaxhighlight>

Пример основных параметров `config.json`:

<syntaxhighlight lang="json">
{
"default_server_config": {
"m.homeserver": {
"base_url": "https://chat.ramba-art.ru",
"server_name": "ramba-art.ru"
}
},

"disable_custom_urls": true,
"disable_guests": true,
"brand": "RAMBA Chat",
"default_theme": "dark"
}
</syntaxhighlight>

Благодаря этому пользователю достаточно открыть Element и войти под своим RAMBA Matrix аккаунтом.

== Мобильные клиенты ==

На мобильных устройствах используются Matrix-совместимые клиенты.

Для подключения используется homeserver:

<syntaxhighlight lang="text">
https://chat.ramba-art.ru
</syntaxhighlight>

Либо автоматическое обнаружение через:

<syntaxhighlight lang="text">
ramba-art.ru
</syntaxhighlight>

После входа рекомендуется сразу настроить:

* подтверждение устройства;
* безопасное хранилище;
* восстановление ключей;
* PIN/Face ID клиента;
* push-уведомления.

== Федерация ==

Matrix поддерживает обмен событиями между независимыми homeserver.

Для федерации используется server name:

<syntaxhighlight lang="text">
ramba-art.ru
</syntaxhighlight>

и delegation на:

<syntaxhighlight lang="text">
chat.ramba-art.ru
</syntaxhighlight>

Базовая проверка:

<syntaxhighlight lang="bash">
curl -s \
https://ramba-art.ru/.well-known/matrix/server
</syntaxhighlight>

При проблемах с федерацией необходимо проверять:

* DNS;
* TLS;
* `.well-known`;
* доступность `chat.ramba-art.ru`;
* Nginx;
* журнал Dendrite.

== Резервное копирование ==

Matrix нельзя считать защищённым только потому, что существует snapshot VM.

Необходимо резервировать отдельно:

{| class="wikitable"
! Компонент
! Требуется backup
|-
| PostgreSQL
| Да
|-
| dendrite.yaml
| Да
|-
| matrix_key.pem
| '''Обязательно'''
|-
| Media Store
| Да
|-
| Coturn config
| Да
|-
| Element config.json
| Да
|-
| BrainyCP / Nginx vhost
| Да
|}

Особенно критичен:

<syntaxhighlight lang="text">
matrix_key.pem
</syntaxhighlight>

Это identity key Matrix homeserver. Его потеря может привести к серьёзным проблемам с федерацией и идентичностью сервера.

== PostgreSQL backup ==

Пример:

<syntaxhighlight lang="bash">
sudo -u postgres \
pg_dump dendrite \
> /root/dendrite-$(date +%F).sql
</syntaxhighlight>

Проверяем:

<syntaxhighlight lang="bash">
ls -lh /root/dendrite-*.sql
</syntaxhighlight>

Для production рекомендуется автоматизировать резервное копирование и периодически тестировать восстановление.

== Backup конфигурации ==

Пример:

<syntaxhighlight lang="bash">
tar -czf /root/ramba-matrix-config-$(date +%F).tar.gz \
/opt/dendrite/dendrite.yaml \
/opt/dendrite/matrix_key.pem \
/etc/turnserver.conf \
/etc/systemd/system/dendrite.service
</syntaxhighlight>

Файл с `matrix_key.pem` должен храниться в защищённом месте.

== Proxmox Backup ==

Виртуальная машина RAMBA Matrix также резервируется средствами Proxmox.

Схема:

<syntaxhighlight lang="text">
RAMBA Matrix VM
│
▼
Proxmox VE
│
▼
Proxmox Backup Server
</syntaxhighlight>

Backup VM полезен для быстрого полного восстановления, но не заменяет логический dump PostgreSQL.

== Мониторинг ==

Минимальный набор проверок:

=== Dendrite ===

<syntaxhighlight lang="bash">
systemctl status dendrite
</syntaxhighlight>

=== PostgreSQL ===

<syntaxhighlight lang="bash">
systemctl status postgresql
</syntaxhighlight>

=== Coturn ===

<syntaxhighlight lang="bash">
systemctl status coturn
</syntaxhighlight>

=== Matrix API ===

<syntaxhighlight lang="bash">
curl -s \
https://chat.ramba-art.ru/_matrix/client/versions
</syntaxhighlight>

=== TURN ===

<syntaxhighlight lang="bash">
curl -s \
https://chat.ramba-art.ru/_matrix/client/v3/voip/turnServer
</syntaxhighlight>

=== Media storage ===

<syntaxhighlight lang="bash">
df -h
mount | grep matrix
</syntaxhighlight>

== Диагностика ==

=== Dendrite не запускается ===

<syntaxhighlight lang="bash">
systemctl status dendrite
journalctl -u dendrite -n 100 --no-pager
</syntaxhighlight>

=== Matrix API недоступен ===

Проверяем цепочку:

<syntaxhighlight lang="text">
Client
│
▼
DNS
│
▼
BrainyCP
│
▼
Nginx
│
▼
Dendrite
</syntaxhighlight>

Проверяем внешний адрес:

<syntaxhighlight lang="bash">
curl -Iv https://chat.ramba-art.ru/
</syntaxhighlight>

И backend непосредственно из LAN:

<syntaxhighlight lang="bash">
curl -I http://MATRIX_BACKEND_IP:8008/
</syntaxhighlight>

=== Звонок соединяется без аудио ===

В первую очередь проверяем:

* Coturn;
* relay UDP range;
* NAT;
* `external-ip`;
* firewall;
* TURN credentials.

Проверяем:

<syntaxhighlight lang="bash">
ss -tulpn | grep turnserver
</syntaxhighlight>

=== Не загружаются медиа ===

Проверяем:

<syntaxhighlight lang="bash">
mount | grep matrix
df -h
ls -ld /matrix-media
</syntaxhighlight>

Также необходимо проверить права пользователя Dendrite на NFS.

== Производительность ==

Основная нагрузка Matrix распределяется между:

<syntaxhighlight lang="text">
CPU
│
├── Dendrite
├── PostgreSQL
└── Federation

RAM
│
├── Dendrite
└── PostgreSQL

Disk
│
├── PostgreSQL
└── Media

Network
│
├── Federation
├── Media
└── TURN
</syntaxhighlight>

Для небольшого и среднего deployment особенно важны:

* быстрый локальный диск PostgreSQL;
* достаточный объём RAM;
* стабильное сетевое подключение;
* отдельное пространство для media store.

== Масштабирование ==

Текущая архитектура намеренно проста:

<syntaxhighlight lang="text">
1 VM
│
├── Dendrite
├── PostgreSQL
└── Coturn
</syntaxhighlight>

По мере роста можно отдельно масштабировать:

* PostgreSQL;
* media store;
* TURN;
* reverse proxy;
* мониторинг;
* резервное копирование.

Media Store уже удобно отделять от системного диска через NFS.

== Безопасность ==

Для RAMBA Matrix рекомендуется:

* держать публичную регистрацию отключённой;
* использовать E2EE;
* не публиковать PostgreSQL;
* не публиковать внутренний порт Dendrite;
* не хранить секреты в Wiki;
* регулярно менять административные пароли;
* ограничивать SSH;
* резервировать `matrix_key.pem`;
* хранить backup вне основной VM;
* обновлять Dendrite, PostgreSQL, Element и Coturn;
* проверять журналы после обновлений.

== Полезные команды ==

{| class="wikitable"
! Задача
! Команда
|-
| Статус Dendrite
| <code>systemctl status dendrite</code>
|-
| Перезапуск Dendrite
| <code>systemctl restart dendrite</code>
|-
| Логи Dendrite
| <code>journalctl -u dendrite -f</code>
|-
| Статус PostgreSQL
| <code>systemctl status postgresql</code>
|-
| Статус Coturn
| <code>systemctl status coturn</code>
|-
| Проверить Matrix API
| <code>curl -s https://chat.ramba-art.ru/_matrix/client/versions</code>
|-
| Проверить TURN
| <code>curl -s https://chat.ramba-art.ru/_matrix/client/v3/voip/turnServer</code>
|-
| Проверить NFS
| <code>mount | grep matrix</code>
|-
| Проверить диск
| <code>df -h</code>
|}

== Итоговая схема ==

<syntaxhighlight lang="text">
USERS
│
┌────────────┴────────────┐
│ │
▼ ▼
Element Web Element Mobile
│ │
└────────────┬────────────┘
│
│ HTTPS
▼
┌─────────────────┐
│ BrainyCP │
│ Nginx │
│ SSL │
└────────┬────────┘
│
▼
┌─────────────────┐
│ Dendrite │
└──────┬─────┬────┘
│ │
│ └──────────────┐
▼ ▼
PostgreSQL Coturn
│ │
│ ▼
│ TURN Relay
│
▼
Local Disk

Media API
│
▼
OMV / NFS
</syntaxhighlight>

== Результат ==

RAMBA Matrix представляет собой полностью самостоятельную коммуникационную платформу, работающую на инфраструктуре RAMBA ART.

Система обеспечивает:

* собственные Matrix ID;
* личные и групповые чаты;
* E2EE;
* Android и iOS;
* Element Web;
* голосовые звонки;
* видеозвонки;
* собственное хранение данных;
* резервное копирование;
* федерацию;
* возможность дальнейшего масштабирования.

При этом публичный веб-уровень, Matrix backend, база данных и media store разделены между отдельными компонентами инфраструктуры.

== См. также ==

* [[BrainyCP]]
* [[Proxmox VE]]
* [[Proxmox Backup Server]]
* [[OpenMediaVault]]
* [[RAMBA Wiki]]
* [[Мониторинг]]

== Внешние ссылки ==

* [https://matrix.org/ Matrix.org]
* [https://spec.matrix.org/ Matrix Specification]
* [https://github.com/element-hq/dendrite Dendrite]
* [https://element.io/ Element]
* [https://github.com/coturn/coturn Coturn]

[[Категория:Matrix]]
[[Категория:RAMBA Matrix]]
[[Категория:Мессенджеры]]
[[Категория:Linux]]
[[Категория:Proxmox]]
[[Категория:Сетевая инфраструктура]]
[[Категория:RAMBA ART]]

Minecraft в 2026 году

2026-09-02T10:30:44Z

Artem:

<div class="portal-header">
<div class="portal-title">Minecraft Java Server</div>
<div class="portal-subtitle">
Установка и эксплуатация выделенного сервера Minecraft на Ubuntu 24.04 LTS
</div>
</div>

<div class="portal-card">
'''Minecraft Java Server''' — выделенный сервер для Minecraft Java Edition.

В этой статье рассматривается установка сервера на '''Ubuntu 24.04 LTS''' с отдельным системным пользователем, автоматическим запуском через systemd, RCON-управлением и резервным копированием.

Конфигурация подходит для виртуальной машины, физического сервера или LXC-контейнера.
</div>

__TOC__

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

Базовая схема сервера:

<syntaxhighlight lang="text">
Игроки
│
│ TCP :25565
▼
┌───────────────┐
│ Minecraft │
│ Java Server │
└───────┬───────┘
│
┌────────┴────────┐
│ │
▼ ▼
systemd RCON
│
▼
mcrcon
</syntaxhighlight>

В production-конфигурации Minecraft запускается не вручную, а как системная служба.

== Системные требования ==

{| class="wikitable"
! Параметр
! Минимально
! Рекомендуется
|-
| CPU
| 2 vCPU
| 4+ производительных ядра
|-
| RAM
| 4 ГБ
| 8 ГБ и более
|-
| Диск
| 20 ГБ
| 50+ ГБ SSD
|-
| ОС
| Ubuntu 24.04 LTS
| Ubuntu 24.04 LTS
|-
| Сеть
| 25565/TCP
| Статический IP или NAT
|}

При большой дальности прорисовки, большом количестве игроков или тяжёлых модификациях требования к CPU и RAM могут значительно возрастать.

== Подготовка системы ==

Обновляем систему:

<syntaxhighlight lang="bash">
apt update
apt upgrade -y
</syntaxhighlight>

Устанавливаем необходимые инструменты:

<syntaxhighlight lang="bash">
apt install -y \
wget \
curl \
git \
nano \
unzip \
build-essential
</syntaxhighlight>

Проверяем время и часовой пояс:

<syntaxhighlight lang="bash">
timedatectl
</syntaxhighlight>

При необходимости:

<syntaxhighlight lang="bash">
timedatectl set-timezone Europe/Moscow
</syntaxhighlight>

== Установка Java ==

Версия Java зависит от версии Minecraft.

Перед установкой рекомендуется проверить требования конкретной версии сервера.

Для современных версий Minecraft обычно используется Java 21:

<syntaxhighlight lang="bash">
apt install -y openjdk-21-jdk
</syntaxhighlight>

Проверяем:

<syntaxhighlight lang="bash">
java -version
</syntaxhighlight>

Пример:

<syntaxhighlight lang="text">
openjdk version "21"
OpenJDK Runtime Environment
OpenJDK 64-Bit Server VM
</syntaxhighlight>

=== Проверка установленной Java ===

Путь до Java:

<syntaxhighlight lang="bash">
which java
</syntaxhighlight>

Обычно:

<syntaxhighlight lang="text">
/usr/bin/java
</syntaxhighlight>

== Создание пользователя Minecraft ==

Minecraft не следует запускать от имени root.

Создаём отдельного системного пользователя:

<syntaxhighlight lang="bash">
useradd \
--system \
--create-home \
--user-group \
--home-dir /opt/minecraft \
--shell /bin/bash \
minecraft
</syntaxhighlight>

Проверяем:

<syntaxhighlight lang="bash">
id minecraft
</syntaxhighlight>

Переходим под него:

<syntaxhighlight lang="bash">
su - minecraft
</syntaxhighlight>

Домашним каталогом пользователя будет:

<syntaxhighlight lang="text">
/opt/minecraft
</syntaxhighlight>

== Структура каталогов ==

Создаём:

<syntaxhighlight lang="bash">
mkdir -p ~/server
mkdir -p ~/backups
mkdir -p ~/tools
</syntaxhighlight>

Структура:

<syntaxhighlight lang="text">
/opt/minecraft/
├── server/
│ ├── server.jar
│ ├── server.properties
│ ├── eula.txt
│ ├── world/
│ └── logs/
│
├── backups/
│
└── tools/
</syntaxhighlight>

Назначение:

* '''server''' — сервер Minecraft;
* '''backups''' — резервные копии;
* '''tools''' — вспомогательные утилиты.

== Установка mcrcon ==

'''mcrcon''' используется для отправки команд Minecraft через RCON.

Клонируем проект:

<syntaxhighlight lang="bash">
git clone https://github.com/Tiiffi/mcrcon.git ~/tools/mcrcon
</syntaxhighlight>

Компилируем:

<syntaxhighlight lang="bash">
cd ~/tools/mcrcon
make
</syntaxhighlight>

Проверяем:

<syntaxhighlight lang="bash">
./mcrcon -v
</syntaxhighlight>

== Установка Minecraft Server ==

Переходим:

<syntaxhighlight lang="bash">
cd /opt/minecraft/server
</syntaxhighlight>

Актуальный файл '''server.jar''' необходимо скачивать с официального сайта Minecraft/Mojang.

После получения ссылки:

<syntaxhighlight lang="bash">
wget -O server.jar \
'https://piston-data.mojang.com/.../server.jar'
</syntaxhighlight>

Проверяем:

<syntaxhighlight lang="bash">
ls -lh server.jar
</syntaxhighlight>

== Первый запуск ==

Первый запуск нужен для генерации конфигурации:

<syntaxhighlight lang="bash">
java -Xms2G -Xmx4G -jar server.jar nogui
</syntaxhighlight>

Сервер остановится, поскольку EULA ещё не принята.

После запуска появятся:

<syntaxhighlight lang="text">
eula.txt
server.properties
logs/
</syntaxhighlight>

== Принятие EULA ==

Открываем:

<syntaxhighlight lang="bash">
nano eula.txt
</syntaxhighlight>

Меняем:

<syntaxhighlight lang="text">
eula=false
</syntaxhighlight>

на:

<syntaxhighlight lang="text">
eula=true
</syntaxhighlight>

Сохраняем файл.

== Базовая настройка server.properties ==

Открываем:

<syntaxhighlight lang="bash">
nano server.properties
</syntaxhighlight>

Основные параметры:

<syntaxhighlight lang="properties">
server-port=25565

max-players=100

online-mode=true

enable-command-block=false

view-distance=10
simulation-distance=10

motd=RAMBA-ART Minecraft Server
</syntaxhighlight>

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

<syntaxhighlight lang="properties">
online-mode=true
</syntaxhighlight>

Это включает проверку учётных записей Mojang/Microsoft.

== Настройка RCON ==

В `server.properties`:

<syntaxhighlight lang="properties">
enable-rcon=true
rcon.port=25575
rcon.password=CHANGE_THIS_PASSWORD
broadcast-rcon-to-ops=true
</syntaxhighlight>

После изменения сервер необходимо перезапустить.

=== Безопасность RCON ===

RCON не рекомендуется публиковать напрямую в Интернет.

Предпочтительная схема:

<syntaxhighlight lang="text">
mcrcon
│
│ 127.0.0.1:25575
▼
Minecraft Server
</syntaxhighlight>

То есть порт `25575` должен использоваться только локально либо через защищённую административную сеть/VPN.

== Проверка ручного запуска ==

Запускаем:

<syntaxhighlight lang="bash">
cd /opt/minecraft/server

java -Xms4G -Xmx6G \
-jar server.jar \
nogui
</syntaxhighlight>

Если сервер успешно загрузился, в консоли появится сообщение примерно:

<syntaxhighlight lang="text">
Done (...)! For help, type "help"
</syntaxhighlight>

После проверки останавливаем:

<syntaxhighlight lang="text">
stop
</syntaxhighlight>

== Создание systemd-службы ==

Выходим из пользователя Minecraft:

<syntaxhighlight lang="bash">
exit
</syntaxhighlight>

Создаём:

<syntaxhighlight lang="bash">
nano /etc/systemd/system/minecraft.service
</syntaxhighlight>

Содержимое:

<syntaxhighlight lang="ini">
[Unit]
Description=Minecraft Java Server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple

User=minecraft
Group=minecraft

WorkingDirectory=/opt/minecraft/server

ExecStart=/usr/bin/java \
-Xms4G \
-Xmx6G \
-jar /opt/minecraft/server/server.jar \
nogui

Restart=on-failure
RestartSec=10

SuccessExitStatus=0 143

LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
</syntaxhighlight>

Применяем:

<syntaxhighlight lang="bash">
systemctl daemon-reload
systemctl enable --now minecraft
</syntaxhighlight>

Проверяем:

<syntaxhighlight lang="bash">
systemctl status minecraft
</syntaxhighlight>

== Управление сервером ==

Запуск:

<syntaxhighlight lang="bash">
systemctl start minecraft
</syntaxhighlight>

Остановка:

<syntaxhighlight lang="bash">
systemctl stop minecraft
</syntaxhighlight>

Перезапуск:

<syntaxhighlight lang="bash">
systemctl restart minecraft
</syntaxhighlight>

Статус:

<syntaxhighlight lang="bash">
systemctl status minecraft
</syntaxhighlight>

Логи:

<syntaxhighlight lang="bash">
journalctl -u minecraft -f
</syntaxhighlight>

Последние 100 строк:

<syntaxhighlight lang="bash">
journalctl -u minecraft -n 100
</syntaxhighlight>

== Подключение через RCON ==

Под пользователем Minecraft:

<syntaxhighlight lang="bash">
su - minecraft
</syntaxhighlight>

Подключение:

<syntaxhighlight lang="bash">
/opt/minecraft/tools/mcrcon/mcrcon \
-H 127.0.0.1 \
-P 25575 \
-p 'CHANGE_THIS_PASSWORD' \
-t
</syntaxhighlight>

После подключения можно выполнять команды сервера:

<syntaxhighlight lang="text">
list
say Server restart in 5 minutes
save-all
whitelist list
stop
</syntaxhighlight>

Выход из интерактивного режима mcrcon:

<syntaxhighlight lang="text">
Q
</syntaxhighlight>

== Настройка Firewall ==

Для игроков требуется только:

<syntaxhighlight lang="text">
25565/TCP
</syntaxhighlight>

При использовании UFW:

<syntaxhighlight lang="bash">
ufw allow 25565/tcp
</syntaxhighlight>

Проверяем:

<syntaxhighlight lang="bash">
ufw status
</syntaxhighlight>

'''RCON-порт 25575/TCP не следует открывать для всего Интернета.'''

Если сервер находится в LXC или VM под Proxmox, правила можно централизованно управлять через Proxmox Firewall.

== Проверка порта Minecraft ==

Проверяем локально:

<syntaxhighlight lang="bash">
ss -ltnp | grep 25565
</syntaxhighlight>

Ожидаемый результат:

<syntaxhighlight lang="text">
LISTEN ... :25565
</syntaxhighlight>

Также можно проверить процесс:

<syntaxhighlight lang="bash">
ps aux | grep '[s]erver.jar'
</syntaxhighlight>

== Резервное копирование ==

Для корректного backup мира желательно сначала заставить Minecraft записать данные на диск.

Создаём конфигурационный файл для RCON:

<syntaxhighlight lang="bash">
nano /opt/minecraft/.rcon.env
</syntaxhighlight>

Содержимое:

<syntaxhighlight lang="bash">
RCON_HOST=127.0.0.1
RCON_PORT=25575
RCON_PASSWORD='CHANGE_THIS_PASSWORD'
</syntaxhighlight>

Ограничиваем доступ:

<syntaxhighlight lang="bash">
chown minecraft:minecraft /opt/minecraft/.rcon.env
chmod 600 /opt/minecraft/.rcon.env
</syntaxhighlight>

Создаём backup-скрипт:

<syntaxhighlight lang="bash">
nano /opt/minecraft/tools/backup.sh
</syntaxhighlight>

Содержимое:

<syntaxhighlight lang="bash">
#!/bin/bash

set -e

source /opt/minecraft/.rcon.env

RCON="/opt/minecraft/tools/mcrcon/mcrcon"

BACKUP_DIR="/opt/minecraft/backups"
SERVER_DIR="/opt/minecraft/server"

TIMESTAMP="$(date +%F-%H-%M-%S)"
BACKUP_FILE="${BACKUP_DIR}/minecraft-${TIMESTAMP}.tar.gz"

$RCON \
-H "$RCON_HOST" \
-P "$RCON_PORT" \
-p "$RCON_PASSWORD" \
"save-off"

$RCON \
-H "$RCON_HOST" \
-P "$RCON_PORT" \
-p "$RCON_PASSWORD" \
"save-all flush"

tar \
--exclude='./logs' \
-czf "$BACKUP_FILE" \
-C "$SERVER_DIR" \
.

$RCON \
-H "$RCON_HOST" \
-P "$RCON_PORT" \
-p "$RCON_PASSWORD" \
"save-on"

find "$BACKUP_DIR" \
-type f \
-name 'minecraft-*.tar.gz' \
-mtime +7 \
-delete
</syntaxhighlight>

Делаем исполняемым:

<syntaxhighlight lang="bash">
chmod +x /opt/minecraft/tools/backup.sh
chown minecraft:minecraft /opt/minecraft/tools/backup.sh
</syntaxhighlight>

Тестируем:

<syntaxhighlight lang="bash">
su - minecraft -c '/opt/minecraft/tools/backup.sh'
</syntaxhighlight>

Проверяем:

<syntaxhighlight lang="bash">
ls -lh /opt/minecraft/backups/
</syntaxhighlight>

== Автоматическое резервное копирование ==

Переходим:

<syntaxhighlight lang="bash">
su - minecraft
</syntaxhighlight>

Открываем:

<syntaxhighlight lang="bash">
crontab -e
</syntaxhighlight>

Например, ежедневный backup в 04:00:

<syntaxhighlight lang="cron">
0 4 * * * /opt/minecraft/tools/backup.sh >> /opt/minecraft/backups/backup.log 2>&1
</syntaxhighlight>

Проверяем:

<syntaxhighlight lang="bash">
crontab -l
</syntaxhighlight>

== Обновление Minecraft Server ==

Перед обновлением:

# создаём резервную копию;
# останавливаем сервер;
# сохраняем старый `server.jar`;
# устанавливаем новый;
# запускаем сервер;
# проверяем логи и совместимость мира.

Пример:

<syntaxhighlight lang="bash">
systemctl stop minecraft

cp /opt/minecraft/server/server.jar \
/opt/minecraft/server/server.jar.old
</syntaxhighlight>

После загрузки нового файла:

<syntaxhighlight lang="bash">
systemctl start minecraft
journalctl -u minecraft -f
</syntaxhighlight>

== Проверка ресурсов ==

CPU и память:

<syntaxhighlight lang="bash">
top
</syntaxhighlight>

или:

<syntaxhighlight lang="bash">
htop
</syntaxhighlight>

Память:

<syntaxhighlight lang="bash">
free -h
</syntaxhighlight>

Диск:

<syntaxhighlight lang="bash">
df -h
</syntaxhighlight>

Размер мира:

<syntaxhighlight lang="bash">
du -sh /opt/minecraft/server/world*
</syntaxhighlight>

== Java и Minecraft ==

Требования Java меняются вместе с Minecraft.

Общее правило:

{| class="wikitable"
! Minecraft
! Java
|-
| 1.20.5 и новее
| Java 21
|-
| Старые версии
| Требования зависят от конкретного релиза
|}

Перед обновлением необходимо проверять требования именно для устанавливаемой версии Minecraft.

Не стоит обновлять Java исключительно потому, что появилась более новая версия JDK.

== Типичные проблемы ==

=== Сервер не запускается ===

Проверяем:

<syntaxhighlight lang="bash">
systemctl status minecraft
journalctl -u minecraft -n 100
</syntaxhighlight>

=== Ошибка памяти ===

Проверяем:

<syntaxhighlight lang="bash">
free -h
</syntaxhighlight>

При необходимости уменьшаем:

<syntaxhighlight lang="text">
-Xmx
</syntaxhighlight>

=== Клиенты не подключаются ===

Проверяем:

<syntaxhighlight lang="bash">
ss -ltnp | grep 25565
</syntaxhighlight>

Затем:

* Firewall;
* NAT;
* проброс портов;
* публичный IP;
* `server-port`;
* `server-ip`.

Обычно `server-ip` рекомендуется оставлять пустым.

=== RCON не работает ===

Проверяем:

<syntaxhighlight lang="bash">
grep -E 'enable-rcon|rcon.port' \
/opt/minecraft/server/server.properties
</syntaxhighlight>

И:

<syntaxhighlight lang="bash">
ss -ltnp | grep 25575
</syntaxhighlight>

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

Для production-сервера рекомендуется:

* запускать Minecraft от отдельного пользователя;
* использовать systemd;
* не открывать RCON в Интернет;
* выполнять ежедневные backup;
* хранить резервные копии вне основного сервера;
* использовать SSD;
* контролировать свободное место;
* регулярно проверять логи;
* делать backup перед обновлением;
* обновлять сервер только после проверки совместимости Java и Minecraft.

== Полезные команды ==

{| class="wikitable"
! Задача
! Команда
|-
| Запуск
| <code>systemctl start minecraft</code>
|-
| Остановка
| <code>systemctl stop minecraft</code>
|-
| Перезапуск
| <code>systemctl restart minecraft</code>
|-
| Статус
| <code>systemctl status minecraft</code>
|-
| Логи
| <code>journalctl -u minecraft -f</code>
|-
| Проверить порт
| <code>ss -ltnp | grep 25565</code>
|-
| Проверить Java
| <code>java -version</code>
|-
| Проверить память
| <code>free -h</code>
|-
| Проверить диск
| <code>df -h</code>
|}

== Итоговая архитектура ==

<syntaxhighlight lang="text">
Minecraft Client
│
│ TCP :25565
▼
┌──────────────────────────┐
│ Minecraft Server │
│ │
│ server.jar │
└────────────┬─────────────┘
│
┌────────────┼────────────┐
│ │ │
▼ ▼ ▼
systemd mcrcon backups
│
▼
localhost RCON
</syntaxhighlight>

Такой вариант удобен для постоянной эксплуатации, обновления, диагностики и восстановления сервера.

== См. также ==

* [[Proxmox VE]]
* [[Linux]]
* [[Minecraft]]
* [[Резервное копирование]]
* [[Мониторинг]]

== Внешние ссылки ==

* [https://www.minecraft.net/ Официальный сайт Minecraft]
* [https://www.minecraft.net/download/server Minecraft Java Server]
* [https://github.com/Tiiffi/mcrcon mcrcon]

[[Категория:Minecraft]]
[[Категория:Linux]]
[[Категория:Ubuntu]]
[[Категория:Игровые серверы]]
[[Категория:Администрирование]]
[[Категория:RAMBA ART]]

BrainyCP

2026-09-02T10:27:34Z

Artem:

<div class="portal-header">
<div class="portal-title">BrainyCP</div>
<div class="portal-subtitle">
Панель управления веб-инфраструктурой RAMBA ART
</div>
</div>

<div class="portal-card">
'''BrainyCP''' — панель управления Linux-сервером и веб-хостингом, используемая в инфраструктуре '''RAMBA ART''' для управления веб-сервисами, доменами, SSL-сертификатами и reverse proxy.

В инфраструктуре RAMBA ART BrainyCP выполняет роль внешней точки входа для ряда внутренних сервисов, включая '''RAMBA Wiki'''.
</div>

__TOC__

== Обзор ==

BrainyCP позволяет выполнять большую часть повседневных операций с веб-сервером через графический интерфейс, сохраняя возможность ручного администрирования через SSH.

Основные возможности:

* управление доменами и сайтами;
* Nginx и Apache;
* PHP и PHP-FPM;
* MariaDB / MySQL;
* SSL-сертификаты Let's Encrypt;
* FTP;
* почтовые службы;
* резервное копирование;
* firewall;
* управление пользователями;
* reverse proxy;
* просмотр журналов и диагностика веб-сервисов.

Официальный сайт: [https://brainycp.com/ brainycp.com]

== BrainyCP в инфраструктуре RAMBA ART ==

В нашей инфраструктуре BrainyCP используется не только как обычная hosting-панель.

Он также выполняет функцию '''reverse proxy''' между Интернетом и внутренними сервисами.

<syntaxhighlight lang="text">
INTERNET
│
│ HTTPS :443
▼
┌─────────────────┐
│ BrainyCP │
│ Reverse Proxy │
└────────┬────────┘
│
┌──────────────┼──────────────┐
│ │ │
▼ ▼ ▼
RAMBA Wiki RAMBA Matrix ownCloud
│ │ │
▼ ▼ ▼
MediaWiki Dendrite ownCloud
</syntaxhighlight>

Такой подход позволяет держать приложения на отдельных виртуальных машинах и LXC-контейнерах, а управление HTTPS выполнять централизованно.

=== Пример: RAMBA Wiki ===

Для Wiki используется схема:

<syntaxhighlight lang="text">
Пользователь
│
│ HTTPS
▼
wiki.ramba-art.ru
│
▼
BrainyCP / Nginx
│
│ HTTP
▼
192.168.1.79:80
│
▼
MediaWiki
</syntaxhighlight>

Таким образом, TLS завершается на BrainyCP, после чего запрос передаётся внутреннему серверу MediaWiki.

== Системные требования ==

Для отдельного сервера BrainyCP рекомендуется использовать чистую установку Linux.

{| class="wikitable"
! Параметр
! Минимально
! Рекомендуется
|-
| ОС
| Поддерживаемая версия Linux
| Актуальная стабильная версия
|-
| RAM
| 2 ГБ
| 4 ГБ и более
|-
| Диск
| 20 ГБ
| SSD, 40+ ГБ
|-
| Сеть
| Интернет
| Статический IP
|-
| Доступ
| root
| SSH + root/sudo
|}

Перед установкой необходимо проверить актуальный список поддерживаемых ОС в документации BrainyCP.

== Установка ==

{{Warning|BrainyCP рекомендуется устанавливать на чистую систему. Наличие заранее настроенных Apache, Nginx, PHP или MariaDB может привести к конфликтам.}}

Подключаемся к серверу по SSH.

Обновляем систему:

<syntaxhighlight lang="bash">
apt update
apt upgrade -y
</syntaxhighlight>

После этого запускаем официальный установщик BrainyCP:

<syntaxhighlight lang="bash">
curl -s https://core.brainycp.com/install.sh | bash
</syntaxhighlight>

Процесс установки может занять некоторое время.

После завершения установщик покажет данные для доступа к панели.

== Первый вход ==

Панель управления доступна через HTTPS на управляющем порту BrainyCP.

Пример:

<syntaxhighlight lang="text">
https://SERVER_IP:8000
</syntaxhighlight>

После первого входа рекомендуется:

# изменить пароль администратора;
# проверить имя сервера;
# настроить часовой пояс;
# проверить сетевые параметры;
# установить обновления;
# настроить firewall;
# проверить доступность панели извне.

== Домены и сайты ==

Создание нового сайта выполняется через управление доменами BrainyCP.

Обычно необходимо указать:

* доменное имя;
* владельца;
* каталог сайта;
* версию PHP;
* используемый веб-сервер;
* параметры SSL.

После создания домена BrainyCP автоматически формирует необходимую конфигурацию веб-сервера.

== Веб-сервер ==

BrainyCP поддерживает различные варианты конфигурации.

{| class="wikitable"
! Режим
! Назначение
|-
| '''Nginx'''
| Высокопроизводительная обработка HTTP/HTTPS и reverse proxy
|-
| '''Apache'''
| Совместимость с приложениями, использующими Apache и .htaccess
|-
| '''Nginx + Apache'''
| Nginx работает фронтендом, Apache обслуживает backend
|}

Для инфраструктуры RAMBA ART особенно важен '''Nginx''', поскольку он используется в качестве reverse proxy.

== Reverse Proxy ==

Reverse proxy позволяет принимать запросы на публичном домене и перенаправлять их на внутренний сервер.

Например:

<syntaxhighlight lang="nginx">
location / {
proxy_pass http://192.168.1.79:80;

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
</syntaxhighlight>

В данном примере:

<syntaxhighlight lang="text">
wiki.ramba-art.ru
│
▼
BrainyCP
│
▼
192.168.1.79:80
</syntaxhighlight>

При изменении внутреннего IP сервиса достаточно изменить upstream на BrainyCP — публичный адрес сайта остаётся прежним.

=== Проверка конфигурации ===

После изменения Nginx обязательно проверяем конфигурацию:

<syntaxhighlight lang="bash">
nginx -t
</syntaxhighlight>

При успешной проверке:

<syntaxhighlight lang="text">
syntax is ok
test is successful
</syntaxhighlight>

После этого применяем изменения:

<syntaxhighlight lang="bash">
systemctl reload nginx
</syntaxhighlight>

== SSL / Let's Encrypt ==

BrainyCP позволяет выпускать сертификаты Let's Encrypt для добавленных доменов.

Перед выпуском сертификата необходимо убедиться, что:

* DNS-запись домена указывает на сервер;
* порты 80 и 443 доступны;
* домен добавлен в BrainyCP;
* веб-сервер корректно отвечает на запросы.

После выпуска сертификата рекомендуется проверить автоматическое продление.

Для reverse proxy схема выглядит следующим образом:

<syntaxhighlight lang="text">
CLIENT
│
│ HTTPS
▼
BrainyCP
│
│ TLS termination
▼
HTTP / HTTPS backend
</syntaxhighlight>

== PHP ==

Для сайтов, размещённых непосредственно на BrainyCP, панель позволяет управлять версиями PHP и параметрами PHP-FPM.

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

<syntaxhighlight lang="bash">
systemctl --type=service | grep -i php
</syntaxhighlight>

Конкретное имя PHP-FPM зависит от установленной версии PHP.

Например:

<syntaxhighlight lang="bash">
systemctl status php8.2-fpm
</syntaxhighlight>

== Базы данных ==

BrainyCP предоставляет управление MariaDB/MySQL и позволяет создавать:

* базы данных;
* пользователей;
* пароли;
* права доступа.

Для графического администрирования может использоваться phpMyAdmin.

Для production-систем рекомендуется:

* создавать отдельного пользователя для каждого приложения;
* не использовать root-пользователя БД в приложениях;
* использовать уникальные пароли;
* регулярно выполнять резервное копирование.

== MediaWiki за BrainyCP ==

RAMBA Wiki работает на отдельном сервере MediaWiki, а BrainyCP используется как внешний reverse proxy.

Это отличается от установки MediaWiki непосредственно внутрь hosting-окружения BrainyCP.

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

<syntaxhighlight lang="text">
┌──────────────────────────────┐
│ Internet │
└──────────────┬───────────────┘
│
│ HTTPS
▼
┌──────────────────────────────┐
│ BrainyCP │
│ Nginx │
│ SSL termination │
└──────────────┬───────────────┘
│
│ HTTP
▼
┌──────────────────────────────┐
│ MediaWiki LXC │
│ │
│ MediaWiki + Apache + PHP │
│ MariaDB │
└──────────────────────────────┘
</syntaxhighlight>

Преимущество такой схемы — MediaWiki можно обновлять, переносить или восстанавливать независимо от reverse proxy.

=== X-Forwarded-Proto ===

При завершении HTTPS на reverse proxy backend должен понимать, что исходное соединение пользователя было защищённым.

Nginx передаёт:

<syntaxhighlight lang="nginx">
proxy_set_header X-Forwarded-Proto $scheme;
</syntaxhighlight>

На стороне MediaWiki это необходимо учитывать в конфигурации, иначе могут возникать:

* неправильные HTTP-ссылки;
* циклические redirect;
* проблемы с cookies;
* ошибки определения HTTPS.

== Диагностика ==

=== Nginx ===

Проверка службы:

<syntaxhighlight lang="bash">
systemctl status nginx
</syntaxhighlight>

Проверка конфигурации:

<syntaxhighlight lang="bash">
nginx -t
</syntaxhighlight>

Перезагрузка конфигурации:

<syntaxhighlight lang="bash">
systemctl reload nginx
</syntaxhighlight>

=== Apache ===

В зависимости от системы:

<syntaxhighlight lang="bash">
systemctl status apache2
</syntaxhighlight>

или:

<syntaxhighlight lang="bash">
systemctl status httpd
</syntaxhighlight>

=== Проверка HTTP ===

Для проверки сайта непосредственно из консоли:

<syntaxhighlight lang="bash">
curl -I https://example.ru/
</syntaxhighlight>

Для подробной диагностики:

<syntaxhighlight lang="bash">
curl -Iv https://example.ru/
</syntaxhighlight>

=== Проверка backend ===

Reverse proxy можно исключить из цепочки и проверить backend непосредственно:

<syntaxhighlight lang="bash">
curl -I http://BACKEND_IP/
</syntaxhighlight>

Это позволяет быстро определить, где находится проблема:

<syntaxhighlight lang="text">
Internet
│
▼
DNS
│
▼
BrainyCP / Nginx
│
▼
Backend
│
▼
Application
</syntaxhighlight>

== Резервное копирование ==

Резервные копии рекомендуется хранить '''вне сервера BrainyCP'''.

Необходимо учитывать как минимум:

* конфигурации веб-сервера;
* SSL-сертификаты;
* базы данных;
* файлы сайтов;
* конфигурацию BrainyCP.

Если BrainyCP работает в виртуальной машине или LXC-контейнере, желательно дополнительно использовать резервное копирование на уровне гипервизора.

== Безопасность ==

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

* не публиковать управляющую панель без необходимости;
* использовать сложный пароль администратора;
* ограничить SSH;
* своевременно устанавливать обновления;
* использовать HTTPS;
* контролировать открытые порты;
* регулярно проверять журналы Nginx;
* хранить резервные копии отдельно;
* не использовать root для работы веб-приложений;
* перед изменением production-конфигурации сохранять рабочую версию.

== Полезные команды ==

{| class="wikitable"
! Задача
! Команда
|-
| Проверить Nginx
| <code>nginx -t</code>
|-
| Статус Nginx
| <code>systemctl status nginx</code>
|-
| Применить конфигурацию
| <code>systemctl reload nginx</code>
|-
| Перезапустить Nginx
| <code>systemctl restart nginx</code>
|-
| Проверить сайт
| <code>curl -I https://example.ru/</code>
|-
| Подробный HTTPS-тест
| <code>curl -Iv https://example.ru/</code>
|-
| Проверить порты
| <code>ss -tulpn</code>
|-
| Журнал Nginx
| <code>journalctl -u nginx</code>
|}

== Заключение ==

BrainyCP удобно использовать не только как классическую hosting-панель, но и как центральный узел управления веб-инфраструктурой.

В архитектуре '''RAMBA ART''' особенно полезна связка:

<syntaxhighlight lang="text">
DNS
│
▼
BrainyCP
│
├── SSL
├── Nginx
├── Reverse Proxy
│
▼
Внутренние сервисы RAMBA ART
</syntaxhighlight>

Она позволяет отделить публичный веб-уровень от серверов приложений и независимо обслуживать MediaWiki, Matrix, облачные и другие сервисы.

== См. также ==

* [[Миграция RAMBA Wiki на MediaWiki 1.43]]
* [[Proxmox VE]]
* [[RAMBA Matrix]]
* [[RAMBA ART Infrastructure]]

== Внешние ссылки ==

* [https://brainycp.com/ Официальный сайт BrainyCP]
* [https://docs.brainycp.com/ Документация BrainyCP]

[[Категория:BrainyCP]]
[[Категория:Linux]]
[[Категория:Веб-инфраструктура]]
[[Категория:Администрирование]]
[[Категория:RAMBA ART]]

Мониторинг

2026-09-02T09:10:00Z

Artem: Содержимое страницы заменено на «<rambamonitor />»

Миграция RAMBA Wiki на MediaWiki 1 43

2026-09-02T08:57:38Z

Artem: Artem переименовал страницу Миграция RAMBA Wiki на MediaWiki 1 43 в RAMBA Wiki Migration 1.43

#перенаправление [[RAMBA Wiki Migration 1.43]]

RAMBA Wiki Migration 1.43

2026-09-02T08:57:38Z

Artem: Artem переименовал страницу Миграция RAMBA Wiki на MediaWiki 1 43 в RAMBA Wiki Migration 1.43

__TOC__

<div class="portal-header">
<div style="font-size:2em; font-weight:700;">🚀 Миграция RAMBA Wiki на MediaWiki 1.43</div>
<div style="margin-top:8px; opacity:.85;">
Переезд RAMBA Wiki со старого TurnKey Linux / MediaWiki 1.39 на новую инфраструктуру Debian 12 и MediaWiki 1.43 LTS.
</div>
</div>

{{DISPLAYTITLE:Миграция RAMBA Wiki на MediaWiki 1.43}}

== Общая информация ==

В сентябре 2026 года была выполнена полная миграция '''RAMBA Wiki''' на новую платформу.

Основной задачей было заменить устаревшую установку MediaWiki, сохранив:

* все существующие статьи;
* историю изменений;
* пользователей и права доступа;
* загруженные изображения;
* оформление Wiki;
* мобильную версию;
* необходимые расширения;
* собственное расширение '''RambaGameMonitor''';
* существующий публичный адрес '''wiki.ramba-art.ru'''.

Миграция выполнялась по схеме '''parallel migration''': старая Wiki продолжала существовать во время подготовки новой системы и использовалась как аварийный вариант возврата.

После полного тестирования трафик был переключён на новую Wiki, а старая система была сохранена в Proxmox Backup Server и удалена из рабочей инфраструктуры.

== Исходная система ==

До миграции RAMBA Wiki работала в контейнере Proxmox:

{| class="wikitable"
! Параметр
! Значение
|-
| Proxmox CT
| '''115'''
|-
| Имя
| '''WiKi'''
|-
| Дистрибутив
| TurnKey MediaWiki 17.1 / Debian 11 Bullseye
|-
| MediaWiki
| '''1.39.2 LTS'''
|-
| PHP
| 7.4
|-
| MariaDB
| 10.5
|-
| Web-сервер
| Apache 2.4
|-
| IP
| 192.168.1.11
|-
| RAM
| 512 MB
|-
| CPU
| 1 vCPU
|-
| Диск
| 8 GB
|}

MediaWiki 1.39 к моменту миграции уже являлась устаревшей веткой, поэтому было принято решение не обновлять существующий TurnKey-контейнер на месте, а построить новую систему.

== Новая архитектура ==

Для новой RAMBA Wiki был создан отдельный LXC-контейнер:

{| class="wikitable"
! Параметр
! Значение
|-
| Proxmox CT
| '''102'''
|-
| Имя
| '''wiki-v2'''
|-
| ОС
| Debian 12 Bookworm
|-
| MediaWiki
| '''1.43.9 LTS'''
|-
| PHP
| 8.2
|-
| MariaDB
| 10.11
|-
| Web-сервер
| Apache 2.4
|-
| IP
| '''192.168.1.79'''
|-
| RAM
| 2048 MB
|-
| Swap
| 512 MB
|-
| CPU
| 2 vCPU
|-
| RootFS
| 16 GB
|-
| Storage
| OMV-SSD1
|}

Система работает как unprivileged LXC-контейнер.

== Схема работы ==

Публичный HTTPS завершается на reverse proxy BrainyCP.

<syntaxhighlight lang="text">
Internet
│
│ HTTPS :443
▼
wiki.ramba-art.ru
│
▼
BrainyCP / nginx
CT 105
192.168.1.12
│
│ HTTP :80
▼
RAMBA Wiki
CT 102 — wiki-v2
192.168.1.79
│
├── Apache
├── PHP 8.2
├── MediaWiki 1.43
└── MariaDB 10.11
</syntaxhighlight>

TLS-сертификат обслуживается reverse proxy.

Сам MediaWiki-контейнер не требует собственного HTTPS-сервера.

== Создание нового контейнера ==

Новая Wiki была развёрнута на чистом Debian 12.

Основные установленные компоненты:

<syntaxhighlight lang="bash">
apache2
mariadb-server
imagemagick

php8.2
libapache2-mod-php8.2
php8.2-mysql
php8.2-intl
php8.2-mbstring
php8.2-xml
php8.2-curl
php8.2-gd
php8.2-zip
php8.2-apcu
</syntaxhighlight>

Для Apache были активированы необходимые модули:

<syntaxhighlight lang="bash">
a2enmod rewrite
a2enmod headers
a2enmod expires
</syntaxhighlight>

Основная директория MediaWiki:

<syntaxhighlight lang="text">
/var/www/mediawiki
</syntaxhighlight>

== Перенос базы данных ==

База данных старой Wiki была экспортирована из CT 115 и импортирована в MariaDB нового CT 102.

После импорта был выполнен штатный процесс обновления схемы базы данных MediaWiki.

<syntaxhighlight lang="bash">
cd /var/www/mediawiki
runuser -u www-data -- php maintenance/run.php update
</syntaxhighlight>

Обновление схемы прошло успешно.

В результате были сохранены:

* статьи;
* ревизии;
* категории;
* пользователи;
* права пользователей;
* служебные страницы MediaWiki;
* история изменений.

== Перенос изображений ==

Каталог загруженных файлов старой Wiki был перенесён в:

<syntaxhighlight lang="text">
/var/www/mediawiki/images
</syntaxhighlight>

После переноса были восстановлены корректные права доступа для Apache:

<syntaxhighlight lang="bash">
chown -R www-data:www-data /var/www/mediawiki/images
find /var/www/mediawiki/images -type d -exec chmod 755 {} \;
find /var/www/mediawiki/images -type f -exec chmod 644 {} \;
</syntaxhighlight>

Также был перенесён логотип RAMBA Wiki:

<syntaxhighlight lang="text">
/var/www/mediawiki/resources/assets/ramba_b.png
</syntaxhighlight>

== Короткие URL ==

Для статей сохранена привычная структура адресов:

<syntaxhighlight lang="text">
https://wiki.ramba-art.ru/wiki/Название_страницы
</syntaxhighlight>

В MediaWiki используется:

<syntaxhighlight lang="php">
$wgScriptPath = "";
$wgArticlePath = "/wiki/$1";
$wgServer = "https://wiki.ramba-art.ru";
</syntaxhighlight>

Apache выполняет перенаправление запросов вида:

<syntaxhighlight lang="text">
/wiki/Название
</syntaxhighlight>

на MediaWiki `index.php`.

== Reverse Proxy ==

Reverse proxy RAMBA Wiki находится в BrainyCP:

{| class="wikitable"
! Параметр
! Значение
|-
| Proxmox CT
| 105
|-
| IP
| 192.168.1.12
|-
| Web-сервер
| nginx
|-
| Backend
| 192.168.1.79:80
|-
| Frontend
| HTTPS :443
|}

Основной upstream:

<syntaxhighlight lang="nginx">
location / {
proxy_pass http://192.168.1.79:80;

proxy_http_version 1.1;

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Proto https;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port 443;

proxy_redirect off;
}
</syntaxhighlight>

До миграции upstream указывал на старый сервер:

<syntaxhighlight lang="text">
192.168.1.11:80
</syntaxhighlight>

После проверки новой Wiki он был изменён на:

<syntaxhighlight lang="text">
192.168.1.79:80
</syntaxhighlight>

Это позволило переключить production без изменения DNS.

== HTTPS за reverse proxy ==

Поскольку HTTPS завершается на nginx, а между nginx и Apache используется HTTP, MediaWiki необходимо корректно сообщать исходный протокол запроса.

В `LocalSettings.php` добавлена проверка доверенного reverse proxy:

<syntaxhighlight lang="php">
if (
($_SERVER["REMOTE_ADDR"] ?? "") === "192.168.1.12" &&
($_SERVER["HTTP_X_FORWARDED_PROTO"] ?? "") === "https"
) {
$_SERVER["HTTPS"] = "on";
}
</syntaxhighlight>

Заголовок `X-Forwarded-Proto` принимается только от reverse proxy RAMBA с адресом `192.168.1.12`.

== Мобильная версия ==

Для мобильного интерфейса используются:

* '''MobileFrontend'''
* '''MinervaNeue'''

Конфигурация:

<syntaxhighlight lang="php">
wfLoadSkin( 'MinervaNeue' );

$wgDefaultMobileSkin = 'minerva';

wfLoadExtension( 'MobileFrontend' );
</syntaxhighlight>

Расширение MobileFrontend установлено в версии, совместимой с MediaWiki 1.43.

После миграции была дополнительно переработана главная страница RAMBA Wiki, чтобы карточки корректно отображались на небольших экранах.

На мобильных устройствах карточки автоматически перестраиваются в один столбец.

== Редактирование исходного кода ==

Для работы с исходным кодом страниц используются:

<syntaxhighlight lang="php">
wfLoadExtension( 'WikiEditor' );
wfLoadExtension( 'CodeEditor' );
wfLoadExtension( 'SyntaxHighlight_GeSHi' );

$wgDefaultUserOptions['usebetatoolbar'] = 1;
$wgWikiEditorRealtimePreview = true;
</syntaxhighlight>

`SyntaxHighlight_GeSHi` используется для оформления команд, конфигурационных файлов и программного кода в технических статьях RAMBA Wiki.

== Основные расширения ==

После миграции были активированы необходимые стандартные расширения:

<syntaxhighlight lang="php">
wfLoadExtension( 'ParserFunctions' );
wfLoadExtension( 'Cite' );
wfLoadExtension( 'TemplateData' );
wfLoadExtension( 'InputBox' );
wfLoadExtension( 'ImageMap' );
wfLoadExtension( 'Nuke' );
wfLoadExtension( 'ReplaceText' );
</syntaxhighlight>

== DynamicPageList3 ==

Для существующих страниц RAMBA Wiki была сохранена поддержка DynamicPageList3.

Установлен:

<syntaxhighlight lang="text">
DynamicPageList3 3.5.2
</syntaxhighlight>

Активация:

<syntaxhighlight lang="php">
wfLoadExtension( 'DynamicPageList3' );
</syntaxhighlight>

После установки расширение было проверено на MediaWiki 1.43.

== RambaGameMonitor ==

Сохранено собственное расширение '''RambaGameMonitor'''.

Расширение предоставляет тег:

<syntaxhighlight lang="text">
<rambamonitor />
</syntaxhighlight>

который позволяет отображать состояние игровых серверов непосредственно на страницах RAMBA Wiki.

В текущей реализации выполняются запросы:

* Rust — Source Engine Query / UDP;
* Minecraft Java Edition — Server List Ping / TCP.

Пример результата:

{| class="wikitable"
! Сервер
! Состояние
! Игроки
! Дополнительная информация
|-
| Rust
| Online / Offline
| текущие / максимум
| карта
|-
| Minecraft
| Online / Offline
| текущие / максимум
| версия
|}

После переноса расширение было проверено непосредственно на MediaWiki 1.43 и PHP 8.2.

== Отказ от устаревших компонентов ==

Во время миграции была проведена ревизия расширений старой Wiki.

Некоторые компоненты намеренно не переносились.

{| class="wikitable"
! Компонент
! Решение
! Причина
|-
| GameQ
| Не переносить
| RambaGameMonitor больше не зависит от GameQ
|-
| LocalisationUpdate
| Не переносить
| Устаревшее расширение
|-
| GoogleCodePrettify
| Не переносить
| Заменено SyntaxHighlight
|-
| Renameuser
| Не переносить
| Функциональность присутствует в современном MediaWiki
|}

Таким образом новая установка не является простой копией старого сервера — устаревшие компоненты были удалены.

== Права доступа ==

Анонимным пользователям разрешено чтение Wiki, но запрещено редактирование и самостоятельная регистрация.

<syntaxhighlight lang="php">
$wgGroupPermissions['*']['read'] = true;
$wgGroupPermissions['*']['edit'] = false;
$wgGroupPermissions['*']['createpage'] = false;
$wgGroupPermissions['*']['createaccount'] = false;

$wgGroupPermissions['user']['edit'] = true;
$wgGroupPermissions['user']['createpage'] = true;
</syntaxhighlight>

Для администратора Wiki дополнительно было назначено право:

<syntaxhighlight lang="text">
interface-admin
</syntaxhighlight>

Это необходимо для редактирования системных CSS/JS-страниц, включая:

<syntaxhighlight lang="text">
MediaWiki:Common.css
</syntaxhighlight>

== Безопасность ==

После миграции были сгенерированы новые значения:

<syntaxhighlight lang="text">
$wgSecretKey
$wgUpgradeKey
</syntaxhighlight>

Старые значения больше не используются.

Значения ключей в документации намеренно не публикуются.

Пароль базы данных также не должен храниться в статьях Wiki или открытых конфигурационных примерах.

== Резервное копирование ==

После успешного запуска production была создана полная резервная копия нового CT 102 в '''Proxmox Backup Server'''.

Идентификатор backup:

<syntaxhighlight lang="text">
ct/102/2026-09-02T08:36:30Z
</syntaxhighlight>

Объём файловой системы на момент резервного копирования составлял приблизительно:

<syntaxhighlight lang="text">
1.77 GiB
</syntaxhighlight>

После дедупликации и сжатия в PBS было передано около:

<syntaxhighlight lang="text">
568 MiB
</syntaxhighlight>

Так как используемое для rootfs NFS-хранилище не поддерживает необходимый тип snapshot, Proxmox автоматически переключил backup из режима `snapshot` в режим `suspend`.

Контейнер был приостановлен приблизительно на две секунды.

Backup завершился успешно.

== Переключение production ==

После проверки новой системы был изменён upstream nginx:

<syntaxhighlight lang="text">
СТАРЫЙ:
192.168.1.11:80

НОВЫЙ:
192.168.1.79:80
</syntaxhighlight>

Перед применением конфигурации nginx была выполнена проверка:

<syntaxhighlight lang="bash">
nginx -t
</syntaxhighlight>

После успешной проверки:

<syntaxhighlight lang="bash">
systemctl reload nginx
</syntaxhighlight>

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

<syntaxhighlight lang="text">
https://wiki.ramba-art.ru/
↓
HTTP 301
↓
https://wiki.ramba-art.ru/wiki/Заглавная_страница
↓
HTTP 200
</syntaxhighlight>

== Проверка после миграции ==

После переключения production были протестированы:

* открытие главной страницы;
* HTTPS;
* короткие URL;
* авторизация;
* редактирование статей;
* редактирование `MediaWiki:Common.css`;
* загрузка файлов;
* отображение изображений;
* мобильный интерфейс;
* MinervaNeue;
* DynamicPageList3;
* SyntaxHighlight;
* RambaGameMonitor;
* Apache;
* MariaDB.

Финальная проверка:

<syntaxhighlight lang="text">
HTTP: 200
Redirects: 1
Final:
https://wiki.ramba-art.ru/wiki/Заглавная_страница
</syntaxhighlight>

== Вывод старой системы из эксплуатации ==

После успешной работы CT 102 старый контейнер CT 115 был остановлен.

После остановки была повторно проверена публичная Wiki:

<syntaxhighlight lang="text">
CT 102: running
CT 115: stopped
wiki.ramba-art.ru: HTTP 200
</syntaxhighlight>

Это подтвердило отсутствие зависимости production от старого контейнера.

После этого была создана финальная резервная копия CT 115 в Proxmox Backup Server.

Старый контейнер был удалён:

<syntaxhighlight lang="bash">
pct destroy 115
</syntaxhighlight>

Proxmox подтвердил удаление старого диска:

<syntaxhighlight lang="text">
Logical volume "vm-115-disk-0" successfully removed.
</syntaxhighlight>

После полного удаления CT 115 Wiki была проверена ещё раз:

<syntaxhighlight lang="text">
HTTP: 200
Time: 0.262066s
</syntaxhighlight>

Таким образом старая установка полностью выведена из эксплуатации.

== Итоговая конфигурация ==

<div class="portal-grid">

<div class="portal-card">
'''🌐 Production'''

'''wiki.ramba-art.ru'''

MediaWiki 1.43.9 LTS

Debian 12 Bookworm
</div>

<div class="portal-card">
'''📦 Контейнер'''

CT '''102'''

'''wiki-v2'''

192.168.1.79
</div>

<div class="portal-card">
'''🔀 Reverse Proxy'''

BrainyCP

CT '''105'''

192.168.1.12
</div>

<div class="portal-card">
'''💾 Backup'''

Proxmox Backup Server

Резервируются новая и архивная версии Wiki
</div>

</div>

== Результат ==

Миграция RAMBA Wiki выполнена успешно.

Старая архитектура:

<syntaxhighlight lang="text">
TurnKey Linux
Debian 11
MediaWiki 1.39
PHP 7.4
CT 115
192.168.1.11
</syntaxhighlight>

заменена на:

<syntaxhighlight lang="text">
Debian 12
MediaWiki 1.43.9 LTS
PHP 8.2
MariaDB 10.11
CT 102
192.168.1.79
</syntaxhighlight>

При этом были сохранены существующие данные Wiki и необходимые функции, удалены устаревшие компоненты, восстановлена мобильная версия, настроен reverse proxy и HTTPS, обновлены ключи безопасности и создана новая точка восстановления в Proxmox Backup Server.

'''RAMBA Wiki полностью переведена на новую инфраструктуру.'''

[[Категория:RAMBA Wiki]]
[[Категория:MediaWiki]]
[[Категория:Proxmox]]
[[Категория:Инфраструктура RAMBA]]
[[Категория:Миграции]]

RAMBA Wiki Migration 1.43

2026-09-02T08:52:27Z

Artem: Новая страница: «__TOC__ <div class="portal-header"> <div style="font-size:2em; font-weight:700;">🚀 Миграция RAMBA Wiki на MediaWiki 1.43</div> <div style="margin-top:8px; opacity:.85;"> Переезд RAMBA Wiki со старого TurnKey Linux / MediaWiki 1.39 на новую инфраструктуру Debian 12 и MediaWiki 1.43 LTS. </div> </div> {{DISPLAYTITLE:Миграция RAMBA Wiki на MediaWiki 1.43}} == Общая информация == В...»

Gitignore

2026-09-02T08:41:31Z

Artem: /* Python.gitignore */

== Python.gitignore ==

'''Ссылка на [https://github.com/github/gitignore/blob/main/Python.gitignore гитхаб]'''

'''[https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore .gitignore file тут]'''

==0209==

Unit for tg bot

2026-08-31T18:36:12Z

Artem:

= Запуск Python-скрипта как службы systemd =

В Linux Python-скрипт можно запустить как системную службу с помощью ‘’‘systemd’’’ .

Это удобно для Telegram-ботов, веб-сервисов и других приложений, которые должны:

* автоматически запускаться вместе с сервером;
* работать в фоновом режиме;
* автоматически перезапускаться после ошибки;
* управляться стандартными командами systemctl;
* сохранять журнал работы в journalctl.

В этой статье рассмотрим два варианта запуска Python-приложения на примере Telegram-бота ‘’‘noProdaction’’’.

TOC

== Способ №1 — запуск через отдельный shell-скрипт ==

В этом варианте systemd запускает вспомогательный shell-скрипт, который, в свою очередь, запускает Python-приложение.

Схема запуска:

<pre>
systemd
│
▼
noProdaction.sh
│
▼
python3
│
▼
main.py
</pre>

=== Создание скрипта запуска ===

Создаём каталог для скрипта запуска, если его ещё нет:

<syntaxhighlight lang="bash">
mkdir -p /opt/Python/Telegram/start
</syntaxhighlight>

Создаём файл:

<syntaxhighlight lang="bash">
nano /opt/Python/Telegram/start/noProdaction.sh
</syntaxhighlight>

Добавляем:

<syntaxhighlight lang="bash">
#!/bin/bash

exec /usr/bin/python3.11 /opt/Python/Telegram/noProdaction/noprodaction-1/main.py
Сохраняем файл:

<pre>
Ctrl + O
Enter
Ctrl + X
</pre>

Делаем его исполняемым:

<syntaxhighlight lang="bash">
chmod +x /opt/Python/Telegram/start/noProdaction.sh
</syntaxhighlight>

{{Note|Использование exec позволяет заменить процесс shell непосредственно процессом Python. Благодаря этому systemd корректнее отслеживает PID приложения и управляет его завершением.}}

=== Создание systemd unit ===

Создаём unit-файл:

<syntaxhighlight lang="bash">
nano /etc/systemd/system/noprodaction.service
</syntaxhighlight>

Добавляем:

<syntaxhighlight lang="ini">
[Unit]
Description=Telegram bot noProdaction
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/Python/Telegram/noProdaction/noprodaction-1
ExecStart=/opt/Python/Telegram/start/noProdaction.sh

Restart=on-failure
RestartSec=5

NoNewPrivileges=true
PrivateDevices=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target
Сохраняем файл:

<pre>
Ctrl + O
Enter
Ctrl + X
</pre>

=== Активация службы ===

После создания или изменения unit-файла необходимо перечитать конфигурацию systemd:

<syntaxhighlight lang="bash">
systemctl daemon-reload
</syntaxhighlight>

Добавляем службу в автозагрузку:

<syntaxhighlight lang="bash">
systemctl enable noprodaction.service
</syntaxhighlight>

Запускаем:

<syntaxhighlight lang="bash">
systemctl start noprodaction.service
</syntaxhighlight>

Можно выполнить обе команды сразу:

<syntaxhighlight lang="bash">
systemctl enable --now noprodaction.service
</syntaxhighlight>

=== Проверка работы ===

Проверяем состояние:

<syntaxhighlight lang="bash">
systemctl status noprodaction.service
</syntaxhighlight>

При нормальной работе должна присутствовать строка:

<pre>
Active: active (running)
</pre>

Например:

<pre>
● noprodaction.service - Telegram bot noProdaction
Loaded: loaded (/etc/systemd/system/noprodaction.service; enabled)
Active: active (running)
Main PID: 173 (python3.11)
Tasks: 2
Memory: 34.1M
CPU: 1.766s
</pre>

== Способ №2 — запуск Python напрямую из systemd ==

{{Note|’’‘Рекомендуемый вариант.’’’ Если для запуска приложения не требуется выполнять дополнительные команды, создавать отдельный .sh-файл нет необходимости. Python можно запускать непосредственно из systemd.}}

Схема становится проще:

<pre>
systemd
│
▼
python3
│
▼
main.py
</pre>

Создаём unit-файл:

<syntaxhighlight lang="bash">
nano /etc/systemd/system/noprodaction.service
</syntaxhighlight>

Добавляем:

<syntaxhighlight lang="ini">
[Unit]
Description=Telegram bot noProdaction
After=network-online.target
Wants=network-online.target

[Service]
Type=simple

User=root
WorkingDirectory=/opt/Python/Telegram/noProdaction/noprodaction-1

ExecStart=/usr/bin/python3.11 /opt/Python/Telegram/noProdaction/noprodaction-1/main.py

Restart=on-failure
RestartSec=5

NoNewPrivileges=true
PrivateDevices=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target
После создания файла выполняем:

<syntaxhighlight lang="bash">
systemctl daemon-reload
systemctl enable --now noprodaction.service
</syntaxhighlight>

Проверяем:

<syntaxhighlight lang="bash">
systemctl status noprodaction.service
</syntaxhighlight>

== Управление службой ==

После создания unit-файла ботом можно управлять стандартными командами systemd.

{| class=“wikitable”
! Действие

! Команда

Проверить состояние

systemctl status noprodaction

-

Запустить

systemctl start noprodaction

-

Остановить

systemctl stop noprodaction

-

Перезапустить

systemctl restart noprodaction

-

Добавить в автозагрузку

systemctl enable noprodaction

-

Убрать из автозагрузки

systemctl disable noprodaction

}

== Просмотр логов ==

Одно из преимуществ запуска через systemd — вывод Python-приложения автоматически попадает в системный журнал.

Посмотреть последние записи:

<syntaxhighlight lang="bash">
journalctl -u noprodaction.service
</syntaxhighlight>

Последние 100 строк:

<syntaxhighlight lang="bash">
journalctl -u noprodaction.service -n 100
</syntaxhighlight>

Следить за журналом в реальном времени:

<syntaxhighlight lang="bash">
journalctl -u noprodaction.service -f
</syntaxhighlight>

Выйти из режима просмотра:

<pre>
Ctrl + C
</pre>

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

<syntaxhighlight lang="bash">
journalctl -u noprodaction.service -b
</syntaxhighlight>

== После изменения Python-кода ==

Если был изменён только код main.py или других файлов приложения, выполнять daemon-reload не требуется.

Достаточно перезапустить приложение:

<syntaxhighlight lang="bash">
systemctl restart noprodaction
</syntaxhighlight>

Если же был изменён сам файл:

<pre>
/etc/systemd/system/noprodaction.service
</pre>

необходимо выполнить:

<syntaxhighlight lang="bash">
systemctl daemon-reload
systemctl restart noprodaction
</syntaxhighlight>

== Автоматический перезапуск ==

В нашем unit-файле используются параметры:

<syntaxhighlight lang="ini">
Restart=on-failure
RestartSec=5
</syntaxhighlight>

Это означает, что если Python-процесс аварийно завершится, systemd подождёт 5 секунд и попробует запустить его снова.

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

<syntaxhighlight lang="bash">
systemctl show noprodaction.service -p NRestarts
</syntaxhighlight>

== Проверка пути к Python ==

Путь к Python может отличаться в зависимости от системы.

Проверить его можно командой:

<syntaxhighlight lang="bash">
which python3
</syntaxhighlight>

Например:

<pre>
/usr/bin/python3
</pre>

Версию Python:

<syntaxhighlight lang="bash">
python3 --version
</syntaxhighlight>

Если конкретная версия Python не требуется, в unit-файле можно использовать:

<syntaxhighlight lang="ini">
ExecStart=/usr/bin/python3 /opt/Python/Telegram/noProdaction/noprodaction-1/main.py
</syntaxhighlight>

== Запуск через Python Virtual Environment ==

Если проект использует собственное виртуальное окружение Python, рекомендуется запускать Python непосредственно из него.

Например, если виртуальное окружение находится здесь:

<pre>
/opt/Python/Telegram/noProdaction/venv/
</pre>

то ExecStart будет выглядеть так:

<syntaxhighlight lang="ini">
ExecStart=/opt/Python/Telegram/noProdaction/venv/bin/python /opt/Python/Telegram/noProdaction/noprodaction-1/main.py
</syntaxhighlight>

Активировать venv командой source внутри systemd не требуется.

== Рекомендуемый unit-файл ==

Для обычного Python-приложения итоговый вариант может выглядеть следующим образом:

<syntaxhighlight lang="ini">
[Unit]
Description=Telegram bot noProdaction
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root

WorkingDirectory=/opt/Python/Telegram/noProdaction/noprodaction-1
ExecStart=/usr/bin/python3.11 /opt/Python/Telegram/noProdaction/noprodaction-1/main.py

Restart=on-failure
RestartSec=5

NoNewPrivileges=true
PrivateDevices=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target
После создания:

<syntaxhighlight lang="bash">
systemctl daemon-reload
systemctl enable --now noprodaction.service
</syntaxhighlight>

Проверяем:

<syntaxhighlight lang="bash">
systemctl status noprodaction.service
</syntaxhighlight>

и журнал:

<syntaxhighlight lang="bash">
journalctl -u noprodaction.service -f
</syntaxhighlight>

== Примечание по безопасности ==

В примерах выше служба запускается от пользователя:

<syntaxhighlight lang="ini">
User=root
</syntaxhighlight>

Для собственного сервера это работает, однако большинству Python-приложений права root не нужны.

Более безопасный вариант — создать отдельного системного пользователя для приложения и запускать службу от его имени.

Например:

<syntaxhighlight lang="bash">
useradd --system --home /opt/Python/Telegram/noProdaction --shell /usr/sbin/nologin noprodaction
</syntaxhighlight>

После этого необходимо выдать пользователю права на необходимые файлы приложения и заменить в unit-файле:

<syntaxhighlight lang="ini">
User=root
</syntaxhighlight>

на:

<syntaxhighlight lang="ini">
User=noprodaction
</syntaxhighlight>

{{Warning|Не храните токены Telegram-бота, API-ключи, пароли баз данных и другие секреты непосредственно в публичном unit-файле или исходном коде проекта. Для секретов лучше использовать отдельный файл окружения с ограниченными правами доступа.}}

== Итог ==

Для простого Python-приложения рекомендуется использовать ‘’‘Способ №2’’’:

<pre>
Загрузка Linux
│
▼
systemd
│
▼
noprodaction.service
│
▼
Python
│
▼
main.py
│
▼
Telegram Bot
</pre>

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

Unit for tg bot

2026-08-31T18:35:43Z

Artem: /* Запуск Python-скрипта как службы systemd */Обновление статьи

= Запуск Python-скрипта как службы systemd =

В Linux Python-скрипт можно запустить как системную службу с помощью ‘’‘systemd’’’.

Это удобно для Telegram-ботов, веб-сервисов и других приложений, которые должны:

* автоматически запускаться вместе с сервером;
* работать в фоновом режиме;
* автоматически перезапускаться после ошибки;
* управляться стандартными командами systemctl;
* сохранять журнал работы в journalctl.

В этой статье рассмотрим два варианта запуска Python-приложения на примере Telegram-бота ‘’‘noProdaction’’’.

TOC

== Способ №1 — запуск через отдельный shell-скрипт ==

В этом варианте systemd запускает вспомогательный shell-скрипт, который, в свою очередь, запускает Python-приложение.

Схема запуска:

<pre>
systemd
│
▼
noProdaction.sh
│
▼
python3
│
▼
main.py
</pre>

=== Создание скрипта запуска ===

Создаём каталог для скрипта запуска, если его ещё нет:

<syntaxhighlight lang="bash">
mkdir -p /opt/Python/Telegram/start
</syntaxhighlight>

Создаём файл:

<syntaxhighlight lang="bash">
nano /opt/Python/Telegram/start/noProdaction.sh
</syntaxhighlight>

Добавляем:

<syntaxhighlight lang="bash">
#!/bin/bash

exec /usr/bin/python3.11 /opt/Python/Telegram/noProdaction/noprodaction-1/main.py
Сохраняем файл:

<pre>
Ctrl + O
Enter
Ctrl + X
</pre>

Делаем его исполняемым:

<syntaxhighlight lang="bash">
chmod +x /opt/Python/Telegram/start/noProdaction.sh
</syntaxhighlight>

{{Note|Использование exec позволяет заменить процесс shell непосредственно процессом Python. Благодаря этому systemd корректнее отслеживает PID приложения и управляет его завершением.}}

=== Создание systemd unit ===

Создаём unit-файл:

<syntaxhighlight lang="bash">
nano /etc/systemd/system/noprodaction.service
</syntaxhighlight>

Добавляем:

<syntaxhighlight lang="ini">
[Unit]
Description=Telegram bot noProdaction
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/Python/Telegram/noProdaction/noprodaction-1
ExecStart=/opt/Python/Telegram/start/noProdaction.sh

Restart=on-failure
RestartSec=5

NoNewPrivileges=true
PrivateDevices=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target
Сохраняем файл:

<pre>
Ctrl + O
Enter
Ctrl + X
</pre>

=== Активация службы ===

После создания или изменения unit-файла необходимо перечитать конфигурацию systemd:

<syntaxhighlight lang="bash">
systemctl daemon-reload
</syntaxhighlight>

Добавляем службу в автозагрузку:

<syntaxhighlight lang="bash">
systemctl enable noprodaction.service
</syntaxhighlight>

Запускаем:

<syntaxhighlight lang="bash">
systemctl start noprodaction.service
</syntaxhighlight>

Можно выполнить обе команды сразу:

<syntaxhighlight lang="bash">
systemctl enable --now noprodaction.service
</syntaxhighlight>

=== Проверка работы ===

Проверяем состояние:

<syntaxhighlight lang="bash">
systemctl status noprodaction.service
</syntaxhighlight>

При нормальной работе должна присутствовать строка:

<pre>
Active: active (running)
</pre>

Например:

<pre>
● noprodaction.service - Telegram bot noProdaction
Loaded: loaded (/etc/systemd/system/noprodaction.service; enabled)
Active: active (running)
Main PID: 173 (python3.11)
Tasks: 2
Memory: 34.1M
CPU: 1.766s
</pre>

== Способ №2 — запуск Python напрямую из systemd ==

{{Note|’’‘Рекомендуемый вариант.’’’ Если для запуска приложения не требуется выполнять дополнительные команды, создавать отдельный .sh-файл нет необходимости. Python можно запускать непосредственно из systemd.}}

Схема становится проще:

<pre>
systemd
│
▼
python3
│
▼
main.py
</pre>

Создаём unit-файл:

<syntaxhighlight lang="bash">
nano /etc/systemd/system/noprodaction.service
</syntaxhighlight>

Добавляем:

<syntaxhighlight lang="ini">
[Unit]
Description=Telegram bot noProdaction
After=network-online.target
Wants=network-online.target

[Service]
Type=simple

User=root
WorkingDirectory=/opt/Python/Telegram/noProdaction/noprodaction-1

ExecStart=/usr/bin/python3.11 /opt/Python/Telegram/noProdaction/noprodaction-1/main.py

Restart=on-failure
RestartSec=5

NoNewPrivileges=true
PrivateDevices=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target
После создания файла выполняем:

<syntaxhighlight lang="bash">
systemctl daemon-reload
systemctl enable --now noprodaction.service
</syntaxhighlight>

Проверяем:

<syntaxhighlight lang="bash">
systemctl status noprodaction.service
</syntaxhighlight>

== Управление службой ==

После создания unit-файла ботом можно управлять стандартными командами systemd.

{| class=“wikitable”
! Действие

! Команда

Проверить состояние

systemctl status noprodaction

-

Запустить

systemctl start noprodaction

-

Остановить

systemctl stop noprodaction

-

Перезапустить

systemctl restart noprodaction

-

Добавить в автозагрузку

systemctl enable noprodaction

-

Убрать из автозагрузки

systemctl disable noprodaction

}

== Просмотр логов ==

Одно из преимуществ запуска через systemd — вывод Python-приложения автоматически попадает в системный журнал.

Посмотреть последние записи:

<syntaxhighlight lang="bash">
journalctl -u noprodaction.service
</syntaxhighlight>

Последние 100 строк:

<syntaxhighlight lang="bash">
journalctl -u noprodaction.service -n 100
</syntaxhighlight>

Следить за журналом в реальном времени:

<syntaxhighlight lang="bash">
journalctl -u noprodaction.service -f
</syntaxhighlight>

Выйти из режима просмотра:

<pre>
Ctrl + C
</pre>

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

<syntaxhighlight lang="bash">
journalctl -u noprodaction.service -b
</syntaxhighlight>

== После изменения Python-кода ==

Если был изменён только код main.py или других файлов приложения, выполнять daemon-reload не требуется.

Достаточно перезапустить приложение:

<syntaxhighlight lang="bash">
systemctl restart noprodaction
</syntaxhighlight>

Если же был изменён сам файл:

<pre>
/etc/systemd/system/noprodaction.service
</pre>

необходимо выполнить:

<syntaxhighlight lang="bash">
systemctl daemon-reload
systemctl restart noprodaction
</syntaxhighlight>

== Автоматический перезапуск ==

В нашем unit-файле используются параметры:

<syntaxhighlight lang="ini">
Restart=on-failure
RestartSec=5
</syntaxhighlight>

Это означает, что если Python-процесс аварийно завершится, systemd подождёт 5 секунд и попробует запустить его снова.

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

<syntaxhighlight lang="bash">
systemctl show noprodaction.service -p NRestarts
</syntaxhighlight>

== Проверка пути к Python ==

Путь к Python может отличаться в зависимости от системы.

Проверить его можно командой:

<syntaxhighlight lang="bash">
which python3
</syntaxhighlight>

Например:

<pre>
/usr/bin/python3
</pre>

Версию Python:

<syntaxhighlight lang="bash">
python3 --version
</syntaxhighlight>

Если конкретная версия Python не требуется, в unit-файле можно использовать:

<syntaxhighlight lang="ini">
ExecStart=/usr/bin/python3 /opt/Python/Telegram/noProdaction/noprodaction-1/main.py
</syntaxhighlight>

== Запуск через Python Virtual Environment ==

Если проект использует собственное виртуальное окружение Python, рекомендуется запускать Python непосредственно из него.

Например, если виртуальное окружение находится здесь:

<pre>
/opt/Python/Telegram/noProdaction/venv/
</pre>

то ExecStart будет выглядеть так:

<syntaxhighlight lang="ini">
ExecStart=/opt/Python/Telegram/noProdaction/venv/bin/python /opt/Python/Telegram/noProdaction/noprodaction-1/main.py
</syntaxhighlight>

Активировать venv командой source внутри systemd не требуется.

== Рекомендуемый unit-файл ==

Для обычного Python-приложения итоговый вариант может выглядеть следующим образом:

<syntaxhighlight lang="ini">
[Unit]
Description=Telegram bot noProdaction
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=root

WorkingDirectory=/opt/Python/Telegram/noProdaction/noprodaction-1
ExecStart=/usr/bin/python3.11 /opt/Python/Telegram/noProdaction/noprodaction-1/main.py

Restart=on-failure
RestartSec=5

NoNewPrivileges=true
PrivateDevices=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target
После создания:

<syntaxhighlight lang="bash">
systemctl daemon-reload
systemctl enable --now noprodaction.service
</syntaxhighlight>

Проверяем:

<syntaxhighlight lang="bash">
systemctl status noprodaction.service
</syntaxhighlight>

и журнал:

<syntaxhighlight lang="bash">
journalctl -u noprodaction.service -f
</syntaxhighlight>

== Примечание по безопасности ==

В примерах выше служба запускается от пользователя:

<syntaxhighlight lang="ini">
User=root
</syntaxhighlight>

Для собственного сервера это работает, однако большинству Python-приложений права root не нужны.

Более безопасный вариант — создать отдельного системного пользователя для приложения и запускать службу от его имени.

Например:

<syntaxhighlight lang="bash">
useradd --system --home /opt/Python/Telegram/noProdaction --shell /usr/sbin/nologin noprodaction
</syntaxhighlight>

После этого необходимо выдать пользователю права на необходимые файлы приложения и заменить в unit-файле:

<syntaxhighlight lang="ini">
User=root
</syntaxhighlight>

на:

<syntaxhighlight lang="ini">
User=noprodaction
</syntaxhighlight>

{{Warning|Не храните токены Telegram-бота, API-ключи, пароли баз данных и другие секреты непосредственно в публичном unit-файле или исходном коде проекта. Для секретов лучше использовать отдельный файл окружения с ограниченными правами доступа.}}

== Итог ==

Для простого Python-приложения рекомендуется использовать ‘’‘Способ №2’’’:

<pre>
Загрузка Linux
│
▼
systemd
│
▼
noprodaction.service
│
▼
Python
│
▼
main.py
│
▼
Telegram Bot
</pre>

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

Unit for tg bot

2026-08-31T18:34:47Z

Artem: Содержимое страницы заменено на «== '''Создаем Unit для tg bot''' ==»

== '''Создаем Unit для tg bot''' ==

Unit for tg bot

2026-08-31T18:34:29Z

Artem:

== '''Создаем Unit для tg bot''' ==

=== '''Способ №1:''' ===

Создаем исполняемый фаил '''noProdaction.sh''' и в нем вписываем что то типо:

#!/bin/bash<br><br>
/usr/bin/python3.11 /opt/Python/Telegram/noProdaction/noprodaction-1/main.py

Далее создаем с помощью нашего любимого редактора '''nano''' по пути /'''etc/systemd/system/''' фаил '''noprodaction.service'''

nano /etc/systemd/system/noprodaction.service

И вписываем что то типо такого:

[Unit]
Description=telegam bot OmArtVal
After=network.target<br>
[Service]
User=root
Nice=1
KillMode=process
SuccessExitStatus=0 1
ProtectHome=true
ProtectSystem=full
PrivateDevices=true
NoNewPrivileges=true
WorkingDirectory=/opt/Python/Telegram/noProdaction
ExecStart=/opt/Python/Telegram/start/noProdaction.sh
Restart=always<br>
[Install]
WantedBy=multi-user.target

Закрываем редактор с сохранением изменений '''CTRL+O''' и '''CTRL+X'''

Перезагружаем демона:

systemctl daemon-reload

И стартуем его:

systemctl start noprodaction.service

И все! Наш сервис должен работать! Проверить это можно командой

systemctl status noprodaction.service

Вывод должен быть таким:

root@python:~# systemctl status noprodaction.service
* noprodaction.service - telegam bot noProdaction
Loaded: loaded (/etc/systemd/system/noprodaction.service; enabled; vendor preset: enabled)
Active: active (running) since Tue 2023-11-14 11:44:32 MSK; 3h 14min ago
Main PID: 173 (python3.11)
Tasks: 2 (limit: 96529)
Memory: 34.1M
CPU: 1.766s
CGroup: /system.slice/noprodaction.service
`-173 /usr/bin/python3.11 /opt/Python/Telegram/noProdaction/noprodaction-1/main.py<br>
Nov 14 11:44:32 python systemd[1]: Started telegam bot noProdaction.

и у нас при старте сервера вудет работать скрипт.

NGINXproxyManager

2026-08-31T18:21:55Z

Artem: Обновление статьи

= Установка Nginx Proxy Manager в Docker =

‘’‘Nginx Proxy Manager (NPM)’’’ — удобная графическая оболочка для управления реверсивным прокси-сервером Nginx.

С его помощью можно:

* публиковать внутренние веб-сервисы в Интернет;
* направлять разные домены и поддомены на разные серверы;
* автоматически получать SSL-сертификаты Let’s Encrypt;
* управлять HTTPS через веб-интерфейс;
* создавать перенаправления;
* ограничивать доступ к отдельным сервисам.

В результате схема работы выглядит примерно так:

<pre>
INTERNET
│
HTTP / HTTPS
80 / 443
│
▼
┌─────────────────────┐
│ Nginx Proxy Manager │
│ │
│ Docker │
└──────────┬──────────┘
│
┌───────────┼───────────┐
│ │ │
▼ ▼ ▼
Web #1 Web #2 Web #3
192.168.1.x 192.168.1.x 192.168.1.x
</pre>

== Требования ==

Для установки потребуется сервер или виртуальная машина с Linux.

В данной инструкции предполагается использование Debian/Ubuntu.

Также необходимо убедиться, что порты:

* ‘’‘80/TCP’’’ — HTTP;
* ‘’‘443/TCP’’’ — HTTPS;
* ‘’‘81/TCP’’’ — панель управления Nginx Proxy Manager

не заняты другими сервисами.

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

<syntaxhighlight lang="bash">
ss -tulpn
</syntaxhighlight>

== Обновление системы ==

Сначала обновляем список пакетов и установленные пакеты:

<syntaxhighlight lang="bash">
apt update && apt upgrade -y
</syntaxhighlight>

При необходимости устанавливаем дополнительные сетевые утилиты:

<syntaxhighlight lang="bash">
apt install net-tools curl ca-certificates -y
</syntaxhighlight>

== Установка Docker ==

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

Добавляем ключ репозитория:

<syntaxhighlight lang="bash">
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg \
-o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc
</syntaxhighlight>

Добавляем репозиторий Docker:

<syntaxhighlight lang="bash">
cat > /etc/apt/sources.list.d/docker.sources <<EOF
Types: deb
URIs: https://download.docker.com/linux/debian
Suites: $(. /etc/os-release && echo "$VERSION_CODENAME")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
</syntaxhighlight>

Обновляем список пакетов:

<syntaxhighlight lang="bash">
apt update
</syntaxhighlight>

Устанавливаем Docker Engine и Docker Compose:

<syntaxhighlight lang="bash">
apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
</syntaxhighlight>

Проверяем версию Docker:

<syntaxhighlight lang="bash">
docker --version
</syntaxhighlight>

И Docker Compose:

<syntaxhighlight lang="bash">
docker compose version
</syntaxhighlight>

== Проверка Docker ==

Проверяем состояние службы:

<syntaxhighlight lang="bash">
systemctl status docker
</syntaxhighlight>

Если Docker не запущен:

<syntaxhighlight lang="bash">
systemctl start docker
</syntaxhighlight>

Добавляем Docker в автозагрузку:

<syntaxhighlight lang="bash">
systemctl enable docker
</syntaxhighlight>

Для дополнительной проверки можно запустить тестовый контейнер:

<syntaxhighlight lang="bash">
docker run --rm hello-world
</syntaxhighlight>

Если установка выполнена правильно, Docker загрузит тестовый образ и выведет сообщение об успешном запуске.

== Установка Nginx Proxy Manager ==

Создадим отдельный каталог для Nginx Proxy Manager:

<syntaxhighlight lang="bash">
mkdir -p /opt/nginx-proxy-manager
cd /opt/nginx-proxy-manager
</syntaxhighlight>

Создаём файл Docker Compose:

<syntaxhighlight lang="bash">
nano docker-compose.yml
</syntaxhighlight>

Добавляем следующую конфигурацию:

<syntaxhighlight lang="yaml">
services:
app:
image: 'jc21/nginx-proxy-manager:2.15.1'
restart: unless-stopped
ports:
- '80:80'
- '81:81'
- '443:443'
volumes:
- ./data:/data
- ./letsencrypt:/etc/letsencrypt
</syntaxhighlight>

Сохраняем файл:

<pre>
Ctrl + O
Enter
Ctrl + X
</pre>

В данной конфигурации используется встроенная база данных SQLite, поэтому отдельный контейнер MariaDB для обычной установки не требуется.

== Запуск Nginx Proxy Manager ==

Запускаем контейнеры:

<syntaxhighlight lang="bash">
docker compose up -d
</syntaxhighlight>

Проверяем их состояние:

<syntaxhighlight lang="bash">
docker compose ps
</syntaxhighlight>

Также можно посмотреть непосредственно запущенные Docker-контейнеры:

<syntaxhighlight lang="bash">
docker ps
</syntaxhighlight>

Nginx Proxy Manager должен отображаться со статусом:

<pre>
Up
</pre>

Первый запуск может занять некоторое время.

При необходимости посмотреть журнал запуска:

<syntaxhighlight lang="bash">
docker compose logs -f
</syntaxhighlight>

Выход из просмотра журнала:

<pre>
Ctrl + C
</pre>

== Вход в панель управления ==

Открываем браузер и переходим по адресу:

<pre>
http://IP_СЕРВЕРА:81
</pre>

Например:

<pre>
http://192.168.1.20:81
</pre>

После первого входа необходимо настроить учётную запись администратора согласно интерфейсу текущей версии Nginx Proxy Manager.

‘’‘Обязательно используйте собственный надёжный пароль администратора.’’’

== Назначение портов ==

{| class=“wikitable”
! Порт
! Протокол

! Назначение

80

TCP

Входящие HTTP-запросы

-

443

TCP

Входящие HTTPS-запросы

-

81

TCP

Web-интерфейс администратора

}

{{Warning|Порт 81 предназначен для административной панели. Не рекомендуется без необходимости публиковать его напрямую в Интернет. Ограничьте доступ локальной сетью, VPN или правилами межсетевого экрана.}}

== Создание первого Proxy Host ==

После входа в Nginx Proxy Manager открываем:

<pre>
Hosts → Proxy Hosts → Add Proxy Host
</pre>

Указываем:

{| class=“wikitable”
! Параметр

! Пример

Domain Names

wiki.example.com

-

Scheme

http

-

Forward Hostname / IP

192.168.1.30

-

Forward Port

80

}

После этого Nginx Proxy Manager будет принимать запрос:

<pre>
https://wiki.example.com
</pre>

и передавать его внутреннему серверу:

<pre>
http://192.168.1.30:80
</pre>

Схематично:

<pre>
Пользователь
│
│ https://wiki.example.com
▼
┌─────────────────────┐
│ Nginx Proxy Manager │
│ :443 │
└──────────┬──────────┘
│
│ HTTP
▼
192.168.1.30:80
│
▼
Web-сервис
</pre>

== Получение SSL-сертификата ==

При создании Proxy Host переходим во вкладку:

<pre>
SSL
</pre>

Выбираем:

<pre>
Request a new SSL Certificate
</pre>

При необходимости включаем:

* ‘’‘Force SSL’’’ — принудительное перенаправление HTTP → HTTPS;
* ‘’‘HTTP/2 Support’’’ — поддержку HTTP/2;
* ‘’‘HSTS’’’ — только если понимаем последствия его использования.

После сохранения Nginx Proxy Manager автоматически запросит сертификат Let’s Encrypt.

Для стандартной HTTP-проверки Let’s Encrypt домен должен указывать на внешний IP сервера, а TCP-порт ‘’‘80’’’ должен быть доступен извне.

== Управление контейнером ==

=== Остановить Nginx Proxy Manager ===

<syntaxhighlight lang="bash">
cd /opt/nginx-proxy-manager
docker compose down
</syntaxhighlight>

=== Запустить ===

<syntaxhighlight lang="bash">
docker compose up -d
</syntaxhighlight>

=== Перезапустить ===

<syntaxhighlight lang="bash">
docker compose restart
</syntaxhighlight>

=== Посмотреть журнал ===

<syntaxhighlight lang="bash">
docker compose logs -f
</syntaxhighlight>

=== Проверить состояние ===

<syntaxhighlight lang="bash">
docker compose ps
</syntaxhighlight>

== Обновление Nginx Proxy Manager ==

Перед обновлением рекомендуется сделать резервную копию каталога:

<pre>
/opt/nginx-proxy-manager
</pre>

Затем переходим в каталог:

<syntaxhighlight lang="bash">
cd /opt/nginx-proxy-manager
</syntaxhighlight>

Загружаем актуальный Docker-образ:

<syntaxhighlight lang="bash">
docker compose pull
</syntaxhighlight>

Пересоздаём контейнер:

<syntaxhighlight lang="bash">
docker compose up -d
</syntaxhighlight>

После обновления проверяем:

<syntaxhighlight lang="bash">
docker compose ps
</syntaxhighlight>

и журнал:

<syntaxhighlight lang="bash">
docker compose logs --tail=100
</syntaxhighlight>

== Резервное копирование ==

Основные данные установки находятся в каталогах:

<pre>
/opt/nginx-proxy-manager/data
/opt/nginx-proxy-manager/letsencrypt
</pre>

Для резервного копирования желательно сохранить весь каталог:

<pre>
/opt/nginx-proxy-manager/
</pre>

В нём находятся конфигурация Nginx Proxy Manager, база данных, SSL-сертификаты и файл Docker Compose.

== Итог ==

После установки получаем централизованный reverse proxy:

<pre>
INTERNET
│
┌──────┴──────┐
│ │
:80 :443
│ │
└──────┬──────┘
▼
┌─────────────────────┐
│ Nginx Proxy Manager │
│ Docker │
└──────────┬──────────┘
│ LAN
┌───────────────┼───────────────┐
▼ ▼ ▼
Wiki Cloud Matrix
192.168.1.x 192.168.1.x 192.168.1.x
</pre>

Теперь новые внутренние веб-сервисы можно публиковать через HTTPS практически полностью из графического интерфейса Nginx Proxy Manager.

Заглавная страница

2026-08-28T10:53:12Z

Artem:

<div style="padding:20px;">

<div style="text-align:center; margin-bottom:30px;">
<h1>📚 База знаний</h1>
<p>Документация по инфраструктуре, Linux и игровым серверам.</p>
</div>

{| style="width:100%; border-spacing:12px;"
|-
| style="width:33%; vertical-align:top; background:#f8f9fa; border:1px solid #c8ccd1; border-radius:8px; padding:15px;" |

=== 🖥️ Инфраструктура ===
''Серверы и виртуализация''

* [[Proxmox]]
* [[PBS]]
* [[iLO]]
* [[BrainyCP]]
* [[Сетевое оборудование]]
* [[RAMBA Matrix]]
* [[RAMBA AI Router]]
* [[Happ-gateway|HAPP Gateway]]
* [[Kuzya2-0|Телеграм бот Кузя 2.0]]

| style="width:33%; vertical-align:top; background:#f8f9fa; border:1px solid #c8ccd1; border-radius:8px; padding:15px;" |

=== 🐧 Linux ===
''Системное администрирование''

* [[Ubuntu]]
* [[Debian]]
* [[Nginx]]
* [[Docker]]
* [[Bash]]

| style="width:33%; vertical-align:top; background:#f8f9fa; border:1px solid #c8ccd1; border-radius:8px; padding:15px;" |

=== 🎮 Игровые серверы ===
''Игровая инфраструктура''

* [[Rust]]
* [[LGSM]]
* [[SteamCMD]]
* [[Резервное копирование]]
* [[Мониторинг]]

|}

<div style="margin-top:20px; background:#f8f9fa; border:1px solid #c8ccd1; border-radius:8px; padding:15px;">

== ⭐ Избранные статьи ==

* [[Установка Proxmox VE]]
* [[Настройка Proxmox Backup Server]]
* [[Настройка BrainyCP]]
* [[Создание LXC-контейнеров]]
* [[Настройка Rust-сервера через LGSM]]
* [[Minecraft_в_2026_году]]

</div>

<div style="margin-top:20px; background:#f8f9fa; border:1px solid #c8ccd1; border-radius:8px; padding:15px;">

== 🕒 Последние изменения ==

* [[Special:RecentChanges|Посмотреть все последние изменения]]

</div>

<div style="margin-top:20px; background:#f8f9fa; border:1px solid #c8ccd1; border-radius:8px; padding:15px;">

== 🔗 Полезные ссылки ==

* [[Special:AllPages|Все статьи]]
* [[Special:Categories|Все категории]]
* [[Special:WantedPages|Нужные страницы]]
* [[Special:Random|🎲 Случайная статья]]

</div>

</div>

Kuzya2-0

2026-08-28T10:38:47Z

Artem: Новая страница: «= Кузя — интеллектуальный администратор Telegram-сообщества = '''Кузя''' — Telegram-бот для администрирования и сопровождения сообщества. Проект развивается от классического административного бота к интеллектуальному помощнику и AI-модератору, способному ана...»

Gitignore

2023-04-15T18:32:07Z

Artem:

Gitignore

2023-04-15T18:30:20Z

Artem: Содержимое страницы заменено на «== Python.gitignore == '''[https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore .gitignore file тут]'''»

== Python.gitignore ==

'''[https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore .gitignore file тут]'''

Gitignore

2023-04-15T18:16:25Z

Artem: Новая страница: «# Byte-compiled / optimized / DLL files __pycache__/ *.py[cod] *$py.class # C extensions *.so # Distribution / packaging .Python build/ develop-eggs/ dist/ downloads/ eggs/ .eggs/ lib/ lib64/ parts/ sdist/ var/ wheels/ share/python-wheels/ *.egg-info/ .installed.cfg *.egg MANIFEST # PyInstaller # Usually these files are written by a python script from a template # before PyInstaller builds the exe, so as to inject date/other infos into it. *.manifest *....»

# Byte-compiled / optimized / DLL files
__pycache__/
*.py[cod]
*$py.class

# C extensions
*.so

# Distribution / packaging
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# PyInstaller
# Usually these files are written by a python script from a template
# before PyInstaller builds the exe, so as to inject date/other infos into it.
*.manifest
*.spec

# Installer logs
pip-log.txt
pip-delete-this-directory.txt

# Unit test / coverage reports
htmlcov/
.tox/
.nox/
.coverage
.coverage.*
.cache
nosetests.xml
coverage.xml
*.cover
*.py,cover
.hypothesis/
.pytest_cache/
cover/

# Translations
*.mo
*.pot

# Django stuff:
*.log
local_settings.py
db.sqlite3
db.sqlite3-journal

# Flask stuff:
instance/
.webassets-cache

# Scrapy stuff:
.scrapy

# Sphinx documentation
docs/_build/

# PyBuilder
.pybuilder/
target/

# Jupyter Notebook
.ipynb_checkpoints

# IPython
profile_default/
ipython_config.py

# pyenv
# For a library or package, you might want to ignore these files since the code is
# intended to run in multiple environments; otherwise, check them in:
# .python-version

# pipenv
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
# However, in case of collaboration, if having platform-specific dependencies or dependencies
# having no cross-platform support, pipenv may install dependencies that don't work, or not
# install all needed dependencies.
#Pipfile.lock

# poetry
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
# This is especially recommended for binary packages to ensure reproducibility, and is more
# commonly ignored for libraries.
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
#poetry.lock

# pdm
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
#pdm.lock
# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
# in version control.
# https://pdm.fming.dev/#use-with-ide
.pdm.toml

# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
__pypackages__/

# Celery stuff
celerybeat-schedule
celerybeat.pid

# SageMath parsed files
*.sage.py

# Environments
.env
.venv
env/
venv/
ENV/
env.bak/
venv.bak/

# Spyder project settings
.spyderproject
.spyproject

# Rope project settings
.ropeproject

# mkdocs documentation
/site

# mypy
.mypy_cache/
.dmypy.json
dmypy.json

# Pyre type checker
.pyre/

# pytype static type analyzer
.pytype/

# Cython debug symbols
cython_debug/

# PyCharm
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
# and can be added to the global gitignore or merged into this file. For a more nuclear
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
#.idea/

VENV

2023-04-15T18:03:00Z

Artem:

Для создания нового виртуального окружения в проекте:

python3 -m venv имя_вирт_окружения

Запуск VENV

Windows - .\env\Scripts\activate

Linux/MacOS - source venv/bin/activate

Заглавная страница

2023-04-15T08:00:10Z

Artem:

[https://wiki.ramba-art.ru/NGINXproxyManager '''Поднимаем NGINXproxyManager''']

[https://wiki.ramba-art.ru/VENV '''Кратко о VENV''']

[https://wiki.ramba-art.ru/%D0%9A%D0%B0%D0%BA_%D1%81%D0%BE%D0%B7%D0%B4%D0%B0%D1%82%D1%8C_requirements_txt '''Как создать requirements txt''']

[https://wiki.ramba-art.ru/%D0%9D%D0%B0%D1%81%D1%82%D1%80%D0%BE%D0%B9%D0%BA%D0%B0_%D0%BB%D0%BE%D0%BA%D0%B0%D0%BB%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D0%B8_Ubuntu_%D0%B8%D0%BB%D0%B8_UBUNTU_%D0%BD%D0%B0_%D1%80%D1%83%D1%81%D1%81%D0%BA%D0%BE%D0%BC '''UBUNTU на русский''']

[https://wiki.ramba-art.ru/%D0%9A%D0%B0%D0%BA_%D1%81%D0%B4%D0%B5%D0%BB%D0%B0%D1%82%D1%8C_%D1%81%D0%B5%D1%80%D0%B2%D0%B5%D1%80_Minecraft_%D0%BD%D0%B0_Ubuntu_20_04 '''Как сделать сервер Minecraft на Ubuntu 20 04''']

[https://wiki.ramba-art.ru/%D0%A0%D0%B0%D0%B7%D1%80%D0%B5%D1%88%D0%B8%D1%82%D1%8C_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8E_root_%D0%BF%D0%BE%D0%B4%D0%BA%D0%BB%D1%8E%D1%87%D0%B0%D1%82%D1%8C%D1%81%D1%8F_%D0%BF%D0%BE_ssh '''Разрешить пользователю root подключаться по ssh''']

[https://wiki.ramba-art.ru/%D0%9E%D1%82%D0%BA%D0%BB%D1%8E%D1%87%D0%B8%D1%82_%D0%BF%D0%B5%D1%80%D0%B5%D1%85%D0%BE%D0%B4_%D0%B2_%D1%81%D0%BE%D0%BD_%D0%B8%D0%BB%D0%B8_%D0%B3%D0%B8%D0%B1%D0%B5%D1%80%D0%BD%D0%B0%D1%86%D0%B8%D1%8E_%D0%BF%D1%80%D0%B8_%D0%B7%D0%B0%D0%BA%D1%80%D1%8B%D1%82%D0%B8%D0%B8_%D0%BA%D1%80%D1%8B%D1%88%D0%BA%D0%B8_%D0%BD%D0%BE%D1%83%D1%82%D0%B0_%D0%BF%D0%BE%D0%B4_%D1%83%D0%BF%D1%80%D0%B0%D0%B2%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5%D0%BC_linux '''Отключить ждущий режим и гибернацию в Ubuntu''']

[https://wiki.ramba-art.ru/%D0%94%D0%BE%D0%B1%D0%B0%D0%B2%D0%B8%D1%82%D1%8C_proxy_%D0%B2_ubuntu'''Добавить proxy в ubuntu''']

'''[https://wiki.ramba-art.ru/Unit%20for%20tg%20bot Unit for tg bot]'''

Unit for tg bot

2023-04-12T17:05:37Z

Artem: Новая страница: « [Unit] Description=telegam bot OmArtVal After=network.target [Service] User=root Nice=1 KillMode=process SuccessExitStatus=0 1 ProtectHome=true ProtectSystem=full PrivateDevices=true NoNewPrivileges=true WorkingDirectory=/opt/Python/Telegram/noProdaction ExecStart=/opt/Python/Telegram/start/noProdaction.sh Restart=always [Install] WantedBy=multi-user.target»

[Unit]
Description=telegam bot OmArtVal
After=network.target

[Service]
User=root
Nice=1
KillMode=process
SuccessExitStatus=0 1
ProtectHome=true
ProtectSystem=full
PrivateDevices=true
NoNewPrivileges=true
WorkingDirectory=/opt/Python/Telegram/noProdaction
ExecStart=/opt/Python/Telegram/start/noProdaction.sh
Restart=always

[Install]
WantedBy=multi-user.target

Заглавная страница

2023-03-27T16:35:19Z

Artem:

Разрешить пользователю root подключаться по ssh

2023-03-27T16:34:18Z

Artem: Новая страница: «разрешить подключение по '''рут ''' Используя команду: '''sudo sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config''' Или лезем в фаил '''sshd_config''' находящийся в каталоге '''etc''' потом '''ssh''' '''nano /etc/ssh/sshd_config''' убираем комент ('''#''') в строчке '''PermitRootLogin''' и ставим знач...»

разрешить подключение по '''рут
'''
Используя команду:

'''sudo sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config'''

Или лезем в фаил '''sshd_config''' находящийся в каталоге '''etc''' потом '''ssh'''

'''nano /etc/ssh/sshd_config'''

убираем комент ('''#''') в строчке '''PermitRootLogin''' и ставим значение '''''yes''''', а также ищем строчку '''PermitRootLogin''' и устанавливаем значение '''''prohibit-password'''''

'''ВАЖНО!!!!! ЛОГИНИТСЯ ПОД РУТ - НЕБЕЗОПАСНО!!!!! ОПАСТНО!!!!!'''

Заглавная страница

2023-03-25T20:50:39Z

Artem:

Заглавная страница

2023-03-25T20:50:23Z

Artem:

Как сделать сервер Minecraft на Ubuntu 20 04

2023-03-25T20:49:34Z

Artem: Новая страница: «'''Подготовка''' Согласно официальному сайту Minecraft, в качестве минимальной конфигурации для типичной установки рекомендуется 4 ГБ ОЗУ. '''Установите пакеты, необходимые для сборки инструмента mcrcon :''' apt update && apt upgrate -y apt install git build-essential '''Установка сред...»

'''Подготовка'''
Согласно официальному сайту Minecraft, в качестве минимальной конфигурации для типичной установки рекомендуется 4 ГБ ОЗУ.

'''Установите пакеты, необходимые для сборки инструмента mcrcon :'''

apt update && apt upgrate -y
apt install git build-essential

'''Установка среды выполнения Java'''

apt install openjdk-17-jre-headless

'''Проверяем версию'''

java -version

'''Ответ должны получить'''

openjdk version "17.0.5" 2022-10-18
OpenJDK Runtime Environment (build 17.0.5+8-Ubuntu-2ubuntu120.04)
OpenJDK 64-Bit Server VM (build 17.0.5+8-Ubuntu-2ubuntu120.04, mixed mode, sharing)

'''Создание пользователя Minecraft'''

По соображениям безопасности Minecraft не следует запускать от имени пользователя root. Мы создадим нового системного пользователя и группу с домашним каталогом /opt/minecraft . У пользователя будут минимально необходимые разрешения для запуска сервера Minecraft:

useradd -r -m -U -d /opt/minecraft -s /bin/bash minecraft

Мы не будем устанавливать пароль для этого пользователя. Таким образом, пользователь не сможет войти через SSH и его нельзя будет скомпрометировать. Чтобы перейти на пользователя minecraft , вам необходимо войти на сервер как пользователь root или пользователь с привилегиями sudo .

'''Установка Minecraft на Ubuntu'''

Переходим на вновь созданного пользователя

su - minecraft

Выполните следующую команду, чтобы создать три новых каталога внутри домашнего каталога пользователя:

mkdir -p ~/{backups,tools,server}

* В каталоге backups будут храниться резервные копии вашего сервера Minecraft. Вы можете синхронизировать этот каталог с вашим удаленным сервером резервного копирования.
* Каталог tools будет содержать клиент mcrcon и скрипт резервного копирования.
* Каталог server будет содержать фактический сервер Minecraft и его данные.

'''Скачивание и компиляция mcrcon'''

RCON — это протокол, который позволяет подключаться к серверам Minecraft и выполнять команды. mcron — это клиент RCON, написанный на C.

Мы mcrcon исходный код с GitHub и mcrcon двоичный файл mcrcon .

Tiiffi/mcrcon репозиторий Tiiffi/mcrcon с GitHub в каталог ~/tools/mcron :

git clone https://github.com/Tiiffi/mcrcon.git ~/tools/mcrcon

По завершении mcron каталог mcron и mcron утилиту:

cd ~/tools/mcrcon
gcc -std=gnu11 -pedantic -Wall -Wextra -O2 -s -o mcrcon mcrcon.c

После завершения убедитесь, что mcrcon успешно скомпилирован, распечатав его версию:

./mcrcon -v

Результат будет выглядеть примерно так:

mcrcon 0.7.2 (built: Oct 2 2022 16:10:42) - https://github.com/Tiiffi/mcrcon
Bug reports:
tiiffi+mcrcon at gmail
https://github.com/Tiiffi/mcrcon/issues/

'''Скачивание сервера Minecraft'''

Существует несколько модов сервера Minecraft, таких как Craftbukkit или Spigot, которые позволяют добавлять функции (плагины) на ваш сервер и дополнительно настраивать и настраивать параметры сервера.

В этом руководстве мы установим последний официальный ванильный сервер Minecraft от Mojang. Те же инструкции применимы и для установки других серверных модов.

Перейдите на страницу [https://www.minecraft.net/en-us/download/server загрузки Minecraft], чтобы получить ссылку для загрузки последней версии файла архива Java (JAR) сервера Minecraft. На момент написания последняя версия — 1.19.4 .

Загрузите файл jar в каталог ~/server с помощью wget :

wget https://piston-data.mojang.com/v1/objects/8f3112a1049751cc472ec13e397eade5336ca7ae/server.jar -P ~/server

'''Настройка Сервера Майнкрафт'''

После завершения загрузки переключитесь в каталог ~/server и запустите сервер Minecraft:

cd ~/server
java -Xmx1024M -Xms1024M -jar server.jar nogui

При первом запуске сервер выполняет некоторые операции, создает файлы server.properties и eula.txt и останавливается.

[17:35:14] [main/ERROR]: Failed to load properties from file: server.properties
[17:35:15] [main/WARN]: Failed to load eula.txt
[17:35:15] [main/INFO]: You need to agree to the EULA in order to run the server. Go to eula.txt for more info.

Чтобы запустить сервер, вам необходимо согласиться с лицензионным соглашением Minecraft EULA, как указано в выходных данных выше. Откройте файл eula.txt и замените eula=false на eula=true :

nano ~/server/eula.txt

'''''~/server/eula.txt'''''
eula=true

акройте и сохраните файл. Напомню ctrl + O => save & ctrl + X => exit.

Затем откройте файл server.properties включите протокол rcon и установите пароль rcon:

nano ~/server/server.properties

Найдите следующие строки и обновите их значения, как показано ниже:

'''''~/server/server.properties'''''
rcon.port=25575
rcon.password=strong-password
enable-rcon=true

Не забудьте сменить надежный strong-password на более безопасный. Если вы не хотите подключаться к серверу Minecraft из удаленных мест, убедитесь, что порт rcon заблокирован вашим брандмауэром.
Здесь вы также можете настроить свойства сервера по умолчанию. Для получения дополнительной информации о настройках сервера посетите страницу [https://minecraft.fandom.com/wiki/Server.properties server.properties] .

'''Создание файла модуля Systemd'''

Вместо того, чтобы вручную запускать сервер Minecraft, мы создадим файл модуля Systemd и запустим Minecraft как службу.

Вернитесь к своему пользователю sudo, набрав exit .

Откройте текстовый редактор и создайте файл с именем minecraft.service в каталоге /etc/systemd/system/ :

sudo nano /etc/systemd/system/minecraft.service

Вставьте следующую конфигурацию:

'''''/etc/systemd/system/minecraft.service'''''
[Unit]
Description=Minecraft Server
After=network.target

[Service]
User=minecraft
Nice=1
KillMode=none
SuccessExitStatus=0 1
ProtectHome=true
ProtectSystem=full
PrivateDevices=true
NoNewPrivileges=true
WorkingDirectory=/opt/minecraft/server
ExecStart=/usr/bin/java -Xmx1024M -Xms1024M -jar server.jar nogui
ExecStop=/opt/minecraft/tools/mcrcon/mcrcon -H 127.0.0.1 -P 25575 -p strong-password stop

[Install]
WantedBy=multi-user.target

Измените флаги Xmx и Xms соответствии с ресурсами вашего сервера. Флаг Xmx определяет максимальный пул распределения памяти для виртуальной машины Java (JVM), а Xms определяет начальный пул распределения памяти. Также убедитесь, что вы используете правильный порт rcon и пароль.

Сохраните файл и перезагрузите конфигурацию systemd manager:

sudo systemctl daemon-reload

Теперь вы можете запустить сервер Minecraft, набрав:

sudo systemctl start minecraft

При первом запуске службы она сгенерирует несколько файлов конфигурации и каталогов, включая мир Minecraft.

Проверьте статус службы с помощью следующей команды:

sudo systemctl status minecraft

* minecraft.service - Minecraft Server
Loaded: loaded (/etc/systemd/system/minecraft.service; disabled; vendor preset: enabled)
Active: active (running) since Tue 2020-06-23 17:48:44 UTC; 8s ago
Main PID: 1338035 (java)
Tasks: 15 (limit: 1074)
Memory: 465.3M
CGroup: /system.slice/minecraft.service
└─1338035 /usr/bin/java -Xmx1024M -Xms1024M -jar server.jar nogui

Наконец, включите автоматический запуск службы Minecraft во время загрузки:

sudo systemctl enable minecraft

'''Настройка брандмауэра'''

Ubuntu поставляется с инструментом настройки брандмауэра под названием UFW. Если в вашей системе включен брандмауэр , и вы хотите получить доступ к серверу Minecraft извне вашей локальной сети, вам необходимо открыть порт 25565 :

sudo ufw allow 25565/tcp

'''Настройка резервного копирования'''

В этом разделе мы создадим сценарий оболочки резервного копирования и задание cron для автоматического резервного копирования сервера Minecraft.

Переключитесь на minecraft :

sudo su - minecraft

Откройте текстовый редактор и создайте следующий файл:

nano /opt/minecraft/tools/backup.sh

Вставьте следующую конфигурацию:

'''''/opt/minecraft/tools/backup.sh'''''
#!/bin/bash

function rcon {
/opt/minecraft/tools/mcrcon/mcrcon -H 127.0.0.1 -P 25575 -p strong-password "$1"
}

rcon "save-off"
rcon "save-all"
tar -cvpzf /opt/minecraft/backups/server-$(date +%F-%H-%M).tar.gz /opt/minecraft/server
rcon "save-on"

## Delete older backups
find /opt/minecraft/backups/ -type f -mtime +7 -name '*.gz' -delete

Сохраните файл и сделайте скрипт исполняемым :

chmod +x /opt/minecraft/tools/backup.sh

Затем создайте задание cron, которое будет запускаться автоматически один раз в день в определенное время.

Откройте файл crontab, набрав:

crontab -e

Чтобы запускать сценарий резервного копирования каждый день в 23:00, вставьте следующую строку:

0 23 * * * /opt/minecraft/tools/backup.sh

'''Доступ к консоли Minecraft'''

Для доступа к консоли Minecraft используйте утилиту mcrcon . Вам необходимо указать хост, порт rcon, пароль rcon и использовать переключатель -t который включает mcrcon терминала mcrcon :

/opt/minecraft/tools/mcrcon/mcrcon -H 127.0.0.1 -P 25575 -p strong-password -t

Logged in. Type "Q" to quit!
>

При доступе к консоли Minecraft из удаленного места убедитесь, что порт rcon не заблокирован.

Если вы регулярно подключаетесь к консоли Minecraft, вместо того, чтобы вводить эту длинную команду, вы создаете псевдоним bash .

'''Выводы'''

Мы показали вам, как создать сервер Minecraft на Ubuntu 20.04 и настроить ежедневное резервное копирование.

Теперь вы можете запустить свой клиент Minecraft , подключиться к серверу и начать свое приключение в Minecraft.

Файл:Безымянныcй.png

2023-03-25T20:10:35Z

Artem:

скрин терминала