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:
Pjandro
2026-11-22 21:39:08 +03:00
parent ae7c8b755a
commit b3511f8b74
27 changed files with 1616 additions and 0 deletions
+52
View File
@@ -0,0 +1,52 @@
# Конфигурация сервера (`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).