Установка
Установка EduBox Core на сервер Linux
Инструкция для системного администратора: от скачивания до первого входа, резервные копии, обновление и диагностика.
Коротко: скачать и проверить архив (раздел 3) → edubox doctor - что на сервере и как
ставить (раздел 4) → edubox install (раздел 5) → edubox setup (раздел 6) → DNS (раздел 7) →
HTTPS, на общем сервере - edubox proxy-config (раздел 8) → edubox status (разделы 12, 13).
Что проверено на настоящем сервере
15.11.2026 EduBox установлен на сервер Ubuntu 24.04 (Hetzner), общий с другими проектами: nginx уже занимал порты 80 и 443 (около двадцати сайтов), PostgreSQL 16 самого сервера - порт 127.0.0.1:5432, в Docker работали чужие контейнеры. Проверено:
edubox installс базой в контейнере на порту 5433;edubox setupв режимеproxyза существующим nginx (EduBox на 127.0.0.1:8787);- служба под systemd со всеми ограничениями песочницы из юнита;
edubox backupиedubox restoreкопии, сделанной на другой машине.
Не проверено на настоящем сервере: режим files (TLS у самого EduBox), режим внешней базы,
восстановление службы на втором сервере, срабатывание ежедневного таймера копий.
Команды doctor, proxy-config, внешние проверки status и автоматический выбор портов
написаны после этой установки по её итогам - то, что тогда делалось вручную. Они проверены
тестами, выводом --dry-run и на macOS (настройки nginx - nginx -t версии 1.29), но на
настоящем сервере ещё не запускались.
1. Что получится
Интернет ──► :443 ─┐
├─ edubox serve (служба systemd, пользователь edubox)
Интернет ──► :80 ──┘ │ читает /etc/edubox/edubox.toml
(или nginx/Caddy, │ данные в /var/lib/edubox
который уже стоит) ▼
PostgreSQL 17 в контейнере edubox-postgres (только 127.0.0.1, порт 5432
или первый свободный с 5433) или внешний PostgreSQL по строке подключения
На свободном сервере EduBox сам принимает 80 и 443 (режим files). На общем сервере, где
порты уже заняты nginx или другим веб-сервером, EduBox слушает локальный порт за ним
(режим proxy) - edubox doctor определяет это сам.
| Что | Где |
|---|---|
| Исполняемый файл | /usr/local/bin/edubox |
| Настройки службы (с паролем роли службы, права 0640 root:edubox) | /etc/edubox/edubox.toml |
| Пароль владельца базы (только для команд от root, права 0600 root:root) | /etc/edubox/owner.toml |
| Пароль суперпользователя PostgreSQL в контейнере (0600) | /etc/edubox/postgres.env |
| Шаблоны сайтов | /var/lib/edubox/templates |
| Загруженные файлы | /var/lib/edubox/uploads |
| Резервные копии (по умолчанию, 0700 root) | /var/lib/edubox/backups |
| Служба и ежедневная копия | /etc/systemd/system/edubox.service, edubox-backup.service, edubox-backup.timer |
| Данные PostgreSQL | том Docker edubox-pgdata |
В базе две роли:
edubox_owner- владелец базы. Ею пользуются только команды, запускаемые от root:edubox migrate,setup,seed,admin create,backup,restore. Её строка подключенияmigrate_database_urlлежит в отдельном файле/etc/edubox/owner.toml(0600 root:root), который служба прочитать не может.edubox_app- роль работающей службы (строкаdatabase_url). Может читать и менять строки таблиц, но не может менять схему, удалять таблицы, отключать триггеры журнала действий; в журнал действий может только дописывать.
Служба не применяет миграции сама: если схема базы не совпадает с версией программы,
она не запускается и пишет в журнал, что делать (edubox migrate).
Служба не запускается, если пароль владельца доступен ей: когда migrate_database_url
записан в /etc/edubox/edubox.toml или задан в переменной окружения
EDUBOX_MIGRATE_DATABASE_URL, она отказывается стартовать (см. «Диагностика»). Строке место
только в owner.toml.
2. Требования
- Linux x86_64 или aarch64 с systemd (Ubuntu 22.04+, Debian 12+, Astra Linux SE 1.7+, RHEL/Alma/Rocky 9 и подобные). Программа собрана статически и не зависит от версии glibc.
- Доступ root (
sudo). - Для PostgreSQL на этом же сервере: Docker (команда
dockerи службаdocker) и доступ к образуdocker.io/library/postgres:17(или его копия во внутреннем реестре, см. «Диагностика»). Порт 5432 может быть занят другим PostgreSQL - тогда база EduBox получит первый свободный порт с 5433. - Либо внешний PostgreSQL 17 и на этом сервере клиентские программы
pg_dump/pg_restoreверсии 17 (пакетpostgresql-client-17) - они нужны для резервных копий. - Домен для портала, например
edu.example.kz, и возможность создать в DNS запись для него и для*.edu.example.kz. - Сертификат TLS на
edu.example.kzи*.edu.example.kz(wildcard) - на обратном прокси или в файлах на этом сервере (раздел 8). Это могут быть и два разных сертификата. - Свободные порты 80 и 443 (если TLS у самого EduBox) или уже работающий веб-сервер (nginx, Caddy, Apache), за которым встанет EduBox.
- Место на диске: от 10 ГБ для начала; загруженные файлы и копии растут со временем. Копии лучше держать на отдельном диске.
3. Скачивание и проверка
Скачайте архив под архитектуру сервера (uname -m: x86_64 или aarch64) и файл
контрольной суммы рядом с ним:
edubox-0.1.0-linux-x86_64.tar.gz
edubox-0.1.0-linux-x86_64.tar.gz.sha256
Проверьте и распакуйте:
sha256sum -c edubox-0.1.0-linux-x86_64.tar.gz.sha256 # должно быть: OK
tar -xzf edubox-0.1.0-linux-x86_64.tar.gz
cd edubox-0.1.0-linux-x86_64
sha256sum -c SHA256SUMS # все файлы: OK
./edubox --version
Внутри: edubox (программа, админка уже внутри), templates/ (шаблоны сайтов),
docs/install.md (этот файл), SHA256SUMS.
Контрольную сумму архива сверяйте с той, что получена по отдельному доверенному каналу (не с того же сервера, откуда скачан архив). Подпись выпусков появится позже.
4. Проверка сервера: edubox doctor
Первый шаг на любом сервере - особенно на общем, где уже работают другие сайты:
sudo ./edubox doctor --domain edu.example.kz
Ничего не меняет. Показывает:
- кто занимает порты 80 и 443 (nginx, apache, caddy, контейнер Docker или неизвестная программа) и порт 127.0.0.1:5432;
- есть ли и работает ли Docker, есть ли systemd, сколько места там, где будут данные;
- установлен ли EduBox уже (файл настроек, служба, контейнер базы);
- куда указывают записи DNS домена и
*.домена(см. раздел 12 «Проверки снаружи») - до того, как заказывать сертификат; - рекомендацию простыми словами: режим HTTPS (
files, если 80 и 443 свободны;proxy, если их уже занял веб-сервер), свободный локальный порт для EduBox в режимеproxy(первый свободный с 127.0.0.1:8080), порт базы (5432 или первый свободный с 5433), готовые командыinstall,setup,proxy-configи предупреждения, например «nginx is running: EduBox will be installed behind it».
Пример на общем сервере:
Server
port 80 in use by nginx (0.0.0.0:80, [::]:80)
port 443 in use by nginx (0.0.0.0:443, [::]:443)
127.0.0.1:5432 in use by postgres (127.0.0.1:5432)
…
Recommended
HTTPS proxy: nginx already owns ports 80 and 443: EduBox will listen on a local port behind it
behind proxy yes
listen 127.0.0.1:8080 (a free local port the nginx forwards to)
database port 127.0.0.1:5433 (127.0.0.1:5432 is used by postgres (another PostgreSQL); …)
--json - то же для сценариев; --offline - без проверок по сети. Код выхода 1, если
установка откажется (строки «Install would refuse») или проверки снаружи нашли проблему.
Без --domain берётся домен из уже записанных настроек.
Как это определяется и где может ошибаться:
- Занятые порты читаются из
/proc/net/tcpи/proc/net/tcp6, имя программы - через/proc/<pid>/fd. Безsudoимена чужих программ не видны: порт будет «in use by a program that could not be identified». Порт, проброшенный Docker безdocker-proxy("userland-proxy": false), в этих таблицах не виден. - Docker: команда
docker version; «installed, not answering» - служба не запущена или нет прав. - Если EduBox уже установлен, его собственные порты (служба, контейнер базы) не считаются занятыми - повторная установка их сохраняет.
5. Установка: edubox install
Сначала посмотрите, что будет сделано, - ничего не меняется, пароли скрыты:
sudo ./edubox install --dry-run
Вывод начинается с итогов проверки сервера (строки # environment: …, # HTTPS: …,
# database port …: … - какой порт базы выбран и почему), затем перечисляет каждый файл с
содержимым и каждую команду. Строки # would refuse: … означают, что установка откажется
(не root, нет systemd, нет docker).
Порт базы выбирается сам. Если 127.0.0.1:5432 занят (например, PostgreSQL самого сервера),
install берёт первый свободный порт с 5433 и пишет, почему. Явный --db-port 5440 всегда
главнее; занятый явный порт - отказ. При повторной установке остаётся порт, записанный в
настройках.
Затем установка:
sudo ./edubox install
Она:
- создаёт системного пользователя
eduboxбез входа в систему; - создаёт
/etc/eduboxи/var/lib/eduboxс подпапками и правами из таблицы выше; - копирует программу в
/usr/local/bin/eduboxи шаблоны в/var/lib/edubox/templates(поставляемые шаблоны обновляются; свои шаблоны держите в папках с другими именами); - запускает контейнер
edubox-postgres(PostgreSQL 17, только на 127.0.0.1, порт 5432 или выбранный, томedubox-pgdata, перезапускunless-stopped), ждёт его готовности, создаёт ролиedubox_owner,edubox_appи базуeduboxсо случайными паролями; - пишет два файла:
/etc/edubox/edubox.toml(0640 root:edubox) со строкой подключения службы и/etc/edubox/owner.toml(0600 root:root) со строкой владельца базы. Если вedubox.tomlосталась строкаmigrate_database_urlот прежней версии, она переносится вowner.tomlи изedubox.tomlудаляется; - пишет и включает службу
eduboxи таймер ежедневной копии (служба запустится послеsetup).
Повторный запуск безопасен: существующие пользователь, контейнер и пароли сохраняются,
ключи, записанные setup, не трогаются.
Служба работает с ограничением памяти: MemoryHigh=1536M (выше ядро начинает жёстко отбирать
память), MemoryMax=2G (при превышении служба завершается), MemorySwapMax=0 (без подкачки),
и перезапускается после сбоя (Restart=on-failure, через 5 секунд). Изменить ограничения:
sudo systemctl edit edubox, в открывшемся файле [Service] и новые значения, затем
sudo systemctl restart edubox.
Внешний PostgreSQL
Если база на отдельном сервере, контейнер не нужен. Попросите администратора базы создать роли и базу (пароли придумайте свои):
CREATE ROLE edubox_owner LOGIN PASSWORD '…';
CREATE ROLE edubox_app LOGIN PASSWORD '…';
CREATE DATABASE edubox OWNER edubox_owner ENCODING 'UTF8' TEMPLATE template0;
REVOKE ALL ON DATABASE edubox FROM PUBLIC;
GRANT CONNECT, TEMPORARY ON DATABASE edubox TO edubox_app;
Права edubox_app на таблицы выдаёт сама команда edubox migrate после каждой миграции.
Установка (строка владельца попадёт в /etc/edubox/owner.toml, строка службы - в
/etc/edubox/edubox.toml):
sudo ./edubox install \
--database-url 'postgres://edubox_app:ПАРОЛЬ@db.example.kz:5432/edubox' \
--migrate-database-url 'postgres://edubox_owner:ПАРОЛЬ@db.example.kz:5432/edubox'
Особые символы в пароле в строке подключения кодируются как в адресах (@ → %40).
Для TLS к базе добавьте ?sslmode=require (или verify-full).
6. Настройка: edubox setup
sudo edubox setup
Вопросы:
| Вопрос | Пример | Что значит |
|---|---|---|
| Домен портала | edu.example.kz | сайты будут <имя>.edu.example.kz, админка admin.edu.example.kz. Кириллический домен - в punycode (xn--…) |
| Почта первого администратора | admin@example.kz | ему печатается ссылка-приглашение |
| Название корневой организации (каз., затем рус.) | Абай облысының білім басқармасы | корневой узел портала |
| Как обеспечивается HTTPS | proxy или files | раздел 8; по умолчанию - рекомендация проверки сервера |
| Адрес, который слушает EduBox | 127.0.0.1:8080 | для proxy - локальный порт, куда прокси передаёт запросы (по умолчанию свободный, найденный проверкой); для files - 0.0.0.0:443 |
Путь к сертификату и ключу (для files) | /etc/edubox/tls/fullchain.pem | PEM-файлы |
Стоит ли перед EduBox обратный прокси, который ставит X-Forwarded-For | yes / no | см. ниже |
| Папка для резервных копий | /backup/edubox | лучше отдельный диск |
Перед вопросами setup печатает ту же рекомендацию, что edubox doctor; в квадратных скобках
стоит рекомендованный ответ - Enter принимает его. Если выбранный адрес уже занят другой
программой (и её удалось опознать), setup отказывается и предлагает свободный.
Вопрос о прокси задаётся всегда и намеренно. Если ответить неверно, все посетители за прокси
будут выглядеть как один адрес, и ограничение попыток входа заблокирует всех сразу; или,
наоборот, любой сможет подделать свой адрес. Поэтому setup не принимает противоречивые
ответы: при proxy ответ должен быть yes, при files - no.
Затем setup пишет настройки, создаёт схему базы (миграции ролью-владельцем), выдаёт права
роли службы и проверяет, что служба может подключиться, заносит справочники (языки, уровни,
типы разделов) и корневой узел (без демонстрационных организаций), печатает ссылку-приглашение
администратора, нужные записи DNS и запускает службу.
Без вопросов, для сценариев:
sudo edubox setup --non-interactive \
--domain edu.example.kz --admin-email admin@example.kz \
--root-name 'Абай облысының білім басқармасы' \
--root-name-ru 'Управление образования области Абай' \
--tls proxy --behind-proxy yes --backup-dir /backup/edubox
Без --listen в режиме proxy берётся свободный локальный порт (первый с 127.0.0.1:8080, при
повторном запуске - прежний); --listen 127.0.0.1:8787 задаёт его явно. --tls (если
его нет в прежних настройках) и --behind-proxy в таком запуске обязательны: при их отсутствии setup называет
рекомендованное значение, но сам его не подставляет.
В режиме proxy setup заканчивается подсказкой, как получить настройки веб-сервера:
sudo edubox proxy-config --server nginx --write /etc/nginx/sites-available/edubox.conf.
Повторный setup безопасен: меняет настройки, переименовывает корень и печатает новую ссылку
(если пользователь уже есть - ссылку сброса пароля).
7. DNS
У регистратора или в DNS-сервере создайте две записи на публичный адрес сервера (или прокси):
edu.example.kz. A 203.0.113.10
*.edu.example.kz. A 203.0.113.10
Wildcard покрывает admin.edu.example.kz и все сайты. Проверка: dig +short admin.edu.example.kz
или sudo edubox doctor --domain edu.example.kz - он сравнивает ответ DNS с адресами самого
сервера (до заказа сертификата: без записей DNS сертификат не выдадут).
8. HTTPS
Режим proxy: за nginx, Caddy или другим прокси
EduBox слушает локальный адрес (listen в настройках, например 127.0.0.1:8080), прокси
принимает 80 и 443 и передаёт запросы, сохраняя заголовок Host и добавляя адрес клиента в
X-Forwarded-For. EduBox берёт самый правый адрес из X-Forwarded-For - тот, что добавил
ближайший прокси.
Настройки для прокси пишет сама программа - для настроенного домена и адреса:
sudo edubox proxy-config --server nginx # напечатать
sudo edubox proxy-config --server nginx \
--write /etc/nginx/sites-available/edubox.conf # записать в файл
sudo edubox proxy-config --server caddy --write /etc/caddy/edubox.caddy
В настройках nginx: перенаправление HTTP → HTTPS (кроме /.well-known/acme-challenge/ - для
выпуска сертификатов через /var/www/html), отдельный блок для edu.example.kz и отдельный для
*.edu.example.kz (у них могут быть разные сертификаты), www.edu.example.kz → edu.example.kz,
Host сохраняется, X-Forwarded-For дополняется, X-Forwarded-Proto, предел тела запроса
51m (загрузки до 50 МБ), таймауты 5 с на соединение и 120 с на ответ. Строка
listen 443 ssl http2; выбрана намеренно: её понимают и nginx 1.24 (Ubuntu 24.04), и новые
версии; nginx 1.25.1 и новее печатают при nginx -t безвредное предупреждение
the "listen ... http2" directive is deprecated (новой формы http2 on; в 1.24 нет).
Пути к сертификатам:
| Параметр | По умолчанию |
|---|---|
--cert, --key - для edu.example.kz | nginx: /etc/letsencrypt/live/edu.example.kz/fullchain.pem, privkey.pem; Caddy: выпускает сам |
--wildcard-cert, --wildcard-key - для *.edu.example.kz | те же, что для основного домена |
Если файлов ещё нет или сертификат не покрывает нужное имя либо истекает через 14 дней и раньше, команда предупреждает. Веб-сервер она не перезагружает - печатает точные команды:
sudo ln -sf /etc/nginx/sites-available/edubox.conf /etc/nginx/sites-enabled/edubox.conf
sudo nginx -t && sudo systemctl reload nginx
Для Caddy - import /etc/caddy/edubox.caddy в /etc/caddy/Caddyfile, затем
caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddy. Caddy сам
перенаправляет на HTTPS и выпускает сертификат для основного домена; сертификат на
*.edu.example.kz он может получить только через DNS, для этого нужна сборка Caddy с модулем
DNS-провайдера (в выводе есть закомментированный пример) - или укажите готовые файлы
--wildcard-cert/--wildcard-key.
Если прокси на другой машине, укажите в setup --listen внутренний адрес этого сервера и
закройте порт межсетевым экраном для всех, кроме прокси.
Общий сервер: EduBox за уже работающим nginx
Так прошла первая установка. Порядок:
sudo ./edubox doctor --domain edu.example.kz # nginx на 80/443, 5432 занят → proxy, порты
sudo ./edubox install # сам берёт порт базы, например 5433
sudo edubox setup # Enter на рекомендованных ответах: proxy, yes,
# свободный 127.0.0.1:8080 (или --listen …)
sudo edubox proxy-config --server nginx --write /etc/nginx/sites-available/edubox.conf
# сертификаты: --cert/--key, --wildcard-cert/--wildcard-key
sudo ln -sf /etc/nginx/sites-available/edubox.conf /etc/nginx/sites-enabled/edubox.conf
sudo nginx -t && sudo systemctl reload nginx
sudo edubox status # база, DNS, HTTPS обоих имён
Чужие сайты и их настройки не затрагиваются: EduBox добавляет только свой файл с блоками
server_name edu.example.kz, *.edu.example.kz, www.edu.example.kz. Если на сервере уже
есть блок с таким же server_name (например, старая заглушка домена), nginx -t предупредит
conflicting server name - отключите старый блок (уберите ссылку из sites-enabled).
Режим files: TLS у самого EduBox
EduBox слушает 443 с сертификатом и ключом из PEM-файлов и отвечает на 80 перенаправлением на
https. Права на порты даёт служба (CAP_NET_BIND_SERVICE), root не нужен. Файлы должны читаться
пользователем edubox:
sudo install -d -m 0750 -o root -g edubox /etc/edubox/tls
sudo install -m 0640 -o root -g edubox fullchain.pem /etc/edubox/tls/fullchain.pem
sudo install -m 0640 -o root -g edubox privkey.pem /etc/edubox/tls/privkey.pem
В fullchain.pem сначала сертификат сайта, затем промежуточные. После замены файлов:
sudo systemctl reload edubox # перечитывает сертификат без остановки (SIGHUP)
Если новые файлы не читаются, остаётся прежний сертификат, а в журнале - ошибка.
Срок действия показывает edubox status.
Сертификат на все поддомены вручную
Автоматического выпуска сертификатов пока нет. Сертификат на *.edu.example.kz (его требуют
admin.edu.example.kz и все сайты школ) Let's Encrypt выдаёт только с проверкой через DNS:
нужно создать запись TXT. Так сделано при первой установке:
Сертификат на основной домен
edu.example.kz- обычным способом, напримерsudo certbot --nginx -d edu.example.kz(проверка по HTTP; certbot продлевает его сам).Сертификат на поддомены - вручную через DNS:
sudo certbot certonly --manual --preferred-challenges dns -d '*.edu.example.kz' \ --cert-name edu.example.kz-wildcardcertbot покажет значение для одной записи
TXT _acme-challenge.edu.example.kz. Создайте её у DNS-провайдера, дождитесь, пока она видна (dig +short TXT _acme-challenge.edu.example.kz), нажмите Enter. Файлы появятся в/etc/letsencrypt/live/edu.example.kz-wildcard/.Подключите оба сертификата:
sudo edubox proxy-config --server nginx \ --wildcard-cert /etc/letsencrypt/live/edu.example.kz-wildcard/fullchain.pem \ --wildcard-key /etc/letsencrypt/live/edu.example.kz-wildcard/privkey.pem \ --write /etc/nginx/sites-available/edubox.conf sudo nginx -t && sudo systemctl reload nginx
Ограничения, честно:
- Сертификат действует около 90 дней и сам не продлевается:
certbot renewдля сертификата, полученного с--manual, не сработает без скрипта для DNS-провайдера. Каждые два–три месяца процедуру надо повторять (с новым значением TXT).edubox statusнапоминает за 14 дней: «expires in N days: renew it». - Значение TXT каждый раз новое; старую запись можно удалить после выпуска.
- Если просить сразу
-d edu.example.kz -d '*.edu.example.kz', certbot попросит два значения для одной и той же записи_acme-challenge- оба нужно добавить в неё, а продлевать такой сертификат тоже придётся вручную. Поэтому основной домен лучше держать отдельным сертификатом с автоматическим продлением. - В режиме
files(TLS у самого EduBox) нужен один сертификат на оба имени: тогда запросите оба имени сразу и скопируйте файлы, как показано выше для режимаfiles.
Сертификат от другого удостоверяющего центра: закажите на edu.example.kz и
*.edu.example.kz, ключ создайте у себя:
openssl req -new -newkey rsa:3072 -nodes -keyout privkey.pem -out request.csr \
-subj "/CN=edu.example.kz" -addext "subjectAltName=DNS:edu.example.kz,DNS:*.edu.example.kz"
Полученный сертификат и цепочку соедините: cat cert.pem intermediate.pem > fullchain.pem.
9. Первый вход
setup печатает ссылку вида https://admin.edu.example.kz/invite/?token=…. Откройте её,
задайте пароль - вы администратор корневого узла. Ссылка потерялась или истекла:
sudo edubox admin create --email admin@example.kz
Эта же команда - аварийный вход: для существующего пользователя печатает ссылку сброса пароля.
10. Резервные копии
Таймер edubox-backup.timer каждый день около 02:30 делает копию и оставляет 14 последних.
Вручную:
sudo edubox backup # одна копия в backup_dir
sudo edubox backup --keep 30 # и удалить старше 30 последних
systemctl list-timers edubox-backup.timer
journalctl -u edubox-backup -n 20
Копия - один файл edubox-backup-ГГГГММДД-ЧЧММСС.tar.gz (время UTC): дамп базы, загруженные
файлы, копии обоих файлов настроек - config/edubox.toml и config/owner.toml (пароли базы
в них заменены на REDACTED) - и manifest.json с версией программы, версией схемы и
контрольными суммами всех файлов.
Символические ссылки и особые файлы (каналы, сокеты, устройства) в папке загруженных файлов в копию не попадают и не разыменовываются: команда перечисляет пропущенное в своём выводе и в журнале. Обычно таких файлов там нет; если они появились, выясните, откуда.
Копии на этом же сервере не спасут при потере сервера. Пока автоматической отправки нет, копируйте их регулярно на другую машину, например:
rsync -a /backup/edubox/ backup-host:/srv/edubox-backups/
Восстановление
sudo edubox restore /backup/edubox/edubox-backup-20261115-023012.tar.gz
Команда распаковывает архив во временную папку, принадлежащую root, вне папки данных
(/var/tmp, если она есть, иначе системная временная папка), проверяет контрольные суммы и
версию схемы (копию из более новой версии программы не примет), спрашивает подтверждение
(--yes - без вопроса), останавливает службу, делает копию текущего состояния
(…-pre-restore.tar.gz; пропустить - --no-safety-backup), заменяет базу и загруженные
файлы, доводит схему до версии программы и запускает службу. Загруженные файлы копируются из
временной папки без перехода по символическим ссылкам.
Прежние файлы остаются в /var/lib/edubox/uploads.before-restore-… - удалите, когда убедитесь,
что всё в порядке. Файлы настроек (edubox.toml, owner.toml) не заменяются; их копии из
архива (с паролями REDACTED) кладутся в папку копий как restored-config-…toml и
restored-owner-…toml.
На новом сервере: install, затем setup с теми же ответами (домен, TLS, прокси - их можно
посмотреть в config/edubox.toml внутри архива: tar -xzOf АРХИВ config/edubox.toml), затем
restore. Приглашение, напечатанное setup, после восстановления недействительно - входите
прежними учётными записями.
11. Обновление (пока вручную)
# скачать и проверить новый архив (раздел 3), распаковать, перейти в папку
sudo edubox backup
sudo systemctl stop edubox
sudo install -m 0755 ./edubox /usr/local/bin/edubox
sudo cp -r ./templates/. /var/lib/edubox/templates/
sudo edubox migrate
sudo systemctl start edubox
sudo edubox status
Откат: верните прежний файл программы. Если новая версия уже применила миграции, прежняя откажется запускаться («the database was migrated by a newer EduBox») - тогда восстановите копию, сделанную перед обновлением, прежней версией программы.
Обновление с проверкой подписи и автоматическим откатом появится позже.
12. Проверки снаружи (DNS, HTTPS)
edubox status и edubox doctor смотрят на установку и со стороны сети:
- DNS. Основной домен и проверочное имя
edubox-check-….edu.example.kz(проверяет запись*.edu.example.kz) должны указывать на адрес этого сервера. Адреса сервера берутся из таблиц ядра (/proc/net/fib_trie,/proc/net/if_inet6). Если у сервера нет публичного адреса (он за NAT или балансировщиком), программа пишет «could not determine», а не гадает. Если имя на самом сервере указывает на 127.0.0.1 (запись в/etc/hosts), проверка тоже не делается - проверьте с другой машины:dig +short edu.example.kz. - HTTPS (только в режиме
proxy): запросыhttps://edu.example.kz/healthzиhttps://admin.edu.example.kz/api/health, а также рукопожатие TLS с проверочным именем поддомена. Для каждого - ответ, действительность сертификата (по встроенному списку корневых центров, как в браузере) и срок. Проблема, если сертификат недействителен, не покрывает*.edu.example.kz(«the wildcard certificate is missing») или истекает через 14 дней и раньше, а также если прокси отвечает 502 (EduBox не запущен или прокси смотрит не туда).
У каждой сетевой операции короткий таймаут (3–4 с), все идут параллельно. Если сети нет или
ответа не дождались, пункт помечается «not checked: …» и не считается проблемой (код выхода не
меняется). --offline пропускает эти проверки совсем.
13. Диагностика
sudo edubox doctor # что на сервере: порты, Docker, systemd, место, DNS; рекомендация
sudo edubox status # версия, схема, база, место, последняя копия, сертификат, DNS, HTTPS
sudo edubox status --json # то же для мониторинга; код выхода 1 при проблемах
sudo edubox status --offline # без проверок по сети
journalctl -u edubox -f # журнал службы
systemctl status edubox
docker logs edubox-postgres # журнал PostgreSQL
| Признак | Причина и что делать |
|---|---|
refusing to start: the database schema is behind this binary | после обновления не выполнена sudo edubox migrate |
refusing to start: the database has no EduBox schema yet | не выполнен sudo edubox setup |
base_domain is not set | не выполнен sudo edubox setup |
refusing to start: migrate_database_url … | пароль владельца базы доступен службе: строка migrate_database_url есть в /etc/edubox/edubox.toml или задана EDUBOX_MIGRATE_DATABASE_URL. Перенесите строку в /etc/edubox/owner.toml (0600 root:root) - это делает повторный sudo edubox install, - уберите её из edubox.toml и из окружения службы (systemctl cat edubox), затем sudo systemctl start edubox |
reading /etc/edubox/owner.toml (run this command as root) | команды migrate, setup, seed, admin create, backup, restore запускайте через sudo |
служба перезапускается сама, в журнале oom-kill или memory | упёрлась в MemoryMax=2G; посмотрите, что её нагружает, при необходимости поднимите предел через sudo systemctl edit edubox |
binding 0.0.0.0:443: Permission denied | служба запущена не из юнита (нет CAP_NET_BIND_SERVICE) - запускайте через systemctl |
binding …: Address in use | порт занят другой программой: sudo edubox doctor покажет какой; для режима proxy выберите свободный адрес (setup --listen), затем proxy-config заново |
reading /etc/edubox/tls/…: Permission denied | права на файлы сертификата: группа edubox, режим 0640, папка 0750 |
connecting to PostgreSQL | контейнер не запущен: docker ps -a, docker start edubox-postgres; внешняя база - проверьте строку и доступ |
установка: port 5440 on 127.0.0.1 (given with --db-port) is in use | явно указанный порт базы занят: уберите --db-port (свободный выберется сам) или укажите другой |
status: DNS edu.example.kz: does not resolve / points to … | нет записи A или она указывает не на этот сервер (раздел 7) |
status: the wildcard certificate is missing | прокси отдаёт для поддоменов сертификат без *.edu.example.kz: раздел «Сертификат на все поддомены вручную», затем proxy-config --wildcard-cert … |
status: expires in N days: renew it | продлите сертификат; полученный вручную через TXT сам не продлится |
status: answered 502 | прокси не достучался до EduBox: systemctl status edubox; адрес в настройках прокси должен совпадать с listen в /etc/edubox/edubox.toml |
nginx -t: conflicting server name | на сервере уже есть блок с тем же доменом (заглушка): уберите его ссылку из sites-enabled |
образ postgres:17 не скачивается (нет интернета) | на машине с интернетом docker pull postgres:17 && docker save postgres:17 -o pg17.tar, перенести, docker load -i pg17.tar и повторить install |
| страница «сайт не найден» | нет записи DNS (sudo edubox status) или узел с таким коротким именем не создан/не опубликован |
| все входы блокируются разом | за прокси ответили no на вопрос о прокси или прокси не ставит X-Forwarded-For - повторите setup |
| копии не делаются | journalctl -u edubox-backup; для внешней базы нужен pg_dump версии 17 |
Подробный журнал: sudo systemctl edit edubox, добавить
[Service] / Environment=RUST_LOG=edubox=debug,tower_http=debug, затем systemctl restart edubox.