Admin 控制台指南

Django Admin 是 Cordy Gateway 的控制平面。只有 ADMIN 或 OWNER 角色可以进入；MEMBER 用户使用独立的自助门户。

登录

生产快速开始使用 createsuperuser 创建首位运维用户。打开：

http://<admin-host>:<ADMIN_HTTP_PORT>/<DJANGO_ADMIN_URL>

ADMIN_HTTP_PORT 默认为 8001。DJANGO_ADMIN_URL 是你配置的私有路径，必须以 / 结尾。

配置上游模型

一个可调用的公开模型需要供应商中说明的五类记录：

1. Provider——名称与供应商类型，例如 OPENAI、ANTHROPIC、ARK 或其他大写标识。
2. Model——客户端发送的公开 slug，例如 gpt-4o-mini。
3. Provider model——把公开模型映射到上游模型 ID 与能力标志。
4. Channel——端点、加密凭据、优先级、权重、区域、限制及供应商配置。
5. Channel-provider-model——在该通道上启用对应映射。

示例：创建服务商 OpenAI、公开模型 gpt-4o-mini、上游模型 ID gpt-4o-mini，以及保存 OpenAI 密钥的通道，再添加 channel-provider-model 绑定。标准 OpenAI 集成使用其内置端点。缺少绑定或绑定未启用时，模型即使存在也无法路由。

交付给用户前，在 Channel 表单执行 Test connection。通道凭据由 CHANNEL_ENCRYPTION_KEYS 使用 Fernet 加密；Admin 与 Gateway 必须获得同一组密钥。

创建成员

打开 Users → Add 并设置：

字段	默认值	运维选择
邮箱 / 密码	必填	MEMBER 用它登录 /my/login/
角色	MEMBER	ADMIN/OWNER 仅用于运维人员
状态	ACTIVE	INACTIVE 或 SUSPENDED 无法登录或调用
套餐	free	free、pro、standard 或 enterprise
默认限速	每分钟 60 次	复制到通过 /my/ 创建的密钥
默认 token 配额	10,000	复制到通过 /my/ 创建的密钥
订阅到期 / 套餐 ID	空	可选账户元数据
预付余额	0	只读，必须通过流水操作修改

增加预付额度

额度是计费闸门。在用户列表：

1. 选择一个或多个用户；
2. 输入 Top-up USD 与可选原因；
3. 选择 Top up prepaid credit 并执行。

该操作会原子更新余额并追加 topup 流水，不能直接编辑余额。网关结算会追加负数 consume 流水；调整与退款也保留在只读账本中。

余额与 token 配额是两个独立控制： 余额为零返回 402 insufficient_credits；某把密钥的 token 配额耗尽返回 429 quota_exceeded。

签发并控制 API 密钥

成员可在 /my/ 创建与撤销自己的密钥。运维也可在 API keys 或用户内联区域创建。门户创建的密钥会复制用户默认限速与 token 配额；在 Admin 直接创建的密钥从 API key 模型默认值开始——每分钟 1,000 次与 10,000 token——因此成员需要不同限制时应明确填写这两个字段。生成的 wnx_ 明文只显示一次，系统仅保存 SHA-256 哈希。

新密钥默认包含以下推理作用域：

• chat
• completions
• embeddings
• models

客户端需要调用余额、订阅、套餐或账户分析接口时，再添加 balance。仅为明确的管理集成保留 admin。空作用域列表属于遗留的无限制行为；请使用明确的最小权限列表。

逐把检查状态、到期时间、每分钟限速、token 配额与已用配额。撤销会从下一次请求起生效。

限制模型

使用 User model permissions 为用户允许或拒绝公开模型。网关在密钥鉴权之后、路由之前执行该权限。用该用户密钥调用 GET /v1/models，确认可见列表符合预期。

设置全平台自助限制

打开 Users & Access → Platform settings。max_api_keys_per_user 默认为 3，限制成员在 /my/ 可创建的密钥记录数。当前计数包含已撤销与未激活密钥，因此撤销不会释放门户创建名额。同一页面显示只读的许可证状态与证据。请只保留一条 Platform settings 记录，并在接纳需要更多密钥的用户之前调整上限。

维护价格

打开 Gateway Config → Price audit，或编辑供应商模型中的 Price history 内联区。价格历史是请求时成本快照与成本报告的权威来源；Provider model 上较早的价格列已隐藏，不参与成本计算。

每条价格记录需设置：

