Files

2026-04-23 16:30:57 +08:00

4.9 KiB

Raw Blame History

title, description, category, order

title	description	category	order
API Key 创建与管理	在控制台创建 API Key，了解权限范围与速率限制，安全使用建议。	getting-started	3

API Key 创建与管理

在控制台创建 API Key，了解权限范围与速率限制，安全使用建议。

🔑 什么是 API Key？

API Key 是调用 Websopy API 的凭证，类似于「数字身份证」，用于：

✅ 身份认证 - 证明你是平台用户
✅ 权限控制 - 控制可以访问哪些资源
✅ 用量统计 - 记录 API 调用情况
✅ 计费依据 - 按使用量进行计费

📋 创建 API Key

步骤 1：进入控制台

登录 Websopy 控制台
导航到 开发者中心 → API Key
点击 创建新 Key

步骤 2：配置 Key

配置项	说明
名称	给 Key 取个易识别的名字，如「生产环境」「测试用」
权限范围	选择 Key 允许的操作（见下文）
有效期	设置过期时间（可选）
IP 白名单	限制只有指定 IP 才能使用（可选）

步骤 3：保存 Key

⚠️ 重要：API Key 只显示一次，请立即：

复制保存到安全位置
设置环境变量

# Linux/macOS
echo 'export WEBSOPY_API_KEY="ws_live_xxxxx"' >> ~/.bashrc
source ~/.bashrc

# Windows PowerShell
[Environment]::SetEnvironmentVariable("WEBSOPY_API_KEY", "ws_live_xxxxx", "User")

🛡️ 权限范围

可用权限

权限	说明	适用场景
`user:read`	读取用户信息	数据展示
`user:write`	修改用户信息	用户管理
`project:read`	读取项目	数据展示
`project:write`	创建/修改/删除项目	项目管理
`storage:read`	读取文件	文件读取
`storage:write`	上传/删除文件	文件管理
`ai:agent`	使用 AI 智能体	AI 功能
`ai:knowledge`	管理知识库	知识库管理
`payment:read`	读取账单	账单查看
`admin:*`	所有权限	⚠️ 仅管理员

权限组合

推荐按最小权限原则配置：

// 只读权限（安全）
{
  "permissions": ["user:read", "project:read", "storage:read"]
}

// 读写权限（一般开发）
{
  "permissions": ["user:read", "user:write", "project:*", "storage:*"]
}

// AI 功能
{
  "permissions": ["ai:agent", "ai:knowledge"]
}

🚫 IP 白名单

增强安全性，限制只有指定 IP 可以使用 Key：

创建/编辑 Key 时开启「IP 白名单」
添加允许的 IP 地址或 CIDR 范围

# 支持的格式
203.0.113.1           # 单个 IP
203.0.113.0/24        # IP 段
203.0.113.1,198.51.100.0/24  # 多个，用逗号分隔

⏱️ 速率限制

套餐	请求限制
免费版	100 次/分钟
专业版	1,000 次/分钟
企业版	10,000 次/分钟

查看当前用量

const client = new WebsopyClient({
  apiKey: process.env.WEBSOPY_API_KEY
})

// 获取当前配额
const quota = await client.account.getQuota()
console.log('今日剩余:', quota.remaining)
console.log('重置时间:', quota.resetAt)

处理限流

async function callWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn()
    } catch (error) {
      if (error.code === 'RATE_LIMIT_EXCEEDED') {
        // 等待后重试
        await sleep(error.retryAfter * 1000)
        continue
      }
      throw error
    }
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms))
}

🔐 安全最佳实践

✅ 推荐做法

// 1. 使用环境变量，不硬编码
const client = new WebsopyClient({
  apiKey: process.env.WEBSOPY_API_KEY  // ✅ 正确
})

// ❌ 危险：硬编码在代码中
const client = new WebsopyClient({
  apiKey: 'ws_live_xxxxx'  // ❌ 危险
})

// 2. 区分不同环境的 Key
const client = new WebsopyClient({
  apiKey: process.env.NODE_ENV === 'production' 
    ? process.env.WEBSOPY_API_KEY_PROD 
    : process.env.WEBSOPY_API_KEY_DEV
})

// 3. 前端使用受限 Key
const client = new WebsopyClient({
  apiKey: process.env.WEBSOPY_API_KEY_PUBLIC,
  // 前端 Key 应该只开只读权限
  allowedMethods: ['user.getProfile', 'project.list']
})

❌ 避免事项

不要将 Key 提交到代码仓库
不要在前端暴露有写权限的 Key
不要使用同一个 Key 处理所有业务
不要通过 URL 参数传递 Key

# .gitignore
.env
.env.*
*.local

🔄 Key 轮换

定期更换 API Key 是个好习惯：

在控制台创建新 Key
更新所有使用旧 Key 的地方
验证新 Key 正常工作
禁用或删除旧 Key

📊 审计日志

在控制台查看 API Key 的使用记录：

调用时间、频率
调用的接口
请求来源 IP
错误情况

4.9 KiB Raw Blame History Unescape Escape