⬇ 下载全部文件 (zip)

2026-09-16 重要更正与风险提示（务必先读） 1. Claude 也能走 bedrock-mantle：路径是 /anthropic/v1/messages（Anthropic Messages 面），模型用 mantle 的短 ID（不带版本后缀、不带 us. 前缀），如 anthropic.claude-opus-4-8、anthropic.claude-sonnet-5。此前 word文档/本文判定"Claude 不在 mantle"是因为拿 runtime 的长版本 ID（...-20250929-v1:0）去打 mantle，mantle 不认这种 ID → 404，被误读成"端点不支持 Claude"。实测（2026-09-16，us-east-1 与香港 ap-east-1 Lambda）均 200。 2. 地域门按"模型/厂商"判，不按"端点"判：香港出口下，OpenAI 系在 mantle 和 runtime 两个端点都被挡（400 unsupported countries）；Claude 在两个端点都能过（200）。 3. ⚠️ 但 Claude 从香港能用属"意外"，理论上不该放行，随时可能被收紧。生产架构不要依赖"Claude 从香港直连"这条——Claude 也走海外中继，既统一出口/鉴权/模型名，又不受这条政策变化影响。GPT 是明确被挡的，本来就必须走中继。

0. 一页结论

本文所有文件在 deliverables/ 目录下，见 §6 文件清单。三步走每一步都给了 控制台点选版 和 命令行版，两者任选其一。

读者定位：熟悉 Linux / docker / nginx / TLS 的运维同学，但没碰过 AWS。所以 docker compose、nginx upstream、openssl 自签这些不展开；AWS 专有名词在 §0.1 用你们熟悉的东西对照解释一遍，正文里第一次出现时也会点一下。

0.1 AWS 概念对照（懂运维、不懂 AWS 看这个就够）

1. 对 word文档 与 runbook 的逐条修正

1.1 word文档

1.2 Bedrock-OneAPI-双机部署runbook.md

1.3 原文 §7 "待确认" 的答案

1. One API 的 AWS Bedrock 渠道能否指向中继？ 不能（源码确认，见 A1）。Claude 必须走 OpenAI 渠道 + 中继上的转换盒。转换盒用 LiteLLM（本文）或 aws-samples/bedrock-access-gateway 都行；LiteLLM 更通用、社区大。
2. 账号内实际可用模型 ID（aws bedrock list-foundation-models --region us-east-1 实查，2026-09-15）：

规则：mantle 只认短 ID，runtime 只认带前缀 profile ID。Claude 在 mantle 走 Anthropic Messages 面（/anthropic/v1/messages），不支持 OpenAI 的 /v1/chat/completions（实测 400 does not support the ... API）；GPT 反之走 /openai/v1/chat/completions。列 mantle 模型清单需 bedrock-mantle:ListModels 权限（调用只需 CreateInference）。 3. 香港到底挡不挡：见 §0。 4. 中继放哪（从香港 EC2 与东京/新加坡 EC2 实测 TCP 建连时延）：

端点必须留在 us-east-1（GPT-5.6 的 mantle OpenAI 兼容端点只有美东，runbook 已实测）。 5. 要不要 Bedrock API Key（Bearer）：不需要。IAM 角色 + sigv4-proxy/LiteLLM 自动签名，没有任何长期密钥要保管。API Key 只在"中继不在 AWS 上"时才有意义。

2. 目标架构（修正版）

