d6da2c795d
- 支持 `/?url=...` 查询参数调用方式，兼容标准 API 格式 - 为根路径添加功能完整、响应式的 HTML 落地页，包含使用示例、特性介绍和动画效果 - 更新 README 文档，说明两种调用方式（路径参数和查询参数）
75 lines
3.6 KiB
Markdown
75 lines
3.6 KiB
Markdown
# WordPress mShots Proxy
|
||
|
||
这是一个基于 Node.js 的 WordPress mShots 服务反向代理，主要用于缓存截图请求，减少回源次数，并支持自动协议检测。
|
||
|
||
## 功能特性
|
||
|
||
- **反向代理**: 代理请求到 `https://s0.wp.com/mshots/v1`。
|
||
- **持久化缓存**: 将有效的图片响应缓存到本地文件系统 (`cache/` 目录)。
|
||
- **兜底机制**: 当上游服务不可用时，尝试返回本地已有的缓存。
|
||
- **自动协议检测**: 支持省略 URL 协议（http/https），系统会自动检测目标主机是否支持 HTTPS (端口 443)，若支持则优先使用 HTTPS，否则降级为 HTTP。
|
||
|
||
## 安装与运行
|
||
|
||
1. 安装依赖:
|
||
```bash
|
||
npm install
|
||
```
|
||
|
||
2. 启动服务:
|
||
```bash
|
||
npm start
|
||
```
|
||
默认运行在端口 `11489`。
|
||
|
||
## 使用方法
|
||
|
||
### 基础用法
|
||
|
||
支持两种调用方式：
|
||
|
||
**1. 路径参数 (推荐)**:
|
||
|
||
- `http://localhost:11489/https://www.baidu.com`
|
||
- `http://localhost:11489/www.baidu.com` (自动检测协议)
|
||
|
||
**2. 查询参数 (兼容标准 API)**:
|
||
|
||
- `http://localhost:11489/?url=https://www.baidu.com`
|
||
- `http://localhost:11489/?url=www.baidu.com`
|
||
|
||
### 自动协议检测 (新功能)
|
||
|
||
你可以省略 `http://` 或 `https://`，服务会自动判断：
|
||
|
||
- `http://localhost:11489/www.baidu.com`
|
||
- 系统会尝试连接 `www.baidu.com:443`。
|
||
- 如果连接成功，将代理到 `https://s0.wp.com/mshots/v1/https://www.baidu.com`。
|
||
- 否则，将代理到 `https://s0.wp.com/mshots/v1/http://www.baidu.com`。
|
||
|
||
## 环境变量
|
||
|
||
- `PORT`: 指定服务监听端口 (默认 11489)。
|
||
|
||
## 更新日志
|
||
|
||
- **2026-01-25**:
|
||
- 并发健壮性提升：
|
||
- 实现 **请求合并 (Request Coalescing)**：当多个客户端同时请求同一个未缓存的 URL 时，复用同一个回源请求，避免瞬间高并发流量击穿上游 (Thundering Herd)。
|
||
- 实现 **原子化缓存写入 (Atomic Write)**：使用“写临时文件 + 重命名”策略，确保缓存文件在写入过程中不会被读取到不完整的数据，彻底解决并发读写导致的文件损坏问题。
|
||
- **稳定性修复**:
|
||
- 修复了在请求合并逻辑中因 Promise 链处理不当导致的 `Unhandled Promise Rejection` 崩溃问题。
|
||
- 增加了文件流读取的错误监听，防止因文件系统异常导致的进程退出。
|
||
- 增加了全局异常捕获 (`uncaughtException`, `unhandledRejection`)，确保服务在极端异常下记录日志而不崩溃。
|
||
|
||
- **2026-01-20**:
|
||
- 重构代码，提取核心代理逻辑。
|
||
- 新增 `checkPort443` 函数，实现目标主机的 SSL/HTTPS 自动检测。
|
||
- 更新路由处理，支持无协议前缀的 URL 请求（如 `/www.baidu.com`）。
|
||
- 添加详细的代码注释。
|
||
- 优化协议检测逻辑：当目标主机 443 端口无法连接或超时时，自动降级并打印日志 `falling back to HTTP`，确保非 SSL 站点也能正常访问。
|
||
- 优化缓存逻辑：不再缓存小尺寸（< 15KB）的 GIF 图片（通常是 mShots 的 "Generating" 占位图），以便下次请求时能重新尝试获取真实截图。
|
||
- 新增备用接口机制：当 mShots 返回无效图片（如生成中 GIF）或失败时，自动降级尝试使用 `thum.io` 获取截图，确保高可用性。
|
||
- 性能优化：将关键路径上的同步文件 I/O (readFileSync/writeFileSync) 替换为异步操作 (fs.promises)，防止高并发下 Event Loop 阻塞导致服务无响应。
|
||
- 用户体验优化：当在浏览器中直接访问 API (Accept: text/html) 时，返回一个带有加载动画的 HTML 页面，解决等待过程中的白屏问题。
|
||
|