API 密钥管理
API Key（API 密钥）是用于第三方系统对接 DNS-Go 的认证凭证。API Key 使用 SHA-256 哈希 存储，数据库中不会保存明文密钥，确保安全。
功能概述
API Key 管理提供以下功能：
- 创建密钥：生成唯一的 API Key，支持设置名称、描述和 IP 白名单
- 编辑密钥：修改密钥名称、描述、IP 白名单和状态
- 删除密钥：删除不再使用的 API Key
- 启用/禁用：临时禁用密钥而不删除
- IP 白名单：限制特定 IP 地址使用，空则不限制
- 最后使用时间：自动记录每次认证时间
适用场景
API Key 适用于以下场景：
- 第三方系统集成：其他系统通过 API 调用 DNS-Go 接口
- 自动化脚本：CI/CD 流水线自动化管理域名记录
- 微服务调用：内部微服务之间的认证
- 无需验证码：API Key 认证绕过图形验证码校验
管理 API Key
创建 API Key
超级管理员可以创建 API Key：
- 登录 Web 管理界面
- 进入 系统管理 → API Key 管理
- 点击 创建 API Key 按钮
- 填写以下信息：
| 字段 | 说明 | 必填 |
|---|---|---|
| 名称 | 密钥标识，如：第三方系统对接 | ✅ |
| 描述 | 用途说明 | ❌ |
| IP 白名单 | 逗号分隔的 IP 地址，留空则不限制 IP | ❌ |
- 点击 创建 按钮
⚠️ 重要：创建成功后，系统会 一次性 显示完整 API Key。请立即复制并安全保存，关闭对话框后无法再次查看完整密钥。
编辑 API Key
- 在 API Key 列表中找到目标密钥
- 点击 编辑 按钮
- 修改名称、描述、IP 白名单或状态
- 点击 保存
启用/禁用
在 API Key 列表中直接点击 启用 或 禁用 按钮，无需打开弹窗：
- 启用：密钥可正常认证使用
- 禁用：认证时返回 401，密钥暂时不可用
删除 API Key
- 在列表中找到要删除的密钥
- 点击 删除 按钮
- 在弹出确认框中确认删除
⚠️ 警告：删除操作不可恢复，使用该密钥的服务将立即无法访问。
使用 API Key
认证方式
API Key 通过请求头 X-API-Key 传递，与 JWT Token 认证兼容并存：
bash
# 使用 API Key 进行认证
curl -X GET http://localhost:8085/api/system/info \
-H "X-API-Key: dnsgo_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"
# 无需 Bearer Token，也无需验证码认证优先级
请求认证流程：
请求到达
↓
检测 X-API-Key 请求头
├─ 有 API Key → 验证密钥（哈希校验）
│ → 检查 IP 白名单
│ → 检查密钥状态（是否禁用）
│ → 通过后设置 role=admin 放行
│ → 异步更新 last_used_at
└─ 无 API Key → 继续原有 JWT Bearer Token 认证IP 白名单说明
创建或编辑 API Key 时，可以在 allowed_ips 字段设置 IP 白名单：
- 留空（默认）：所有 IP 均可使用此 API Key
- 填写 IP：只有白名单中的 IP 可以访问，不匹配则返回 403
- IP 之间用逗号分隔，支持单个 IP 和 CIDR 网段
bash
# 示例：仅允许特定 IP 使用
X-API-Key: dnsgo_xxxxx
# 后台配置 allowed_ips = "192.168.1.100,10.0.0.0/8"安全建议
- 定期轮换密钥：建议每 90 天更换一次 API Key
- 设置 IP 白名单：尽量限制可使用的 IP 范围
- 最小权限原则：按需创建密钥，不共享
- 及时禁用：不再使用的密钥及时禁用或删除
- 监控使用情况：关注 last_used_at 字段，发现异常立即禁用
- 安全传输：API Key 仅在 HTTPS 加密通道中传输
常见问题
Q: API Key 和 JWT Token 有什么区别？
| 特性 | API Key | JWT Token |
|---|---|---|
| 适用场景 | 第三方系统对接 | 用户 Web 登录 |
| 有效期 | 永久（可手动禁用） | 可配置过期时间 |
| IP 限制 | ✅ 支持白名单 | ❌ 不支持 |
| 验证码 | ❌ 不需要 | ✅ 需要（可配置） |
| 存储方式 | SHA-256 哈希 | 客户端保存，服务端验证签名 |
| 管理方式 | 后台管理页面 | 登录/登出 |
Q: API Key 丢失怎么办？
API Key 仅在创建时展示一次。如果丢失：
- 登录后台创建新的 API Key
- 删除旧的 API Key
- 更新对接系统使用新密钥
Q: 可以创建多个 API Key 吗？
可以，系统支持创建任意数量的 API Key，方便区分不同的对接方。
Q: 如何查看 API Key 的使用情况？
在列表中可以查看每个密钥的 最后使用时间（last_used_at），如果显示"从未使用"表示该密钥创建后未被调用过。
相关文档
- JWT 认证 - 了解 JWT Token 认证机制
- 权限控制 - 详细了解权限系统
- API 文档 - API 密钥管理 - 查看完整 API