После запуска из урока «Open WebUI через Python» интерфейс уже открывается на локальной машине, но сам процесс open-webui serve продолжает занимать окно терминала. Передадим управление этим экземпляром пользовательскому менеджеру systemd в Ubuntu 24.04 x86_64. Переустанавливать пакеты, создавать нового системного пользователя или переносить базу данных не нужно: служба запустит уже готовое приложение из прежнего виртуального окружения с теми же путями и локальным адресом.
Все команды выполняем в Bash на той же машине с Ubuntu 24.04, от имени обычного пользователя, который устанавливал приложение и впервые входил в него. Браузер открываем на этом же компьютере. Сначала сверим параметры прежнего запуска и остановим ручной процесс. Затем сохраним конфигурацию службы и проверим состояние процесса, готовность веб-приложения и вход в существующую учётную запись.
Подготовим прежний экземпляр к передаче службе
Переход на службу меняет только способ управления процессом. Сама программа, установленные в .venv пакеты и каталог данных остаются на прежних местах. Для запуска прежней установки через systemd сохраним четыре параметра ручного старта.
| Параметр прежнего запуска | Значение в нашей установке | Зачем сохранять точное значение |
|---|---|---|
| Исполняемый файл | ~/open-webui-python/.venv/bin/open-webui | Прямой запуск установленного Open WebUI 0.12.3 без повторной установки пакетов |
| Рабочая папка | ~/open-webui-python | Поиск файла .webui_secret_key в текущем каталоге при стандартном запуске без отдельной переменной WEBUI_SECRET_KEY |
Каталог данных DATA_DIR | ~/.local/share/open-webui-python | Подключение прежней базы данных и пользовательских файлов |
| Адрес и порт | 127.0.0.1:8080 | Доступ к интерфейсу только с этого же компьютера |
Сохраним и рабочую папку, и каталог данных. В Open WebUI 0.12.3 путь к файлу секретного ключа по умолчанию вычисляется относительно текущего рабочего каталога (Path.cwd() / ".webui_secret_key"), а не внутри DATA_DIR. Сам ключ мы не читаем и не копируем внутрь файла службы: достаточно запускать процесс в прежней папке ~/open-webui-python, где этот файл уже лежит.
Ubuntu 24.04 использует семейство systemd 255. Посмотреть установленную в вашей системе версию можно командой:
Команда показывает версию пакета и сборку systemd, но не проверяет доступность пользовательского менеджера служб. Для нашего сценария нужен обычный локальный сеанс Ubuntu, в котором пользовательский экземпляр systemd уже запущен при входе в систему.
Перед включением службы штатно остановим Open WebUI, если он ещё работает в терминале с прошлого урока. Перейдите в то окно терминала, нажмите Ctrl+C и дождитесь возврата обычного приглашения Bash. Запускать службу поверх работающего ручного процесса нельзя: оба экземпляра попытаются занять один и тот же адрес 127.0.0.1:8080 и будут обращаться к одной базе данных. Если порт занят какой-то другой программой, не завершайте неизвестные процессы наугад, а сначала проверьте, где именно осталась запущена прежняя сессия.
Пользовательская служба не привязана к конкретному окну терминала, но по умолчанию её жизнь связана с работой вашего пользовательского менеджера systemd. В конце урока мы отдельно разберём, как работают старт при входе в систему, выход из всех сеансов и необязательный режим работы без входа.
Сохраним конфигурацию пользовательской службы
В документации Open WebUI по развёртыванию приводится пример системного unit-файла для многопользовательского сервера с отдельным сервисным аккаунтом. Мы продолжаем локальную установку обычного пользователя, поэтому права root и перенос прав на файлы не нужны. Сохраним личный unit-файл в домашнем каталоге и будем обращаться к менеджеру текущего пользователя с флагом --user.
Создадим каталог для пользовательских служб systemd, если его ещё нет:
Создадим текстовый файл ~/.config/systemd/user/open-webui.service в удобном редакторе. Если файл с таким именем уже существует, сначала проверьте его содержимое, чтобы не перезаписать другую нужную настройку.
Запишите в файл следующее содержимое и сохраните его:
В этой конфигурации каждая директива задаёт свою часть запуска. Синтаксис unit-файла отличается от Bash:
WorkingDirectory=%h/open-webui-pythonиEnvironment="DATA_DIR=%h/.local/share/open-webui-python"передают процессу прежнюю рабочую папку с файлом.webui_secret_keyи внешний каталог данных.- Спецификатор
%hв правилах разбора unit-файлов systemd обозначает домашний каталог пользователя, от имени которого работает менеджер служб. Внутри директивыEnvironment=нельзя написать$HOMEкак в Bash: там знак доллара воспринимается буквально, и подстановка пути из оболочки не сработает. ExecStart=...указывает полный путь к исполняемому файлуopen-webuiвнутри уже созданного виртуального окружения.venvи явно закрепляет локальный адрес127.0.0.1и порт8080(без этих флагов командаserveпо умолчанию слушает0.0.0.0:8080). Поскольку мы вызываем бинарник из.venv/binнапрямую, в файле службы не нужны ниsource .venv/bin/activate, ни вызовыuvx, ни повторная установка пакетов.Type=execзадаёт правило: служба считается запущенной на уровне процесса в тот момент, когда системный вызовexecve()успешно передал управление исполняемому файлу. При этом успешный запуск процесса ещё не означает, что веб-сервер завершил внутреннюю инициализацию и готов отвечать браузеру.Restart=on-failureиRestartSec=5sпросятsystemdперезапустить процесс через 5 секунд, если он завершился с ненулевым кодом ошибки, аварийным сигналом или по таймауту. Это помогает пережить случайный сбой процесса, но не исправляет ошибки в путях или правах доступа.WantedBy=default.targetпривязывает автозапуск службы к стандартной цели пользовательского менеджера. ДирективуUser=мы сюда не добавляем: пользовательский менеджер уже работает от вашего имени и переключать системных пользователей не может. Все команды управления такой службой выполняются безsudo.
Запустим службу и проверим готовность приложения
После сохранения файла попросим пользовательский менеджер перечитать конфигурации на диске, затем включим и сразу запустим службу:
Команда daemon-reload загружает новый файл open-webui.service в память менеджера. Команда enable создаёт символическую ссылку для автоматического старта при запуске пользовательского менеджера, а флаг --now сразу же запускает процесс в текущем сеансе. Сам по себе шаг enable ещё не означает, что служба будет стартовать при загрузке компьютера до входа пользователя в систему.
Проверим запуск на трёх уровнях: состояние процесса, готовность HTTP-приложения и вход в интерфейс через браузер.
Посмотрим текущее состояние службы и последние записи её журнала:
В выводе status нас интересует строка состояния active (running). Если служба остановлена или завершилась с ошибкой, systemctl status штатно возвращает ненулевой код завершения. Это говорит о состоянии службы, а не о поломке утилиты systemctl. При этом статус active (running) для Type=exec подтверждает только то, что процесс Python стартовал; приложению нужно ещё некоторое время, чтобы подключить базу данных и поднять веб-сервер.
В документации systemd 255 для journalctl --user указано условие: хранение и доступность пользовательских журналов зависят от того, включено ли в системе постоянное хранение логов (persistent logging). Если journalctl --user ничего не вывел, это само по себе не означает, что программа не запускалась. Менять системные настройки journald ради этого урока не требуется.
Когда процесс активен, отдельно проверим готовность самого веб-приложения через эндпоинт /ready:
В коде Open WebUI 0.12.3 маршрут /ready начинает отвечать успешно только после того, как завершилась стартовая инициализация приложения и прошла проверка подключения к базе данных (а также к Redis, если он настроен). Пока сервер ещё поднимается, curl может вернуть ошибку соединения или сообщение об ответе 503 — в этом случае подождите немного и повторите команду. После завершения инициализации команда выполнится успешно, без ошибки соединения или HTTP-ошибки. Сам код 200 при таком наборе флагов в терминал не печатается. Эта проверка подтверждает готовность веб-сервера и базы данных, но не проверяет подключение языковых моделей.
После успешного ответа /ready откройте адрес http://127.0.0.1:8080 в браузере на той же машине с Ubuntu и войдите в учётную запись, созданную в предыдущем уроке. Поскольку мы сохранили прежний DATA_DIR и рабочую папку, вас должно встретить окно входа в существующий аккаунт, а не страница первичной регистрации администратора.
Будем управлять службой
Управление текущим процессом и настройка его автоматического старта при следующем запуске менеджера разделены. Команды в таблице рассчитаны на разные ситуации, поэтому выполнять их все подряд не нужно.
| Задача | Команда | Что происходит |
|---|---|---|
| Перезапустить службу | systemctl --user restart open-webui.service | Текущий процесс останавливается, затем менеджер запускает новый экземпляр |
| Временно остановить процесс | systemctl --user stop open-webui.service | Процесс завершается сейчас; unit-файл, виртуальное окружение, база данных и ключ остаются на месте |
| Запустить после остановки | systemctl --user start open-webui.service | Менеджер снова запускает остановленную службу с текущей конфигурацией |
| Отключить автозапуск и остановить | systemctl --user disable --now open-webui.service | Убирается привязка к запуску пользовательского менеджера, и работающий процесс останавливается |
Проверим перезапуск под управлением systemd:
После этого снова проверьте состояние процесса через systemctl --user status open-webui.service --no-pager, дождитесь успешного выполнения команды curl --fail --silent --show-error http://127.0.0.1:8080/ready и убедитесь, что интерфейс по адресу http://127.0.0.1:8080 открывается с вашей учётной записью.
Для остальных команд действуют три правила:
- Ручная остановка через
systemctl --user stopсчитается штатным действием пользователя, а не аварией. ПолитикаRestart=on-failureне будет самовольно поднимать службу, которую вы остановили явно. - Команда
systemctl --user disable open-webui.serviceбез флага--nowтолько отключает автоматический старт в будущем, но не останавливает уже работающий процесс. - Если вы отредактировали файл
~/.config/systemd/user/open-webui.service, сначала выполнитеsystemctl --user daemon-reload, затемsystemctl --user restart open-webui.serviceи повторите проверку готовности.
Остановка, перезапуск и отключение службы не удаляют каталог .venv, папку данных или файл секретного ключа. Перезапуск также не обновляет пакеты Python и не заменяет резервное копирование: как подчёркивается в руководстве по обновлению Open WebUI, перед любым обновлением версий и миграциями схемы данных нужно отдельно сохранять резервную копию хранилища.
Разберём ошибки при переходе на службу
Если служба не запускается или браузер открывает не тот экран, сопоставим симптом с уровнем настройки. Переустанавливать окружение или менять права доступа наугад не нужно.
| Наблюдение | Возможная причина и что проверить |
|---|---|
Failed to connect to bus: No medium found (или аналогичная ошибка шины) | Команда запущена вне полноценного пользовательского сеанса Ubuntu или от другого пользователя. Проверьте, что вы находитесь в обычном сеансе того же системного аккаунта. Добавлять sudo к systemctl --user нельзя — это не чинит подключение к пользовательской шине. |
Статус failed сразу после старта | Возможная причина — опечатка в путях ExecStart или WorkingDirectory. Сверьте пути в unit-файле с реальным расположением ~/open-webui-python и .venv/bin/open-webui, а после правки выполните daemon-reload и restart. |
Служба падает из-за занятого порта 8080 | Возможно, прежний ручной запуск open-webui serve не был остановлен; порт также может занимать другая программа. Проверьте открытые терминалы, штатно завершите свой старый процесс через Ctrl+C и перезапустите службу. Не принудительно завершайте незнакомые системные процессы. |
status показывает active (running), но /ready возвращает ошибку | Приложение ещё продолжает стартовую инициализацию либо столкнулось с ошибкой при открытии базы. Подождите немного, повторите запрос curl, а если ответ не появляется — проверьте вывод status и доступные строки journalctl --user. |
| В браузере открылась регистрация первого администратора вместо входа | Процесс запустился с другим каталогом DATA_DIR, от другого пользователя или вы открыли другой порт/экземпляр. Проверьте строку Environment="DATA_DIR=..." в unit-файле и адрес http://127.0.0.1:8080. |
| Открылось окно входа, но старый сеанс в браузере разлогинился | Повторный запрос пароля сам по себе не означает потерю базы данных: на активный токен сеанса мог повлиять срок его действия или смена рабочего каталога с файлом .webui_secret_key. Проверьте WorkingDirectory и войдите под прежней учётной записью. |
Повторные попытки запуска тоже ограничены: при частых сбоях может сработать ограничение частоты запусков systemd. Политика перезапуска не устраняет причину ошибки в unit-файле или окружении.
Если нужен запуск без входа пользователя
Этот раздел необязателен. Переходите к нему, только если базовый запуск службы уже проверен и Open WebUI нужен вне пользовательского сеанса.
По умолчанию жизненный цикл пользовательского менеджера systemd управляется модулем pam_systemd. Менеджер запускается при вашем первом входе в систему (графическом или консольном) и продолжает работать, пока открыт хотя бы один ваш сеанс. Поэтому закрытие одного окна терминала внутри активного рабочего стола не останавливает службу. Однако без дополнительной настройки нельзя рассчитывать, что пользовательская служба запустится сразу после включения питания компьютера до вашего входа или продолжит работать после того, как вы полностью выйдете из всех своих сеансов.
Чтобы пользовательский менеджер стартовал при загрузке ОС и не завершался после выхода из системы, в systemd используется режим linger (подробно описанный в справочнике loginctl). Настройка действует на весь пользовательский менеджер и все включённые в нём службы, а не только на open-webui.service.
Сначала посмотрим текущее состояние этого параметра для вашей учётной записи:
Значение Linger=no означает, что этот режим не включён. В обычной конфигурации работа менеджера связана с пользовательскими сеансами; точный момент его завершения зависит от настроек системы.
Если вам нужно, чтобы служба поднималась при загрузке машины до входа в систему и оставалась активной после полного выхода, и политика вашего компьютера позволяет такое изменение, включите этот режим:
Команда без указания имени применяется к пользователю текущего сеанса; в зависимости от настроек системы она может запросить подтверждение прав администратора. После выполнения можно снова вызвать loginctl show-user "$USER" --property=Linger и убедиться, что значение сменилось на Linger=yes. Эта строка подтверждает изменение настройки в systemd-logind, но не заменяет реальную проверку после перезагрузки хоста.
Если позже вы решите вернуться к стандартному поведению, режим можно отключить отдельной командой:
Выполняйте disable-linger только тогда, когда уверены, что фоновая работа без входа не нужна другим пользовательским службам в вашей учётной записи.
После этих проверок локальный Python-экземпляр Open WebUI управляется пользовательской службой systemd с прежним окружением .venv, каталогом данных и секретным ключом. Состояние процесса и готовность HTTP-интерфейса проверяются отдельно. Службу можно штатно перезапускать и останавливать, а работу менеджера во время сеанса или без входа выбирать через режим linger.
