Zimin A.N.
d5268b9395
Новая документация-as-code на платформе Diplodoc (Yandex open-source) с YFM (Yandex Flavored Markdown). Build → static HTML, deployable куда угодно. Что добавлено: - package.json + .yfm + toc.yaml — Diplodoc setup, навигация для sidebar - index.md — главная страница с tabs для разных audiences - README.md — инструкция для contributors Раздел integration/api/ — 11 страниц про интеграцию consumers: - index — обзор + глоссарий - auth — Keycloak service accounts, scope mapping - read-endpoints — GET /dictionaries, list/by-key, spatial filters - events — Kafka outbox топики, partition keys, idempotency, DLQ - webhooks — HMAC, SSRF guard, retry policy, test ping endpoint - bitemporal — validFrom/validTo + history, future-dated entries, bulk close/export - x-references — FK syntax, validation errors, scope hiding, orphan scanner, v2 cascade preview - caching — TTL / push / snapshot strategies, hybrid pattern - errors — full error code reference (validation/auth/conflict/server), retry strategy - best-practices — 33 numbered rules для consumers - bundle-cuod — все 40 справочников с FK графом и сценариями Обновлены: - ops/README.md — link на новую integration/api/, убран inline <br> - ops/slo.md — broken cross-repo links заменены на text references Build: cd docs && pnpm install && pnpm build → ./_dist (20 HTML files, 7.1M) pnpm serve # → http://localhost:8088 CI deploy job для GitLab Pages — в roadmap (см. docs/README.md). Существующий tech/api-integration.md оставлен в toc как legacy (содержимое мигрировано + расширено в integration/api/).
Ordinis НСИ ЦУОД — Operator Runbook
Карточки процедур для on-call инженера. Каждая карточка self-contained: можно открыть в момент инцидента и пройти по шагам без необходимости понимать всю архитектуру.
Indexed by symptom
| Симптом | Карточка |
|---|---|
Spring Boot pod'ы залипли в Init:0/1 после reboot |
vault-unseal.md |
Kafka pod не Running, либо vault-agent не достукивается |
kafka-restart.md |
Метрика ordinis_outbox_dlq_size > 0 |
outbox-dlq.md |
Pod в CrashLoopBackOff с liquibase ошибкой в логах |
db-migrations.md |
| API возвращает 401 на любые запросы | См. §1 ниже |
| API возвращает 500 на конкретный endpoint | См. §2 ниже |
| Admin UI не загружается (502/503) | См. §3 ниже |
1. 401 Unauthorized
Сейчас на staging ORDINIS_AUTH_REQUIRED=true. Anonymous = 401. Проверить:
# 1. Header передан?
curl -v -H "Authorization: Bearer $TOKEN" ... | grep -i authorization
# 2. JWT валиден?
echo $TOKEN | cut -d. -f2 | base64 -d 2>/dev/null | jq
# проверить exp, iss, realm_access.roles
# 3. Issuer правильный?
# должен быть https://auth.nstart.space/realms/nstart
Если JWT прошёл проверку, но 401 — backend логи:
kubectl logs -n ordinis-staging deploy/ordinis-app -c app --tail=50 \
| grep -iE "jwt|invalid_token|expired"
Типичные причины:
Invalid signature— Keycloak ротировал ключи, но бэкенд кэширует старый. Restart pod.Token expired— refresh token не сработал, юзер должен перелогиниться.Issuer mismatch— JWT issued другим Keycloak realm'ом.
2. 500 Internal Server Error на endpoint
# Найти trace_id из ответа
curl -i ... | grep -i traceid
# либо UI показывает traceId в alert
# Найти полный stack trace
kubectl logs -n ordinis-staging deploy/ordinis-app -c app --tail=200 \
| grep "<traceId>"
Типичные причины (в наших коммитах):
could not determine data type of parameter $N— Hibernate JPQL сIS NULLна nullable timestamp. Решение — sentinel value (см. fix audit search).DataIntegrityViolationException dictionary_records_no_overlap— bitemporal exclusion constraint, период пересекается. Friendly 409 уже маппится — если 500 значит код-путь неуспел поймать.JsonMappingException— payload поломан (фронт передал stale schema).
3. Admin UI не загружается / 502 / 503
kubectl get pods -n ordinis-staging | grep admin-ui
| Status | Причина |
|---|---|
ImagePullBackOff |
Тег image не существует в registry. Проверь kubectl describe. Восстановить: kubectl set image deployment/ordinis-admin-ui ui=<registry>/ordinis-admin-ui:main -n ordinis-staging |
CrashLoopBackOff |
nginx config invalid либо resolver недоступен. См. logs. |
Running 1/1, но 502 |
Upstream (writer/read-api) сам в дауне. Проверь те pod'ы. |
4. Что-то ещё — где смотреть
- Pod state:
kubectl get pods -n ordinis-staging - Recent events:
kubectl get events -n ordinis-staging --sort-by='.lastTimestamp' | tail -20 - Resource usage:
kubectl top pod -n ordinis-staging - Logs:
kubectl logs -n ordinis-staging deploy/<name> -c app --tail=100 - Liveness/readiness probes:
kubectl describe pod -n ordinis-staging <pod> - Ingress:
kubectl get ingress -n ordinis-staging - Helm release:
helm history ordinis -n ordinis-staging
5. Эскалация
30 мин downtime, не понятно куда копать → tech lead (zimin.an@nstart.space).
6. Связанные ресурсы
- API integration guide: ../integration/api/index.md (Diplodoc, latest)
- Альтум integration: ../integration/altum-imaging-order.md
- Project state snapshots: см.
docs/status/*-state.mdв repo (исключены из Diplodoc build) - Helm chart:
ordinis-infra/charts/ordinis/ - Vault setup:
ordinis-infra/k8s/vault/setup.sh