Asset-cache/README.md

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

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

Gitea：https://ckk.photo8.site/Photo8/Asset-cache

Github：https://github.com/cansnow123/Asset-cache

## 特性

- 保留原始目录层级：按源 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）
  - 返回示例：
    ```json
    {
      "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`
  - 示例：
    ```json
    {
      "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](https://ckk.photo8.site/Photo8/Asset-cache)