donghyeon.kang/document-haness
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

refactor: 문서 개선 중

Browse Source
This commit is contained in:
donghyeon-ka
2026-09-21 14:30:55 +09:00
parent c93cdea150
commit 805a18f486
1497 changed files with 525837 additions and 59152 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/keycloak-session-store/final/assets/session-sharing-path/session-sharing-path.alt.md
+7 -10
View File
@@ -2,22 +2,19 @@
## Alternative text
keycloak-0 과 keycloak-1 이 각자 캐시를 갖고 PostgreSQL 을 함께 읽는 구성. 두 캐시 사이에는 세션 복제 경로가 없다.
Keycloak replica 두 개에서 JGROUPS_PING으로는 멤버 발견이, OFFLINE_USER_SESSION으로는 세션 저장과 조회가 갈라지는 두 경로.
## Long description
keycloak-0 과 keycloak-1 은 JGROUPS_PING 테이블을 통해 서로를 발견하고 클러스터 뷰를 형성한다. 그러나 sessions 캐시의 엔트리는 노드 사이로 복제되지 않으며, 각 노드는 자기가 처리한 로그인만 캐시한다. 노드 A 로 로그인한 세션을 노드 B 가 아는 이유는 노드 B 가 PostgreSQL 의 OFFLINE_USER_SESSION 을 직접 읽기 때문이고, 이는 반대편 노드가 날린 SQL 을 문장 로깅으로 잡아 확인했다.
keycloak-0과 keycloak-1은 JGROUPS_PING을 통해 서로를 발견하지만 sessions cache 엔트리를 서로 복제하지 않는다. 다른 노드가 만든 세션을 알아야 할 때는 PostgreSQL OFFLINE_USER_SESSION을 직접 읽는다. discovery와 session sharing은 같은 데이터베이스 안에서도 다른 책임이다.
## Elements and evidence
- **keycloak-0** (service): 로그인을 처리하고 자기 sessions 캐시에만 엔트리를 남긴다. Evidence: L49–L51.
- **PostgreSQL** (datastore): OFFLINE_USER_SESSION 에 세션 행을 보관한다. 두 노드가 같은 행을 본다. Evidence: L48–L52.
- **keycloak-1** (service): 다른 노드가 만든 세션을 캐시로 받지 않고 데이터베이스에서 읽는다. Evidence: L48–L51.
- **JGROUPS_PING** (datastore): 노드가 서로를 발견하는 자리. 여기 등록되어 있다는 것과 세션이 복제된다는 것은 다른 사건이다. Evidence: L44–L46.
- **Keycloak replica 2개** (service): keycloak-0과 keycloak-1은 각자 sessions cache를 갖고 같은 PostgreSQL을 사용한다. Evidence: L75–L81.
- **JGROUPS_PING** (datastore): 노드 discovery와 membership을 위한 테이블이다. 세션 엔트리 복제 경로가 아니다. Evidence: L75–L75.
- **OFFLINE_USER_SESSION** (datastore): 다른 노드가 만든 세션을 직접 읽는 실제 공유 경로다. Evidence: L78–L81.
## Relationships
- **keycloak-0 → JGROUPS_PING:** 멤버 등록. Evidence: L44–L45.
- **keycloak-0 → PostgreSQL:** 세션 INSERT. Evidence: L49–L52.
- **keycloak-1 → JGROUPS_PING:** 멤버 등록. Evidence: L44–L45.
- **keycloak-1 → PostgreSQL:** 세션 SELECT. Evidence: L48–L50.
- **Keycloak replica 2개 → JGROUPS_PING:** 멤버 발견. Evidence: L75–L75.
- **Keycloak replica 2개 → OFFLINE_USER_SESSION:** 세션 저장 · 조회. Evidence: L78–L81.
docs/keycloak-session-store/final/assets/session-sharing-path/session-sharing-path.d2
+5 -10
View File
@@ -1,19 +1,14 @@
# 세션 공유가 실제로 지나는 경로
# Question: 두 Keycloak 노드가 같은 세션을 아는 것은 무엇 때문인가
direction: right
n0: "keycloak-0" {
n0: "Keycloak replica 2개" {
shape: rectangle
}
n1: "PostgreSQL" {
n1: "JGROUPS_PING" {
shape: cylinder
}
n2: "keycloak-1" {
shape: rectangle
}
n3: "JGROUPS_PING" {
n2: "OFFLINE_USER_SESSION" {
shape: cylinder
}
n0 -> n1: "세션 INSERT"
n2 -> n1: "세션 SELECT"
n0 -> n3: "멤버 등록"
n2 -> n3: "멤버 등록"
n0 -> n1: "멤버 발견"
n0 -> n2: "세션 저장 · 조회"
docs/keycloak-session-store/final/assets/session-sharing-path/session-sharing-path.dot
+5 -8
View File
@@ -2,12 +2,9 @@ digraph techviz {
graph [rankdir=LR, splines=ortho, nodesep=0.55, ranksep=0.85];
node [fontname=Helvetica, fontsize=11, margin="0.18,0.12", style="rounded,filled", fillcolor=white, color="#2d4357", penwidth=1.5];
edge [fontname=Helvetica, fontsize=10, color="#364b5f", penwidth=1.4, arrowsize=0.75];
n0 [label="keycloak-0", shape=box, style="rounded,filled"];
n1 [label="PostgreSQL", shape=cylinder, style="rounded,filled"];
n2 [label="keycloak-1", shape=box, style="rounded,filled"];
n3 [label="JGROUPS_PING", shape=cylinder, style="rounded,filled"];
n0 -> n1 [label="세션 INSERT", style=solid];
n2 -> n1 [label="세션 SELECT", style=solid];
n0 -> n3 [label="멤버 등록", style=solid];
n2 -> n3 [label="멤버 등록", style=solid];
n0 [label="Keycloak replica 2개", shape=box, style="rounded,filled"];
n1 [label="JGROUPS_PING", shape=cylinder, style="rounded,filled"];
n2 [label="OFFLINE_USER_SESSION", shape=cylinder, style="rounded,filled"];
n0 -> n1 [label="멤버 발견", style=solid];
n0 -> n2 [label="세션 저장 · 조회", style=solid];
}
docs/keycloak-session-store/final/assets/session-sharing-path/session-sharing-path.drawio
+11 -24
View File
@@ -1,40 +1,27 @@
<?xml version="1.0" encoding="UTF-8"?>
<mxfile host="app.diagrams.net" modified="2026-07-23T00:00:00.000Z" agent="techviz-harness" version="24.7.17" type="device">
<diagram id="session-sharing-path" name="세션 공유가 실제로 지나는 경로">
<mxGraphModel dx="680" dy="422" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
<mxGraphModel dx="680" dy="353" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
<root>
<mxCell id="0"/>
<mxCell id="1" parent="0"/>
<mxCell id="n_keycloak-0" value="keycloak-0&lt;br/&gt;자기 처리분만 캐시" tooltip="로그인을 처리하고 자기 sessions 캐시에만 엔트리를 남긴다. | Evidence: L49-L51" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="70.0" y="111.5" width="150.0" height="71.0" as="geometry"/>
<mxCell id="n_replicas" value="Keycloak replica 2개&lt;br/&gt;keycloak-0 · keycloak-1&lt;br/&gt;sessions cache는 각자" tooltip="keycloak-0과 keycloak-1은 각자 sessions cache를 갖고 같은 PostgreSQL을 사용한다. | Evidence: L75-L81" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="70.0" y="140.0" width="195.0" height="88.0" as="geometry"/>
</mxCell>
<mxCell id="n_keycloak-1" value="keycloak-1&lt;br/&gt;refresh 시 DB 조회" tooltip="다른 노드가 만든 세션을 캐시로 받지 않고 데이터베이스에서 읽는다. | Evidence: L48-L51" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="70.0" y="254.5" width="150.0" height="71.0" as="geometry"/>
<mxCell id="n_discovery" value="JGROUPS_PING&lt;br/&gt;노드 둘 등록&lt;br/&gt;discovery만 담당" tooltip="노드 discovery와 membership을 위한 테이블이다. 세션 엔트리 복제 경로가 아니다. | Evidence: L75-L75" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;shape=cylinder3;boundedLbl=1;backgroundOutline=1;fillColor=#eef6fb;" vertex="1" parent="1">
<mxGeometry x="437.0" y="60.0" width="150.0" height="88.0" as="geometry"/>
</mxCell>
<mxCell id="n_jgroups-ping" value="JGROUPS_PING&lt;br/&gt;노드 둘 등록&lt;br/&gt;세션 복제 아님" tooltip="노드가 서로를 발견하는 자리. 여기 등록되어 있다는 것과 세션이 복제된다는 것은 다른 사건이다. | Evidence: L44-L46" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;shape=cylinder3;boundedLbl=1;backgroundOutline=1;fillColor=#eef6fb;strokeColor=#9ca3af;fillColor=#f9fafb;" vertex="1" parent="1">
<mxGeometry x="392.0" y="60.0" width="150.0" height="114.0" as="geometry"/>
<mxCell id="n_session-store" value="OFFLINE_USER_SESSION&lt;br/&gt;keycloak-0 INSERT&lt;br/&gt;keycloak-1 SELECT" tooltip="다른 노드가 만든 세션을 직접 읽는 실제 공유 경로다. | Evidence: L78-L81" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;shape=cylinder3;boundedLbl=1;backgroundOutline=1;fillColor=#eef6fb;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="425.0" y="220.0" width="174.0" height="88.0" as="geometry"/>
</mxCell>
<mxCell id="n_postgres" value="PostgreSQL&lt;br/&gt;OFFLINE_USER_SESSION&lt;br/&gt;offline_flag=&#x27;0&#x27;&lt;br/&gt;두 노드 공용" tooltip="OFFLINE_USER_SESSION 에 세션 행을 보관한다. 두 노드가 같은 행을 본다. | Evidence: L48-L52" style="whiteSpace=wrap;html=1;rounded=1;strokeWidth=2;fontSize=14;fontStyle=1;fillColor=#ffffff;strokeColor=#2d4357;verticalAlign=middle;shape=cylinder3;boundedLbl=1;backgroundOutline=1;fillColor=#eef6fb;strokeColor=#2563eb;strokeWidth=2;" vertex="1" parent="1">
<mxGeometry x="380.0" y="246.0" width="174.0" height="131.0" as="geometry"/>
</mxCell>
<mxCell id="e_k0-discovery" value="멤버 등록" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_keycloak-0" target="n_jgroups-ping">
<mxCell id="e_discovery-path" value="멤버 발견" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_replicas" target="n_discovery">
<mxGeometry relative="1" as="geometry">
<mxPoint x="330.0" y="123.0" as="offset"/>
<mxPoint x="375.0" y="139.5" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_k0-writes" value="세션 INSERT" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_keycloak-0" target="n_postgres">
<mxCell id="e_session-path" value="세션 저장 · 조회" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_replicas" target="n_session-store">
<mxGeometry relative="1" as="geometry">
<mxPoint x="324.0" y="229.2" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_k1-discovery" value="멤버 등록" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_keycloak-1" target="n_jgroups-ping">
<mxGeometry relative="1" as="geometry">
<mxPoint x="330.0" y="203.5" as="offset"/>
</mxGeometry>
</mxCell>
<mxCell id="e_k1-reads" value="세션 SELECT" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;endArrow=block;endFill=1;" edge="1" parent="1" source="n_keycloak-1" target="n_postgres">
<mxGeometry relative="1" as="geometry">
<mxPoint x="324.0" y="309.8" as="offset"/>
<mxPoint x="369.0" y="228.5" as="offset"/>
</mxGeometry>
</mxCell>
</root>
docs/keycloak-session-store/final/assets/session-sharing-path/session-sharing-path.excalidraw
+74 -341
View File
@@ -4,12 +4,12 @@
"source": "techviz-harness",
"elements": [
{
"id": "edge-k0-discovery",
"id": "edge-discovery-path",
"type": "arrow",
"x": 220.0,
"y": 108.0,
"x": 265.0,
"y": 104.0,
"width": 172.0,
"height": 30.0,
"height": 71.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
@@ -22,9 +22,9 @@
"frameId": null,
"index": null,
"roundness": null,
"seed": 584024925,
"seed": 1106475085,
"version": 1,
"versionNonce": 1230381351,
"versionNonce": 990051078,
"isDeleted": false,
"boundElements": [],
"updated": 0,
@@ -33,11 +33,11 @@
"points": [
[
0.0,
30.0
71.0
],
[
86.0,
30.0
71.0
],
[
86.0,
@@ -50,12 +50,12 @@
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-keycloak-0",
"elementId": "node-replicas",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-jgroups-ping",
"elementId": "node-discovery",
"focus": 0,
"gap": 4
},
@@ -64,10 +64,10 @@
"elbowed": true
},
{
"id": "edge-label-k0-discovery",
"id": "edge-label-discovery-path",
"type": "text",
"x": 285.0,
"y": 111.0,
"x": 330.0,
"y": 127.5,
"width": 90,
"height": 24,
"angle": 0,
@@ -84,9 +84,9 @@
"roundness": {
"type": 3
},
"seed": 239076698,
"seed": 199108613,
"version": 1,
"versionNonce": 442745641,
"versionNonce": 1069221822,
"isDeleted": false,
"boundElements": [],
"updated": 0,
@@ -94,21 +94,21 @@
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "멤버 등록",
"text": "멤버 발견",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "멤버 등록",
"originalText": "멤버 발견",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "edge-k0-writes",
"id": "edge-session-path",
"type": "arrow",
"x": 220.0,
"y": 156.0,
"x": 265.0,
"y": 193.0,
"width": 160.0,
"height": 146.5,
"height": 71.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
@@ -121,9 +121,9 @@
"frameId": null,
"index": null,
"roundness": null,
"seed": 567703682,
"seed": 881837761,
"version": 1,
"versionNonce": 1423801697,
"versionNonce": 471574632,
"isDeleted": false,
"boundElements": [],
"updated": 0,
@@ -140,21 +140,21 @@
],
[
80.0,
146.5
71.0
],
[
160.0,
146.5
71.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-keycloak-0",
"elementId": "node-replicas",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-postgres",
"elementId": "node-session-store",
"focus": 0,
"gap": 4
},
@@ -163,10 +163,10 @@
"elbowed": true
},
{
"id": "edge-label-k0-writes",
"id": "edge-label-session-path",
"type": "text",
"x": 279.0,
"y": 217.25,
"x": 324.0,
"y": 216.5,
"width": 90,
"height": 24,
"angle": 0,
@@ -183,9 +183,9 @@
"roundness": {
"type": 3
},
"seed": 1833086279,
"seed": 1672745407,
"version": 1,
"versionNonce": 1211439496,
"versionNonce": 68217443,
"isDeleted": false,
"boundElements": [],
"updated": 0,
@@ -193,219 +193,21 @@
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "세션 INSERT",
"text": "세션 저장 · 조회",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "세션 INSERT",
"originalText": "세션 저장 · 조회",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "edge-k1-discovery",
"type": "arrow",
"x": 220.0,
"y": 126.0,
"width": 172.0,
"height": 155.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": null,
"seed": 249138565,
"version": 1,
"versionNonce": 1103409032,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
0.0,
155.0
],
[
86.0,
155.0
],
[
86.0,
0.0
],
[
172.0,
0.0
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-keycloak-1",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-jgroups-ping",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-k1-discovery",
"type": "text",
"x": 285.0,
"y": 191.5,
"width": 90,
"height": 24,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 693543637,
"version": 1,
"versionNonce": 134865854,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "멤버 등록",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "멤버 등록",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "edge-k1-reads",
"type": "arrow",
"x": 220.0,
"y": 299.0,
"width": 160.0,
"height": 21.5,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": null,
"seed": 1249142507,
"version": 1,
"versionNonce": 1362277348,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"points": [
[
0.0,
0.0
],
[
80.0,
0.0
],
[
80.0,
21.5
],
[
160.0,
21.5
]
],
"lastCommittedPoint": null,
"startBinding": {
"elementId": "node-keycloak-1",
"focus": 0,
"gap": 4
},
"endBinding": {
"elementId": "node-postgres",
"focus": 0,
"gap": 4
},
"startArrowhead": null,
"endArrowhead": "arrow",
"elbowed": true
},
{
"id": "edge-label-k1-reads",
"type": "text",
"x": 279.0,
"y": 297.75,
"width": 90,
"height": 24,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 1330903131,
"version": 1,
"versionNonce": 222775751,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 13,
"fontFamily": 5,
"text": "세션 SELECT",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "세션 SELECT",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-keycloak-0",
"id": "node-replicas",
"type": "rectangle",
"x": 70.0,
"y": 111.5,
"width": 150.0,
"height": 71.0,
"y": 140.0,
"width": 195.0,
"height": 88.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#ffffff",
@@ -420,9 +222,9 @@
"roundness": {
"type": 3
},
"seed": 969396610,
"seed": 1255192028,
"version": 1,
"versionNonce": 1478355734,
"versionNonce": 1720096067,
"isDeleted": false,
"boundElements": [],
"updated": 0,
@@ -430,12 +232,12 @@
"locked": false
},
{
"id": "node-label-keycloak-0",
"id": "node-label-replicas",
"type": "text",
"x": 80.0,
"y": 121.5,
"width": 130.0,
"height": 51.0,
"y": 150.0,
"width": 175.0,
"height": 68.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
@@ -450,9 +252,9 @@
"roundness": {
"type": 3
},
"seed": 293436436,
"seed": 471343967,
"version": 1,
"versionNonce": 1829861746,
"versionNonce": 1781276630,
"isDeleted": false,
"boundElements": [],
"updated": 0,
@@ -460,90 +262,21 @@
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "keycloak-0\n자기 처리분만 캐시",
"text": "Keycloak replica 2개\nkeycloak-0 · keycloak-1\nsessions cache는 각자",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "keycloak-0\n자기 처리분만 캐시",
"originalText": "Keycloak replica 2개\nkeycloak-0 · keycloak-1\nsessions cache는 각자",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-keycloak-1",
"id": "node-discovery",
"type": "rectangle",
"x": 70.0,
"y": 254.5,
"width": 150.0,
"height": 71.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#ffffff",
"fillStyle": "solid",
"strokeWidth": 2,
"strokeStyle": "solid",
"roughness": 1,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 1492679290,
"version": 1,
"versionNonce": 684109252,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false
},
{
"id": "node-label-keycloak-1",
"type": "text",
"x": 80.0,
"y": 264.5,
"width": 130.0,
"height": 51.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
"fillStyle": "solid",
"strokeWidth": 1,
"strokeStyle": "solid",
"roughness": 0,
"opacity": 100,
"groupIds": [],
"frameId": null,
"index": null,
"roundness": {
"type": 3
},
"seed": 186685213,
"version": 1,
"versionNonce": 935977296,
"isDeleted": false,
"boundElements": [],
"updated": 0,
"link": null,
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "keycloak-1\nrefresh 시 DB 조회",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "keycloak-1\nrefresh 시 DB 조회",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-jgroups-ping",
"type": "rectangle",
"x": 392.0,
"x": 437.0,
"y": 60.0,
"width": 150.0,
"height": 114.0,
"height": 88.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#e7f5ff",
@@ -558,9 +291,9 @@
"roundness": {
"type": 3
},
"seed": 1691553665,
"seed": 416343162,
"version": 1,
"versionNonce": 657056607,
"versionNonce": 505161968,
"isDeleted": false,
"boundElements": [],
"updated": 0,
@@ -568,12 +301,12 @@
"locked": false
},
{
"id": "node-label-jgroups-ping",
"id": "node-label-discovery",
"type": "text",
"x": 402.0,
"x": 447.0,
"y": 70.0,
"width": 130.0,
"height": 94.0,
"height": 68.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
@@ -588,9 +321,9 @@
"roundness": {
"type": 3
},
"seed": 593986141,
"seed": 739181678,
"version": 1,
"versionNonce": 116663944,
"versionNonce": 1366297557,
"isDeleted": false,
"boundElements": [],
"updated": 0,
@@ -598,21 +331,21 @@
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "JGROUPS_PING\n노드 둘 등록\n세션 복제 아님",
"text": "JGROUPS_PING\n노드 둘 등록\ndiscovery만 담당",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "JGROUPS_PING\n노드 둘 등록\n세션 복제 아님",
"originalText": "JGROUPS_PING\n노드 둘 등록\ndiscovery만 담당",
"autoResize": true,
"lineHeight": 1.25
},
{
"id": "node-postgres",
"id": "node-session-store",
"type": "rectangle",
"x": 380.0,
"y": 246.0,
"x": 425.0,
"y": 220.0,
"width": 174.0,
"height": 131.0,
"height": 88.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "#e7f5ff",
@@ -627,9 +360,9 @@
"roundness": {
"type": 3
},
"seed": 1035759464,
"seed": 1116566259,
"version": 1,
"versionNonce": 1511157596,
"versionNonce": 818331454,
"isDeleted": false,
"boundElements": [],
"updated": 0,
@@ -637,12 +370,12 @@
"locked": false
},
{
"id": "node-label-postgres",
"id": "node-label-session-store",
"type": "text",
"x": 390.0,
"y": 256.0,
"x": 435.0,
"y": 230.0,
"width": 154.0,
"height": 111.0,
"height": 68.0,
"angle": 0,
"strokeColor": "#1e1e1e",
"backgroundColor": "transparent",
@@ -657,9 +390,9 @@
"roundness": {
"type": 3
},
"seed": 1404040862,
"seed": 1900921604,
"version": 1,
"versionNonce": 1598470501,
"versionNonce": 273878787,
"isDeleted": false,
"boundElements": [],
"updated": 0,
@@ -667,11 +400,11 @@
"locked": false,
"fontSize": 15,
"fontFamily": 5,
"text": "PostgreSQL\nOFFLINE_USER_SESSION\noffline_flag='0'\n두 노드 공용",
"text": "OFFLINE_USER_SESSION\nkeycloak-0 INSERT\nkeycloak-1 SELECT",
"textAlign": "center",
"verticalAlign": "middle",
"containerId": null,
"originalText": "PostgreSQL\nOFFLINE_USER_SESSION\noffline_flag='0'\n두 노드 공용",
"originalText": "OFFLINE_USER_SESSION\nkeycloak-0 INSERT\nkeycloak-1 SELECT",
"autoResize": true,
"lineHeight": 1.25
}
docs/keycloak-session-store/final/assets/session-sharing-path/session-sharing-path.manifest.json
+5 -5
View File
@@ -2,26 +2,26 @@
"harness_version": "0.2.0",
"spec_id": "session-sharing-path",
"spec_version": "1.1",
"spec_sha256": "e2e4de7934fcac11766554789e18049d2f9bf1dbadc76c946dee5f4e69e628c2",
"spec_sha256": "6a674c49c42588c886d89b957edbdc70a758e06be73c4b0312d2f3c01f041add",
"source_context": {
"document": "docs/keycloak-session-store/final/document.md",
"document_sha256": "609353e10bfd37a9bbb6a79ecf2a32f3d3c02d5d161879a14ad4713e49e7e5e8",
"document_sha256": "28aef96a2bbb94fbb10ade26a71238fee62a5a4d9fa6e7749ae98cfd0a65e560",
"anchor": {
"kind": "heading",
"value": "그런데 첫 실험에서 전제가 무너졌다",
"line": 33
"line": 64
}
},
"outputs": [
"session-sharing-path.svg",
"session-sharing-path.drawio",
"session-sharing-path.mmd",
"session-sharing-path.d2",
"session-sharing-path.dot",
"session-sharing-path.drawio",
"session-sharing-path.excalidraw",
"session-sharing-path.alt.md"
],
"lint_issue_count": 2,
"lint_issue_count": 0,
"assumption_count": 0,
"assumptions_allowed": false,
"composition_profile": "component-flow",
docs/keycloak-session-store/final/assets/session-sharing-path/session-sharing-path.mmd
+5 -8
View File
@@ -1,11 +1,8 @@
%% 세션 공유가 실제로 지나는 경로
%% question: 두 Keycloak 노드가 같은 세션을 아는 것은 무엇 때문인가
flowchart LR
n0["keycloak-0"]
n1[("PostgreSQL")]
n2["keycloak-1"]
n3[("JGROUPS_PING")]
n0 -->|"세션 INSERT"| n1
n2 -->|"세션 SELECT"| n1
n0 -->|"멤버 등록"| n3
n2 -->|"멤버 등록"| n3
n0["Keycloak replica 2개"]
n1[("JGROUPS_PING")]
n2[("OFFLINE_USER_SESSION")]
n0 -->|"멤버 발견"| n1
n0 -->|"세션 저장 · 조회"| n2
docs/keycloak-session-store/final/assets/session-sharing-path/session-sharing-path.svg
+28 -40
View File
@@ -1,8 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<svg xmlns="http://www.w3.org/2000/svg" width="680" height="422" viewBox="0 0 680 422" role="img" aria-labelledby="diagram-title diagram-description">
<svg xmlns="http://www.w3.org/2000/svg" width="680" height="353" viewBox="0 0 680 353" role="img" aria-labelledby="diagram-title diagram-description">
<title id="diagram-title">세션 공유가 실제로 지나는 경로</title>
<desc id="diagram-description">keycloak-0 과 keycloak-1 은 JGROUPS_PING 테이블을 통해 서로를 발견하고 클러스터 뷰를 형성한다. 그러나 sessions 캐시의 엔트리는 노드 사이로 복제되지 않으며, 각 노드는 자기가 처리한 로그인만 캐시한다. 노드 A 로 로그인한 세션을 노드 B 가 아는 이유는 노드 B 가 PostgreSQL 의 OFFLINE_USER_SESSION 을 직접 읽기 때문이고, 이는 반대편 노드가 날린 SQL 을 문장 로깅으로 잡아 확인했다.</desc>
<metadata>{&quot;techviz&quot;:{&quot;spec_version&quot;:&quot;1.1&quot;,&quot;id&quot;:&quot;session-sharing-path&quot;,&quot;profile&quot;:&quot;component-flow&quot;},&quot;source_context&quot;:{&quot;document&quot;:&quot;docs/keycloak-session-store/final/document.md&quot;,&quot;document_sha256&quot;:&quot;609353e10bfd37a9bbb6a79ecf2a32f3d3c02d5d161879a14ad4713e49e7e5e8&quot;,&quot;anchor&quot;:{&quot;kind&quot;:&quot;heading&quot;,&quot;value&quot;:&quot;그런데 첫 실험에서 전제가 무너졌다&quot;,&quot;line&quot;:33}},&quot;evidence_policy&quot;:&quot;Each factual element cites source lines or is marked assumption.&quot;,&quot;diagram_only&quot;:true}</metadata>
<desc id="diagram-description">keycloak-0과 keycloak-1은 JGROUPS_PING을 통해 서로를 발견하지만 sessions cache 엔트리를 서로 복제하지 않는다. 다른 노드가 만든 세션을 알아야 할 때는 PostgreSQL OFFLINE_USER_SESSION을 직접 읽는다. discovery와 session sharing은 같은 데이터베이스 안에서도 다른 책임이다.</desc>
<metadata>{&quot;techviz&quot;:{&quot;spec_version&quot;:&quot;1.1&quot;,&quot;id&quot;:&quot;session-sharing-path&quot;,&quot;profile&quot;:&quot;component-flow&quot;},&quot;source_context&quot;:{&quot;document&quot;:&quot;docs/keycloak-session-store/final/document.md&quot;,&quot;document_sha256&quot;:&quot;28aef96a2bbb94fbb10ade26a71238fee62a5a4d9fa6e7749ae98cfd0a65e560&quot;,&quot;anchor&quot;:{&quot;kind&quot;:&quot;heading&quot;,&quot;value&quot;:&quot;그런데 첫 실험에서 전제가 무너졌다&quot;,&quot;line&quot;:64}},&quot;evidence_policy&quot;:&quot;Each factual element cites source lines or is marked assumption.&quot;,&quot;diagram_only&quot;:true}</metadata>
<defs>
<marker id="arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
<path d="M 0 0 L 10 5 L 0 10 z" />
@@ -49,44 +49,32 @@
.timeline-detail { font-size: 11px; fill: #4b5563; text-anchor: middle; }
</style>
</defs>
<rect class="canvas" width="680" height="422" />
<polyline class="edge kind-write style-solid emphasis-normal" points="220.0,138.0 306.0,138.0 306.0,108.0 392.0,108.0" data-evidence="44-45" />
<rect class="edge-label-bg" x="304.2" y="109.0" width="51.5" height="22" rx="3" />
<text class="edge-label" x="330.0" y="124.0">멤버 등록</text>
<polyline class="edge kind-write style-solid emphasis-normal" points="220.0,156.0 300.0,156.0 300.0,302.5 380.0,302.5" data-evidence="49-52" />
<rect class="edge-label-bg" x="284.9" y="215.2" width="78.3" height="22" rx="3" />
<text class="edge-label" x="324.0" y="230.2">세션 INSERT</text>
<polyline class="edge kind-write style-solid emphasis-normal" points="220.0,281.0 306.0,281.0 306.0,126.0 392.0,126.0" data-evidence="44-45" />
<rect class="edge-label-bg" x="304.2" y="189.5" width="51.5" height="22" rx="3" />
<text class="edge-label" x="330.0" y="204.5">멤버 등록</text>
<polyline class="edge kind-read style-solid emphasis-normal" points="220.0,299.0 300.0,299.0 300.0,320.5 380.0,320.5" data-evidence="48-50" />
<rect class="edge-label-bg" x="284.9" y="295.8" width="78.3" height="22" rx="3" />
<text class="edge-label" x="324.0" y="310.8">세션 SELECT</text>
<g id="node-keycloak-0">
<rect class="node-shape kind-service emphasis-primary role-source" data-evidence="49-51" x="70.0" y="111.5" width="150.0" height="71.0" rx="7" />
<text class="node-label" x="145.0" y="138.5">keycloak-0</text>
<line class="node-detail-divider" x1="84.0" y1="159.5" x2="206.0" y2="159.5" />
<text class="node-detail" x="86.0" y="176.5">자기 처리분만 캐시</text>
<rect class="canvas" width="680" height="353" />
<polyline class="edge kind-write style-solid emphasis-normal" points="265.0,175.0 351.0,175.0 351.0,104.0 437.0,104.0" data-evidence="75-75" />
<rect class="edge-label-bg" x="349.2" y="125.5" width="51.5" height="22" rx="3" />
<text class="edge-label" x="375.0" y="140.5">멤버 발견</text>
<polyline class="edge kind-data style-solid emphasis-normal" points="265.0,193.0 345.0,193.0 345.0,264.0 425.0,264.0" data-evidence="78-81" />
<rect class="edge-label-bg" x="326.5" y="214.5" width="85.0" height="22" rx="3" />
<text class="edge-label" x="369.0" y="229.5">세션 저장 · 조회</text>
<g id="node-replicas">
<rect class="node-shape kind-service emphasis-primary role-source" data-evidence="75-81" x="70.0" y="140.0" width="195.0" height="88.0" rx="7" />
<text class="node-label" x="167.5" y="167.0">Keycloak replica 2개</text>
<line class="node-detail-divider" x1="84.0" y1="188.0" x2="251.0" y2="188.0" />
<text class="node-detail" x="86.0" y="205.0">keycloak-0 · keycloak-1</text>
<text class="node-detail" x="86.0" y="221.0">sessions cache는 각자</text>
</g>
<g id="node-keycloak-1">
<rect class="node-shape kind-service emphasis-primary role-target" data-evidence="48-51" x="70.0" y="254.5" width="150.0" height="71.0" rx="7" />
<text class="node-label" x="145.0" y="281.5">keycloak-1</text>
<line class="node-detail-divider" x1="84.0" y1="302.5" x2="206.0" y2="302.5" />
<text class="node-detail" x="86.0" y="319.5">refresh 시 DB 조회</text>
<g id="node-discovery">
<rect class="node-shape kind-datastore emphasis-normal role-target" data-evidence="75-75" x="437.0" y="73.0" width="150.0" height="62.0" /><ellipse class="node-shape kind-datastore emphasis-normal role-target" cx="512.0" cy="73.0" rx="75.0" ry="13.0" /><path class="storage-bottom" d="M 437.0 135.0 A 75.0 13.0 0 0 0 587.0 135.0" />
<text class="node-label" x="512.0" y="87.0">JGROUPS_PING</text>
<line class="node-detail-divider" x1="451.0" y1="108.0" x2="573.0" y2="108.0" />
<text class="node-detail" x="453.0" y="125.0">노드 둘 등록</text>
<text class="node-detail" x="453.0" y="141.0">discovery만 담당</text>
</g>
<g id="node-jgroups-ping">
<rect class="node-shape kind-datastore emphasis-muted role-support" data-evidence="44-46" x="392.0" y="73.0" width="150.0" height="88.0" /><ellipse class="node-shape kind-datastore emphasis-muted role-support" cx="467.0" cy="73.0" rx="75.0" ry="13.0" /><path class="storage-bottom" d="M 392.0 161.0 A 75.0 13.0 0 0 0 542.0 161.0" />
<text class="node-label" x="467.0" y="100.0">JGROUPS_PING</text>
<line class="node-detail-divider" x1="406.0" y1="121.0" x2="528.0" y2="121.0" />
<text class="node-detail" x="408.0" y="138.0">노드 둘 등록</text>
<text class="node-detail" x="408.0" y="154.0">세션 복제 아님</text>
</g>
<g id="node-postgres">
<rect class="node-shape kind-datastore emphasis-primary role-store" data-evidence="48-52" x="380.0" y="259.0" width="174.0" height="105.0" /><ellipse class="node-shape kind-datastore emphasis-primary role-store" cx="467.0" cy="259.0" rx="87.0" ry="13.0" /><path class="storage-bottom" d="M 380.0 364.0 A 87.0 13.0 0 0 0 554.0 364.0" />
<text class="node-label" x="467.0" y="286.0">PostgreSQL</text>
<line class="node-detail-divider" x1="394.0" y1="307.0" x2="540.0" y2="307.0" />
<text class="node-detail" x="396.0" y="324.0">OFFLINE_USER_SESSION</text>
<text class="node-detail" x="396.0" y="340.0">offline_flag=&#x27;0&#x27;</text>
<text class="node-detail" x="396.0" y="356.0">두 노드 공용</text>
<g id="node-session-store">
<rect class="node-shape kind-datastore emphasis-primary role-target" data-evidence="78-81" x="425.0" y="233.0" width="174.0" height="62.0" /><ellipse class="node-shape kind-datastore emphasis-primary role-target" cx="512.0" cy="233.0" rx="87.0" ry="13.0" /><path class="storage-bottom" d="M 425.0 295.0 A 87.0 13.0 0 0 0 599.0 295.0" />
<text class="node-label" x="512.0" y="247.0">OFFLINE_USER_SESSION</text>
<line class="node-detail-divider" x1="439.0" y1="268.0" x2="585.0" y2="268.0" />
<text class="node-detail" x="441.0" y="285.0">keycloak-0 INSERT</text>
<text class="node-detail" x="441.0" y="301.0">keycloak-1 SELECT</text>
</g>
</svg>
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 7.8 KiB

After

Width:  |  Height:  |  Size: 6.7 KiB