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

• 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); на нём установщик не останавливается, а печатает предупреждение WARN: протестировано на Debian 12; продолжаю… и идёт дальше. Это не разрешение: дальше вы в непроверенном окружении, и следующая же ошибка будет ваша. Жёстко установщик отказывает только не-Debian системам — строкой нужен Debian 12 (найдено: …). Образ:

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

Что увидите. Установщик проходит по шагам с печатью в терминал и в конце выводит блок с четырьмя строками, которые надо сохранить: адрес локальной панели по имени, адрес по IP, пароль входа в панель и MAC порта управления (пригодится сетевому администратору для резервации адреса).

После установки доступна команда synctwin-ctl. Ежедневно нужны шесть:

synctwin-ctl nics            # физические порты: какие свободны под EtherCAT
synctwin-ctl list            # какие станки (VM) развёрнуты и в каком состоянии
synctwin-ctl status <vm>     # состояние одного станка
synctwin-ctl doctor <vm>     # почему стенд не отвечает — цепочка проверок до первого обрыва
synctwin-ctl update <vm>     # обновить агента в госте (--check — только посмотреть)
synctwin-ctl panel-pass      # пароль локальной панели (--show | --reset)

Остальное — по случаю: start / stop / reset / delete <vm>, autostart <vm> on|off, stop-all, host-info, host-reboot, nic-release <порт>, mgmt-move, inventory <vm>, register <vm>.

synctwin-ctl doctor — первое, что стоит запустить, когда стенд «не виден». Он идёт по цепочке и печатает первое оборвавшееся звено, а не общий диагноз: «VM в состоянии …» · «гость не отвечает по ssh» · «node-agent не установлен — apt-get install synctwin-node-agent в госте» · «токена нет — стенд НЕ прописан» · «некуда звонить: в env нет AICNC_NODE_URL» · «облако со стенда не отвечает» · «журнал агента пуст» · «контроллер не поднят — норма, пока станок не запускали (launch поднимет)». Последняя строка — не поломка: так и выглядит здоровый свежий стенд.

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

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

Второй аргумент — имя физического порта из synctwin-ctl nics. Станку без EtherCAT (пока идёт только виртуальный прогон) вместо имени порта пишется none — VM поднимется без проброса.

Что VM получает по умолчанию

• память — 2048 МБ, меняется флагом --ram;
• ядра — 4 vCPU, меняется флагом --vcpus; какие именно ядра хоста отдать под реальное время, задаёт --cpus 2,4;
• системный диск — 20 ГБ, фиксирован;
• диск данных — 4 ГБ, отдельный и переживающий переустановку гостя;
• имя станка в платформе — --machine-name, если оно должно отличаться от имени VM.

Что увидите. Развёртывание идёт минутами: создаётся диск, гость грузится, получает адрес, ставит агента. По завершении synctwin-ctl list показывает VM в состоянии «работает», а synctwin-ctl doctor stand1 проходит цепочку до конца.

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

Если стенд в облаке так и не появился, его связь с платформой заводится явно: synctwin-ctl register stand1 --platform-url wss://…/ws/node --node-token <токен>. Признак именно этой причины — doctor обрывается на строке «токена нет — стенд НЕ прописан».

Тексты приведены дословно — по ним отказ и опознаётся в терминале.

При установке

• запусти через sudo: curl -fsSL … | sudo bash — команду запустили без root. Повторить с sudo.
• нужен Debian 12 (найдено: …) — система не Debian. Это жёсткий отказ: ставить бокс поверх Ubuntu, RHEL или Proxmox нельзя.
• WARN: протестировано на Debian 12; продолжаю… — Debian, но не 12. Установка продолжится, окружение непроверенное.
• не скачался base-образ — нет доступа в интернет с порта управления либо заблокирован наш адрес. Проверить ping -c3 synctwin.ru и прокси предприятия.

При развёртывании станка

• VM '<имя>' exists — 'delete' it first — станок с таким именем уже развёрнут. Либо другое имя, либо synctwin-ctl delete <имя>.
• guest never came up on the network (see /tmp/<имя>-console.log) — гость загрузился, но адрес не получил. Смотреть названный файл консоли: там видно, дошло ли до загрузчика и что ответил DHCP.

При освобождении порта под EtherCAT

Две проверки, которые спасают от потери связи с боксом, и обе снимаются флагом --force — снимайте, только если понимаете, чем платите:

• '<порт>' carries the DEFAULT ROUTE — releasing it kills internet. Move mgmt first (mgmt-move), or --force… — вы отдаёте под EtherCAT тот самый порт, через который бокс выходит в сеть. Сначала перенести управление: synctwin-ctl mgmt-move iface <другой порт>.
• '<порт>' is the interface toward THIS SSH session — releasing it locks you out. Connect via another path, or --force. — вы сидите по SSH через этот же порт. Отдадите — соединение оборвётся и вернуть его будет нечем, кроме монитора у бокса.

Порт возвращается в обычную сеть тем же инструментом: synctwin-ctl nic-release <порт> --restore, а --status показывает, кому порт сейчас принадлежит.

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

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). Забыли или хотите сменить — не лезьте в файл руками, для этого есть команда:

synctwin-ctl panel-pass --show     # показать текущий
synctwin-ctl panel-pass --reset    # выдать новый, действует сразу

Вход запоминается в браузере на 30 дней (cookie HttpOnly, SameSite=Lax).

Отказы этой команды: нет /etc/synctwin/box.env — бокс не установлен? (запустили не на боксе или установка не доехала) и (пароль не задан — панель пускает без входа). Второе — не косметика: пустой PANEL_PASS отключает вход целиком, и панель, которая управляет реальным железом, открыта любому в сети цеха. Увидели эту строку — задайте пароль через --reset.

Что в панели

• Статус — идентичность бокса и версия, ядра / 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-контур (ядро, контур управления, EtherCAT-мастер) — заморожен на провалидированном наборе версий и обновляется только сменой золотого образа, никогда «сам».

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