feat(ch2): 2.5 \u8eab\u4efd\u5b9e\u4f53\u7ae0\u8282\u6587\u6863 + 5 \u6b65\u5b9e\u9a8c

Author: lonegunmanb

docs/.vitepress/config.mjs

@@ -33,7 +33,8 @@ export default defineConfig({
              { text: '2.1 "Dev" 开发模式的适用边界与安全风险预警', link: '/ch2-dev-mode' },
              { text: '2.2 封印与解封（Seal/Unseal）机制的密码学底层原理', link: '/ch2-seal-unseal' },
              { text: '2.3 租约（Lease）、无感续期与强制撤销的生命周期管理', link: '/ch2-lease' },
-             { text: '2.4 认证（Authentication）与令牌（Tokens）树状层级关系本质', link: '/ch2-auth-tokens' }
+             { text: '2.4 认证（Authentication）与令牌（Tokens）树状层级关系本质', link: '/ch2-auth-tokens' },
+             { text: '2.5 身份实体（Identity Entity）：打通多维度认证源的元数据中心', link: '/ch2-identity-entity' }
            ]
          }
         ],

docs/ch2-identity-entity.md

@@ -236,7 +236,7 @@ Vault 推出的 **机密同步（Secret Sync）** 功能，提出了一种开源
 
 **5\. 最终成果：全新交互式动手课程目录大纲**
 
-基于上述严谨、深度且穷尽的底层分析与教学法重构，为您交付如下剔除一切过时陈旧信息、深度融合现代架构机制、且全面覆盖现阶段（1.17+ 至 1.20+ 路线图）社区开源版最佳实践的全新知识体系架构。（根据任务指令，第 6 章“机密引擎”下层细节保持占位留空，供您后续自由选定填充）。
+基于上述严谨、深度且穷尽的底层分析与教学法重构，为您交付如下剔除一切过时陈旧信息、深度融合现代架构机制、且全面覆盖现阶段（1.17+ 至 1.20+ 路线图）社区开源版最佳实践的全新知识体系架构。考虑到学习者的兴趣曲线，将“机密引擎”章节前置至基础 CLI 之后，让读者在掌握命令行后能立刻动手存取真实业务机密；底层架构与身份治理章节则后移至上层应用搭建之前。（根据任务指令，机密引擎章节下层细节保持占位留空，供您后续自由选定填充）。
 
 # **《HashiCorp Vault 现代实战与零信任架构进阶指南》课程大纲**
 
@@ -274,36 +274,36 @@ Vault 推出的 **机密同步（Secret Sync）** 功能，提出了一种开源
 * 3.5 **【核心新增】** 轻量级代理服务指令：vault proxy 的配置文件解析与进程调试  
 * 3.6 集群底层运维手术刀：operator (init, unseal, rekey, rotate, raft) 指令簇全解
 
-## **第 4 章：集群配置文件调优与高可用自动化运维**
-
-* 4.1 配置文件架构纵览与现代 HCL 语法规范  
-* 4.2 网络监听器（Listener）与最高级别 TLS 协议族强化配置  
-* 4.3 自动化云端解封（Auto-Seal）机制对接（AWS KMS, Azure Key Vault, Transit 代理）  
-* 4.4 **【全面更新】** 现代存储引擎的绝对基石：Integrated Storage (Raft) 协议深度剖析  
-* 4.5 **【核心新增】** 彻底解放人工干预：配置 Raft 自动驾驶仪（Autopilot）  
-  * 4.5.1 服务器观察稳定期（Server Stabilization Time）防抖动设置  
-  * 4.5.2 死节点无痛自动清理（Dead Server Cleanup）与 Quorum 阈值维护  
-* 4.6 分布式服务注册与发现（K8s 原生发现机制与 Consul 集成模式）  
-* 4.7 核心指标遥测（Telemetry）暴露与可视化 UI 界面底层配置
-
-## **第 5 章：面向现代系统的联邦身份验证与治理**
-
-* 5.1 Token 身份验证（作为一切验证基础的核心基座）  
-* 5.2 面向微服务与机器架构的认证：强化版 AppRole 实战  
-* 5.3 面向人员体系的认证：Userpass 与云原生 GitHub 鉴权接入  
-* 5.4 企业组织架构目录集成：现代安全标准下的 LDAP 配置实践  
-* 5.5 **【核心新增】** 原生内核级防暴力破解：User Lockout 防御基线与参数调优实战  
-* 5.6 **【核心新增】** 无密钥云身份联邦：配置 JWT/OIDC 实现跨域 WIF 动态授权访问  
-* 5.7 **【核心新增】** 角色反转，Vault 作为单点登录枢纽：激活内置 OIDC Provider 身份代理服务
-
-## **第 6 章：核心机密引擎管理体系 (Secret Engines)**
+## **第 4 章：核心机密引擎管理体系 (Secret Engines)**
 
 *(讲师留空：此章节结构框架依据后续实际业务技术栈选型与应用场景进行针对性填充)*
 
