初始版本

public/docs/apikey.md

@@ -0,0 +1,211 @@
+# 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)