Files
java-word-pdf/docs/operations/configuration.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

53 lines
3.5 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.
# Конфигурация сервера (`wordpdf-app`)
## Свойства и env
|Свойство|Env|Дефолт|Смысл|
|---|---|---|---|
|`wordpdf.api-key`|`WORDPDF_API_KEY`|пусто|ключ заголовка `X-API-Key`; пусто = аутентификация выключена|
|`wordpdf.max-mb`|`WORDPDF_MAX_MB`|5 (литерал `@Value`)|дефолтный лимит размера входа, МБ (MiB); ≤ 0 на старте → `IllegalStateException`|
|`wordpdf.max-pages`|`WORDPDF_MAX_PAGES`|100 (литерал `@Value`)|дефолтный лимит страниц; ≤ 0 → падение на старте|
|`wordpdf.convert-timeout`|`WORDPDF_CONVERT_TIMEOUT`|`2m`|таймаут одной конвертации (Duration) → 504|
|`spring.servlet.multipart.max-file-size` / `max-request-size`|—|`100MB`|потолок контейнера, зеркалит nginx `client_max_body_size 100m`|
|`spring.servlet.multipart.file-size-threshold`|—|`2MB`|части больше — на диск Tomcat (heap держит только копию одной сериализованной конвертации)|
|`server.forward-headers-strategy`|—|`framework`|работа за префикс-срезающим прокси (`X-Forwarded-*`); `native` не понимает `X-Forwarded-Prefix`|
|`springdoc.api-docs.enabled`|`SPRINGDOC_API_DOCS_ENABLED`|`true`|OpenAPI-спек; `false` → `/v3/api-docs` отдаёт 404|
|`springdoc.swagger-ui.enabled`|`SPRINGDOC_SWAGGER_UI_ENABLED`|`true`|Swagger UI|
|`springdoc.swagger-ui.persist-authorization`|—|`true`|не требовать ключ заново после перезагрузки страницы UI|
Ограничитель очереди (16 мест) — константа `ConversionService.QUEUE_CAPACITY`,
не конфигурируется.
!!! warning "Не объявляйте `wordpdf.max-mb`/`max-pages` в `application.properties`"
Дефолты 5/100 живут литералами `@Value` в `ConvertController`. Пустое значение
ключа в properties **затенит** литерал и сломает старт. Либо не объявляйте
(тогда дефолт), либо конкретное число.
## Примеры запуска
```bash
# ключ + лимиты через env
WORDPDF_API_KEY=$(openssl rand -hex 32) WORDPDF_MAX_MB=10 \
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar
# или аргументами
java -jar wordpdf-app/target/wordpdf-app-1.0.0.jar \
--wordpdf.api-key=secret --wordpdf.convert-timeout=3m
```
В prod-like compose-стеке `WORDPDF_API_KEY` читается из `.env` (fail-closed:
`${WORDPDF_API_KEY:?}` — без него стек не поднимается), на проде ключ приходит
только из Gitea Secret через окружение контейнера.
## Что задала не я, а инфраструктура
|Параметр|Где|Значение|
|---|---|---|
|`client_max_body_size`|`gateway/nginx.conf`|`100m`|
|proxy_read timeout|`gateway/nginx.conf`|300 с|
|heap контейнера app|`Containerfile` (ENTRYPOINT)|`-Xms2g -Xmx2g`; лимит `mem_limit: 3g` — в compose|
|`VITE_BASE`|build-arg образа web|`/pdf-converter/` (путь публикации на проде)|
Значение `maxMb`/`maxPages` конкретного стенда прод-автотесты читают из
`WORDPDF_MAX_MB`/`WORDPDF_MAX_PAGES` (на проде — 5/100).