• 供应商模型；
• 每 1,000 token 的输入与输出价格；
• 三位货币代码及其转换为美元的正数汇率；
• effective_from 与可选的排他 effective_to 时间；
• 来源：人工、服务商同步或账单调整。

同一供应商模型的生效窗口不能重叠。变更价格时不要改写历史：让当前记录在新价格开始时结束，再添加从同一时刻开始的新记录。请求时没有有效价格记录时，系统会保留明确的“成本未知”状态。

当前源码限制：cheapest 路由仍使用已隐藏的旧 Provider model 价格列评分，而不是 Price history。编辑 Price history 会更新计量与结算证据，但不会更新该路由输入。不要把 cheapest 视为受 Price audit 页面控制；启用前请针对你获得的交付版本验证此策略。

查看监控证据

Admin 提供以下运维视图：

视图	用途	写入行为
Platform overview / Usage & cost	请求、token、成本与健康的高层汇总	仅看板
Request logs	按请求 ID、用户、密钥、通道、状态、延迟、token、成本与可选追踪链接检索	只读
Usage stats	查看每日请求/token/成本聚合	只读
Channel health	修改路由配置前检查通道健康证据	运维证据
Audit log	查看操作者、对象、动作、时间与变更内容	仅追加，Admin 中只读

单个请求的诊断步骤见运维指南。不要通过编辑证据记录来让看板“对上”。

导入并核对上游账单

Admin 的 Cost Reconciliation 页面只读。先把服务商汇总 CSV 或 JSON 账单复制进 Admin 容器，再执行导入：

必填列为 provider、period_start、period_end 与 billed_amount，且 period_end 必须晚于 period_start。可选字段为 currency（默认 USD）、fx_rate_to_usd（默认 1）、request_count、prompt_tokens、completion_tokens、total_tokens，以及 JSON 对象 metadata。例如：

provider,period_start,period_end,currency,billed_amount,fx_rate_to_usd,request_count,prompt_tokens,completion_tokens,total_tokens
openai-main,2026-08-01,2026-09-01,USD,42.50,1,1200,800000,200000,1000000

docker compose -f docker-compose.prod.yml -f docker-compose.production-overrides.yml --env-file .env cp \
  ./invoice.csv admin:/tmp/invoice.csv

docker compose -f docker-compose.prod.yml -f docker-compose.production-overrides.yml --env-file .env exec admin \
  uv run python manage.py import_upstream_invoice /tmp/invoice.csv \
  --format auto --imported-by-email operator@example.com --output table

--format 接受 auto、csv 或 json；重复的来源记录会按证据身份跳过。随后按服务商与“起始日包含、结束日不包含”的账期核对：

docker compose -f docker-compose.prod.yml -f docker-compose.production-overrides.yml --env-file .env exec admin \
  uv run python manage.py reconcile_upstream_invoice \
  --provider openai-main --start 2026-08-01 --end 2026-09-01 \
  --threshold-absolute-usd 1.00 --threshold-percentage 5.0 \
  --created-by-email operator@example.com --format table

默认漂移阈值为 1.00 美元与 5.0%。预览时添加 --no-persist；省略它才会创建 Admin 中只读的 Reconciliation run。核对只比较请求时内部成本证据与导入账单总额，不会修改成员余额、价格或请求日志。

核对前如需运维专用的用量细分，可运行：

docker compose -f docker-compose.prod.yml -f docker-compose.production-overrides.yml --env-file .env exec admin \
  uv run python manage.py usage_cost_report \
  --group-by day,provider,model \
  --start 2026-08-01T00:00:00Z --end 2026-09-01T00:00:00Z \
  --format table

起始时间包含、结束时间不包含。还可按用户、API 密钥、通道、模型、服务商与状态筛选。

理解高级记录

• 平台运维可以创建 Prompt templates、versions 与 experiments，但当前 Gateway 请求代码不会读取或把它们注入 chat/completions。它们目前只是控制平面中的存储目录；修改后不会改变实时推理。
• Test runs 与 test artifacts 是内部质量运行工具导入的只读记录，不配置客户流量。
• Eval results 是附着在请求证据上的只读评估输出，不控制路由、计费或提示词。

在未来版本把它们接入受支持请求路径之前，请把这些页面视为内部证据/目录界面。

验证入驻

以成员身份：

1. 登录 /my/login/；
2. 创建密钥并复制仅显示一次的明文；
3. 确认余额与最近用量；
4. 调用 GET /v1/models；
5. 发起纯文本 POST /v1/chat/completions；
6. 确认请求出现在门户“用量”中，预付账本产生扣减。

健康检查与诊断见运维。