Перед началом
Deploy запускает образ контейнера как сервис с публичным HTTPS-адресом. Всё описанное на этой странице может выполнить скрипт или ИИ-агент через Management API. Три шага с аккаунтом выполняет человек в браузере.
- Образ должен быть собран для linux/amd64 и размещён в реестре: публичном, приватном репозитории Docker Hub или GitHub Container Registry либо в вашем собственном реестре ACDN.
- Аккаунту нужны подтверждённый адрес электронной почты, баланс больше нуля и одобренная проверка личности. GET /api/user/deploy/requirements показывает, чего не хватает, и возвращает страницу, на которой владелец аккаунта выполняет нужный шаг.
- В одном приложении одновременно работает до 3 экземпляров. Выпуск сервиса без томов временно добавляет один экземпляр, поэтому в приложении с таким сервисом можно настроить до 2 экземпляров.
- Использование оплачивается с баланса аккаунта. Цены указаны в разделе «Оплата» в конце страницы.
Если запрос вернул статус 403, вызовите GET /api/user/deploy/requirements и покажите владельцу аккаунта message и action_url невыполненного требования. Решить это может только он; повторять запрос бесполезно.
Подключение acdn-agent.py
acdn-agent.py — утилита из одного файла: она получает OAuth-токен через device flow и передаёт его в curl. Команда authorize печатает ссылку и код и ждёт; владелец аккаунта открывает ссылку, входит в аккаунт и подтверждает доступ. Токен сохраняется в tmp/acdn-agent/ в текущем каталоге и обновляется автоматически.
curl -fsSLO https://acdn.uz/tools/acdn-agent.py
python3 acdn-agent.py authorize --no-browser
# чего не хватает аккаунту, доступные регионы, ограничения, цены
python3 acdn-agent.py call /api/user/deploy/requirements
Аргументы после «--» передаются в curl. В примерах используется --json, для него нужен curl 7.82 или новее; в более старых версиях передавайте --header "Content-Type: application/json" --data. При ошибке запроса печатается JSON с ошибкой, а код завершения ненулевой. Сообщения возвращаются на языке аккаунта; чтобы получать их на английском, добавьте после «--» --header "Accept-Language: en".
Создание приложения
Приложение объединяет сервисы, тома и точки доступа одного проекта в одном регионе и одной частной сети. Сохраните полученный id. Приложение подготавливается в фоне, обычно за несколько секунд; перед деплоем дождитесь статуса ready.
python3 acdn-agent.py call /api/user/deploy/applications -- \
--json '{"name":"Chat backend","region":"UZ"}'
# повторяйте, пока не появится "status":"ready"
python3 acdn-agent.py call /api/user/deploy/applications/APPLICATION_ID
- Опрашивайте каждые несколько секунд. Подготовка прекращается через 5 минут со статусом failed; тогда отправьте POST /api/user/deploy/applications/prepare/APPLICATION_ID, чтобы повторить её.
- Тома, сервисы и точки доступа можно создавать при любом статусе приложения, кроме удаления. Деплой принимается, только когда статус ready; иначе запрос вернёт 409.
- Не повторяйте запрос на создание после тайм-аута, не проверив список приложений: каждый принятый запрос создаёт ещё одно приложение.
Добавление тома и сервиса
Сначала создайте том, затем сервис, который его монтирует. endpoint_ports запрашивает публичный HTTPS-адрес для каждого указанного порта контейнера; сгенерированное имя хоста возвращается в endpoints.
python3 acdn-agent.py call /api/user/deploy/volumes -- \
--json '{"deploy_application_id":"APPLICATION_ID","name":"data","size_gb":1}'
python3 acdn-agent.py call /api/user/deploy/services -- --json '{
"deploy_application_id": "APPLICATION_ID",
"name": "web",
"image": "ghcr.io/example/chat:1.4.2",
"http_port": 8080,
"health_check_path": "/healthz",
"replicas": 1,
"volume_mounts": [{"deploy_volume_id": "VOLUME_ID", "mount_path": "/data"}],
"environment_variables": [
{"name": "LOG_LEVEL", "value": "info", "is_secret": false},
{"name": "SESSION_SECRET", "value": "change-me", "is_secret": true}
],
"endpoint_ports": [8080]
}'
- http_port — порт, который слушает ваш процесс. Слушайте 0.0.0.0, а не только 127.0.0.1. Переменная PORT не задаётся.
- health_check_path должен отвечать статусом от 200 до 399, когда сервис готов принимать трафик. Проверка отправляется напрямую экземпляру, а не через публичный адрес.
- Поле volume_mounts обязательно; для сервиса без томов передайте пустой массив.
- Сервис, который хранит файл базы данных на томе, должен работать с replicas 1: каждый экземпляр получает собственный отдельный диск.
- Секреты доступны только на запись. Они попадают в контейнер как переменные окружения и никогда не возвращаются через API.
- Пока ничего не запущено: сервис создаётся со статусом draft.
Деплой и ожидание результата
Запрос на деплой сразу возвращает новый деплой в поле latest_deployment. Запомните его id и опрашивайте сервис примерно раз в 5 секунд, пока этот деплой не получит статус active, failed или cancelled. На готовность деплою отводится 10 минут.
python3 acdn-agent.py call /api/user/deploy/services/deploy/SERVICE_ID -- --request POST
# статус сервиса и его последнего деплоя
python3 acdn-agent.py call /api/user/deploy/services/SERVICE_ID
# последние деплои с хронологией; найдите свой по id
python3 acdn-agent.py call /api/user/deploy/services/deployments/SERVICE_ID
- Успех: у вашего деплоя статус active, у сервиса статус running. Сервис отвечает по адресу endpoints[].url через HTTPS.
- Ошибка: поле failure вашего деплоя содержит причину, а progress — перечень событий. Прочитайте логи до любых изменений: они исчезают при замене экземпляра.
- После неудачного деплоя платформа может добавить более новый деплой с action recover, который восстанавливает предыдущий релиз. Тогда сервис снова показывает running, хотя ваш деплой завершился ошибкой, поэтому всегда проверяйте деплой с тем id, который вы запустили.
- Новое имя хоста публикуется в DNS при создании точки доступа. Подождите несколько минут, пока оно начнёт разрешаться повсеместно.
Статус и логи
# состояние проверки работоспособности каждого экземпляра
python3 acdn-agent.py call /api/user/deploy/services/readiness/SERVICE_ID
# последние 1000 строк первого экземпляра; в ответе перечислены все экземпляры
python3 acdn-agent.py call /api/user/deploy/services/logs/SERVICE_ID
# вывод запуска, предшествовавшего последнему перезапуску экземпляра
python3 acdn-agent.py call '/api/user/deploy/services/logs/SERVICE_ID?instance=INSTANCE_ID&instance_uid=INSTANCE_UID&previous=1'
- Логи — это стандартный вывод и стандартный поток ошибок контейнера, с меткой времени перед каждой строкой.
- Доступен только недавний вывод экземпляров, которые ещё существуют. Читайте логи неудачного деплоя сразу.
- INSTANCE_ID и INSTANCE_UID берутся из предыдущего ответа с логами: instances[].id перечисляет экземпляры, а instance_uid относится к экземпляру, чей текст возвращён.
- Для сервиса без экземпляров возвращаются пустой text и instance со значением null.
Повторный деплой, откат, остановка
Чтобы выпустить новый образ, загрузите его в реестр и выполните деплой ещё раз: при каждом деплое тег заново разрешается в дайджест. Чтобы изменить настройки, сначала обновите сервис или его окружение, затем выполните деплой. Сохранённые изменения не действуют до следующего деплоя.
# заменить окружение, затем выпустить его
python3 acdn-agent.py call /api/user/deploy/services/environment/SERVICE_ID -- --request PUT --json '{
"environment_variables": [
{"name": "LOG_LEVEL", "value": "debug", "is_secret": false},
{"name": "SESSION_SECRET", "value": "", "is_secret": true}
]
}'
python3 acdn-agent.py call /api/user/deploy/services/deploy/SERVICE_ID -- --request POST
# вернуться к более раннему релизу: выберите деплой с "can_rollback": true
python3 acdn-agent.py call /api/user/deploy/services/rollback/SERVICE_ID -- \
--json '{"source_deployment_id":"DEPLOYMENT_ID"}'
# запустить новые экземпляры текущего релиза или остановить сервис
python3 acdn-agent.py call /api/user/deploy/services/restart/SERVICE_ID -- --request POST
python3 acdn-agent.py call /api/user/deploy/services/stop/SERVICE_ID -- --request POST
# удалить всё, включая данные на томах
python3 acdn-agent.py call /api/user/deploy/applications/APPLICATION_ID -- --request DELETE
- Запрос окружения заменяет весь список. Существующий секрет, переданный с пустым значением, сохраняет своё значение; переменная, которой нет в списке, удаляется.
- Откат восстанавливает образ, конфигурацию, окружение и секреты выбранного релиза. Данные на томах не откатываются.
- Откат не меняет сохранённую конфигурацию. Следующий deploy снова применит сохранённую конфигурацию, поэтому после отката сохраните и те настройки, которые хотите оставить.
- Для отката подходит только деплой, который когда-либо был активным; любой другой id вернёт 404.
- На deploy, stop, restart и rollback вместе действует ограничение 6 запросов в минуту, и у сервиса может выполняться только один деплой (иначе статус 409). В ограничении учитывается каждый запрос, включая отклонённые.
Оплата
- CPU: 0,02 $ за CPU-час. Учитывается только фактически потреблённое процессорное время, поэтому простаивающий сервис почти ничего не стоит по CPU.
- Память: 0,005 $ за ГиБ-час используемой памяти; измеряется рабочая память экземпляра, включая активно используемый файловый кеш.
- Тома: 0,10 $ за ГиБ-месяц выделенного размера каждого диска, независимо от заполненности и от того, запущен ли сервис. Том ничего не стоит, пока не развёрнут сервис, который его монтирует (до этого allocated_bytes равен 0).
- Исходящий трафик: 0,05 $ за ГиБ, отправленный вашими экземплярами. Трафик, отданный на собственном домене через pull-зону CDN, дополнительно оплачивается как доставка CDN по цене тарифа pull-зоны.
- Нет бесплатного объёма, минимального платежа и платы за само приложение или точку доступа.
- Использование учитывается примерно каждые 30 минут и списывается с баланса аккаунта. API возвращает использование за текущий месяц для каждого сервиса, тома и приложения.
- Для создания приложения нужен баланс больше нуля. При обнаружении отрицательного баланса действующим сервисам Deploy даётся отсрочка оплаты на три дня (72 часа). В течение отсрочки сервисы работают, деплой и перезапуск доступны. Плата за использование продолжает начисляться.
- Письма сообщают о начале отсрочки и точном сроке оплаты, напоминают за 24 часа до его истечения и подтверждают приостановку после остановки сервисов. GET /api/user/deploy/requirements возвращает negative_balance_grace_ends_at и deployments_blocked. Баланс проверяется каждую минуту; до обнаружения отрицательного баланса срок равен null.
- Если к указанному сроку баланс остаётся отрицательным, все сервисы Deploy, включая личные реестры, штатно останавливаются. Деплой, перезапуск и откат возвращают 402 до погашения долга. Пополнение до нуля или выше сбрасывает отсчёт; частичная оплата, оставляющая баланс отрицательным, не продлевает срок.
- После пополнения баланса до нуля или выше приходит подтверждение по почте, а сервисы, приостановленные из-за задолженности, автоматически запускаются с прежним релизом. Восстановление проверяется каждую минуту и дожидается завершения уже начатой остановки. Приостановленный личный реестр запускается раньше сервисов, которым нужны его образы. Вручную остановленные сервисы остаются выключенными. Настройки и сохранённые данные остаются; плата за выделенные тома и Storage реестра начисляется до их удаления.
Точные поля запросов и ответов, ограничения и ответы с ошибками приведены в справочнике Management API.