Развёртывание через Docker Compose

Панель работает за Nginx с HTTPS и управляет Samba по SSH. Используйте отдельную production-конфигурацию: Compose в корне проекта без суффикса production предназначен для разработки.

Варианты

Конфигурация	Назначение
`docker-compose.production.yml`	Панель и Nginx; Samba уже установлена на другом сервере.
Оба файла: `production` и `samba`	Дополнительно изолированный Samba/SSH-узел с постоянными томами.

HTTP-порт приложения и SSH-порт Samba-узла не публикуются на хосте. Снаружи доступен только HTTPS и, во втором варианте, SMB на выбранном адресе. По умолчанию оба порта привязаны к 127.0.0.1. Для доступа из LAN явно задайте адрес сервера в .env и настройте сетевой доступ.

Панель и Nginx запускаются без root, с read-only корневой файловой системой и без capabilities. Включён no-new-privileges. Samba-узел работает от root внутри контейнера: это необходимо для создания системных пользователей, изменения владельцев файлов и работы Samba. Он не использует privileged, Docker socket, host network или каталоги хоста с системной конфигурацией.

Требования

Docker Engine и Docker Compose с поддержкой up --wait и Compose secrets; Git для получения файлов поставки.
Опубликованный Docker-образ Sambryx с конкретным тегом версии или digest.
TLS-сертификат с полной цепочкой и приватный ключ для имени панели.
Непривилегированный пользователь с доступом к Docker; Bash для скрипта запуска.
Для встроенного Samba-узла: доступ к Ubuntu-репозиториям при первой сборке и отдельная пара SSH-ключей.

JDK и npm на сервере установки не требуются. Автоматическое получение и продление сертификата в этот Compose не входит. Передавайте сертификаты из вашего существующего процесса управления TLS.

Настройка

Справочник настроек разделяет переменные Compose, свойства панели и пути на Samba-сервере.

Получите файлы Compose, Nginx и скрипт запуска вместе. Для новой установки:

git clone https://github.com/AndreyJVM/sambryx.git
cd sambryx

Команда получает текущий исходный код и файлы установки; приложение запускается из опубликованного образа, сборка исходников не нужна. Файлы master могут быть новее выбранного образа. Изменения приложения после его тега попадут пользователям только с последующим релизом. Для воспроизводимой установки сохраняйте выбранный commit файлов и тег/digest образа.

Далее все команды выполняйте из этого каталога. При обновлении используйте существующий каталог и сохраните .env, ключи и имя Compose-проекта; повторно их не создавайте.

umask 077
mkdir -p deploy/production/secrets
cp deploy/production/.env.example deploy/production/.env
id -u
id -g

Поместите сертификат и ключ в выбранные файлы и отредактируйте .env. Список опубликованных версий есть в Releases; например, для версии v0.15.0 тег образа — andreyvorobevaqa/sambryx:0.15.0. Не оставляйте REPLACE_WITH_RELEASE_TAG и не используйте latest. Подготовьте SSH_KNOWN_HOSTS_FILE по инструкции доверия до запуска: файл должен существовать и читаться UID 10001.

Переменная	Настройка
`COMPOSE_PROJECT_NAME`	Имя нового проекта: `sambryx-production`; для существующего стека сохраните прежнее имя, см. переход.
`SAMBRYX_IMAGE`	Конкретный опубликованный тег или digest. Замените `REPLACE_WITH_RELEASE_TAG`; `latest` не используется.
`PROXY_UID`, `PROXY_GID`	Ненулевые UID/GID владельца TLS-ключа; значения `id -u` и `id -g`.
`TLS_CERT_FILE`	Путь к полной цепочке сертификата.
`TLS_KEY_FILE`	Путь к приватному ключу с правами `0600`, доступному `PROXY_UID`.
`HTTPS_BIND_IP`, `HTTPS_PORT`	Адрес и порт HTTPS; по умолчанию `127.0.0.1:8443`.
`SSH_KNOWN_HOSTS_FILE`	Файл независимо проверенных SSH-ключей сервера, read-only; см. инструкцию.
`SSH_AUTHORIZED_KEYS_FILE`	Только для встроенного узла: файл публичного SSH-ключа управления.
`SAMBA_BIND_IP`, `SAMBA_PORT`	Только для встроенного узла: адрес и порт SMB; по умолчанию `127.0.0.1:445`.

