Runbook: СКУД Политех (PolytechSKUD*)

Этот runbook привязан к группе алертов polytech_skud в Prometheus. Цель — за минуту понять «наша проблема или их», и кому звонить.

SSH-клиент и правило владельца

Все SSH-команды этого runbook используют существующие настройки доступа и штатный known_hosts своего operator с явным StrictHostKeyChecking=accept-new. Новый target не требует предварительной записи или независимой сверки fingerprint; смена уже известного ключа не принимается молча. Не использовать StrictHostKeyChecking=no/off или отбрасывание known_hosts.

Действует общекомандное правило из /home/olvr/HANDBOOK.md, раздел «SSH: правило владельца», решение 2u1L/hrBEmT: верификацию ключей не инициировать, не выполнять, не обсуждать и не превращать в поручение, вопрос владельцу или условие работы.

Единственная оговорка — изменение уже известного host key: проверить, что переинсталляция сервера нам известна, затем перейти на новый ключ в своём штатном carrier и кратко записать «ключи сменились, перешли на новые». Если известного факта переинсталляции нет, не обходить штатный отказ и не переходить молча; сообщить РП только этот факт, без независимой сверки fingerprint, доверенной консоли и нового поручения на верификацию.

Этот раздел меняет только документационный рецепт. Ключи, known_hosts, SSH-настройки и серверы этим amendment не меняются; production writes по-прежнему требуют разрешения владельца.

Архитектура интеграции

lk.olvery.ru  ──►  back-nfc (PassService)
              ──►  back-acs (ExternalPassController)
                 ──►  ApacsProxyDriver (PHP, retry +5)
                    ──►  apacs-proxy (Go, localhost:8099 в контейнере back-acs)
                       ──►  СКУД Политех (mTLS, 192.168.200.138:443)
                          └─ маршрут через IPSec srv-pstu-vpn.tmpm

Источники алертов

Алерт	Слой	Кто чинит
`PolytechSKUDIntegrationDown`	end-to-end	смотреть оба ниже
`PolytechApacsProxyDown`	наш Go-прокси	мы
`PolytechSKUDHostUnreachable`	хост Политеха	Политех + IPSec
`PolytechSKUDHighLatency`	end-to-end >20с	мы (диагностика)

Когда красное — как локализовать

1. Если только PolytechSKUDHostUnreachable

Хост СКУД Политех (192.168.200.138:443) не отвечает на TCP-connect с gw1.olvr через IPSec.

Проверь алерт IpsecTunnelDown — если красный, разорван туннель через srv-pstu-vpn.tmpm.
Если IPSec зелёный — хост лежит у них. Звонить Политеху, открыть им встречную задачу.

2. Если только PolytechApacsProxyDown

(будет активен после раскатки OLV-3707 на прод)

Наш Go-прокси apacs-proxy внутри контейнера tpark-it.back-acs.latest не отдаёт /health.

ssh -o StrictHostKeyChecking=accept-new srv-prod-app docker exec tpark-it.back-acs.latest curl -sS localhost:8099/health

Если ответ не 200 {«status»:«ok»} — рестарт контейнера:

ssh -o StrictHostKeyChecking=accept-new srv-prod-app docker restart tpark-it.back-acs.latest

Если рестарт не помог — смотреть логи Go-прокси:
```
docker logs tpark-it.back-acs.latest 2>&1 | grep -i apacs-proxy
```
Частые причины: проблемы с mTLS-сертификатами Политеха, истёкший клиентский cert, конфиг APACS_PROXY_URL / провайдера в БД.

3. Если PolytechSKUDIntegrationDown красный, а оба нижних зелёные

End-to-end проба POST /api/nfc/v1/pass отдаёт не-2xx-и-не-400, а наш Go-прокси и их хост по отдельности живы — значит проблема между back-nfc и back-acs.

Проверь логи back-nfc (PassService, AcsApiService.post).
Проверь логи back-acs (ExternalPassService.create) — есть ли вообще запрос, или back-nfc не дошёл до него?
Если запрос дошёл и сразу 5xx — лезть в ExternalPassController.

4. Если PolytechSKUDHighLatency, но Down-алертов нет

Интеграция работает, но >20с на пробу (baseline 12с, max за 24h бывает 29с). Это сигнал-разогрев — если регулярно, СКУД у них тормозит. Длительная высокая latency может стать 504 (apacs-proxy имеет таймаут на upstream).

Открыть письмо/чат Политеху — «у нас фиксируется устойчивая высокая задержка на проверке пропусков, проверьте свою сторону».
На нашей стороне костыли не нужны — пользователь видит длинную проверку пропуска, но успех штатный.

Полезные команды

Прямые пробы

# Наш apacs-proxy (после раскатки OLV-3707):
curl -sS https://lk.olvery.ru/api/acs/v1/health/apacs-proxy
 
# TCP до Политеха через IPSec (с gw1.olvr):
ssh -o StrictHostKeyChecking=accept-new root@gw1.olvr curl -sS -m 5 -k -o /dev/null -w "%{http_code} t=%{time_total}s\n" https://192.168.200.138/
 
# End-to-end (как мониторинг):
curl -sS -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer <см. blackbox_exporter.yml http_post_polytech_skud>" \
  -d '{"deviceId":"bebd6444-70e0-4763-9f51-9626e2420e19","locationId":36,"userId":10760,"deviceDescription":"manual"}' \
  https://lk.olvery.ru/api/nfc/v1/pass

Что куда

back-acs logs: ssh -o StrictHostKeyChecking=accept-new srv-prod-app docker logs tpark-it.back-acs.latest –tail 200
back-nfc logs: ssh -o StrictHostKeyChecking=accept-new srv-prod-app docker logs tpark-it.back-nfc.latest –tail 200
apacs-proxy внутри контейнера: docker exec tpark-it.back-acs.latest ps aux | grep apacs
Prometheus targets: https://prom1.olvr или ssh -o StrictHostKeyChecking=accept-new gw1.olvr curl localhost:9090/api/v1/targets?state=active

История

2026-04-21 OLV-3527 — добавлен blackbox_polytech_skud (1 проба end-to-end), алерты PolytechSKUDIntegrationDown / PolytechSKUDHighLatency.
2026-05-17 Полноценный инцидент 504 на POST /pass — алерт сработал штатно, но было невозможно различить «наш слой или их хост». Михаил Андреев попросил разделить.
2026-05-26 OLV-3707 — добавлены blackbox_polytech_host (TCP до их хоста) и health-эндпоинт /api/acs/v1/health/apacs-proxy (после раскатки back-acs включается blackbox_apacs_proxy_health). Алерты PolytechSKUDHostUnreachable / PolytechApacsProxyDown (последний пока закомментирован, ждёт раскатки).