Files

Snowz 15b3926b95 feat: 新增前端首页与缓存资源管理功能

- 添加公共静态目录及首页HTML/CSS/JS文件
- 实现缓存资源列表API，支持分页、过滤与排序
- 移除multer依赖，简化上传功能
- 更新README文档说明新增功能与接口

2025-11-28 22:20:51 +08:00

7.5 KiB

Raw Blame History

Asset Cache Server（CSS/JS 永久缓存服务）

一个用于将外部 CSS/JS 资源永久缓存到本地并通过自有域名提供静态访问的 Node 服务。支持上传 TXT 批量抓取、按原 URL 目录层级保存、去重跳过、返回可直接引用的公共路径与完整 URL，适合与 CDN 防盗链配合使用。

特性

保留原始目录层级：按源 URL 路径保存到 cache/css 或 cache/js 下
去重缓存：同一路径已存在则跳过抓取并返回 skipped: true
统一静态访问：通过 /css/... 与 /js/... 直接访问，设置长缓存头
批量抓取：支持上传 TXT（每行一个 URL）或一次提交多条 URL
结果即用：API 返回 saved（公共路径）与 accessUrl（完整 URL）
环境配置：支持 .env 设置 PORT，适配反向代理与不同端口
路径安全：剔除 .. 等越权片段，写入校验不越出缓存根

原理与代码位置

目录与类型解析：server.js:42（resolveTargetPath）
抓取与去重：server.js:133（fetchAndStore）
TXT 解析与批量：server.js:164、server.js:176
静态目录映射：server.js:192–server.js:193
公共路径与完整 URL：server.js:107（getPublicPath）、server.js:121（buildAccessUrl）
前端首页注册：server.js:42（registerPublicHomepage）

快速开始

安装依赖：npm install
设置端口（任选其一）：
- 在 .env 中写入：PORT=11488
- Windows 启动前：$env:PORT=11488; npm start
- Linux/systemd/pm2：在进程配置里设置环境变量 PORT
启动服务：npm start
健康检查：GET /health → {"ok":true}

前端首页

访问路径：/
内容包含：项目简介、健康检查入口、触发 Seed 抓取入口、免责声明与推荐公共 CDN 列表、已缓存资源的可视化列表（仅展示可直接复制的完整 URL）
目的：为内部用户提供更直观的访问入口与使用指引
高级功能：分页加载（20–50/页）、按名称/类型/更新时间过滤、按名称/大小/时间排序、懒加载与轻量虚拟滚动、统一暗色科技风视觉与动画

使用声明（免责声明）

本网站收录的开源库均仅支持内部使用，不对外提供公共 CDN 服务
如需稳定的外部公共库服务，请使用以下成熟 CDN：
- BootCDN 加速服务：https://www.bootcdn.cn/
- CDNJS 前端公共库：https://cdnjs.com/
- jsDelivr：https://www.jsdelivr.com/
- 七牛免费 CDN 前端公开库：https://www.staticfile.org/
- 又拍云常用 JavaScript 库 CDN 服务：http://jscdn.upai.com/
- Google Hosted Libraries：https://developers.google.com/speed/libraries
- Microsoft Ajax CDN：https://ajax.aspnetcdn.com/

接口说明

GET /api/seed
- 从项目内置 seed.txt 读取并批量抓取，无需重启
- 管理抓取仅通过修改服务器上的 seed.txt 实现，服务端不接受外部提交 URL

GET /api/list-cache

列出当前已缓存的 CSS/JS 文件，按最近修改时间倒序
查询参数：
- type: css | js（可选）
- q: 关键字（可选，匹配路径片段）
- limit: 最大返回条数（默认 200，最多 2000）

返回示例：

{
  "count": 200,
  "total": 1234,
  "hasMore": true,
  "items": [
    { "type": "css", "path": "/css/npm/.../file.css", "url": "http://host/css/npm/.../file.css", "size": 12345, "mtime": 1730000000000 }
  ]
}

接口更新（list-cache 扩展）

GET /api/list-cache

支持分页、排序与更丰富的过滤参数：
- type: css | js（可选）
- q: 关键字（匹配路径片段与URL，模糊搜索）
- name: 库名称（匹配解析出的名称，模糊搜索）
- updatedFrom / updatedTo: 毫秒时间戳范围过滤（可选）
- sortBy: mtime | name | size（默认 mtime）
- order: asc | desc（默认 desc）
- page: 页码（默认 1）
- pageSize: 每页条数（默认 30，范围 20–50）
返回字段增加：page、pageSize、name、version、ext、category

示例：

{
  "count": 30,
  "total": 1234,
  "page": 1,
  "pageSize": 30,
  "hasMore": true,
  "items": [
    {
      "type": "css",
      "path": "/css/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
      "url": "http://host/css/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
      "size": 12345,
      "mtime": 1730000000000,
      "name": "bootstrap",
      "version": "5.3.0",
      "ext": ".css",
      "category": "bootstrap"
    }
  ]
}

静态访问

CSS：/css/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css
JS：/js/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js

保存规则与目录结构

路径规则：按原 URL 路径层级保存到 cache/css 或 cache/js
- 原地址：https://cdn.jsdmirror.com/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css
- 本地保存：cache/css/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css
- 对外访问：/css/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css
类型判定：优先扩展名（.css/.js），其次 Content-Type
安全加固：移除 .. 等越权片段，写入前校验不越界（server.js:65 起）

去重策略

目标路径存在则跳过抓取，响应中返回 skipped: true
强制刷新：删除对应缓存文件后再次触发抓取

安全与白名单建议

推荐在 CDN/WAF 层配置防盗链白名单（如 *.aaa.com、www.bbb.com）
管理接口仅保留 GET /api/seed，不提供外部 POST；如需更强控制可扩展签名 URL 校验（服务端或边缘验证令牌）

部署建议

Windows（开发/测试）：npm install && $env:PORT=11488; npm start
Debian 12 / Node 22.19.0（生产）：
- 创建 .env 设置端口：PORT=<你的端口>
- npm install && npm start
- 建议使用 systemd/pm2 守护进程，并在 Nginx 反向代理到 127.0.0.1:<PORT>

常见问题（FAQ）

修改 seed.txt 是否需要重启？不需要，GET /api/seed 会重新读取。
同名文件内容更新如何刷新？删除旧缓存文件后再触发，或用带版本号的 URL。
端口为何不是 3000？端口读取自环境变量 PORT，可通过 .env 或进程管理器设置。

变更记录（摘要）

增强目录层级映射与路径安全加固（越权剔除、根校验）
内置 seed.txt 与 GET /api/seed（无需重启）
去重逻辑（已存在则跳过，返回 skipped: true）
.env 支持（PORT），适配多端口部署
接口响应统一返回公共路径 saved 与完整 URL accessUrl
依赖升级：express@^5.1.0、multer@^2.0.2、axios@^1.13.2、morgan@^1.10.1
移除外部提交接口：POST /api/upload-txt 与 POST /api/cache，仅支持通过 seed.txt 批量抓取
新增前端首页与公共静态目录（public/），主页包含免责声明及推荐公共 CDN 列表
新增 GET /api/list-cache 接口，支持过滤、限制与前端展示一键复制
升级首页缓存区域视觉与交互：统一暗色科技风、移除相对路径展示、仅保留完整 URL 复制与打开、优化响应式布局与过渡动画
增强缓存管理：分页加载（20–50/页）、按名称/类型/更新时间过滤、按名称/大小/时间排序、轻量虚拟滚动与懒加载、元数据解析（库名/版本/扩展名/类别）

7.5 KiB Raw Blame History Unescape Escape