Установка бокса

• x86_64 ПК с аппаратной виртуализацией (Intel VT-x / AMD-V), от 4 ядер;
• сетевые порты: один для управления + по одному Intel-порту на каждый EtherCAT-станок;
• чистый Debian 12 (netinst достаточно), доступ в интернет при установке;
• права root (sudo).

Куда втыкать кабели

• Порт №1 (первый сетевой) — управление и интернет. В него — кабель от роутера или свитча с DHCP и выходом в интернет. Через этот порт бокс сам дозванивается до платформы; входящие подключения не нужны.
• Остальные порты — EtherCAT, один порт — один станок. Кабель из порта — во вход (IN) первого устройства EtherCAT-шины станка, дальше устройства соединяются цепочкой. Никаких свитчей и роутеров в EtherCAT-сегменте.
• Ёмкость: портов N → станков максимум N−1 — один порт всегда остаётся управлению. После установки synctwin-ctl nics покажет, какие порты свободны под EtherCAT.

порт 1 интернет / управление

порт 2 станок 1 (EtherCAT)

порт 3 станок 2 (EtherCAT)

порт 4 станок 3 (EtherCAT)

BIOS / UEFI

• включить аппаратную виртуализацию: Intel VT-x / AMD-V (в меню разных вендоров называется «Intel Virtualization Technology» или «SVM Mode»);
• включить IOMMU: Intel VT-d / AMD IOMMU — нужен для проброса EtherCAT-портов в VM станка;
• выставить загрузку с USB — понадобится на время установки.

На Intel-платформах после установки может понадобиться параметр ядра intel_iommu=on — установщик бокса сам подскажет при проверке окружения. Наш референс — AMD, там IOMMU работает из коробки.

Проверенная конфигурация

Референс, на котором мы гоняем стек: мини-ПК на Ryzen 7 6850H — три станко-VM одновременно, задержки RT-цикла <60 мкс (cyclictest), живая EtherCAT-шина на 6 устройств. Ориентир по памяти: VM станка по умолчанию получает 2 ГБ RAM (меняется опцией --ram), то есть 16 ГБ на бокс — комфортно для трёх станков. Для новых сборок рекомендуем (рекомендация, не жёсткое требование): 6+ ядер, 4 сетевых порта Intel i226/i210. Подробнее — Поддерживаемое железо.

Стек провалидирован на Debian 12 (bookworm) — нужен именно он. Текущий выпуск Debian — уже 13 (trixie), и установщик бокса его отвергнет, поэтому «просто свежий Debian» не подойдёт. Образ:

https://cdimage.debian.org/cdimage/archive/latest-oldstable/amd64/iso-cd/debian-12.15.0-amd64-netinst.iso

Контрольная сумма SHA256 — файл SHA256SUMS лежит в том же каталоге; проверка: sha256sum -c или сверить строку вручную:

cd4462c06aa8892e692c0c4b9c17802f38c8ab8690e85cbfb5ccaa5956e9af17  debian-12.15.0-amd64-netinst.iso

Записать на флешку

Windows — balenaEtcher или Rufus (режим DD); Linux / Mac — balenaEtcher или dd:

sudo dd if=debian-12.15.0-amd64-netinst.iso of=/dev/sdX bs=4M status=progress oflag=sync

Внимание: /dev/sdX — именно флешка (проверьте по lsblk): dd затирает указанный диск безвозвратно.

Установка

Перед запуском установщика воткните интернет-кабель в порт управления (порт №1, см. Шаг 1) — netinst тянет пакеты из сети, адрес получает по DHCP. Важные пункты в инсталляторе (остальное — по умолчанию):

• имя хоста — например box1, домен — пустой;
• пароль root оставить пустым — тогда Debian сам ставит sudo и выдаёт его первому пользователю; иначе sudo в системе не будет, и однострочник установки (Шаг 3) не запустится без ручной настройки;
• создать обычного пользователя — например oper;
• разметка диска: авто, весь диск, ext4;
• выбор ПО (tasksel): снять все галки Desktop, оставить только «SSH server» и «standard system utilities» — бокс работает headless, монитор нужен только на время установки.

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

ping -c3 synctwin.ru

Одна команда — ставит KVM/libvirt, скрипты оркестрации, базовый образ и box-agent (исходящее соединение к серверу, входящий SSH не нужен):

curl -fsSL https://synctwin.ru/install.sh | sudo bash

Хорошая практика — сначала посмотреть, что запускаете: curl -fsSL https://synctwin.ru/install.sh | less

После установки доступна команда synctwin-ctl:

synctwin-ctl nics     # физические порты: какие свободны под EtherCAT
synctwin-ctl list     # какие станки (VM) развёрнуты