-* 6.1 Key/Value (KV v2) 引擎：带有版本历史控制的现代静态机密存储框架  
+* 4.1 Key/Value (KV v2) 引擎：带有版本历史控制的现代静态机密存储框架  
 * ... (待选定特定机密引擎内容，例如 Database 等)...  
 * ... (待选定特定机密引擎内容，例如 SSH 等)...
 
+## **第 5 章：集群配置文件调优与高可用自动化运维**
+
+* 5.1 配置文件架构纵览与现代 HCL 语法规范  
+* 5.2 网络监听器（Listener）与最高级别 TLS 协议族强化配置  
+* 5.3 自动化云端解封（Auto-Seal）机制对接（AWS KMS, Azure Key Vault, Transit 代理）  
+* 5.4 **【全面更新】** 现代存储引擎的绝对基石：Integrated Storage (Raft) 协议深度剖析  
+* 5.5 **【核心新增】** 彻底解放人工干预：配置 Raft 自动驾驶仪（Autopilot）  
+  * 5.5.1 服务器观察稳定期（Server Stabilization Time）防抖动设置  
+  * 5.5.2 死节点无痛自动清理（Dead Server Cleanup）与 Quorum 阈值维护  
+* 5.6 分布式服务注册与发现（K8s 原生发现机制与 Consul 集成模式）  
+* 5.7 核心指标遥测（Telemetry）暴露与可视化 UI 界面底层配置
+
+## **第 6 章：面向现代系统的联邦身份验证与治理**
+
+* 6.1 Token 身份验证（作为一切验证基础的核心基座）  
+* 6.2 面向微服务与机器架构的认证：强化版 AppRole 实战  
+* 6.3 面向人员体系的认证：Userpass 与云原生 GitHub 鉴权接入  
+* 6.4 企业组织架构目录集成：现代安全标准下的 LDAP 配置实践  
+* 6.5 **【核心新增】** 原生内核级防暴力破解：User Lockout 防御基线与参数调优实战  
+* 6.6 **【核心新增】** 无密钥云身份联邦：配置 JWT/OIDC 实现跨域 WIF 动态授权访问  
+* 6.7 **【核心新增】** 角色反转，Vault 作为单点登录枢纽：激活内置 OIDC Provider 身份代理服务
+
 ## **第 7 章：应用自动化接入与现代 Kubernetes 云原生集成生态 【架构重大重构】**
 
 * 7.1 技术演进背景：消除应用层代码中的“机密感知 SDK”集成负担  

plan.md

