docs: сайт документации на MkDocs Material
- Контент-дерево docs/: пользователь, REST API, библиотека, архитектура, разработчику, эксплуатация; навигация обязательна (strict-сборка). - docs/agent/ и docs/standards/ из сайта исключены (exclude_docs), ссылки на них — внешние, на Gitea. - Javadoc публичного API core попадает на сайт как docs/apidocs (gitignored).
This commit is contained in:
@@ -0,0 +1,74 @@
|
||||
# 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) маршрутизируется по байтам — это
|
||||
не ошибка.
|
||||
Reference in New Issue
Block a user