Где ломается «идеальный» compose
Docker Compose делает сервисы повторяемыми до тех пор, пока секрет не записан дважды разными путями: переменная OPENCLAW_GATEWAY_TOKEN из окружения и поле gateway.auth.token в смонтированном openclaw.json должны иметь одного владельца истины.
Коды 1006 и 1008 WebSocket раскладывают проблему по слоям: 1006 обычно указывает на обрыв транспорта или прокси, 1008 чаще связан с политикой авторизации или Origin.
Pairing хранит промежуточные доказательства во временных файлах; анонимные тома Docker уничтожают их при пересоздании контейнера и создают «вечное ожидание» в UI.
HTTP /health не заменяет проверку апгрейда WebSocket: успешный curl не гарантирует корректные заголовки Upgrade за ingress.
TLS-терминация на reverse proxy часто сопровождается более короткими idle-timeout, чем период ping клиента — без синхронизации появляются ложные 1006.
Холодный старт gateway может занимать десятки секунд; агрессивный healthcheck убивает процесс до загрузки плагинов.
QA-копии забывают обновить gateway.remote.url, что смешивается с проблемами токена и маскируется как split-brain.
Журналы WebSocket должны классифицироваться по типам данных для комплаенса; иначе ротация секретов ломает аудит.
Форматирование JSON в CI меняет контрольные суммы без изменения семантики.
Соседние контейнеры с лог-агентами могут менять права на том pairing без явного тикета.
Сочетание Kubernetes и Compose на одном хосте с host network даёт коллизии портов без явной ответственности.
Бэкапы без метки compose-проекта восстанавливают старые pairing-шарды в новый стек.
Compose profiles лучше fork’ов репозитория с ручным копированием env.
Дашборды должны быть разделены по compose-проектам, чтобы не смешивать инциденты клиентов.
Несколько compose-override без явной иерархии порождают частичную интерполяцию секретов: человеческие процессы теряют последнюю записанную версию токена.
Миграция с bare metal часто сохраняет абсолютные пути в JSON; контейнер видит другой файл при ошибочном bind-mount даже при верном значении переменной.
Стратегии zero-downtime допускают короткое сосуществование двух токенов; без явной матрицы совместимости клиенты смешивают RPC и потоковые сессии.
Прикладные WAF редко анализируют Upgrade как обычный HTTP-трафик; добавляйте правила или логируйте отказы до обвинения gateway.
CDN может менять поведение HTTP и WebSocket по регионам POP без изменений репозитория.
Нагрузочное тестирование только RPC скрывает всплески pairing при первом rollout.
Регуляторные окружения должны версионировать шифрованные env рядом с Vault-ID чтобы исключить параллельные ротации.
Сегменты сети могут резать UDP/QUIC, не затронув TCP RPC; проверьте карту ACL перед тем как считать токен битым.
Git hooks с подстановкой фейковых токенов для локальных тестов могут попасть в CI если скрипт не чистит артефакты.
Гибридный VPN добавляет RTT и искажает дедлайны handshake без явной ошибки.
Тесты совместимости браузеров обязательны: Safari и Chrome по-разному обрабатывают SameSite cookies через некоторые прокси.
Мультирегион следует документировать: какой ЦОД отвечает за истину DNS при локально запущенном compose.
Медленный ответ registry создаёт ложные тревоги pairing: образ долго тянется, а healthcheck уже решил, что сервис мёртв.
Квартальные обзоры политики секретов дешевле исправления silently drifted конфигураций после года эксплуатации.
Еженедельные игровые учения на ротации токенов при активных пользователях показывают реальный простой.
Зеркалируйте handshake dashboards между платформенной и продуктовой командами — разделённые Grafana-папки предотвращают ошибочную ownership инцидентов.
Слои диагностики как в официальной документации
Следуйте официальному порядку OpenClaw: процесс, транспорт, авторизация, pairing — Compose меняет только инструменты сбора улик.
Процесс: нет ли скрытого рестарта из-за ошибки bind или fork без PID-файла.
Транспорт: порты, NAT, IPv6, firewall и published ports.
Авторизация: один канонический токен и синхронная ротация через Vault/Terraform.
Pairing: именованный том с UID контейнера.
Наблюдаемость: коды закрытия WS и latency без утечки полного токена.
Гovernance: ревью compose-файлов включает env_file и secrets одновременно.
Для распределённых команд нужна RACI-матрица, чтобы два региона не крутили разные hotfix одновременно.
Учения chaos с живыми пользователями показывают реальный простой при ротации.
Не отключайте TLS-verify ради скорости — исправляйте цепочки сертификатов.
Перед продакшеном автоматизируйте сравнение хэшей двух источников токена на orchestrator.
При нескольких reverse-proxy слоях измеряйте idle-timeout каждого и синхронизируйте с ping интервалом.
Используйте профили compose для сред вместо клонирования репозитория целиком — это уменьшает расхождение env файлов.
Не смешивайте журналирование sidecar и основного gateway в один пайп без фильтра — затрудняется триаж WS ошибок.
Поддерживайте playbook восстановления: detach stack, список volume, удалить только анонимные слои.
Для Metal-сервера также контролируйте термальный троттлинг — он может замедлять crypto операций без явной ошибки токена.
Метрики и пороги
start_period не менее 45 секунд при медленных registry или air-gap.
Внешние WS-пробы раз в минуту, внутренние curl — каждые 15 секунд.
RPC RTT в overlay измеряйте отдельно от WAN.
Pairing SSD до 10 секунд; если до 40 секунд — проверяйте IO.
Полная ротация за 5 минут или автоматизируйте всё в одном пайплайне.
Храните close-коды минимум 14 дней для корреляции с ingress.
Следите за cgroup CPU throttle — он удлиняет handshake без ошибки auth.
Короткий TTL DNS вместе с частой ротацией имитирует отказ авторизации.
Разделите Grafana по клиентам compose.
Учитывайте JIT задержку первого запроса после деплоя.
При образах из закрытого контура ставьте start_period до 90 секунд пока не стабилизируете SLA загрузки.
Фиксируйте histogram времени pairing для каждой версии gateway чтобы регрессии версии были очевидны.
Снимайте метрики времени pull образа отдельно от времени готовности listener.
При смешении systemd-сервисов на хосте и compose на том же порту документируйте очередность автозапуска.
Раз в месяц проводите synthetic транзакцию pairing через production-путь даже если клиентских жалоб нет.
Лимиты памяти cgroup должны учитывать burst больших WS сообщений.
Размер кадров WebSocket может упираться в proxy_buffers или lua скрипты без ошибки токена — профилируйте именно большие payload.
Если одновременно активирован overlay CNI кластера и docker bridge, сохраните трассу до контейнерного listener как базовый артефакт инцидентов.
Аппаратное RNG offload может отличаться внутри образа и на хосте — проверьте одинаковую доступность к crypto-пути до выпуска трафика.
Mesh-sidecar с дополнительным mTLS поверх уже шифрованного канала может множить рукопожатия и закрывать сессии без явной ошибки gateway.
Снимайте snapshot конфигурации ingress ежеквартально даже без деплоев — платформенные патчи часто меняют idle timeout.
Отдельный мониторинг времени pull образа из закрытого registry помогает отличить сетевые задержки от проблем токена.
Используйте двухуровневые дашборды: один для compose-проекта внутри namespace, второй для клиентского SLA при pairing.
Журналируйте выбор cipher suite для TLS даже если проблема кажется auth-токеном — иногда legacy клиенты отваливаются раньше проверки секрета.
Для mixed workload на одном хосте документируйте приоритет systemd unit против compose restart policy.
Поддерживайте минимум два окна обслуживания при ротации токенов для географически распределённых пользователей.
Регулярно проверяйте, что логи пар не попадают в центральное хранилище без редактирования даже при давлении поддержки.
Обновляйте документацию по pairing каждый раз при смене базового образа gateway.
Экспорт метрик из контейнера должен использовать те же метки compose.project что и алерты.
Фиксируйте baseline времени переподключения WebSocket после деплоя чтобы регрессии были видны численно.
Если используете IPv6 и IPv4 одновременно, создайте явные тесты pairing для каждого стека.
Держите список резервных ingress классов на случай канареечного выпуска новых таймаутов.
Планируйте capacity для burst reconnect после рестарта gateway — одновременные клиенты могут создать эффект thundering herd.
Проверяйте согласованность часов NTP между контейнером и upstream proxy перед диагностикой JWT.
Разграничивайте секреты bootstrap gateway от секретов каналов чтобы случайная ротация не блокировала файловый pairing.
Для macOS-хостов помните про разницу между virtualization.framework и docker desktop при измерении времени cold boot.
Напоминайте разработчикам очищать локальные docker volume перед репродукцией багов pairing.
Включите алерт на рост числа half-open TCP сессий если клиенты массово переподключаются после ротации.
Храните историю изменений idle-timeout ingress рядом с changelog gateway releases.
Матрица решений
| Топология | Токен | WebSocket | Pairing |
|---|---|---|---|
| Bridge publish | Один источник истины | Порты = клиентским URL | Именованный том |
| host network | Часто JSON лидирует | Без NAT; риск коллизий | Пути как на железе |
| Reverse proxy | Только на сервере | Idle выше ping | При необходимости sticky |
| Sidecar secrets | Без гонок монтажа | Не путать логи | Не чистить общий том |
Матрица ниже связывает топологию и источник токена с требованиями WebSocket и pairing; дополняет гайд по установке Docker.
Bridge по умолчанию предсказуем; host mode упрощает localhost, но множит конфликты.
Reverse proxy должен сохранять Upgrade и держать idle выше ping.
Sidecar-секреты не должны GC-ить общие тома pairing.
Экономически дрейфующий QA дороже эталонного арендованного узла.
Короткие release notes с пометкой «синхронизирован gateway token» спасают ночные выезды.
Для креативных студий важно именовать compose-проект по клиенту.
Перед включением host networking распределите порты между платформенной командой и владельцами приложений.
При переходе с docker-compose v1 на v2 plugin проверьте изменение переменных COMPOSE_PROJECT_NAME по умолчанию.
Если ingress добавляет Geo блокировки, убедитесь что тестовые учётки не попадают в запрет без связи с токеном.
Сервисные mesh могут переупорядочивать заголовки X-Forwarded-* и ломать проверку Origin если конфиг не зафиксирован.
Переезд между регионами иногда меняет путь до объектного хранилища образов — включите это в чеклист деплоя.
Файловые ACL macOS хоста важно сверять с тем как они проброшены внутрь контейнера через bind mounts для локальных staging.
Фиксируйте минимальный SLA времени восстановления pairing отдельно от SLA общего API чтобы KPI были реалистичны.
См. также руководство по путям установки.
Пошаговый compose
version: "3.9"
services:
openclaw-gateway:
image: ghcr.io/example/openclaw-gateway:latest
env_file:
- .env.gateway
environment:
OPENCLAW_GATEWAY_TOKEN: "${OPENCLAW_GATEWAY_TOKEN}"
volumes:
- ./openclaw.json:/etc/openclaw/openclaw.json:ro
- gateway_pairing:/var/lib/openclaw/pairing
ports:
- "18789:18789"
healthcheck:
test: ["CMD", "curl", "-fsS", "http://127.0.0.1:18789/health"]
interval: 30s
timeout: 5s
retries: 5
start_period: 45s
volumes:
gateway_pairing:
Шаг 1: сохраните compose config и маски токена до изменений.
Шаг 2: выберите канон между gateway.auth.token и OPENCLAW_GATEWAY_TOKEN.
Шаг 3: смонтируйте pairing на именованный том.
Шаг 4: выставьте start_period под холодный старт.
Шаг 5: настройте proxy idle и Upgrade.
Шаг 6: запустите openclaw doctor.
Шаг 7: задокументируйте ротацию и откат.
Шаг 8: при странном URL см. матрицу удалённого шлюза.
Связанные материалы
Читайте материал про удалённый шлюз если RPC странные при правильном токене.
Split-brain статья помогает отличить бинарный дрейф от секретного.
Daemon install объясняет launchd/systemd аналоги для healthcheck.
Сравнение install.sh/npm/docker показывает почему смешиваются пайплайны.
Навигация: главная, прайс, помощь для выбора арендованного Mac.
Сравнивайте часы дежурства с SLA аренды.
Держите рядом runbook про удалённый gateway когда несколько команд делят один wildcard DNS.
Шифруйте pcap следы без секретов в открытом виде для будущих разборов WS проблем.
Если SLA pairing расползаются относительно обещаний пользователям, проверьте размер тома и тип SSD.
Добавьте главу про WS/TLS в онбординг новых инженеров чтобы повторяющиеся тикеты сократились.
Сравнивайте cost nightly поддержки compose-only инфраструктуры с арендой узла под SLA.
FAQ
Ответы ниже связывают эксплуатацию с compose-ограничениями; юридический аудит данных WS остаётся отдельным тикетом.
Гибрид bare metal + orchestrator требует единого владельца identity.
Поддерживайте журнал изменений ingress-таймаутов и связывайте его с релизами gateway чтобы исключить ложные корреляции и ускорить разбор инцидентов.
Почему два токена конфликтуют?
Compose интерполирует .env раньше монтажа JSON — зафиксируйте приоритет.
Всегда ли 1008 это пароль?
Часто политика или Origin; читайте сообщение сервера.
Почему pairing после recreate?
Анонимные тома теряют файлы — нужны именованные тома или восстановление из бэкапа с проверкой compose-project.
Перед резюме фиксируйте compose project label в каждом инциденте.
Итог: Compose стабилен при едином токене, именованном pairing и терпимых healthcheck к холодному старту; именно так задаётся устойчивость описанных цепочек.
Ограничения: Compose не исправляет кривые прокси или хаотичную ротацию Vault.
Контраст: аренда удалённых Mac у SFTPMAC даёт контролируемое железо Apple, SLA и трассируемые передачи — дополняя ваши compose-рецепты без замены инженерной документации.
Запускайте doctor после каждого крупного выравнивания.