Upload 11 files

.dockerignore

@@ -0,0 +1,49 @@
+# Docker ignore file for HF Spaces
+node_modules
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.git
+.gitignore
+.dockerignore
+
+# Development files
+.env*
+*.md
+!README.md
+test-*.html
+test-*.md
+test-screenshot.jpg
+
+# Alternative deployment configs
+railway.toml
+render.yaml
+vercel.json
+.railwayignore
+Dockerfile.hf
+Dockerfile.simple
+deploy-hf.sh
+server-simple.js
+performance-config.js
+
+# Documentation
+API_GUIDE.md
+DEPLOYMENT_GUIDE.md
+HF_SPACES_ENV_GUIDE.md
+PRIVATE_SPACE_GUIDE.md
+RAILWAY_ALTERNATIVE.md
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE files
+.vscode/
+.idea/
+*.swp
+*.swo

.env.example

@@ -0,0 +1,26 @@
+# Environment Variables Configuration for Hugging Face Spaces
+# Copy these to your HF Spaces Settings → Variables
+
+# API Key Configuration
+API_KEYS=demo-key-123,production-key-456,client-key-789
+REQUIRE_API_KEY=true
+
+# Performance Settings (Optional)
+NODE_ENV=production
+PORT=7860
+
+# Security Settings (Optional)
+MAX_CONCURRENT_REQUESTS=3
+CPU_THRESHOLD=95
+
+# Instructions for Hugging Face Spaces:
+# 1. Go to your Space Settings
+# 2. Click on "Variables" tab
+# 3. Add each variable above (one per line, without quotes)
+# 4. Space will automatically restart with new configuration
+
+# Example API Keys (Generate your own secure keys):
+# - Use random strings of 20+ characters
+# - Include letters, numbers, and symbols
+# - Keep them secure and don't share publicly
+# - Consider using UUID format: 550e8400-e29b-41d4-a716-446655440000

API_GUIDE.md

