Привязки баз данных приложений

Привязка приложения предоставляет одному Container, Deployment или подходящей службе рабочей нагрузки приватный доступ к одной управляемой базе данных. Opfield создаёт для привязки отдельного пользователя или роль движка с правами уровня приложения в управляемой базе — никогда не учётные данные владельца или суперпользователя. Идентичность движка принадлежит привязке, а не временному процессу рабочей нагрузки.

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

Движок	Идентичность привязки
PostgreSQL	Роль с правом входа, входящая в роль приложения и использующая её по умолчанию; без прав суперпользователя, создания баз данных и ролей
ClickHouse	Пользователь, роль которого имеет все права на базу данных приложения и чтение нужных Opfield системных таблиц; доступа к другим базам нет
Redis	Пользователь ACL, которому разрешены команды чтения, записи, соединения, транзакций, публикации и подписки и выполнения скриптов; опасные и административные команды запрещены

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

Используйте привязку, если приложению нужен доступ к базе без общих учётных данных владельца и без публикации базы в более широкую сеть. Владелец базы одобряет, какие рабочие нагрузки получают доступ, владелец приложения выбирает способ передачи параметров подключения в рабочую нагрузку, а владелец платформы поддерживает доступность нод хранилища и Docker. Успех означает, что приложение выполняет нужные операции, не может выполнять административные действия за пределами базы данных приложения и сохраняет доступ после контролируемого пересоздания без создания дублирующих идентичностей.

Главный риск — повторное использование учётных данных или слишком широких прав. Создавайте отдельную привязку для каждой границы рабочей нагрузки, сохраняйте базу приватной по умолчанию и удаляйте привязку, когда доступ больше не нужен.

Для операторов: транспорт и модель владения

Начиная с 2.11.1 каждая привязка работает через общий коннектор защищённых связей целевой ноды Docker — тот же, что обслуживает привязки хранилища и связи контейнеров. Каждая привязка получает собственную небольшую приватную сеть, к которой подключается рабочая нагрузка; в ней коннектор отвечает на имя хоста привязки и передаёт каждое соединение через Relay на ноду хранилища базы данных. Отдельного контейнера-коннектора для каждой привязки и службы приёма соединений на хосте нет. Opfield согласует связь как часть желаемого состояния привязки. Сети связей получают адреса из отдельного диапазона, описанного в разделе Общий коннектор и сети связей.

Связь и идентичность движка — отдельные, но согласованные записи. У каждой привязки есть собственная идентичность в базе данных, поэтому ротация учётных данных, удаление или изменение прав одной рабочей нагрузки не затрагивает другую незаметно. При пересоздании рабочей нагрузки привязка и отдельная идентичность движка сохраняются; Opfield снова согласует связь и передаёт актуальные параметры подключения.

Сначала диагностируйте состояние связи привязки и готовность базы; маршруты Ingress в пути привязки не участвуют.

Создайте привязку

До создания убедитесь, что управляемая база имеет статус Ready, целевая нода Docker подключена, рабочая нагрузка поддерживает привязки, а у вас есть доступ к обоим ресурсам: databases:edit для базы, а для рабочей нагрузки — docker:containers:environment и docker:containers:secrets для Container или Deployment либо docker:compose:manage для службы Compose. Изменение привязки на развёртывании может выкатить его заново, поэтому требует docker:containers:manage для этого развёртывания, а при изменении его переменных среды — ещё и docker:containers:edit. Проверьте необходимые права на базу или роль и убедитесь, что рабочая нагрузка может использовать переданные параметры подключения без сохранения их в системе контроля версий.

Выберите управляемую базу данных и целевую рабочую нагрузку.
Выберите, какие параметры подключения передать, и имя переменной среды для каждого.
Создайте привязку и дождитесь, пока Opfield подготовит идентичность движка и согласует связь.
Применяйте или пересоздавайте рабочую нагрузку только тогда, когда этого требует изменение её конфигурации.
Выполните реальный запрос приложения, затем проверьте телеметрию привязки и журналы рабочей нагрузки и базы данных.

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

