Мост и агенты на своей инфраструктуре

Свежие версии агента, установщики и обновления самого моста могут подтягиваться с официального канона: интернет для этого нужен только серверу моста. Машинам парка внешняя сеть не требуется.

01Обзор

Серверная часть парка состоит из двух компонентов, которые разворачиваются на вашей инфраструктуре:

Мост раздает по своему порту 7480 публичный каталог: установщики install.sh и install.ps1, дистрибутивы агента и свой корневой сертификат ca.crt. Агенты, установленные с этого моста, доверяют именно его центру сертификации: у каждого моста собственный изолированный центр.

Установщик install-bridge.sh выполняет всю работу идемпотентно: первый запуск создает центр сертификации, секреты и службу, повторный обновляет бинарник моста и файлы раздачи, сохраняя сертификаты, токен, коды и журнал.

Две схемы развертывания

• Канон, источник истины: мост сам раздает дистрибутивы и обновления, так работает публичный сервис. Адрес канона пуст, сверка выключена;
• Локальный мост в изолированной сети: ставится с указанием канона, периодически сверяется с ним и раздает агентам свежие версии, не выпуская парк в интернет.

Публичная страница любого моста на порту 7480 показывает готовые команды установки агентов под адрес этого моста.

02Требования

• Linux x86_64 (amd64) для моста и веб-консоли: в раздаче лежит только linux-amd64. Для arm64 (Raspberry Pi и подобное) собирается лишь агент. Дистрибутивы статические, glibc не нужна. Рекомендуемые системы: Ubuntu или Debian, Rocky или Alma, CentOS Stream, openSUSE;
• права суперпользователя или sudo;
• система инициализации systemd: установщик создает службу office-admin-bridge и таймер самообновления office-admin-bridge-selfupdate.timer;
• утилиты curl, openssl, awk, sed, sha256sum;
• открытые входящие порты: 7443 (агенты парка), 7480 (раздача установщиков) и 7444 (веб-консоль оператора, ставится по умолчанию);
• лицензионный ключ моста: без него мост не выдает сертификаты новым машинам и не пускает в программный интерфейс, кроме ввода самого ключа (глава 03);
• желательно постоянное имя в домене или стабильный сетевой адрес: агенты запоминают адрес моста при установке;
• при сверке с каноном нужен исходящий доступ к нему по HTTP (глава 09).

Отдельный сервер не нужен: мост состоит из одного небольшого статического бинарника без внешних зависимостей, база встроена. Подойдет минимальный сервер на 1 ядро и 512 МБ памяти.

03Установка одной командой

Установщик скачивается с официального источника дистрибутивов, файлы для агентов берутся с того же зеркала (переменная OA_MIRROR, по умолчанию официальное зеркало, глава 04):

curl -fsSL http://sa-projects.ru:7480/install-bridge.sh \
  | sudo OA_MIRROR=http://sa-projects.ru:7480 bash

Если OA_MIRROR не задан, используется официальное зеркало по умолчанию. Адрес канона для периодической сверки задается отдельно, переменной OA_UPSTREAM: по умолчанию он совпадает с зеркалом, а пустая строка означает, что этот мост сам источник истины.

Что делает скрипт

• создает системного пользователя office-admin и каталог /etc/office-admin с правами 0700;
• если центра сертификации еще нет, генерирует собственный центр и сертификат моста через openssl: имя постоянное (office-bridge), а список адресов собирается из localhost, 127.0.0.1, имени хоста, локальных адресов интерфейсов, плюс заданные OA_DNS и OA_IP;
• создает bridge.yaml: случайный токен администратора, код подключения и адрес канона;
• скачивает бинарник моста с зеркала и сверяет его по sha256sums.txt;
• копирует установочные файлы агентов в публичный каталог /etc/office-admin/install/ и кладет туда свой ca.crt;
• ставит и запускает службу office-admin-bridge;
• ставит системный таймер office-admin-bridge-selfupdate.timer: он проверяет маркеры обновления и подменяет бинарники моста и веб-консоли, после чего перезапускает нужную службу. Сам мост прав на /usr/local/bin не имеет;
• проверяет программный интерфейс запросом списка агентов с токеном и печатает итог: токен, код подключения, режим сверки, команды добавления агентов, напоминание про лицензию и правила межсетевого экрана;
• ставит рядом веб-консоль, рабочее место оператора на порту 7444, чтобы сразу управлять агентами. Отключается переменной OA_CONSOLE=0, если нужен только узел раздачи.