Относительные пути разрешаются от корня репозитория. .env и каталог secrets исключены из Git. Приватный TLS-ключ не должен быть доступен всем пользователям. Если ключ принадлежит другому служебному пользователю, настройте UID/GID Nginx и права доступа соответственно.

Compose secrets здесь являются read-only файловыми подключениями, а не зашифрованным хранилищем секретов. Защищайте исходные файлы и резервные копии на хосте.

Панель для существующего сервера

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

docker compose --env-file deploy/production/.env \
  -f docker-compose.production.yml config --quiet
docker compose --env-file deploy/production/.env \
  -f docker-compose.production.yml pull web nginx
bash scripts/production/run.sh
docker compose --env-file deploy/production/.env \
  -f docker-compose.production.yml ps

Ожидаемый результат: web и nginx имеют состояние healthy. Это подтверждает готовность HTTP/HTTPS, но ещё не SSH-доступ и не права на удалённом сервере.

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

Эквивалентная команда без скрипта:

docker compose --env-file deploy/production/.env \
  -f docker-compose.production.yml up -d --wait

Откройте https://<имя-панели>:<HTTPS_PORT>/ui/ и укажите SSH-адрес Samba-сервера и его реквизиты. SSH-сервер должен разрешать необходимые административные команды; см. настройку сервера. Пароли и SSH-ключи для входа не задаются через Compose environment.

Nginx заменяет входящие forwarded-заголовки. В приложении включена обработка forwarded-заголовков и защищённая сессионная cookie. Не публикуйте web:8080 напрямую и не подключайте посторонние контейнеры к сети proxy: приложение доверяет заголовкам обратного прокси. TLS защищает браузерное соединение. Подлинность SSH-сервера проверяется по read-only known_hosts; неизвестный или изменившийся ключ запрещает вход. Перед запуском настройте доверенные ключи.

Адреса и проверка первого подключения

Где используется адрес	Что указывать
URL в браузере	Имя панели из TLS-сертификата и `HTTPS_PORT`, например `https://panel.example.org:8443/ui/`. Имя должно разрешаться на Docker-хост.
«Хост / IP» в форме входа	Адрес Samba-сервера, разрешаемый и достижимый из контейнера `web`, например `files.example.org`. Не URL панели и не SMB-путь.
`known_hosts`	Точно тот же SSH-хост; для порта 22 — `files.example.org`, для 2222 — `[files.example.org]:2222`.
Встроенный Samba-узел	В форме — `samba-node`, порт 22; в `known_hosts` — `samba-node`. Это имя доступно внутри Compose-сети.

localhost / 127.0.0.1 в форме относятся к контейнеру web. Даже если Samba работает на Docker-хосте, укажите его адрес, доступный из контейнера. Наличие SSH-доступа из терминала оператора само по себе не доказывает доступность из Docker-сети.

При HTTPS_BIND_IP=127.0.0.1 браузер должен работать на Docker-хосте либо использовать заранее настроенный защищённый туннель к нему. Для LAN-доступа задайте конкретный LAN-IP Docker-хоста в HTTPS_BIND_IP, настройте DNS и разрешите HTTPS-порт в существующем firewall. TLS-сертификат должен соответствовать имени в браузере. Не обходите проверку сертификата.

