huawei-cloud-sac-new-api

华为云 NewAPI 大模型网关

概述

在华为云端到端部署“构建 NewAPI 大模型网关”解决方案。 该平台提供基于 NewAPI 的大模型 API 网关，用于统一管理和转发多个大模型 API 请求， 支持负载均衡、密钥轮换和用量统计。

架构： ECS（Ubuntu 22.04）、VPC、子网、安全组 （SSH 端口 22 和 NewAPI Web 端口 3000）、EIP 和 EVS （系统盘）。Cloud-init 安装 Docker 并启动 NewAPI 网关容器。

工具链： Playwright CLI（解决方案信息提取）+ Python 3.10+ （辅助脚本）+ Terraform 1.5+（声明式部署）。 不使用 KooCLI — 所有资源操作均通过 Terraform 完成。

前提条件

• Python 3.10+、Playwright CLI、Terraform 1.5+ — 请参阅 CLI 安装指南
• 通过环境变量设置华为云 AK/SK（HW_ACCESS_KEY、HW_SECRET_KEY）；如果未设置，则提示用户手动编辑 terraform.auto.tfvars.json 填写 AK/SK — ⛔ 绝不在对话上下文中读取或显示此文件
• 具有足够权限的 IAM 用户 — 请参阅 IAM 策略

安全

• 🚫 绝不在对话或输出中泄露 AK/SK
• 🚫 绝不要求用户在聊天中输入 AK/SK
• 🚫 绝不在对话上下文中读取或显示 terraform.auto.tfvars.json（其中包含 AK/SK）
• ✅ 优先使用 IAM 用户，而非主账号
• ✅ 修改操作（apply、destroy）必须获得用户明确确认

核心命令

占位符值（请参阅“参数”了解各操作系统对应的值）：

占位符	Linux / macOS	Windows PowerShell	Windows CMD
<python>	python3	python	python
<script_dir>	./scripts	./scripts	scripts
<temp_dir>	/tmp	$env:TEMP	%TEMP%
<region>	cn-north-4	cn-north-4	cn-north-4
<workdir>	newapi-workdir	newapi-workdir	newapi-workdir
<solution_detail_page_url>	（见下方说明）	（相同）	（相同）
<tf_template_url>	（见下方说明）	（相同）	（相同）

<solution_detail_page_url> = https://www.huaweicloud.com/solution/implementations/building-a-newapi-llm-gateway.html

<tf_template_url> = https://documentation-samples.obs.cn-north-4.myhuaweicloud.com/solution-as-code-publicbucket/solution-as-code-moudle/building-a-newapi-llm-gateway/building-a-newapi-llm-gateway.tf.json

# 1. Extract solution info
<python> <script_dir>/extract_sac_deploy_info.py \
  --url "<solution_detail_page_url>" \
  --out <temp_dir>/sac_selected.json

# 2. Download and normalize template
<python> <script_dir>/download_tf_template_file.py \
  --url "<tf_template_url>" \
  --out-dir <temp_dir>/<workdir>

<python> <script_dir>/normalize_tf_providers.py <temp_dir>/<workdir> \
  --region "<region>"

# 3. List variables for review
<python> <script_dir>/list_tf_variables.py <temp_dir>/<workdir>

# 4. Deploy
terraform -chdir=<temp_dir>/<workdir> init
terraform -chdir=<temp_dir>/<workdir> plan
# ⛔ STOP — Review the plan output above. Do NOT auto-apply.
# Confirm with the user (AskUserQuestion or equivalent) before proceeding.
# Only after explicit user confirmation:
terraform -chdir=<temp_dir>/<workdir> apply

# 5. Verify
terraform -chdir=<temp_dir>/<workdir> state list
terraform -chdir=<temp_dir>/<workdir> output -json

# 6. Cleanup
terraform -chdir=<temp_dir>/<workdir> destroy
python -c "import os; f='<temp_dir>/<workdir>/terraform.auto.tfvars.json'; os.path.exists(f) and os.remove(f)"

工作流

1. 提取解决方案信息

完成“核心命令”第 1 步后，向用户显示结果：