sudo /usr/local/bin/office-bridge license -config /etc/office-admin/bridge.yaml -set 'SA1-XXXXX-…'
sudo /usr/local/bin/office-bridge license -config /etc/office-admin/bridge.yaml -show

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

Все параметры задаются переменными окружения перед командой, все необязательные:

Пример: мост на других портах, со своим кодом и именем в домене.

sudo OA_LISTEN=0.0.0.0:8443 OA_PUBLIC=0.0.0.0:8480 \
  OA_CODE=office-2026:servers OA_DNS=bridge.mycompany.ru \
  bash -c "$(curl -fsSL http://sa-projects.ru:7480/install-bridge.sh)"

Обратите внимание: адрес моста, который будет указан в команде установки агентов, обязан присутствовать в списке имен сертификата (глава 11).

05Структура на сервере

Все, что создает мост, лежит в /etc/office-admin и принадлежит пользователю office-admin:

06Подключение агентов

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

• OA_BASE адрес раздачи другого узла, например http://bridge.mycompany.ru:7480. Нужен только если файл раздается с зеркала или прокси: установщик сам выведет адрес защищенного канала, тот же хост и порт 7443;
• OA_CODE код подключения. Нужен, если у моста несколько кодов с разными группами: после первого подключения агент получает собственный сертификат, и код больше не нужен.

Linux

curl -fsSL http://bridge.mycompany.ru:7480/install.sh | OA_CODE=<код> bash

Явный вариант, с кодом и без конвейера, в системном режиме:

curl -fsSL http://bridge.mycompany.ru:7480/install.sh -o /tmp/install.sh
sudo OA_CODE=ваш-код bash /tmp/install.sh

Windows

Командная оболочка от имени администратора:

$env:OA_CODE="<код>"; irm http://bridge.mycompany.ru:7480/install.ps1 | iex

После установки машина появляется в журнале моста: группа из кода подключения, имя агента совпадает с именем хоста машины. Посмотреть подключенных агентов:

curl -sk https://127.0.0.1:7443/api/admin/agents \
  -H "Authorization: Bearer ВАШ_ТОКЕН"

07Проверка и журнал

Статус службы

systemctl status office-admin-bridge
systemctl restart office-admin-bridge   # при необходимости

Журнал: что делает мост

journalctl -u office-admin-bridge -f      # следить
journalctl -u office-admin-bridge -n 50   # последние 50 строк

Проверка интерфейса и раздачи

# защищенный канал отвечает кодом 200 с токеном
curl -sk -o /dev/null -w '%{http_code}\n' https://127.0.0.1:7443/api/admin/agents \
  -H "Authorization: Bearer ВАШ_ТОКЕН"

# публичный каталог отдает файлы
curl -s http://127.0.0.1:7480/versions.json | head
curl -s http://127.0.0.1:7480/ca.crt | openssl x509 -noout -subject

Итоговая диагностика, все сразу:

journalctl -u office-admin-bridge -n 30 --no-pager && \
  ss -ltnp | grep -E '7443|7480|7444'

08Сеть и межсетевой экран

Ubuntu и Debian:

sudo ufw allow 7443/tcp comment 'агенты парка'
sudo ufw allow 7480/tcp comment 'раздача установщиков'
sudo ufw allow 7444/tcp comment 'веб-консоль оператора'
sudo ufw reload

Rocky и CentOS:

sudo firewall-cmd --permanent --add-port=7443/tcp --add-port=7480/tcp --add-port=7444/tcp
sudo firewall-cmd --reload

В облаке дополнительно откройте порты в правилах группы безопасности. Порт 7480 отдает страницу-портал моста с готовыми командами установки, установочные файлы и корневой сертификат: после того как парк развернут, его можно закрыть и открывать по мере необходимости.

Если включена сверка с каноном (глава 09), мост сам ходит исходящим HTTP к канону, по умолчанию раз в минуту (минимум 30 секунд, период задается OA_UPSTREAM_SEC и параметром upstream_sec), то есть на сверку хватает одного исходящего запроса и входящие порты для этого не нужны. При полностью закрытом контуре оставьте адрес канона пустым, и мост будет источником истины.

09Обновление и перенос

Обновление моста

