Установка и первое подключение

Подготовка компьютеров

Дистрибутивы Studio выпускаются для Linux x86_64/aarch64, macOS ARM64 и Windows 11 x86_64. Требуются Python 3.11 и новее, PostgreSQL 15 и новее. Astra Linux 1.8 — один из вариантов развёртывания. Готовый архив выбирают по архитектуре компьютера и версии Python: например, cp311 предназначен для Python 3.11. Требования к glibc определяются выбранной сборкой; Linux-установщик использует systemd. Примеры команд ниже приведены для дистрибутивов с пакетным менеджером apt.

Перед установкой запишите адреса машин, роли, порты и каталоги хранения. Проверьте свободное место, синхронизацию времени и доступ между компонентами. Для Historian учитывайте не только размер таблиц, но и индексы, журнал транзакций PostgreSQL (WAL), временные операции и резервные копии. Нагрузка Runtime зависит от числа тэгов, сложности скриптов, периодов опроса и протоколов.

python3 --version
systemctl --version
df -h
timedatectl status

Команды установки пакетов выполняет администратор ОС. В Debian-подобной системе требуются совместимые пакеты Python с venv и PostgreSQL. Проверьте имена пакетов и доступные версии в репозитории своей ОС. Не заменяйте системный Python вручную ради одного компонента.

Установка на Windows и macOS

Выберите архив своей ОС, архитектуры и версии CPython. Распакуйте его в отдельный каталог. Внутри находятся установщик и файл Install с полной последовательностью действий. Для Studio и Historian необходим PostgreSQL 15 или новее; для Runtime и HMI отдельная база PostgreSQL не требуется.

Windows 11 x86_64

Установите 64-разрядный Python для всех пользователей компьютера и Microsoft Visual C++ Redistributable x64. Откройте PowerShell от имени администратора в каталоге распакованного архива. Укажите путь к Python нужной версии:

.\install.ps1 -Python C:\Python313\python.exe

Настройте JSON-файлы в C:\ProgramData\SAMUTAG. Для Studio укажите подключение к PostgreSQL в Studio\studio.json. Затем активируйте установку:

.\install.ps1 -Python C:\Python313\python.exe -Activate

Пакет Servers позволяет выбрать отдельный компонент параметром -Services runtime, -Services hmi или -Services historian. Используйте тот же параметр при подготовке и активации. Службы samutag-studio, samutag-runtime, samutag-hmi и samutag-historian доступны в диспетчере служб Windows. Журналы находятся в папке logs каждого компонента.

macOS ARM64

Используйте нативный ARM64 Python. Минимальная версия macOS указана в manifest.json выбранного архива. Пример для Python, установленного через Homebrew:

sudo /opt/homebrew/bin/python3.13 -B install.py

Настройте JSON-файлы в /Library/Application Support/SAMUTAG, затем выполните:

sudo /opt/homebrew/bin/python3.13 -B install.py --activate

Для отдельного серверного компонента используйте --services runtime, --services hmi или --services historian. Службы запускаются через launchd от учётной записи _samutag. Например, состояние Runtime отображает команда sudo launchctl print system/ru.samutag.runtime.

На Windows и macOS Studio обслуживается веб-сервером Waitress; на Linux — Gunicorn. Перед обновлением Studio сохраните резервную копию её базы. Установщик сохраняет существующие настройки. Для сетевого доступа укажите адреса прослушивания и разрешите необходимые порты в настройках ОС.

Установка системных пакетов

Перед запуском готового дистрибутива SAMUTAG установите Python с поддержкой виртуальных окружений. PostgreSQL установите на компьютере, который будет хранить базы Studio или Historian.

1. Получите права администратора

Ниже команды для систем с apt. Если у пользователя есть права sudo, выполняйте их как показано. Если sudo отсутствует, выполните su -, введите пароль root и выполняйте команды без слова sudo. Устанавливать sudo только ради SAMUTAG не требуется.

2. Установите Python и утилиты

sudo apt update
apt-cache policy python3 python3-venv
sudo apt install python3 python3-venv bash passwd util-linux ca-certificates tar gzip
python3 --version
python3 -c "import venv, ensurepip; print('venv и ensurepip доступны')"
systemctl --version

python3-venv добавляет создание виртуального окружения для штатного Python системы. Пакет passwd предоставляет useradd, необходимую для создания служебного пользователя; util-linux — стандартные системные утилиты. ca-certificates содержит доверенные сертификаты, tar и gzip нужны для работы с архивами.

Версия Python должна быть не ниже 3.11 и совпадать с вариантом сборки. Например, архив cp311 требует Python 3.11, cp312 — Python 3.12. Если нужен Python 3.11, установленный отдельно от штатного python3, установите и его модуль venv:

