- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
5.2 KiB
Troubleshooting
Симптом → причина → действие. Только подтверждённое поведение стендов.
401 «Ключ доступа не передан или неверен»
- Забыт заголовок
X-API-Key/ ключ не совпадает соWORDPDF_API_KEYсервера. - Prod-like стенд не поднимается без
.env— это fail-closed (${WORDPDF_API_KEY:?}), не баг. - Запрос идёт через точечный сегмент (
/actuator/../api/...) — открытые префиксы с../%2eключем не обходятся, так и задумано. - Фронт: экран ключа не появляется, хотя сервер его требует? Проверьте, что
probeApiKey()дошёл до сервера (network-вкладка); ключ из localStorage стирается при 401.
422 «Конвертация отменена: … найдены диаграммы/SmartArt/OLE-объекты»
Не ошибка — сработал включённый error-флаг запроса. Снимите errorOnCharts/
errorOnSmartArt/errorOnOle (по умолчанию выключены). На .doc флаги не
срабатывают в принципе (плейсхолдеры — растры).
503
Очередь конвертации (16 мест) полна: воркер один, все конвертации сериализованы. Повторите позже. Систематически — увеличивайте время ответа вниз (документы поменьше) или масштабируйте количество экземпляров за балансировщиком (каждый со своей очередью).
504
Конвертация дольше wordpdf.convert-timeout (2m). Уменьшите документ (много
больших растров/диаграмм) или поднимите таймаут серверу. Учтите: отменённая
конвертация дожигается, следующий запрос ждёт её в очереди.
413
Тело больше контейнерного потолка multipart (100 МБ) или nginx client_max_body_size 100m — обе границы стоят 100 МБ. Логический лимит входа (wordpdf.max-mb, дефолт
5 МБ) отсекает раньше и даёт 400, так что 413 — это когда серверный лимит поднят
выше 100 МБ бессмысленно либо запрос идёт мимо ожидаемого пути. Файл реально меньше,
но 413? Проверьте, не режет ли промежуточный прокси.
В PDF напечатано «...TO HIDE THESE MESSAGES...»
В classpath нет SLF4J-провайдера — docx4j пишет предупреждения прямо в PDF.
Для библиотеки: оставить slf4j-simple (в транзитивах wordpdf-core) или принести
свой провайдер. Для app: slf4j-simple исключён в пользу logback — если логическая
конфигурация app сломана и SLF4J не инициализирован, верните провайдер.
Картинки диаграмм «мыльные» (ресемпл)
Нарушен контракт префикса media-частей /word/media/chart-*: по нему
ChartImageHandler отключает пересжатие PNG в FOP. Если части переименованы
ручной правкой — верните префикс (DrawingPreRenderer.CHART_MEDIA_URI_PREFIX).
Вместо знаков — # или пустые боксы
#— глифа нет ни в шрифте ранa, ни в fallback, и не сработала резка по покрытию (для docx-пута это регрессия — заведите issue с документом).- Пустой бокс
.notdefдля U+2188/U+218A — известное ограничение OFL-бандла, не чинится. - «Битый»/подменённый шрифт в целом — проверьте алиасы (
Calibri→Carlitoи т.д., Шрифты): подмена метрически совместима и ожидаема.
Стенд крутит старый код после пересборки
podman-compose пересобрал образ, но контейнеры остались на старом — перезапустите
с --force-recreate (Стенды).
.doc не конвертируется (400)
Проверьте сигнатуру: D0 CF 11 E0 A1 B1 1A E1. Word 6–95 и зашифрованные (Office 95
password) документы мостом не поддерживаются → 400/ValidationException. Расширение
.doc при zip-содержимом (переименованный docx) маршрутизируется по байтам — это
не ошибка.