Есть два пути. Автоматически: если задан адрес канона, мост раз в заданный период сверяет свою раздачу с каноном и скачивает новые версии агента, установщики и обновление самого себя. Готовые бинарники кладутся в каталог раздачи, а маркеры обновления — рядом с базой, в /etc/office-admin: системный таймер раз в минуту проверяет маркер, сверяет контрольную сумму и подменяет бинарник моста, после чего перезапускает службу. Так же обновляется и веб-консоль: если она стоит на этом же хосте, мост оставляет маркер .console-update, и тот же таймер подменяет office-console и перезапускает ее. Руками делать ничего не нужно.

Библиотеки обновлений мост берет с канона вместе с подписью издателя (manifest.sig) и сверяет их с контрольными суммами; режим проверки задается параметром update_sig: auto — принимать канон без подписи с предупреждением в журнале, strict — только подписанное, off — не проверять. Состояние проверки видно в статусе сверки полем sig.

Вручную: повторно запустите ту же команду установки (глава 03). Скрипт переиспользует центр сертификации, токен, коды и журнал, обновит бинарник и файлы раздачи. Агенты в обоих случаях продолжают работать без переустановки.

Статус сверки

Адрес канона, время последней сверки и ожидающее обновление моста:

curl -sk https://127.0.0.1:7443/api/admin/upstream \
  -H "Authorization: Bearer ВАШ_ТОКЕН"

Форсировать сверку: запрос POST /api/admin/upstream/sync. Для канона он вернет код 409, потому что сверка выключена.

Перенос на другой сервер

1. остановите службу: sudo systemctl stop office-admin-bridge;
2. упакуйте состояние: sudo tar -C /etc -czf office-admin-backup.tgz office-admin;
3. на новом сервере распакуйте архив в /etc, при необходимости верните владельца: chown -R office-admin:office-admin /etc/office-admin;
4. запустите установщик: он подхватит существующую конфигурацию и центр сертификации, пересоздаст бинарник, службу и права (глава 03).

Если меняется адрес или имя хоста, добавьте новое имя в сертификат (глава 11) и переустановите агентов: они запоминают адрес моста при установке.

Резервное копирование

Достаточно архивировать один каталог /etc/office-admin: конфигурацию, сертификаты и журнал. Восстановление: распаковка архива и повторный запуск установщика.

10Консоль рядом с мостом

Консоль: рабочее место оператора. Список машин с живой сводкой, чат с ИИ на русском, подтверждение строгих задач, снимок экрана активного сеанса и заявки «Помощь» по Ctrl+Alt+H. Мост принимает агентов и ведет журнал, консоль читает его программный интерфейс и выполняет задачи через него.

Установка рядом с мостом

Мост ставится с нашего канона — там свежие версии и подписанные контрольные суммы (если вы не переопределили источник переменной OA_MIRROR). Агентов потом раздает уже ваш мост. Консоль на тот же сервер, где стоит мост, ставится одной командой с самого моста:

curl -fsSL http://АДРЕС-МОСТА:7480/install-console.sh | sudo bash

Скрипт берет со своего моста бинарник консоли и сверяет его по sha256sums.txt. Если мост еще не раздаёт консоль, он сначала просит мост синхронизироваться с каноном (POST /api/admin/upstream/sync), и файл появляется в раздаче. Дальше скрипт берет из bridge.yaml адрес моста и токен администратора, ставит службу office-console на порт 7444 и прописывает свой адрес в портал: на странице моста появляется кнопка «Войти в консоль».

Ту же команду с адресом моста печатает и сам мост на порту 7480 в разделе «Консоль». Для консоли на другом хосте нужны адрес моста и его токен:

curl -fsSL http://АДРЕС-МОСТА:7480/install-console.sh \
  | sudo OA_BASE=http://АДРЕС-МОСТА:7480 OA_TOKEN=ТОКЕН bash

В изолированном контуре без интернета все файлы берутся с вашего моста: внешняя сеть нужна только ему самому, для сверки с каноном.

Вход

Пароль входа по умолчанию совпадает с токеном администратора моста, он же ключ доступа к интерфейсу. Свой пароль задается при установке переменной OA_PASSWORD. Консоль хранит сессии, чаты и реестр провайдеров модели в /etc/office-admin/console.db.

Провайдер модели

На стартовой странице консоли есть кнопка «Провайдеры ИИ»: добавьте облачный сервис с ключом и моделью или локальный сервер, например Ollama. Пока провайдер не добавлен, чат отвечает просьбой его настроить. Запросы к модели идут с сервера консоли, а не с машин парка, поэтому машинам интернет не нужен.

