Среда выполнения Serve

Обзор

packages/cli/src/serve/ — это загрузочный слой для qwen serve. Он преобразует флаги CLI в ServeOptions, проверяет конфигурацию запуска, собирает приложение Express, подключает middleware, регистрирует маршруты, предоставляет провайдеры preflight/статуса для хоста демона, поддерживает кольцо аудита разрешений и управляет двухфазным процессом корректного завершения работы (graceful shutdown). Работа с HTTP находится в этом слое; работа с ACP находится на уровень ниже в @qwen-code/acp-bridge (см. 03-acp-bridge.md).

Обязанности

• Парсинг и валидация ServeOptions: адрес прослушивания, аутентификация, рабочее пространство (workspace), лимиты сессий/подключений, бюджет/пул MCP, CORS, таймауты простоя для промптов/SSE/сессий, rate limit и связанные переключатели.
• Канонизация основного рабочего пространства ровно один раз, а также канонизация каждого повторного --workspace перед регистрацией сессионных сред выполнения. Основная каноническая форма используется в /capabilities.workspaceCwd, fallback для POST /session и в основном bridge.
• Разрешение bearer: --token, затем QWEN_SERVER_TOKEN, затем — если ни один источник не задан и запрошенный --hostname не является loopback (буквальный localhost разрешается первым) — генерируется эфемерный 128-битный base64url bearer (22 символа), выводимый один раз при запуске. Loopback-записи никогда не генерируют токен и сохраняют доверенный режим без токена, если не установлен --require-auth. Генерация зависит от записи, а отказ при загрузке читает разрешённый адрес, что даёт два исключения: localhost, разрешающийся вне loopback, никогда не генерирует токен и загружается только при наличии разрешённого источника токена (иначе Refusing to bind …); а не-буквальное имя, разрешающееся в loopback, генерирует токен, теряя доверенный режим без токена, поэтому его bearer выводит только токен.
• Отклонение небезопасных или невалидных конфигураций запуска: привязка не к loopback-интерфейсу без токена, --require-auth без токена, wildcard или не-loopback HTTP(S) --allow-origin без токена, mcpBudgetMode='enforce' без положительного mcpClientBudget, несуществующий или не являющийся директорией --workspace, а также невалидные значения таймаутов или rate-limit.
• Создание фабрики WorkspaceFileSystem, издателя аудита разрешений (permission audit publisher), DaemonStatusProvider и acp-bridge.
• Сборка приложения Express, подключение middleware (удаление loopback Origin -> access log -> захват входящего trace-id -> hostAllowlist -> удаление remote same-origin Origin -> allowOriginCors поверх мутабельного allowlist origin -> pre-auth /health -> pre-auth ресурсы Web Shell -> вебхуки каналов -> bearerAuth -> rate limit -> JSON parser -> telemetry -> per-route mutationGate) и монтирование маршрутов для сессий, CRUD-операций с рабочим пространством, файлами, аутентификации через device-flow, голосования за разрешения и ACP HTTP. (Безусловная стена denyBrowserOriginCors сохраняется только в бутстрап-приложении run-qwen-serve.ts.)
• Привязка порта прослушивания и регистрация обработчиков сигналов.
• Запуск двухфазного завершения работы по SIGINT/SIGTERM; принудительный выход при получении второго сигнала.

Архитектура

Точка входа: runQwenServe(opts, deps) в packages/cli/src/serve/run-qwen-serve.ts. Возвращает RunHandle ({ url, port, close, ... }).

Фабрика приложения: createServeApp(opts, getPort, deps) в packages/cli/src/serve/server.ts. Собирает Express Application. Прямые встраивающие модули и тесты вызывают её без обёртки бутстрапа.

Реестр возможностей: SERVE_CAPABILITY_REGISTRY в packages/cli/src/serve/capabilities.ts. Каждый тег имеет версию since и опциональные modes. Условные теги исключаются, если их деплойментный или рантаймный предикат ложен; реестр и карта предикатов являются источником истины. См. 11-capabilities-versioning.md.

Middleware (packages/cli/src/serve/auth.ts, server.ts, server/self-origin.ts и server/access-log.ts):

Подсистемы:

Импорты из пакета ACP bridge:

• Примитивы event-bus импортируются из @qwen-code/acp-bridge/eventBus.
• Примитивы статуса импортируются из @qwen-code/acp-bridge/status.
• serve/acp-session-bridge.ts остаётся как локальный для CLI фасад совместимости для более широкой поверхности bridge.

Поток выполнения

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

До того как runQwenServe() запускает эту последовательность, режим CLI --open-with-auth проверяет возможность работы с loopback/Web Shell и заполняет ServeOptions.token выбранным настроенным токеном или 32 случайными байтами (256-битный bearer) в кодировке base64url, если выбор пуст. Это сгенерированное значение является обычным настроенным токеном для всех шагов ниже — именно поэтому --require-auth --open-with-auth загружается — и это отдельный генератор от эфемерного bearer для не-loopback в шаге 1. Прямые встраивающие модули, вызывающие createServeApp самостоятельно, никогда не генерируют токен.

