Усунення несправностей

Кожен запис — це симптом, його причина та виправлення. Команди припускають Docker Compose; під Helm ті самі перевірки застосовуються до подів.

Спочатку подивіться

Адміністрування → Статус називає більшість проблем сам по собі: пошта, невдалі фонові завдання, сканування нагадувань, бекапи та перевірка відновлення, диски, реліз та його міграції, HTTPS.
Журнали: docker compose logs kept і docker compose logs migrate. KEPT_LOG_FORMAT=pretty робить їх читабельними для ока; KEPT_LOG_LEVEL (за замовчуванням info) задає рівень.
Ідентифікатор запиту: кожна відповідь містить x-request-id; знайдіть його в журналі, щоб відшукати рядок, що належить звіту.
Зонди: /healthz (процес обслуговує HTTP), /readyz (обидва з’єднання з базою даних відповідають), /version (версія, коміт, джерело). Див. моніторинг.
Перевірки, які можна запустити: kept admin backup verify, kept admin storage verify --store local (або s3) та kept admin config (CLI).

`docker compose up` зупиняється на сервісі `bootstrap`

Причина: разовий bootstrap (kept bootstrap) не зміг налаштувати входи до бази даних. Його журнал пояснює, чому: docker compose logs bootstrap. Найчастіші: образ старіший за 1.13.0 і не має команди bootstrap (встановіть KEPT_IMAGE на 1.13.0 або новішу); або петльовий інтерфейс бази даних налаштовано так, що потребує пароль, а KEPT_DB_SUPERUSER_PASSWORD у .env його не містить.

Виправлення: виправте те, що названо в рядку, і запустіть docker compose up -d знову; bootstrap безпечно запускати будь-яку кількість разів.

Kept завершується при запуску з `kept: invalid environment: …` або іншим рядком `kept:`

Причина: середовище перевіряється до початку чогось, і перша проблема зупиняє процес одним рядком, що її називає. Найчастіші:

Рядок каже	Виправлення
`kept: invalid environment: KEPT_PUBLIC_URL`	Встановіть адресу: `docker compose run --rm init` (встановлення)
`KEPT_DATABASE_URL has no password, and KEPT_DB_APP_PASSWORD_FILE: … does not exist`	Bootstrap не запускався: запустіть за допомогою `docker compose up -d`, який спочатку його виконує, а не лише `docker compose up kept`
`KEPT_SECRET_KEY and KEPT_AUTH_SECRET are set together or not at all`	Встановіть обидва або зніміть обидва, щоб використовувати згенеровану пару у томі конфігурації
`<path>/secrets.json exists but …; fix or restore it`	Файл згенерованих ключів пошкоджено: поверніть ключі з набору відновлення
`KEPT_BACKUP_DIR is inside KEPT_DATA_DIR …`	Вкажіть резервну копію на інший диск
`a backup target is set, and the nightly backup dumps the database as kept_owner …`	Надайте воркеру `KEPT_OWNER_DATABASE_URL` (бекапи)
`set one backup target, not …`	Залиште один з `KEPT_BACKUP_DIR`, `KEPT_BACKUP_S3_BUCKET`, `KEPT_BACKUP_SFTP`
`KEPT_STORAGE=s3 needs …`	Додайте налаштування S3, які він називає (сховище)
`KEPT_OIDC_ISSUER is set without KEPT_OIDC_CLIENT_ID`	Додайте ідентифікатор клієнта або зніміть видавця

Кожна змінна описана в довіднику конфігурації.

Змінили пароль бази даних у `.env`, і тепер нічого не підключається

Причина: з compose.yaml Kept 1.13.0 це виправляється само: bootstrap встановлює пароль кожного входу на той, що в .env (або у його файлі), при кожному docker compose up -d. Це відбувається зі старішим compose.yaml, який встановлював паролі один раз, коли том kept-db було вперше створено.

Виправлення: використайте поточний compose.yaml і запустіть docker compose up -d. Зі старим змініть пароль ролі в Postgres так, щоб він збігався, а потім перезапустіть:

docker compose exec db psql -U postgres -c "ALTER ROLE kept_app PASSWORD '<the new password>'"

