Skip to content

feat(static): fetch index.html from cdn for beta#372

Merged
PIKACHUIM merged 8 commits intoOpenListTeam:mainfrom
xrgzs:feat/static
Jul 22, 2025
Merged

feat(static): fetch index.html from cdn for beta#372
PIKACHUIM merged 8 commits intoOpenListTeam:mainfrom
xrgzs:feat/static

Conversation

@xrgzs
Copy link
Copy Markdown
Member

@xrgzs xrgzs commented Jun 25, 2025

目前 OpenList 使用 CDN 部署存在以下问题和优化:

1. 本地资源与 CDN 资源未隔离

config.json 中配置了 CDN 域名后,前端静态资源仍可通过本地路径访问。由于 OpenList 引入 SWF 播放器后前端应用体积翻倍,存在一些 WASM 的大文件,这可能被恶意刷取流量,消耗源站带宽资源。

本 PR b5d685d 已修复该问题,在配置了 CDN 的条件下禁止添加本地资源的路由,实现了 CDN 与本地资源的访问隔离。

2. index.html 文件版本不兼容

目前前端 Vite 打包生成的 JS 文件名采用哈希命名,修改过的部分构建后文件名会发生变化,导致不同版本的 index.html 彼此不兼容。

OpenList 的 index.html 需要加载到本地内存中,因为后端还会插入一些代码、修改变量等等,仅使用 Pages 修改 API 地址部署会导致功能缺失、路由失效。

  • 对于 Release 版本,静态资源通过 NPM CDN 加载,版本固定,可直接使用内置的 embed.FS 中的 index.html,一般不会出现问题;
    • 已知一些 NPM CDN(如 npmmirror)禁止访问 HTML 文件,但 Release 版本仅使用其它产物,无需依赖 CDN 的 index.html,因此不受太大的影响;
    • 为了降低程序二进制大小,可以仅打包 Release 版本的 index.html 文件,并配置 CDN。
  • 对于 Beta 版本,更新频繁,不适合上传至 NPM。若继续使用程序内置的 index.html,配置 CDN 后易出现资源路径失效的问题。

为解决 Beta 版本的 CDN 资源适配问题,本 PR 实现了从 CDN 获取 index.html 的功能,可以参考以下步骤实现:

  1. 前端构建产物部署至 CDN 平台的 Pages(如 Cloudflare Pages、EdgeOne Pages 等);
    • 可能需要配置 CORS 标头;
    • 可以在部署前端时使用“复制+覆盖”的方式,保留一些旧版本的资源文件,这样即使内存中的 index.html 不是最新的,也不影响使用。
  2. config.json 中配置 CDN;
  3. 程序启动时自动从 CDN 拉取最新的 index.html
  4. 如需更新前端到最新版本,只需重启程序。

@xrgzs xrgzs requested review from PIKACHUIM and jyxjjj June 25, 2025 11:16
@jyxjjj
Copy link
Copy Markdown
Member

jyxjjj commented Jun 25, 2025

同意第一点,第二点经商议未得出结论, 要不让大佬看看 @KirCute

@ljcbaby
Copy link
Copy Markdown
Contributor

ljcbaby commented Jun 25, 2025

Beta 版本不应该用于生产吧,其次 需要考虑网络受限的环境

@xrgzs xrgzs removed request for PIKACHUIM and jyxjjj June 28, 2025 16:03
@xrgzs
Copy link
Copy Markdown
Member Author

xrgzs commented Jun 28, 2025

Beta 版本不应该用于生产

正常情况是这样,但还是有特殊情况,需要用到Beta 版本、自行构建的 Beta 版本中的功能,因此有需求给 Beta 版本上 CDN。


解释一下:

  • 本 PR 中第 2 点改动仅针对 Beta 版本等非正式版本做优化,对于正式版本,表现和之前的一样,会使用程序内置的 index.html,不存在 BREAKING CHANGE。
  • Beta 版本无 NPM CDN,也不要求 OpenListTeam 给 Beta 版本部署到 CDN
  • 通过这个 PR,可以让 Beta 版本用正式版的前端资源,只需给 $version 改成对应的版本即可,无需让 OpenListTeam 在 NPM 上传 Beta 版本
  • 存在特殊情况需要用到自行构建的 OpenList-Frontend,且已经将自行构建的前端静态文件部署到了自己的服务器,不会占用 OpenListTeam 的 CDN 资源

为什么不使用程序内置的 index.html

因为 index.html 中写死了 Vite 打包的文件名:

...
var preloads = [
  {
    parentTagName: "head",
    tagName: "link",
    attrs: { href: "/static/manifest.json", rel: "manifest" },
  },
  {
    parentTagName: "head",
    tagName: "script",
    attrs: {
      type: "module",
      crossorigin: "",
      src: "/assets/index-fec7825c.js",
    },
  },
  {
    parentTagName: "head",
    tagName: "link",
    attrs: { rel: "stylesheet", href: "/assets/index-c0564af7.css" },
  },
];
...

让这个文件名后面的哈希消失,也可以解决问题,但也会出现 index.html 和 CDN 中版本不一致的问题,这个哈希我认为有存在的意义。因此需要让 Beta 或者自行构建版本的 OpenList 后端支持从 CDN (自行部署)获取 index.html


需要考虑网络受限的环境

如果部署 OpenList 的机器网络受限,可以选择不用 CDN ——不要定义 cdn 字段,程序会使用内置的静态资源。

如果配置的 CDN 是网络受限的,那我认为也没折腾的必要。而且作为 Beta 版本,正如您说的,不应该在生产中使用。


如果社区对于此 PR 的第 2 点持否定态度,请务必让我知道,我会将本 PR 的第 1 点单独提取出来,谢谢!

@xrgzs
Copy link
Copy Markdown
Member Author

xrgzs commented Jul 22, 2025

经过思考发现其实不存在请求 index.html 失败之后的处理问题。因为如果请求失败,首先会用 Resty 重试最多 3 次,如果不行会直接 Fatal(log & os.Exit(1)),具体情况见下图。如果用了 docker 或者 systemd 之类的话,支持配置自动重启,那么就可以一直重启到网络恢复,请求成功。这个请求只会执行一次,所以不用担心后面会出现请求失败的问题。

另外对于第 1 点的处理,改成了重定向到 CDN,避免前端可能存在的写死路径的 BUG。

@xrgzs
Copy link
Copy Markdown
Member Author

xrgzs commented Jul 22, 2025

以下是 Mermaid 便于理解:

flowchart TD
    A[程序初始化] --> B{是否配置CDN?}
    
    B -->|是| D{版本类型?}
    B -->|否| E{是否配置本地dist?}


    E -->|否| F[使用程序内置的index.html]
    E -->|是| G[使用本地dist中的index.html]
    

    D -->|Beta版本| H[从CDN获取index.html]
    D -->|Release版本| F
    
    H --> I{CDN获取成功?}
    I -->|成功| J[使用CDN获取的index.html]
    I -->|失败| K[Resty重试3次]
    K -->|成功| J
    K -->|仍失败| L[程序退出,等待重启]
    
    F --> M[替换CDN、站点信息等变量]
    G --> M
    J --> M
    M --> N[返回页面]
Loading

@PIKACHUIM PIKACHUIM merged commit 7d0de17 into OpenListTeam:main Jul 22, 2025
12 checks passed
@xrgzs xrgzs deleted the feat/static branch October 19, 2025 15:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants