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