• 解决方案名称：输出 JSON 中的 title 字段
• 预估价格：estimated_price_text 字段
• 部署链接：列出 deploy_links 数组中每项的 text 和 url
• 如果 title 或 estimated_price_text 为空，请向用户发出警告，并建议在解决方案页面手动核实

2. 下载并规范化模板

normalize_tf_providers.py 会写入 terraform.auto.tfvars.json（包括区域 和其他参数）。如果未设置环境变量 HW_ACCESS_KEY/HW_SECRET_KEY，AK/SK 字段将留空。**告知用户文件路径，并提示他们手动编辑文件以填写 AK/SK。⛔ 绝不在对话上下文中读取或显示文件内容。**然后继续下一步。

3. 确认变量

与用户核对。如果敏感变量为空或强度不足，则阻止执行 apply。

4. 部署

⛔ 停止 — 运行 terraform apply 前，检查 terraform plan 的输出并征求用户确认（使用 AskUserQuestion 或等效方式）。 不要自动执行 apply。只有获得用户明确确认后才能继续。

5. 验证

请参阅验证方法和验收标准。

6. 清理

参数

参数	必填	默认值	限制
region	是	cn-north-4	仅支持此区域
AK/SK	是	—	环境变量 HW_ACCESS_KEY/HW_SECRET_KEY；如果未设置，请提示用户编辑 tfvars.json（⛔ 绝不要在上下文中读取 tfvars.json）
ecs_password	是	—	8-26 个字符，包含大小写字母、数字和特殊字符
ecs_flavor	否	x1.8u.16g	ECS 规格 ID
system_disk_size	否	100	40-1024 GB
bandwidth_size	否	300	EIP 带宽，单位为 Mbit/s
charging_unit	否	month	month 或 year
charging_period	否	1	—

部署后输出

• terraform output -json — 包含带有 NewAPI 网关 URL 的 access_instructions
• NewAPI Web 界面：http://<EIP>:3000（云初始化大约需要 10 分钟）
• 验证：ssh root@<EIP> "docker ps" 显示 NewAPI 容器正在运行

输出格式

terraform output -json 返回包含以下关键字段的 JSON：

{
  "access_instructions": { "value": "http://<EIP>:3000" },
  "ecs_eip":             { "value": "<Elastic IP>" },
  "ecs_id":              { "value": "<ECS Instance ID>" },
  "vpc_id":              { "value": "<VPC ID>" }
}

所有脚本输出均为 JSON 格式：extract_sac_deploy_info.py 输出解决方案信息 JSON，list_tf_variables.py 输出变量列表 JSON。

验证

逐步验证部署结果：

1. 模板提取 — 检查 <temp_dir>/sac_selected.json 是否包含 solution_name、price 字段
2. 模板下载 — 确认 <temp_dir>/newapi-workdir 下存在 .tf 文件， 且 terraform validate 通过
3. 变量确认 — list_tf_variables.py 输出中的敏感变量（AK/SK、密码）不为空；用户已确认覆盖值
4. 部署 — terraform plan 未显示错误；用户已确认部署；执行 apply 后， terraform state list 显示所有预期资源
5. 服务可访问性 — 等待 10-15 分钟让云初始化完成，然后 curl -s http://<EIP>:3000 返回 200
6. 容器 — ssh root@<EIP> "docker ps" 显示 NewAPI 容器正在运行

详情请参阅验证方法和 验收标准。

最佳实践

• 始终先执行 terraform plan，再执行 apply
• 从 charging_unit=month 开始；验证后再切换为 year
• 部署后预留 10-15 分钟等待云初始化完成
• 监控 NewAPI 仪表板中的 API 使用情况和密钥轮换状态

参考文档

文档	描述
CLI 安装指南	安装 Python、Playwright CLI、Terraform
IAM 策略	权限、委托设置、故障处理
验证方法	按工作流步骤逐步验证
验收标准	完整的部署验收清单
相关命令	Terraform、脚本、远程访问参考

注意事项

• 仅支持 cn-north-4 区域
• terraform.auto.tfvars.json 包含敏感信息 — 绝不要提交到 VCS；绝不要在对话上下文中读取或显示
• normalize_tf_providers.py 会将区域写入 tfvars；如果未设置环境变量，AK/SK 将留空，用户必须手动填写
• 工具链：Playwright CLI + Python + Terraform — 不使用 KooCLI