Вход выполняется SSH-пользователем сервера. Укажите SSH-порт через кнопку «Порт: 22», выберите пароль или SSH-ключ и нажмите «Подключиться». Успех — открывается обзор сервера; проверьте статус Samba и список общих папок. Наличие пустого списка не является ошибкой подключения. У отдельного нового Samba-узла ещё нет пользовательских ресурсов.

Результат	Действие администратора
Контейнеры не `healthy`	Проверьте `ps`, наличие файлов и права UID, тег образа, соответствие TLS-ключа сертификату. Не передавайте приватные ключи или пароли в отчётах.
Браузер не открывает HTTPS	Проверьте bind-адрес, порт, DNS, доверие цепочке и имя сертификата.
Неизвестный SSH-ключ	Сверьте отпечаток через доверенную консоль, добавьте ключ с точным host/port в `known_hosts`, затем пересоздайте только панель.
Изменённый SSH-ключ	Остановите попытки, выясните причину и независимо подтвердите новый ключ; порядок действий — в инструкции.
Файл доверия недоступен	Проверьте `SSH_KNOWN_HOSTS_FILE`, файловое подключение и чтение UID 10001; файл не должен быть каталогом.
Ошибка SSH-аутентификации или соединения	Проверьте контейнерный адрес/порт, пользователя, выбранный способ входа и настройки SSH-сервера; не меняйте доверенный ключ для исправления пароля или сетевой ошибки.

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

docker compose --env-file deploy/production/.env \
  -f docker-compose.production.yml up -d --no-deps --force-recreate --wait web

Для полного стека добавьте -f docker-compose.samba.yml перед up. Пересоздание web завершает текущие сессии панели, но не удаляет данные Samba.

Полный стек с Samba

Создайте отдельный ключ управления. Приватный ключ хранится у оператора и не подключается к контейнерам; публичный передаётся через Compose secret:

ssh-keygen -t ed25519 -N '' -f deploy/production/secrets/management

Не перезаписывайте существующий ключ. Пример создаёт отдельный ключ без passphrase, поддерживаемый текущей формой входа; храните приватный файл с правами 0600.

Затем выполните первый запуск узла и проверку его SSH-ключа: сначала пустой файл доверия и только samba-node, затем сверка fingerprint и запись ключа. После этого запустите панель:

bash scripts/production/run.sh --with-samba

Эквивалент запуска:

docker compose --env-file deploy/production/.env \
  -f docker-compose.production.yml -f docker-compose.samba.yml \
  up -d --build --wait

В форме входа укажите:

host: samba-node;
SSH port: 22;
username: root;
способ: SSH-ключ; содержимое приватного файла management.

Парольный SSH-вход выключен. SSH root-доступ ограничен изолированным Samba-контейнером; это административный доступ ко всему узлу, не разграничение ролей внутри приложения. Публичный ключ копируется в /run с владельцем root для проверки OpenSSH StrictModes. Ключи SSH-хоста создаются при первом запуске и сохраняются в томе состояния.

Общие папки и Samba-пользователи изначально отсутствуют: создайте их через панель. Пути общих папок в этом варианте ограничены /srv/samba. Подключение SMB-клиентов выполняется к адресу Docker-хоста, заданному в SAMBA_BIND_IP, а не к имени samba-node. Поддерживается прямой SMB на TCP 445; legacy NetBIOS-порты наружу не открыты.

Samba, SSH и опциональный winbind управляются Supervisor. Команды systemctl, используемые панелью, направляются совместимым скриптом к известным службам; полноценного systemd в узле нет. Проверка этого стека не подтверждает AD-присоединение, аудит ОС или совместимость с Astra Linux.

Данные и обновление

Именованные тома создаются с префиксом проекта sambryx-production:

Том	Содержимое
`node-identity`	`/etc`: пользователи, UID/GID, shadow, группы, SSH-ключи хоста, Samba-конфигурация и её копии.
`samba-state`	`/var/lib/samba`: база Samba-паролей, SID и постоянное состояние Samba.
`samba-data`	`/srv/samba`: файлы общих папок и их владельцы.
`samba-home`	`/home`: домашние каталоги созданных пользователей.
`samba-logs`	`/var/log/samba`: журналы Samba.