@@ -0,0 +1,212 @@
+# API Authentication & Usage Guide
+
+## 🔐 Setting Up API Keys in Hugging Face Spaces
+
+### Step 1: Generate Secure API Keys
+```bash
+# Generate random API keys (example methods)
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+# Or use UUID format
+node -e "console.log(require('crypto').randomUUID())"
+```
+
+### Step 2: Configure in HF Spaces
+1. Navigate to your Space: `https://huggingface.co/spaces/your-username/space-name`
+2. Click **"Settings"** tab
+3. Click **"Variables"** section
+4. Add these environment variables:
+
+| Variable | Value | Description |
+|----------|-------|-------------|
+| `API_KEYS` | `key1,key2,key3` | Comma-separated API keys |
+| `REQUIRE_API_KEY` | `true` | Enable authentication |
+
+### Step 3: Test Authentication
+```bash
+# Test without API key (should fail)
+curl https://your-space.hf.space/screenshot
+
+# Test with API key (should work)
+curl -H "X-API-Key: your-key-here" https://your-space.hf.space/screenshot
+```
+
+## 📊 Understanding Server Status Responses
+
+### Normal Operation
+```json
+{
+  "status": "running",
+  "system": { "cpuUsage": "25%" },
+  "queue": { "activeRequests": 1, "queuedRequests": 0 }
+}
+```
+
+### Server Busy (CPU > 95%)
+```json
+{
+  "status": "busy",
+  "error": "Server is currently overloaded",
+  "cpuUsage": "96%",
+  "queueLength": 3
+}
+```
+
+### Queue Full Response
+```json
+{
+  "status": "busy", 
+  "error": "Request queue timeout",
+  "queueLength": 10
+}
+```
+
+## 🔄 Implementing Retry Logic
+
+### JavaScript Retry Pattern
+```javascript
+async function screenshotWithRetry(url, options = {}, maxRetries = 3) {
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      const response = await fetch('/screenshot', {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'X-API-Key': 'your-api-key'
+        },
+        body: JSON.stringify({ url, ...options })
+      });
+
+      if (response.ok) {
+        return await response.blob();
+      }
+
+      if (response.status === 503) {
+        const error = await response.json();
+        if (error.status === 'busy') {
+          console.log(`Attempt ${attempt}: Server busy, retrying...`);
+          await new Promise(resolve => setTimeout(resolve, 2000 * attempt));
+          continue;
+        }
+      }
+
+      // Other errors, don't retry
+      throw new Error(`API Error: ${response.status}`);
+      
+    } catch (error) {
+      if (attempt === maxRetries) throw error;
+      await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
+    }
+  }
+}
+```
+
+### Python Retry Pattern
+```python
+import time
+import requests
+from typing import Optional
+
+def screenshot_with_retry(url: str, api_key: str, max_retries: int = 3) -> Optional[bytes]:
+    for attempt in range(1, max_retries + 1):
+        try:
+            response = requests.post(
+                'https://your-space.hf.space/screenshot',
+                headers={'X-API-Key': api_key, 'Content-Type': 'application/json'},
+                json={'url': url},
+                timeout=30
+            )
+            
+            if response.status_code == 200:
+                return response.content
+                
+            if response.status_code == 503:
+                error_data = response.json()
+                if error_data.get('status') == 'busy':
+                    print(f"Attempt {attempt}: Server busy (CPU: {error_data.get('cpuUsage', 'N/A')})")
+                    time.sleep(2 * attempt)
+                    continue
+                    
+            response.raise_for_status()
+            
+        except requests.RequestException as e:
+            if attempt == max_retries:
+                raise e
+            time.sleep(attempt)
+    
+    return None
+```
+
+## 🚨 Rate Limiting & Best Practices
+
+### Rate Limit Headers
+The API returns rate limiting information:
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1640995200
+```
+
+### Best Practices
+1. **Implement exponential backoff** for retries
+2. **Cache results** when possible
+3. **Use appropriate image quality** (70-80% usually sufficient)
+4. **Monitor your usage** via `/status` endpoint
+5. **Handle queue timeouts** gracefully
+
+### Production Usage Example
+```javascript
+class ScreenshotAPI {
+  constructor(apiKey, baseUrl) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl;
+    this.requestCount = 0;
+    this.resetTime = 0;
+  }
+
+  async screenshot(url, options = {}) {
+    // Check rate limit
+    if (this.requestCount >= 95 && Date.now() < this.resetTime) {
+      throw new Error('Rate limit approached, waiting...');
+    }
+
+    const response = await this.makeRequest('/screenshot', {
+      method: 'POST',
+      body: JSON.stringify({ url, ...options })
+    });
+
+    // Update rate limit tracking
+    this.requestCount = parseInt(response.headers.get('X-RateLimit-Remaining') || '0');
+    this.resetTime = parseInt(response.headers.get('X-RateLimit-Reset') || '0') * 1000;
+
+    return response;
+  }
+
+  async makeRequest(endpoint, options = {}) {
+    return fetch(this.baseUrl + endpoint, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        'X-API-Key': this.apiKey,
+        ...options.headers
+      }
+    });
+  }
+}
+```
+
+## 🔧 Troubleshooting
+
+### Common Issues
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `401 Unauthorized` | Missing API key | Add `X-API-Key` header |
+| `403 Forbidden` | Invalid API key | Check key spelling/validity |
+| `503 Service Unavailable` | Server overloaded | Implement retry with delay |
+| `429 Too Many Requests` | Rate limit exceeded | Wait for reset time |
+
+### Performance Optimization
+- Use smaller dimensions for faster processing
+- Lower quality settings for non-critical uses
+- Batch requests with appropriate delays
+- Monitor CPU usage via `/status`

HF_SPACES_ENV_GUIDE.md

@@ -0,0 +1,184 @@
+# Hugging Face Spaces 环境变量设置指南
+
+## 🔧 在 HF Spaces 中设置环境变量
+
+### 方法一：通过 Web 界面设置
+
+1. **进入 Space 设置**
+   - 访问你的 Space：`https://huggingface.co/spaces/your-username/your-space-name`
+   - 点击页面顶部的 **"Settings"** 标签
+
+2. **添加环境变量**
+   - 在设置页面中找到 **"Variables"** 或 **"Environment Variables"** 部分
+   - 点击 **"Add Variable"** 或 **"New Variable"**
+
+3. **配置认证相关变量**
+
+   | Variable Name | Value | Description |
+   |---------------|-------|-------------|
+   | `REQUIRE_API_KEY` | `true` | 启用 API 认证 |
+   | `API_KEYS` | `key1,key2,key3` | 自定义 API 密钥列表 |
+   | `HF_TOKEN` | `hf_your_token` | Hugging Face access token（可选） |
+
+### 方法二：通过 Space YAML 配置
+
+在你的 Space 根目录创建或编辑 `README.md` 文件，在顶部添加配置：
+
+```yaml
+---
+title: Page Screenshot API
+emoji: 📸
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+license: mit
+variables:
+  REQUIRE_API_KEY: "true"
+  API_KEYS: "demo-key-123,production-key-456"
+  NODE_ENV: "production"
+---
+```
+
+## 🔐 推荐的环境变量配置
+
+### 基础配置（公开 Space）
+```bash
+# 不设置任何环境变量，或设置：
+REQUIRE_API_KEY=false
+```
+
+### 受保护配置（带自定义 API Key）
+```bash
+REQUIRE_API_KEY=true
+API_KEYS=your-secret-key-1,your-secret-key-2,backup-key-3
+```
+
+### 企业配置（多种认证方式）
+```bash
+REQUIRE_API_KEY=true
+API_KEYS=client-key-001,client-key-002,admin-key-999
+NODE_ENV=production
+MAX_CONCURRENT_REQUESTS=5
+CPU_THRESHOLD=90
+```
+
+## 🚨 重要安全注意事项
+
+### ✅ 安全的做法
+- **永远不要在代码中硬编码 token**
+- 使用 HF Spaces 的环境变量功能存储敏感信息
+- 为不同的客户端生成不同的 API key
+- 定期轮换 API keys
+
+### ❌ 避免的做法
+- 不要在 GitHub 仓库中提交包含 token 的 `.env` 文件
+- 不要在 README.md 的明文部分暴露真实的 API keys
+- 不要使用简单易猜的 API keys
+
+## 🔄 环境变量的工作原理
+
+在你的 Space 中，这些环境变量会被自动注入到运行环境中：
+
+```javascript
+// server.js 中的代码会自动读取这些环境变量
+const API_KEYS = process.env.API_KEYS ? 
+  process.env.API_KEYS.split(',').map(key => key.trim()) : [];
+const REQUIRE_API_KEY = process.env.REQUIRE_API_KEY === 'true';
+```
+
+## 📊 不同认证模式的配置示例
+
+### 模式 1：完全开放（演示用）
+```bash
+# 不设置任何环境变量
+# 所有人都可以访问 API，有基础速率限制（30次/15分钟）
+```
+
+### 模式 2：混合模式（推荐）
+```bash
+REQUIRE_API_KEY=false
+API_KEYS=vip-key-001,premium-key-002
+# 未认证用户：30次/15分钟
+# 认证用户：100次/15分钟
+# HF token 用户：100次/15分钟（自动支持）
+```
+
+### 模式 3：完全保护
+```bash
+REQUIRE_API_KEY=true
+API_KEYS=enterprise-key-001,client-key-002
+# 只有持有有效 API key 或 HF token 的用户才能访问
+```
+
+## 🛠️ 实际部署步骤
+
+### 1. 设置环境变量
+1. 进入 Space Settings → Variables
+2. 添加必要的环境变量：
+   ```
+   REQUIRE_API_KEY: true
+   API_KEYS: your-generated-key-1,your-generated-key-2
+   ```
+
+### 2. 生成安全的 API Keys
+```bash
+# 使用 Node.js 生成随机密钥
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+
+# 或生成 UUID 格式
+node -e "console.log(require('crypto').randomUUID())"
+```
+
+### 3. 验证配置
+部署后访问你的 Space 的健康检查端点：
+```bash
+curl https://your-space.hf.space/
+```
+
+响应应该显示认证状态：
+```json
+{
+  "authentication": {
+    "required": true,
+    "supportedMethods": [
+      "X-API-Key: custom-api-key",
+      "Authorization: Bearer custom-api-key",
+      "Authorization: Bearer hf_token (for private Spaces)"
+    ]
+  }
+}
+```
+
+## 🔄 动态配置更新
+
+环境变量更改后：
+1. Space 会自动重启
+2. 新的配置会立即生效
+3. 无需重新部署代码
+
+## 📈 监控和管理
+
+### 检查当前配置
+```bash
+curl https://your-space.hf.space/status
+```
+
+### 测试认证
+```bash
+# 测试自定义 API key
+curl -H "X-API-Key: your-key" https://your-space.hf.space/
+
+# 测试 HF token（如果 Space 是私有的）
+curl -H "Authorization: Bearer hf_your_token" https://your-space.hf.space/
+```
+
+## 💡 最佳实践建议
+
+1. **开发阶段**：使用开放模式进行测试
+2. **生产部署**：启用认证保护
+3. **密钥管理**：定期轮换 API keys
+4. **访问控制**：为不同用户组分配不同的 keys
+5. **监控使用**：定期检查 API 使用情况
+
+通过以上配置，你可以完全通过 Hugging Face Spaces 的界面管理所有认证相关的环境变量，无需在代码中硬编码任何敏感信息！