1. Разрешение токена из opts.token или QWEN_SERVER_TOKEN с обрезкой, чтобы завершающий символ новой строки от cat token.txt не мог скрыто нарушить сравнение bearer. Когда запрошенный --hostname не является loopback (буквальный localhost разрешается первым) и ни один источник не присутствует, генерируется эфемерный 128-битный (16-байтный) bearer как 22 символа base64url вместо отказа; он выводится один раз удалённым быстрым стартом после listen() и ротируется при каждом перезапуске. Loopback-записи никогда не генерируют, поэтому сохраняют доверенный режим без токена. Явно пустой источник (--token '' или QWEN_SERVER_TOKEN установленный в пустое или только пробельное значение) не считается «отсутствующим», поэтому всегда подавляет генерацию — но пустота определяет разрешённый токен только в одном направлении: пустой --token затеняет установленное значение env и разрешается в отсутствие токена, тогда как пустое env разрешается в отсутствие токена только когда --token не передан (непустой --token всё равно побеждает); в обоих случаях не-loopback привязка без разрешённого токена всё равно не проходит проверки ниже.
2. Защита от опечаток в hostname: --hostname localhost:4170 вызывает ошибку и предлагает использовать --port.
3. Preflight аутентификации: не-loopback привязка без разрешённого токена отклоняется — это достижимо через явно пустой источник или через привязку localhost, чьё одноразовое разрешение попадает вне loopback (генерация зависит от записи, поэтому там ничего не было сгенерировано); --require-auth отклоняет привязку без токена, что после шага 1 означает привязку к loopback без настроенного источника. Защитные механизмы wildcard и не-loopback HTTP(S) --allow-origin читают тот же разрешённый токен, поэтому на не-loopback привязке сгенерированный bearer удовлетворяет им, и эти отказы тоже только для loopback.
4. Валидация рабочего пространства: абсолютный путь, существует, является директорией. EACCES / EPERM оборачиваются, чтобы указать на флаг.
5. Канонизация рабочего пространства: canonicalizeWorkspace(rawWorkspace) один раз запускает realpathSync.native и передаёт результат в /capabilities, fallback для POST /session и в bridge.
6. Валидация бюджета MCP: положительное целое число; enforce требует указания бюджета.
7. Вывод переключателя пула MCP: родительская переменная окружения QWEN_SERVE_NO_MCP_POOL=1 устанавливает mcpPoolActive=false, поэтому возможности честно исключают mcp_workspace_pool и mcp_pool_restart.
8. Валидация CORS / таймаутов / rate-limit: wildcard и не-loopback HTTP(S) значения --allow-origin требуют разрешённый токен (см. шаг 3, почему эти отказы только для loopback); значения таймаутов простоя промптов, writer, канала, сессии, reaper и окна rate-limit приводят к быстрому сбою при невалидности.
9. childEnvOverrides для каждого handle: передача QWEN_SERVE_MCP_CLIENT_BUDGET и QWEN_SERVE_MCP_BUDGET_MODE дочернему процессу ACP через BridgeOptions.childEnvOverrides вместо мутации process.env.
10. Однократная загрузка settings.json: чтение context.fileName, policy.permissionStrategy и policy.consensusQuorum. Повреждённые файлы откатываются к значениям по умолчанию. validatePolicyConfig() проверяет policy.* на соответствие SERVE_CAPABILITY_REGISTRY.permission_mediation.modes; неизвестные стратегии или неположительный consensusQuorum выбрасывают InvalidPolicyConfigError. Кворум, установленный для стратегии, отличной от consensus, логирует предупреждение в stderr.
11. Выделение PermissionAuditRing (512 записей).
12. Сборка fsFactory: runQwenServe по умолчанию использует trusted: true; прямые вызовы createServeApp по умолчанию используют trusted: false и выводят одно предупреждение.
13. createHttpAcpBridge, см. 03-acp-bridge.md.
14. createServeApp собирает Express.
15. Создание и привязка HTTP(S)-сервера к жизненному циклу перед прослушиванием, затем вызов server.listen(port, hostname) и разрешение фактического getPort() для allowlist хоста. Владение Conversations не может начаться, пока этот слушатель и оставшиеся хост-гейты запуска не будут готовы.
16. Регистрация обработчиков SIGINT / SIGTERM для корректного завершения работы через общий жизненный цикл приложения.

Корректное завершение работы

1. Закрытие допуска и начало всех дренирований по первому сигналу:
   • Удаление реестра device-flow и отмена ожидающих потоков.
   • bridge.shutdown() помечает каждый канал isDying = true, отправляет корректное закрытие в stdin каждого дочернего процесса ACP, ждёт KILL_HARD_DEADLINE_MS (10 с) для каждого канала, затем при необходимости вызывает channel.kill().