Все эти тома составляют один набор для резервного копирования. Папка с файлами без базы пользователей и SID недостаточна для восстановления доступа. Используйте согласованную резервную копию с остановленным Samba-узлом, защищайте её как содержащую пароли и ключи. При изменении имени Compose-проекта будут созданы новые тома: сохраняйте имя проекта или переносите данные явно.

Для обновления панели задайте новый SAMBRYX_IMAGE и выполните:

docker compose --env-file deploy/production/.env \
  -f docker-compose.production.yml pull web nginx
bash scripts/production/run.sh

Для полного стека последнюю команду выполняйте с --with-samba. После пересоздания приложения нужно войти заново: HTTP/SSH-сессии не являются постоянными данными.

Samba-образ собирается отдельно. Том /etc при пересоздании сохраняется целиком, поэтому новые package defaults из обновлённого Ubuntu-образа автоматически туда не попадут. Обновление Samba-образа требует резервной копии, проверки изменений конфигураций/PAM/NSS на стенде и контролируемой миграции. Не подключайте к этому тому другую версию ОС и не заменяйте его содержимое вслепую.

Остановка без удаления данных:

docker compose --env-file deploy/production/.env \
  -f docker-compose.production.yml -f docker-compose.samba.yml down

Не используйте down -v для рабочего стека: эта команда удаляет постоянные тома. При ротации сертификата или публичного SSH-ключа пересоздайте соответствующий контейнер, чтобы обновились файловые подключения secrets. Nginx ограничивает тело запроса 64 MiB; отдельные лимиты загрузки Spring Boot настраиваются независимо и могут быть ниже.

Проверка конфигурации и smoke-тест

./mvnw -B -f tools/smoke/pom.xml -Pproduction-smoke verify -Dit.test=ComposeModelIT

Проверки модели используют Docker Compose CLI без запуска контейнеров. Сквозной тест требует JDK 21, OpenSSL, ssh-keygen, Docker и локально подготовленные образы:

./mvnw clean package
docker build -t sambryx-ci:production .
docker pull nginx:1.30.6-alpine
docker build -t sambryx-samba-node:ubuntu24.04 deploy/production/samba
./mvnw -B -f tools/smoke/pom.xml -Pproduction-smoke verify \
  -Dsmoke.image=sambryx-ci:production

Тест создаёт уникальный Compose-проект с временными ключами и случайными loopback-портами. Он проверяет TLS, вход через настоящий SSH, CSRF, защищённую cookie, создание пользователя/ресурса, запись и чтение по SMB, перезапуск службы и сохранность данных после пересоздания. Затем через API создаётся backup конфигурации, меняется server string и выполняется restore: байты /etc/samba/smb.conf сверяются с копией, результат чтения API — с файлом, проверяется SMB. Проверяются оба публичных варианта restore endpoint. Для копии с недопустимым значением security настоящий testparm должен завершиться с ошибкой; restore должен вернуть HTTP 500 с success=false, сохранить байты действующего файла и PID smbd. После отказа повторяется чтение SMB.

Restore проверяет выбранную копию через testparm до safety backup, замены конфигурации и restart. Это проверка синтаксиса Samba, а не гарантия правильности любых настроек или восстановления всех томов. На стенде созданная API копия получает фиксированное синтетическое имя допустимого формата через docker compose exec: это исключает совпадение с именем safety backup с точностью до секунды. Коллизии имён при одновременных операциях и внешнее изменение файла между проверкой и копированием этот сценарий не проверяет. В конце удаляются только контейнеры, сети и тома этого тестового проекта. Образы остаются в кэше. Сертификат smoke-теста самоподписанный, доверие задаётся только локальному тестовому клиенту.