香港（客户现有 One API，1 台或多台都一样，不动业务逻辑）        东京
┌──────────────────────────────────────────┐        ┌─────────────────────────────────────────────────────────┐
│ One API 节点 ×N                           │        │ ALB（固定域名，HTTPS 443，安全组只放香港各节点出口 IP）      │
│  渠道 GPT-5.6  ×2  OpenAI类型             │ HTTPS  │   目标组 :80 /healthz 5s×2                                │
│    base_url https://<ALB>/mantle/openai ──┼───────►│   ┌──────────────── Auto Scaling Group（min 2，跨 AZ）──────┐│
│    密钥 = RELAY_GPT_KEY                   │        │   │ 中继 EC2（启动模板 = Ubuntu + install-relay.sh 用户数据）  ││
│  渠道 Claude   ×2  OpenAI类型             │        │   │  nginx :80 ─┬ /mantle/* 校验Bearer → sigv4-proxy ──────┼┼─→ bedrock-mantle.us-east-1 /openai/v1 (GPT)
│    base_url https://<ALB>/claude ─────────┼───────►│   │             └ /claude/*  → LiteLLM (master_key) ──────┼┼─→ bedrock-runtime.us-east-1 Converse (Claude)
│    密钥 = RELAY_CLAUDE_KEY                │        │   │  IAM 角色：bedrock:Invoke* + bedrock-mantle:CreateInference ││
│  系统设置：失败重试 3                      │        │   └─────────────────────────────────────────────────────────┘│
└──────────────────────────────────────────┘        │   实例挂/不健康 → ASG 自动换新并注册回 ALB                      │
                                                     └─────────────────────────────────────────────────────────┘

• PoC 阶段（§3.2）没有 ALB/ASG：单台中继，渠道 base_url 直接填 https://<中继IP>/mantle/openai 与 https://<中继IP>/claude，中继 nginx 443 自签 TLS。
• 生产阶段（§3.3）中继完全无状态、无本地配置差异，所以可以被 ASG 随时换掉；两把 RELAY_*_KEY 写在启动模板的用户数据里，所有中继一致。
• 每个模型对同一个 ALB 建 两个 渠道：One API 失败重试时会换另一个渠道（它不会重试同一个），第二次请求经 ALB 大概率落到健康节点，用来兜 ALB 健康检查的 ~10 秒窗口。
• 中继上 没有静态 AWS 密钥；RELAY_*_KEY 只是"中继的门钥匙"。
• 香港 ↔ ALB 走公网 TLS：ALB 证书放 ACM（有域名用正规证书；没域名导入自签，One API 容器用 SSL_CERT_FILE 信任）。

3. 三步走 Runbook

下面凡是 AWS 专有名词（角色、实例配置文件、安全组、跃点限制、Session Manager、EIP、ALB、目标组、ACM），含义与坑见 §0.1，正文不再重复解释。docker / nginx / openssl 部分默认你已熟悉。

3.0 前置：一次性创建 IAM 角色（账号级，只做一次）

控制台：IAM → 角色 → 创建角色 → 可信实体 AWS 服务 / EC2 → 下一步 → 先勾 AmazonSSMManagedInstanceCore（让你能在浏览器里点"连接 → Session Manager"进机器，不用密钥对）→ 角色名 bedrock-relay-role → 创建。再进该角色 → 添加权限 → 创建内联策略 → JSON → 粘贴 cli/bedrock-invoke-policy.json 全文 → 名字 bedrock-invoke。

命令行：bash cli/01-create-iam-role.sh

策略要点：bedrock:InvokeModel*/Converse* 加上 bedrock-mantle:CreateInference（GPT 走 mantle 端点必需）。另外要在 Bedrock 控制台（us-east-1）确认已开通 Anthropic 与 OpenAI 模型访问（"模型访问权限"页面）。

3.1 第一步：证明账号权限没问题（任意海外区 EC2）

目的：在不涉及中继的情况下，证明 (a) 这个 AWS 账号能调 Claude 和 GPT，(b) 该 EC2 所在区的出口 IP 过得了地域门。建议就在你打算放中继的区（东京）开一台临时机；同一脚本在香港机上跑一遍，可以亲眼看到 GPT 被挡而 Claude 不挡。

控制台：EC2（右上角切到 东京 ap-northeast-1）→ 启动实例 → 名称 bedrock-test → AMI 选 Ubuntu Server 24.04 → 类型 t3.micro 即可 → 密钥对"不使用" → 网络：默认 VPC、不需要开任何入站端口 → 高级详情 → IAM 实例配置文件 = bedrock-relay-role → 启动。等状态检查通过后，选中实例 → 连接 → Session Manager → 连接，得到一个浏览器终端。然后：