LICENSE

@@ -0,0 +1,27 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2024. All rights reserved.
+
+NOTICE: This software and its documentation are proprietary and confidential 
+information. This software is provided under a proprietary license agreement.
+
+RESTRICTIONS:
+- You may NOT copy, modify, or distribute this software
+- You may NOT reverse engineer or decompile this software  
+- You may NOT use this software for commercial purposes without a license
+- You may NOT redistribute or sublicense this software
+
+PERMITTED USES:
+- Personal, non-commercial use only
+- Educational purposes with proper attribution
+- Evaluation for potential commercial licensing
+
+COMMERCIAL LICENSING:
+Commercial use requires a separate license agreement. Contact the developer
+for commercial licensing terms and pricing.
+
+DISCLAIMER:
+This software is provided "AS IS" without warranty of any kind. The author
+shall not be liable for any damages arising from the use of this software.
+
+For licensing inquiries: [Contact Information]

PRIVATE_SPACE_GUIDE.md

@@ -0,0 +1,193 @@
+# 私有 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. **自定义 Bearer Token** (`Authorization: Bearer xxx`)
+3. **API Key Header** (`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 和 HF token，可以在 Space 设置中添加：
+
+```bash
+# 启用认证（可选）
+REQUIRE_API_KEY=true
+
+# 自定义 API keys（可选）
+API_KEYS=your-custom-key-1,your-custom-key-2,your-custom-key-3
+```
+
+**注意：** 即使设置了 `REQUIRE_API_KEY=false`，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.2.0",
+  "authentication": {
+    "required": true,
+    "supportedMethods": [
+      "X-API-Key: custom-api-key",
+      "Authorization: Bearer custom-api-key", 
+      "Authorization: Bearer hf_token (for private Spaces)"
+    ]
+  }
+}
+```
+
+### 服务器状态监控
+```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": "Invalid Hugging Face token format",
+  "message": "Hugging Face tokens should start with \"hf_\" and be at least 20 characters long",
+  "example": "Authorization: Bearer hf_abcdefghijklmnopqrstuvwxyz"
+}
+```
+
+## 📝 最佳实践总结
+
+1. **部署时设置为私有：** 在生产环境中始终使用私有 Space
+2. **使用环境变量：** 通过环境变量管理敏感配置
+3. **实施监控：** 定期检查 API 使用情况和性能
+4. **Token 管理：** 定期轮换 access token，保持安全性
+5. **错误处理：** 在客户端代码中正确处理认证错误
+
+通过以上配置，你的私有 Hugging Face Space 将支持安全的 token 认证访问！

README.md

@@ -8,49 +8,156 @@ pinned: false
 license: mit
 ---
 
-# Page Screenshot API
+# 📸 Page Screenshot API
 
-A web service that captures screenshots of web pages using Puppeteer, optimized for Hugging Face Spaces.
+Professional web page screenshot service built with Node.js and Puppeteer, optimized for Hugging Face Spaces.
 
-## Features
-- Web page screenshot capture
-- Customizable dimensions (width/height) 
-- Adjustable image quality
-- Rate limiting for API protection
-- CORS enabled for cross-origin requests
-- Interactive demo interface
+## 🚀 Live Demo
 
-## Live Demo
-Visit `/demo` to try the interactive screenshot tool!
+- **API Endpoint**: `https://your-username-page-shot.hf.space/screenshot`
+- **Demo Interface**: `https://your-username-page-shot.hf.space/demo`
+- **Health Check**: `https://your-username-page-shot.hf.space/`
 
-## API Usage
+## 🔐 Access Control
 
-### POST /screenshot
+This API uses **Hugging Face system-level authentication**:
+
+### Public Spaces
+- Open access for all users
+- Rate limited to 100 requests per 15 minutes
+- Perfect for demos and testing
+
+### Private Spaces
+- Requires valid Hugging Face access token
+- Access controlled by HF platform automatically
+- Higher security for production use
+
+## 📖 API Usage
+
+### Public Space Access
+```bash
+curl -X POST https://your-space.hf.space/screenshot \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com", "width": 1280, "height": 720}' \
+  --output screenshot.jpg
+```
+
+### Private Space Access
+```bash
+curl -X POST https://your-space.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 Example
+```javascript
+const response = await fetch('https://your-space.hf.space/screenshot', {
+  method: 'POST',
+  headers: {
+    'Content-Type': 'application/json',
+    // Add this line only for private spaces:
+    // 'Authorization': 'Bearer hf_your_token_here'
+  },
+  body: JSON.stringify({
+    url: 'https://example.com',
+    width: 1280,
+    height: 720,
+    quality: 80
+  })
+});
+
+const imageBlob = await response.blob();
+```
+
+## 📊 Parameters
+
+| Parameter | Type | Default | Range | Description |
+|-----------|------|---------|-------|-------------|
+| `url` | string | **required** | - | Target webpage URL |
+| `width` | number | 1280 | 100-1600 | Screenshot width in pixels |
+| `height` | number | 720 | 100-1200 | Screenshot height in pixels |
+| `quality` | number | 75 | 10-100 | JPEG quality percentage |
+
+## 🔄 Response Examples
+
+### Success Response
+```
+HTTP/1.1 200 OK
+Content-Type: image/jpeg
+Content-Length: 245760
+
+[Binary JPEG data]
+```
+
+### Error Response
+```json
+{
+  "error": "Failed to capture screenshot",
+  "message": "Navigation timeout exceeded"
+}
+```
+
+### Server Busy Response
 ```json
 {
-  "url": "https://example.com",
-  "width": 1280,
-  "height": 720,
-  "quality": 75
+  "status": "busy",
+  "error": "Server is currently overloaded",
+  "cpuUsage": "96%",
+  "queueLength": 3
 }
 ```
 
-**HF Spaces Limits:**
-- Width: 100-1600px
-- Height: 100-1200px  
-- Timeout: 15 seconds
-- Rate limit: 30 requests/15min
+## 🛠️ Features
 
-### GET /
-Health check endpoint
+- ✅ **Queue Management** - Handles concurrent requests efficiently
+- ✅ **CPU Monitoring** - Automatic load balancing
+- ✅ **Rate Limiting** - Prevents abuse
+- ✅ **HF Authentication** - Integrated with HuggingFace platform
+- ✅ **Error Handling** - Comprehensive error responses
+- ✅ **Demo Interface** - Built-in testing UI
+- ✅ **Health Monitoring** - Status endpoint for monitoring
 
-### GET /demo
-Interactive demo interface
+## 📈 Monitoring
 
-## Example Usage
+### Health Check
 ```bash
-curl -X POST /screenshot \
-  -H "Content-Type: application/json" \
-  -d '{"url": "https://google.com", "width": 1280, "height": 720}' \
-  --output screenshot.jpg
-```
+curl https://your-space.hf.space/
+```
+
+### Server Status
+```bash
+curl https://your-space.hf.space/status
+```
+
+## 🚨 Rate Limits
+
+| Space Type | Requests | Window |
+|------------|----------|--------|
+| Public | 100 | 15 minutes |
+| Private | 100 | 15 minutes |
+
+## 🔧 Deployment
+
+This application is optimized for Hugging Face Spaces with:
+- Docker-based deployment
+- Automatic dependency management
+- Resource-efficient Chrome configuration
+- Built-in security features
+- HuggingFace platform integration
+
+## 🔒 Security Notes
+
+- **Private Spaces**: Access automatically controlled by HF platform
+- **Public Spaces**: Open access with rate limiting
+- **No API keys needed**: Authentication handled by HuggingFace
+- **Secure by design**: Follows HF Spaces best practices
+
+## 📄 License
+
+Proprietary - Commercial use requires license. See [LICENSE](LICENSE) for details.
+
+## 🤝 Support
+
+For technical support or questions, please contact the administrator.

package.json

@@ -1,16 +1,17 @@
 {
   "name": "page-screenshot-api",
-  "version": "1.0.0",
-  "description": "Web page screenshot API service",
+  "version": "1.3.0",
+  "description": "Professional web page screenshot API service for Hugging Face Spaces",
   "main": "server.js",
   "scripts": {
     "start": "node server.js",
     "dev": "nodemon server.js",
     "build": "echo 'No build step required'"
   },
-  "keywords": ["screenshot", "api", "puppeteer"],
+  "keywords": ["screenshot", "api", "puppeteer", "huggingface", "spaces"],
   "author": "",
-  "license": "MIT",
+  "license": "UNLICENSED",
+  "private": true,
   "dependencies": {
     "express": "^4.18.2",
     "puppeteer": "^21.5.2",

server-simple.js

@@ -0,0 +1,54 @@
+const express = require('express');
+const puppeteer = require('puppeteer');
+const cors = require('cors');
+
+const app = express();
+const PORT = process.env.PORT || 7860;
+
+app.use(cors());
+app.use(express.json());
+
+// 健康检查
+app.get('/', (req, res) => {
+  res.json({ message: 'Page Screenshot API', status: 'running' });
+});
+
+// 截图端点
+app.post('/screenshot', async (req, res) => {
+  const { url, width = 1280, height = 720, quality = 75 } = req.body;
+
+  if (!url) {
+    return res.status(400).json({ error: 'URL is required' });
+  }
+
+  let browser;
+  try {
+    browser = await puppeteer.launch({
+      headless: 'new',
+      executablePath: '/usr/bin/google-chrome-stable',
+      args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage']
+    });
+
+    const page = await browser.newPage();
+    await page.setViewport({ width: parseInt(width), height: parseInt(height) });
+    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 15000 });
+    
+    const screenshot = await page.screenshot({
+      type: 'jpeg',
+      quality: parseInt(quality),
+      fullPage: false
+    });
+
+    res.set('Content-Type', 'image/jpeg');
+    res.send(screenshot);
+
+  } catch (error) {
+    res.status(500).json({ error: 'Screenshot failed', message: error.message });
+  } finally {
+    if (browser) await browser.close();
+  }
+});
+
+app.listen(PORT, () => {
+  console.log(`Screenshot API running on port ${PORT}`);
+});

server.js

@@ -3,44 +3,192 @@ const puppeteer = require('puppeteer');
 const cors = require('cors');
 const helmet = require('helmet');
 const rateLimit = require('express-rate-limit');
+const os = require('os');
 
 const app = express();
 const PORT = process.env.PORT || 7860;
 
-// 中间件配置 - HF Spaces 优化
+// 请求队列管理
+const requestQueue = [];
+let activeRequests = 0;
+const MAX_CONCURRENT_REQUESTS = 3;
+
+// CPU 监控
+let lastCpuUsage = 0;
+let cpuMonitorInterval;
+
+// 中间件配置
 app.use(helmet({
   contentSecurityPolicy: false
 }));
 app.use(cors());
 app.use(express.json({ limit: '10mb' }));
 
-// 速率限制
+// 简化的速率限制 - 所有用户统一限制
 const limiter = rateLimit({
   windowMs: 15 * 60 * 1000,
-  max: 30,
+  max: 100, // 统一的较高限制
   message: {
     error: 'Too many requests, please try again later.'
+  },
+  keyGenerator: (req) => {
+    return req.ip;
   }
 });
 app.use('/screenshot', limiter);
 
+// CPU 监控功能
+function startCpuMonitoring() {
+  const cpus = os.cpus();
+  
+  cpuMonitorInterval = setInterval(() => {
+    const cpus = os.cpus();
+    let totalIdle = 0;
+    let totalTick = 0;
+    
+    cpus.forEach(cpu => {
+      for (const type in cpu.times) {
+        totalTick += cpu.times[type];
+      }
+      totalIdle += cpu.times.idle;
+    });
+    
+    const idle = totalIdle / cpus.length;
+    const total = totalTick / cpus.length;
+    const usage = 100 - ~~(100 * idle / total);
+    
+    lastCpuUsage = usage;
+  }, 2000);
+}
+
+// 请求队列处理
+function processQueue() {
+  if (requestQueue.length === 0 || activeRequests >= MAX_CONCURRENT_REQUESTS) {
+    return;
+  }
+
+  if (lastCpuUsage >= 95) {
+    return;
+  }
+
+  const { req, res, next } = requestQueue.shift();
+  activeRequests++;
+  
+  const originalSend = res.send;
+  res.send = function(...args) {
+    activeRequests--;
+    setImmediate(processQueue);
+    return originalSend.apply(this, args);
+  };
+
+  next();
+}
+
+// 队列中间件
+const queueMiddleware = (req, res, next) => {
+  if (lastCpuUsage >= 95) {
+    return res.status(503).json({
+      status: 'busy',
+      error: 'Server is currently overloaded',
+      message: 'CPU usage is too high. Please try again later.',
+      cpuUsage: `${lastCpuUsage}%`,
+      queueLength: requestQueue.length
+    });
+  }
+
+  if (activeRequests >= MAX_CONCURRENT_REQUESTS) {
+    requestQueue.push({ req, res, next });
+    
+    const timeout = setTimeout(() => {
+      const index = requestQueue.findIndex(item => item.res === res);
+      if (index !== -1) {
+        requestQueue.splice(index, 1);
+        res.status(503).json({
+          status: 'busy',
+          error: 'Request queue timeout',
+          message: 'Request was queued too long and timed out.',
+          queueLength: requestQueue.length
+        });
+      }
+    }, 30000);
+
+    req.on('close', () => {
+      clearTimeout(timeout);
+      const index = requestQueue.findIndex(item => item.res === res);
+      if (index !== -1) {
+        requestQueue.splice(index, 1);
+      }
+    });
+
+    return;
+  }
+
+  activeRequests++;
+  
+  const originalSend = res.send;
+  res.send = function(...args) {
+    activeRequests--;
+    setImmediate(processQueue);
+    return originalSend.apply(this, args);
+  };
+
+  next();
+};
+
+// 启动 CPU 监控
+startCpuMonitoring();
+
 // 健康检查端点
 app.get('/', (req, res) => {
   res.json({
     message: 'Page Screenshot API - Hugging Face Spaces',
-    version: '1.0.0',
+    version: '1.3.0',
     status: 'running',
     platform: 'HuggingFace Spaces',
+    authentication: {
+      type: 'HuggingFace System Level',
+      note: 'Authentication is handled by HuggingFace platform for private Spaces'
+    },
     endpoints: {
       screenshot: 'POST /screenshot',
       demo: 'GET /demo',
-      health: 'GET /'
+      health: 'GET /',
+      status: 'GET /status'
+    },
+    license: 'Proprietary - Commercial use requires license'
+  });
+});
+
+// 服务器状态端点
+app.get('/status', (req, res) => {
+  const memUsage = process.memoryUsage();
+  
+  res.json({
+    status: 'running',
+    timestamp: new Date().toISOString(),
+    system: {
+      cpuUsage: `${lastCpuUsage}%`,
+      memoryUsage: {
+        rss: `${Math.round(memUsage.rss / 1024 / 1024)}MB`,
+        heapUsed: `${Math.round(memUsage.heapUsed / 1024 / 1024)}MB`,
+        heapTotal: `${Math.round(memUsage.heapTotal / 1024 / 1024)}MB`
+      },
+      uptime: `${Math.floor(process.uptime())}s`
+    },
+    queue: {
+      activeRequests,
+      queuedRequests: requestQueue.length,
+      maxConcurrent: MAX_CONCURRENT_REQUESTS
+    },
+    authentication: {
+      type: 'HuggingFace System Level',
+      note: 'No application-level authentication required'
     }
   });
 });
 
-// 截图API端点
-app.post('/screenshot', async (req, res) => {
+// 截图API端点 - 移除所有认证检查
+app.post('/screenshot', queueMiddleware, async (req, res) => {
   const { url, width = 1280, height = 720, quality = 75 } = req.body;
 
   if (!url) {
@@ -71,9 +219,8 @@ app.post('/screenshot', async (req, res) => {
 
   let browser;
   try {
-    console.log('Launching browser...');
+    console.log(`Taking screenshot of: ${url}`);
     
-    // HF Spaces 优化配置 - 明确指定 Chrome 路径
     const browserOptions = {
       headless: 'new',
       executablePath: '/usr/bin/google-chrome-stable',
@@ -93,7 +240,6 @@ app.post('/screenshot', async (req, res) => {
     };
 
     browser = await puppeteer.launch(browserOptions);
-
     const page = await browser.newPage();
     
     await page.setViewport({
@@ -115,8 +261,6 @@ app.post('/screenshot', async (req, res) => {
       }
     });
 
-    console.log(`Navigating to: ${url}`);
-    
     await page.goto(url, {
       waitUntil: 'domcontentloaded',
       timeout: 15000
@@ -124,15 +268,13 @@ app.post('/screenshot', async (req, res) => {
 
     await page.waitForTimeout(1000);
 
-    console.log('Taking screenshot...');
-    
     const screenshot = await page.screenshot({
       type: 'jpeg',
       quality: Math.max(10, Math.min(100, parseInt(quality))),
       fullPage: false
     });
 
-    console.log(`Screenshot taken: ${screenshot.length} bytes`);
+    console.log(`Screenshot completed: ${screenshot.length} bytes`);
 
     res.set({
       'Content-Type': 'image/jpeg',
@@ -163,7 +305,6 @@ app.post('/screenshot', async (req, res) => {
     if (browser) {
       try {
         await browser.close();
-        console.log('Browser closed');
       } catch (closeError) {
         console.error('Error closing browser:', closeError.message);
       }
@@ -171,9 +312,9 @@ app.post('/screenshot', async (req, res) => {
   }
 });
 
-// HF Spaces 演示界面
+// 简化的演示界面
 app.get('/demo', (req, res) => {
-  res.send(`
+  const demoHtml = `
     <!DOCTYPE html>
     <html>
     <head>
@@ -200,7 +341,7 @@ app.get('/demo', (req, res) => {
                 background: linear-gradient(135deg, #007bff, #0056b3); 
                 color: white; border: none; padding: 14px 28px; 
                 border-radius: 6px; cursor: pointer; font-size: 16px; font-weight: 600;
-                transition: transform 0.2s;
+                transition: transform 0.2s; margin: 5px;
             }
             button:hover { transform: translateY(-1px); }
             button:disabled { background: #6c757d; cursor: not-allowed; transform: none; }
@@ -214,12 +355,23 @@ app.get('/demo', (req, res) => {
                 padding: 8px 12px; margin: 5px; border-radius: 4px; cursor: pointer; font-size: 14px;
             }
             .example-btn:hover { background: #dee2e6; }
+            .status-info { background: #d1ecf1; padding: 15px; border-radius: 6px; margin-bottom: 20px; border-left: 4px solid #17a2b8; }
+            .hf-info { background: #d4edda; padding: 15px; border-radius: 6px; margin-bottom: 20px; border-left: 4px solid #28a745; }
         </style>
     </head>
     <body>
         <div class="container">
-            <h1>📸 Page Screenshot API</h1>
-            <p>Enter a URL to capture a screenshot. Optimized for Hugging Face Spaces.</p>
+            <h1>📸 Page Screenshot API Demo</h1>
+            <p>Professional screenshot service powered by Hugging Face Spaces.</p>
+            
+            <div class="hf-info">
+                <strong>🔐 Access Control</strong><br>
+                This service uses Hugging Face system-level authentication. If this Space is private, access is automatically controlled by HF platform.
+            </div>
+            
+            <div class="status-info">
+                <strong>📊 Server Status:</strong> <span id="serverStatus">Loading...</span>
+            </div>
             
             <div class="examples">
                 <strong>Try these examples:</strong><br>
@@ -250,11 +402,27 @@ app.get('/demo', (req, res) => {
             </div>
             
             <button onclick="takeScreenshot()" id="captureBtn">Take Screenshot</button>
+            <button onclick="checkStatus()" id="statusBtn">Check Status</button>
             
             <div id="result"></div>
         </div>
         
         <script>
+            async function checkStatus() {
+                try {
+                    const response = await fetch('/status');
+                    const data = await response.json();
+                    document.getElementById('serverStatus').innerHTML = 
+                        \`CPU: \${data.system.cpuUsage} | Queue: \${data.queue.queuedRequests} | Active: \${data.queue.activeRequests}\`;
+                    
+                    document.getElementById('result').innerHTML = 
+                        '<h3>Server Status:</h3><pre>' + JSON.stringify(data, null, 2) + '</pre>';
+                } catch (error) {
+                    document.getElementById('serverStatus').innerHTML = 'Error loading status';
+                    document.getElementById('result').innerHTML = '<p style="color: red;">Error: ' + error.message + '</p>';
+                }
+            }
+            
             function setExample(url) {
                 document.getElementById('url').value = url;
             }
@@ -279,7 +447,7 @@ app.get('/demo', (req, res) => {
                     const response = await fetch('/screenshot', {
                         method: 'POST',
                         headers: {
-                            'Content-Type': 'application/json',
+                            'Content-Type': 'application/json'
                         },
                         body: JSON.stringify({ url, width, height, quality })
                     });
@@ -288,6 +456,7 @@ app.get('/demo', (req, res) => {
                         const blob = await response.blob();
                         const imageUrl = URL.createObjectURL(blob);
                         const size = (blob.size / 1024).toFixed(1);
+                        
                         document.getElementById('result').innerHTML = 
                             '<div class="success"><h3>Screenshot Result:</h3>' +
                             '<p>Size: ' + size + ' KB | Dimensions: ' + width + 'x' + height + '</p>' +
@@ -295,9 +464,19 @@ app.get('/demo', (req, res) => {
                             '<a href="' + imageUrl + '" download="screenshot.jpg" style="background: #28a745; color: white; padding: 10px 20px; text-decoration: none; border-radius: 5px;">Download Image</a></div>';
                     } else {
                         const error = await response.json();
-                        document.getElementById('result').innerHTML = 
-                            '<div class="error"><strong>Error:</strong> ' + error.error + 
-                            (error.suggestion ? '<br><strong>Suggestion:</strong> ' + error.suggestion : '') + '</div>';
+                        let errorMsg = '<div class="error"><strong>Error:</strong> ' + error.error;
+                        
+                        if (error.status === 'busy') {
+                            errorMsg += '<br><strong>Status:</strong> Server is currently busy (CPU: ' + (error.cpuUsage || 'N/A') + ')';
+                            errorMsg += '<br><strong>Queue Length:</strong> ' + (error.queueLength || 0);
+                        }
+                        
+                        if (error.suggestion) {
+                            errorMsg += '<br><strong>Suggestion:</strong> ' + error.suggestion;
+                        }
+                        
+                        errorMsg += '</div>';
+                        document.getElementById('result').innerHTML = errorMsg;
                     }
                 } catch (error) {
                     document.getElementById('result').innerHTML = 
@@ -308,6 +487,12 @@ app.get('/demo', (req, res) => {
                 }
             }
             
+            // 页面加载时检查状态
+            checkStatus();
+            
+            // 每30秒更新一次状态
+            setInterval(checkStatus, 30000);
+            
             // Enter key support
             document.getElementById('url').addEventListener('keypress', function(e) {
                 if (e.key === 'Enter') {
@@ -317,7 +502,9 @@ app.get('/demo', (req, res) => {
         </script>
     </body>
     </html>
-  `);
+  `;
+  
+  res.send(demoHtml);
 });
 
 // 错误处理中间件
@@ -335,6 +522,17 @@ app.use((req, res) => {
   });
 });
 
+// 优雅关闭
+process.on('SIGTERM', () => {
+  console.log('SIGTERM received, shutting down gracefully...');
+  if (cpuMonitorInterval) {
+    clearInterval(cpuMonitorInterval);
+  }
+  process.exit(0);
+});
+
 app.listen(PORT, '0.0.0.0', () => {
   console.log(`Screenshot API server running on port ${PORT} for Hugging Face Spaces`);
+  console.log('Authentication: Handled by HuggingFace platform (system-level)');
+  console.log('No application-level authentication required');
 });