212 lines
4.9 KiB
Markdown
212 lines
4.9 KiB
Markdown
# 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
|
||
- 错误情况
|
||
|
||
---
|
||
|
||
**上一步：** [安装 SDK 与初始化](./sdk-installation.md)
|
||
**下一步：** [流式输出（SSE）接入](./streaming.md)
|