sudo apt install python3.11 python3.11-venv
python3.11 -c "import sys, venv, ensurepip; print(sys.version)"

Этот пример применим, если пакеты доступны в репозитории вашей ОС. Для другой версии замените 3.11 в обеих командах. Если репозиторий предлагает Python ниже 3.11, используйте поддерживаемый вашей ОС источник пакетов или отдельный совместимый Python. Системный интерпретатор заменять не нужно.

3. Проверьте создание окружения

Проверка создаёт временное окружение, запускает его pip и автоматически удаляет временный каталог. Запускайте её тем Python, для которого выбран дистрибутив; при необходимости замените python3 на python3.11 или другую подходящую версию.

python3 - <<'PY'
import pathlib
import subprocess
import tempfile
import venv
with tempfile.TemporaryDirectory(prefix="samutag-venv-check-") as folder:
    venv.EnvBuilder(with_pip=True).create(folder)
    python = pathlib.Path(folder) / "bin" / "python"
    subprocess.run([str(python), "-m", "pip", "--version"], check=True)
print("Окружение готово")
PY

При ошибке ensurepip или venv установите пакет venv именно для выбранной версии Python. Отдельные системные пакеты python3-pip, python3-dev, компилятор и заголовки PostgreSQL для установки готового дистрибутива не требуются: библиотеки поставляются в архиве и устанавливаются в окружение службы.

4. При необходимости установите FFmpeg

На компьютере Studio можно установить FFmpeg заранее:

sudo apt install ffmpeg
ffmpeg -version

Либо подтвердите его установку при запуске install.sh. Без FFmpeg можно загружать новые аудиофайлы PCM WAV и импортировать готовый аудиокаталог. Runtime, HMI и Historian для установки своих служб FFmpeg не требуют.

Для установки системных пакетов нужен доступ к репозиторию ОС либо подготовленному локальному зеркалу. Готовый дистрибутив SAMUTAG содержит свои Python-зависимости; подключение к PyPI для их установки не требуется.

Установка PostgreSQL

Выполните эти действия на сервере баз данных. Если PostgreSQL 15 или новее уже установлен и работает, переходите к созданию ролей и баз. Studio и Historian могут использовать один сервер PostgreSQL, но разные базы и роли.

1. Проверьте версию пакетов в репозитории. Она должна соответствовать PostgreSQL 15 или новее.
2. Установите сервер и консольный клиент.
3. Включите службу и проверьте подключение.

sudo apt update
apt-cache policy postgresql postgresql-client
sudo apt install postgresql postgresql-client
sudo systemctl enable --now postgresql
pg_lsclusters
sudo -u postgres psql -c 'SHOW server_version;'
sudo -u postgres psql -c 'SELECT 1;'

Метапакет postgresql устанавливает версию, выбранную вашей ОС. Если она ниже 15, не используйте её для SAMUTAG. Установите доступную поддерживаемую версию из репозитория ОС; например, при наличии пакетов версии 15:

sudo apt install postgresql-15 postgresql-client-15

Для PostgreSQL 16 и новее используйте соответствующий номер пакета. Не устанавливайте несколько версий одновременно без необходимости. Если нужной версии нет в репозитории, воспользуйтесь инструкцией поставщика ОС; для поддерживаемых выпусков Debian доступна официальная инструкция PostgreSQL. Репозитории другой ОС нельзя подключать к Astra Linux без проверки совместимости.

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

systemctl status postgresql --no-pager
journalctl -u postgresql -n 100 --no-pager
pg_lsclusters

Если sudo отсутствует, откройте root-оболочку через su -. Команды apt и systemctl выполняйте без sudo, а проверку сервера — так:

su - postgres -c "psql -c 'SHOW server_version;'"
su - postgres -c "psql -c 'SELECT 1;'"

Если PostgreSQL находится на другом компьютере, локальный сервер на Studio или Historian не нужен. Для проверки соединения достаточно клиента:

sudo apt install postgresql-client

Далее создайте роли и базы на сервере PostgreSQL, разрешите соединения от нужных компьютеров и укажите его адрес в конфигурациях Studio и Historian.

Две базы PostgreSQL

Создайте разные роли и базы для Studio и Historian. В примере ниже это samutag_studio и samutag_historian. Имена произвольны, но затем их необходимо точно повторить в конфигурации. Роли приложений не должны иметь права суперпользователя.

На сервере PostgreSQL откройте psql от системного пользователя postgres через sudo. Для этого вашей учётной записи нужны соответствующие права sudo. Если роли и базы уже существуют, повторно создавать их не нужно.

sudo -u postgres psql
CREATE ROLE samutag_studio LOGIN;
\password samutag_studio
CREATE DATABASE samutag_studio OWNER samutag_studio;
CREATE ROLE samutag_historian LOGIN;
\password samutag_historian
CREATE DATABASE samutag_historian OWNER samutag_historian;
\q

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