Привязка может указывать на подходящий автономный Container, Deployment или службу Compose Project на подключённой ноде Docker, а база данных должна иметь статус Ready. Opfield передаёт выбранные значения — URI подключения, хост, порт, базу данных, имя пользователя и пароль — под заданными вами именами переменных среды; нужно выбрать хотя бы одно значение. Console предлагает имена вроде DATABASE_URL или REDIS_URL либо имена отдельных значений для конкретного движка. URI использует обычный протокол движка в приватной сети привязки (postgresql://, redis:// или http:// для ClickHouse); привязки не добавляют параметры TLS. Обычный URI работает и с PostgreSQL, у которого включён TLS: если клиент подключается без TLS, демон на ноде хранилища базы данных (2.11 или новее) сам устанавливает TLS-соединение с PostgreSQL и проверяет сертификат экземпляра. Клиент, который сам запрашивает TLS, например с sslmode=require, сохраняет собственный сквозной сеанс TLS. Считайте секретом каждое переданное значение, даже если сама связь приватна. Не копируйте URI в исходный код Compose, слои образа, снимки экрана, журналы или конфигурацию среды выполнения Pages.

Одна база может обслуживать несколько рабочих нагрузок через отдельные привязки. Это безопаснее общей учётной записи: каждую привязку можно независимо аудировать, ротировать и выводить из эксплуатации. Opfield отклоняет конфликтующие назначения переменных среды вместо незаметной замены уже существующего значения приложения; единственное исключение — явное согласие на замену существующих значений для автономного Container.

Рабочая нагрузка не запущена

Целевая рабочая нагрузка может быть не запущена. Привязку можно создать или удалить для Container, Deployment или службы Compose, которые остановлены, циклически перезапускаются, завершились ошибкой или ещё не развёрнуты. Запрос возвращается, не дожидаясь запуска нагрузки или её исправного состояния, а неудачное развёртывание не отменяет привязку.

Привязка, которая уже сохранена в конфигурации рабочей нагрузки, но ещё не используется ею, отображается как pending (observedState: "target_applied" в API и MCP). Она становится активной, когда нагрузка в следующий раз запустится или завершит текущее развёртывание.
Циклически перезапускающийся Container пересоздаётся с привязкой и продолжает перезапускаться по своей политике перезапуска.
Deployment, у которого первая сборка из Git завершилась ошибкой, получает привязку, когда вы повторно запускаете сборку; задавать образ вручную не нужно.
Во время выкатки сборки из Git привязки по-прежнему можно сохранять: они попадут в новую ревизию, когда выкатка завершится.
Через API, MCP или ассистента можно также привязать Container с источником Git до его первой сборки — по имени, — а службу Compose — до первой ревизии проекта или пока проект занят выкаткой сборки. Первая сборка или следующая ревизия запускает нагрузку уже с привязкой; если в этой ревизии нет нужной службы, привязка завершается ошибкой с указанием причины. В Console привязки для таких нагрузок становятся доступны, когда Container или первая ревизия уже существуют.
Откат Deployment, переключение слота и применение более старой ревизии Compose сохраняют текущие привязки. Ревизию, в которой нет привязанной службы, нельзя применить, пока вы не удалите эту привязку.
Целевая нода Docker должна быть подключена: привязку для нагрузки на отключённой ноде Opfield отклоняет с ошибкой 409 NODE_OFFLINE.

Критерии успешной привязки

После создания или пересоздания рабочей нагрузки проверьте:

привязка имеет статус Ready, а не pending, и целевая рабочая нагрузка запущена;
рабочая нагрузка получила ожидаемые имена переменных без раскрытия значений;
запрос приложения выполняется, а административная операция за пределами базы данных приложения, например создание роли или базы, завершается отказом;
телеметрия среды выполнения привязки показывает ожидаемый поток без устойчивых отказов допуска;
пересоздание рабочей нагрузки сохраняет ту же привязку и не создаёт дополнительную роль движка;
несвязанная рабочая нагрузка не может обратиться к приватной сети привязки или повторно использовать идентичность привязки.

Просмотр контейнера (inspect), вкладки окружения, экспорт архива и дублирование не раскрывают пароли привязок и ключи привязок хранилищ, а дубликат не наследует привязки исходного контейнера. Раскрытие учётных данных — исключительное диагностическое действие. Оно требует явных прав и соблюдения обычных правил обращения с секретами. Не раскрывайте данные только ради проверки, если реальный запрос приложения и телеметрия дают более безопасное доказательство.

Ёмкость привязки и пулы соединений

Привязка управляемой базы данных выдерживает до 64 одновременных соединений, как и привязка управляемого хранилища. Ёмкость принадлежит привязке, а не контейнеру: её делят все контейнеры, которые обслуживает привязка, а во время blue/green-развёртывания старый и новый слоты делят её, пока старый слот не остановится. Workload Availability даёт каждому размещению собственную привязку. Сверху действует ограничение самого движка: управляемый экземпляр PostgreSQL сохраняет стандартный для PostgreSQL предел в 100 соединений на все свои привязки вместе.

Задавайте пулы соединений одного контейнера не больше половины ёмкости, то есть 32, и учитывайте все пулы в процессе — ORM, очередь задач, миграции и отдельные драйверы, — чтобы новый слот мог открыть свои пулы, пока обслуживающий слот держит свои. SDK для S3 по умолчанию держат большие пулы постоянных соединений (50 сокетов на клиента в AWS SDK для JavaScript), поэтому ограничьте и их.

Нода, на которой работает рабочая нагрузка, соблюдает ёмкость для привязки целиком: её коннектор защищённых связей держит не больше 64 открытых соединений, через какой бы Relay пула ни шло каждое из них, а каждый Relay ограничивает маршрут привязки теми же 64. Соединение сверх ёмкости принимается и сразу закрывается, поэтому клиенты видят ошибки вроде Connection terminated unexpectedly или ECONNRESET, а клиент S3 привязки хранилища получает ошибку соединения. Нода записывает managed link connection rejected с reason=link_limit раз в минуту для каждой привязки, вместе с числом отказов с предыдущей записи; эта строка видна в журналах ноды в Opfield, а не только в системном журнале хоста.

Состояние привязки

Обзор связанного Container, Deployment или Compose Project показывает состояние каждой привязки: открытые соединения относительно предела в 64, объём трафика, задержку установки соединения, долю успешно завершённых соединений и отказы допуска с причиной последнего отказа. Привязки хранилищ у Containers и Deployments показаны рядом с привязками баз данных и помечены S3. Состояние привязки Availability — сумма по её размещениям.

Интерфейс	Привязка базы данных	Привязка хранилища
REST	`GET /api/databases/managed/{id}/bindings/{bindingId}/runtime`	`GET /api/managed-storage/{id}/bindings/{bindingId}/runtime`
MCP и ассистент	`manage_managed_database` `get_binding_runtime`	`manage_managed_storage` `get_binding_runtime`

activeStreams — число открытых соединений по подсчёту ноды, на которой работает рабочая нагрузка, openedTotal и счётчики байтов — то, что привязка передала через эту ноду, через какие бы Relay это ни шло, throttledTotal — число соединений, отклонённых сверх ёмкости нодой или Relay, а connections добавляет предел, отказы ноды, причину и время последнего отказа. Число завершённых и неудачных соединений, задержка установки и длительность берутся у Relay. connections равно null, пока на этой ноде работает Docker-демон старше 2.11, и тогда остальные значения тоже берутся у Relay. Устойчивые отказы допуска означают, что пулы контейнеров за привязкой слишком велики.

Согласование и обработка сбоев

Желаемое состояние привязки сохраняется после пересоздания рабочей нагрузки, перезапуска Docker-демона, повторного подключения ноды и перезапуска Relay. Привязка сохраняет соединения, когда API Docker ненадолго замедляется и когда Availability забирает рабочую нагрузку или возвращает её, а согласование выполняется только для той рабочей нагрузки, которой касается событие. Согласование восстанавливает связь и подтверждает идентичность движка, не создавая новую идентичность для каждой временной среды выполнения. Так обычные перезапуски и пересоздания не оставляют осиротевшие роли.

При сбое проверяйте владельцев по порядку: готовность управляемой базы; состояние ноды хранилища; состояние ноды Docker и рабочей нагрузки; желаемое состояние привязки и её последнюю Task; связь в коннекторе защищённых связей ноды; идентичность и права движка; затем конфигурацию и журналы приложения. После исправления причины используйте поддерживаемое согласование или точечный повтор. Не удаляйте роль движка, сеть связи или коннектор вручную: это может рассинхронизировать долговременную запись с базой и демоном.

Удаление и восстановление

Удаляйте привязку через Opfield, когда рабочей нагрузке больше не нужен доступ. Opfield удаляет связь и выводит идентичность движка из эксплуатации в рамках одного записанного жизненного цикла, поэтому обычное удаление не оставляет неиспользуемых идентичностей. По возможности удалите привязку до базы или рабочей нагрузки, затем убедитесь, что очистка связи, телеметрии и идентичности движка завершилась. Удаление автономного Container через Opfield удаляет и его привязки; то же происходит, когда его имя достаётся другому контейнеру при создании, дублировании, переименовании или импорте, поэтому новый контейнер с тем же именем никогда не получает сеть и учётные данные прежней привязки.

Если удаление прервалось, оставьте долговременную запись привязки и используйте состояние её операции для восстановления. Ручное удаление роли — исключительная процедура, поскольку оно может нарушить следующее согласование. Применяйте его только по явному согласованному плану восстановления.

Для операторов: обновления и совместимость

Привязки переходят на общий коннектор, когда Docker-демон целевой ноды обновляется до 2.11.1. Opfield один раз пересоздаёт каждую связанную рабочую нагрузку, чтобы подключить её к новой сети связи, по одной рабочей нагрузке на каждой ноде, следующую — после того как предыдущая работает исправно: Deployment выкатывается по схеме blue/green без простоя, а автономный Container или служба Compose один раз перезапускается. Ничего делать вручную не нужно; имена переменных и учётные данные не меняются. Откат Docker-демона до 2.11.0 автоматически возвращает привязки обратно, тоже с одним пересозданием каждой рабочей нагрузки и не больше чем четырьмя одновременно на ноде — это предел одновременных команд демона; на ноде с большим числом связанных рабочих нагрузок последние переподключаются немного позже. Не удаляйте прежние сети связей и контейнеры вручную ни при одном из этих переходов.

При обновлении коннектора защищённых связей открытые соединения сохраняются до 30 минут, после чего закрываются один раз; клиенты должны переподключаться с ограниченным числом повторов. Перезапуск только приложения Opfield не разрывает установленные потоки привязок, пока Relay и целевые демоны работоспособны. Обновление Relay затрагивает контур данных и может прервать потоки. После перезапуска целевого Docker-демона или ноды проверьте и состояние привязки, и реальный запрос.

Симптом	Сначала проверьте	Следующий безопасный шаг
Привязка не готова	Task, состояние обеих нод и Relay	Дождитесь или повторите поддерживаемое согласование, не создавая второй Container
Приложение получает отказ	Идентичность привязки и конфигурацию приложения	Сверьте права и строку подключения; не используйте учётную запись владельца базы
Привязка пропала после перезапуска	Docker-демон, связь привязки и фактический запрос	Дайте ноде переподключиться и проверьте операции с базами