@@ -0,0 +1,101 @@
+#!/bin/bash
+# ─────────────────────────────────────────────────────────
+# setup-common.sh — shared setup functions for Killercoda scenarios
+#
+# This file is the SINGLE SOURCE OF TRUTH for common setup logic.
+# It is copied into each scenario's assets/ directory by:
+#   npm run sync-setup  (or automatically via prebuild)
+#
+# Usage in background.sh:
+#   source /root/setup-common.sh
+#   install_vault
+#   finish_setup
+# ─────────────────────────────────────────────────────────
+
+VAULT_VERSION="${VAULT_VERSION:-1.19.2}"
+
+install_vault() {
+  if ! command -v unzip > /dev/null 2>&1; then
+    apt-get update -qq && apt-get install -y -qq unzip > /dev/null 2>&1
+  fi
+
+  curl --connect-timeout 10 --max-time 120 -fsSL \
+    "https://releases.hashicorp.com/vault/${VAULT_VERSION}/vault_${VAULT_VERSION}_linux_amd64.zip" \
+    -o /tmp/vault.zip \
+    && unzip -o -q /tmp/vault.zip -d /usr/local/bin/ \
+    && chmod +x /usr/local/bin/vault \
+    && rm -f /tmp/vault.zip
+
+  vault version || echo "WARNING: vault install failed"
+}
+
+start_vault_dev() {
+  # Start Vault in dev mode (in-memory, no TLS, root token = root)
+  export VAULT_ADDR='http://127.0.0.1:8200'
+  export VAULT_TOKEN='root'
+
+  # Persist env for ALL future shells (Killercoda's editor terminal is a
+  # separate shell that does not inherit from background.sh, and may not
+  # source ~/.bashrc — /etc/profile.d/*.sh is loaded by every login shell).
+  cat > /etc/profile.d/vault.sh <<'EOF'
+export VAULT_ADDR='http://127.0.0.1:8200'
+export VAULT_TOKEN='root'
+EOF
+  chmod +x /etc/profile.d/vault.sh
+  # Also append to /root/.bashrc so non-login interactive shells pick it up.
+  grep -q "VAULT_ADDR=" /root/.bashrc 2>/dev/null || \
+    cat /etc/profile.d/vault.sh >> /root/.bashrc
+
+  vault server -dev -dev-root-token-id=root \
+    -dev-listen-address=0.0.0.0:8200 \
+    > /var/log/vault-dev.log 2>&1 &
+
+  echo "Waiting for Vault dev server to be ready..."
+  for i in $(seq 1 30); do
+    if vault status > /dev/null 2>&1; then
+      echo "Vault is ready."
+      return 0
+    fi
+    sleep 1
+  done
+  echo "WARNING: Vault did not become healthy within 30 seconds"
+  cat /var/log/vault-dev.log
+}
+
+start_postgres() {
+  # Start a Postgres container for dynamic-secret demos.
+  # Image: postgres:16. Superuser: root / rootpassword. Listens on 5432.
+  if ! command -v docker > /dev/null 2>&1; then
+    echo "WARNING: docker not available, cannot start postgres"
+    return 1
+  fi
+
+  docker rm -f learn-postgres > /dev/null 2>&1 || true
+  docker run -d \
+    --name learn-postgres \
+    -e POSTGRES_USER=root \
+    -e POSTGRES_PASSWORD=rootpassword \
+    -p 5432:5432 \
+    --rm \
+    postgres:16 > /dev/null
+
+  echo "Waiting for Postgres to be ready..."
+  for i in $(seq 1 60); do
+    if docker exec learn-postgres pg_isready -U root > /dev/null 2>&1; then
+      echo "Postgres is ready."
+      # Create the read-only role that dynamic users will inherit from.
+      docker exec -i learn-postgres psql -U root -c \
+        "CREATE ROLE \"ro\" NOINHERIT;" > /dev/null 2>&1 || true
+      docker exec -i learn-postgres psql -U root -c \
+        "GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"ro\";" > /dev/null 2>&1 || true
+      return 0
+    fi
+    sleep 1
+  done
+  echo "WARNING: Postgres did not become healthy within 60 seconds"
+  docker logs learn-postgres || true
+}
+
+finish_setup() {
+  touch /tmp/.setup-done
+}

vault-tutorial/ch2-identity-entity/assets/setup-common.sh