(Роль — kept_owner, kept_app, kept_auth або kept_system, відповідно до змінної.)

`/readyz` відповідає 503

Причина: одне з двох з’єднань вебу з базою даних (app і system, показані як false у тілі відповіді) не може виконати запит. У журналі є readiness check failed. Під час запуску Kept чекає близько двох хвилин на базу даних, що ще стартує, перш ніж здатися.

Виправлення: перевірте, що docker compose ps db працює нормально, і що вхід із назвою false має правильний пароль (вище). На керованому Postgres перевірте, що існують чотири входи (керований Postgres).

“Цей Kept налаштовано для …” або “The request did not come from this site.”

Застосунок: “Цей Kept налаштовано для адреса. Відкрийте його там.”, на сторінці входу або смугою над застосунком, коли збереження відхилено.
API: 403, “The request did not come from this site.”

Причина: запис, що несе cookie Kept, має надходити з точного походження KEPT_PUBLIC_URL або одного з KEPT_EXTRA_ADDRESSES: схема, хост і порт. Kept порівнює його із заголовком Origin браузера, який є адресою в адресному рядку; зворотний проксі між ними нічого не змінює. Відкриття Kept за іншою адресою (IP замість назви, http замість https, інший порт, внутрішня адреса проксі) робить кожен запис 403. Посилання, QR-коди та запрошення на пошту будуються з того ж значення, і ключі доступу реєструються на його ім’я хоста.

Виправлення: встановіть KEPT_PUBLIC_URL точно на те, що показує адресний рядок браузера, перезапустіть, і завжди відкривайте Kept там. Якщо ви заходите до Kept за двома реальними адресами, наприклад ім’ям у локальній мережі та ім’ям Tailscale, перелічіть інші у KEPT_EXTRA_ADDRESSES (Більше ніж одна адреса).

Kept не запускається після оновлення, а `migrate` завершився з помилкою

Причина: сервіс kept запускається лише після успішного виконання migrate. Перед міграцією бази даних, що містить дані, kept migrate робить знімок перед оновленням, якщо задано ціль резервного копіювання; якщо знімок не вдався, нічого не мігрується і він завершується з причиною (оновлення).

Виправлення: прочитайте docker compose logs migrate, виправте резервне копіювання (ціль, пароль, монтування на migrate) і знову docker compose up -d. Щоб оновитися навмисно без знімка, для цього запуску встановіть KEPT_UPGRADE_SNAPSHOT=off.

Kept відмовляється запускатися з `downgrade_refused`

Причина: образ старіший за базу даних більше ніж на один реліз (або база даних має міграції, які не зробив жоден зареєстрований реліз). На одну версію назад дозволено; більше — ні.

Виправлення: запустіть новіший реліз знову або відновіть знімок перед оновленням, зроблений старішим. KEPT_ALLOW_DOWNGRADE=1 примушує запуск і аудитується; використовуйте лише тоді, коли примітки до релізу це кажуть (повернення на одну версію).

Код налаштування загублений, або налаштування заблоковане

Причина: код друкується один раз процесом, що його створив. Неправильні коди блокують адресу, яка їх надіслала, а багато неправильних кодів блокують сам інстанс.

Виправлення: docker compose run --rm migrate admin setup-code видає новий код і знімає блокування інстансу; блокування на адресу завершується саме. Якщо всі заблоковані одночасно, читайте наступний запис.

Усі потрапляють під одні обмеження входу

Причина: за зворотним проксі Kept для кожного відвідувача бачить адресу проксі, якщо проксі не в KEPT_TRUSTED_PROXIES, тому всі мають спільний набір обмежень.

Виправлення: перелічіть адресу проксі так, як її бачить Kept, у KEPT_TRUSTED_PROXIES (зворотні проксі).

Завантаження не вдаються, або великі фото ніколи не доходять

Причина: Kept відмовляє у файлі, що перевищує KEPT_MAX_FILE_MB (25 МБ за замовчуванням), кодом 413. Проксі попереду часто має власне менше обмеження тіла і завершується раніше.

Виправлення: підніміть обмеження проксі принаймні до KEPT_MAX_FILE_MB (пропустити завантаження).

