Files
java-word-pdf/docs/operations/troubleshooting.md
T
Pjandro b3511f8b74 docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура,
  разработчику, эксплуатация; навигация обязательна (strict-сборка).
- docs/agent/ и docs/standards/ из сайта исключены (exclude_docs),
  ссылки на них — внешние, на Gitea.
- Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
2026-11-22 21:39:08 +03:00

75 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` и т.д.,
[Шрифты](../architecture/fonts.md)): подмена метрически совместима и ожидаема.
## Стенд крутит старый код после пересборки
podman-compose пересобрал образ, но контейнеры остались на старом — перезапустите
с `--force-recreate` ([Стенды](stack.md)).
## `.doc` не конвертируется (400)
Проверьте сигнатуру: `D0 CF 11 E0 A1 B1 1A E1`. Word 6–95 и зашифрованные (Office 95
password) документы мостом не поддерживаются → 400/`ValidationException`. Расширение
`.doc` при zip-содержимом (переименованный docx) маршрутизируется по байтам — это
не ошибка.