Asset-cache/README.md

# 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`）

## 快速开始

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

## 接口说明

- `POST /api/upload-txt`
  - 上传 TXT（字段名 `file`），每行一个 URL；支持 `#` 注释与空行
  - 响应项示例：
    - `{
        "url": "https://cdn.jsdmirror.com/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
        "saved": "/css/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
        "accessUrl": "https://<你的域名>/css/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
        "filename": "bootstrap.min.css",
        "type": "css",
        "size": 232914,
        "skipped": false
      }`

- `POST /api/cache`
  - 提交单条 `url` 或数组 `urls`
  - 单条示例：`{"url":"https://.../bootstrap.min.css"}`
  - 多条示例：`{"urls":["https://.../bootstrap.min.css","https://.../bootstrap.bundle.min.js"]}`

- `GET /api/seed`
  - 从项目内置 `seed.txt` 读取并批量抓取，无需重启

## 静态访问

- 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`）
- 如需更强控制可扩展签名 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`