Камера, встановлення, push або місцезнаходження не працюють на телефонах

Причина: телефони дозволяють їх лише на безпечному походження; адреса у локальній мережі через простий HTTP не є таким. Через HTTP Kept також відмовляє у показі секретних значень, експортах, токенах доступу, OAuth-з’єднаннях, завантаженні набору відновлення та налаштуваннях бекапів.

Виправлення: поставте Kept на HTTPS і встановіть KEPT_PUBLIC_URL на адресу https://.

Збереження постачальника AI або вебхука не вдається: “That address is on a private network.”

Причина: вихідні запити відмовляються до приватних, локальних і зарезервованих адрес (private_address). Постачальник у вашій власній мережі, включно з Compose http://ollama:11434/v1, розв’язується до такої.

Виправлення: адміністратор інстансу вмикає Адміністрування → Налаштування → Дозволити приватні адреси. Див. модель безпеки.

Пошта не надходить

Причина: без KEPT_SMTP_URL і KEPT_SMTP_FROM пошту лише записують у журнал як таку, що має бути надіслана, а Адміністрування → Статус каже, що пошту не налаштовано.

Виправлення: встановіть обидва і перезапустіть (встановлення).

Бекапи не запускаються, або спрацьовує сповіщення “Backup stale”

Причина: зазвичай одне з: немає цілі чи пароля (немає незашифрованого бекапу), воркер без KEPT_OWNER_DATABASE_URL, ціль-директорія не змонтована на контейнері, або така, що не належить користувачеві Kept (uid 10001).

Виправлення: дотримуйтесь бекапів, потім запустіть один вручну і прочитайте, що він каже:

docker compose run --rm --no-deps --entrypoint kept kept admin backup

Він завершується з 1 при попередженні, за назвою:

Попередження	Що це означає і що робити
`backup_suspicious_size`	значно менший за останній вдалий; якщо зменшення реальне, `kept admin backup --accept-size`
`files_unreadable`	restic не зміг прочитати деякі файли; перевірте дозволи тому даних
`blob_checksum_mismatch`	збережений файл більше не збігається з його SHA-256; перевірте диск
`readable_incomplete`	читабельна копія місця розташування не вдалася; журнал її називає

Після збою застаріле блокування restic може блокувати кожен запуск: kept admin backup unlock знімає його (воно відмовляється, поки виконується бекап).

Відновлення відмовляється запускатися

Причина: Kept відновлює лише у порожню базу даних і перевіряє, що pg_restore відповідає основній версії Postgres сервера і що розширення існують.

Виправлення: створіть нову порожню базу даних з розширеннями, як у відновленні; ніколи не спрямовуйте відновлення на робочу.

Після відновлення секретні значення та ключі AI не можна прочитати

Причина: вони запечатані з KEPT_SECRET_KEY, якого немає в бекапі.

Виправлення: помістіть ключі з набору відновлення у .env (з KEPT_SECRET_KEY_VERSION і KEPT_SECRET_KEYS_RETIRED, якщо він їх перелічує) і перезапустіть. Якщо набір перелічує застарілі ключі, запустіть kept admin rotate-key --resume, коли Kept запрацює. Без ключа ці значення втрачено назавжди.

`kept admin` каже `KEPT_OWNER_DATABASE_URL … is required`

Причина: більшості команд admin потрібен вхід власника бази даних, який має лише сервіс migrate.

Виправлення: запустіть їх як docker compose run --rm migrate admin <command>, або для rotate-key, backup, restore і export надайте сервісу kept вхід власника у compose.override.yaml (CLI).

Контейнер лише воркера нездоровий

Причина: з KEPT_ROLE=worker перевірка здоров’я читає файл, до якого звертається цикл завдань (/tmp/kept-worker-alive); вона завершується невдачею, коли цикл не опитував базу даних дві хвилини.

Виправлення: перевірте журнал воркера та його з’єднання з базою даних; застосовуються ті самі перевірки бази даних, що й для /readyz.

Все ще застрягли

Відкрийте задачу з версією з /version, способом запуску Kept і відповідними рядками журналу з видаленим приватним. Проблема безпеки проходить через приватне повідомлення про вразливість (модель безпеки).