Эталонное развертывание Managed Agent

Эталонный дистрибутив Managed Agent носит экспериментальный характер. Принятая начальная топология: одна управляющая плоскость Java и встроенный Runtime Broker на одном доверенном Linux-хосте, одна база данных MySQL и один совместимый Qwen Hosted Harness. Манифест совместимости в каждом релизе является авторитетным для этого релиза.

Проверка и распаковка

Загрузите архив, отдельный манифест и SHA256SUMS.txt из одного и того же GitHub-пререлиза. Проверьте их перед распаковкой:

sha256sum --check SHA256SUMS.txt
tar -xzf qwen-managed-agent-reference-<version>.tar.gz
cd qwen-managed-agent-reference-<version>
sha256sum --check SHA256SUMS

Изучите manifest.json. Убедитесь, что source.revision — это проверенная ревизия, compatibility.qwenCodeVersion совпадает с установленной версией CLI/Harness, а compatibility.databaseSchema.latestMigrationVersion приемлема для целевой базы данных. Релиз считается недействительным, если какая-либо проверка контрольных сумм или совместимости не пройдена.

Предварительные требования

• Linux на доверенном хосте приложений.
• JDK 21 или новее.
• Node.js, соответствующая compatibility.node, и Qwen Code, соответствующая compatibility.qwenCodeVersion.
• MySQL 8 с пустой базой данных или базой данных, ранее управляемой более старой совместимой эталонной сборкой.
• Закрытые, постоянные каталоги для состояния Runtime и авторизованного рабочего пространства.
• Стабильные учетные данные базы данных, связка ключей учетных данных Runtime и токен Harness, хранящиеся отдельно от архива.

Java-архив не содержит npm CLI. Установите или соберите точную совместимую ревизию Qwen Code отдельно и укажите путь к dist/cli.js для воркеров Runtime.

Запуск Hosted Harness

Выберите один токен и дайджест возможностей и передайте те же значения Harness и Java-сервису:

export QWEN_MANAGED_AGENT_HARNESS_TOKEN='<private-random-token>'
export QWEN_MANAGED_AGENT_CAPABILITY_DIGEST='sha256:<64-hex-digest>'
 
QWEN_SERVER_TOKEN="$QWEN_MANAGED_AGENT_HARNESS_TOKEN" \
QWEN_HOSTED_HARNESS_CAPABILITY_DIGEST="$QWEN_MANAGED_AGENT_CAPABILITY_DIGEST" \
qwen serve --profile hosted-harness --port 4170 --hostname 127.0.0.1 --no-web

Оставьте Harness на loopback. Запишите порт, который он сообщает; --port может увеличиться, если запрошенный порт уже занят.

Запуск управляющей плоскости Java

В другом терминале настройте тот же Harness и базу данных:

export SPRING_DATASOURCE_URL='jdbc:mysql://127.0.0.1:3306/qwen_managed_agent'
export SPRING_DATASOURCE_USERNAME='qwen'
export SPRING_DATASOURCE_PASSWORD='<private-password>'
export QWEN_MANAGED_AGENT_HARNESS_ENABLED='true'
export QWEN_MANAGED_AGENT_HARNESS_BASE_URL='http://127.0.0.1:4170'
export QWEN_MANAGED_AGENT_HARNESS_TOKEN='<private-random-token>'
export QWEN_MANAGED_AGENT_CAPABILITY_DIGEST='sha256:<64-hex-digest>'
 
bin/qwen-managed-agent-server

Лаунчер использует серверный JAR из этого архива. Spring Flyway применяет прямые миграции базы данных перед тем, как сервис станет готов. Дождитесь:

curl --fail http://127.0.0.1:8080/actuator/health

Эта базовая конфигурация поддерживает текстовые Hosted-сессии. Оставьте слушатель на loopback, если не настроен подписанный или аутентифицированный вход. Полная конфигурация аутентификации, API и возможностей содержится в docs/server-reference.md.

Включение принятого пути выполнения инструментов на локальном процессе

Выполнение инструментов требует существующей настройки Runtime и рабочего пространства с fail-closed. Как минимум, настройте:

export QWEN_MANAGED_AGENT_RUNTIME_BROKER_ENABLED='true'
export QWEN_MANAGED_AGENT_RUNTIME_BROKER_TOKEN='<private-random-token>'
export QWEN_MANAGED_AGENT_RUNTIME_CREDENTIAL_KEY_ID='reference-v1'
export QWEN_MANAGED_AGENT_RUNTIME_CREDENTIAL_KEY='<base64-encoded-32-byte-key>'
export QWEN_MANAGED_AGENT_RUNTIME_STATE_DIRECTORY='/var/lib/qwen-managed-agent/runtime'
export QWEN_MANAGED_AGENT_NODE_EXECUTABLE='/usr/bin/node'
export QWEN_MANAGED_AGENT_RUNTIME_WORKER_ENTRY='/opt/qwen-code/dist/cli.js'
export QWEN_MANAGED_AGENT_WORKSPACE_ID='reference-workspace'
export QWEN_MANAGED_AGENT_WORKSPACE_CWD='/srv/qwen-workspace'
export QWEN_MANAGED_AGENT_RUNTIME_VERIFIED_WORKSPACE_RECOVERY_ENABLED='true'

Перед допуском работы с файлами, Shell или дочерними Git, выполните регистрацию нативного хранилища и проверку идентичности монтирования, описанную в разделе «Verified physical Workspace recovery» файла docs/server-reference.md. Незарегистрированное или неоднозначное монтирование должно оставаться недоступным. Публичная реклама Shell и возможностей v2 остается отключенной до завершения их отдельной квалификации.

Обновление

1. Загрузите и проверьте новый архив, прочитайте оба манифеста. Подтвердите новые требования Qwen Code/Harness, Java, протокола и базы данных до внесения изменений в работающее развертывание.
2. Остановите новый входной трафик. Дождитесь завершения допущенной работы согласно существующей процедуре дренирования развертывания.
3. Сделайте резервную копию MySQL, QWEN_MANAGED_AGENT_RUNTIME_STATE_DIRECTORY, полной связки ключей учетных данных Runtime и точного старого дистрибутива. Не ротируйте ключ учетных данных во время обновления.
4. Остановите Java-сервис и Hosted Harness. Сохраните рабочее пространство и долговременное состояние Runtime.
5. Установите совместимую версию Qwen Code/Harness по манифесту и запустите её с существующим токеном и дайджестом возможностей.
6. Запустите новый bin/qwen-managed-agent-server с теми же настройками базы данных и долговременными настройками. Flyway выполнит миграцию схемы вперед.
7. Дождитесь здорового ответа actuator, прочитайте существующую сессию и историю, затем выполните один новый ход без инструментов перед открытием входного трафика. Повторно квалифицируйте любую дополнительную возможность инструмента перед её включением.

Понижение версии базы данных не поддерживается. Если запуск или проверка не удались до возобновления трафика, исправьте конфигурацию и повторите попытку с тем же артефактом. Чтобы вернуться к версии, манифест которой имеет более старый диапазон схем, восстановите резервную копию базы данных и состояния Runtime до обновления вместе, прежде чем принимать любую новую запись; никогда не запускайте более старый сервер против мигрированной базы данных по предположению.

Ротация ключа учетных данных Runtime

Ротируйте ключ учетных данных отдельно от обновления дистрибутива. Сделайте резервную копию базы данных и текущих ключей, затем настройте новую активную пару и сохраните старую пару в previous-credential-keys:

qwen:
  managed-agent:
    runtime-broker:
      credential-key-id: reference-v2
      credential-key: <base64-encoded-32-byte-v2-key>
      previous-credential-keys:
        '[reference-v1]': <base64-encoded-32-byte-v1-key>

Оберните каждый ключ карты в [ ... ]. Spring relaxed binder нормализует обычные ключи — ID вида legacy/v1, legacy:v1 или legacy v1 связывается как legacyv1 независимо от того, заключен ли он в кавычки в YAML — поэтому связка ключей никогда не совпадает с сохранённым ID ключа, и строки, записанные с этим ID, остаются нечитаемыми, даже если ключ настроен. Форма в скобках сохраняет точный ID.