Если sudo отсутствует, войдите как root командой su -, затем откройте ту же консоль:

su - postgres -c 'psql'

Выполните в ней SQL-команды из примера. Для остальных примеров с sudo -u postgres psql -c можно аналогично открыть эту консоль и ввести SQL-запрос после -c без внешних кавычек. Команда \q закрывает psql.

Найдите файл правил доступа и добавьте разрешения для нужных сочетаний базы, роли и адреса:

sudo -u postgres psql -c 'SHOW hba_file;'

host  samutag_studio     samutag_studio     127.0.0.1/32  scram-sha-256
host  samutag_historian  samutag_historian  127.0.0.1/32  scram-sha-256

Правила pg_hba.conf проверяются сверху вниз. Для удалённой службы вместо локального адреса 127.0.0.1 укажите её адрес; настройте listen_addresses и сетевой доступ PostgreSQL. Не используйте trust как средство устранения ошибки пароля и не открывайте базу всем адресам.

sudo -u postgres psql -c 'SELECT pg_reload_conf();'
psql -h 127.0.0.1 -U samutag_studio -d samutag_studio -W -c 'SELECT current_database(), current_user;'
psql -h 127.0.0.1 -U samutag_historian -d samutag_historian -W -c 'SELECT current_database(), current_user;'

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

Установка Studio из дистрибутива

1. Скопируйте каталог нужной версии из distrib/STUDIO целиком. Сохраните install.sh, bootstrap.py, gunicorn_config.py, архивы и файлы контрольных сумм.
2. Перейдите в каталог поставки. Архив программы вручную распаковывать не требуется.
3. Запустите установщик. От обычного пользователя он использует sudo, а при отсутствии sudo — su. От root повышение прав не нужно.

chmod +x install.sh
./install.sh

Мастер подбирает совместимый архив, проверяет его и запрашивает параметры. Укажите адрес и порт PostgreSQL, имя базы, роль и пароль. Далее задайте адрес прослушивания Studio, HTTP-порт и адрес, по которому пользователи будут открывать её в браузере.

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

systemctl status samutag-studio --no-pager
journalctl -u samutag-studio -n 100 --no-pager

Установщик применяет миграции Studio и запускает Gunicorn. Журнал установки находится в /var/log/samutag-install. После успешного обновления мастер предлагает удалить старые релизы; решение принимайте после проверки новой версии и наличия резервной копии.

studio.json и первый администратор

Стандартный каталог Studio — /opt/SAMUTAG/Studio. Основные настройки находятся в studio.json. Перед ручным изменением сделайте копию файла. JSON не допускает комментариев и лишней запятой после последнего поля.

Установщик предлагает создать первого администратора, если активного администратора ещё нет. Для отдельного создания или восстановления доступа используется команда управления из установленного релиза. Используйте учётную запись, имеющую доступ к конфигурации Studio; в типовой установке команда выполняется администратором ОС.

cd /opt/SAMUTAG/Studio/current
./venv/bin/python manage.py studiocreateadmin

Следуйте приглашениям команды и затем войдите через браузер. Если команда не может подключиться к базе, проверьте параметры подключения в studio.json. После изменения конфигурации службы выполните:

systemctl restart samutag-studio

Установка Runtime, HMI и Historian

Скопируйте каталог версии из distrib/SERVER и запустите его install.sh. Меню позволяет установить все компоненты либо выбрать Runtime, HMI или Historian отдельно. При размещении на разных машинах выберите для каждой нужные компоненты.

При первой установке создаются начальные файлы конфигурации. Замените их конфигурациями узлов своего проекта перед подключением служб. До первой загрузки проекта Runtime ожидает исполняемую конфигурацию. Для Historian необходимо указать действующую базу и применить конфигурацию истории.

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

systemctl restart samutag-runtime
systemctl restart samutag-hmi
systemctl restart samutag-historian
journalctl -u samutag-historian -n 100 --no-pager

Проверка подключения узлов

1. В свойствах узла укажите адрес, доступный со Studio. Если служба работает на другой машине, 127.0.0.1 для неё не подходит.
2. Сверьте UUID узла, роль, управляющий и диагностический порты с установленным JSON. На одном адресе порты разных служб не должны пересекаться.
3. Сверьте токен проекта. Отказ авторизации отличается от сетевого таймаута: в первом случае служба ответила, во втором ответ не получен вовремя.
4. Откройте просмотр узла в Studio. Проверьте версию, состояние, журнал и блок лицензии.
5. Для Historian проверьте готовность базы; для Runtime — успешную активацию после загрузки; для HMI — операторский адрес после загрузки видеокадров.

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