Photo8/Asset-cache
1
0
Fork 0
Code Pull Requests Actions Packages Projects Releases Activity
Files
471ed156af946ae4ecd532f1fa5fda2f139d1a56
Asset-cache/README.md
Snowz 471ed156af feat(ui): 优化缓存区布局并修复分段筛选问题 
- 将工具栏分为上下两行布局，优化窄屏下的显示效果
- 增加元素间距和可点击区域，提升用户体验
- 修复切换CSS/JS/全部时未重置分页的问题
- 禁用首页和HTML文件的缓存，避免浏览器缓存旧版本
- 更新README文档说明布局优化细节
2025-11-28 23:00:18 +08:00

8.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）
  • 目的：为内部用户提供更直观的访问入口与使用指引

缓存区布局优化说明

  • 字体与文本：统一行高与字间距，url 文本支持多行折行显示并保留省略控制，确保在窄屏下仍具可读性
  • 按钮与控件：增大最小高度与内边距，提升可点击区域；工具栏分为上下两行以避免拥挤
  • 布局优化：工具栏采用两行分组（类型/时间/刷新、搜索/排序/方向/页容量），列表卡片增加间距与对比度
  • 视觉一致性：沿用暗色科技风、玻璃拟态渐变与细边框，悬停有轻微抬升与阴影反馈
  • 响应式适配：≥1100px 两列卡片、<760px 单列；工具栏在小屏纵向排列，输入与选择控件宽度自适应
  • 高级功能：分页加载（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/页）、按名称/类型/更新时间过滤、按名称/大小/时间排序、轻量虚拟滚动与懒加载、元数据解析（库名/版本/扩展名/类别）
  • 修复分段筛选：切换 CSS/JS/全部 时重置分页并重新加载
  • 静态缓存优化：/ 与 HTML 响应禁用缓存；为首页 CSS/JS 增加版本参数以避免浏览器缓存旧样式与脚本
  • 页面视觉细节：为 header 与 main 增加间距（≥30px），背景设置 background-attachment: fixed 并覆盖视窗（居中、等比、无重复）
View Git Blame Copy Permalink