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
+61
View File
@@ -0,0 +1,61 @@
# Стенды и топология
Наружу публикуется **только nginx-gateway**; контейнер `app` (:8080) наружу не
выставляется никогда. Порты стендов зафиксированы конвенцией сети.
|Стенд|Файл|Вход|Ключ доступа|springdoc|
|---|---|---|---|---|
|prod|`docker-compose.yml` (рендерится CI)|`https://pjandro.ru/pdf-converter/`|обязателен (Gitea Secret)|открыт|
|prod-like (локально)|`compose.yml`|`http://localhost:9010/`|fail-closed: `.env` с `WORDPDF_API_KEY`|выключен env-ами|
|dev|`compose.dev.yml`|`http://<LAN-IP>:9011/`|выключен|включён|
|без контейнеров|`java -jar` + `npm run dev`|`:8080` + `:5173`|выключен|включён|
## Gateway (prod-like/dev)
`gateway/nginx.conf`: `client_max_body_size 100m`, таймауты прокси 300 с,
`resolver` привязан literal-ом к шлюзу docker-сети стенда (10.113.0.1 / 10.112.0.1 —
не путать при копировании).
Маршруты:
|Location|Куда|
|---|---|
|`/api/`|`app:8080` (URI передаётся как есть)|
|`/swagger-ui`, `/v3/api-docs`, `/actuator`|`app:8080`|
|`/` (остальное)|`web` — чистая статика SPA|
`proxy_pass` через переменную + `resolver` — чтобы DNS-имя контейнера резолвилось
на каждый запрос, а не один раз при старте nginx.
## Подъём
```bash
# dev (:9011) — «тестовый сервер» проекта
podman-compose -f compose.dev.yml up -d --build --force-recreate
# prod-like (:9010) — нужен .env с WORDPDF_API_KEY (fail-closed), шаблон .env.example
cp .env.example .env # WORDPDF_API_KEY: openssl rand -hex 32
podman-compose up -d --build
```
!!! warning "--force-recreate"
Без него podman-compose пересоберёт образ, но контейнеры оставит на старом —
будет крутиться jar прошлой сборки.
## Прод
Прод-стек (`docker-compose.yml` + прод `nginx.conf`) **не хранится ни на хосте, ни в
репозитории** — job `deploy` в CI рендерит их из Gitea Variables (ключ — из Secret,
на диск не пишется), затем pull/`up -d --force-recreate`/health-гейты/автооткат.
Копии прод-конфигов на хосте/в репо — нарушение конвенции. Подробности —
[Деплой](deployment.md).
## Порты (конвенция)
|Порт|Кто|
|---|---|
|9010|prod-like gateway|
|9011|dev gateway|
|9012|сайт документации (nginx static, [Docs-сайт](docs-site.md))|
|8080|`java -jar` бэкенд (только localhost)|
|5173|vite dev-сервер SPA|