@@ -0,0 +1,21 @@
+# 恭喜完成实验！🎉
+
+你已经亲手验证了 Vault Identity 文档里五个最关键的设计点：
+
+| 主题 | 一句话总结 |
+| --- | --- |
+| 隐式 Entity 与 Alias | 任何非 token 的 auth method 一登录就自动建好 entity + alias，无需主动管理 |
+| Mount accessor 决定唯一性 | (alias_name, mount_accessor) 才是 alias 的唯一键；同名 alias 在不同 mount 上 Vault 视为不同人 |
+| 手工合并 alias | 把多条 alias 改挂到同一个命名 Entity 下，之后任何 mount 登录都共享同一 `entity_id` |
+| Entity policy 请求时叠加 | 加权 / 减权立即生效、不需要重登；但 entity policy **只能加**、不能压住 token 自带 policy |
+| Group 与子组继承 | policy 沿 entity → group → 父 group 的链路自动传递，最终生效集合是所有层级的并集 |
+
+## 下一步
+
+- **2.6 策略（Policies）**：本节实验里反复出现的 HCL policy 文档，
+  下一节会系统讲清 path / capabilities / templated policy / 优先级
+- **5.x User Lockout / OIDC / WIF**：本节里 alice 是用最简单的
+  userpass 登的——后续身份治理章节会演示如何把 entity 与外部 IdP
+  （LDAP / OIDC / WIF）的真实身份系统对接
+- **8.x 审计**：本节强调 entity_id 让审计能按真实身份聚合，对应
+  审计章节会演示在审计日志里看到 entity_id 字段的样子

vault-tutorial/ch2-identity-entity/finish/finish.md

@@ -0,0 +1,47 @@
+{
+  "title": "Entity / Alias / Group 的归并与策略叠加",
+  "description": "把 Vault Identity 文档里五个关键设计跑一遍：隐式 entity、按 mount 唯一性、手工合并 alias、entity policy 请求时叠加、group 子组继承",
+  "details": {
+    "intro": {
+      "text": "init/init.md",
+      "background": "init/background.sh",
+      "foreground": "init/foreground.sh"
+    },
+    "steps": [
+      {
+        "title": "隐式 Entity 与 Alias",
+        "text": "step1/text.md"
+      },
+      {
+        "title": "不同 mount 不会自动合并",
+        "text": "step2/text.md"
+      },
+      {
+        "title": "手工合并：把多个 alias 挂到同一 Entity",
+        "text": "step3/text.md"
+      },
+      {
+        "title": "Entity policy 请求时叠加",
+        "text": "step4/text.md"
+      },
+      {
+        "title": "Identity Group 与子组继承",
+        "text": "step5/text.md"
+      }
+    ],
+    "finish": {
+      "text": "finish/finish.md"
+    },
+    "assets": {
+      "host01": [
+        {"file": "setup-common.sh", "target": "/root", "chmod": "+x"}
+      ]
+    }
+  },
+  "backend": {
+    "imageid": "ubuntu"
+  },
+  "interface": {
+    "layout": "editor-terminal"
+  }
+}

vault-tutorial/ch2-identity-entity/index.json

@@ -0,0 +1,13 @@
+#!/bin/bash
+# Background setup — runs before the user sees the terminal.
+
+source /root/setup-common.sh
+
+install_vault
+start_vault_dev
+
+if ! command -v jq > /dev/null 2>&1; then
+  apt-get update -qq && apt-get install -y -qq jq > /dev/null 2>&1
+fi
+
+finish_setup

vault-tutorial/ch2-identity-entity/init/background.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Foreground setup — waits for background to complete, then greets the user.
+
+echo "等待环境初始化..."
+while [ ! -f /tmp/.setup-done ]; do
+  sleep 1
+done
+
+export VAULT_ADDR='http://127.0.0.1:8200'
+export VAULT_TOKEN='root'
+
+echo ""
+echo "✅ 环境已就绪：Vault dev 服务器（root token = root）"
+echo ""
+vault status

vault-tutorial/ch2-identity-entity/init/foreground.sh

