Wiki AI Architecture

First Post:

Last Update:

Wiki AI 架构说明

目标

主站是真正给用户访问的：

https://mornikar.github.io/Mornikar/

Wiki AI 不能直接从浏览器请求讯飞 MaaS，所以前端会把对话请求转给 Cloudflare Pages 代理：

https://mornikar-ai-wiki.pages.dev/api/v2/chat/completions

这样做是为了：

  1. 解决浏览器跨域限制。
  2. 让国内用户尽量不依赖 VPN 也能使用 Wiki AI。

当前线上链路

mornikar.github.io/Mornikar
-> wiki-chat.js
-> mornikar-ai-wiki.pages.dev/api/v2/chat/completions
-> Cloudflare Pages Function
-> 讯飞 MaaS OpenAI 兼容接口

关键文件：

两条发布链路

1. GitHub Pages

用途：
发布 https://mornikar.github.io/Mornikar/

方式：
source 分支触发 GitHub Actions，构建 public/，再部署到 gh-pages 分支的 Mornikar/ 目录。

2. Cloudflare Pages

用途：
发布 https://mornikar-ai-wiki.pages.dev/api/...

方式：
Cloudflare Pages 直接连接 GitHub 仓库的 source 分支，自动读取仓库中的 functions/。

结论：

  • 主站页面走 GitHub Pages。
  • Wiki AI 代理接口走 Cloudflare Pages。

以后改 GitHub 代码，Cloudflare Function 要不要跟着改

不一定。

不需要改 Function 的情况

  • 只改页面样式、布局、动效。
  • 只改文章、Wiki 内容、静态资源。
  • 只改前端文案、Prompt、TTS 展示层。
  • 只改 GitHub Pages 页面构建，但代理请求格式没变。

需要改 Function 的情况

  • 改代理域名。
  • 改上游 MaaS 地址。
  • 改鉴权方式、headers、超时、限流、日志。
  • 改前端请求协议或接口路径。
  • 想把前端默认 API Key 挪到 Cloudflare 环境变量里。

前端和 Function 需要一起检查的情况

  • wiki-chat.js 里的默认代理地址变了。
  • /api/v2/chat/completions 的请求格式变了。
  • Cloudflare 上新建了正式自定义二级域名，需要替换默认入口。

自动同步规则

当前自动同步依赖同一个 source 分支：

  1. 推送到 GitHub source 分支。
  2. GitHub Actions 自动发布主站到 gh-pages。
  3. Cloudflare Pages 也会自动从 source 分支重新构建 Function。

这意味着：

  • 改 themes/**，主站会自动更新。
  • 改 functions/**，Cloudflare Pages 会自动更新。
  • 只要 Cloudflare Pages 项目一直绑定这个仓库的 source 分支，就不需要手工再传一遍 Function。

这次专门补的自动化保障

为了让后续 AI 更稳地接手，这次额外保证了：

  • functions/** 变动也会被 GitHub Actions 发布链路识别。
  • source/docs/** 变动也会触发文档同步发布。

域名使用原则

稳定域名

长期配置使用：

https://mornikar-ai-wiki.pages.dev

预览域名

像：

https://5bf0c356.mornikar-ai-wiki.pages.dev

这种是部署预览地址，不应该写死到长期配置里。

自定义二级域名

如果以后在 Cloudflare 里绑定了更适合国内访问的正式二级域名，比如：

https://wiki-ai.xxx.com

那就应该把 wiki-chat.js 里的默认代理地址同步替换成这个新域名。

后续 AI 接手时的排查顺序

  1. 先确认问题是不是“主站能打开，但 Wiki AI 不能对话”。
  2. 检查线上主站 wiki-chat.js 的默认代理地址。
  3. 检查该代理地址的 /api/v2/chat/completions 是否能返回 405 或 200。
  4. 如果前端和代理域名不一致，先同步前端配置。
  5. 如果代理请求打不到上游，再查 Cloudflare Pages Function。

一句话原则

GitHub Pages 负责发站点页面，Cloudflare Pages Function 负责接住 Wiki AI 对话请求。
只要代理域名、接口协议、上游转发逻辑变了，就应该同时检查前端和 Function。