Приложения

Раздел Приложения запускает ваш код у нас: веб-приложения, API, боты с веб-хуком. Код собирается из исходников, запросы к нему проходят ту же защиту, что и обычный проксируемый сайт — WAF, лимиты запросов, баны и, по желанию, бот-защиту. Открытого порта в интернете у приложения нет: достучаться до него можно только через WebShield.

Раздел находится в кабинете: Услуги → Приложения. Сейчас он в бета-версии. Проект Cloudflare Workers запускается здесь же — как функция.

Проекты и приложения

Проект — общее пространство для приложений одной системы: свои лимиты, свои образы, приложения разных проектов друг друга не видят. Приложение — один запускаемый сервис внутри проекта. В проекте также живут его базы Postgres и хранилища Valkey.

Имена проектов и приложений — строчные латинские буквы, цифры и дефис. Имя приложения и проект, к которому оно относится, после создания не меняются.

Порт. Приложение должно слушать HTTP на порту из настроек (по умолчанию 8080). Тот же номер приходит в переменной окружения PORT — проще всего слушать её.

Выкатка

Выкатить код можно тремя способами:

• Из терминала или CI: webshield apps deploy — CLI упакует каталог и загрузит его (подробности — ниже).
• Архивом с компьютера: вкладка Выкатки → Загрузить .tar.gz.
• Ссылкой на архив: https-ссылка на .tar.gz, которая открывается без входа. Например, архив ветки публичного репозитория GitHub: https://github.com/<владелец>/<репозиторий>/archive/refs/heads/main.tar.gz.

Если приложение лежит не в корне архива, укажите папку внутри архива.

Как собирается. Если в корне (или в указанной папке) есть Dockerfile, сборка идёт по нему. Если нет — стек определяется сам по файлам проекта: Node.js (package.json), Python (requirements.txt, pyproject.toml), Go (go.mod), PHP, Ruby, Java, статический сайт и другие.

Статусы: В очереди → Сборка → Запуск → Работает. Если что-то пошло не так — Ошибка с причиной и журналом сборки (кнопка Журнал сборки). Пока новая версия не запустилась, работает прежняя: неудачная выкатка сайт не роняет.

Первая сборка без Dockerfile может занять несколько минут, повторные — быстрее.

Ограничения: архив — до 100 МБ, сборка — до 30 минут. Одновременно у приложения идёт одна выкатка.

Откат и повторная выкатка

В истории выкаток у работающей версии есть кнопка Выкатить заново, у прежних — Вернуть эту версию. Обе выкатывают уже собранный образ без новой сборки, поэтому занимают секунды. Вернуть можно любую из пяти последних успешных выкаток.

Повторная выкатка нужна и после правки переменных окружения или настроек: они применяются со следующей выкатки.

Переменные окружения

Вкладка Переменные: имя и значение. Значения хранятся зашифрованными и попадают в приложение как переменные окружения. Имена — латиница, цифры и _, не с цифры. PORT и имена, начинающиеся с K_, заняты платформой.

Базы данных: Postgres

В карточке проекта — блок Базы данных: имя, размер (до 20 ГБ) и, если нужно, реплика на другой ноде — она подхватит работу, если основной экземпляр выйдет из строя. Каждая база — свой экземпляр Postgres этого проекта, доступный только его приложениям.

• Бекап — сам: изменения уходят в хранилище непрерывно, полная копия — раз в сутки. Вернуть данные можно на любой момент последних 7 дней — об этом ниже.
• Размер только увеличивается, на ходу. Всем базам и Valkey с диском в проекте отведено 40 ГБ; журнал изменений занимает ещё четверть размера базы, реплика удваивает всё. Когда место в самой базе кончается, запись отвергается с ошибкой No space left on device, а чтение продолжает работать.
• Подключение — под владельцем app к базе app; прав суперпользователя нет.

Восстановление базы

Кнопка Восстановить у базы создаёт из бекапа новую базу — последнее состояние или состояние на выбранный момент. Исходная продолжает работать как ни в чём не бывало, так что можно спокойно сравнить и вытащить нужное.

Чтобы приложение перешло на восстановленную базу, поменяйте ссылку в переменной (например, ${{db.url}} → ${{db2.url}}) и нажмите Выкатить заново. Старую базу удалите, когда она станет не нужна.

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

Из терминала:

webshield apps db window db                                   # с какого и по какой момент
webshield apps db restore db --as db2 --time 2026-10-21T15:00:00+03:00

Valkey: кеш, сессии, очереди

Блок Valkey — хранилище «ключ — значение», совместимое с клиентами Redis. Память — от 64 до 512 МБ. По умолчанию данные только в памяти и пропадают при перезапуске; с отметкой Хранить на диске — переживают его.

Когда память заполнена, запись отвергается (OOM command not allowed), ключи сами не удаляются. Нужен кеш с вытеснением старого — задайте время жизни ключам (EXPIRE).

Ссылки в переменных

