Welcome to the new VergeOS docs! The legacy docs remain available until they're retired later this year.
Legacy VergeOS Docs
Ctrlk
Verge.ioGitHub repoSupport
For the complete documentation index, see llms.txt. This page is also available as Markdown.

API 密钥

如何创建、管理和使用 API 密钥，以便程序化访问 VergeOS REST API，包括身份验证、IP 访问控制、过期设置和安全最佳实践。

概述

API 密钥为 VergeOS REST API 和集成服务提供程序化访问认证。每个 API 密钥都关联到一个特定用户账户，并继承该用户的权限和访问级别。这使应用程序、脚本和第三方工具无需交互式登录会话即可与 VergeOS 交互。

API 密钥的常见用途：

  • 用于自动化和集成的 REST API 认证

  • OpenAI 兼容的 AI 路由器访问

  • 第三方工具集成（监控、编排、IaC 工具）

  • CI/CD 流水线认证

了解 API 密钥认证

VergeOS 中的 API 密钥在 HTTP Authorization 头中作为 Bearer 令牌使用。与 UI 登录期间生成的会话令牌（在无操作后会过期）不同，API 密钥会一直有效，直到其配置的到期日期或被手动删除。

每个 API 密钥都会继承其关联用户账户的全部权限。为 Tenant Admin 用户创建的 API 密钥将具有 Tenant Admin 权限，而为 System Admin 创建的密钥将拥有系统级访问权限。

API 密钥与会话令牌

会话令牌是会在无操作后过期的临时凭据。API 密钥专为长期程序化访问而设计，并会一直有效，直到过期或被删除。

创建 API 密钥

转到 API 密钥管理

  1. 从 VergeOS 主菜单中，转到 系统 > 用户

  2. 选择将拥有该 API 密钥的用户账户

  3. 在用户仪表板中，单击 API 密钥 小组件以查看现有密钥

API 密钥部分显示一个表格，包含：

  • 名称：每个密钥的描述性标识符

  • 上次登录：最近一次认证时间戳

  • 上次登录 IP：上次认证的来源 IP

  • 到期时间：距过期还剩的天数

  • 创建时间：密钥生成时间戳

创建新的 API 密钥

  1. 点击 + 新建 API 密钥 位于 API 密钥表的底部

  2. 表单打开后会显示两个面板： API 密钥 （左侧）和 访问 （右侧）

配置 API 密钥设置

名称 （必填）输入 API 密钥的描述性标识符。清晰的命名有助于跟踪和管理密钥。

描述 （可选）添加有关该密钥用途、请求者或相关系统的更多上下文。

过期类型 选择如何管理密钥的有效期：

  • 设置日期：定义一个特定的到期日期（建议用于安全性）

  • 永不过期：创建永久密钥（请谨慎使用）

到期时间 （当选择“设置日期”时）使用日期/时间选择器设置密钥应在何时过期。常见的过期周期为 30、60 或 90 天。

配置访问控制

IP 允许列表 将 API 密钥限制为特定 IP 地址或 CIDR 范围。只有列出的地址才能使用此密钥进行认证。

  1. 点击 +（加号） 用于添加条目的图标

  2. 输入一个 IP 地址（例如， 192.168.1.100）或 CIDR 范围（例如， 192.168.1.0/24)

  3. 勾选复选框以启用该条目

  4. 根据需要添加其他条目

IP 拒绝列表 阻止特定 IP 地址或范围使用此密钥，同时允许其他所有地址。

  1. 点击 +（加号） 用于添加条目的图标

  2. 输入要阻止的 IP 地址或 CIDR 范围

  3. 勾选复选框以启用该条目

允许列表与拒绝列表的优先级

当两个列表都已配置时，IP 允许列表具有优先级。如果某个地址同时出现在两个列表中，则由允许列表决定访问权限。

保存并获取 API 密钥

  1. 检查所有设置是否正确

  2. 点击 提交 以生成 API 密钥

弹出窗口会显示生成的 API 密钥，并提供两个选项：

  • 复制：单击可将完整密钥字符串复制到剪贴板

  • 保存：单击可将密钥下载为 .PAK （受保护的 API 密钥）文件

一次性显示

完整的 API 密钥只会在创建时显示。关闭此弹出窗口后，就无法再取回完整密钥。如果您丢失了该密钥，必须将其删除并重新创建。

在妥善保管密钥后，关闭弹出窗口。新的 API 密钥将显示在 API 密钥表中。

管理现有 API 密钥

编辑 API 密钥

  1. 在 API 密钥表中，找到您要修改的密钥

  2. 点击 编辑 旁边的（铅笔）图标

  3. 更新设置（名称、描述、过期时间、IP 列表）

  4. 点击 提交 以保存更改

密钥字符串无法更改

编辑 API 密钥只会更新其元数据和访问控制。实际的密钥字符串无法修改。要更改密钥字符串，必须创建新的 API 密钥并删除旧密钥。

删除 API 密钥

  1. 在 API 密钥表中，找到您要移除的密钥

  2. 点击 删除 旁边的（垃圾桶）图标

  3. 确认删除

立即吊销

删除 API 密钥会立即吊销所有访问权限。任何使用已删除密钥的应用程序或脚本都将认证失败。

使用 API 密钥

认证格式

API 密钥在 HTTP Authorization 头中作为 Bearer 令牌使用：

API 请求示例

环境变量存储

为安全起见，请从环境变量加载 API 密钥，而不是将其硬编码：

安全注意事项

将 API 密钥视为密码 API 密钥会以关联用户的身份提供完整认证。请像保护密码一样谨慎保护它们。

使用 IP 限制 尽可能配置 IP 允许列表，以限制密钥可被使用的位置。这会在密钥泄露时显著降低风险。

设置到期日期 尽量避免使用永久密钥。定期过期可强制轮换密钥并限制暴露窗口。

监控密钥使用情况 定期检查“上次登录”和“上次登录 IP”字段，以识别异常访问模式。

删除未使用的密钥 移除不再需要的 API 密钥，以尽量缩小攻击面。

故障排除

API 密钥认证失败

确认密钥已作为 Bearer 令牌正确包含在 Authorization 头中。检查是否有多余空格或截断。

有效密钥被拒绝访问

检查 IP 允许/拒绝列表。您的来源 IP 可能未被允许，或者位于拒绝列表中。

密钥已过期

检查 API 密钥表中的“Expires”列。如果旧密钥已过期，请创建新密钥。

无法找回丢失的密钥

API 密钥在初始创建弹出窗口关闭后无法恢复。删除丢失的密钥并创建新密钥。

相关资源

上一页私有 AI 概述

最后更新于

这有帮助吗？