PRIVATE_SPACE_GUIDE.md

# 私有 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 认证访问！