首次配置 Admin Console

这一页面向已经启动 Halro、准备配置第一条可调用链路的管理员。完成后，应用应只拿到一个 Gateway Key、Gateway 地址和公开模型别名；Provider 凭据、真实模型和价格仍只留在 Halro。

先确认版本

Credential、Provider、Deployment、Route、Project、推理 Key 和 Run Governance 都在正式版里； 其中 Run Governance 的接口成熟度仍是 experimental。使用前先用 halro version 核对实际 部署版本，并在安装中心确认各渠道已经验收到哪一版。

本页从“实例已经存在首个管理员”开始。v0.8.3 起的生产初始化能力：远程部署应使用只读 admin.setup_token_file，或在启动前执行幂等的离线 admin bootstrap，不再从服务日志取 Token。 完整交付、审计与恢复步骤见 生产环境 Admin 初始化与 Secret 生命周期；v0.8.2 及更早的发布包不支持这套命令和配置。

若 Web 初始化已经提交管理员，但登录会话创建失败，初始化实际上已经完成。不要重新提交或轮换密码， 直接转到 /admin/login 登录并检查 admin.bootstrap 审计事件。

开始前准备

先准备以下信息，不要边填表边猜：

开始前准备

信息	应由谁确认	用途
Provider 类型、访问面和官方 Base URL	平台管理员	决定凭据方案和协议 Profile
真实模型或部署 ID、Region、账户项目	Provider 管理员	建立准确的调用目标
模型能力和上限证据	应用负责人、平台管理员	决定 Deployment 可以承接什么请求
当前价格、币种、Region/Tier 和生效时间	FinOps、平台管理员	创建不可变 Price Version
公开别名、环境和故障域	应用负责人、平台管理员	设计 Route，而不把上游名称写进应用
Project 责任方、预算、限流和来源网段	业务负责人、平台管理员	建立访问与费用边界

生产 Admin 应通过 HTTPS 和受限网络访问，并使用 admin.mfa_policy: required。当前登录账号必须是 管理员；只读账号可以审查资源，不能创建或修改它们。完整的 Admin 入站和 MFA 参数见 配置参数参考。

一、保存 Credential

进入 凭据与服务商 → 凭据，创建与本次访问面匹配的 Credential：

1. 选择 Provider 类型和访问面；
2. 填写名称、绑定的 Base URL 和凭据；Bedrock Mantle 还要在这里选择 Region，Region 会进入凭据绑定的端点；
3. 若凭据有到期时间，填写真实到期时间；
4. 保存后确认页面只显示“已配置”，不再回显明文。

Credential 会绑定 Provider 类型、访问面和 Base URL。以后轮换同一端点的 Secret，应在原记录上 轮换；切换到另一个端点或凭据方案时创建新 Credential。不要把 Provider Key 放入 Gateway Key、 Project 名称、日志或测试正文。

可选：创建 Provider 出站代理

只有 Provider 必须通过指定网络出口访问上游时，才进入 凭据与服务商 → 出站代理 创建代理：

1. 使用带显式端口的 http:// 或 https:// CONNECT 地址；地址不能包含路径、查询参数、片段或内嵌用户名密码；
2. 需要 Basic Auth 时在表单中单独填写，密码由 Vault 加密且不会被 API 返回；
3. 访问私网、回环地址，或在明文 HTTP 上发送 Basic Auth，都必须完成界面要求的独立风险确认；
4. 容器内的 127.0.0.1 指向 Halro 容器自身，不是宿主机；请使用审核过的 host gateway、容器网络代理服务或主机网络；
5. 保存代理后，在 Provider 表单中选择它，再使用真实 Provider 连接测试验证出口。

已绑定代理的 Provider 在代理失败时不会静默直连。修改代理端点、认证或策略前，先停用或排空使用它的 Deployment；修改后重新执行 Provider 测试再恢复流量。删除仍被 Provider 引用的代理会被拒绝。

二、创建 Provider 连接

仍在 凭据与服务商 中创建 Provider：

1. 选择类型、访问面、Base URL 和刚才保存的 Credential；
2. Azure 等平台按界面补充 API Version、Project 等身份信息；Bedrock Region 来自所选 Credential；
3. 按网络边界选择“直连”或已经审核的出站代理；
4. 只启用这条连接实际允许的能力，不用“以后也许会用”扩大能力上限；
5. 保存后执行连接测试，并记录失败分类，而不是复制可能含敏感内容的上游错误正文。

部分访问面只有在至少存在一个 Deployment 后才能选择真实模型执行 Provider 测试；如果界面明确提示 需要 Deployment，先完成下一步，再回到 Provider 执行测试。这不是测试通过，也不应手动绕过提示。

一条连接可以由 Halro 解析为多个协议绑定。Profile 决定请求能如何编码和哪些字段会在 Provider I/O 前被拒；它不是营销名称。连接成功也只证明凭据和端点可达，不证明某个模型具备工具、视觉或结构化 输出能力。

三、选择真实目标并建立能力证据

进入 模型部署 创建 Deployment：

