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 起）

规则补充（无扩展名与根路径资源）

• 无扩展名的资源将根据类型自动补全扩展名：text/css → .css、application/text-javascript/text/javascript → .js
• 根路径资源（如 https://cdn.tailwindcss.com）为避免跨域冲突，将以主机名作为首层目录：
  • 本地保存：cache/js/cdn.tailwindcss.com/index.js
  • 对外访问：/js/cdn.tailwindcss.com/index.js

字体与依赖资源处理（CSS 自动抓取）

• 当抓取 CSS 文件时，会自动解析其中的 url(...) 引用，并尝试下载相对路径的依赖（如字体、图片等），统一保存到 cache/css/... 对应目录下，保持与源路径相同的层级结构。
• 这样，形如 @font-face { src: url(fonts/element-icons.woff) } 的引用将会在本地落盘为：/css/.../fonts/element-icons.woff，无需跨域请求第三方源。
• 失败的依赖抓取会被静默跳过，不影响主 CSS 的可用性。
• 针对使用 ../webfonts/... 的场景（如 Font Awesome），已修正对上级目录的处理，确保依赖文件最终位于与 css/ 同级的 webfonts/ 目录；旧版本误存于 css/webfonts/ 的文件会在后续抓取时自动迁移到正确位置。

去重策略

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

安全与白名单建议

• 推荐在 CDN/WAF 层配置防盗链白名单（如 *.aaa.com、www.bbb.com）
• CORS 建议在 CDN/WAF/网关统一配置按域名的跨域放行策略，服务端默认不设置跨域响应头。
• 管理接口仅保留 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>

环境变量示例（.env.example）

• 复制示例文件并按需修改：
  • Windows PowerShell：Copy-Item .env.example .env
  • Linux/Mac：cp .env.example .env
• 可用变量：
  • PORT：服务器端口（默认 3000）
  • SEED_SOURCE：file 或 url（默认 file）
  • SEED_URL：当 SEED_SOURCE=url 时的远程TXT地址（Gitea Raw直链或API）
  • SEED_AUTH_HEADER：自定义认证头（如 Bearer <token>）
  • SEED_TOKEN：令牌（将自动以 Authorization: token <TOKEN> 发送）
• 生效方式：修改 .env 后重启服务
• 相关代码位置：server.js:19（环境变量读取）、server.js:419（远程/本地加载逻辑）

前端交互更新（Seed抓取）

• 禁止跳转到 /api/seed，前端通过 fetch 异步触发 Seed 抓取
• 成功无新增：黄色提示 已执行Seed抓取，无新增数据
• 成功有新增：绿色提示 已执行Seed抓取，发现 ${新增数量} 条新数据
• 错误：红色提示 请求失败，请稍后重试
• Toast：右下角非模态，自动隐藏 3 秒；颜色由代码控制
• 加载：请求超过 500ms 时显示按钮内微型旋转指示，结束后自动隐藏
• 防抖：点击 300ms 防抖，避免重复请求与误触
• 代码位置：
  • 触发按钮：public/index.html:46（id="seedTrigger"）
  • 异步调用与提示：public/app.js:275（runSeed）、public/app.js:97（toastBR）
  • 加载指示逻辑：public/app.js:258（showSeedSpinner，500ms 延迟显示）
  • 计算新增数量：public/app.js:267（calcNewCount）
  • 样式：public/styles.css:614（.toast-br）、public/styles.css:636（.btn-spinner）、public/styles.css:648（.btn.is-loading）

常见问题（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 并覆盖视窗（居中、等比、无重复）
• 修复：CSS 依赖路径对 .. 上级目录的正确解析与落盘（兼容 Font Awesome 的 ../webfonts）；增强 CDN 回退匹配支持 @scope 包名（jsDelivr / unpkg）
• 新增：开源许可文件 LICENSE（GPL-3.0），并在 README 增加许可说明与仓库地址
• 新增：seed.txt 支持远程来源（Gitea 原始文件），通过环境变量配置

开源许可与仓库地址

• 许可证：GNU GPL v3（详见仓库根目录 LICENSE）
• 仓库地址：https://ckk.photo8.site/Photo8/Asset-cache
• 使用须知：
  • 复制、修改与分发本项目需在同等 GPLv3 条款下进行
  • 分发时需保留版权声明与本许可证文本，并开放源代码
  • 不提供任何形式的担保，详见 LICENSE 的免责声明章节

Seed 配置（本地与远程）

• 默认行为：GET /api/seed 读取仓库根目录的本地 seed.txt
• 远程来源：将环境变量设置为以下值以从 Gitea 原始文件拉取
  • SEED_SOURCE=url
  • SEED_URL=<你的Gitea原始TXT地址>（例如：https://gitea.example.com/api/v1/repos/<owner>/<repo>/raw/seed.txt?ref=main 或 Raw 文件直链）
  • 可选认证：
    • SEED_AUTH_HEADER="Bearer <token>"（自定义 Authorization 头）
    • 或 SEED_TOKEN="<token>"（自动使用 Authorization: token <token> 头）
• 回退机制：远程拉取失败时，若本地 seed.txt 存在则自动使用本地文件
• 相关代码：
  • 远程/本地加载逻辑：server.js:419（loadSeedTxt）
  • 执行批量抓取：server.js:440（runSeed）

Copyright © 2025 Asset Cache Server Developer By SnowZ