2. Закрытие слушателя, пока выполняются дренирования приложения и хоста:
   • server.close() прекращает приём новых соединений и позволяет завершиться выполняющимся запросам.
   • SHUTDOWN_FORCE_CLOSE_MS (5 с) инициирует server.closeAllConnections().
   • Второй дедлайн в 2 с при необходимости снова эскалирует завершение.
3. Освобождение владения Conversations только после положительного доказательства завершения от слушателя, локальной работы приложения, работы хоста, очистки Live discovery и дренирований среды выполнения. Любое неполное доказательство отклоняет завершение вместо небезопасной передачи.
4. Второй сигнал во время выхода:
   • bridge.killAllSync() + process.exit(1), чтобы избежать блокировки выхода демона осиротевшими дочерними процессами.

Состояние и жизненный цикл

RunHandle предоставляет:

• url: разрешённый URL прослушивания, после разрешения эфемерного порта.
• port: фактический порт, включая разрешение 0.
• close(): программное завершение работы для встраивающих модулей и тестов.

Прямой вызов createServeApp возвращает только Application. Встраивающему модулю, которому нужны Live/Conversations, необходимо создать фактический Node-сервер, вызвать getServeAppLifecycle(app).bindServer(server) перед первым listen() и ожидать lifecycle.close() во время завершения работы. Без привязки обычные маршруты остаются доступными, но Live/Conversations завершаются с ошибкой (fail closed). Вызов обычного server.close() запускает очистку на основе событий, но встраивающий модуль всё равно должен ожидать lifecycle.close(), чтобы получить информацию о сбоях дренирования или освобождения владения.

Зависимости

Конфигурация

См. 17-configuration.md для сводной документации.

Важные замечания и известные ограничения

• Прямой вызов createServeApp без deps.fsFactory или deps.bridge по умолчанию устанавливает trusted: false; ACP writeTextFile на стороне агента отклоняет запрос с ошибкой untrusted_workspace. Предупреждение выводится один раз.
• Runtime-приложение запускает allowOriginCors поверх мутабельного allowlist; несовпадающие значения Origin получают 403 deny envelope (безусловная стена denyBrowserOriginCors сохраняется только в бутстрап-приложении). Loopback Web Shell работает, потому что другой middleware сначала удаляет совпадающие значения same-origin для loopback; на не-loopback привязке с токеном same-origin XHR оболочки bearer-аутентифицированы и их Origin удаляется перед стеной, поэтому им не нужен --allow-origin. Три случая всё ещё требуют записи в allowlist: WebSocket-обновления (terminal, voice), TLS-терминирующий фронт-прокси, чей https origin никогда не совпадает с открытым сокетом, и любой plain-HTTP посредник, переписывающий заголовок Host — nginx по умолчанию с proxy_set_header Host $proxy_host и k8s Ingress оба делают это. Только трансляция порта не требует ничего на не-loopback привязке (docker -p 8080:4170): проверка сравнивает Origin только с нормализованным пересланным Host и никогда не обращается к порту прослушивания (только порты по умолчанию для схемы :80/:443 удаляются; порт не по умолчанию должен сохраняться в нём дословно). На привязке loopback по умолчанию это не так: Host allowlist от DNS-rebinding принимает только собственный порт демона, поэтому туннель с трансляцией порта (ssh -L 8080:localhost:4170) отклоняется с 403 Invalid Host header для каждого запроса, включая документ оболочки, и --allow-origin не может это переопределить — перенаправляйте тот же порт или привязывайтесь к не-loopback. Решение для случаев WebSocket и TLS-терминирующего прокси — --allow-origin <origin>; посредник с переписыванием Host может быть настроен на пересылку Host дословно — что не может помочь, когда TLS терминируется на прокси, потому что схема читается из собственного сокета демона.
• Порядок body-parser: маршруты, использующие mutate({ strict: true }), возвращают 401 только после express.json(). В худшем случае это --max-connections × express.json({limit: '10mb'}), что может привести к выделению до 2,5 ГБ временной памяти при максимальной нагрузке на loopback-листенер; этот компромисс является осознанным.
• Несколько демонов в одном процессе должны использовать childEnvOverrides для каждого handle; мутация process.env приводит к гонкам, поскольку defaultSpawnChannelFactory делает снимок окружения в момент spawn.

Ссылки

• packages/cli/src/serve/run-qwen-serve.ts (бутстрап, валидация загрузки, корректное завершение работы)
• packages/cli/src/serve/server.ts (createServeApp(), сборка middleware и маршрутов)
• packages/cli/src/serve/auth.ts (CORS, allowlist Host, bearer-аутентификация, mutation gate)
• packages/cli/src/serve/rate-limit.ts (HTTP rate limit для каждого уровня)
• packages/cli/src/serve/capabilities.ts (реестр возможностей и условное объявление)
• packages/cli/src/serve/types.ts (ServeOptions, CapabilitiesEnvelope)
• packages/cli/src/serve/daemon-status-provider.ts
• packages/cli/src/serve/permission-audit.ts
• Issues: #3803 , #4175