1. 选择 Provider，再刷新该 Provider 的真实模型或调用目标列表；
2. 上游能枚举时，从刷新结果选择目标。列表只能证明“谁存在”，不能单独证明“它能做什么”；
3. 目录已覆盖的模型，核对其不可变能力快照和来源；
4. 未知或冲突目标，先确认正确的协议绑定，再由管理员显式声明，或执行受控能力检测；
5. 只保留业务实际需要且已有证据的能力，并设置 Deployment 并发上限；
6. 保存后执行 Deployment 测试。

能力检测会真实调用 Provider，可能产生上游费用。这类控制面调用不计入 Project 预算、Accounting Ledger 或 Usage，不能用业务账单证明它已被 Halro 归集。检测的 unsupported、inconclusive、 unavailable 和 unauthorized 含义不同；没有得到可信结论时保持关闭，不能把沉默当作支持。

四、创建生效的 Price Version

在 Deployment 的 价格版本 中选择“设置价格”：

1. 确认计价对象正是该 Provider、目标、Region 和 Tier；
2. 按上游规则填写输入、缓存输入、输出的 USD / 1M tokens，以及适用时的 USD / request；
3. 只有确认该目标确实免费时才选择 free，不能用四个零表示“尚未核价”；
4. 填写价格依据和复核说明，选择立即生效或未来生效；
5. 在确认页用示例用量复算金额，再创建不可变版本。

没有已生效的价格版本时，默认成本治理会在 Provider I/O 前拒绝流量。调价、分时价位、价格建议、 恢复后的 pricing quarantine 和验收方法见 版本化定价与 Project/Token Guard。

五、创建公开 Route

进入 模型路由，使用应用稳定依赖的公开别名，例如 support-chat-prod：

• 单目标先创建一条启用 Route，并确认它没有被能力漂移、价格或依赖状态扣留；
• 主备使用 ordered，数字较小的优先；round_robin 用于分流，不代表主备；
• 同一别名下只放语义能力相当、价格已配置且处于不同故障域的目标；
• 原生 Anthropic、延迟任务和 Files/Batches 等资源操作有固定或唯一目标约束，不能照搬同步 Chat 的回退设计。

执行 Route 测试，确认实际选中的 Deployment、Provider 和 Profile 与预期一致。测试会真实调用上游， 可能产生费用。

六、创建 Policy 和 Project

需要 Token Guard 或 Redaction 时，先在 安全策略 中创建并测试策略，再进入 项目与密钥 创建 Project。至少逐项确认：

六、创建 Policy 和 Project

Project 设置	决策问题
Allowed Models	这个业务只能调用哪些公开 Route 别名？
Daily Budget	该 Project 在记账时区的一个自然日最多花多少？
RPM、TPM、最大并发	正常峰值和故障重试最多允许多大？
输入/输出 Token、正文和流时长	单请求最坏成本和资源占用是否有界？
Allowed CIDRs	哪些应用网段可以使用该 Project 的 Key？
Token Guard / Redaction	异常检测和数据处理是否已用真实样本验收？
Deferred Responses	是否接受把成功结果密封写入本机数据目录？
Run Governance	是否使用 v0.7 Work Unit、Run、Outcome 和 Run 预算？

Project 使用公开别名授权，不直接绑定 Provider 或 Deployment。开发、预发布和生产应使用不同 Project 与别名；需要独立预算或责任人的生产工作负载也应分开。

七、签发 Gateway Key

在 Project 的 Key 区域创建应用 Key：

• 普通推理只授予 inference；
• v0.7 Agent 编排按需增加 work_unit:create、run:create、run:attach；
• 业务验收单独使用只有 outcome:write、按需带 governance:read 的 Key；
• 设置负责人、用途和到期轮换计划。

Key 明文只显示一次。先复制到应用的 Secret 管理系统，再关闭弹窗；如果明文丢失，撤销该 Key 并 重新签发，不能从 Halro 取回。

八、完成首条受控验收

先检查 Gateway 就绪状态：

curl -fsS http://127.0.0.1:8080/health/ready

再用应用 Key 和公开别名发一个有明确输出上限的请求：

export HALRO_GATEWAY_KEY='gw_...'
curl https://halro.example.com/v1/chat/completions \
  -H "Authorization: Bearer $HALRO_GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model":"support-chat-prod",
    "max_tokens":64,
    "messages":[{"role":"user","content":"只回复 READY"}]
  }'

验收不以 HTTP 200 为终点。还要在 用量与调用 中确认：

• Request 归入正确 Project，Attempt 选中预期 Route、Deployment 和 Provider；
• Attempt 带当前 Price Version 快照，费用不是未知值或被误填的免费值；
• Token、延迟、错误分类和 Provider Request ID 符合预期；
• 用无权 Key、未授权别名和超低预算各做一次负向测试，均在 Provider I/O 前拒绝；
• 主备 Route 还要分别验证安全回退和歧义失败不回退。

本地开发实例可使用 开发者工作台 发同样的真实 Gateway 请求。它不是模拟器，仍会访问 Provider 并可能计费；远程 Admin 建议关闭该功能。应用接入的错误与重试处理继续阅读 我拿到了一个 Key和重试、超时与幂等。