Частые вопросы и диагностика обновления
Сначала в «Настройки → Системная информация» уточните версию приложения, состояние миграций базы данных и состояние подключения зависимостей, а затем смотрите журналы соответствующего сервиса. Приведённые ниже команды Compose выполняются в корне репозитория; для зависимостей локальной разработки используйте docker compose -f docker-compose.dev.yml, журналы app смотрите в терминале хоста или в его файле журнала — в dev-compose сервиса app нет.
docker compose ps
docker compose logs --tail=200 app
docker compose logs --tail=200 docreader
docker compose logs --tail=200 postgres redisПосле изменения .env пересоздайте соответствующий контейнер командой docker compose up -d <имя сервиса>; docker compose restart не перечитывает переменные окружения контейнера.
Диагностика по симптомам
| Симптом | Порядок проверки и пояснения |
|---|---|
| Сбой загрузки, разбор всё время в обработке | Причина сбоя в деталях документа и трассировка разбора → доступность движка разбора → очередь фоновых задач; см. Разбор документов и Асинхронные задачи |
| Изображения видны на локальной машине, но не открываются на других устройствах | Проверьте, не содержит ли возвращаемый адрес localhost, имя сервиса контейнера или недоступный адрес объектного хранилища; получив resource://, сторонний клиент разбирает его по Доступ к файлам и не может использовать напрямую как URL изображения |
| После сохранения конфигурации возвращаются старые значения | Проверьте, не переписывает ли ответ прокси/кеш браузера, не подключились ли вы к другой среде или не переключили ли пространство; для встроенных моделей дополнительно проверьте синхронизацию YAML при запуске; см. Управление моделями |
| После обновления сообщает о нехватке прав | Сверьте текущую роль пространства, принадлежность ресурса и область возможностей API Key; см. Аутентификация и авторизация. Администратор платформы и Owner пространства — разные понятия |
| Agent сообщает, что модель не готова | Убедитесь, что модель, на которую ссылается агент, ещё существует и её конфигурация полна, выполните проверку соединения с моделью; см. Управление моделями |
| Подключение к источнику данных, модели или векторной базе в частной сети отклонено | Проверьте проверку SSRF и политику портов; по Справочнику конфигурации разрешите только нужные цели |
| Ошибка «разрешён исходящий трафик только по белому списку» | В развёртывании включён SSRF_DNS_WHITELIST_ONLY: хосты вне белого списка отклоняются ещё до разрешения DNS. Добавьте целевой хост в SSRF_WHITELIST или SSRF_WHITELIST_EXTRA и пересоздайте контейнеры app / docreader, см. Подробная конфигурация |
| Эндпоинт входа возвращает HTML 404 | Проверьте, не совпадает ли SEARXNG_PORT с APP_PORT (по умолчанию 8080). В Linux после того, как SearXNG занял 127.0.0.1:8080, запросы к localhost:8080 сначала попадут в SearXNG. Оставьте SearXNG на порту 8888 или другом свободном |
При загрузке образа MinIO возникает pull access denied или 401 UNAUTHORIZED | MinIO закрыл анонимную загрузку из Docker Hub и quay.io. Текущие Compose и Helm используют собранный сообществом pgsty/minio; в собственных файлах оркестрации нужно синхронно изменить адрес образа |
После обновления перестали работать встроенная страница или подписанные ссылки (страница встраивания показывает embed session signing key is not configured, в журнале запуска есть [startup-env] no usable signing key) | Ключ подписи берётся из SYSTEM_SIGNING_KEY, при отсутствии — откат к SYSTEM_AES_KEY; примерные ключи и ключи короче 16 символов не могут подписывать. Сгенерируйте openssl rand -hex 32 и задайте SYSTEM_SIGNING_KEY, не меняйте ради этого SYSTEM_AES_KEY, иначе сохранённые учётные данные нельзя будет расшифровать. В v0.8.2 изменён алгоритм подписи встроенных сессий: все сессии встраивания, выданные до обновления, перестают действовать, посетителям нужно зайти заново; при развёртывании с несколькими репликами используйте один ключ |
| После обновления бот DingTalk больше не отвечает | С v0.8.2 DingTalk поддерживает только режим Stream, миграция обновления меняет канал webhook на websocket. Нужно включить режим Stream для этого приложения в консоли разработчика DingTalk, см. Интеграция с IM |
| Фоновая очередь постоянно накапливается | Диагностируйте по времени ожидания самой старой задачи, активным worker и квоте нижестоящей системы; увеличение числа worker не повышает квоту провайдера моделей, см. Оценка ёмкости |
| Навык добавлен в каталог, но не выполняется | Каталогизация и установка в песочницу — два шага; проверьте запись установки, выбор песочницы агентом и область действия навыка, см. Каталог навыков и песочница |
| После обновления не находится локальная песочница | Бэкенд local удалён, настройте заново Docker, CubeSandbox или E2B; см. Развёртывание песочницы и диагностика |
| Локальный браузер сопряжён, но не выполняет задачи в браузере | В поле ввода умного рассуждения нужно включить локальный браузер; приостановленные задачи нужно продолжить явно, см. Локальный браузер |
| Страница встраивания не загружается или возвращает 403 | В белый список внесите фактический Origin узла; проверьте CSP, обратный прокси и Origin обмена в безопасном режиме, см. Канал встраивания |
| Тест приложения Feishu успешен, но папки не загружаются | Тест соединения проверяет только идентичность приложения, для папок ещё нужна авторизация; см. Подключение облачного диска Feishu |
Сбой миграции базы данных
По умолчанию приложение выполняет миграции при запуске. После сбоя оно всё равно может запуститься, поэтому «страница открывается» не значит, что структура таблиц успешно обновлена. Версия миграции, отметка dirty и ошибки в системной информации, а также журнал запуска app — это точки входа для диагностики.
Не предполагайте, что неудачная миграция полностью откатилась. Фактическое состояние зависит от границ транзакций SQL и места сбоя. Перед восстановлением сохраните журналы, сделайте резервную копию базы данных, сверьте файл миграции неудачной версии с фактической схемой; не пропускайте ошибку удалением тома данных или прямым изменением номера версии.
PostgreSQL использует migrations/versioned/, SQLite — migrations/sqlite/. Приведённые ниже команды Make вызывают скрипт миграций PostgreSQL; базу SQLite в Lite следует обрабатывать соответствующим драйвером и каталогом миграций, DSN PostgreSQL здесь не подходит.
make migrate-versionТакже можно выполнить проверку только на чтение в целевой базе данных:
SELECT version, dirty FROM schema_migrations;
-- Следующие два запроса только для PostgreSQL
SELECT version();
SELECT extname, extversion FROM pg_extension;Отсутствующие расширения или нехватка прав
Отсутствие gin_trgm_ops обычно соответствует pg_trgm, отсутствие типа vector — pgvector, а функциональность BM25 зависит от pg_search в ParadeDB. Сначала уточните, к какой базе данных фактически подключается приложение, затем попросите администратора базы данных проверить пакеты расширений, расширения внутри базы и владение объектами.
SELECT name, default_version, installed_version
FROM pg_available_extensions
WHERE name IN ('pg_trgm', 'vector', 'pg_search');Отсутствие файлов расширения и нехватка прав SQL — разные проблемы; CREATE EXTENSION IF NOT EXISTS не устанавливает автоматически пакеты ОС и не обновляет уже существующие расширения. Создавайте только те расширения, которые действительно нужны текущему развёртыванию, и не превращайте развёртывание с внешним поисковым движком в поиск по PostgreSQL по ошибке.
Обновление образов и версий расширений существующих баз ParadeDB — в разделе Обновление ParadeDB.
Состояние Dirty
AUTO_RECOVER_DIRTY включён по умолчанию и при запуске пытается сбросить версию миграции и запустить её заново. Это механизм повторной попытки; он не исправит отсутствие расширений, нехватку места на диске или различия схемы, вызванные ручными изменениями.
При ручном восстановлении сначала остановите запись в приложение и проверьте, не оставила ли неудачная миграция частичных изменений. Только убедившись, что база данных соответствует предыдущей успешной версии и неудачную миграцию можно безопасно запустить заново, используйте force. Он изменяет только отметку версии миграции и не выполняет откатывающий SQL. Например, убедившись, что предыдущая успешная версия — 98:
make migrate-force version=98
make migrate-up98 здесь — пример; обязательно замените его на реально подтверждённую версию, нельзя механически вычитать единицу из числа в ошибке. При сбое начальной миграции нужно отдельно проверить состояние инициализации. После восстановления перезапустите app, убедитесь, что системная информация больше не показывает ошибок, и проверьте затронутые функции.
Прерывание параллельного создания индекса
Миграция 000106 создаёт индекс для messages с помощью CREATE INDEX CONCURRENTLY, во время построения запись не блокируется. Если построение прервано (перезапуск процесса, тайм-аут, нехватка места на диске), остаётся INVALID-индекс idx_messages_session_created_id, и IF NOT EXISTS его не пересоздаст. Сначала проверьте и удалите этот индекс, затем восстановите состояние миграции по описанному выше и запустите заново:
SELECT indexrelid::regclass, indisvalid FROM pg_index
WHERE indexrelid = 'idx_messages_session_created_id'::regclass;
DROP INDEX CONCURRENTLY IF EXISTS idx_messages_session_created_id;Нехватка места на диске и различия схемы
Построение индекса требует дополнительного временного пространства. При No space left on device проверьте ёмкость тома данных базы данных и временного каталога, освободите место и затем восстановите по фактическому состоянию миграции.
Если типы столбцов, индексы или ограничения не совпадают с ожиданиями миграции, сверьтесь с файлом неудачной миграции и предыдущей успешной версией; не повторяйте ошибочный SQL снова и снова прямо в продакшн-базе. Если нужно воспроизвести операцию записи, сначала проверьте её в изолированной базе, восстановленной из резервной копии.
Что предоставить при сообщении о проблеме
Укажите версию/номер commit приложения, время сбоя, полный текст ошибки, тип и версию базы данных, версию миграции/состояние dirty, а также соответствующие нестандартные настройки. Сначала удалите из журналов токены, пароли, строки подключения и содержимое документов. Реализация миграций базы данных и способ разработки — в разделе База данных и миграции.