Устранение неполадок развёртывания

Четыре сбоя съедают первый деплой. Запустите preflight раньше всего — он назовёт неверную конфигурацию вместо того, чтобы вы гадали:

pnpm import:self-host-check

docker run --rm --env-file .env ghcr.io/capitality-io/mildport-aio \
  bun dist/cli/self-host-check.js

В Kubernetes helm test mildport — та же проверка внутри кластера.

Образы не pull-ятся (ImagePullBackOff)

Образы живут на ghcr.io/capitality-io/* и закрытые. Под в ImagePullBackOff / ErrImagePull почти всегда одно из:

1. Доступ ещё не выдан. Запросите его в Self-hosting в аккаунте для GitHub-пользователя, который будет pull-ить. Ожидающие гранты выглядят как неверный пароль.

2. Узел не залогинен. docker login на ноутбуке кластеру не помогает.

   echo $GITHUB_TOKEN | docker login ghcr.io -u <your-github-username> --password-stdin

   В Kubernetes эти учётные данные — в imagePullSecret:

   kubectl create secret docker-registry ghcr-pull \
     --docker-server=ghcr.io \
     --docker-username=<your-github-username> \
     --docker-password=$GITHUB_TOKEN \
     -n mildport

   imagePullSecrets:
     - name: ghcr-pull

3. Неверный реестр. Мы публикуем в GHCR, не Docker Hub. Если в values всё ещё capitality/mildport, pull никогда не выйдет. См. Доступ к образам.

Каждый импорт возвращает 401

401 значит, ключ лицензии не прошёл проверку. Тело выглядит как { "status": "error", "code": "UNAUTHORIZED", "reason": "…" }. reason — это исправление:

reason	Что значит	Что делать
missing	Нет заголовка Authorization: Bearer …	Передайте ключ из Лицензии
not_configured	На движке нет IMPORT_LICENSE_PUBLIC_KEY	Вставьте публичный ключ со Self-hosting; перезапустите
expired	exp ключа в прошлом	Перегенерируйте в Лицензии; старый действует до истечения
revoked	Id лицензии в IMPORT_LICENSE_REVOKED_IDS	Уберите, или используйте новый ключ
malformed / bad_signature / bad_attestation	Обрезанный ключ, лишние пробелы, или ключ другого издателя	Скопируйте ключ снова; не выпускайте его сами

Отсутствующий публичный ключ — также сбой readiness (checks.license: missing) — движок отвечает на /health и всё равно даёт 401 каждому импорту.

Это не 401:

• 403 ORIGIN_NOT_ALLOWED — ключ действителен, но выпущен со списком origin, в котором нет этой страницы. Перегенерируйте с нужными origin (или пустым списком). Это не CORS.
• CORS в браузере — запрос никогда не получает JSON-тело. Следующий раздел.

Проверьте ключ против работающего движка через GET /api/import/v1/license/verify. Подробнее о ключах: Лицензирование.

Виджет ничего не делает (CORS)

Продакшен-образ (NODE_ENV=production) отклоняет каждый cross-origin браузерный вызов, когда ALLOWED_ORIGINS пуст — включая http://localhost:5173. Localhost в dev-режиме разрешён только вне продакшена.

Задайте точный origin страницы, которая встраивает виджет, со схемой и портом:

ALLOWED_ORIGINS=https://app.example.com,http://localhost:5173

В Helm это app.allowedOrigins. Сервер-к-серверу вызывающие (без заголовка Origin) не затрагиваются; опускайте переменную только если ничего в браузере не говорит с движком.

Список origin на ключе (403 ORIGIN_NOT_ALLOWED) — второй, отдельный замок. CORS решает, может ли браузер говорить; ключ решает, может ли этот origin использовать этот ключ.

Под никогда не становится Ready

GET /health — liveness. Возвращает {"status":"ok","service":"mildport",…}, как только процесс может ответить, до Mongo и лицензий. Readiness-зонд чарта — GET /health/ready. Под, который жив, но никогда не Ready, падает на этом зонде.

curl -i localhost:8090/health/ready

503 с телом:

{
  "status": "not_ready",
  "service": "mildport",
  "checks": { "mongo": "down", "license": "missing" }
}

Check	down / missing значит	Исправление
mongo	Движок не пингует Mongo (неверный URI, network policy, Mongo не поднят)	MONGO_CONNECTION_STRING; подождите Mongo; helm test
license	Нет публичного ключа и режим разработки выключен	IMPORT_LICENSE_PUBLIC_KEY со страницы Self-hosting

license: dev-mode — ready: синтетические ключи работают, и это не стоит отгружать.

Упавшие sidecar не валят readiness. Незаданные decode URL просто значат, что эти семейства файлов отклоняются. PDF, который даёт 503, пока /health/ready — 200, это URL sidecar, не застрявший под.

Дальше: Первый импорт · Конфигурация · Доступ к образам