Файлы и служба

Доступ и обновление

Откройте адрес моста на порту 7444 и при первом запуске разрешите порт 7444 (глава 08). Обновление консоли: повторный запуск той же команды. конфигурация, пароль, база и настройки модели сохраняются. Нужен HTTPS, ставьте с переменной OA_TLS=1: сертификат выпустит центр моста, браузер будет предупреждать о неизвестном центре, пока ca.crt не импортирован как доверенный.

11Сертификаты и имена

Как устроен центр сертификации моста

• при первой установке мост генерирует собственный центр и сертификат моста, подписанный этим центром; срок действия центра 10 лет;
• в сертификат попадают localhost, 127.0.0.1, имя хоста сервера и все, что передано в OA_DNS и OA_IP;
• агент при подключении получает клиентский сертификат от центра моста, срок задается параметром cert_days, по умолчанию 365 дней;
• агенты доверяют мосту через ca.crt, который мост кладет в свой публичный каталог.

Правило имен

Адрес, по которому агенты ходят на мост, обязан присутствовать в сертификате моста, иначе агент отвергнет соединение. Поэтому имя в домене или внешний адрес задается при первой установке через OA_DNS и OA_IP.

Перевыпуск сертификата моста без смены центра

Если нужно добавить имя уже после установки, агенты не пострадают: центр остается тем же.

# новый ключ и запрос на сертификат
sudo openssl req -newkey rsa:2048 -nodes \
  -keyout /etc/office-admin/server.key \
  -out /tmp/server.csr -subj "/CN=office-bridge"

# подпись своим центром с нужным списком имен
sudo openssl x509 -req -in /tmp/server.csr \
  -CA /etc/office-admin/ca.crt -CAkey /etc/office-admin/ca.key \
  -days 825 -sha256 \
  -extfile <(printf 'subjectAltName=DNS:localhost,DNS:bridge.mycompany.ru,DNS:%s,IP:127.0.0.1\n' "$(hostname)") \
  -out /etc/office-admin/server.crt

sudo rm -f /tmp/server.csr
sudo chown office-admin:office-admin /etc/office-admin/server.key /etc/office-admin/server.crt
sudo systemctl restart office-admin-bridge

12Безопасность

• Токен администратора: ключ доступа к программному интерфейсу моста. Храните его в менеджере паролей и не передавайте в открытом виде. При утечке замените в bridge.yaml и перезапустите службу;
• Код подключения нужен агенту один раз. После подключения агент работает по собственному клиентскому сертификату, коды можно менять и добавлять в конфигурации;
• Порт 7480 ограничьте доверенными подсетями или открывайте только на время установки (глава 08);
• Ключ центра никогда не покидает сервер и не раздается;
• служба работает под непривилегированным пользователем office-admin с ограничениями файловой системы и запретом повышения прав;
• регулярно обновляйте мост повторным запуском установщика (глава 09);
• наблюдайте за журналом службы: там видны подключения новых машин и ошибки.

При подозрении на компрометацию: остановите службу, удалите /etc/office-admin, переустановите мост с новым центром и секретами, затем переустановите агентов с новым кодом подключения.

13Агент на Linux и Windows

Агент собирается под Linux (x86_64 и arm64, статический бинарник, glibc не нужна) и под Windows (x86_64, от Windows 7 SP1 до 11 и Windows Server). Установщик на Windows работает в PowerShell 2.0 и новее, то есть на тех же системах, где уже стоит служба агента.

Linux

Без прав root установка выполняется в пользовательском режиме, с sudo ставится системная служба. sudo не обязателен, но нужен для системного режима и самообновления. Имя агента по умолчанию совпадает с именем хоста машины, при желании задается явно:

curl -fsSL http://bridge.mycompany.ru:7480/install.sh | OA_NAME=web-01 bash

Для системного режима переменные передаются перед оболочкой после скачивания файла, потому что флаг sudo -E может быть запрещен политикой:

curl -fsSL http://bridge.mycompany.ru:7480/install.sh -o /tmp/install.sh
sudo OA_NAME=web-01 OA_CODE=ваш-код bash /tmp/install.sh

Windows

Запустите командную оболочку от имени администратора: установка регистрирует службу Windows и требует прав администратора, из обычного окна система откажет.

