DongHyeonkaandClaude Opus 5
2109f726fe
기록 84편을 계약 에이전트로 다시 썼다. 기존 71편(kss 25 · virt 46)과, 계약에만 있고 안 쓰여 있던 새 글감 13편이다. 원장 84개를 열어 단계마다 스킬 영수증과 관문 종료 코드를 적었고 verify-pipeline-run.py 가 error 0 으로 닫는다. SSOT 결함 둘을 고쳤다. - kss 의 `약 58일` 이 반입 중 `약 59일` 로 바뀌어 있었다. 원 증거 파일이 「남은 일수: 88일 … 실제 갱신까지 약 58일」로 산수를 직접 적는다. D-4a 쪽 `약 59일` 은 강제 갱신 뒤(`VALID: 89 days`)라 맞는 값이라 그대로 뒀다. - virt §198 의 `11.6GB` 는 §178 의 원 측정 `Mem: 11648`(MiB)과 어긋나는데 원 가이드의 표기 그대로라 고치지 않고 쓰이는 자리에 대조를 적었다. 기록의 수치 오류 셋을 고쳤다 — CASE 요약의 「게스트 셋에 8240MB」(5120+3120 은 둘이다), k3s 편이 같은 것을 여섯·일곱·여덟로 세던 것, no-docker 편의 「셋을 더 든다」(§281 의 표는 네 행이고 디스크 행이 빠져 있었다). 계약을 셋 고쳤다. - kss 의 sourceRepository 리비전이 cdac9b8 이었는데 그 커밋에는 docs/guides/** 28개가 아예 없다. 9465582b 로 바꾸고, 반입한 바이트가 어느 커밋과도 같지 않다는 것을 측정값과 함께 적었다 — 반입은 커밋이 아니라 그 시점의 작업 트리에서 떠 온 것이다(kss 297/306 · virt 12/14 가 작업 트리와 같고, 200 커밋을 거슬러 전수 대조했을 때 가장 가까운 커밋도 28개가 어긋났다). - virt 계약이 「2026-09-11 재배분」이라고 적는데 SSOT 는 재배분 날짜를 적지 않고 재배분 뒤 값은 이미 2026-09-10 측정에 찍혀 있다. - kss 후보 대장이 지나친 절 아홉에 처분을 적었다(warn 9 → 0). 새 글감은 0건이고 넷은 앵커가 h3 슬러그의 접두가 아니라 중간 토막이라 검사기가 못 본 것이었다. style_profile.mjs 의 결함 둘을 고쳤다 — frontmatter 가 문장으로 세어져 (실측 398자짜리 「문장」 하나) 평균 길이를 기준 안으로 밀어 올리고 있었고, engPerSent 의 분자는 목록을 포함한 글에서, 분모는 목록을 걷어낸 글에서 세고 있었다(Question 기록에서 11.94 → 3.86). verify-pipeline.py 전 항목 PASS · error 0 · unittest 334건 OK. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
110 lines
8.4 KiB
Markdown
110 lines
8.4 KiB
Markdown
---
|
|
kind: CONCEPT
|
|
slug: persistent-vs-volatile-user-sessions
|
|
title: persistent-user-sessions 가 세션의 거처를 정한다
|
|
topic: session-custody-across-nodes
|
|
topicName: Keycloak 두 노드가 같은 세션을 읽는 경로
|
|
project: keycloak-session-store
|
|
status: 게시 전
|
|
basisVersion: Keycloak 26.7.0 · persistent-user-sessions 기본 활성 · 24 이전과 대조
|
|
sourceRevision: cdac9b8178391311d8eca1ebc6cac15bb62d79af
|
|
source:
|
|
- final/document.md#코드보다-먼저-드러난-문제-버전-조건
|
|
assets:
|
|
- key: version-conditional-results
|
|
file: ../../../final/assets/version-conditional-results/version-conditional-results.svg
|
|
evidence:
|
|
- ../../../final/evidence/raw/session-replication__01-cross-node-session.txt
|
|
- ../../../final/evidence/raw/a7-volatile-comparison__01-switch-to-volatile.txt
|
|
- ../../../final/evidence/raw/a1-jgroups-transport-block__09-cross-node-under-partition.txt
|
|
- ../../../final/evidence/raw/a7-volatile-comparison__04-a1-rerun-partition.txt
|
|
- ../../../final/evidence/raw/a8-rolling-restart__02-session-survival.txt
|
|
- ../../../final/evidence/raw/a7-volatile-comparison__03-a8-rerun-restart.txt
|
|
- ../../../final/evidence/raw/a2-database-loss__03-four-paths.txt
|
|
- ../../../final/evidence/raw/a7-volatile-comparison__05-a2-rerun-db-loss.txt
|
|
---
|
|
|
|
# persistent-user-sessions 가 세션의 거처를 정한다
|
|
|
|
persistent-user-sessions 가 켜져 있으면 세션은 PostgreSQL 에 남고, 꺼져 있으면 노드 메모리에만 있다. Keycloak 26 은 켜진 쪽이 기본값이고 24 이전은 꺼진 쪽이 기본이었다. 이 실험대에서 그 플래그만 끄고 A층 실험 셋을 다시 돌리자 세 결과가 전부 반대로 나왔다.
|
|
|
|
## 관계
|
|
|
|
- **클러스터는 형성됐는데 세션을 나르는 것은 데이터베이스였다**
|
|
플래그가 켜진 쪽에서 세션이 실제로 어느 경로를 지나는지 SQL 로 확정한 기록이다.
|
|
- **롤링 재시작은 세션을 남기고 캐시만 지웠다**
|
|
같은 플래그가 켜져 있을 때 재시작이 무엇을 남기고 무엇을 지우는지 세어 본 기록이다.
|
|
- **버전과 설정을 결과와 함께 적는다**
|
|
플래그 하나로 결과가 갈린다는 것을 적는 규칙으로 편 기준이다.
|
|
|
|
## 본문
|
|
|
|
<!-- body:start -->
|
|
|
|
## 세션이 기록되는 두 곳
|
|
|
|
`persistent-user-sessions` 는 로그인한 사용자의 세션을 데이터베이스에 쓸지 노드 메모리에만 둘지 정하는 Keycloak 의 기능 플래그다. 켜져 있으면 로그인 하나가 PostgreSQL 의 세션 행 하나가 되고, 꺼져 있으면 그 세션은 로그인을 처리한 노드의 Infinispan 캐시에만 생긴다. Infinispan 은 Keycloak 에 들어 있는 분산 캐시이고, 세션을 데이터베이스에 쓰지 않을 때 다른 노드가 같은 세션을 알게 만드는 것이 이 복제다.
|
|
|
|
세션이 들어가는 테이블 이름은 `OFFLINE_USER_SESSION` 이다. 이 기능이 새 테이블을 만들지 않고 기존 오프라인 세션 테이블을 재사용하기 때문이고, `offline_flag` 컬럼으로 둘을 구분해 `'0'` 이 일반 로그인이다.
|
|
|
|
Keycloak 26 은 이 플래그가 기본으로 켜져 있고 24 이전은 꺼져 있었다. 아래에서 말하는 24 이전 동작은 Keycloak 24 를 설치해서 본 것이 아니라, 26.7.0 한 판 위에서 `--features-disabled=persistent-user-sessions` 로 그 플래그만 끄고 같은 실험을 다시 돌려 재현한 것이다.
|
|
|
|
|
|
|
|
## 클러스터 뷰가 생겨도 세션은 건너가지 않는다
|
|
|
|
플래그가 켜진 상태로 노드 두 대를 올리면 로그에 클러스터 뷰가 찍힌다.
|
|
|
|
```text label="로그에 찍힌 클러스터 뷰"
|
|
ISPN000094: Received new cluster view for channel ISPN:
|
|
[keycloak-0-10001|1] (2) [keycloak-0-10001, keycloak-1-52537]
|
|
```
|
|
|
|
두 노드는 `JGROUPS_PING` 테이블에 자기를 등록해서 상대를 찾는다. 그런데 노드 A 로 로그인하고 노드 B 로 refresh 하면, 노드 B 는 PostgreSQL 로 SQL 을 보내고 문장 로깅이 그 문장을 기록한다. 세션 엔트리는 노드 사이를 건너가지 않고, 각 노드는 자기가 처리한 로그인만 캐시한다.
|
|
|
|
문장 로깅은 데이터베이스가 받은 SQL 을 한 문장씩 기록하도록 켜 두는 설정이다. 노드 B 가 캐시에서 답했는지 데이터베이스를 읽고 답했는지가 여기서 갈린다.
|
|
|
|
두 노드가 같은 답을 내놓는 이유는 복제가 아니라 같은 데이터베이스를 보기 때문이다. `sessions` 캐시 사이에는 경로가 없고 둘 다 `OFFLINE_USER_SESSION` 을 읽는다.
|
|
|
|
## 플래그를 끄면 같은 실험이 반대로 끝난다
|
|
|
|
`--features-disabled=persistent-user-sessions` 로 세션을 노드 메모리에만 두고 A층 실험 셋을 다시 돌렸다.
|
|
|
|
| 실험 | persistent (26 기본) | volatile (24 이전) |
|
|
|---|---|---|
|
|
| A-1 · 7800 차단 후 교차 노드 refresh | `200` — 안 깨진다 | `400 Session not active` — 깨진다 |
|
|
| A-8 · 롤링 재시작 후 refresh | `200` — 세션 생존 | `400 Session not active` |
|
|
| A-2 · DB 정지 중 새 로그인 | `500` | `200` — 된다 |
|
|
|
|
7800 은 JGroups 가 노드 사이 전송에 쓰는 TCP 포트다. 세션이 데이터베이스에 있으면 이 포트를 끊어도 반대편 노드가 같은 행을 읽어 refresh 가 `200` 으로 끝난다. 세션이 노드 메모리에만 있으면 로그인을 처리한 노드와 refresh 를 받은 노드가 갈라진 채로 남아 `400 Session not active` 가 된다.
|
|
|
|
A-1 줄의 뒤집힘은 재고 나서 안 것이 아니다. 세션이 어디 있는지를 처음 확인한 직후, 아직 아무것도 주입하기 전에 예측표를 적었고 거기에 「7800 차단이 A-1과 정반대로 치명적이 된다」가 들어 있었다. 근거 칸은 「그때는 캐시가 진실의 원천」이었다.
|
|
|
|
A-8 의 volatile 쪽은 롤링 재시작 전에 만들어 둔 세션 하나로 refresh 를 찔러 얻은 값이다. 세션이 노드 메모리에만 있으니 프로세스가 끝나면 함께 사라진다는 설명이 그 뒤에 붙지만, 이 `400` 자체는 탐침 토큰 하나를 확인한 결과이고 여러 사용자의 토큰을 각각 찔러 센 것이 아니다.
|
|
|
|
A-2 는 방향이 반대다. 세션을 데이터베이스에 써야 하는 쪽에서는 데이터베이스가 멈춰 있는 동안 새 로그인이 `500` 으로 끝나고, 노드 메모리에만 두는 쪽에서는 같은 상황에서 `200` 이 나온다.
|
|
|
|
## 두 모드가 맞바꾸는 것
|
|
|
|
앞 절의 세 줄은 실험에서 잰 값이고, 아래 표는 그 측정에서 끌어낸 것이다.
|
|
|
|
| 무엇이 갈리나 | persistent | volatile |
|
|
|---|---|---|
|
|
| 재시작 내구성 | 있다 | 없다 |
|
|
| 7800 의존 | 낮다 (무효화만) | 높다 (세션 자체) |
|
|
| DB 부하 | 로그인·refresh 마다 쓰기 | 세션 관련 없음 |
|
|
| 노드 확장 | DB 가 병목 | 복제 트래픽이 N² 로 증가 |
|
|
| 지연 민감도 | DB 왕복에 민감 (A-6) | 클러스터 왕복에 민감 |
|
|
|
|
이 표에서 잰 것은 위 두 줄뿐이다. 재시작 내구성과 7800 의존은 A-8 과 A-1 을 다시 돌려 관측했고, DB 부하 · 노드 확장 · 지연 민감도 세 줄은 이 실험이 재지 않았다. 파드가 둘뿐이라 `N²` 는 볼 수 없다.
|
|
|
|
## 이 설명이 닿는 범위
|
|
|
|
뒤집힌 것은 A-1 · A-2 · A-8 세 건이다. 세 줄 모두 각 실험을 플래그만 바꿔 한 번씩 다시 돌려 얻은 값이고, 같은 조건을 여러 번 반복해 분포를 본 것이 아니다.
|
|
|
|
A-2 줄에는 조건이 하나 더 붙는다. A-7a 가 같은 상황을 캐시 온도별로 다시 재 보니 volatile 에서 데이터베이스가 멈췄을 때의 결과가 그 노드가 어떤 조회를 이미 캐시했는지에 따라 갈렸고, 완전 냉시동에서는 클라이언트 조회조차 캐시에 없어 로그인이 `400` 이었다.
|
|
|
|
이 실험대가 본 것은 Keycloak 한 제품의 이 플래그 하나다. 기본값이 메이저 버전 사이에 바뀐 다른 제품에서도 같은 폭으로 결과가 갈리는지는 여기서 재지 않았다.
|
|
|
|
<!-- body:end -->
|