Asset Cache Server 项目记录

项目缘起

最近在处理网站时，遇到一个棘手的问题：大量依赖的外部 CSS/JS 资源（如字体图标库、统计脚本、公共 CDN 的库文件）经常因为防盗链策略或 CDN 节点不稳定导致加载失败。最糟糕的是，有些资源链接直接失效了，影响了线上业务的稳定性。

于是有了这个想法：为什么不把这些外部资源永久缓存到自己的服务器上？ 既能避免防盗链限制，又能确保资源长期可用。这就是 Asset Cache Server 诞生的初衷。

核心功能设计

这个项目是一个轻量的 Node.js 服务，实现了几个关键特性：

1. 智能 URL 映射与目录保留

我们没有简单地把所有文件堆在一个文件夹，而是按原始 URL 的目录层级保存。比如 https://cdn.example.com/lib/v1/jquery.min.js 会完整保存在 ./cache/lib/v1/jquery.min.js。这样做的好处是：

• 结构清晰，便于手动管理
• 避免不同站点的同名文件冲突
• 符合开发者直觉，找文件时一目了然

2. TXT/JSON 批量抓取

在根目录放置一个包含 URLs 列表的 TXT/JSON 文件，服务会自动读取并批量下载。每行一个 URL，支持注释（# 开头）。对于需要迁移大量资源的场景，这节省了大量手动操作。并且所需资源的内容可控，避免被污染。

3. 去重跳过机制

通过检查本地文件是否存在，自动跳过已缓存的资源。重复运行也不用担心产生冗余文件或覆盖已有内容。

4. 公共路径自动生成

最贴心的设计是返回格式化的引用路径。抓取完成后，控制台会输出：

公共路径: /cache/lib/v1/jquery.min.js
完整 URL: https://my-cdn.com/cache/lib/v1/jquery.min.js

直接复制就能在项目中使用，无需手动拼接路径。

技术实现要点

选择 Node.js 是因为：

• 异步 I/O 适合批量网络请求
• 生态丰富，有 axios、fs-extra 等趁手工具
• 部署简单，一条命令即可启动

核心流程很清晰：

1. 读取 TXT/JSON → 2. 校验 URL → 3. 生成本地路径 → 4. 检查是否已存在 → 5. 下载并保存 → 6. 返回引用地址

特别处理了路径生成逻辑，确保不同操作系统的路径分隔符兼容性。

与 CDN 防盗链的完美配合

这个项目最大的价值在于配合 CDN 防盗链使用。

我们可以：

• 将外部资源抓取到本地服务器
• 通过自己的 CDN（开启防盗链）分发
• 既保护了资源安全，又避免了外部链接的不确定性

相当于在自由开放的互联网资源和自己的业务之间建立了一道可控的缓冲层。

部署方式

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

思考与收获

这个项目，对静态资源管理有了更深的理解：

• 依赖外部资源 = 把稳定性交给别人。即使是知名 CDN，也可能因政策、网络问题影响你的业务。
• 简单的方案往往最有效。没有引入复杂的数据库或缓存策略，仅靠文件系统就解决了核心问题。
• 开发者体验很重要。返回可直接复制的路径这个小功能，让工具用起来格外顺手。

项目仓库：https://ckk.photo8.site/Photo8/Asset-cache