@@ -0,0 +1,13 @@
+# Entity / Alias / Group 的归并与策略叠加
+
+阅读 [2.5 章节文档](../ch2-identity-entity) 之后，本实验把 Identity
+文档里五个关键设计点亲手验证一遍：
+
+- 任何非 token 的 auth method 登录都会**自动**生成 entity + alias
+- 同一种 auth method 在两个不同 mount 上的 alias **不会**自动合并
+- 手工合并后，多种登录方式得到的 token 共享同一个 `entity_id`
+- Entity policy 在请求时动态求值——挂上立刻生效、摘掉立刻失能，**不需要重登**
+- Identity Group 让策略沿组关系（含子组）传递
+
+后台脚本会启动 Vault dev 模式（root token = `root`），并安装 `jq`
+方便后续 JSON 解析。

vault-tutorial/ch2-identity-entity/init/init.md

@@ -0,0 +1,83 @@
+# 第一步：隐式 Entity 与 Alias
+
+文档 §3 的核心论断：
+
+> When a client authenticates via any credential backend (except the
+> Token backend), Vault creates a new entity. It attaches a new alias
+> to it if a corresponding entity does not already exist.
+
+我们用 userpass 让 alice 登一次，看看 Vault 在背后默默建了什么。
+
+## 1.1 启用 userpass、创建用户、登录
+
+```bash
+vault auth enable userpass
+
+vault write auth/userpass/users/alice \
+  password=s3cr3t \
+  token_policies=default
+
+vault login -format=json -method=userpass username=alice password=s3cr3t \
+  > /root/alice-login.json
+```
+
+抓出 token 上的 `entity_id`：
+
+```bash
+ENT_ID=$(jq -r .auth.entity_id /root/alice-login.json)
+echo "alice 这次登录拿到的 token 上 entity_id = $ENT_ID"
+```
+
+注意——alice 还**完全没碰过 identity 子系统**，但 `entity_id` 已经
+有了。这就是文档说的"非 token auth method 一登录就隐式建 entity"。
+
+## 1.2 看看 Vault 自动建出来的 Entity
+
+```bash
+vault read identity/entity/id/$ENT_ID
+```
+
+注意几个关键字段：
+
+- `aliases` 数组里有一条，`name = alice`，`mount_type = userpass`
+- `policies` 是空的——Vault 不会替你猜该挂什么 policy，需要管理员显式挂
+- `metadata` 是 `<nil>`——同样需要管理员或外部 IdP 同步系统填
+
+## 1.3 看看自动建出来的 Alias
+
+把 alias_id 拿出来：
+
+```bash
+ALIAS_ID=$(vault read -format=json identity/entity/id/$ENT_ID \
+  | jq -r '.data.aliases[0].id')
+
+vault read identity/entity-alias/id/$ALIAS_ID
+```
+
+注意 `mount_accessor` 字段——这就是文档 §2.1 说的"alias 唯一键的另一半"：
+
+```bash
+USERPASS_ACC=$(vault auth list -format=json | jq -r '."userpass/".accessor')
+echo "userpass mount 的 accessor = $USERPASS_ACC"
+echo "alias 上记录的 mount_accessor   = $(vault read -format=json identity/entity-alias/id/$ALIAS_ID | jq -r .data.mount_accessor)"
+```
+
+两者必须一致——这正是 Vault 内部把"哪个 mount 上的 alice"区分开的方式。
+
+## 1.4 列出整个 Identity Store
+
+```bash
+echo "所有 entity:"
+vault list identity/entity/id
+
+echo ""
+echo "所有 alias:"
+vault list identity/entity-alias/id
+```
+
+各 1 条——alice 的隐式 entity 和它的 userpass alias。
+
+**这一步的核心结论**：你不需要主动管理 Entity，只要有人登录过 Vault
+就**自动**有了它的"持久身份记录"。Entity 只是一个 ID + 一组 alias 的
+集合，**它本身完全不能鉴权**——鉴权依旧靠 2.4 章节里的 token。Identity
+做的是"在 token 之外另开一条持久身份的副线"。