claude-relay-service/docs/api-key-expiry-guide.md

API Key 过期时间管理指南

概述

Claude Relay Service 支持为 API Keys 设置过期时间，提供了灵活的过期管理功能，方便进行权限控制和安全管理。

功能特性

• ✅ 创建时设置过期时间
• ✅ 随时修改过期时间
• ✅ 自动禁用过期的 Keys
• ✅ 手动续期功能
• ✅ 批量续期支持
• ✅ Web 界面和 CLI 双重管理

CLI 管理工具

1. 查看 API Keys

npm run cli keys
# 选择 "📋 查看所有 API Keys"

显示内容包括：

• 名称和部分 Key
• 活跃/禁用状态
• 过期时间（带颜色提示）
• Token 使用量
• Token 限制

2. 修改过期时间

npm run cli keys
# 选择 "🔧 修改 API Key 过期时间"

支持的过期选项：

• ⏰ 1小时后（测试用）
• 📅 1天后
• 📅 7天后
• 📅 30天后
• 📅 90天后
• 📅 365天后
• ♾️ 永不过期
• 🎯 自定义日期时间

3. 批量续期

npm run cli keys
# 选择 "🔄 续期即将过期的 API Key"

功能：

• 查找7天内即将过期的 Keys
• 支持全部续期30天或90天
• 支持逐个选择续期

4. 删除 API Keys

npm run cli keys
# 选择 "🗑️ 删除 API Key"

Web 界面功能

创建时设置过期

在创建 API Key 时，可以选择：

• 永不过期
• 1天、7天、30天、90天、180天、365天
• 自定义日期

查看过期状态

API Key 列表中显示：

• 🔴 已过期（红色）
• 🟡 即将过期（7天内，黄色）
• 🟢 正常（绿色）
• ♾️ 永不过期

手动续期

对于已过期的 API Keys：

1. 点击"续期"按钮
2. 选择新的过期时间
3. 确认更新

自动清理机制

系统每小时自动运行清理任务：

• 检查所有 API Keys 的过期时间
• 将过期的 Keys 标记为禁用（isActive = false）
• 不删除数据，保留历史记录
• 记录清理日志

测试工具

1. 快速测试脚本

node scripts/test-apikey-expiry.js

创建5个测试 Keys：

• 已过期（1天前）
• 1小时后过期
• 1天后过期
• 7天后过期
• 永不过期

2. 迁移脚本

为现有 API Keys 设置默认30天过期时间：

# 预览（不实际修改）
npm run migrate:apikey-expiry:dry

# 执行迁移
npm run migrate:apikey-expiry

使用场景

1. 临时访问

为临时用户或测试创建短期 Key：

# 创建1天有效期的测试 Key
# 在 Web 界面或 CLI 中选择"1天"

2. 定期更新

为安全考虑，定期更新 Keys：

# 每30天自动过期，需要续期
# 创建时选择"30天"

3. 长期合作

为可信任的长期用户：

# 选择"365天"或"永不过期"

4. 测试过期功能

快速测试过期验证：

# 1. 创建1小时后过期的 Key
npm run cli keys
# 选择修改过期时间 -> 选择测试 Key -> 1小时后

# 2. 等待或手动触发清理
# 3. 验证 API 调用被拒绝

API 响应

过期的 API Key 调用时返回：

{
  "error": "Unauthorized",
  "message": "Invalid or inactive API key"
}

最佳实践

1. 定期审查：定期检查即将过期的 Keys
2. 提前通知：在过期前通知用户续期
3. 分级管理：根据用户级别设置不同过期策略
4. 测试验证：新功能上线前充分测试过期机制
5. 备份恢复：使用数据导出工具备份 Key 信息

注意事项

• 过期的 Keys 不会被删除，只是禁用
• 可以随时续期已过期的 Keys
• 修改过期时间立即生效
• 清理任务每小时运行一次