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,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).
|
||||
Reference in New Issue
Block a user