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).
|
||||
@@ -0,0 +1,54 @@
|
||||
# Деплой (прод)
|
||||
|
||||
Наружный вход прода — **`https://pjandro.ru/pdf-converter/`** (пользовательский
|
||||
nginx режет префикс и проксирует на стек конвертера). Публикация полностью
|
||||
автоматизрована: **push в `main` → Gitea Actions**.
|
||||
|
||||
## Пайплайн `main.yml`
|
||||
|
||||
```
|
||||
java + web (тесты/гейты) ──> images-app + images-web (build+push в реестр)
|
||||
──> deploy (рендер прод-стека, pull, up, health-гейты, автооткат)
|
||||
──> autotests (pytest против живого прода; провал → rollback)
|
||||
```
|
||||
|
||||
1. **`java` / `web`** — те же гейты, что на PR (`mvn clean verify` в контейнере
|
||||
без fontconfig; `npm ci`/build/lint).
|
||||
2. **`images-app` / `images-web`** — сборка Containerfile в Nexus-реестр, теги
|
||||
`prod` + неизменяемый `sha-<7 символов>`; web печётся с
|
||||
`VITE_BASE=/pdf-converter/` (путь публикации запекается в образ).
|
||||
3. **`deploy`** — job **рендерит** `docker-compose.yml` и `nginx.conf` в директорию
|
||||
деплоя из Gitea Variables (прод-хост не хранит ни конфигураций, ни секретов;
|
||||
API-ключ — из Secret через окружение деплоя, на диск не пишется), затем
|
||||
login/pull/`up -d --force-recreate app web`, гейты healthy + recreate gateway.
|
||||
Единственное состояние на проде — `.rollback.env` (image id предыдущего рана).
|
||||
4. **`autotests`** — 31 pytest-проверка против живого стенда; провал → откат
|
||||
на образ из `.rollback.env`.
|
||||
|
||||
## Где креды и координаты
|
||||
|
||||
Всё вне репозитория — **Gitea Actions Variables/Secrets** (полный список и настройка
|
||||
branch protection: [`GITEA-vars.md`](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/GITEA-vars.md)).
|
||||
Прод-ключ `WORDPDF_API_KEY` — только Secret. В репо и на диске прод-хоста ключа нет.
|
||||
|
||||
## Ручные операции
|
||||
|
||||
!!! warning "Перед ручным перезапуском прода"
|
||||
Прочитать `/home/pjandro/prod/java-word-pdf/DEPLOY.md` (живёт на прод-хосте,
|
||||
вне репозитория) — там актуальные координаты и процедура. Ручных скриптов
|
||||
деплоя в репозитории нет и не заводить.
|
||||
|
||||
Прод-образ/`compose` правятся только через CI-рендер; копий прод-стека на хосте
|
||||
или в репо быть не должно.
|
||||
|
||||
## Проверка после деплоя
|
||||
|
||||
CI сам докладывает по job'ам (`/actions/runs/<id>/jobs`); руками:
|
||||
|
||||
```bash
|
||||
curl -sf https://pjandro.ru/pdf-converter/actuator/health # 200 {"status":"UP"}
|
||||
curl -s -o /dev/null -w '%{http_code}\n' https://pjandro.ru/pdf-converter/ # 200 SPA
|
||||
```
|
||||
|
||||
Глубина (нюансы runner'ов, `DOCKER_BUILDKIT=0`, реестр, rollback-механика) —
|
||||
[ci-cd.md (репозиторий)](http://git.pjandro.ru/pjandro/java-word-pdf/src/branch/main/docs/agent/ci-cd.md).
|
||||
@@ -0,0 +1,88 @@
|
||||
# Этот сайт документации
|
||||
|
||||
Статический сайт (MkDocs Material) собирается из `docs/` этого репозитория и
|
||||
раздаётся nginx-контейнером на rpi-хосте LAN-сервера:
|
||||
|
||||
- адрес: **`http://192.168.88.23:9012/`** (LAN; наружу не публикуется);
|
||||
- статика: `/home/pjandro/srv/wordpdf-docs/` (rsync без рестарта контейнера);
|
||||
- javadoc публичного API: [`/apidocs/index.html`](/apidocs/index.html).
|
||||
|
||||
## Публикация (с хоста, из репозитория)
|
||||
|
||||
```bash
|
||||
./mise.sh run docs-install # разово: venv docs/.venv + mkdocs-material
|
||||
./mise.sh run docs-deploy # javadoc → strict-build → rsync в ~/srv/wordpdf-docs
|
||||
```
|
||||
|
||||
`docs-deploy` выполняет фиксированный порядок: `mvn javadoc:javadoc` → копия
|
||||
`wordpdf-core/target/site/apidocs` → `docs/apidocs` → `mkdocs build --strict` →
|
||||
`rsync -a --delete site/ ~/srv/wordpdf-docs/`. **Рестарт сервиса не нужен** —
|
||||
nginx раздаёт файлы с смонтированного тома. Strict-сборка ловит битые ссылки и
|
||||
страницы вне `nav`.
|
||||
|
||||
Dev-цикл: `./mise.sh run docs-serve` → `http://127.0.0.1:8000/` (live-reload).
|
||||
|
||||
## Сервис отдачи
|
||||
|
||||
Rootless podman (nginx-контейнер) под user-systemd (`linger=yes`). Юнит
|
||||
`~/.config/systemd/user/wordpdf-docs.service` (вне git; канон текста — здесь):
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Word PDF — сайт документации (nginx static, :9012)
|
||||
|
||||
[Service]
|
||||
# podman run без -d — foreground, systemd видит основной процесс
|
||||
ExecStart=/usr/bin/podman run --name wordpdf-docs --replace -p 9012:80 -v /home/pjandro/srv/wordpdf-docs:/usr/share/nginx/html:ro docker.io/library/nginx:alpine
|
||||
ExecStopPost=/usr/bin/podman rm -f wordpdf-docs
|
||||
Restart=on-failure
|
||||
RestartSec=5
|
||||
TimeoutStopSec=30
|
||||
|
||||
[Install]
|
||||
WantedBy=default.target
|
||||
```
|
||||
|
||||
Разовая установка (на хосте `192.168.88.23`):
|
||||
|
||||
```bash
|
||||
podman pull docker.io/library/nginx:alpine
|
||||
install -d /home/pjandro/srv/wordpdf-docs
|
||||
systemctl --user daemon-reload
|
||||
systemctl --user enable --now wordpdf-docs.service
|
||||
```
|
||||
|
||||
Проверка/управление:
|
||||
|
||||
```bash
|
||||
systemctl --user status wordpdf-docs.service
|
||||
journalctl --user -u wordpdf-docs.service -n 50
|
||||
curl -sf -o /dev/null -w '%{http_code}\n' http://127.0.0.1:9012/
|
||||
```
|
||||
|
||||
Порт 9012: соседние 9010/9011 заняты стендами конвертера (конвенция сети), 8000 —
|
||||
dev-preview. Наружу (wan) не публикуем; наружный nginx `pjandro.ru` при желании
|
||||
добавит владелец сервера отдельно.
|
||||
|
||||
## Почему не Gitea Pages
|
||||
|
||||
Публиковать на инстансе `git.pjandro.ru` (Gitea 1.26.4) проверенным способом «Pages»
|
||||
нельзя — встроенного Pages в этой сборке нет:
|
||||
|
||||
- в swagger инстанса отсутствует эндпоинт `/repos/{owner}/{repo}/pages`,
|
||||
в config cheat sheet — `ENABLE_PAGES`/`PAGES_DOMAIN`;
|
||||
- FAQ инстанса: «Gitea doesn't provide a built-in Pages server»;
|
||||
- в Gitea Actions игнорируется `jobs.*.environment`, не поддерживаются scopes
|
||||
`pages`/`deployments`; тандем `upload-pages-artifact` + `deploy-pages`
|
||||
неработоспособен (`upload-artifact@v4` не поддерживается, `@v3` подвешивается).
|
||||
|
||||
Поэтому публикация — локальная задача `docs-deploy` на том же хосте, где живёт
|
||||
сервис; CI не участвует (docs-файлы не требуют гейтов).
|
||||
|
||||
## Что входит в сайт / не входит
|
||||
|
||||
В сайт попадают все страницы `docs/`, **кроме** `docs/agent/`, `docs/standards/`
|
||||
и `docs/requirements.txt` (`exclude_docs` в `mkdocs.yml`) — это внутренние
|
||||
справочники и спецификации, на них ведут внешние ссылки на Gitea
|
||||
([Внутренние справочники](../internal-guides.md)). Каталог `docs/apidocs/`
|
||||
(gitignored) заполняется задачей `docs-deploy` и копируется mkdocs как статика.
|
||||
@@ -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|
|
||||
@@ -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