Перезапустите единую управляющую плоскость Java, убедитесь, что существующие привязки загружаются, и проверьте, что новые строки привязок записывают reference-v2. Новые секреты используют только активный ключ; старые строки остаются зашифрованными под их записанным ID ключа. Сервер не перешифровывает старые строки при чтении, а удаление всё ещё используемого ключа делает эти строки нечитаемыми.

Выводите reference-v1 из использования только тогда, когда ни одна сохранённая строка не ссылается на него. ma_runtime_binding.credential_key_id и ma_runtime_binding.runtime_credential_key_id — единственные сохранённые ссылки; обе хранят байты UTF-8. Выбирайте их без CONVERT, чтобы дедупликация оставалась побайтово точной, как и выбор ключа: преобразованное значение несёт стандартную колляцию набора символов и объединило бы два ID, различающихся только регистром или акцентом, скрыв ключ, на который строки всё ещё ссылаются.

SELECT DISTINCT credential_key_id AS key_id
FROM ma_runtime_binding WHERE credential_key_id IS NOT NULL
UNION
SELECT DISTINCT runtime_credential_key_id AS key_id
FROM ma_runtime_binding WHERE runtime_credential_key_id IS NOT NULL;

Результат перечисляет ID ключей, которые всё ещё требуются сохранёнными строками: ожидайте только активный ID (reference-v2). Пока присутствует reference-v1, этот ключ должен оставаться настроенным.

Связка ключей — это карта, и её нельзя передать через переменную окружения QWEN_MANAGED_AGENT_*: relaxed binding молча разрешает форму переменной окружения в пустую или неправильно ключеванную связку, без ошибки запуска. Настройте previous-credential-keys в application.yml, который процесс сервера действительно загружает. Эталонный дистрибутив не поставляется с конфигурационным файлом, и Spring разрешает внешний application.yml относительно рабочего каталога процесса (./ и ./config/), а не корня дистрибутива; bin/qwen-managed-agent-server передаёт свои аргументы JVM, поэтому --spring.config.additional-location=file:<absolute-path> фиксирует расположение. Развертывание, полагающееся только на переменные окружения, запускается с пустой связкой ключей, поэтому ротация credential-key-id без настройки предыдущего ключа делает строки, записанные с его использованием, нечитаемыми.

Точка входа восстановления оператором читает ту же активную пару и карту previous-credential-keys, что и сервер. Загрузите тот же внешний YAML для восстановления, например с помощью SPRING_CONFIG_ADDITIONAL_LOCATION=file:<absolute-path>/application.yml, и оставьте новый ключ активным, сохраняя при этом каждый ключ, на который всё ещё ссылается привязка. Основные приложения обслуживания CSI/миграции, включая зонд CSI Hosted, по-прежнему читают одну пару ключей учетных данных; запускайте эти точки входа с тем ключом, которым зашифрована их целевая привязка, в качестве активной пары.

После успешной настройки связки ключей сервер и точка входа восстановления логируют разрешённый активный ID и настроенные ID один раз на экземпляр протектора. Эти ID являются несекретными идентификаторами, уже хранящимися рядом с шифротекстом; диагностика экранирует управляющие и не-ASCII символы в JSON, сохраняет пробелы и регистр и никогда не включает ключевой материал, шифротекст или токены. Сравните настроенные ID с точными ID, возвращёнными запросом на вывод из использования, перед использованием ротированного развертывания. Ошибка недоступного ключа называет запрошенный, активный и настроенные ID, поэтому молча нормализованное или ошибочно введённое сопоставление может быть найдено без раскрытия секретов. Эта диагностика не доказывает, что каждая сохранённая строка может быть расшифрована.

Восстановление оператором

bin/qwen-managed-agent-operator-recovery запускает отдельно упакованную точку входа восстановления. Она отключена, если не установлено специфичное для восстановления окружение, и не запускает HTTP-сервис или воркер. Следуйте docs/hosted-workspace-recovery.md; никогда не делайте предположений о физической остановке и не удаляйте долговременные строки для обхода страховочного предела.

Границы области

Данная сборка не сертифицирует множественные управляющие плоскости Java, кросс-хостовый перехват, публичный CSI, вывод из эксплуатации Kubernetes, публичный Shell, рекламу v2 или стабильную производственную поддержку. Эти возможности требуют отдельных доказательств в релизе.