Каждый станок — отдельная VM, привязанная к своему EtherCAT-порту. Развёртывание из «золотого» образа с зафиксированными версиями (RT-ядро, LinuxCNC, EtherCAT-мастер — версии заморожены, apt upgrade их не сдвинет):

synctwin-ctl deploy stand1 eno1   # имя VM + EtherCAT-порт

Внутри VM автоматически устанавливается node-agent — из нашего подписанного APT-репозитория, штатным deb-пакетом synctwin-node-agent. Агент дозванивается до платформы сам; стенд появляется в интерфейсе управления.

После установки на самом боксе поднимается локальная веб-панель — откройте в браузере с любого устройства в той же сети цеха. Два адреса, пробуйте по порядку — оба печатаются в конце установки:

1) http://<имя-бокса>.local     по имени — не зависит от смены адреса
2) http://<ip-бокса>            по адресу — если имя не открылось

По имени — короткий путь: бокс отвечает на своё имя в локальной сети (mDNS), и ссылка не ломается, когда роутер выдаст боксу другой адрес. Работает из macOS, Windows 10/11 и Linux с avahi.

По адресу — если имя не открывается. Так бывает в строгих корпоративных сетях: включён VPN, служебные политики блокируют mDNS, домен предприятия сам занимает суффикс .local, или ноутбук и бокс в разных подсетях. IP — адрес порта управления (порт №1), его выдаёт ваш роутер; на боксе виден командой ip -4 addr, а в облаке — в списке «Мои боксы».

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

Адрес выдан по DHCP и однажды сменится. Чтобы ссылка на панель держалась годами, попросите сетевого администратора закрепить адрес за боксом (резервация в DHCP по MAC). Всё, что ему нужно — имя, порт, MAC и текущий адрес — установщик печатает отдельной строкой в конце установки.

Вход по паролю

Панель закрыта страницей входа. Пароль генерируется установщиком и печатается в конце установки — строка «Пароль входа». Он хранится на самом боксе в /etc/synctwin/box.env (переменная PANEL_PASS): забыли — посмотрите там; хотите сменить — отредактируйте значение, новый пароль действует сразу. Вход запоминается в браузере (cookie) на 30 дней.

Что в панели

• Статус — идентичность бокса и версия, ядра / RT-изоляция / память / загрузка, привязка к платформе (привязан / не привязан / нет связи), последний обмен с сервером.
• Станки (VM) — список станков-виртуалок с состоянием; пуск, остановка, жёсткий сброс зависшего гостя, автозапуск с боксом.
• Стенд — живая картина станка прямо с шины: слейвы EtherCAT и текущие координаты (DRO) читаются с бокса без облака, чтобы наладчик у железа сразу видел, что на стенде происходит.
• Сеть — порт-карта (интернет / свободен / отдан в EtherCAT / управление); освобождение порта под EtherCAT и возврат в обычную сеть.

Панель управляет реальным железом (VM, сетевые порты), поэтому держите её в доверенной сети цеха. Разрушающие действия — сброс VM, освобождение порта, перезагрузка бокса — требуют явного подтверждения.

Удалённая поддержка

В разделе «Статус» есть кнопка «Подключиться к поддержке». По нажатию бокс сам открывает временный защищённый канал к инженеру SyncTwin — входящий доступ к боксу не нужен, ничего пробрасывать наружу вручную не требуется. Канал живёт только пока вы держите его включённым: нажали «Отключить» — доступ закрылся, перезагрузка бокса тоже его снимает.

Пакеты SyncTwin распространяются из подписанного репозитория. Подлинность каждого пакета проверяет сам APT по GPG-подписи — подменённый пакет установить нельзя.

curl -fsSL https://synctwin.ru/synctwin-archive-keyring.gpg \
  -o /usr/share/keyrings/synctwin-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/synctwin-archive-keyring.gpg] https://synctwin.ru/apt ./" \
  | sudo tee /etc/apt/sources.list.d/synctwin.list
sudo apt update && sudo apt install synctwin-node-agent

Ключ подписи: SyncTwin Package Signing <packages@synctwin.ru>, отпечаток B435 EDAE 1B8E EC2C FA45  BFB2 F41E D693 10A2 F748. Текстовая версия ключа: synctwin-archive-key.asc.

• Скрипты бокса — box-agent сверяет версию с сервером и обновляет их сам;
• node-agent в VM — обычный apt install synctwin-node-agent из репозитория;
• RT-контур (ядро, LinuxCNC, EtherCAT-мастер) — заморожен на провалидированном наборе версий и обновляется только сменой золотого образа, никогда «сам».

Вопросы по установке или железу — напишите нам.