# keycloak-monitor

Keycloak(`nexthd`レルム)のSSO疎通を定期監視し、異常時にメール通知するアプリ。

2026-08-13にKeycloakのDB接続断(Docker組み込みDNSのSERVFAIL、詳細はプロジェクトメモリ`project_dokploy_multiserver_plan`参照)でプリザンター・XWikiのSSOが停止した際、発覚が偶然の作業中だったことを受けて作成。

## 何を監視しているか

単純なHTTP 200チェック(`.well-known`等)ではKeycloakプロセスが生きているだけでDB接続断を検知できない(実際に2026-08-13はプロセス自体は200を返し続けていた)。そのため、実際に`client_credentials`グラントでtoken発行を行い、DB接続まで含めた実疎通を確認する。

- 監視対象: `${KEYCLOAK_BASE_URL}/realms/${KEYCLOAK_REALM}/protocol/openid-connect/token`
- 使用クライアント: org-master-syncの既存サービスアカウント(client_credentials、権限追加不要)

## アラートの挙動

単発の揺らぎで通知が飛ばないよう、以下の状態機械(`src/alertState.js`)で制御している。

- `ALERT_THRESHOLD`回連続失敗して初めて通知(デフォルト3回=3分間隔なら3分)
- 通知後もダウンが続く場合は`REALERT_INTERVAL_MINUTES`ごとに再通知(デフォルト30分)
- 復旧したら1回だけ復旧通知を送り、状態をリセット

## ローカル開発

```
cd apps/keycloak-monitor
npm install
cp .env.example .env
# .envにKEYCLOAK_CLIENT_SECRETを設定(apps/xwiki/.envのKEYCLOAK_ADMIN_CLIENT_SECRETと同じ値)
npm run dev
```

`http://localhost:3000/` `http://localhost:3000/health` `http://localhost:3000/status`(直近チェック結果・現在のアラート状態)で確認。

```
npm test
```

## 本番同等の動作確認（Docker）

```
docker compose -f docker-compose.local.yml up --build
```

## Dokployへのデプロイ

`.claude/skills/dokploy-webapp/SKILL.md`の手順に準拠。このアプリは外部公開ドメインを持たない(portal-sample-batchと同じパターン、`dokploy-network`内部のみ)ため、`docker-compose.yml`にTraefikラベルは付けていない。

1. Gitea(`https://git73.next-hd.net/mygit-admin/NodeSrv.git`)へpush
2. Dokployで新規Compose(`webapps` project、Provider: Gitea、sourceType: gitea、Compose Path: `apps/keycloak-monitor/docker-compose.yml`)を作成、Node A(`52.193.142.134`)へデプロイ
3. Dokploy Environment画面で`.env.example`の内容を設定。特に以下はDokploy側で運用しながら変更する想定:
   - `NOTIFY_EMAILS`(通知先、カンマ区切りで複数追加可)
   - `CHECK_INTERVAL_SECONDS`(監視間隔)
   - `ALERT_THRESHOLD` / `REALERT_INTERVAL_MINUTES`
   - `KEYCLOAK_CLIENT_SECRET`(機密情報、必ずDokploy側でのみ設定)
4. デプロイ後、コンテナ内から`/status`を確認して監視が回っていることを確認