目录
背景
目前存在的问题：
- 打包发布流程
- 全量打包静态站点，打镜像，发布部署，即便只改一个标点符号大约已经一小时
- 打包占用 CI 服务器资源内存超过 12G，经常失败（且需要手动调整参数禁止并行任务）
- 纯静态站点，却部署在 k8s 服务上，还需要额外打 Docker 镜像（占用镜像仓库、CDN 、编排资源和时间）
- 设计及交互
- 没有设计规范，未遵守响应式优先
-
- 每个组件单独手写样式，冗余代码多且容易产生样式污染
- 组件排布不统一，比如 ScrollSpy 随页面滚动的导航菜单有的在左侧边栏有的在右侧边栏
- 相同功能组件样式过多（如链接、Typography 等）
- 有的页面有面包屑导航，有的没有
- 有的页面有最近更新时间，有的没有
- 文章反馈点赞和意见
-
- 机器人消息没有办法汇总和统计
- 系统配置
- 边栏手动配置
- 国际化配置非动态
- 文档内容及结构
- 包含自定义的 Markdown 语法
- 包含自定义的 Vue 组件，如：
-
- SDK 切换组件： 使用账号密码认证 | Authing 文档
- 相关文档： Express 集成 OIDC 单点登录指南 | Authing 文档
- Include 另一个 md 文档：什么是认证 | Authing 文档
- 特殊化的页面、文档，如：
-
- Step 步长引导： 接入微信扫码登录 | Authing 文档
- 含有资源的指南： Spring Security 集成 Authing OAuth 2.0 快速开始 | Authing 文档
- 以及 APN 等特殊页面
- 图片引用方式
- 内链引用方式
- 中英文文档内部的跨语言相互引用
- 以上这些均会影响文档导出成 PDF
系统架构
主要调整：
- 由纯静态站点改为动态站点
- 主要文档内容、图片及生成的 PDF 资源通过 CDN（OSS） 托管
- Git 提交判断文档变化，进行增量生成并覆盖上传 CDN
-
- 退而求其次还是依然全量，去优化打包生成的性能
- 动态配置选项：私有化部署方案将 CDN 资源路径改为本地资源路径去进行访问
入口
- 域名后负载均衡器（或者 K8s 配置）部分暂不关注
- 应用服务器应当为后期弹性伸缩做预留
- 应用服务器不用特别高的性能，主要为 IO 操作和内网请求
应用服务
为显著提升打包性能，避免使用 Webpack 传统应用框架。有两类方案。
带本地缓存的 ISR
典型且唯一具备该功能的框架 Next.js （基于 SWC 打包）。
参考： Data Fetching: Incremental Static Regeneration | Next.js
特点：
- 对于 CDN 资源的请求会稍有减少
- 本地资源可以在打包发布时构建，更新的话会稍微麻烦一点（有点类似于原有项目需要打包、打镜像、部署发布）
现代化嵌套式路由全栈框架
- 推荐 Remix，官网： Remix - Build Better Websites （基于 ESBuild 打包）
- Nuxt.js 3 RC （基于 Vite 打包）
- 站点与文档内容隔离（如果不用 MDX 或者动态组件的话）
特点：
- 更高的性能（打包及运行）
- 也可以实现类似于 Next.js 的本地缓存（如利用 LRU 等，需要额外开发）
文档增量更新
手动触发
- 在 App Server 提供一个接口
-
- 传入一个 URL Path 参数，指定更新某一篇文档 （暂不考虑数组）
- 请求接口时（同步，暂不考虑队列）
-
- HTTP + Secret Token 访问指定仓库下载文档
- 渲染生成对应的 MDX 组件或其他静态资源
- 将生成的文档和文档中的图片一并上传至 CDN（OSS）（暂不考虑图片资源删除）
CI/CD 流水线自动触发
- 提供一个脚本
-
- 检查发生的文档
- 遍历改动文件
-
- 渲染生成对应的 MDX 组件或其他静态资源
- 将生成的文档和文档中的图片一并上传至 CDN（OSS）（暂不考虑图片资源删除）
注意事项
如 Github Contributor 贡献名单、全文检索索引创建等情况也需要一并考虑。
或者预留一定扩展的能力
需求设计
建议做减法。参考多年前的文章： 需求分析-团队领袖计划
在添加产品功能需求之前，思考以下两个问题：
- 什么样的需求该忽略
- 什么样的需求该重视
原则
核心思想原则
安全 > 并发性能 > 用户体验(UE) > 用户界面(UI)
该原则适用于所有项目。
最简化可实行产品（MVP）原则
专注一个突破点。不盲目搞大。
冰冻三尺非一日之寒，一口吃不成胖子。所有庞大的系统，都是由一个个小的子系统逐步演化而来。
明确受众用户，明确核心功能，快速迭代。
其他参考
UI 设计
原则
- 响应式优先
- 设计要尊重组件，比如说 React Router Link 相关的 Class Name 是自动化添加的，不要有很奇怪的样式需要手动改动组件（体验怎么样先不说，这种无意义的工作量应当严令禁止，把 80% 的精力放在 20% 最有意义的事情上）
- 尊重已有的成熟设计规范，不做发明创造，简约即可，避免无效设计
- 规范、统一
-
- 避免使用图标字体（IconFont）、图标图片素材避免使用 png，统一使用 svg，统一使用 1024px viewbox，图标统一正方形（避免出现 15px 20px 这种不适合 ppi 缩放的尺寸， 推荐统一 2^n， 如 16px 32px 这样的单位）
- 避免使用固定值宽高、避免使用 px 绝对单位（参考 Tailwind 或 Ant Design 设计规范，避免特殊尺寸元素，如 button 可以定义 small、normal、large 尺寸，建议直接采用成熟的设计组件和元素规则）
- 文档内容（如指南、SDK 说明、集成等）尽量统一样式，不搞特殊化（即使按步骤操作的，也尽量上下平铺标题上面加第 N 步即可，方便脚本代码导出 PDF）
- 相同功能不要重复出现（如点赞按钮同时出现在顶部和底部）
- 相同功能不要出现在不同的位置（如 ScrollSpy 导航只出现在右侧边栏，不要某个特殊页面冒出在左边）
方法
Color Palette
Color Palettes for Designers and Artists - Color Hunt
主色调 4 色为佳，配合 5 个延展辅色调（可直接用 Daisy UI 提供的 20 余配色主题）。
Typography
参考上图右侧，创建一个画布，设置背景色、罗列所有元素及配色的排列组合。页面和组件均从这张完整速查表中抽取组合拼接而成。
传统设计框架
如我们官网风格基本来自于 Ant Design - 一套企业级 UI 设计语言和 React 组件库， 可以严格使用样式框架的风格和组件。
避免把精力花费在反复的样式和组件细节调整上。其他可参考的样式框架有：
- Bootstrap
- Material UI
- Element UI
- 等等
现代化设计框架
Tailwind CSS，官网：Tailwind CSS - Rapidly build modern websites without ever leaving your HTML.
配合 DaisyUI 来进行主题切换和一些常用组件设计规范定义，参考： daisyUI — Tailwind CSS Components ，包含 Typography 可以直接使用。
模块功能实现
项目拆分
- App Server 项目
- 文档拆分项目（独立管理）
-
- 中文文档项目
- 英文文档项目
应用服务
全站内容动态可配置，如站点语言、首页顶部导航菜单、各特殊页面上的内容数据、每个页面的边栏配置等
框架页面
需要特殊处理的页面模板包括不限于：
- 主页
- 开发集成
- APN
框架组件封装
包括不限于：
- 顶部菜单导航
- 底部统一链接及版权
- 语言切换组件
- 边栏导航
- ScrollSpy 页内 TOC 导航
- 最后更新时间
- Github 贡献者
- 点赞、反馈组件
- 搜索组件*
静态化资源生成
Markdown、MDX 渲染处理
参考资料：
-
- Next.js 核心开发者，谢扬多次推荐过
- Next.js 纯静态本地内容，通过 ContentLayer Contentlayer makes content easy for developers 缓存内容
- MDX 解析
-
- Remix + CDN（Cloudflare KV）远程内容数据
- 提供了 API 接口动态更新内容缓存 willin.wang/statistics.server.ts at main · willin/willin.wang
- MDX 解析
PDF Generate
注意点：
- 避免使用无头浏览器方式生成 pdf
- 避免使用 Canvas 渲染图片再生成 pdf
Github 贡献者名单获取
参考之前的知识库： 开源贡献
第三方服务集成
全文检索
全站范围全文检索，推荐使用成熟服务进行集成。
动态网站也可以通过接口搜索，但由于资源都在 CDN 中，效率较低且会产生流量
502
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
