Lens

一个使用现代 TypeScript 构建的高性能图像代理和 Web 服务工具包。Lens 提供了一整套 Web 实用工具，包括图像处理、截图捕获、字体服务等。

🚀 特性

核心服务

• 🖼️ 图像代理: 使用 IPX 进行图像处理，支持调整大小、格式转换和优化
• 📸 截图捕获: 快速网站截图服务，带资源优化
• 📄 阅读器: 使用 Readability 提取文章内容（HTML/Markdown）
• 🅰️ 字体服务: 兼容 Google Fonts 的 API，支持多个提供商
• 🎨 Open Graph 图像: 动态生成 OG 图像
• 🎯 Favicon 提取: 从网站智能提取 Favicon
• 👤 Gravatar 代理: 基于电子邮件或哈希输入的缓存 Gravatar 头像代理
• 🤖 MCP 服务器: 通过 JSON-RPC 2.0 暴露所有服务作为工具的 Model Context Protocol 服务器

性能与可扩展性

• ⚡ Redis 缓存: 基于 Redis 的缓存，具有 24 小时智能缓存
• 🚀 资源优化: 通过阻止不必要的资源来优化页面加载
• 🛡️ 速率限制: 对昂贵操作进行速率限制
• 🔄 平滑降级: 自动为缺失的服务提供回退

📦 快速开始

前提条件

• Node.js 22+
• pnpm 10+（推荐）或 npm

安装

# Clone the repository

git clone https://github.com/bysages/lens.git

cd lens



# Install dependencies

pnpm install



# Copy environment configuration

cp .env.example .env

开发

# Start development server

pnpm dev



# Build for production

pnpm build



# Preview production build

pnpm preview

默认情况下，服务器将在 http://localhost:3000 启动。

🛠️ 配置

配置

所有配置都是可选的，并且会平滑降级：

# Image proxy security

ALLOWED_DOMAINS=example.com,cdn.example.com



# Caching (significantly improves performance)

REDIS_URL=redis://localhost:6379

请参阅 .env.example 获取所有可用选项。

📡 API 参考

所有缓存响应都包含 X-Cache 头（HIT/MISS）和 ETag 头，用于条件 304 响应。

图像

图像代理

实时转换和优化图像：

GET /img/{modifiers}/{image_url}

示例：

# Resize to 300px width, convert to WebP

https://api.bysages.com/img/w_300,f_webp/https://example.com/image.jpg



# Create 200x200 square thumbnail

https://api.bysages.com/img/s_200x200,q_80/https://example.com/image.png



# Smart crop with high quality

https://api.bysages.com/img/w_400,h_300,c_fill,q_95/https://example.com/photo.jpg

支持的修饰符：

• w_XXX - 宽度
• h_XXX - 高度
• s_XXXxYYY - 大小（宽度 x 高度）
• f_FORMAT - 格式（webp, jpg, png, avif）
• q_XXX - 质量（1-100）
• c_MODE - 裁剪模式（fill, fit, pad）

性能特性：

• 通过 Redis 缓存实现最佳性能
• 自动格式优化和压缩

截图捕获

使用 Playwright 对齐选项捕获网站截图：

GET /screenshot?url={website_url}&options

示例：

# Basic screenshot

https://api.bysages.com/screenshot?url=https://example.com



# JPEG with custom quality

https://api.bysages.com/screenshot?url=https://example.com&type=jpeg&quality=80



# Mobile screenshot with custom viewport

https://api.bysages.com/screenshot?url=https://example.com&width=375&height=667&mobile=true



# Full page capture

https://api.bysages.com/screenshot?url=https://example.com&fullPage=true



# Clip region (x,y,width,height)

https://api.bysages.com/screenshot?url=https://example.com&clip=0,0,400,300



# Transparent background

https://api.bysages.com/screenshot?url=https://example.com&omitBackground=true



# Disable animations for clean capture

https://api.bysages.com/screenshot?url=https://example.com&animations=disabled



# Custom CSS scale

https://api.bysages.com/screenshot?url=https://example.com&scale=css



# Inject custom stylesheet

https://api.bysages.com/screenshot?url=https://example.com&style=body{background:red}

参数：

性能说明：

• 截图缓存时间为1天，并有速率限制
• 相同请求返回缓存结果，响应时间在一秒以内
• 资源优化（阻止字体、媒体、WebSocket）可将截图生成速度提高60-80%

Open Graph 图像

生成动态 OG 图像：

GET /og?title={title}&description={description}

示例：

# Basic OG image

https://api.bysages.com/og?title=Welcome&description=Get%20started%20with%20Lens



# Custom styling

https://api.bysages.com/og?title=Hello%20World&theme=dark&fontSize=72&width=1200&height=630

缓存：

• 生成的 OG 图像缓存24小时
• 具有相同参数的相同请求会立即返回缓存结果

Web 服务

Reader (内容提取)

从任何 URL 提取渲染的 HTML 或 Markdown 内容：

GET /reader?url={website_url}&options

示例：

# Extract rendered HTML

https://api.bysages.com/reader?url=https://github.com/bysages/lens



# Convert to Markdown

https://api.bysages.com/reader?url=https://github.com/bysages/lens&format=markdown



# Wait for full page load

https://api.bysages.com/reader?url=https://github.com/bysages/lens&waitUntil=load

参数：

Favicon 提取

提取高质量的 favicon：

GET /favicon?url={website_url}&size={size}

示例：

# Extract favicon