$env:OA_NAME = "web-01"
$env:OA_CODE = "<код>"
irm http://bridge.mycompany.ru:7480/install.ps1 | iex

Запуск службы под учетной записью

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

Самообновление

Агенты периодически сверяются с каталогом раздачи моста (versions.json) и обновляют себя сами, когда там появляется версия новее установленной: мост предлагает файл, агент скачивает его со своего моста и сверяет sha256 с манифестом, а с версии 0.1.54 дополнительно проверяет подпись издателя и откатывается, если она не сходится. Отдельного подтверждения от оператора не требуется: обновление идет по парку само. Чтобы обновить каталог раздачи, дождитесь сверки с каноном или перезапустите установщик моста (глава 09).

14Если что-то не так

Мост не запускается

Смотрите причину: journalctl -u office-admin-bridge -n 50 --no-pager. Чаще всего порт занят (проверьте ss -ltnp | grep 7443 и смените OA_LISTEN) либо неверные права на файлы сертификатов: они должны принадлежать office-admin.

Агент не подключается

• порт 7443 не открыт на мосту (глава 08): проверьте ss -ltnp и правила межсетевого экрана;
• адрес в команде агента не совпадает с именем из сертификата (глава 11): используйте имя из списка или перевыпустите сертификат;
• на машине агента неверное время: взаимная проверка сертификатов чувствительна к расхождению часов;
• неверный или уже использованный код подключения. Возьмите свежий: он в выводе установщика или в bridge.yaml. Признак именно этого: ошибка enroll: HTTP 401 и сообщение о неверном коде. Коды у каждого моста свои, а в конвейере переменная принадлежит первой команде, поэтому переустановите из файла: curl -fsSL http://<мост>:7480/install.sh -o /tmp/i.sh, затем sudo OA_CODE=<код с портала> bash /tmp/i.sh.

Интерфейс отвечает 401

Неверный токен администратора в заголовке авторизации. Возьмите актуальный из /etc/office-admin/bridge.yaml.

Интерфейс отвечает 402 (license_expired)

• лицензионный ключ не введен, истек или выпущен для другого моста: статус и причина видны в ответе в поле error, а отпечаток этого моста — в консоли, «Настройки» → «Лицензия»;
• пока ключ не принят, отвечает только ввод ключа: агенты получают 402, повторяют опрос и сами возвращаются в строй после активации;
• часы сервера убежали вперед и вернулись: мост держит максимальное виденное время, поэтому откат часов на сервере ловится как ошибка лицензии (clock_bad) — верните точное время.

Публичный каталог пуст или устарел

Повторно запустите установщик: он заново скопирует файлы агентов с зеркала и положит свой ca.crt. Права каталога install: владелец office-admin, 0755.

Агент старый и не обновляется

Проверьте versions.json в каталоге раздачи и журнал моста. Если у моста задан адрес канона, новые версии подтянутся сами (глава 09). Для канона обновите каталог перезапуском установщика моста. Убедитесь, что машины видят раздачу своего моста, порт 7480.

Нет сверки с каноном

• адрес канона и время последней сверки: GET /api/admin/upstream (глава 09);
• адрес пуст, значит мост считает себя источником истины и сверки нет;
• нет исходящего доступа к канону (глава 08) либо не сошлась контрольная сумма: смотрите журнал службы;
• период сверки не меньше минимума: upstream_sec от 30 секунд.

Мост или консоль не обновляются сами

• проверьте таймер: systemctl status office-admin-bridge-selfupdate.timer и журнал office-admin-bridge-selfupdate;
• маркеры обновления: .bridge-update для моста и .console-update для консоли в каталоге /etc/office-admin, строка вида «контрольная сумма, версия, файл»;
• маркер консоли появляется только если на этом хосте есть служба office-console: консоль на другом сервере обновляется повторным запуском ее установщика на нем;
• если контрольная сумма не сходится, таймер не подменяет бинарник: файл поврежден, дождитесь следующей сверки;
• статус ожидающих обновлений: GET /api/admin/upstream, поля bridge_update_pending и console_update_pending.

15Что дальше

1. Установите мост (глава 03) и сохраните токен администратора и код подключения;
2. добавьте первые машины командами из главы 06;
3. проверьте подключение запросом из главы 06 и журналом службы (глава 07);
4. настройте обновления (глава 09) и регулярные резервные копии каталога /etc/office-admin.