# 把 step1-账号权限测试/bedrock-test.py 的全文粘进去保存（或 nano bedrock-test.py 粘贴），再：
python3 bedrock-test.py

命令行：（在自己电脑或任意有 AWS CLI 的地方）

REGION=ap-northeast-1; AMI=$(aws ssm get-parameter --region $REGION --name /aws/service/canonical/ubuntu/server/24.04/stable/current/amd64/hvm/ebs-gp3/ami-id --query Parameter.Value --output text)
aws ec2 run-instances --region $REGION --image-id $AMI --instance-type t3.micro --iam-instance-profile Name=bedrock-relay-role \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=bedrock-test}]' --query "Instances[0].InstanceId" --output text
# 然后 aws ssm start-session --region $REGION --target <实例ID>，进去后同上跑 python3 bedrock-test.py

判读（脚本自带 ✅/❌ 和说明）：

脚本只用 python3 标准库，自带 SigV4 签名，不需要 AWS CLI、不需要 pip。（原 curl 版在 Ubuntu 24.04 自带的 curl 8.5 上签名有 bug，已弃用。）

3.2 第二步：PoC 双机（香港 One API → 东京中继 → Bedrock）

3.2.1 中继机（先装）

控制台：EC2（东京）→ 启动实例：

启动后约 80~90 秒就绪。连接 → Session Manager，运行：

sudo cat /opt/relay/.env           # 看两把钥匙
sudo bash /opt/relay/selftest.sh   # 期望：healthz=ok；[2] GPT PONG；[3] Claude PONG；[4] 401
sudo cat /opt/relay/tls/server.crt # 证书内容，香港机要信任它（也可由香港机自动抓取，见下）

命令行：

export HK_CIDR=<香港机公网IP>/32 RELAY_GPT_KEY=sk-relay-gpt-xxx RELAY_CLAUDE_KEY=sk-relay-claude-xxx
REGION=ap-northeast-1 NAME=bedrock-relay-a bash cli/02-launch-relay.sh

建议：给中继绑一个弹性 IP（EC2 → 弹性 IP → 分配 → 关联），否则停机再开 IP 会变。绑完在机上执行 sudo /opt/relay/gen-cert.sh && cd /opt/relay && sudo docker compose restart nginx 重新签发含新 IP 的证书。

中继机上到底有什么（/opt/relay/，完整内容见 step2-中继机/配置参考/）：

要加模型：改 litellm.yaml 加一段 model_name → sudo docker compose restart litellm；GPT 路不用改（mantle 直接认 openai.gpt-5.6-luna 等裸 ID），只需在 One API 渠道模型列表里加名字。

3.2.2 香港 One API 机

客户已有 One API（docker 部署） —— 只做三件事：

1. 信任中继证书：把中继的 server.crt 追加到一个 PEM 文件（系统 CA + 中继证书），挂进容器并设 SSL_CERT_FILE。step2-香港OneAPI机/add-relay-cert.sh <中继IP> 会自动抓证书、追加、重启容器。手工版 compose 片段： yaml services: one-api: volumes: - ./relay-ca-bundle.pem:/etc/ssl/certs/relay-ca-bundle.pem:ro environment: SSL_CERT_FILE: /etc/ssl/certs/relay-ca-bundle.pem # Go 程序读这个变量 RELAY_TIMEOUT: "300" （relay-ca-bundle.pem = cat /etc/ssl/certs/ca-certificates.crt 中继server.crt，这样其它 https 渠道不受影响。）
2. 配两个渠道（控制台：渠道 → 添加新的渠道）：

或者命令行：./setup-channels.sh <中继IP> <RELAY_GPT_KEY> <RELAY_CLAUDE_KEY>（用管理令牌走 One API 的 /api/channel 接口，效果与上表一致，并顺手把重试次数设为 3、建一个测试令牌）。 3. 设置 → 运营设置 → 失败重试次数 = 3（默认 0；多渠道时才会自动换渠道）。