https://api.bysages.com/favicon?url=github.com



# Custom size

https://api.bysages.com/favicon?url=github.com&size=64

特性：

• 从多个来源智能提取 favicon（PWA 清单、Apple 触摸图标、HTML 标签）
• 服务器端缓存30天，支持 ETag/304
• 如果未找到 favicon，则自动回退到生成的 favicon

Gravatar 代理

通过电子邮件、MD5 哈希或路径获取 Gravatar 头像。所有查询参数（除了 email/hash）都会直接转发给 Gravatar。您只需替换 URL 前缀即可从 Gravatar 切换。

GET /gravatar/{md5}?{gravatar_params}

GET /gravatar?email={email}

GET /gravatar?hash={md5}&{gravatar_params}

示例：

# By path (drop-in replacement for Gravatar URLs)

https://api.bysages.com/gravatar/{md5}?size=200



# By email

https://api.bysages.com/gravatar?email=user@example.com



# By MD5 hash

https://api.bysages.com/gravatar?hash={md5}



# With Gravatar parameters

https://api.bysages.com/gravatar?email=user@example.com&size=200&default=identicon&rating=pg

参数：

• {md5} - URL 路径中的 MD5 哈希（即插即用模式）
• email - 电子邮件地址（将自动进行 MD5 哈希处理）
• hash - 预先计算的 MD5 哈希（作为电子邮件的替代）
• 所有其他参数都将转发到 Gravatar API

MCP 服务器

通过 HTTP 上的 JSON-RPC 2.0 暴露所有 Lens 服务作为工具的 Model Context Protocol 服务器。

POST /mcp

使用 Claude Desktop 设置 (claude_desktop_config.json)：

{

  "mcpServers": {

    "lens": {

      "url": "https://api.bysages.com/mcp"

    }

  }

}

可用工具：

字体

字体服务

与 Google Fonts 兼容的 API，支持 v1 和 v2 两个端点：

GET /css?family={font_family}&display=swap

GET /css2?family={font_family}&display=swap

API 差异：

参数：

• family - 字体族名称（必填）
• display - 字体显示策略（默认：swap）
• subset - 字体子集（默认：latin）
• provider - 字体提供商（google, bunny, fontshare, fontsource，默认：google）
• proxy - 使用代理获取字体文件（true/false，默认：false）

示例：

# Basic font (v1 API - pipe separator)

https://api.bysages.com/css?family=Roboto:wght@400;700|Open+Sans:wght@300;400;600&display=swap



# Multiple fonts (v2 API - repeated family parameter)

https://api.bysages.com/css2?family=Inter:wght@400;700&family=Roboto:wght@300;400&display=swap



# Variable fonts with weight range (v2 only)

https://api.bysages.com/css2?family=Inter:wght@200..800&display=swap



# Font metadata

https://api.bysages.com/webfonts?sort=popularity&category=sans-serif

建议：

• 对于需要与旧版 Google Fonts 语法保持兼容性的应用，请使用 /css
• 对于需要支持可变字体并进行更好优化的现代应用，请使用 /css2
• 两个端点都支持所有字体提供商（Google, Bunny, Fontshare, Fontsource）

🏗️ 架构

Lens 是基于现代 Web 标准构建的，并遵循干净架构原则：

核心技术

• 运行时：Node.js 22+ 配合 Nitro
• 语言：TypeScript，严格的类型安全
• 图像代理：IPX 配合 Sharp
• 浏览器自动化：Playwright 配合 Crawlee BrowserPool
• 缓存：Redis 配合 unstorage

设计原则

• KISS（保持简单）：简单的、专注的解决方案优于复杂的抽象
• DRY（不要重复自己）：共享工具和配置
• 优雅降级：缺少依赖项时的回退机制
• 类型安全：全面的 TypeScript 覆盖
• 性能优先：优化速度和效率

🚀 部署

前提条件

• Node.js 22+ 运行时
• pnpm 10+ 包管理器
• Redis（可选，用于分布式缓存）

生产环境部署

# Build the application

pnpm run build



# Start production server

pnpm run preview

Docker 部署（推荐）

选项 1：使用 Docker Compose

# Copy environment variables

cp .env.example .env



# Edit .env file to configure your settings

# nano .env



# Start the application

docker-compose up -d



# View logs

docker-compose logs -f app



# Stop the application

docker-compose down

应用程序将在 http://localhost:3000 上可用。

堆栈包括：

• Lens 应用程序在端口 3000 上
• Redis 用于分布式缓存（可选但推荐）

选项 2：使用 Docker Run

# Pull the official image

docker pull bysages/lens:latest



# Run container with host network (recommended for accurate IP logging)

docker run -d \

  --name lens \

  --network host \

  --env-file .env \

  --restart unless-stopped \

  bysages/lens:latest



# View logs

docker logs -f lens



# Stop the container

docker stop lens

docker rm lens

选项 3：从源代码构建

# Build Docker image

docker build -t lens .



# Run container

docker run -d \

  --name lens \

  --network host \

  --env-file .env \

  --restart unless-stopped \

  lens

环境变量

所有配置都是可选的：

# Image Proxy Security

ALLOWED_DOMAINS=example.com,cdn.example.com



# Caching (significantly improves performance)

REDIS_URL=redis://localhost:6379

有关所有可用选项，请参阅 .env.example 文件。

📄 许可证

MIT 许可证 - 详情见 LICENSE 文件。

由 By Sages 用心打造。