Найдите последний этап и полную ошибку: сборка, SSH, БД, миграции, backend или HTTPS. От этого зависит следующий шаг.
Посмотрите логи
Работайте из корня проекта: Source — на VPS под пользователем deploy, Archive/Registry — на управляющем компьютере, prod-local — на своём компьютере.
bash ./deploy/control status --env local --json
bash ./deploy/control logs --env local --service backend
bash ./deploy/control logs --env local --service postgres
bash ./deploy/control logs --env local --service frontend
Для сервера замените local на имя окружения. При make dev backend и Vite пишут в его терминал, это не Docker-сервисы. Перед передачей логов удалите секреты и строки подключения с паролями.
Сборка не завершилась
| Ошибка | Что сделать |
|---|---|
| Docker unavailable | Запустите Docker и проверьте выбранный context |
| Engine API 1.49 required | Проверьте версии клиента и daemon |
| Containerd image store required | Включите нужный режим Docker для локального релиза |
| Release output already exists | Укажите новое имя JSON релиза |
| Port already allocated | Найдите процесс на настроенном порту, не останавливая чужие окружения |
DNS или сетевой timeout
lookup ...: i/o timeout сообщает, что не удалось получить адрес указанного сервиса. Это ещё не доказательство ошибки кода, региональной блокировки или проблемы определённого провайдера.
Проверьте адрес из сообщения там, где выполнялся шаг: Source собирается на VPS, Archive/Registry — на компьютере или runner. Docker может использовать другие DNS/proxy-настройки, чем терминал. Различайте registry, Go/npm и публичный HTTPS. После устранения причины повторите build; если operation ID уже создан, сначала разберите операцию. Увеличение таймаута и отключение проверок не исправляют DNS.
Deploy остановился
| Состояние | Следующее действие |
|---|---|
| Unresolved reservation | Status/reconcile и исходная операция; не удаляйте reservation |
| Existing schema без current | Разберите первый запуск, не повторяйте его как пустую установку |
| Environment changed | Сверьте рабочий JSON с действующей конфигурацией; для delivery/backup используйте reconfigure |
| Migration checksum mismatch | Верните исходный зарегистрированный SQL; не меняйте checksum в БД |
| Unknown SQL file | Зарегистрируйте custom-миграцию штатным способом |
| Не найден образ релиза | Верните именно записанный образ или архив; новый образ с прежним тегом не заменяет его |
Certbot не выпустил сертификат
Сообщение Certbot failed — итог; причина находится в файле certbot.log, путь к которому печатает команда. Откройте на VPS именно этот файл:
tail -n 80 /ПУТЬ_ИЗ_ОШИБКИ/certbot.log
Если центр сертификации получил HTTP 403 на /.well-known/acme-challenge/, запрос дошёл до HTTP-сервера, но файл проверки не выдан. Сопоставьте IP в логе с VPS и откройте журнал frontend:
bash ./deploy/control logs --env production --service frontend
Permission denied для /var/www/acme/ указывает на права папки проверки. В актуальных инструментах она подготавливается доступной для Nginx. Не меняйте права на всё runtime-хранилище: рядом находятся секреты и БД. Если запрос блокирует внешний proxy, исправьте его правило для пути проверки.
Предупреждение Nginx can not modify ... default.conf (read-only file system?) само по себе не означает сбой: важны результат проверки конфигурации и следующая ошибка.
После устранения причины выполните resume исходной операции. Не запускайте новый provision поверх неё.
Старые инструменты после обновления генератора
Ошибки configuration must be a regular file при новом UI-профиле, No such image: sha256:... при существующем образе Docker 29 и повторная загрузка secrets.json при resume исправлялись в инструментах генератора. Сначала выполните Generate актуальным генератором, передайте изменения проекта через Git на VPS и разберите текущую операцию.
Нужна ли пересборка, зависит от файла: deploy/control и управляющий production.sh читаются из checkout; код приложения и инструменты внутри ops-образа требуют нового build. Обновлённый checkout не заменяет автоматически сохранённые инструменты уже начатой операции. Не меняйте вручную ID образов или JSON релиза.
Backend запущен, но /readyz = 503
503 означает, что приложение не готово. Смотрите логи мигратора/backend и соответствие миграций релизу. В раннем 0.8.1 проверка искала старые системные имена миграций; исправленный шаблон использует manifest. Для этого случая Generate и сборка нового образа нужны, фиктивные записи schema_migrations — нет. Если первый запуск не записал current, начните с восстановления.
HTTPS или вход не работает
Если curl с локальной --cacert .../pki/ui-ca.crt работает, а браузер нет, проверьте доверие CA, hosts, адрес и порт из JSON. Логина по умолчанию нет: первого суперадминистратора создают через bootstrap-superadmin. При 401/403 проверьте аккаунт и права именно в этом окружении; вход в Generator UI от него независим.
Не открываются изображения
Проверьте, перенесены ли файлы вместе с БД, верны ли папка и права backend. При смене local-пути нужна привязка к новому месту после восстановления файлов. Не подменяйте её для пустой папки и не создавайте marker-файлы вручную.
В системе администрирования нужен доступ к исходной persistent-сущности; virtual-доступ не заменяет его. Прямые ссылки размеров external API используют отдельные правила доступа по ссылке и кеширование — проверяйте именно ваш способ загрузки.
После исправления
Изменения кода не обновляют уже работающий образ. При правке модели/шаблона выполните Generate, затем build и deploy. Если предыдущая операция не завершена, сначала определите её результат. Не удаляйте БД или .state как универсальное средство исправления.
Диск заполнен после нескольких сборок
Проверьте df -h / и docker system df именно на VPS. Образы, кэш сборки и файлы *.images.tar занимают место независимо друг от друга. Подробная последовательность команд — в очистке диска. Не удаляйте вручную /var/lib/docker, /var/lib/containerd или state окружения.
Docker не скачивает базовый образ
Source не требует вашего registry, но Docker всё равно скачивает базовые образы и зависимости. При lookup auth.docker.io ... timeout проблема возникла при обращении к DNS/registry. Проверьте доступ с VPS и повторите docker pull для образа из ошибки. При network is unreachable с IPv6 проверьте сетевую настройку сервера. Не удаляйте рабочие образы или БД ради повторения сборки. Уже имеющиеся сервисные образы build использует локально; строки source=local и source=pull показывают, откуда они взяты.
Удалили ops и control больше не работает
Ops нужен и после выпуска. Для Source/Archive найдите архив текущего релиза по state/current.json и загрузите его через docker load -i /полный/путь/к/архиву.images.tar. Эта команда возвращает образы в Docker и не перезапускает приложение. Для Registry восстановите точный образ по ссылке .ops из записи релиза через docker pull. Не собирайте другой образ под старым именем в качестве замены.