跳转至

认证方式

Unifiles 使用 API Key 进行身份认证。本文介绍如何获取和使用 API Key。

API Key 概述

API Key 是访问 Unifiles API 的凭证，格式为：

<api-key>
  • 前缀 sk_ 表示 Secret Key
  • live 表示生产环境（test 表示测试环境）
  • 后续为随机字符串

安全提示

API Key 应当妥善保管，不要在客户端代码或版本控制中暴露。

获取 API Key

SaaS 用户

当前公开仓库只保证自部署 Server 的实现。下列控制台流程需要一个单独部署的 SaaS 控制台；没有该服务时请使用“自部署用户”流程。

  1. 登录 Unifiles 控制台
  2. 进入「设置」→「API 密钥」
  3. 点击「创建新密钥」
  4. 复制并安全保存密钥（只会显示一次）

自部署用户

启动自部署 Server 时设置 bootstrap API Key：

export UNIFILES_BOOTSTRAP_API_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
unifiles-server --port 8088

# 使用 bootstrap Key 创建后续 Key
UNIFILES_API_KEY="$UNIFILES_BOOTSTRAP_API_KEY" \
UNIFILES_BASE_URL='http://localhost:8088' \
unifiles api-keys create production --scope 'files:*' 'kb:*'

或通过 API 创建（需要管理员权限）：

curl -X POST "http://localhost:8088/v1/api-keys" \
  -H "Authorization: Bearer <admin-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-key",
    "scopes": ["files:*", "kb:*"],
    "expires_at": "2027-01-15T10:30:00Z"
  }'

使用 API Key

Python SDK

from unifiles import UnifilesClient

# 方式 1: 直接传入
client = UnifilesClient(api_key="<api-key>")

# 方式 2: 从环境变量读取（推荐）
import os
client = UnifilesClient(api_key=os.environ["UNIFILES_API_KEY"])

# 方式 3: 自动读取环境变量
# 设置环境变量 UNIFILES_API_KEY 后，可以省略参数
client = UnifilesClient()

REST API

在请求头中添加 Authorization 字段：

curl -X GET "https://api.unifiles.dev/v1/files" \
  -H "Authorization: Bearer <api-key>"

环境变量配置

推荐使用环境变量管理 API Key：

export UNIFILES_API_KEY="<api-key>"

$env:UNIFILES_API_KEY = "<api-key>"

UNIFILES_API_KEY=<api-key>

使用 python-dotenv 加载：

from dotenv import load_dotenv
load_dotenv()

from unifiles import UnifilesClient
client = UnifilesClient()  # 自动读取环境变量

权限范围（Scopes）

API Key 可以配置不同的权限范围，限制其访问能力：

Scope 说明
files:read 读取文件信息和下载
files:write 上传和删除文件
files:* 文件的所有权限
extractions:read 读取提取结果
extractions:write 创建提取任务
extractions:* 提取的所有权限
kb:read 读取知识库和搜索
kb:write 创建和修改知识库
kb:* 知识库的所有权限
api_keys:* 管理 API 密钥
webhooks:* 管理 Webhooks
* 所有权限

创建限制权限的 Key

# 使用管理员 Key
admin_client = UnifilesClient(api_key="<admin-key>")

# 创建只读 Key
readonly_key = admin_client.api_keys.create(
    name="readonly-key",
    scopes=["files:read", "kb:read"]
)

# 创建只能搜索的 Key
search_key = admin_client.api_keys.create(
    name="search-only",
    scopes=["kb:read"]
)

API Key 管理

列出所有 Key

keys = client.api_keys.list()
for key in keys.items:
    print(f"{key.id}: {key.name} - {key.scopes}")

撤销 Key

client.api_keys.revoke(key_id="key_xxx")

设置过期时间

key = client.api_keys.create(
    name="temp-key",
    scopes=["files:*"],
    expires_at="2027-01-15T10:30:00Z"
)

print(f"过期时间: {key.expires_at}")

安全最佳实践

1. 使用环境变量

不要在代码中硬编码 API Key：

# ❌ 不要这样做
client = UnifilesClient(api_key="<api-key>")

# ✅ 推荐做法
import os
client = UnifilesClient(api_key=os.environ["UNIFILES_API_KEY"])

2. 限制权限范围

为每个应用创建专用 Key，只授予必要的权限：

# 为搜索服务创建只读 Key
search_key = admin_client.api_keys.create(
    name="search-service",
    scopes=["kb:read"]  # 只能搜索，不能修改
)

# 为上传服务创建写入 Key
upload_key = admin_client.api_keys.create(
    name="upload-service",
    scopes=["files:write", "extractions:write"]
)

3. 定期轮换

定期更换 API Key，降低泄露风险：

# 创建新 Key
new_key = admin_client.api_keys.create(
    name="production-v2",
    scopes=["*"]
)

# 更新应用配置使用新 Key
# ...

# 撤销旧 Key
admin_client.api_keys.revoke(old_key_id)

4. 监控使用情况

定期检查 API Key 的使用情况：

usage = client.usage.stats(
    start_date="2024-01-01",
    end_date="2024-01-31"
)

print(f"API 调用次数: {usage.total_requests}")
print(f"文件上传量: {usage.files_uploaded}")

常见问题

API Key 泄露了怎么办？
  1. 立即撤销泄露的 Key： 
    admin_client.api_keys.revoke(compromised_key_id)
  2. 创建新的 API Key
  3. 更新所有使用该 Key 的应用
  4. 检查是否有异常活动
如何在多环境中管理 Key？

为每个环境创建独立的 Key：

  • 开发、测试和生产环境均使用部署返回的 <api-key>；前缀只是实现细节，不要手工拼接。

使用环境变量区分：

import os

env = os.environ.get("ENV", "development")
api_key = os.environ.get(f"UNIFILES_API_KEY_{env.upper()}")

client = UnifilesClient(api_key=api_key)
API Key 过期了会怎样？

过期的 Key 会返回 401 错误：

{
  "success": false,
  "error": {
    "code": "AUTH_KEY_EXPIRED",
    "message": "API key has expired"
  }
}

需要创建新的 Key 并更新应用配置。

下一步