File size: 5,188 Bytes
0b2f2ef 2018c79 0b2f2ef 2018c79 0b2f2ef 2018c79 0b2f2ef 2018c79 0b2f2ef 2018c79 0b2f2ef 2018c79 0b2f2ef 2018c79 0b2f2ef 2018c79 0b2f2ef |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 |
# 私有 Hugging Face Spaces 访问指南
## 🔐 私有 Space 认证说明
当你的 Hugging Face Space 设置为 **private** 时，可以通过以下方式使用 access token 调用 API：
### 1. 获取 Hugging Face Access Token
1. 访问 [Hugging Face Settings](https://huggingface.co/settings/tokens)
2. 点击 "New token" 创建新的访问令牌
3. 选择适当的权限（通常选择 "Read" 权限即可）
4. 复制生成的 token（格式为 `hf_xxxxxxxxxx`）
### 2. 设置 Space 为私有
1. 进入你的 Space 设置页面
2. 在 "Visibility" 部分选择 **Private**
3. 保存设置
### 3. 使用 Access Token 调用 API
#### 方法一：Authorization Bearer Header
```bash
curl -X POST https://your-username-space-name.hf.space/screenshot \
-H "Content-Type: application/json" \
-H "Authorization: Bearer hf_your_token_here" \
-d '{"url": "https://example.com", "width": 1280, "height": 720}' \
--output screenshot.jpg
```
#### 方法二：JavaScript 调用
```javascript
const response = await fetch('https://your-username-space-name.hf.space/screenshot', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': 'Bearer hf_your_token_here'
},
body: JSON.stringify({
url: 'https://example.com',
width: 1280,
height: 720,
quality: 80
})
});
if (response.ok) {
const imageBlob = await response.blob();
// 处理图片数据
} else {
const error = await response.json();
console.error('Error:', error);
}
```
#### 方法三：Python 调用
```python
import requests
url = "https://your-username-space-name.hf.space/screenshot"
headers = {
"Content-Type": "application/json",
"Authorization": "Bearer hf_your_token_here"
}
data = {
"url": "https://example.com",
"width": 1280,
"height": 720,
"quality": 80
}
response = requests.post(url, headers=headers, json=data)
if response.status_code == 200:
with open("screenshot.jpg", "wb") as f:
f.write(response.content)
print("Screenshot saved successfully")
else:
print("Error:", response.json())
```
## 🔄 认证方式优先级
本 API 支持多种认证方式，按以下优先级处理：
1. **Hugging Face Token** (`Authorization: Bearer hf_xxx`) - 最高优先级
2. **自定义 API Key** (`Authorization: Bearer xxx` 或 `x-api-key: xxx`)
## 🚨 Token 安全注意事项
### ✅ 安全实践
- 定期轮换 access token
- 不要在客户端代码中硬编码 token
- 使用环境变量存储 token
- 为不同用途创建不同的 token
### ❌ 避免的做法
- 不要在 GitHub 等公开仓库中提交 token
- 不要在浏览器控制台中暴露 token
- 不要与他人分享你的 personal access token
## 📊 私有 Space 的优势
### 🔒 访问控制
- 只有拥有 token 的用户才能访问
- 可以精确控制 API 使用权限
- 保护敏感的截图服务不被滥用
### 📈 性能优势
- 更高的速率限制（100 次/15分钟 vs 30 次/15分钟）
- 优先级处理队列
- 更稳定的服务可用性
### 💰 成本控制
- 避免不必要的 API 调用
- 防止恶意使用导致的资源消耗
- 更好的使用量监控
## 🛠️ 环境变量配置
如果你想启用自定义 API key 认证，可以在 Space 设置中添加：
```bash
# 自定义 API key（可选）
API_KEY=sk-your-secure-api-key-here
```
**注意：** 即使没有设置 `API_KEY`，HF access token 仍然可以正常使用。
## 🔍 调试和监控
### 检查认证状态
```bash
curl https://your-username-space-name.hf.space/ \
-H "Authorization: Bearer hf_your_token_here"
```
响应会显示支持的认证方法：
```json
{
"message": "Page Screenshot API - Hugging Face Spaces",
"version": "1.4.0",
"authentication": {
"type": "API Key Required",
"required": true,
"note": "API key required for screenshot endpoint"
}
}
```
### 服务器状态监控
```bash
curl https://your-username-space-name.hf.space/status \
-H "Authorization: Bearer hf_your_token_here"
```
## 🆘 故障排除
### 401 Unauthorized
- 检查 token 是否正确
- 确认 token 以 `hf_` 开头
- 验证 token 长度至少 20 个字符
### 403 Forbidden
- Token 格式不正确
- Token 可能已过期或被撤销
- 检查 Space 的访问权限设置
### 示例错误响应
```json
{
"error": "Unauthorized",
"message": "Valid API key required. Please provide API key in Authorization header or x-api-key header.",
"hint": "Use \"Authorization: Bearer YOUR_API_KEY\" or \"x-api-key: YOUR_API_KEY\""
}
```
## 📝 最佳实践总结
1. **部署时设置为私有：** 在生产环境中始终使用私有 Space
2. **使用环境变量：** 通过环境变量管理敏感配置
3. **实施监控：** 定期检查 API 使用情况和性能
4. **Token 管理：** 定期轮换 access token，保持安全性
5. **错误处理：** 在客户端代码中正确处理认证错误
通过以上配置，你的私有 Hugging Face Space 将支持安全的 token 认证访问！ |