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

# API Key 创建与管理

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

## 🔑 什么是 API Key？

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

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

## 📋 创建 API Key

### 步骤 1：进入控制台

1. 登录 [Websopy 控制台](https://console.websopy.com)
2. 导航到 **开发者中心 → API Key**
3. 点击 **创建新 Key**

### 步骤 2：配置 Key

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

### 步骤 3：保存 Key

⚠️ **重要**：API Key 只显示一次，请立即：
1. 复制保存到安全位置
2. 设置环境变量

```bash
# 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:*` | 所有权限 | ⚠️ 仅管理员 |

### 权限组合

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

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

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

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

## 🚫 IP 白名单

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

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

```text
# 支持的格式
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 次/分钟 |

### 查看当前用量

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

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

### 处理限流

```typescript
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))
}
```

## 🔐 安全最佳实践

### ✅ 推荐做法

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

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

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

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

### ❌ 避免事项

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

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

## 🔄 Key 轮换

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

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

## 📊 审计日志

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

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