Строки подключения не нужно копировать вручную: в переменной окружения напишите ссылку, и при выкатке она заменится настоящим значением.

Ссылка	Значение
${{db.url}}	строка подключения Postgres базы db
${{cache.url}}	строка подключения Valkey cache
${{db.host}}, .port, .user, .password, .database	отдельные части

Например, DATABASE_URL = ${{db.url}} и REDIS_URL = ${{cache.url}}. Ссылка на несуществующую базу останавливает выкатку с ошибкой — прежняя версия продолжает работать. После правки переменных нажмите Выкатить заново.

Свой домен

Вкладка Имена привязывает к приложению имя вашего домена: поддомен (app.example.com) или сам домен.

NS домена указывают на WebShield — всё делается само: имя за минуту-две получает DNS-запись и сертификат и начинает отдавать приложение. Если у имени была своя A, AAAA или CNAME, она сохраняется и вернётся, когда вы отвяжете имя.

Домен подключён записями (NS остаются у вашего провайдера) — под именем появятся две записи. Сначала _acme-challenge.<имя> CNAME: она доказывает, что имя ваше; поставьте её и нажмите Проверить. После подтверждения выпускается сертификат, и тогда вторая запись — само имя CNAME на наш адрес — переводит трафик. Порядок тот же, что у подключения записями; там же — что делать с корнем домена и записями CAA. Отвязанное имя теряет адрес: чтобы вернуть его, привяжите заново и поставьте новые записи.

Защиту настраивают в разделе Хосты — кнопка Настройки защиты у имени ведёт прямо туда: бот-защита, капча, исключения путей, лимит размера запроса, кеш. Режим такого хоста — Приложение: сменить его можно, только отвязав имя.

Журнал

Вкладка Журнал показывает вывод приложения (stdout и stderr): период от 5 минут до 7 дней, поиск по тексту, галочка Следить выводит новые строки по мере появления. Записи хранятся 7 дней.

Пишите журнал в stdout — в файлы внутри контейнера писать бессмысленно, они пропадают при перезапуске.

Сон и пробуждение

Настройка Всегда запущено экземпляров:

• 0 — приложение засыпает, когда запросов нет, и просыпается на первом запросе. Первый ответ после сна приходит на одну-две секунды позже.
• 1 и больше — приложение не засыпает.

Наибольшее число экземпляров ограничивает рост под нагрузкой. Обе настройки применяются со следующей выкатки.

Приложение не должно хранить данные на своём диске: при перезапуске и масштабировании он чистый. Данные держите в базе, файлы — в объектном хранилище.

Оплата

Приложения работают по оплате по факту: проект создаётся сразу, без предоплаты, а счёт за использованное приходит раз в месяц. До первой оплаты доступен один проект с потолком в 1 vCPU и 1 ГБ памяти гарантированного резерва (пиково — до 2 vCPU и 2 ГБ). Цены видны в разделе — над списком проектов.

Платите за то, что работает, посекундно:

• CPU и память — сколько приложение, база или Valkey потребляют на деле, но не меньше гарантированного им минимума. Уснувшее приложение не стоит ничего.
• Диск — заказанный объём томов баз и Valkey с диском, пока они существуют.
• Копии баз и данные функций — объём резервных копий и журнала изменений, а также данные функций, по цене объектного хранилища.

Начисления копятся за сутки и списываются раз в месяц. Над проектами видно, сколько уже начислено и сколько ещё можно потратить до кредитного лимита. Лимит исчерпан или счёт не оплачен — придёт письмо, новые выкатки и базы закроются, а через 7 дней приложения, базы и Valkey всех проектов встанут на паузу: запросы получают ответ 503. Тома и данные остаются, место на дисках продолжает оплачиваться. Оплатите задолженность — всё запустится само за несколько минут.

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

Из терминала и CI

webshield apps deploy --project shop --app web     # упаковать каталог, загрузить, дождаться запуска
webshield apps logs --project shop --app web -f    # журнал с новыми строками
webshield apps deployments --project shop --app web
webshield apps redeploy 42                         # откат на выкатку #42
webshield apps env set DATABASE_URL='${{db.url}}' --redeploy

Переменные, базы и Valkey тоже управляются из терминала — apps env, apps db, apps kv, все команды — в справке CLI.

Чтобы не писать имена каждый раз, положите рядом с кодом webshield.toml:

[app]
project = "shop"
name = "web"

В архив попадает всё, кроме .git и того, что исключают .gitignore и .webshieldignore (синтаксис тот же). Скрытые файлы вроде .npmrc остаются. deploy ждёт, пока выкатка запустится, а при ошибке печатает хвост журнала сборки и завершается с ненулевым кодом — задание CI упадёт.

Для CI выпустите токен для CI в карточке проекта: он умеет только выкатывать этот проект и смотреть статус и журнал — ни создавать приложения, ни менять переменные, ни трогать домены он не может. Пошагово — в руководстве Выкатка из приватного репозитория.

Общие API-токены с областью Приложения выпускаются в настройках.