Documentation 2026-10-06 23:59 UTC to 2026-10-07 00:59 UTC

57 快速入門57 快速入門

58</h2>58</h2>

59 59 

60此快速入門走最小路徑：在您的 IdP 中註冊 OAuth 用戶端，寫入 `gateway.yaml`，使用 Docker Compose 與 Postgres 一起執行閘道，並驗證端到端登入。它使用 Amazon Bedrock 上游；Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Anthropic API 同樣受支援，只需如[配置參考](/docs/zh-TW/claude-apps-gateway-config#upstreams)所示交換 `upstreams` 區塊。最後，您有一個開發人員可以 `/login` 的閘道。60此快速入門走最小路徑：在您的 IdP 中註冊 OAuth 用戶端，寫入 `gateway.yaml`，使用 Docker Compose 與 Postgres 一起執行閘道，並驗證端到端登入。它使用 Amazon Bedrock 上游；Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Anthropic API 同樣受支援，只需如[設定參考](/docs/zh-TW/claude-apps-gateway-config#upstreams)所示交換 `upstreams` 區塊。最後，您有一個開發人員可以 `/login` 的閘道。

61 61 

62<Note>62<Note>

63 **在您的私有網路上部署。** Claude Code 只連接到地址為私有的閘道。這是一個安全防護，因為受信任的閘道可以推送在開發人員機器上執行命令的設定。將閘道放在內部負載平衡器或 VPN 後面，並給它一個只解析為私有 IP 的主機名。如果您的內部網路是從您的組織擁有的公開 IPv4 空間編號的，請參閱[允許閘道在您擁有的公開地址空間上](#allow-a-gateway-on-public-address-space-you-own)。63 **在您的私有網路上部署。** Claude Code 只連接到地址為私有的閘道。這是一個安全防護，因為受信任的閘道可以推送在開發人員機器上執行命令的設定。將閘道放在內部負載平衡器或 VPN 後面，並給它一個只解析為私有 IP 的主機名。如果您的內部網路是從您的組織擁有的公開 IPv4 空間編號的，請參閱[允許閘道在您擁有的公開地址空間上](#allow-a-gateway-on-public-address-space-you-own)。

73| - | - |73| - | - |

74| Claude Code v2.1.195 或更新版本 | `claude gateway` 子命令和閘道登入流程在 v2.1.195 中發布。較早的公開版本不包含它們。執行閘道伺服器的機器和每個開發人員的機器都必須是 v2.1.195 或更新版本；執行 `claude update` 以取得最新版本。[Claude Platform on AWS 上游](/docs/zh-TW/claude-apps-gateway-config#claude-platform-on-aws)在閘道伺服器上需要 Claude Code v2.1.198 或更新版本。 |74| Claude Code v2.1.195 或更新版本 | `claude gateway` 子命令和閘道登入流程在 v2.1.195 中發布。較早的公開版本不包含它們。執行閘道伺服器的機器和每個開發人員的機器都必須是 v2.1.195 或更新版本；執行 `claude update` 以取得最新版本。[Claude Platform on AWS 上游](/docs/zh-TW/claude-apps-gateway-config#claude-platform-on-aws)在閘道伺服器上需要 Claude Code v2.1.198 或更新版本。 |

75| OpenID Connect (OIDC) 身份提供商 | Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex，或任何其他符合 OIDC 的 IdP，例如 PingFederate。閘道針對它執行標準 OIDC 發現和授權碼流程。不支援 SAML 和 LDAP。 |75| OpenID Connect (OIDC) 身份提供商 | Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex，或任何其他符合 OIDC 的 IdP，例如 PingFederate。閘道針對它執行標準 OIDC 發現和授權碼流程。不支援 SAML 和 LDAP。 |

76| PostgreSQL 14 或更新版本 | 支援裝置登入流程，其中瀏覽器回呼寫入，輪詢 CLI 讀取，加上速率限制計數器。任何受管 Postgres 都可以，包括最小層級。在未配置支出限制的情況下，閘道儲存幾 KB 的短期身份驗證狀態；使用[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)，它還持有應備份的耐久支出、稽核和身份表。建議透過 `?sslmode=require` 使用 TLS。 |76| PostgreSQL 11 或更新版本 | 支援裝置登入流程和速率限制計數器。受管 PostgreSQL 服務皆可使用，包括最小層級；請參閱[支援哪些資料庫](/docs/zh-TW/claude-apps-gateway-deploy#postgres)。使用[支出限制](/docs/zh-TW/claude-apps-gateway-spend-limits)時，它還持有應備份的耐久支出、稽核和身份表。建議透過 `?sslmode=require` 使用 TLS。PostgreSQL 11、12 和 13 在閘道伺服器上需要 Claude Code v2.1.290 或更新版本。PostgreSQL 專案已不再維護這些版本，因此請盡可能使用較新的版本。 |

77| 模型上游 | Amazon Bedrock 認證、Claude Platform on AWS 認證、Google Cloud 認證、Microsoft Foundry 資源或 Anthropic API 金鑰。支援多個上游和故障轉移。 |77| 模型上游 | Amazon Bedrock 憑證、Claude Platform on AWS 憑證、Google Cloud 憑證、Microsoft Foundry 資源或 Anthropic API 金鑰。支援多個上游和故障轉移。 |

78| HTTPS | 閘道必須可從開發人員筆記型電腦和用於登入的任何瀏覽器透過 `https://` 到達；閘道在同一監聽器上提供裝置驗證頁面。透過 `listen.tls` 提供 TLS 憑證，或在 TLS 終止入口後執行並設定 `listen.public_url` 為外部來源（兩種情況下都是如此）。純 `http://` 來源僅在閘道主機為環回時接受：`localhost`、`127.0.0.1` 或 `::1`。 |78| HTTPS | 閘道必須可從開發人員筆記型電腦和用於登入的任何瀏覽器透過 `https://` 到達；閘道在同一監聽器上提供裝置驗證頁面。透過 `listen.tls` 提供 TLS 憑證，或在 TLS 終止入口後執行，並在兩種情況下都將 `listen.public_url` 設定為外部來源。在 `/login` 處，Claude Code 僅在閘道主機為環回時接受純 `http://` 來源：`localhost`、`127.0.0.1` 或 `::1`。 |

79| 私有網路地址 | 在 `/login` 處，Claude Code 要求閘道的主機名或 IP 地址僅解析為私有地址：RFC 1918、連結本地、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 或環回。對於您託管的閘道，任何公開地址都會被拒絕；請參閱部署指南中的[威脅模型](/docs/zh-TW/claude-apps-gateway-deploy#threat-model-summary)。如果開發人員機器透過公司代理路由 HTTPS，登入還要求代理主機解析為私有地址；如果不是，將閘道主機新增到 `NO_PROXY`，以便 CLI 直接連接。如果您的內部網路是從您的組織擁有的公開 IPv4 空間編號的，[宣告這些區塊](#allow-a-gateway-on-public-address-space-you-own)，以便 `/login` 接受那裡的閘道。 |79| 私有網路地址 | 在 `/login` 處，Claude Code 要求閘道的主機名或 IP 地址僅解析為私有地址：RFC 1918、連結本地、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 或環回。對於您託管的閘道，任何位於您所宣告區塊之外的公開地址都會被拒絕；請參閱部署指南中的[威脅模型](/docs/zh-TW/claude-apps-gateway-deploy#threat-model-summary)。如果開發人員機器透過公司代理伺服器路由 HTTPS，登入還要求代理伺服器主機解析為私有地址；如果不是，將閘道主機新增到 `NO_PROXY`，以便 CLI 直接連接。如果您的內部網路是從您的組織擁有的公開 IPv4 空間編號的，[宣告這些區塊](#allow-a-gateway-on-public-address-space-you-own)，以便 `/login` 接受那裡的閘道。 |

80| Linux 執行時 | 閘道伺服器僅在原生 Linux 二進位檔上執行。macOS 適用於本地開發。Windows 不支援作為伺服器平台。 |80| Linux 執行時 | 閘道伺服器僅在原生 Linux 二進位檔上執行。macOS 適用於本地開發。Windows 不支援作為伺服器平台。 |

81 81 

82<h3 id="steps">82<h3 id="steps">

89 </Step>89 </Step>

90 90 

91 <Step title="佈建 PostgreSQL 資料庫">91 <Step title="佈建 PostgreSQL 資料庫">

92 任何 Postgres 14 或更新版本都可以，包括最小受管層級。閘道在啟動時執行自己的架構遷移，因此資料庫角色需要建立和更改表的權限；請參閱 [`store`](/docs/zh-TW/claude-apps-gateway-config#store)。92 使用 PostgreSQL 11 或更新版本。最小的受管層級即已足夠。閘道在啟動時執行自己的 schema 遷移，因此資料庫角色需要建立和更改表的權限；請參閱 [`store`](/docs/zh-TW/claude-apps-gateway-config#store)。

93 </Step>93 </Step>

94 94 

95 <Step title="寫入 gateway.yaml">95 <Step title="寫入 gateway.yaml">

96 機密透過 `${ENV_VAR}` 擴展讀取，因此檔案本身可以存在於版本控制中。使用在您的網路上解析為私有 IP 的 `public_url` 主機名，因為 `/login` 拒絕公開地址。最小配置有五個部分，其他每個欄位都有預設值：96 機密透過 `${ENV_VAR}` 擴展讀取，因此檔案本身可以存在於版本控制中。使用在您的網路上解析為私有 IP 的 `public_url` 主機名，因為 `/login` 拒絕公開地址。最小設定有五個部分，其他每個欄位都有預設值：

97 97 

98 ```yaml gateway.yaml theme={null}98 ```yaml gateway.yaml theme={null}

99 listen:99 listen:

120 upstreams:120 upstreams:

121 - provider: bedrock121 - provider: bedrock

122 region: us-east-1122 region: us-east-1

123 auth: {} # 空：AWS 預設認證鏈123 auth: {} # 空：AWS 預設憑證鏈

124 # (IRSA、EC2/ECS 任務角色、環境變數、~/.aws)124 # (IRSA、EC2/ECS 任務角色、環境變數、~/.aws)

125 125 

126 # 模型會自動按上游轉換。內建目錄126 # 模型會自動按上游轉換。內建目錄

130 auto_include_builtin_models: true130 auto_include_builtin_models: true

131 ```131 ```

132 132 

133 此配置足以使用預設 Amazon Bedrock 模型目錄進行有效的登入迴圈。執行後，透過 [`managed.policies`](/docs/zh-TW/claude-apps-gateway-config#managed) 新增按群組 RBAC 和受管設定、透過 [`telemetry`](/docs/zh-TW/claude-apps-gateway-config#telemetry) 的遙測扇出，以及多上游故障轉移、佈建輸送量 ARN 或非美國區域，透過 [`models`](/docs/zh-TW/claude-apps-gateway-config#models)。133 此設定足以使用預設 Amazon Bedrock 模型目錄進行有效的登入迴圈。執行後，透過 [`managed.policies`](/docs/zh-TW/claude-apps-gateway-config#managed) 新增按群組 RBAC 和受管設定、透過 [`telemetry`](/docs/zh-TW/claude-apps-gateway-config#telemetry) 的遙測扇出，以及多上游故障轉移、佈建輸送量 ARN 或非美國區域，透過 [`models`](/docs/zh-TW/claude-apps-gateway-config#models)。

134 134 

135 <Note>135 <Note>

136 Amazon Bedrock 上游需要一個 AWS 主體，具有 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream` 在 `inference-profile/us.anthropic.*` ARN 和基礎 `foundation-model/anthropic.*` ARN 上。它也需要 Anthropic 的一次性使用案例表單從 Bedrock 主控台的模型目錄提交給帳戶。136 Amazon Bedrock 上游需要一個 AWS 主體，具有 `bedrock:InvokeModel` 和 `bedrock:InvokeModelWithResponseStream` 在 `inference-profile/us.anthropic.*` ARN 和基礎 `foundation-model/anthropic.*` ARN 上。它也需要 Anthropic 的一次性使用案例表單從 Bedrock 主控台的模型目錄提交給帳戶。

137 137 

138 透過 EKS 上的 IRSA、ECS 任務角色或 EC2 執行個體設定檔提供認證，而不是靜態金鑰。[`upstreams` 參考](/docs/zh-TW/claude-apps-gateway-config#upstreams)具有完整的 IAM 詳細資訊、跨雲認證矩陣和其他提供商的 `auth` 區塊。138 透過 EKS 上的 IRSA、ECS 任務角色或 EC2 執行個體設定檔提供憑證，而不是靜態金鑰。[`upstreams` 參考](/docs/zh-TW/claude-apps-gateway-config#upstreams)具有完整的 IAM 詳細資訊、跨雲憑證矩陣和其他提供商的 `auth` 區塊。

139 </Note>139 </Note>

140 </Step>140 </Step>

141 141 

152 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}152 OIDC_CLIENT_SECRET: ${OIDC_CLIENT_SECRET}

153 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}153 GATEWAY_JWT_SECRET: ${GATEWAY_JWT_SECRET}

154 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway154 GATEWAY_POSTGRES_URL: postgres://gw:pw@postgres/gateway

155 # AWS 認證：在生產中，省略這些並使用執行個體155 # AWS 憑證：在生產中，省略這些並使用執行個體

156 # 角色。對於本地 Compose 測試，傳遞您自己的：156 # 角色。對於本地 Compose 測試，傳遞您自己的：

157 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}157 AWS_ACCESS_KEY_ID: ${AWS_ACCESS_KEY_ID}

158 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}158 AWS_SECRET_ACCESS_KEY: ${AWS_SECRET_ACCESS_KEY}

170 volumes: { pgdata: }170 volumes: { pgdata: }

171 ```171 ```

172 172 

173 閘道是一個單一 Linux 二進位檔，讀取配置，連接到 Postgres 並應用其架構遷移，針對您的 IdP 執行 OIDC 發現，建立上游用戶端，並開始監聽。啟動對配置、Postgres 連接、OIDC 發現和上游用戶端構造是失敗關閉的。如果其中任何一個無法到達或配置錯誤，閘道會以錯誤退出，而不是以降級狀態提供流量。173 閘道是一個單一 Linux 二進位檔，讀取設定，連接到 Postgres 並套用其 schema 遷移，針對您的 IdP 執行 OIDC 發現，建立上游用戶端，並開始監聽。

174 174 

175 成功啟動不驗證推理路徑，因為 Amazon Bedrock 和 Google Cloud 的 Agent Platform 執行個體認證在第一個請求時解析，而不是在啟動時。175 啟動對設定、Postgres 連接、OIDC 發現和上游用戶端建構是失敗關閉的。如果其中任何一個無法到達或設定錯誤，閘道會以錯誤退出，而不是以降級狀態提供流量。

176 176 

177 監視 stderr 以了解啟動序列。日誌行使用格式 `[gateway] <timestamp> <level> <message>`，稽核事件是帶有 `evt` 欄位的單行 JSON，啟動橫幅（下面省略）在遷移和監聽行之間列印。新資料庫為每個架構遷移列印一個 `migration N applied` 行；已遷移的資料庫不列印任何行。您應該按順序看到：177 成功啟動不驗證推理路徑，因為 Amazon Bedrock 和 Google Cloud 的 Agent Platform 執行個體憑證在第一個請求時解析，而不是在啟動時。

178 

179 監視 stderr 以了解啟動序列。日誌行使用格式 `[gateway] <timestamp> <level> <message>`，稽核事件是帶有 `evt` 欄位的單行 JSON，啟動橫幅（下面省略）在遷移和監聽行之間列印。新資料庫為每個 schema 遷移列印一個 `migration N applied` 行；已遷移的資料庫不列印任何行。您應該按順序看到：

178 180 

179 ```text theme={null}181 ```text theme={null}

180 {"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}182 {"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}

192 * 無法到達的 Postgres194 * 無法到達的 Postgres

193 * 沒有 DDL 權限的 Postgres 角色195 * 沒有 DDL 權限的 Postgres 角色

194 * 無法到達或無效的 OIDC 發現文件196 * 無法到達或無效的 OIDC 發現文件

195 * 配置架構違規，帶有違規欄位路徑197 * 設定 schema 違規，帶有違規欄位路徑

196 198 

197 修復它並重新啟動。199 修復它並重新啟動。

198 200 

204 206 

205 示例使用閘道的公開 URL；對於沒有入口的本地 Compose 設定，在前兩個檢查中替換 `http://localhost:8080`。第三個檢查開啟 `verification_uri_complete`，它從 `public_url` 建立，因此對於本地 Compose，在 `gateway.yaml` 中設定 `public_url: http://localhost:8080`，並在步驟 1 的 OAuth 用戶端上新增 `http://localhost:8080/oauth/callback` 作為第二個重定向 URI，因為閘道從 `public_url` 建立 IdP `redirect_uri`。驗證連結然後在您的本地瀏覽器中開啟。207 示例使用閘道的公開 URL；對於沒有入口的本地 Compose 設定，在前兩個檢查中替換 `http://localhost:8080`。第三個檢查開啟 `verification_uri_complete`，它從 `public_url` 建立，因此對於本地 Compose，在 `gateway.yaml` 中設定 `public_url: http://localhost:8080`，並在步驟 1 的 OAuth 用戶端上新增 `http://localhost:8080/oauth/callback` 作為第二個重定向 URI，因為閘道從 `public_url` 建立 IdP `redirect_uri`。驗證連結然後在您的本地瀏覽器中開啟。

206 208 

207 在 Windows PowerShell 中，執行 `curl.exe`；裸 `curl` 是 `Invoke-WebRequest` 的別名，拒絕這些標誌。209 在 Windows PowerShell 中，執行 `curl.exe`；裸 `curl` 是 `Invoke-WebRequest` 的別名，拒絕這些旗標。

208 210 

209 首先，獲取發現文件，確認閘道已啟動、配置有效且所有啟動檢查已通過：211 首先，取得發現文件，確認閘道已啟動、設定有效且所有啟動檢查已通過：

210 212 

211 ```bash theme={null}213 ```bash theme={null}

212 curl -s https://claude-gateway.internal.example.com/.well-known/oauth-authorization-server | jq214 curl -s https://claude-gateway.internal.example.com/.well-known/oauth-authorization-server | jq

251 </Step>253 </Step>

252 254 

253 <Step title="登入開發人員">255 <Step title="登入開發人員">

254 最後一步發生在開發人員機器上，而不是伺服器上。在該機器的[受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)中將 `forceLoginMethod` 設定為 `"gateway"` 並將 `forceLoginGatewayUrl` 設定為您的閘道的 `public_url`，然後執行 `/login`，在**雲端閘道**螢幕上按 Enter，並完成瀏覽器登入。下面的[設定閘道 URL](#set-the-gateway-url) 涵蓋大規模分發兩個金鑰。256 最後一步發生在開發人員機器上，而不是伺服器上。在該機器的[受管設定檔](/docs/zh-TW/managed-settings#delivery-mechanisms)中將 `forceLoginMethod` 設定為 `"gateway"` 並將 `forceLoginGatewayUrl` 設定為您的閘道的 `public_url`，然後執行 `/login`，在**雲端閘道**螢幕上按 Enter，並完成瀏覽器登入。下面的[設定閘道 URL](#set-the-gateway-url) 涵蓋如何將這兩個設定鍵分發到每台開發人員機器。

255 </Step>257 </Step>

256</Steps>258</Steps>

257 259 

156閘道僅在啟動時讀取一次金鑰和憑證，因此變更的檔案僅在重新啟動後才會生效。請依照以下順序輪換，以確保沒有任何 token 請求出示 IdP 沒有的憑證：156閘道僅在啟動時讀取一次金鑰和憑證，因此變更的檔案僅在重新啟動後才會生效。請依照以下順序輪換，以確保沒有任何 token 請求出示 IdP 沒有的憑證：

157 157 

1581. 將新憑證上傳到 IdP，與舊憑證並存。1581. 將新憑證上傳到 IdP，與舊憑證並存。

1592. 替換 `gateway.yaml` 載入的金鑰和憑證檔案，然後重新啟動閘道。1592. 替換 `gateway.yaml` 載入的金鑰和憑證檔案，然後重新啟動閘道。如果您執行多個副本，可以使用[滾動重新啟動](/docs/zh-TW/claude-apps-gateway-deploy#upgrades)，因為在您移除舊憑證之前，IdP 同時擁有兩個憑證。

1603. 從 IdP 移除舊憑證。1603. 在每個副本都重新啟動後，從 IdP 移除舊憑證。

161 161 

162<h4 id="idp-requests-through-a-forward-proxy">162<h4 id="idp-requests-through-a-forward-proxy">

163 透過轉發代理伺服器的 IdP 請求163 透過轉發代理伺服器的 IdP 請求

225 225 

226| 欄位 | 必需 | 說明 |226| 欄位 | 必需 | 說明 |

227| - | - | - |227| - | - | - |

228| `postgres_url` | 是 | `postgres://` 或 `postgresql://` URL。必需：裝置授權會合點（瀏覽器回呼寫入且輪詢 CLI 讀取）需要跨副本狀態。閘道在啟動時和升級時執行自己的 schema 遷移，因此角色需要在目標 schema 上建立和更改資料表的權限。請參閱[升級](/docs/zh-TW/claude-apps-gateway-deploy#upgrades)和 [Postgres](/docs/zh-TW/claude-apps-gateway-deploy#postgres)。 |228| `postgres_url` | 是 | 僅含一個主機的 `postgres://` 或 `postgresql://` URL，而不是以逗號分隔的清單。閘道在啟動時和升級時執行自己的 schema 遷移，因此角色需要在目標 schema 上建立和更改資料表的權限。請參閱[升級](/docs/zh-TW/claude-apps-gateway-deploy#upgrades)和 [Postgres](/docs/zh-TW/claude-apps-gateway-deploy#postgres)。 |

229| `username` | 否 | 覆寫 `postgres_url` 中的使用者 |229| `username` | 否 | 覆寫 `postgres_url` 中的使用者 |

230| `password` | 否 | 資料庫憑證。在此設定它而不是在 `postgres_url` 中，以便憑證保持在 URL 之外。接受任何字元並優先於 URL 中的憑證。 |230| `password` | 否 | 資料庫憑證。在此設定它而不是在 `postgres_url` 中，以便憑證保持在 URL 之外。接受任何字元並優先於 URL 中的憑證。 |

231| `max_connections` | 否 | 每個副本的 Postgres 連線池大小。預設 `5`，這是保守的且對共享資料庫友善。啟用[支出限制](#admin)後，熱路徑每個推論請求執行幾個操作，因此在負載下為專用資料庫提高它，並保持副本 × 此值低於資料庫的 `max_connections`。 |231| `max_connections` | 否 | 每個副本的 Postgres 連線池大小。預設 `5`，這是保守的且對共享資料庫友善。啟用[支出限制](#admin)後，熱路徑每個推論請求執行幾個操作，因此在負載下為專用資料庫提高它，並保持副本 × 此值低於資料庫的 `max_connections`。 |

249 Postgres249 Postgres

250</h3>250</h3>

251 251 

252閘道將其狀態儲存在 PostgreSQL 資料庫中：

253 

254* **資料庫**：PostgreSQL 本身，自行託管或受管理皆可，需為[最低版本](/docs/zh-TW/claude-apps-gateway#prerequisites)或更新版本。僅實作 Postgres 協定的資料庫（例如分散式 SQL 資料庫）不受支援。

255* **位址**：`store.postgres_url` 接受一個主機。如果資料庫有多個節點，請使用位於它們前方的位址，例如您的受管理服務的端點、負載平衡器或虛擬 IP。設定比容錯移轉耗時更長的[就緒性寬限期](#readiness-grace-period)。

256 

252閘道保持五個資料表加上 `_migrations` 表，全部由其啟動時遷移建立：257閘道保持五個資料表加上 `_migrations` 表，全部由其啟動時遷移建立：

253 258 

254| 表 | 內容 | 保留 |259| 表 | 內容 | 保留 |

396| CLI `/login`：`Could not resolve the configured HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 中的主機名稱無法從開發者的機器解析，通常是因為它未連線到公司網路 | 讓開發者連線到您的網路或 VPN 並重試，或修正代理伺服器 URL |401| CLI `/login`：`Could not resolve the configured HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 中的主機名稱無法從開發者的機器解析，通常是因為它未連線到公司網路 | 讓開發者連線到您的網路或 VPN 並重試，或修正代理伺服器 URL |

397| CLI `/login`：`Could not resolve gateway host <host>` | 機器無法解析 gateway 的內部 DNS 名稱，通常是因為它不在公司網路上 | 讓開發者連線到您的網路或 VPN，然後重試 `/login` |402| CLI `/login`：`Could not resolve gateway host <host>` | 機器無法解析 gateway 的內部 DNS 名稱，通常是因為它不在公司網路上 | 讓開發者連線到您的網路或 VPN，然後重試 `/login` |

398| 啟動結束，顯示命名 `store.postgres_url` 的設定驗證錯誤 | 未設定 Postgres；gateway 需要 Postgres | 設定 `store.postgres_url`。對於本機開發，請使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |403| 啟動結束，顯示命名 `store.postgres_url` 的設定驗證錯誤 | 未設定 Postgres；gateway 需要 Postgres | 設定 `store.postgres_url`。對於本機開發，請使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |

404| 啟動結束：`store.postgres_url in <path> is not a URL the gateway can read`，或在 v2.1.290 之前僅顯示 `Invalid URL` 或 `URI error` | 無法剖析該 URL，例如因為它列出了多個主機，或其密碼含有未編碼的 `/`、`?`、`#` 或 `%` | 只指定[一個主機](#postgres)，並將密碼移至 [`store.password`](/docs/zh-TW/claude-apps-gateway-config#store) |

399| 啟動結束：`requires the native binary` | 在 Node 下執行而不是原生二進位檔 | 使用其中一種[獨立安裝方法](/docs/zh-TW/setup)安裝 Claude Code |405| 啟動結束：`requires the native binary` | 在 Node 下執行而不是原生二進位檔 | 使用其中一種[獨立安裝方法](/docs/zh-TW/setup)安裝 Claude Code |

400| 啟動結束，在 `config.load` 後出現 OIDC 探索錯誤 | `oidc.issuer` 無法到達，或 TLS 鏈不受信任 | 檢查發行者是否可從 pod 到達並提供 `/.well-known/openid-configuration`。為私有 PKI 設定 `ca_cert_pem`。如果 pod 只能透過轉送代理伺服器到達 IdP，請設定 [`oidc.use_proxy: true`](/docs/zh-TW/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)；在 v2.1.227 之前的版本上，改為給 pod 一條到 IdP 每個端點的直接路由。如果 pod 也無法解析 IdP 的主機名稱，或代理伺服器拒絕 `CONNECT` 到 IP 位址，請參閱[僅透過代理伺服器的出口](/docs/zh-TW/claude-apps-gateway-config#proxy-only-egress)，這需要 v2.1.277 或更新版本。 |406| 啟動結束，在 `config.load` 後出現 OIDC 探索錯誤 | `oidc.issuer` 無法到達，或 TLS 鏈不受信任 | 檢查發行者是否可從 pod 到達並提供 `/.well-known/openid-configuration`。為私有 PKI 設定 `ca_cert_pem`。如果 pod 只能透過轉送代理伺服器到達 IdP，請設定 [`oidc.use_proxy: true`](/docs/zh-TW/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)；在 v2.1.227 之前的版本上，改為給 pod 一條到 IdP 每個端點的直接路由。如果 pod 也無法解析 IdP 的主機名稱，或代理伺服器拒絕 `CONNECT` 到 IP 位址，請參閱[僅透過代理伺服器的出口](/docs/zh-TW/claude-apps-gateway-config#proxy-only-egress)，這需要 v2.1.277 或更新版本。 |

401| 啟動結束，出現 Postgres 權限錯誤 | 資料庫角色在其 schema 上缺少 DDL 權限 | 授予角色在 gateway schema 上的 `CREATE` 權限，以便它可以在啟動時建立和更改其表格 |407| 啟動結束，出現 Postgres 權限錯誤 | 資料庫角色在其 schema 上缺少 DDL 權限 | 授予角色在 gateway schema 上的 `CREATE` 權限，以便它可以在啟動時建立和更改其表格 |

402| 日誌：`could not connect to Postgres at boot, attempt 1 of 3` | 當 gateway 啟動時資料庫無法到達，例如在冷執行個體上，其網路仍在啟動中 | 如果 gateway 隨後完成啟動，則無需採取任何行動。當資料庫無法到達時，gateway 在結束前嘗試連線三次，間隔兩秒。如果它結束時顯示 `could not connect to Postgres`，請檢查 `store.postgres_url` 和到資料庫的網路路徑。如果嘗試逾時而不是被拒絕，請提高 [`store.connect_timeout_seconds`](/docs/zh-TW/claude-apps-gateway-config#store) 以給每個嘗試更長的時間。 |408| 日誌：`could not connect to Postgres at boot, attempt 1 of 3` | 當 gateway 啟動時資料庫無法到達，例如在冷執行個體上，其網路仍在啟動中 | 如果 gateway 隨後完成啟動，則無需採取任何行動。當資料庫無法到達時，gateway 在結束前嘗試連線三次，間隔兩秒。如果它結束時顯示 `could not connect to Postgres`，請檢查 `store.postgres_url`（包括確認它只指定一個主機）以及到資料庫的網路路徑。如果嘗試逾時而不是被拒絕，請提高 [`store.connect_timeout_seconds`](/docs/zh-TW/claude-apps-gateway-config#store) 以給每個嘗試更長的時間。 |

403| `/oauth/callback` 顯示「Sign-in could not be completed」 | 電子郵件網域被拒絕、id\_token 驗證失敗，或 `email_verified` 明確為 `false`，gateway 始終拒絕且無法覆寫 | 檢查 `allowed_email_domains` 以及 IdP 是否傳回已驗證的 `email` 宣告。對於 `email_verified: false`，修正 IdP 端驗證。如果您的 IdP 在不同的宣告名稱下發出電子郵件，請設定 `oidc.email_claim`。 |409| `/oauth/callback` 顯示「Sign-in could not be completed」 | 電子郵件網域被拒絕、id\_token 驗證失敗，或 `email_verified` 明確為 `false`，gateway 始終拒絕且無法覆寫 | 檢查 `allowed_email_domains` 以及 IdP 是否傳回已驗證的 `email` 宣告。對於 `email_verified: false`，修正 IdP 端驗證。如果您的 IdP 在不同的宣告名稱下發出電子郵件，請設定 `oidc.email_claim`。 |

404| 日誌：`token exchange failed request_id=<id>: id_token missing email claim` | IdP 預設不在 id\_token 中包含 `email`。此拒絕僅在設定 `allowed_email_domains` 時觸發；沒有它，遺漏的電子郵件會建立沒有電子郵件的工作階段 | 設定 IdP 在 id\_token 中發出 `email`。Okta：將 `email` 新增到自訂授權伺服器的 ID token 宣告。Entra：在應用程式註冊上新增 `email` 作為選用宣告。PingFederate：啟用發出 `email` 的 OpenID Connect 原則。如果 IdP 從 userinfo 端點提供 `email` 但不會在 id\_token 中包含它，例如 Okta 組織授權伺服器，請設定 `oidc.userinfo_fallback: true`。 |410| 日誌：`token exchange failed request_id=<id>: id_token missing email claim` | IdP 預設不在 id\_token 中包含 `email`。此拒絕僅在設定 `allowed_email_domains` 時觸發；沒有它，遺漏的電子郵件會建立沒有電子郵件的工作階段 | 設定 IdP 在 id\_token 中發出 `email`。Okta：將 `email` 新增到自訂授權伺服器的 ID token 宣告。Entra：在應用程式註冊上新增 `email` 作為選用宣告。PingFederate：啟用發出 `email` 的 OpenID Connect 原則。如果 IdP 從 userinfo 端點提供 `email` 但不會在 id\_token 中包含它，例如 Okta 組織授權伺服器，請設定 `oidc.userinfo_fallback: true`。 |

405| 日誌：`refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`，開發者每 `session.ttl_hours` 看到 `Cloud gateway session expired` | IdP 接受了重新整理 token 但沒有隨之傳回 id\_token，所以 gateway 詢問了 IdP 的 userinfo 端點以取得使用者的宣告。IdP 在那裡拒絕了重新整理的存取 token。gateway 回應 `temporarily_unavailable`，所以 Claude Code 保留重新整理 token 但無法更新工作階段。v2.1.260 之前的 gateway 版本記錄相同的行，但沒有 `(at …)` 詳細資訊。 | 設定 [`oidc.scope_on_refresh: true`](/docs/zh-TW/claude-apps-gateway-config#oidc)（在 gateway v2.1.260 或更新版本中可用），以便重新整理請求再次要求 `openid`。某些 IdP（例如 Okta）僅在被要求時才在重新整理時傳回 id\_token。在 PingFederate 上，改為在 **Applications > OAuth > OpenID Connect Policy Management** 下啟用 **Return ID Token On Refresh Grant**。該金鑰不會改變 PingFederate 的行為。對於仍然省略它的其他 IdP，檢查 userinfo 端點是否接受由重新整理發出的存取 token。作為臨時解決方案，提高 [`session.ttl_hours`](/docs/zh-TW/claude-apps-gateway-config#session)。請參閱[身分提供者設定](#identity-provider-setup)以了解取消佈建權衡。 |411| 日誌：`refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`，開發者每 `session.ttl_hours` 看到 `Cloud gateway session expired` | IdP 接受了重新整理 token 但沒有隨之傳回 id\_token，所以 gateway 詢問了 IdP 的 userinfo 端點以取得使用者的宣告。IdP 在那裡拒絕了重新整理的存取 token。gateway 回應 `temporarily_unavailable`，所以 Claude Code 保留重新整理 token 但無法更新工作階段。v2.1.260 之前的 gateway 版本記錄相同的行，但沒有 `(at …)` 詳細資訊。 | 設定 [`oidc.scope_on_refresh: true`](/docs/zh-TW/claude-apps-gateway-config#oidc)（在 gateway v2.1.260 或更新版本中可用），以便重新整理請求再次要求 `openid`。某些 IdP（例如 Okta）僅在被要求時才在重新整理時傳回 id\_token。在 PingFederate 上，改為在 **Applications > OAuth > OpenID Connect Policy Management** 下啟用 **Return ID Token On Refresh Grant**。該金鑰不會改變 PingFederate 的行為。對於仍然省略它的其他 IdP，檢查 userinfo 端點是否接受由重新整理發出的存取 token。作為臨時解決方案，提高 [`session.ttl_hours`](/docs/zh-TW/claude-apps-gateway-config#session)。請參閱[身分提供者設定](#identity-provider-setup)以了解取消佈建權衡。 |

136 --policy-name bedrock-invoke --policy-document file://bedrock-invoke.json136 --policy-name bedrock-invoke --policy-document file://bedrock-invoke.json

137 ```137 ```

138 138 

139 ECS 也需要執行角色，ECS 代理本身使用它從 ECR 提取映像並注入稍後建立的 Secrets Manager 值。它與 gateway 的 AWS SDK 在執行時使用的任務角色分開：139 ECS 也需要執行角色，ECS agent 本身使用它從 ECR 提取映像並注入稍後建立的 Secrets Manager 值。它與 gateway 的 AWS SDK 在執行時使用的任務角色分開：

140 140 

141 ```bash theme={null}141 ```bash theme={null}

142 aws iam create-role --role-name claude-gateway-execution \142 aws iam create-role --role-name claude-gateway-execution \

169 </Step>169 </Step>

170 170 

171 <Step title="佈建 Amazon RDS for PostgreSQL">171 <Step title="佈建 Amazon RDS for PostgreSQL">

172 實例在私有子網中執行，沒有公開地址，儲存加密已開啟。引擎版本固定為 Postgres 16，滿足 gateway 支援的 PostgreSQL 14 下限，並保證下面的參數群組系列與實例相符。172 實例在私有子網中執行 Postgres 16，沒有公開地址，儲存加密已開啟。

173 173 

174 首先，建立將資料庫放在私有子網中的子網群組，以及具有 `rds.force_ssl=1` 的參數群組，以便伺服器拒絕純文字連接。引擎版本固定一次，因為參數群組的系列必須與實例執行的引擎主要版本相符：174 首先，建立將資料庫放在私有子網中的子網群組，以及具有 `rds.force_ssl=1` 的參數群組，以便伺服器拒絕純文字連接。引擎版本固定一次，因為參數群組的系列必須與實例執行的引擎主要版本相符：

175 175 

218 </Step>218 </Step>

219 219 

220 <Step title="寫入 gateway.yaml">220 <Step title="寫入 gateway.yaml">

221 `upstreams` 區塊使用 `auth: {}` 指向 Bedrock，因此 gateway 透過 ECS 上的任務角色或 EKS 上的 IRSA 角色從 AWS 預設認證鏈進行驗證。有關每個欄位，請參閱[設定參考](/docs/zh-TW/claude-apps-gateway-config)。221 `upstreams` 區塊使用 `auth: {}` 指向 Bedrock，因此 gateway 透過 ECS 上的任務角色或 EKS 上的 IRSA 角色從 AWS 預設憑證鏈進行驗證。有關每個欄位，請參閱[設定參考](/docs/zh-TW/claude-apps-gateway-config)。

222 222 

223 兩個 `listen` 欄位描述什麼位於 gateway 前面：223 兩個 `listen` 欄位描述什麼位於 gateway 前面：

224 224 

225 * `public_url`：外部 `https://` 來源，非環回繫結時必需；請參閱 [`listen` 參考](/docs/zh-TW/claude-apps-gateway-config#listen)。gateway 僅從此值建置 IdP `redirect_uri` 和其發現文件，絕不從 `X-Forwarded-*` 標頭建置。225 * `public_url`：外部 `https://` 來源，非環回繫結時必需；請參閱 [`listen` 參考](/docs/zh-TW/claude-apps-gateway-config#listen)。gateway 僅從此值建置 IdP `redirect_uri` 和其發現文件，絕不從 `X-Forwarded-*` 標頭建置。

226 * `trusted_proxies`：前端的來源範圍。gateway 僅當 TCP 對等體在此清單中時才接受 `X-Forwarded-For`，然後在受信任的躍點之後遍歷鏈，因此每 IP 登入速率限制和稽核事件記錄開發人員 IP 而不是負載平衡器的。226 * `trusted_proxies`：前端的來源範圍。gateway 僅當 TCP 對等體在此清單中時才接受 `X-Forwarded-For`，然後在受信任的躍點之後遍歷鏈，因此每 IP 登入速率限制和稽核事件記錄開發人員 IP 而不是負載平衡器的。

227 227 

228 在兩個軌道上，前端都是內部 ALB，無論是直接建立還是由 AWS Load Balancer Controller 建立，ALB 的節點從其附加到的子網中取得地址，因此將 `trusted_proxies` 設定為這些子網的 CIDR。這信任這些子網中的每個主機作為代理。保持 ALB 的入站來源（您的公司 CIDR）不與它們重疊，並且不要與可能透過 `X-Forwarded-For` 欺騙客戶端 IP 的不受信任的工作負載共享子網。228 在兩個軌道上，前端都是內部 ALB，無論是直接建立還是由 AWS Load Balancer Controller 建立，ALB 的節點從其附加到的子網中取得地址，因此將 `trusted_proxies` 設定為這些子網的 CIDR。這信任這些子網中的每個主機作為代理伺服器。保持 ALB 的入站來源（您的公司 CIDR）不與它們重疊，並且不要與可能透過 `X-Forwarded-For` 欺騙客戶端 IP 的不受信任的工作負載共享子網。

229 229 

230 ALB 的客戶端連接埠保留屬性 `routing.http.xff_client_port.enabled` 可以保持任一設定：開啟時，ALB 將客戶端寫為 `203.0.113.7:54321` 或 `[2001:db8::1]:54321`，gateway 讀取兩者並刪除連接埠。230 ALB 的客戶端連接埠保留屬性 `routing.http.xff_client_port.enabled` 可以保持任一設定：開啟時，ALB 將客戶端寫為 `203.0.113.7:54321` 或 `[2001:db8::1]:54321`，gateway 讀取兩者並刪除連接埠。

231 231 

261 - provider: bedrock261 - provider: bedrock

262 region: <your-region> # 符合 $AWS_REGION 以便 IAM262 region: <your-region> # 符合 $AWS_REGION 以便 IAM

263 # 原則的 ARN 涵蓋它263 # 原則的 ARN 涵蓋它

264 auth: {} # AWS 預設認證鏈：264 auth: {} # AWS 預設憑證鏈：

265 # ECS 任務角色，或 EKS 上的 IRSA265 # ECS 任務角色，或 EKS 上的 IRSA

266 ```266 ```

267 267 

288 字面 `--secret-string` 引數在每個命令執行時在程序表和稽核/EDR 日誌中可見。在共享或受監控的主機上，將值放在 `0600` 檔案中，改為傳遞 `--secret-string file://<path>`。套件的 `setup.sh` 以相同方式將機密值保持在程序 argv 之外，將 `0600` 臨時檔案傳遞給 `--cli-input-json`。288 字面 `--secret-string` 引數在每個命令執行時在程序表和稽核/EDR 日誌中可見。在共享或受監控的主機上，將值放在 `0600` 檔案中，改為傳遞 `--secret-string file://<path>`。套件的 `setup.sh` 以相同方式將機密值保持在程序 argv 之外，將 `0600` 臨時檔案傳遞給 `--cli-input-json`。

289 </Note>289 </Note>

290 290 

291 與機密不同，`gateway.yaml` 本身不包含機密值，因為每個認證在啟動時透過 [`${VAR}` 或 `${file:...}` 擴展](/docs/zh-TW/claude-apps-gateway-config#secret-expansion)解析。一切如何到達容器因軌道而異：291 與機密不同，`gateway.yaml` 本身不包含機密值，因為每個憑證在啟動時透過 [`${VAR}` 或 `${file:...}` 擴展](/docs/zh-TW/claude-apps-gateway-config#secret-expansion)解析。一切如何到達容器因軌道而異：

292 292 

293 * 在 ECS 上，下一步的建置將 `gateway.yaml` 複製到映像中的 `/etc/claude/gateway.yaml`，任務定義透過其 `secrets` 欄位將三個機密注入為環境變數，因此 YAML 參考 `${GATEWAY_JWT_SECRET}`、`${OIDC_CLIENT_SECRET}` 和 `${GATEWAY_POSTGRES_URL}`。293 * 在 ECS 上，下一步的建置將 `gateway.yaml` 複製到映像中的 `/etc/claude/gateway.yaml`，任務定義透過其 `secrets` 欄位將三個機密注入為環境變數，因此 YAML 參考 `${GATEWAY_JWT_SECRET}`、`${OIDC_CLIENT_SECRET}` 和 `${GATEWAY_POSTGRES_URL}`。

294 * 在 EKS 上，從 ConfigMap 掛載 `gateway.yaml` 和機密作為 `/secrets` 中的檔案，參考為 `${file:/secrets/...}`。使用 External Secrets Operator 或 Secrets Store CSI 驅動程式的 AWS 提供者從 Secrets Manager 來源 Kubernetes Secrets，或使用 `kubectl` 直接建立它們。294 * 在 EKS 上，從 ConfigMap 掛載 `gateway.yaml` 和機密作為 `/secrets` 中的檔案，參考為 `${file:/secrets/...}`。使用 External Secrets Operator 或 Secrets Store CSI 驅動程式的 AWS 提供者從 Secrets Manager 來源 Kubernetes Secrets，或使用 `kubectl` 直接建立它們。

400 400 

401 新增 HTTPS 監聽器。`--ssl-policy` 固定現代 TLS 下限，因為省略它會回到舊版 `ELBSecurityPolicy-2016-08` 預設值，仍然接受 TLS 1.0/1.1。401 新增 HTTPS 監聽器。`--ssl-policy` 固定現代 TLS 下限，因為省略它會回到舊版 `ELBSecurityPolicy-2016-08` 預設值，仍然接受 TLS 1.0/1.1。

402 402 

403 ALB 預設在 60 秒後沒有資料的連接關閉。gateway 的保活 ping 保持串流在該預設值內，因此提高逾時在 ping 頻率上方增加邊距；[故障排除](#troubleshooting)行關於掉落的串流涵蓋機制和較舊的 gateway。下面的命令新增監聽器並提高逾時：403 ALB 預設在 60 秒後沒有資料的連接關閉。gateway 的保活 ping 保持串流在該預設值內，因此提高逾時在 ping 頻率上方增加邊距；[疑難排解](#troubleshooting)行關於掉落的串流涵蓋機制和較舊的 gateway。下面的命令新增監聽器並提高逾時：

404 404 

405 ```bash theme={null}405 ```bash theme={null}

406 aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" \406 aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" \

424 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"424 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"

425 ```425 ```

426 426 

427 60 秒的寬限期給冷任務時間拉取映像、連接到儲存並在 ECS 開始計算針對部署的失敗之前回答其第一個健康檢查。目標群組在 `GET /readyz` 上的健康檢查驗證儲存是否可到達，因此無法到達 Postgres 的任務永遠不會進入輪換。為了保持任務通過短資料庫中斷（例如 RDS 容錯移轉）的健康檢查，請設定 `store.readiness_grace_seconds`，如[中斷行為](/docs/zh-TW/claude-apps-gateway-deploy#outage-behavior)所述，其中也涵蓋 `/healthz` 替代方案。427 60 秒的寬限期給冷任務時間拉取映像、連接到儲存並在 ECS 開始計算針對部署的失敗之前回答其第一個健康檢查。

428 

429 目標群組在 `GET /readyz` 上的健康檢查驗證儲存是否可到達，因此無法到達 Postgres 的任務永遠不會進入輪換。為了保持任務通過短資料庫中斷（例如 RDS 容錯移轉）的健康檢查，請設定 `store.readiness_grace_seconds`，如[中斷行為](/docs/zh-TW/claude-apps-gateway-deploy#outage-behavior)所述，其中也涵蓋 `/healthz` 替代方案。

428 430 

429 任務在沒有公開 IP 的私有子網中執行，因此所有出站流量（到 Bedrock、您的 IdP、Secrets Manager、ECR 和 CloudWatch Logs）都透過 NAT 閘道。為了保持 Bedrock 流量不走公開路徑，建立 `bedrock-runtime` 介面 VPC 端點並將上游的 `base_url` 指向它，如 [Bedrock 上游參考](/docs/zh-TW/claude-apps-gateway-config#amazon-bedrock)所示；IdP 仍然需要網際網路出站。431 任務在沒有公開 IP 的私有子網中執行，因此所有出站流量（到 Bedrock、您的 IdP、Secrets Manager、ECR 和 CloudWatch Logs）都透過 NAT 閘道。為了保持 Bedrock 流量不走公開路徑，建立 `bedrock-runtime` 介面 VPC 端點並將上游的 `base_url` 指向它，如 [Bedrock 上游參考](/docs/zh-TW/claude-apps-gateway-config#amazon-bedrock)所示；IdP 仍然需要網際網路出站。

430 432 

436 <Tab title="EKS">438 <Tab title="EKS">

437 此軌道需要在本地安裝 `kubectl` 和 `eksctl`，以及具有 IAM OIDC 提供者和已安裝 AWS Load Balancer Controller 的現有 EKS 叢集。叢集必須在 `$VPC_ID` 上，以便 pod 可以到達 RDS 私有端點，`claude-gateway-db` 安全群組必須允許叢集的 pod 或節點安全群組而不是 `$GW_SG`。439 此軌道需要在本地安裝 `kubectl` 和 `eksctl`，以及具有 IAM OIDC 提供者和已安裝 AWS Load Balancer Controller 的現有 EKS 叢集。叢集必須在 `$VPC_ID` 上，以便 pod 可以到達 RDS 私有端點，`claude-gateway-db` 安全群組必須允許叢集的 pod 或節點安全群組而不是 `$GW_SG`。

438 440 

439 在 EKS 上，gateway 透過 IRSA 而不是 ECS 角色從 Bedrock 獲得其認證。IAM 步驟中的 `ecs-tasks.amazonaws.com` 信任原則在此不適用；IRSA 需要一個信任原則在叢集的 OIDC 提供者上聯合的角色，範圍為 `system:serviceaccount:claude-gateway:gateway`。`eksctl create iamserviceaccount` 在一個步驟中建立該角色、附加原則並使用角色 ARN 註釋 Kubernetes 服務帳戶。將 IAM 步驟中的兩個原則文件轉換為它可以附加的受管原則：441 在 EKS 上，gateway 透過 IRSA 而不是 ECS 角色取得其 Bedrock 憑證。IAM 步驟中的 `ecs-tasks.amazonaws.com` 信任原則在此不適用；IRSA 需要一個信任原則在叢集的 OIDC 提供者上聯合的角色，範圍為 `system:serviceaccount:claude-gateway:gateway`。`eksctl create iamserviceaccount` 在一個步驟中建立該角色、附加原則並使用角色 ARN 註釋 Kubernetes 服務帳戶。將 IAM 步驟中的兩個原則文件轉換為它可以附加的受管原則：

440 442 

441 ```bash theme={null}443 ```bash theme={null}

442 BEDROCK_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-bedrock-invoke \444 BEDROCK_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-bedrock-invoke \

467 * `alb.ingress.kubernetes.io/inbound-cidrs: <your-corporate-cidr>`，因此控制器管理的前端安全群組僅允許您的公司網路代替其 `0.0.0.0/0` 預設值469 * `alb.ingress.kubernetes.io/inbound-cidrs: <your-corporate-cidr>`，因此控制器管理的前端安全群組僅允許您的公司網路代替其 `0.0.0.0/0` 預設值

468 * `alb.ingress.kubernetes.io/certificate-arn` 與 ACM 憑證470 * `alb.ingress.kubernetes.io/certificate-arn` 與 ACM 憑證

469 * `alb.ingress.kubernetes.io/ssl-policy: ELBSecurityPolicy-TLS13-1-2-2021-06`，因此監聽器不會回到接受 TLS 1.0 和 1.1 的舊版預設原則471 * `alb.ingress.kubernetes.io/ssl-policy: ELBSecurityPolicy-TLS13-1-2-2021-06`，因此監聽器不會回到接受 TLS 1.0 和 1.1 的舊版預設原則

470 * `alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=3600`，在 gateway 的串流保活上方的邊距；請參閱[故障排除](#troubleshooting)472 * `alb.ingress.kubernetes.io/load-balancer-attributes: idle_timeout.timeout_seconds=3600`，在 gateway 的串流保活上方的邊距；請參閱[疑難排解](#troubleshooting)

471 473 

472 使用 IRSA，AWS SDK 讀取投影的服務帳戶權杖並與 AWS STS 交換它，因此 pod 永遠不需要 EC2 實例中繼資料服務；出站 NetworkPolicy 可能會為 gateway pod 阻止 `169.254.169.254`。下面[故障排除](#troubleshooting)中的節點躍點限制問題僅適用於跳過 IRSA 並依賴節點實例角色的叢集。474 使用 IRSA，AWS SDK 讀取投影的服務帳戶權杖並與 AWS STS 交換它，因此 pod 永遠不需要 EC2 實例中繼資料服務；出站 NetworkPolicy 可能會為 gateway pod 阻止 `169.254.169.254`。下面[疑難排解](#troubleshooting)中的節點躍點限制問題僅適用於跳過 IRSA 並依賴節點實例角色的叢集。

473 </Tab>475 </Tab>

474 </Tabs>476 </Tabs>

475 </Step>477 </Step>