From 8b09d99fc4b546e4f70233542accb06180643e09 Mon Sep 17 00:00:00 2001
From: Haitao Pan <manbuzhe2009@qq.com>
Date: Wed, 1 Jul 2026 09:52:32 +0800
Subject: [PATCH] docs: add comprehensive troubleshooting section for Vault 400
 and 403 errors

---
 README.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 52 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 5cec603..32cfa60 100644
--- a/README.md
+++ b/README.md
@@ -57,23 +57,46 @@ If you are running the GitHub Actions workflow (`deploy-env-migration.yaml`), pl
 - **Role Binding**: Ensure the JWT `bound_claims` match the new repository name (`repo:ai-workspace-infra/site-migration-toolkit:ref:refs/heads/main` or similar).
 
 **Vault Role Provisioning Script**:
-To avoid CLI parsing issues, use the following JSON payload format to create or update the role:
+To avoid CLI parsing issues, use the following JSON payload format to create or update the role. This also binds the correct policy to the role.
+
+1. **Create the Vault Policy** (Grants read access to required secrets):
+```bash
+vault policy write github-actions-site-migration-toolkit - <<EOF
+path "kv/data/CICD" {
+  capabilities = ["read"]
+}
+path "kv/data/openclaw" {
+  capabilities = ["read"]
+}
+EOF
+```
+
+2. **Create the Vault JWT Role** (Binds the repository claim to the policy):
 ```bash
 vault write auth/jwt/role/github-actions-site-migration-toolkit - <<EOF
 {
   "bound_audiences": ["vault"],
   "bound_claims_type": "glob",
   "bound_claims": {
-    "sub": "repo:ai-workspace-infra/site-migration-toolkit:*"
+    "repository": "ai-workspace-infra/site-migration-toolkit"
   },
   "user_claim": "actor",
   "role_type": "jwt",
-  "policies": ["CICD", "openclaw"], 
+  "policies": ["github-actions-site-migration-toolkit"], 
   "ttl": "1h"
 }
 EOF
 ```
 
+### 🐛 Common Vault Authentication Issues (Troubleshooting)
+
+- **`400 Bad Request` (role could not be found)**: 
+  - *Cause*: The `VAULT_ROLE` defined in `.github/workflows/deploy-env-migration.yaml` does not match any existing role in your Vault server.
+  - *Fix*: Create the role using the script above, ensuring the name is exactly `github-actions-site-migration-toolkit`.
+- **`403 Forbidden` (during Get Vault Secrets)**: 
+  - *Cause*: The JWT authenticated successfully, but the token lacks read permissions for the requested KV paths (e.g., `kv/data/CICD`). This happens if the assigned `policies` in your Role do not exist or lack the `read` capability.
+  - *Fix*: Run `vault policy list` to verify. If missing, create the `github-actions-site-migration-toolkit` policy as shown above and bind it to the role.
+
 ---
 
 # 站点迁移与备份工具集 (Site Migration & Backup Toolkit)
@@ -133,19 +156,42 @@ EOF
 - **角色绑定 (Role Binding)**: 请确保 JWT 的 `bound_claims` 匹配新的代码库名称（例如 `repo:ai-workspace-infra/site-migration-toolkit:ref:refs/heads/main`）。
 
 **Vault 角色配置脚本**:
-为了避免 Vault CLI 在解析命令行 Map 类型时出现报错，推荐使用以下 JSON payload 的格式直接创建或更新角色：
+为了避免 Vault CLI 在解析命令行 Map 类型时出现报错，推荐使用以下 JSON payload 的格式直接创建或更新角色，并同时配齐必需的 Policy。
+
+1. **创建 Vault Policy** (授予访问必需敏感信息的读权限)：
+```bash
+vault policy write github-actions-site-migration-toolkit - <<EOF
+path "kv/data/CICD" {
+  capabilities = ["read"]
+}
+path "kv/data/openclaw" {
+  capabilities = ["read"]
+}
+EOF
+```
+
+2. **创建 Vault JWT Role** (将代码库的身份标识与权限 Policy 绑定)：
 ```bash
 vault write auth/jwt/role/github-actions-site-migration-toolkit - <<EOF
 {
   "bound_audiences": ["vault"],
   "bound_claims_type": "glob",
   "bound_claims": {
-    "sub": "repo:ai-workspace-infra/site-migration-toolkit:*"
+    "repository": "ai-workspace-infra/site-migration-toolkit"
   },
   "user_claim": "actor",
   "role_type": "jwt",
-  "policies": ["CICD", "openclaw"], 
+  "policies": ["github-actions-site-migration-toolkit"], 
   "ttl": "1h"
 }
 EOF
 ```
+
+### 🐛 常见 Vault 鉴权排错指南 (Troubleshooting)
+
+- **报错 `400 Bad Request` (role could not be found)**: 
+  - *原因*: Github Actions 流水线中定义的 `VAULT_ROLE` 在你的 Vault 服务器上不存在。
+  - *解法*: 请使用上方脚本创建名为 `github-actions-site-migration-toolkit` 的角色。
+- **报错 `403 Forbidden` (发生在 Get Vault Secrets 阶段)**: 
+  - *原因*: JWT 登录成功，但是签发的 Token 没有对应路径（如 `kv/data/CICD`）的读权限。这通常是因为绑定在 Role 上的 `policies` 不存在，或者里面的权限配置不包含 `read`。
+  - *解法*: 在服务端运行 `vault policy list` 检查。如果缺少对应策略，请执行上方的【创建 Vault Policy】步骤补充权限，并确保 Role 正确绑定了该 Policy。