全新装 One API 做 PoC（本次测试就是这样）：控制台在 ap-east-1 启动 Ubuntu 24.04 t3.small，用户数据粘 install-oneapi.sh，安全组只对你办公 IP 开 3000（或不开，用 Session Manager 端口转发）；命令行 bash cli/03-launch-oneapi-hk.sh。装完 cd /opt/oneapi && ./add-relay-cert.sh <中继IP> && ./setup-channels.sh <中继IP> <GPT钥匙> <Claude钥匙>。

记得把香港机的公网 IP 填进中继安全组（3.2.1 的 HK_CIDR）。

3.2.3 端到端验证（香港机上）

cd /opt/oneapi && ./e2e-test.sh        # 或 ./e2e-test.sh sk-<你的One API令牌>

期望四条非流式都 HTTP 200 且 content: "PONG"，两条流式都逐块出 data: 行。本次实测输出（节选）：

>>> openai.gpt-5.6-sol      {"choices":[{"message":{"content":"PONG",...   HTTP 200  总耗时 1.13s
>>> gpt-5.6（重定向）        ...content":"PONG"...                          HTTP 200  总耗时 0.96s
>>> claude-sonnet-4-5       ...content":"PONG"...                          HTTP 200  总耗时 1.47s
>>> gpt-5.6-converse（备选） ...content":"PONG"...                          HTTP 200  总耗时 1.56s
>>> claude-sonnet-4-5 流式  data: {...delta":{"content":"1\n2\n3\n4"...}}  ✔
>>> openai.gpt-5.6-sol 流式 data: {...delta":{"content":"1"}...}           ✔

给业务方的两条提醒：① GPT-5.6 请求用 max_completion_tokens（发 max_tokens 会 400，与 OpenAI 官方一致）；改不了的老客户端用 gpt-5.6-converse。② One API 日志会刷 model ratio not found，是计费倍率没配，去"设置 → 运营设置 → 模型倍率"给这几个模型名加倍率即可，不影响调用。

3.3 第三步：高可用（生产）

要解决的三件事：挂了不影响业务（多台 + 入口自动摘除）、挂了自动补（ASG）、升级不停机（实例刷新）。写死 IP 的 nginx LB 解决不了第二件，所以生产用 ASG + ALB。三种做法都实测过：

3.3.1 推荐方案：ASG + ALB

命令行（一条命令建完）：

export HK_CIDRS="<香港节点1 IP>/32 <香港节点2 IP>/32"   # 所有 One API 节点的出口 IP
export RELAY_GPT_KEY=sk-relay-gpt-xxx RELAY_CLAUDE_KEY=sk-relay-claude-xxx
REGION=ap-northeast-1 bash step3-高可用/create-asg-alb.sh

脚本顺序做：ALB 安全组（443 ← 香港）→ 中继安全组（80 ← ALB 安全组）→ 目标组（/healthz，5s×2）→ ALB（空闲超时 300s）→ 自签证书导入 ACM + HTTPS 监听器 → 启动模板（AMI、t3.small、角色、跃点限制 2、install-relay.sh 作用户数据）→ ASG（min 2 / max 4，跨所有默认子网，健康检查类型 ELB，宽限 180s）。最后打印 ALB 域名。

控制台（东京，按同样顺序）： 1. EC2 → 安全组：建 bedrock-relay-alb-sg（入站 443 ← 各香港 IP/32）；建 bedrock-relay-asg-sg（入站 80 ← 来源选安全组 bedrock-relay-alb-sg）。 2. EC2 → 目标组 → 创建：实例、HTTP 80、默认 VPC；健康检查 /healthz，高级：间隔 5、超时 3、阈值 2/2。不选任何实例（ASG 会自动注册）。 3. EC2 → 负载均衡器 → 创建 ALB：面向互联网、默认 VPC 勾全部可用区、安全组只选 bedrock-relay-alb-sg、监听器 HTTPS 443 → 上面的目标组、证书：有域名选 ACM 证书；没域名先建 HTTP 80 监听器，拿到 DNS 名后按 §0.1 ACM 行生成自签、ACM → 导入，再加 HTTPS 监听器并删 HTTP。属性 → 空闲超时 300。 4. EC2 → 启动模板 → 创建：名称 bedrock-relay-lt；AMI Ubuntu 24.04；t3.small；不选密钥对；安全组 bedrock-relay-asg-sg；存储 16G gp3；高级：IAM 实例配置文件 bedrock-relay-role、元数据 v2 仅令牌、跃点限制 2、用户数据粘 install-relay.sh（开头先写两行 export RELAY_GPT_KEY=... RELAY_CLAUDE_KEY=...）。 5. EC2 → Auto Scaling 组 → 创建：选上面的模板（版本 Latest）；网络选默认 VPC 全部子网；负载均衡 → 附加到现有目标组；健康检查类型勾 ELB，宽限期 180；组大小 期望 2 / 最小 2 / 最大 4；标签 Project=bedrock-relay-poc 勾"传播到实例"。 6. 约 3 分钟后目标组两台 healthy。

香港每个 One API 节点：

cd /opt/oneapi
./add-relay-cert.sh <ALB域名>                                   # 自签证书才需要；用正规证书跳过
./setup-channels.sh <ALB域名> <GPT钥匙> <Claude钥匙> alb-1
./setup-channels.sh <ALB域名> <GPT钥匙> <Claude钥匙> alb-2       # 同一 ALB 第二套渠道，给 One API 重试用

控制台等价：每个模型建两个一模一样的 OpenAI 渠道（只差名字），设置 → 运营设置 → 失败重试次数 = 3。

验证（实测记录）： - ./failover-test.sh 20 全 ✅。 - 崩溃演练：aws ec2 terminate-instances --instance-ids <一台中继>（或控制台终止），同时 ./failover-test.sh 20。实测时间线：T+0 终止；T+16s ALB 标 unhealthy；T+28s 目标组只剩一台；T+2m10s ASG 判定失联、拉新机；T+3m45s 新机 healthy。请求 19/20，One API 日志 11 次 using channel #x to retry。 - 升级演练：aws autoscaling start-instance-refresh --auto-scaling-group-name bedrock-relay-asg --preferences '{"MinHealthyPercentage":50,"InstanceWarmup":90}'，期间连续跑 failover-test.sh。实测约 5 分钟两台全部换成新实例，期间 120 个请求 0 失败。

日常运维： - 改中继配置 / 升级镜像：改 install-relay.sh → aws ec2 create-launch-template-version --launch-template-name bedrock-relay-lt --source-version 1 --launch-template-data '{"UserData":"<base64>"}' → 上面的 instance refresh。控制台：启动模板 → 操作 → 修改模板（创建新版本）→ ASG → 实例刷新。 - 换钥匙：同上发新版模板 + 刷新，再改 One API 渠道密钥。 - 扩容：改 ASG 期望容量即可，ALB 自动注册。 - 看状态：ASG 活动历史、目标组健康页；建议给 ALB UnHealthyHostCount ≥ 1 和 HTTPCode_ELB_5XX_Count 加 CloudWatch 告警发到邮箱/企微。 - 已知限制：ALB 摘除坏节点前约 10 秒窗口，靠 One API 双渠道重试兜；极端情况（重试 3 次都落坏节点）仍会返回 502，业务侧保留客户端重试。

3.3.2 过渡方案：香港侧 nginx LB sidecar（无 ASG）

适合还没拿到 ALB/ASG 权限、或只有两台手工维护中继的阶段。在每个 One API 节点旁边起一个 relay-lb nginx 容器（docker-compose.override.yml），upstream 写死中继 IP，proxy_next_upstream ... non_idempotent 让失败的 POST 立刻换台。One API 指向 http://relay-lb:8080/...，不再需要 SSL_CERT_FILE。

cd /opt/oneapi
./add-relay-cert.sh <中继A IP>; ./add-relay-cert.sh <中继B IP>
sudo bash install-hk-lb.sh <中继A IP> <中继B IP>
./setup-channels.sh http://relay-lb:8080 <GPT钥匙> <Claude钥匙> lb

实测：停掉中继 A 的 nginx，随即 10 个请求 10/10。缺点：中继换 IP/重建后要到每个节点改 upstream 重跑脚本；坏机器不会自动补。One API 若跑在 k8s，等价做法是一个 nginx Deployment + Service。

3.3.3 EC2 崩溃后的行为（两种方案通用）

• 容器 restart: always：实例重启后自动拉起，实测 reboot 后 55 秒三容器 Up。
• ASG 方案：实例无响应/不健康 → 终止 → 按模板拉新机 → 注册 ALB，全程无人工。
• 非 ASG 方案：EC2 默认"简化自动恢复"处理宿主机故障；再加 CloudWatch StatusCheckFailed_Instance → 重启实例 告警；系统盘坏了要人手按 3.2.1 重开。
• 不要依赖 One API 的"自动禁用渠道"做故障转移：它只对 401/额度类错误触发。

4. 安全与运维清单

5. 实测记录（2026-09-15，账号 0808…，测试后资源已全部删除）

6. 文件清单（deliverables/）

Bedrock中继方案-修正版-2026-09-15.md      ← 本文
step1-账号权限测试/
  bedrock-test.py                          第一步：只需 python3，自动取实例角色，SigV4 签名，✅/❌ 判读
step2-中继机/
  install-relay.sh                         中继一键安装（可直接作 EC2 用户数据）；顶部可预设两把钥匙
  配置参考/docker-compose.yml | relay.conf.template | litellm.yaml | gen-cert.sh | selftest.sh
step2-香港OneAPI机/
  install-oneapi.sh                        全新装 One API（含 SSL_CERT_FILE、RELAY_TIMEOUT、管理令牌）
  add-relay-cert.sh <中继IP或ALB域名>       抓中继证书加入信任并重启 One API
  setup-channels.sh <中继地址> <GPT钥匙> <Claude钥匙> [后缀]   用 API 建两个渠道 + 重试次数 + 测试令牌
  e2e-test.sh                              端到端验证（4 非流式 + 2 流式）
  docker-compose.yml.参考
step3-高可用/
  install-hk-lb.sh <中继IP...>              过渡方案：One API 节点旁起 nginx LB sidecar（docker-compose.override.yml）
  create-asg-alb.sh                        推荐方案：一键建 ALB/目标组/证书/启动模板/Auto Scaling Group
  failover-test.sh [N]                     连发 N 个请求统计成功率
cli/
  bedrock-invoke-policy.json               中继角色的 IAM 策略（含 bedrock-mantle:CreateInference）
  01-create-iam-role.sh                    建角色 + 实例配置文件
  02-launch-relay.sh                       启动一台中继（安全组、AMI、hop limit、用户数据全自动）
  03-launch-oneapi-hk.sh                   （可选）启动香港 PoC One API 机
  99-cleanup.sh                            按标签 Project=bedrock-relay-poc 删光所有测试资源（含 ASG/启动模板/ALB）

7. 仍需客户侧确认

1. 客户现网 One API 的版本/分支（本次按 songquanpeng/one-api 最新版 justsong/one-api:latest 验证；new-api 等分支界面字段名略有不同，但"OpenAI 类型渠道 + base_url + 密钥"的逻辑一致）。
2. 客户香港 One API 的部署形态：几台、docker 还是 k8s、各节点出口 IP 是什么（ALB 安全组要全放）。是否在 AWS 上不影响方案。
3. 是否有公司域名：有则中继/ALB 证书可换成正规证书，省掉 add-relay-cert.sh 这一步。
4. 业务方是否能改 max_tokens → max_completion_tokens；不能则 GPT 走 gpt-5.6-converse。