Seeridia's Home

把散落的依赖服务状态收进一个工作台中

Mon, 14 Sep 2026 15:30:00 GMT

犀牛鸟实战任务第二任务

犀牛鸟的第二个任务：

用 Agent 落地你的产品。使用 TDesign 组件完成一个功能完整的小应用，并使用任务一的色阶生成能力提供主题色切换；使用 Miora 产出 UI 稿与视觉资产，再使用 CodeBuddy 将它开发成真正能够运行、访问和演示的产品。

上一篇文章里，我从一个主色出发，做出了 OKRamp；这一次，我想知道它离开色板工作台以后，能不能真的进入一个产品里。

其实这边另外可以说的是，在上一个任务的 OKRamp 中，其实其 playground 站点本身也是使用 TDesign 组件开发的，符合 TDesign 设计规范的应用。

我选择的是——多服务融合的状态监控和通知系统

项目的在线体验与源码都在这里：

https://statushub.seeridia.top

由于为了接入国外服务的状态页，该系统部署在国外服务器上，国内访问可能速度较慢或者同时需要特殊的网络环境。

https://github.com/Seeridia/StatusHub

背景

现代产品很少只依赖自己的服务器。云平台、代码托管、支付、邮件、AI API 与 CDN，任何一环出问题，最后都可能变成用户眼中的“你的产品坏了”。

这些服务通常都有自己的状态页。问题是，它们散落在不同网站上，也使用不同的结构。真的出现异常时，我需要先猜是哪一家，再逐个打开页面，判断事故是否与自己使用的服务有关，最后把消息转给团队。

如果依赖只有两三家，这还算不上问题；当依赖逐渐变多，它就会变成一种很机械的值班工作。

所以我最初想做的并不是另一个状态页，而是一个状态页的工作台：

把团队依赖的外部服务放在同一处。
把不同来源的事故整理成一致的状态与时间线。
只有变化符合规则时，才把消息送到需要知道的人那里。

向你介绍 StatusHub

StatusHub 是一个可以自托管的服务状态监控与通知平台。用户输入公开状态页地址，系统识别页面使用的状态引擎，持续采集事故与组件状态，再按照团队配置的规则发送通知。

产品首页优先回答三个问题：

哪些外部依赖正在出问题？
这件事是否可能影响我的团队？
对应的通知有没有成功送达？

围绕这三个问题，工作台形成了总览、服务、事件、通知规则、通知渠道、投递记录与设置七个主要页面。

快速添加

我不希望用户在添加服务之前先理解“Statuspage 适配器”或“incident.io Widget API”是什么。

添加数据源时，用户先在 TDesign SelectInput 中输入服务名称。选择已经收录的服务，例如 OpenAI，页面会自动补全它的官方状态页地址；目录之外的服务仍然可以输入名称并手动填写 URL。

提交之前，后端会先探测这个地址，返回识别到的适配器与资源能力。

目前 StatusHub 支持 Atlassian Statuspage、incident.io、Instatus、Better Stack、Status.io、Cachet、Gatus、cState、受控 HTML recipe 与 AWS public Health 等来源。这里的重点不是为每一家厂商写一份爬虫，而是识别它们背后共用的状态页引擎。

统一事故模型

不同状态页会使用不同字段描述同一件事。StatusHub 在采集后把它们归一为统一的服务、事故、影响等级、阶段与更新时间，再保留上游原文组成时间线。

一条变化进入系统以后，会依次经过这些环节：

flowchart LR
  A[公开状态页] --> B[探测与适配器]
  B --> C[统一事故模型]
  C --> D[PostgreSQL 与 Outbox]
  D --> E[NATS JetStream]
  E --> F[通知规则匹配]
  F --> G[Slack / 飞书 / Webhook / ...]
  G --> H[投递记录与重试]

这条链路让产品完成了一个真正的闭环：接入来源 → 发现变化 → 判断是否相关 → 发出通知 → 确认投递结果。

设计 · Miora

状态监控产品天然会出现大量表格、状态标签和数字。如果视觉稿只追求一张漂亮的大屏，真正放入长标题、失败原因和配置表单以后，很容易失去秩序。

所以在 Miora 阶段，我先确定的不是某一张页面，而是一组可以贯穿产品的视觉原则：清晰、克制、适合长时间阅读；状态依靠颜色、图标和文字共同表达；品牌色负责操作与识别，不与红、橙、绿这些业务状态色争夺含义。

同时，我也希望能够快速使用 TDesign 组件完成页面布局，符合 TDesign 的设计规范和交互模式。这样在进入 CodeBuddy 阶段时，Agent 可以直接把视觉稿映射为组件，而不是需要重新设计。

Miora 产出的视觉内容最终落成三类资产：

工作台融合稿：左侧导航、顶部工具栏与内容工作区组成基础框架，总览用指标卡、服务列表和最近事件建立信息层级。
登录页视觉：中央保留产品说明与登录入口，两侧使用立体装饰构成背景，品牌墙展示产品能够连接的服务生态。
品牌资产：StatusHub 的脉冲折线 Logo 与薄荷绿色彩方向。折线同时像监控波形与状态变化，Hub 则表达把分散来源汇到一起。

比如，我在 Miora 中设计了他的 LOGO：

比如在登录页中，我让 Miora 模仿 TDesign Starter 的登录页背景，也同样生成了一个立体风格的背景作为登录页。同时 Miora 能很方便的通过标记等等方式去提示 Agent 在对应地方进行修改，大大提高了沟通效率

以及，直接在 Miora 中生成了 StatusHub 的 UI 设计稿：

这份设计稿在下面的 CodeBuddy 阶段被 Agent 直接映射为 TDesign 组件，保留了布局、信息层级、状态标签和交互模式，为后续的开发节省了大量时间。

研发 · CodeBuddy

我没有把需求一次性写成“帮我做一个监控后台”。这样的提示或许能很快得到一张可以点击的页面，却很难得到一个能够解释数据、可靠发送通知并持续运行的产品。

在 CodeBuddy 中，这个项目经历了三个很清楚的阶段：先调研，再 Plan，最后开发。它们不是三个互不相关的对话，而是一条逐渐收窄问题的路径。调研决定应该解决什么，Plan 决定先验证哪一部分，开发则不断用真实结果修正规划。

01 · 调研：先寻找问题的结构

最开始，我只知道自己想把 GitHub、Cloudflare、OpenAI、Anthropic 与 AWS 的状态放在一起。CodeBuddy 没有立刻创建项目，而是先调查了两个方向：有没有相近的开源方案，以及这些厂商究竟怎样提供状态数据。

调研得到的第一个关键发现是：GitHub、Cloudflare、OpenAI 与 Anthropic 虽然属于不同公司，却都使用 Atlassian Statuspage。它们的 summary.json、组件和事故接口具有相似结构。与其为四家厂商分别写四份代码，不如先做一个通用的 Statuspage Provider。

AWS 则是一个很有价值的反例。它使用自己的公开数据格式，甚至还需要处理 UTF-16 JSON，不能硬塞进同一个解析器。于是系统从一开始就采用“通用 Provider + 特殊来源独立适配”的结构。

CodeBuddy 还对照了 statusphere 与 ai-status-hub 等项目。前者证明“采集器、任务调度、API 与通知”可以拆成清楚的职责；后者提醒我必须处理误报：来源抓取失败只能表示数据未知，不能被解释成厂商故障。

所以调研并没有直接产出页面，而是先回答了三个会影响整个产品的问题：

哪些厂商可以共享一套采集逻辑？
哪些来源必须保留自己的适配器？
怎样区分厂商异常与 StatusHub 自己没有采集到数据？

这一阶段最大的价值，是把“聚合几个网页”的想法变成了一个可以扩展的数据模型。

02 · Plan：把结论变成可以验收的路径

调研完成以后，CodeBuddy 没有把所有功能塞进一次开发，而是先生成一份完整的 PLAN.md。里面记录架构选择、风险、数据模型、里程碑与每一阶段的验收条件，再交给我审阅。

初始 Plan 把工作拆成 M0 到 M5：先搭建骨架，再接通四家共用 Statuspage 的厂商；随后完成变化检测和通知；再补 AWS Provider；最后才进入订阅、界面与加固。这个顺序有一个很明确的目的：先证明最短的数据链路可以跑通，再增加来源、界面和工程复杂度。

Plan 也提前写出了成本最大的分叉。通用 Provider 能覆盖四个首批来源，AWS 必须单独实现；通知库可以先帮助验证链路，但敏感 Token 不能进入配置仓库；事故只有在状态发生变化时才触发，并且需要去重和静默窗口。

不过，Plan 并不是最终架构的承诺。截图记录的是项目早期版本，当时为了快速验证，方案还是 Go 单体、SQLite 与第三方通知库。随着产品从原型走向可部署版本，SQLite 被 PostgreSQL 取代，进程内链路演进为 Outbox 与 NATS JetStream，通知也变成了可以查看重试与投递结果的独立管线。

我更愿意把 Plan 理解为一张路线图：它让 Agent 和我知道下一步要证明什么，也允许已经被事实推翻的选择被替换。

03 · 开发：让每个文件都对应一个可验证结果

进入开发阶段以后，CodeBuddy 按照 Plan 逐项推进。截图里可以看到它先重整运行时状态，再创建持久化层、探测器、Provider 注册表与 Statuspage 实现。每次生成或修改文件后，它会继续处理类型错误、缺失方法与重复逻辑，而不是等所有代码写完后才尝试运行。

CodeBuddy 在这里承担了调研、文件修改、迁移、测试和浏览器回归，但它并没有替我做完产品判断。例如“首次采集不发送历史事故”“通知规则应该选择服务而不是填写 UUID”“服务状态与采集新鲜度必须分开”，都需要我在看到中间结果以后继续修正规则。

开发中也出现过很典型的偏差：页面一度为了贴近视觉稿覆盖了过多 TDesign 样式，组件原本的交互层级与信息密度反而被削弱。之后我让 CodeBuddy 重新以 TDesign Token 和 Starter 规范为边界，保留 Miora 稿中的布局与信息关系，收回多余的局部样式。

这三个阶段真正形成的是一个反馈环：调研减少错误假设，Plan 控制一次开发的范围，开发结果再返回来修正 Plan。Agent 带来的速度，最终需要靠这条反馈环变成可以交付的质量。

Design Token · OKRamp 色阶生成

这次作业要求复用任务一的色阶能力。我不想在 CSS 里把 Logo 的绿色复制几十次，也不想只覆盖 --td-brand-color，让 Hover、禁用态、链接、边框与深色模式仍然留在原来的蓝色体系里。

StatusHub 直接安装了 @okramp/core 与 @okramp/tdesign。构建前，脚本以 Logo 的薄荷绿 #20C897 为输入，同时生成品牌色阶和带有相同冷暖倾向的中性色阶：

在原文中查看交互内容

生成结果继续映射为 TDesign 的语义 Token：

浅色：brand-7 → 默认操作色，brand-8 → Hover，brand-9 → Active
深色：brand-5 → 默认操作色，brand-4 → Hover，brand-6 → Active
背景、容器、文字与边框 → 由 14 级关联中性色映射

浅色主题需要较深的绿色承载白色按钮文字；深色主题则选择更亮的阶位，保证它在深背景上仍然清楚。contrastPolicy: "adjust" 会在色阶中寻找满足目标对比度、又尽量接近原角色的颜色，生成阶段若仍有检查项不通过便直接失败。

最终，Button、Link、Input、Select、Table、Tag、Drawer 与 Dialog 都从同一套 --td-* 变量读取颜色。主题切换只改变 theme-mode，不需要在运行时重新计算整张色板。圆角也集中映射到 TDesign Token，普通控件从 8px 开始，容器逐级增加，圆形和胶囊形组件仍保留原有形状。

交付与验证

StatusHub 当前已经提供可访问的 HTTPS 演示地址和完整源码仓库。

https://statushub.seeridia.top

由于为了接入国外服务的状态页，该系统部署在国外服务器上，国内访问可能速度较慢或者同时需要特殊的网络环境。

https://github.com/Seeridia/StatusHub

结束语

做完 OKRamp 时，我得到的是一个能够解释颜色如何生成的工具；把它放进 StatusHub 以后，我才真正看到一套色阶如何影响按钮、背景、文字、边框、Hover 与深色模式。

而 StatusHub 本身也经历了类似的过程。它最初只是“把几家状态页放在一起”的想法，经过产品边界、视觉系统、组件语义、数据一致性和通知可靠性的反复补全，才成为一个能够接入、判断、通知与追踪的小应用。

Agent 让从想法到运行产品的距离明显缩短了，Miora、CodeBuddy 让这个过程更可控、更可验证。它们的组合，让我在短时间内完成了一个从设计到研发、从视觉到代码、从单一网页到完整产品的闭环。

重新构想一条色阶

Mon, 14 Sep 2026 15:00:00 GMT

起源于犀牛鸟的任务：

TDesign 各技术栈站点底部都有主题生成器挂件。输入一个主色后，它会扩展出一整套连续色阶，承载从最浅背景、Hover 高亮到最深文字强调等不同场景。

请使用 TypeScript 提供一个函数：输入任意主色，自动“变出”一套 10 级、由浅到深、过渡自然的完整主色阶，并提供 HTML 或任意形式的 UI 界面供体验。如果你能同时考虑深色模式下的色阶效果，以及生成与主题色相关联的中性色阶，将是更好的实现。

其实我在此之前就对颜色相关的一些工作比较感兴趣，所以也想更深入地去了解，想了解这些颜色为什么这样排列，极端输入下应该如何取舍，以及一条色阶怎样继续长成主题。

项目的在线体验和文档都在这里：

https://okramp.seeridia.top

https://github.com/seeridia/okramp

背景

最初看到这个需求时，我也把它理解成一个最普通的插值问题：给定主色，再找一个浅色和一个深色，在它们之间取十个点。

实现并不困难。真正困难的是，当这些颜色摆在一起时，它们是否连续、美观。

哪该如何插值呢

为了把差异直接摆出来，我用同一个主色 #0052D9 做了一组最简单的实验：前七阶从白色插值到主色，后三阶再从主色插值到黑色。除了颜色空间不同，其余条件完全相同。

sRGB 与 HSL

在原文中查看交互内容

就拿我们更常见的 sRGB 来插值，直接让红、绿、蓝三个通道线性变化。色值很好计算，但通道走过相同距离，不代表人眼感受到的明度也走过相同距离。所以你也能明显能感受到他们的亮度并不均匀。

下面这个图就比较直观了

这里其实有两层的不对等。

第一层发生在屏幕上。sRGB 保存的通道值经过一条近似 Gamma 的传递函数编码，它不是灯珠发光强度的直接刻度。

在原文中查看交互内容

这两组颜色是两种不同的中点定义。#808080 的三个通道都位于 00 和 FF 的数值中点；但将 sRGB 编码还原成线性光后，它的相对亮度只有约 21.6%。真正具有 50% 线性光亮度的灰色接近 #BCBCBC。

这说明 sRGB 数值中点不等于视觉中点。但 50% 的视觉中点也不等于 50% 的感知明度：眼睛对亮度的响应同样是非线性的，因此 #BCBCBC 看起来会明显偏亮，#808080 反而更接近通常所说的视觉中灰。第一层不对等发生在 sRGB 编码与屏幕实际发光强度之间，至于人最终觉得它有多亮，还需要继续考虑视觉系统。

第二层发生在眼睛与大脑里。人眼没有三种分别读取屏幕 R、G、B 数字的传感器。视网膜中 S、M、L 三类视锥细胞各自覆盖一段相互重叠的光谱；单个视锥只能报告自己吸收了多少光子，颜色需要由三类视锥的相对响应推断。

因此，sRGB 中每个通道等量前进，只保证设备编码坐标里的步长相等。转换到人眼使用的明暗与拮抗信号后，每一步的距离会被不同程度地拉伸或压缩。

不过，sRGB 编码本身部分利用了视觉的非线性，因此它比直接保存线性光更适合有限位深的图像编码；但它仍然不是三维的感知均匀颜色空间。W3C 对它的描述很直接：sRGB 既不是线性光空间，也不是感知均匀空间。若目标是物理正确地混合光，应在线性 sRGB 中插值；若目标是让颜色沿途更接近感知等距，则更适合使用 Oklab 或 OKLCH。

在原文中查看交互内容

这边就稍微简单讲讲，HSL 把色相、饱和度和亮度分开了，控制起来比 RGB 直观。简单来说，它把颜色参数变得更容易理解（而不是对着 RGB 三个值去调整），却没有让颜色之间的距离更符合人眼感受。

甚至本质上来说，HSL 只是把 sRGB 立方体重新表示成圆柱坐标，本质没有区别。它没有根据视觉实验重新校准空间，因此在圆柱中相同长度的路径，不代表相同的感知色差。

CIELAB 插值

在原文中查看交互内容

到 CIELAB，目标才从“方便描述颜色”变成了“让数值距离近似人眼感受到的色差”。它用 $L^*$ 描述感知明度，用 $a^*$ 表示红—绿方向，用 $b^*$ 表示黄—蓝方向。在这个空间中走过相同距离，通常比 RGB 和 HSL 更接近相同的视觉变化。

上面的过渡因此平稳了不少，尤其是浅色到主色这一段。不过，CIELAB 的感知均匀性只是一种近似，因为它假设整套颜色空间可以共用一把固定的欧氏距离：

\Delta E_{76}^{*} = \sqrt{(\Delta L^{*})^{2}+(\Delta a^{*})^{2}+(\Delta b^{*})^{2}}

但视觉实验发现，人眼的“最小可觉差”会随颜色位置变化。它在色彩空间中表现为大小、方向不同的椭圆，而不是处处相同的圆：

某些区域很小的数值变化就能被察觉。
某些区域需要更大的变化才能被察觉。
蓝色区域还存在明显的色相与彩度耦合。
高彩度颜色距离中性轴更远，更容易暴露模型偏差。

也就是说，人眼在有些区域更敏感，在另一些区域更迟钝；一个固定的欧氏距离无法同时贴合所有区域。这与视锥细胞和后续拮抗通道的非线性响应有关，亮度、彩度和周围环境还会继续影响最终感受到的色差。

当然，后来的 CIEDE2000 色差公式因此加入了随明度、彩度和色相变化的权重，并专门增加蓝色区域的旋转修正项。但这些本质上都是拟补的一些手动，换句话说，如果 CIELAB 本身处处均匀，这些修正就没有存在的必要。原始论文

下面举一个比较明显的例子：在 CIELCH 中保持数值色相不变，只增加彩度

CIELCH：固定数值色相为 301.37°。图片来源：W3C CSS Color 4

OKLCH：固定数值色相为 264.0585°。图片来源：W3C CSS Color 4

这两张图可以这样看：纵轴是明度，越向上越亮；横轴是彩度，越向右越鲜艳。灰色区域超出了 sRGB 能显示的范围，白色轮廓内则是屏幕能够呈现的颜色。

两张图分别固定了 CIELCH 与 OKLCH 中对应 sRGB 蓝色的色相，所以观察时比较彩色区域从左向右是否始终像同一种蓝色。

先看第一张 CIELCH 图。在相近明度下横向移动，只增加彩度，左侧和中段明显偏紫，接近最右端时才逐渐变成蓝色。计算中的色相角始终是 301.37°，人眼看到的色相却发生了变化，这正是 hue curvature。

再看第二张 OKLCH 图。用同样方式从左向右观察，颜色主要是从灰蓝逐渐变成鲜蓝，视觉色相基本保持稳定。

这个对照说明，CIELAB 的问题是它的“固定数值色相”没有对应到人眼感受到的固定色相。

所以回过头来看看

在原文中查看交互内容

你能很明显的发现，浅色部分的蓝色偏紫。它们都是在 CIELAB 中保持数值色相不变，但人眼感受到的色相却发生了变化。

为什么是 OKLCH（OKLAB）

回头看前面的几种方案，它们其实各自解决了一部分问题。

sRGB 忠实描述设备，却不适合拿通道数值当作视觉距离；HSL 让参数变得容易理解，却没有改变 sRGB 不均匀的底层；CIELAB 开始认真拟合人的感知，但在蓝色、高彩度和色相线性上仍有明显偏差。

我需要的颜色空间至少要做到三件事：明度变化看起来稳定，改变彩度时尽量不带动色相，计算过程还要足够简单，才能在浏览器里实时生成整套主题。Oklab 正好是围绕这些目标设计的。

基于视觉实验数据得到的色彩空间

Oklab 沿用了 IPT 颜色空间简洁的计算结构。颜色先从 XYZ 转换成近似三类视锥响应的 $l$ 、 $m$ 、 $s$ ，再经过立方根形式的非线性压缩，最后组合成一条明度轴和两条拮抗色轴：

\begin{pmatrix} l \\ m \\ s \end{pmatrix} = \mathbf{M}_{1} \begin{pmatrix} X \\ Y \\ Z \end{pmatrix}

\begin{pmatrix} L \\ a \\ b \end{pmatrix} = \mathbf{M}_{2} \begin{pmatrix} \sqrt[3]{l} \\ \sqrt[3]{m} \\ \sqrt[3]{s} \end{pmatrix}

真正重要的是矩阵 $\mathbf{M}_{1}$ 与 $\mathbf{M}_{2}$ 如何确定。Oklab 的作者 Björn Ottosson 准备了三组用于检验明度、彩度和色相的数据：明度与彩度数据由 CAM16 在正常观看条件下生成，等色相数据则来自用于建立 IPT 的视觉实验。随后调整矩阵参数，使模型尽可能把“同样亮”“同样鲜艳”和“同一色相”的颜色分别放在对应的等值线上。Oklab 的推导过程

可以把 IPT 理解成一套轻量的颜色坐标。它把颜色拆成“有多亮”，以及“偏红还是偏绿”“偏蓝还是偏黄”。它计算简单，而且改变颜色深浅时不容易突然跑色；不足之处是，它判断一个颜色有多亮、多鲜艳时还不够准确。

CAM16 更像一台复杂的视觉模拟器。同一个色值放在明亮房间、昏暗房间或不同背景上，看起来可能并不一样；CAM16 会把这些观看条件也考虑进去，再估计人眼觉得它有多亮、多鲜艳。它更全面，但计算也复杂得多。

Oklab 的做法可以概括为：使用 IPT 简单好算的结构，学习 CAM16 对明度和彩度的判断，再用视觉实验校准色相。 最终得到一套接近复杂视觉模型，同时能在浏览器里快速计算的颜色坐标。

因此 Oklab 针对图像处理与颜色混合的需求，在准确度、稳定性和计算复杂度之间取得了更合适的平衡。

OKLAB 到 OKLCH

Oklab 使用 $L$ 、 $a$ 、 $b$ 直角坐标，适合计算颜色距离与进行一般混合。OKLCH 只是同一个空间的圆柱表示：

C=\sqrt{a^{2}+b^{2}},\qquad h=\operatorname{atan2}(b,a)

Oklab 提供更接近感知均匀的底层坐标，OKLCH 则把同一坐标改写成适合设计色阶的控制方式，只是通过圆柱坐标系把色阶真正关心的三个维度直接暴露出来： $L$ 控制由浅到深， $C$ 控制每一级保留多少色感， $h$ 控制颜色属于哪个色相。

当然，OKLCH 也不会自动生成一条好色阶。它仍可能产生超出 sRGB 的颜色，也无法替我决定浅色背景、中间主色和深色文字分别应该有多亮、多鲜艳。它解决的是“怎样独立、稳定地控制颜色属性”，后面文章会讲这件事。

其他的一些痛痒

其中看到题目就有的一个矛盾是：保留输入原色听起来理所当然，但它有时会破坏完整色阶。

例如，将 #EAF6FF 固定在第六阶。它已经接近最浅背景色，算法却还需要在它前面安排五个更浅的颜色。无论怎样插值，这五阶都很容易挤在一起。

反过来，如果为了让十阶充分展开而重新建立完整明度曲线，输入色就不一定能原样出现在结果里。对于已有品牌规范的项目，这同样可能无法接受。

完整的明度跨度与固定的输入色位置，在极端输入下可能互相冲突。与其让算法替用户作决定，我更希望把它设计成 API 中明确可选的取舍。

向你介绍 OKRamp

OKRamp 是一个基于 OKLCH 的 TypeScript 色彩引擎。

默认情况下，它从输入色提取色相和彩度特征，再重建完整的十阶明度和彩度曲线。除此之外，它也提供两种保留原色的锚点策略。

整个生成过程分成下面几步：

解析输入

接受可解析的 CSS 颜色字符串，将它转换为 OKLCH，并规范化为不透明的 sRGB 种子颜色。
建立曲线

根据策略计算每一阶的目标明度、彩度和色相。
映射色域

对超出 sRGB 的候选色固定明度与色相，只降低彩度。
检查结果

输出 HEX、RGB 或 OKLCH，同时检查相邻重复、低感知差异和主题对比度。
建立主题

在基础品牌色阶与中性色阶之上，分别映射浅色和深色语义角色。

核心包不依赖 React 以及任何组件库。体验站、组件库适配器和主题导出都建立在这样的公开 API 之上

最小用法

对调用者来说，最小用法只有一行：

import { generateColorScale } from '@okramp/core'

const scale = generateColorScale('#0052D9')
console.log(scale.colors)

默认会得到：

[
  '#f0f5ff',
  '#dce9ff',
  '#bdd5ff',
  '#94bbff',
  '#659cff',
  '#327aff',
  '#155dde',
  '#0244b4',
  '#002e84',
  '#001b54'
]

在原文中查看交互内容

输入和输出足够简单，但引擎不会只返回十个字符串。每一阶还包含 OKLCH 数值、来源和色域映射状态；整个结果也能附带诊断信息，让调用者知道哪些颜色经过了调整、哪些相邻阶位可能过于接近。

例如，截取上面结果的第 6、7 阶和诊断信息，可以看到这样的输出（OKLCH 小数经过取整）：

{
  "recommendedIndex": 6,
  "stops": [
    {
      "index": 5,
      "label": "6",
      "color": "#327aff",
      "oklch": {
        "l": 0.61,
        "c": 0.2112,
        "h": 261.35
      },
      "inGamut": true,
      "source": "gamut-mapped"
    },
    {
      "index": 6,
      "label": "7",
      "color": "#155dde",
      "oklch": {
        "l": 0.52,
        "c": 0.2087,
        "h": 261.35
      },
      "inGamut": true,
      "source": "generated"
    }
  ],
  "diagnostics": {
    "valid": true,
    "messages": [
      {
        "code": "GAMUT_MAPPED",
        "severity": "info",
        "message": "Some stops required OKLCH chroma reduction to fit sRGB.",
        "stopIndexes": [0, 1, 2, 3, 4, 5, 8]
      }
    ],
    "contrastChecks": []
  }
}

这里的 source 描述这一阶如何得到：generated 表示目标 OKLCH 本身就在 sRGB 内，gamut-mapped 表示它原本超出显示范围，引擎保持明度与色相，只降低彩度后得到当前色值。inGamut 表示最终输出已经可以在 sRGB 中安全显示。recommendedIndex 使用从零开始的数组索引，因此 6 指向色阶中的第 7 阶。

生成策略

前面提到的“原色保留”冲突，在 OKRamp 中被设计成三种明确策略：

策略	它优先保证什么	适用场景
`tonal`，默认	完整、稳定的明度跨度	自由输入、极端颜色
`adaptive-anchor`	保留规范化主色，同时选择更合适的阶位	品牌色必须保留，但阶位可以变化
`fixed-anchor`	保留规范化主色和指定阶位	已有明确的设计系统约定

adaptive-anchor 会综合输入明度、目标阶位距离和锚点两侧剩余空间。输入越浅，锚点越靠近浅端；输入越深，锚点越靠近深端。

fixed-anchor 则尊重调用者的明确要求。即使极端输入导致一侧空间被压缩，引擎也不会悄悄移动它，而是返回低相邻色差或重复阶位诊断。

这道题强调“输入任意主色”和“完整色阶”。当输入亮度本身不适合位于中间时，重新建立完整曲线通常能得到更可用的结果。代价是输入色不保证原样出现，这一点会在 UI 和 API 文档中明确说明。

明度曲线

默认十阶的明度预设如下：

L = [0.97, 0.93, 0.87, 0.79, 0.70, 0.61, 0.52, 0.43, 0.34, 0.25]

浅端间隔较小，让大面积背景的变化更克制；从第三阶开始逐渐拉开，到中后段保持相对稳定的差异，为 Hover、默认态、Active 和文字强调留出空间。

端点默认仍然带有色相，而不是强制变成纯白与纯黑。这能让整条色阶更像同一个颜色家族。如果确实需要黑白端点，也可以显式选择 black-white 模式。

这是一条面向界面用途的预设曲线，并不是严格等色差的数学直线。最终是否自然，还要结合彩度变化、色域映射和实际背景一起观察。

彩度曲线

如果十个颜色保持相同彩度，浅端往往会显得发飘，深端也可能显得生硬。因此，OKRamp 使用一条先升后降的彩度曲线：

factor = [0.12, 0.30, 0.52, 0.74, 0.92, 1.00, 0.96, 0.86, 0.70, 0.50]

C[i] = min(seed.C, 0.32) × factor[i]
H[i] = seed.H

浅端只保留少量彩度，使它更适合作为背景；中段达到峰值，集中表达品牌；深端逐步收敛，但仍然保留色相特征，避免简单地一路灰下去。

这条共享曲线是一套可解释的基础预设，并不假装对所有色相都已经达到最终最优。黄色、青色和紫色仍会受到各自 sRGB 边界的影响，这也是下一节要处理的问题。

色域映射

OKLCH 可以描述许多屏幕无法用 sRGB 表示的颜色。高彩度候选色如果直接裁剪 RGB 通道，往往会同时改变它的明度和色相，让局部阶位出现意外跳跃。

OKRamp 的做法是固定 L 和 H，只降低 C，找到仍处于 sRGB 内的最大彩度

因此，映射后的颜色尽量保留原定的明暗位置和色相，只牺牲当前设备无法显示的那部分鲜艳程度。发生映射的阶位会被标记为 gamut-mapped，同时进入诊断结果。

这里需要区分颜色空间与显示色域。OKLCH 是描述颜色的坐标系统，它能够表示的颜色不受 sRGB 边界限制；sRGB 则是目标设备所能显示的一组有限颜色。当某个 OKLCH 坐标落在 sRGB 之外时，需要映射并不是因为 OKLCH 产生了错误，而是当前显示色域无法呈现那个颜色。

固定 $L$ 与 $H$ 、只降低 $C$ ，利用了 OKLCH 将感知明度、彩度和色相分开表达的特点。它不能保留设备无法显示的鲜艳程度，但能尽量避免映射过程额外带来明度跳跃或色相偏移。

主题与生态

我不想止步于生成十个色块。界面需要的是语义角色，而不是阶位数字。

所以，我拓展了 OKRamp 的生态，OKRamp 在基础色阶之上又增加了一层主题模型。并目前提供了下面几个适配器：

@okramp/tdesign：TDesign
@okramp/antd：Ant Design
@okramp/shadcn：shadcn/ui

中性色

如果品牌色是偏冷的蓝色，而所有背景和灰色都使用完全中性的灰，界面有时会产生轻微的割裂感。

OKRamp 会生成一条低彩度中性色阶，让它继承品牌色的冷暖倾向：

neutral.C[i]
  = min(tintStrength, seed.C × 0.18)
  × neutralFactor[i]

默认 tintStrength = 0.025

中性色有独立的 10 阶和 14 阶明度曲线。彩度在中段略高，在极浅与极深端收敛。这样，它仍然是一套能承载大面积背景和正文的“灰”，只是与品牌色处在同一种气氛里。

在原文中查看交互内容

当输入本身接近无彩色时，结果也会自然回到普通灰阶。算法不会凭空为纯黑或纯白发明一个色相。

深色模式

深色模式并不是把浅色色阶倒过来。

在深色界面里，页面背景来自中性色深端，容器和浮层逐级提亮；文字从浅端选择。品牌默认色会比浅色主题更亮，Hover 继续提亮，Active 相对压暗。按钮上的前景色也会重新从黑白中选择，而不是沿用浅色主题的结果。

浅色与深色主题目前共享同一套基础品牌色阶，再分别映射语义角色；项目尚未为深色模式生成一条完全独立的品牌曲线。

对比度

主题角色建立后，引擎会检查预定义的前景与背景组合。默认目标是普通文字 4.5:1、重要非文本元素 3:1。

它提供三种策略：

report：保留原结果，只报告未达到目标的组合。
adjust：在已有品牌或中性色阶中寻找满足目标、且与原角色最接近的候选色。
strict：不调整，只要存在失败项便抛出结构化错误。

这些检查覆盖引擎列出的语义组合。它们能帮助主题映射避免明显问题，但不等同于整个页面、所有字号和全部组件状态都获得了可访问性认证。

Playground

https://okramp.seeridia.top

我同时为 OKRamp 做了一个 React + TDesign 的体验站。

工作台可以调整主色、策略、阶数、端点、色相偏移、中性色强度和对比度策略。每次修改都会同时更新色板、组件预览、语义 Token 与诊断。

界面也能切换浅色和深色，让同一组结果直接进入按钮、卡片、文字和边框，而不是停留在十个色块里。

“方案对比”页面还会并排展示 OKRamp、TDesign 主题生成器使用的 tvision-color、@ant-design/colors，以及 RGB、HSL、Lab 等插值结果。

生成结果可以导出为 CSS、JSON 或 TypeScript，并能映射到 TDesign、Ant Design 和 shadcn/ui。核心算法与这些适配器彼此独立，因此项目也可以只安装实际需要的部分。

展示

最后，把几类输入放在一起看。下面所有 Case 都直接调用 generateColorScale(seed)，使用默认的 tonal 策略与十级曲线，没有为某个颜色单独调整参数。

常规主色

这三组颜色分别覆盖蓝、红、绿三个常见界面色相。观察重点是：浅端是否仍能看出所属色相，中段是否足够鲜明，以及进入深端后有没有迅速发灰。

在原文中查看交互内容

极端明度输入

最后两组故意选择接近白色和黑色的蓝。默认 tonal 不会强行把输入固定在中间某一阶，而是提取它的色相与彩度倾向，重新展开完整明度曲线。因此这两组结果不会保证原始色值出现在色阶中，但仍应当形成可用于背景、交互状态和文字的十个层级。

在原文中查看交互内容

不同方案的对比

再用青色 #0099B8 做一次横向对比。这里统一输入主色与十级数量，但保留每种算法自己的生成规则；对应的结果也可以在 Playground 方案对比中交互查看。

选取这个也能色确实是一个比较极端的例子：它接近 sRGB 边界。不同算法在浅端、中段和深端的处理方式都不一样。

在原文中查看交互内容

OKRamp 使用默认 tonal 策略重新建立完整的明度与彩度曲线，因此输入色没有原样出现在结果中。

在原文中查看交互内容

TDesign 主题生成器使用的 tvision-color 基于 HCT，并根据色相调整 Tone 与彩度曲线。这组结果的推荐主色位于第 5 阶，输入色同样不保证被原样保留。

另外可以明显看到第 3 阶的颜色异常偏亮。

在原文中查看交互内容

Ant Design 使用基于 HSV 的十级色板算法，并将输入主色固定在第 6 阶。它的前五阶向浅端扩展，后四阶向深端扩展，所以主色位置与另外几组并不相同。

在原文中查看交互内容

最后两组使用同一个简单条件：前七阶从白色插值到主色，后三阶从主色插值到黑色。HSL 的参数更容易理解，但明度与饱和度并不感知均匀；sRGB 视觉明度变化容易在深端聚集。

结束语

OKRamp 目前选择了一条偏工程化的路线：用 OKLCH 拆开问题，表达设计倾向，用不同策略公开取舍。

当然也为其生态提供了适配，让它能直接进入各个设计系统中，各个组件库中，帮助设计师和开发者快速生成可用的主题。

它仍然有继续改进的空间。不同色相目前共享基础曲线，sRGB 边界会改变局部彩度变化，比如 Tdesign 的 tvision-color 对很多颜色都单独调整了彩度曲线。OKRamp 也可以在未来提供更多可选的明度与彩度曲线，或者允许用户自定义。

在对任务的探索的过程中，也是对颜色空间、色彩感知和视觉实验有了更深入的理解。了解了不同的颜色空间如何影响颜色的感知，以及如何在设计中应用这些知识来创建更符合人眼感受的颜色方案。

但作为这个任务的回答，我想我的这些工作和这个文档已经不仅能“变出”十个颜色，也能展示这十个颜色为什么这样变化，以及它们如何真正走进一个界面。

用 Cloudflare One 与 EasyTier 构建内外双路径的个人服务网络

Sat, 18 Jul 2026 00:00:00 GMT

自用的自托管服务越来越多，像是 grafana、n8n 等等各种的管理面板，那如何在保证安全性的同时，提高自己的使用体验？

这些服务通常只需要我本人访问，并不适合直接暴露在互联网上。但完全限制在家庭局域网或者 VPN 内，又会在临时设备、公司电脑或无法接入 VPN 的环境中带来不便。

所以我将需求确定：

在接入 VPN 后，访问流量直接通过虚拟内网到达服务器；
在未接入 VPN 时，经过一层登录鉴权后访问。如果可以，这边能较为自由的控制用户策略，比如临时给他人授权。

由此我也确定了采用了由 Easytier 和 Cloudflare 构成的混合方案：

连接 EasyTier 时，访问流量直接通过虚拟内网到达服务器，不经过 Cloudflare；
未连接 EasyTier 时，使用同一个域名访问，先经过 Cloudflare Access 登录鉴权，再通过 Tunnel 回源。

架构设计

flowchart TD
    A["访问 grafana.seeridia.link"] --> B{"是否连接 EasyTier"}
    B -->|"是"| C["DNS 本地映射"]
    C --> D["10.126.0.1:443"]
    D --> E["1Panel / HTTPS"]
    E --> F["Grafana<br/>127.0.0.1:3011"]
    B -->|"否"| G["Cloudflare DNS"]
    G --> H["Cloudflare Access"]
    H --> I["身份认证与允许策略"]
    I --> J["Cloudflare Tunnel"]
    J --> K["Seeridia-Net 连接器"]
    K --> F

使用者不需要关心当前走的是哪条路径，只需要始终打开：

https://grafana.seeridia.link

域名的解析结果决定了后续流量是通过 EasyTier 直达服务器，还是进入 Cloudflare 的身份认证流程。

用户端 - Easytier 侧

EasyTier 负责建立设备和服务器之间的加密虚拟网络，类似于常见的 Tailscale 等 VPN，这些都可以的，其实都差不了太多，不过 Easytier 往往拥有更为激进的策略，这边不展开讲其相关配置。

其实有了 Easytier 我们就可以直接通过内网去访问相关的服务而无需打开相关端口的安全组等等，到这一步就能满足大多数人的需求了，不过我们的最终目标还需要比如访问 grafana.seeridia.link 能根据我们自身环境，后续流量是通过 EasyTier 直达服务器，还是进入 Cloudflare 的身份认证流程。

在用户侧，我们要解决的是对这个 seeridia.link 域名我们应进行 DNS 映射，相关域名直接解析到 EasyTier 地址，我们可以有多种方式去配置 DNS，比如 macOS 可以通过 /etc/resolver 实现“不同域名走不同 DNS”

bookmark

不过我自己有 Surge，就也直接使用 Surge 了

Cloudflare One

我都以自己的seeridia.link 为例，首先需要将域名托管在 Cloudflare。我们要做的是：当设备不使用 Surge 的本地 DNS 映射时，grafana.seeridia.link 会按照 Cloudflare 公网 DNS 的配置进入 Cloudflare 网络。

Cloudflare Tunnel

Cloudflare Tunnel 是用以将服务器接入 Cloudflare

在 Cloudflare Tunnel 中创建了一个名为 Seeridia-Net 的隧道，将服务器接入该隧道，该步骤按照 Cloudflare 的指引即可

接着可以编辑「已发布应用程序路由」

这边放上需要接入 Cloudflare Access 的全部服务

这边不需要再配置 DNS，Cloudflare 会自动帮你配好

标识提供程序

集成→标识提供程序

用于配置提供访问网站的登录方式，这边的 One-time PIN 即发邮箱验证码，是默认免费提供的。当然你可以自己配置 Github、Google 等等的登录方式

访问策略

访问控制→策略

用于配置哪些用户可以访问我们的服务，并且也可以配置多个不同的访问策略面向不同的服务。这边主要就是验证上一步回调或验证的邮箱。

应用程序

访问控制→应用程序

这边主要是将应用程序，即在刚刚配置 Tunnel 那边的应用程序加入 Cloudflare One

服务器反代

正常部署反代即可。

我自己用的是可视化面板的 1Panel，其他的也都差不多。

总结

这套架构的核心并不是简单地把两个组网工具叠在一起，而是为同一个服务设计两种不同的访问方式：

对已经加入可信内网的设备，提供直接、低依赖的 EasyTier 访问路径；
对没有加入内网的设备，提供由 Cloudflare Access 保护的浏览器访问路径。

对我来说，这套方案的价值在于：它既没有要求所有临时设备都安装 VPN，也没有为了方便而直接把私人服务暴露到公网；同时，当设备已经位于自己的 EasyTier 网络中时，又不需要让访问流量无意义地绕行 Cloudflare。

Vitepress 站点提供下载 PDF 的方式

Tue, 20 Jan 2026 18:00:00 GMT

我有另一个关于化学笔记的项目，它使用 VitePress 构建文档站点。

但其实这个项目面向的是高中生，他们更习惯于离线阅读资料（没得手机）。在笔者自己高中的时候，这个就是自己手动去一个个用 Typora 导出 PDF，然后再打包发给同学。一来是麻烦，二来是没办法及时更新。

现在最近也闲了，也发现当时的这个项目现在看的人突然多了起来，所以一方面用 VitePress 构建文档站点，另一方面也想给用户提供一个下载 PDF 的方式。(其实也不仅局限于 vitepress)

所以我想着去彻底解决这个问题——实现在每次我更新文档站点的时候，顺便也能生成一个 PDF 版本的文档的自动化流程。

总体思路

思路其实很简单，VitePress 本身虽然并不支持直接导出 PDF，但是其构建产物不就是 HTML 页面吗？那我们完全可以使用一个工具，把这些 HTML 页面转换成 PDF。

关于 PDF 的问题解决了，另一个就是关于下载的问题。由于用户主要都是国内的高中生，速度需要有保证，所以我选择把生成的 PDF 文件放在 cnb.cool 上面，这样用户可以直接通过 cnb 提供的文件下载链接来下载最新的 PDF 文件。

（实际上是看了一些软件的镜像下载就放在 cnb 上，看着挺不错的，也就这样用了）

清理页面样式

首先是清理一下页面媒体查询在打印时的表现。

媒体查询这个大家都蛮熟的了，这边放上一个调试方式（噗嗤，以前我还真是傻傻的去 Ctrl + P 预览打印效果，后来才知道有这个东西）。

好在 VitePress 本身也蛮打印友好的，稍微调整了一下隐藏一些不必要的元素（比如导航栏、侧边栏、页脚等）就好了。对我来说需求就这些，其实也可以在页脚加上一些只在打印时候显示的信息，比如版权页面等，都可以用媒体查询来实现。

判断需要导出的页面

其实主要是没法每次都全量导出所有页面的 PDF，毕竟文档站点页面多了之后，生成 PDF 的时间会很长。所以我就想着能不能只导出改动过的页面。

下面直接贴代码，主要就是用 git diff 来判断哪些页面改动了，然后只导出这些页面。

同时也对一些“全局变更”做了判断，比如说侧边栏配置、主题配置、公共资源等，只要这些变更了，就直接全量导出 PDF。

// scripts/changed-pages.js

import { execFileSync } from 'child_process'
import fs from 'fs'
import path from 'path'
import url from 'url'

const __dirname = path.dirname(url.fileURLToPath(import.meta.url))

const args = process.argv.slice(2)
const getArgValue = (flag) => {
    const index = args.indexOf(flag)
    if (index === -1) {
        return null
    }
    return args[index + 1] || null
}

const base = getArgValue('--base') || process.env.GIT_BASE
const head = getArgValue('--head') || process.env.GIT_HEAD || 'HEAD'
const outDirInput = getArgValue('--out-dir')
const outDir = outDirInput
    ? path.resolve(process.cwd(), outDirInput)
    : path.resolve(__dirname, '../.github/changed-pages')

// 全 0 的 SHA 表示“无基准”，需要全量导出
const zeroSha = /^0+$/
// 判断是否属于需要全量导出的“全局变更”
const isGlobalChange = (filePath) => {
    if (!filePath) {
        return false
    }
    const normalized = filePath.replace(/\\/g, '/')
    // 如果是下面这些路径的变更，则直接视为全局变更
    return (
        normalized.startsWith('.vitepress/') ||
        normalized.startsWith('public/') ||
        normalized.startsWith('data/') ||
        normalized === 'package.json' ||
        normalized === 'package-lock.json' ||
        normalized === 'bun.lock'
    )
}

// 将 .md 路径映射为站点输出的 .html 路径
const mdToHtml = (filePath) => {
    if (!filePath) {
        return null
    }
    const normalized = filePath.replace(/\\/g, '/')
    if (!/\.md$/i.test(normalized)) {
        return null
    }
    const dir = path.posix.dirname(normalized)
    const baseName = path.posix.basename(normalized)
    const lower = baseName.toLowerCase()
    const targetName =
        lower === 'readme.md' || lower === 'index.md'
            ? 'index.html'
            : baseName.replace(/\.md$/i, '.html')
    return dir === '.' ? targetName : `${dir}/${targetName}`
}

const outputs = {
    forceAll: false,       // 是否需要全量导出
    changed: new Set(),    // 变更的页面列表
    deleted: new Set()     // 删除的页面列表
}

// base 不存在或是全 0，则直接全量
if (!base || zeroSha.test(base)) {
    outputs.forceAll = true
} else {
    let diffOutput = ''
    try {
        // 使用 git diff 获取变更文件列表（含重命名）
        diffOutput = execFileSync('git', ['diff', '--name-status', '-z', `${base}..${head}`], {
            encoding: 'utf8'
        }).trim()
    } catch (error) {
        // 失败时兜底为全量
        outputs.forceAll = true
    }

    if (!outputs.forceAll && diffOutput) {
        // -z 模式以 \0 分隔，便于处理包含空格的路径
        const parts = diffOutput.split('\0').filter(Boolean)
        for (let index = 0; index < parts.length; index += 1) {
            const status = parts[index]
            if (!status) {
                continue
            }
            // 处理重命名：Rxxx 旧路径 新路径
            if (status.startsWith('R')) {
                const oldPath = parts[index + 1]
                const newPath = parts[index + 2]
                index += 2
                if (isGlobalChange(oldPath) || isGlobalChange(newPath)) {
                    outputs.forceAll = true
                }
                // 旧路径视为删除，新路径视为新增
                const deleted = mdToHtml(oldPath)
                const added = mdToHtml(newPath)
                if (deleted) {
                    outputs.deleted.add(deleted)
                }
                if (added) {
                    outputs.changed.add(added)
                }
                continue
            }

            const filePath = parts[index + 1]
            index += 1
            if (isGlobalChange(filePath)) {
                outputs.forceAll = true
            }

            // 只跟踪 Markdown 的变更
            const htmlPath = mdToHtml(filePath)
            if (!htmlPath) {
                continue
            }
            if (status === 'D') {
                outputs.deleted.add(htmlPath)
            } else {
                outputs.changed.add(htmlPath)
            }
        }
    }
}

fs.mkdirSync(outDir, { recursive: true })

const changedList = outputs.forceAll ? [] : Array.from(outputs.changed).sort()
const deletedList = Array.from(outputs.deleted).sort()

// 写入结果文件，供后续工作流读取
fs.writeFileSync(path.join(outDir, 'export-all.txt'), outputs.forceAll ? 'true' : 'false')
fs.writeFileSync(path.join(outDir, 'changed-pages.txt'), changedList.join('\n'))
fs.writeFileSync(path.join(outDir, 'deleted-pages.txt'), deletedList.join('\n'))

// 控制台输出简要统计
console.log(
    JSON.stringify({
        forceAll: outputs.forceAll,
        changed: changedList.length,
        deleted: deletedList.length
    })
)

导出 PDF

这边我使用的是 Playwright 来做这个工作，因为它本身支持无头浏览器操作，并且可以直接导出 PDF。

读取刚刚生成的变更页面列表，然后一个个打开页面，直接调用 page.pdf() 方法导出 PDF 即可。唯一注意的是 CJK 字体的问题，需要注入一些字体样式，确保中文能正确显示。（这边在后续的 GitHub Actions 里也需要安装了 Noto Sans CJK 字体）

// scripts/export-pdf.js

import { chromium } from 'playwright'
import fg from 'fast-glob'
import http from 'http'
import fs from 'fs'
import path from 'path'
import url from 'url'

const __dirname = path.dirname(url.fileURLToPath(import.meta.url))
const distDir = path.resolve(__dirname, '../.vitepress/dist')

const args = process.argv.slice(2)
const listIndex = args.indexOf('--list')
const outIndex = args.indexOf('--out-dir')
const listPath = listIndex >= 0 ? args[listIndex + 1] : null
const outDirArg = outIndex >= 0 ? args[outIndex + 1] : null
if (listIndex >= 0 && !listPath) {
    throw new Error('Missing value for --list')
}
if (outIndex >= 0 && !outDirArg) {
    throw new Error('Missing value for --out-dir')
}
const outDir = outDirArg
    ? path.resolve(process.cwd(), outDirArg)
    : path.resolve(__dirname, '../pdf')

fs.mkdirSync(outDir, { recursive: true })

const mimeTypes = {
    '.css': 'text/css; charset=utf-8',
    '.gif': 'image/gif',
    '.html': 'text/html; charset=utf-8',
    '.jpeg': 'image/jpeg',
    '.jpg': 'image/jpeg',
    '.js': 'application/javascript; charset=utf-8',
    '.json': 'application/json; charset=utf-8',
    '.png': 'image/png',
    '.svg': 'image/svg+xml',
    '.webp': 'image/webp',
    '.woff': 'font/woff',
    '.woff2': 'font/woff2'
}

// 用本地 HTTP 服务替代 file:// 访问，确保 CSS/JS/图片/字体等资源按正常 URL 规则加载
// 同时避免浏览器对 file:// 的安全限制导致资源无法读取
const server = http.createServer((req, res) => {
    if (!req.url) {
        res.writeHead(400)
        res.end('Bad Request')
        return
    }

    // 去掉查询参数后再做 decode，防止路径中包含中文或空格时无法访问
    const decodedPath = decodeURIComponent(req.url.split('?')[0])
    const safePath = decodedPath.replace(/^\/+/, '')
    const filePath = path.resolve(distDir, safePath || 'index.html')

    if (!filePath.startsWith(distDir)) {
        res.writeHead(403)
        res.end('Forbidden')
        return
    }

    fs.stat(filePath, (err, stats) => {
        if (err || !stats.isFile()) {
            res.writeHead(404)
            res.end('Not Found')
            return
        }

        const ext = path.extname(filePath).toLowerCase()
        const contentType = mimeTypes[ext] || 'application/octet-stream'
        res.writeHead(200, { 'Content-Type': contentType })
        fs.createReadStream(filePath).pipe(res)
    })
})

let files = []
if (listPath) {
    const raw = fs.readFileSync(listPath, 'utf8')
    files = raw
        .split('\n')
        .map((line) => line.trim())
        .filter((line) => line && line !== '404.html')
    files = Array.from(new Set(files))
    files = files.filter((file) => fs.existsSync(path.join(distDir, file)))
} else {
    files = await fg('**/*.html', {
        cwd: distDir,
        ignore: ['404.html']
    })
}

if (files.length === 0) {
    console.log('No pages to export.')
    process.exit(0)
}

const serverPort = await new Promise((resolve) => {
    server.listen(0, '127.0.0.1', () => resolve(server.address().port))
})

const browser = await chromium.launch()
const page = await browser.newPage()
// 注入字体样式，确保中文能好好显示
await page.addStyleTag({
    content:
        'html, body { font-family: "Noto Sans CJK SC","Noto Sans SC","Source Han Sans SC","Microsoft YaHei","PingFang SC",sans-serif !important; }'
})

for (const file of files) {
    const inputPath = path.join(distDir, file)
    const outputPath = path.join(outDir, file.replace(/\.html$/, '.pdf'))

    fs.mkdirSync(path.dirname(outputPath), { recursive: true })

    const urlPath = encodeURI(file.replace(/\\/g, '/'))
    const fileUrl = `http://127.0.0.1:${serverPort}/${urlPath}`

    console.log('Exporting:', file)

    await page.goto(fileUrl, { waitUntil: 'networkidle' })
    await page.evaluate(() => (document.fonts ? document.fonts.ready : null))

    await page.pdf({
        path: outputPath,
        format: 'A4',
        printBackground: true,
        margin: {
            top: '15mm',
            bottom: '15mm',
            left: '15mm',
            right: '15mm'
        }
    })
}

await browser.close()
await new Promise((resolve) => server.close(resolve))

Github Actions 集成

到这边我个人的方案是：将上一步已经导出的 PDF 文件 push 到一个单独的仓库上，并且我选择放在 cnb 上面，这样国内用户可以直接通过 cnb 提供的文件下载链接来下载最新的 PDF 文件。

这边我直接是将每次构建的新文件都放新的分支上，然后强制改名覆盖主分支，这样 cnb 上就只有一次 commit 的历史记录，节省空间和拉取速度。

name: Deploy to Production Server

on:
  push:
    branches:
      - master

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      # 第一步：迁出代码
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # 第二步：设置 Bun 环境
      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      # 第三步：安装依赖
      - name: Install Dependencies
        run: bun install

      # 第四步：打包项目
      - name: Build Project
        run: bun run docs:build

      # 第五步：检测变更页面
      - name: Detect changed pages
        id: changed_pages
        run: |
          bun scripts/changed-pages.js --base "${{ github.event.before }}" --head "${{ github.sha }}" --out-dir .github/changed-pages
          export_all=$(cat .github/changed-pages/export-all.txt)
          changed_count=$(grep -c . .github/changed-pages/changed-pages.txt || true)
          deleted_count=$(grep -c . .github/changed-pages/deleted-pages.txt || true)
          echo "export_all=$export_all" >> $GITHUB_OUTPUT
          echo "changed_count=$changed_count" >> $GITHUB_OUTPUT
          echo "deleted_count=$deleted_count" >> $GITHUB_OUTPUT

      # 第六步：上传构建产物供 PDF 导出使用
      - name: Upload build artifacts
        uses: actions/upload-artifact@v4
        with:
          name: site-dist
          path: |
            .vitepress/dist
            .github/changed-pages

      # 第七步：部署到服务器（略）

  export-pdfs:
    needs: build-and-deploy
    runs-on: ubuntu-latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Download build artifacts
        uses: actions/download-artifact@v4
        with:
          name: site-dist
          path: .

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - name: Install Dependencies
        run: bun install

      # 需要安装 CJK 字体以确保 PDF 导出时中文显示正确
      - name: Install CJK fonts
        run: |
          sudo apt-get update
          sudo apt-get install -y fonts-noto-cjk

      # 读取变更页面信息
      - name: Read changed pages info
        id: changed_pages
        run: |
          export_all=$(cat .github/changed-pages/export-all.txt 2>/dev/null || echo "false")
          changed_count=$(grep -c . .github/changed-pages/changed-pages.txt 2>/dev/null || true)
          deleted_count=$(grep -c . .github/changed-pages/deleted-pages.txt 2>/dev/null || true)
          echo "export_all=$export_all" >> $GITHUB_OUTPUT
          echo "changed_count=$changed_count" >> $GITHUB_OUTPUT
          echo "deleted_count=$deleted_count" >> $GITHUB_OUTPUT

      # 克隆 PDF 仓库（只需要 clone 1层，不然后面很大）
      - name: Clone CNB PDF Repository
        if: steps.changed_pages.outputs.export_all == 'true' || steps.changed_pages.outputs.changed_count != '0' || steps.changed_pages.outputs.deleted_count != '0'
        run: |
          git clone --depth 1 https://cnb:${{ secrets.CNB_TOKEN }}@cnb.cool/Seeridia/Chemistry-Note-File.git pdf-repo

      - name: Install Playwright Browsers
        if: steps.changed_pages.outputs.export_all == 'true' || steps.changed_pages.outputs.changed_count != '0'
        run: npx playwright install --with-deps chromium

      - name: Export PDFs (all)
        if: steps.changed_pages.outputs.export_all == 'true'
        run: bun scripts/export-pdf.js --out-dir pdf-repo

      - name: Export PDFs (changed)
        if: steps.changed_pages.outputs.export_all != 'true' && steps.changed_pages.outputs.changed_count != '0'
        run: bun scripts/export-pdf.js --list .github/changed-pages/changed-pages.txt --out-dir pdf-repo

      - name: Remove deleted PDFs
        if: steps.changed_pages.outputs.deleted_count != '0'
        run: |
          while IFS= read -r file; do
            [ -z "$file" ] && continue
            pdf="${file%.html}.pdf"
            rm -f "pdf-repo/$pdf"
          done < .github/changed-pages/deleted-pages.txt

      - name: Push PDF updates
        if: steps.changed_pages.outputs.export_all == 'true' || steps.changed_pages.outputs.changed_count != '0' || steps.changed_pages.outputs.deleted_count != '0'
        run: |
          cd pdf-repo
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          if [ -z "$(git status --porcelain)" ]; then
            echo "No PDF changes to push."
            exit 0
          fi
          git checkout --orphan temp-sync
          git add -A
          git commit -m "Sync PDFs from ${{ github.sha }}"
          git branch -M main
          git push --force origin main

vitepress 配合

最后在 VitePress 站点里加一个下载链接就好了，这一部分可以去 vitepress 官方文档里看看相关内容

<script setup lang="ts">
import { computed } from "vue";
import { useData } from "vitepress";

const { page } = useData();

const PDF_BASE_URL =
  "https://cnb.cool/Seeridia/Chemistry-Note-File/-/git/raw/main/";

// 生成当前页面对应的 PDF 下载链接
const pdfUrl = computed(() => {
  const filePath = page.value.filePath ?? "";
  if (!filePath.endsWith(".md")) return "";
  const pdfPath = filePath.replace(/\.md$/i, ".pdf");
  return `${PDF_BASE_URL}${encodeURI(pdfPath)}?download=true`;
});

// 只有在文档页面才显示下载 PDF 按钮
const isDocPage = computed(
  () => (page.value.frontmatter?.layout ?? "doc") === "doc",
);
const shouldShow = computed(() => isDocPage.value && pdfUrl.value);

</script>

<template>
  <div class="CCPdfDownloadButton">
    <a
      v-if="shouldShow"
      class="CCPdfDownloadButtonBtn"
      :href="pdfUrl"
      target="_blank"
      rel="noopener"
    >
      下载 PDF
    </a>
  </div>
</template>

<style scoped>
.CCPdfDownloadButton {
  display: flex;
  align-items: center;
}

.CCPdfDownloadButtonBtn {
  padding: 8px 14px;
  border-radius: 999px;
  border: 1px solid var(--vp-c-divider);
  background: var(--vp-c-bg-soft);
  color: var(--vp-c-text-1);
  font-size: 14px;
  line-height: 1;
  transition:
    border-color 0.25s,
    background-color 0.25s,
    color 0.25s;
  cursor: pointer;
}

.CCPdfDownloadButtonBtn:hover {
  border-color: var(--vp-c-brand-1);
  background: var(--vp-c-bg-soft-hover);
  color: var(--vp-c-brand-1);
}
</style>

// .vitepress/theme/index.ts

import DefaultTheme from "vitepress/theme";
import type { App } from "vue";
import layout from "./layout.vue";
import "./custom.css";

import CCPdfDownloadButton from "./components/CCPdfDownloadButton.vue";

export default {
  extends: DefaultTheme,
  Layout: layout,
  enhanceApp({ app }: { app: App }) {
    app.component("CCPdfDownloadButton", CCPdfDownloadButton);
  },
};

另外导航栏这边的组件只能在桌面端显示，移动端是放在二级菜单里面，我个人是多处理了一个用插槽来实现移动端显示下载按钮

<script setup>
import DefaultTheme from "vitepress/theme";
import PdfDownloadButton from "./components/CCPdfDownloadButton.vue";

const { Layout } = DefaultTheme;
</script>

<template>
  <Layout>
    <!-- 只有在移动端显示该 PDF 下载按钮，桌面端的按钮在了导航栏里 -->
    <template #nav-bar-content-before>
      <div class="PdfDownloadButton">
        <PdfDownloadButton />
      </div>
    </template>
  </Layout>
</template>

<style scoped>
.PdfDownloadButton {
  display: none;
}

@media (max-width: 768px) {
  .PdfDownloadButton {
    display: block;
  }
}
</style>

到此，我们实现了

PDF 自动构建，实时更新
在 VitePress 站点提供下载链接

具体的实现可以看看原项目

在原文中查看交互内容

text-autospace： CJK 字符间距控制

Thu, 25 Dec 2025 00:17:00 GMT

Introduction

此功能可以用以实现中英文混排中的间距控制

text-autospace: normal;

使用：

:root {
  /* 启用自动混排间距 */
  text-autospace: normal;
}

/* 兼容性判断 */
@supports (text-autospace: normal) {
  :root {
    text-autospace: normal;
  }
}

其实这边的兼容性判断可以不用的，因为旧浏览器会自动忽略这个属性

Example

text-autospace: no-autospace;

text-autospace: normal;

normal：创建默认行为，自动在 CJK 字符与非 CJK 字符之间以及标点符号周围添加间距。此值的效果等同于同时应用 ideograph-alpha 和 ideograph-numeric。
no-autospace：禁用 CJK 和非 CJK 字符间的自动间距行为。
ideograph-alpha：仅在表意文字（如片假名和汉字）与非表意字母（如拉丁字母）之间添加间距。不会在表意文字与非表意数字之间添加间距。
ideograph-numeric仅在表意文字（如片假名和汉字）与非表意数字（如拉丁数字）之间添加间距。不会在表意文字与非表意字母之间添加间距。
punctuation根据特定语言的排版规范，在标点符号周围添加不可分割的间距。
insert仅当表意文字与非表意文字之间不存在现有空格时，才添加指定的间距。
replace将表意文字与非表意文字之间的现有间距（例如 U+0020）替换为指定的间距。
auto允许浏览器选择符合排版规范的间距。不同浏览器和平台间的间距可能存在差异。

或许你看着上面的 repalce 和insert 更好用，因为实际上不少人（特别是像我们这样的开发者）现在都已经习惯在中英文之间加上一个空格了（甚至微信输入法有这个自动加空格的功能），所以这个属性显然更友好（因为能同时兼顾不同书写风格群体）

但是！

挺遗憾的，目前为止（December 24, 2025），只有 Firefox 支持了insert ，而replace 目前就是 0 支持。

使用场景的一点想法？

其实主要并不知道是否是准确的，但是自己是这样想的：

在展示文本等等的大部分场景中，这个text-autospace: normal; 开起来确实是能提高整段话的顺眼程度，但是在编辑的场景中，我个人倒是认为这个不能开，因为会误判——「这边是不是误打个空格？」

不过这边也有一个可以说的，这个间距实际控制得很微妙，其实产生这个误判其实也不是很明显。比如你就回到刚刚上面的那个对比图，怎么说？

反正自己的东西也是放在，这种很稀碎的文章，我之后也放进来吧。并打上标签 TIL (Today I Learned)。

另，本次更新我也顺便把你现在看到的博客整体布局的 body 标签里加上了 text-autospace: normal;，所以你现在看到的博客正文也是开启了这个属性的。

我有特别的日程管理技巧

Thu, 20 Nov 2025 12:00:00 GMT

没有之一，日程管理永远是大学生活中最重要的技能之一。

或许如我刚进大学的时候，不做日程管理，或许也过得很好。要做什么，真就是用脑子想一想就能记住的。作业？截止前自然有人提醒；考试？考前一两周自然老师会反复强调。

但是，随着时间的推移，任务越来越繁重，单靠记忆已经远远不够了。甚至是经常遇到，今天突然告知我下个月要做啥事，这天才能想得起来）

而日程的管理，不仅仅解决的是“记住要做什么”的问题，更重要的是“合理安排任务”的问题。

最为基础的方式：使用日历

主包目前实际用的方式比较复杂了，在后面的章节里面，但是这个方式还是目前最推荐的，因为简单易行。也因此这边图片不多，主要是文字说明。

虽说是最简单的，但也是目前最实用的方式。

我更推荐就直接使用手机自带的日历应用，因为既然我们选择了这种方式，我们就要从简，不仅仅是初次配置的简化，更重要的是后续的使用简化。不能让日历的使用变成一件麻烦事，否则就失去了意义——你坚持不了多久。

日历的配置

我下面都以我自己的手机（小米家的 HyperOS 3）为例，来说说配置，这边仅供参考，其他手机的日历应用大同小异。

一个是创建多个日历（日程集，或者说是日程分类），我当时的方案是只有两个：「课程表」和「任务清单」。

课程表：我使用的是订阅的方式，比如福州大学的西二团队开发的福 uu 课程表，提供了日程订阅的功能，直接订阅就行了。这样就不需要手动添加上课时间了。

对于其他学校的同学，如果学校没有提供类似的课程表订阅功能，可以考虑自己手动录入，或者不在日历里面做这个日程分类，用你们自家的课程表 App 或是小程序还是 Wakeup 之类的来查看上课时间。我自己的这个主要是为了能在一个表里面看到包含课程表在内的所有日程，方便我去安排，而非日历看一下，自己的 App 看一下，这不优雅～

任务清单：则是我自己手动添加的，主要是把所有需要做的任务都添加进去。这里的任务包括作业、考试、活动、会议等等一切需要你去做的事情。事情可以无关大小，重要与否，甚至是提醒自己晚饭后要去拿个快递这种小事也可以添加进去。总之，凡是你需要记住的事情，都可以添加进去。

因为我们在这个阶段的设计目标是：

提醒自己要做什么事
自己要安排某一个事情的时候知道具体的时间有没有空

所以，这两个日历就足够了。

那我们该如何使用呢？

我们最重要的是保证你能把日程管理这个给坚持下来。所以，最重要的就是简单。我就是直接「小爱同学，提醒我明天早上 8:00-9:00 做下高级微积分的作业」，这样，这个日程便添加进来了。你也可以直接在日历 App 里面添加，反正就是简单快捷。

这边也可以给一些可以参考的日程提示（有哪些事情添加进去）：

赚德育分的任务，比如每天要我签到、让我每天拍个照
课程作业的截止时间
考试时间

再多一点：全平台同步的日历

比如我有多个设备，小米、华为、iPhone、Mac、Windows 电脑等等，这些设备上都需要查看日程，甚至或许有在 Google 日历上面使用的需求。我该如何做到呢？

这个时候，我们就需要一个全平台同步的日历服务了。可以考虑使用 Google 日历、Outlook 日历等服务，它们都提供了跨平台的支持，可以在不同设备上查看和管理日程。

这边并不是说你需要下载他们对应的 App，而是说你可以把你手机上面的日历和这些服务进行同步。这样，无论你在哪个设备上查看日程，都是一致的。

而我最推荐的是 iCloud 日历服务，尤其是对于苹果设备用户来说，iCloud 日历的集成度非常高，使用体验也非常好。还有一个好处是，iCloud 可以在任何网络环境下运行，这对于国内用户来说是一个很大的优势。

iCloud 日历的配置

得先有一个 Apple ID，如果没有的话，自己去注册一个
在 iCloud 上创建好自己的日历，至于日历里面的日历分类有哪些，请你参考上一节

但是我没有 Apple 设备怎么办？

iCloud 日历可以通过网页访问，所以你完全可以在 Windows 或者其他 Android 设备上使用 iCloud 日历。只需要在浏览器中登录你的 Apple ID，然后访问 iCloud.com，就可以使用日历功能了。

我们用苹果的 iCloud 日历服务，主要是因为它的稳定性和跨平台支持都非常好，而且在国内的访问速度也比较快。
生成「App 专用密码」

由于我们要在非苹果设备上使用 iCloud 日历，需要生成一个「App 专用密码」来进行登录。这个密码不同于你的 Apple ID 密码，专门用于第三方应用访问你的 iCloud 数据。类似于个人 token。

生成方法如下：
1. 登录你的 Apple ID 账户页面：https://appleid.apple.com/
2. 在「安全性」部分，找到「生成密码」选项
3. 按照提示生成一个新的「App 专用密码」并记住他，我们将在后续步骤中使用它。
在手机上添加 iCloud 账户

以小米手机的日历为例：
1. 打开「日历」应用
2. 右上角菜单进入「设置」页，再进入「日程账号管理」菜单
3. 点击底部的「导入账号」
4. 选择「Caldav 账号」
5. 填入以下信息：
  - 账号：你的 Apple ID 邮箱
  - 密码：刚刚生成的「App 专用密码」
  - 服务器地址：icloud.com

至此，你的手机日历就已经和 iCloud 日历同步了。你可以在手机上查看和管理你的日程，这些更改也会自动同步到 iCloud 上，使得所有订阅了该日历的设备都能看到最新的日程信息。

这边也不仅仅是手机，其他设备也是类似的配置方式，只要支持 Caldav 协议的日历应用，都可以通过类似的方式添加 iCloud 账户，实现日程同步，比如：Google 日历、Outlook 日历、Notion 日历、飞书等等。

最后一点，将任务管理工具放进来

这个较为繁杂，如果你觉得太复杂，可以忽略这一部分，单纯使用日历来管理你的日程也是完全可以的。甚至如果你是刚开始做这样的计划的同学，我更推荐你忽略这一部分，先从日历开始，为了你能坚持下来。

有必要吗？

如果我们把任务管理工具也放进来，那就更完美了。

有必要吗？我的想法是，有必要。我在日历中日程的管理，更多的是「时间」的管理，而任务管理工具更多的是「任务」的管理。两者结合起来，能够更好地帮助我们进行时间和任务的双重管理。

比如：

我将饭后取快递这种提醒类的任务放在手机的日历中
我将每天背单词、去做作业这种任务放在任务管理工具中

那我们该如何做呢？

如果你已经使用了一些任务管理工具，比如 Todoist、Microsoft To Do、TickTick 等等，这些工具大多也支持与日历同步。你可以将这些任务管理工具中的任务同步到你的日历中，这样就能在日历中看到所有的任务和日程，方便你进行整体的时间管理。

我这边用的是 TickTick 嘀嗒清单，这边可以生成一个嘀嗒的任务日历订阅链接，然后把这个链接添加到你的日历中，就能实现任务和日程的统一管理。

但是：你或许会将这个订阅在 iCloud，然后想着「由于我手机上面已经订阅了 iCloud 日历，所以我只要在 iCloud 上面添加这个订阅就行了」，但是实际上并不能这样做，虽然你手机上也正确显示出了对应的日程集，但是会发现有错误，有些任务是直接没有显示出来的。

正确做法是，在手机上（或是你需要展示任务日历的设备上）直接添加这个订阅链接，这样才能正确显示所有的任务。

这边的左图是不要把嘀嗒清单订阅添加到 iCloud 上面去（但是可以添加到 apple 设备的本地日历）

虽然我知道这不符合逻辑，但是我疑心觉得这是 iCloud 日历在解析订阅日程时出现的问题，所以只能这样做了。

所以

以上便是如此，最下面的方案便是我目前在使用的日程管理方案。目前看来还不错，能够满足我的需求。

（不过冤种的我买了嘀嗒清单的会员，因为实际上貌似这个会员可有可无）

当然，对于上面的最后一部分，如果你觉得太复杂，完全可以忽略这一部分，单纯使用日历来管理你的日程也是完全可以的。当然如果有更好的方案，也欢迎告诉我～

Surge.sh 预览配置

Sun, 19 Oct 2025 01:18:00 GMT

Surge.sh 是一个静态网站托管服务，开发者可以快速将静态网站部署上线，方便进行预览和分享。通过配置 Surge.sh 预览环境，可以在每次代码提交后自动生成预览链接，比如可以放在 Pull Request 中，极大地方便了团队协作和反馈。

本文来讲讲如何配置 Surge.sh 预览环境。

安装 Surge

npm install -g surge

surge --version

创建 Surge 账号

surge

命令执行后会提示：

Email：输入你的注册邮箱。
Password：第一次会创建账号。
Project path：默认就是当前目录。
Domain：你可以使用 .surge.sh 的免费子域名，例如 my-project.surge.sh

获取 Surge Token

surge token

配置 GitHub Actions

# .github/workflows/pr-preview.yml

name: Deploy PR Preview to Surge.sh

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  issues: write
  pull-requests: write

jobs:
  deploy-preview:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Bun # 自行根据项目需要更改
        uses: oven-sh/setup-bun@v1
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install

      - name: Build project
        run: bun run build

      - name: Install Surge CLI
        run: bun install -g surge

      - name: Deploy to Surge.sh
        run: surge --project ./dist --domain Loomi-Lair-HomePage-pr-${{ github.event.number }}.surge.sh
        env:
          SURGE_LOGIN: ${{ secrets.SURGE_LOGIN }}
          SURGE_TOKEN: ${{ secrets.SURGE_TOKEN }}

      - name: Comment PR with preview URL
        uses: peter-evans/create-or-update-comment@v3
        with:
          issue-number: ${{ github.event.number }}
          body: |
            Preview deployed: https://Loomi-Lair-HomePage-pr-${{ github.event.number }}.surge.sh

配置 GitHub Secrets

在你的 GitHub 仓库中，进入 Settings -> Secrets and variables -> Actions，添加以下 Secrets：

SURGE_LOGIN：你的 Surge 注册邮箱。
SURGE_TOKEN：你通过刚刚的 surge token 命令获取的 Surge Token。

完成以上配置后，每当有 Pull Request 创建或更新时，GitHub Actions 会自动构建项目并部署到 Surge.sh，然后在 Pull Request 中添加预览链接，方便团队成员查看和反馈。

Surge.sh 还有其他高级功能，比如自定义域名、SSL 证书等，可以根据需要进行配置（因为我还没有用到这些功能，懒了，不写了）

打印色彩与文件交付

Sun, 14 Sep 2025 20:00:00 GMT

本文主要面向非专业设计人员，比如只是在学校里面做做海报什么的，目标也只是普通的小文印店，而非专业的印刷厂。介绍打印色彩的基础知识以及文件交付的注意事项，帮助大家更好地理解打印色彩，避免或尽力减少在打印过程中出现色差等问题。

色彩基础

这部分不会太深入，主要介绍一些基础的色彩知识，帮助大家理解打印色彩。

sRGB

sRGB 是 1996 年由微软和惠普制定的一个标准色彩空间，最初是为了网络和普通显示器而设计的。几乎所有的手机、电脑、平板、网页浏览器默认使用 sRGB 作为显示标准。他是一种加色模型，主要通过红（Red）、绿（Green）、蓝（Blue）三种颜色的光线叠加来显示颜色。

CMYK

CMYK 是一种减色模型，主要用于印刷领域。CMYK 由下面四种颜色的油墨组合而成：

青（Cyan）
品红（Magenta）
黄（Yellow）
黑（Key）

通过叠加这四种颜色的油墨，可以生成各种颜色。与 RGB 不同，CMYK 是通过吸收光线来显示颜色的。因此在转换过程中可能会出现色差。

加色模型与减色模型

加色模型：通过叠加不同颜色的光来产生新的颜色。当三种颜色的光线以不同强度叠加时，可以产生各种颜色，最终叠加到白色光。
减色模型：通过吸收光线来产生新的颜色。在印刷过程中，油墨的叠加会吸收不同波长的光，从而生成各种颜色，最终叠加到黑色。

sRGB 是一种基于 RGB 模型的标准色彩空间，广泛用于显示器、相机、网页等数字设备。

屏幕上的每个像素由红、绿、蓝三个子像素组成。
当这些子像素发出不同强度的光并混合时，人眼感知到不同的颜色。
例如：
- 红光 + 绿光 = 黄光
- 红光 + 蓝光 = 品红光
- 绿光 + 蓝光 = 青光
- 红 + 绿 + 蓝（全开）= 白光
- 全关 = 黑色

CMYK 用于印刷，依赖纸张反射环境光来显色。

纸张本身是白色的，会反射所有可见光。
油墨的作用是吸收（减去）某些颜色的光，只反射我们看到的颜色。
- 青色油墨吸收红光，反射绿光和蓝光（合成青色）
- 品红油墨吸收绿光，反射红光和蓝光（合成品红）
- 黄色油墨吸收蓝光，反射红光和绿光（合成黄色）
当你叠印油墨时：
青 + 品红 = 吸收红和绿，只反射蓝 → 蓝色
青 + 黄 = 吸收红和蓝，只反射绿 → 绿色
品红 + 黄 = 吸收绿和蓝，只反射红 → 红色
青 + 品红 + 黄 = 理论上吸收所有光 → 黑色（但实际上呈深棕，所以加入 K——纯黑油墨）

色彩损失

所以，我们知道了在电脑屏幕上使用的是 RGB 色彩空间，而打印使用的是 CMYK 色彩空间。而 RGB 色彩空间的颜色范围要大于 CMYK 色彩空间的颜色范围。在将 RGB 颜色转换为 CMYK 颜色时，可能会出现色彩损失，导致打印效果与屏幕显示不一致。

下图展示了在 CIE 1931 xy 色度图中，sRGB 和 CMYK 色域的对比。可以看到，CMYK 色域明显小于 sRGB 色域：

图来源于维基百科

同时的，你也可以从图上很明显的看到，RGB → CMYK 的主要差别在鲜艳度和色域范围，典型情况是 鲜艳的蓝色、绿色、紫色、橙色，在这些颜色上，CMYK 都会比 sRGB 差很多。

下面展示一个个人的死亡案例

（CMYK 校准后的图片即模拟打印设备的打印效果）

笔者本人很大胆地使用了非常鲜艳的蓝色作为海报的主色调，直到设计完成后，才发现打印出来的效果和屏幕上差别巨大，蓝色变得非常暗淡，完全失去了原本的鲜艳感。

色彩空间选取

通过上面的描述，我们知道了 RGB 和 CMYK 的区别，以及在转换过程中可能会出现色彩损失。那么，在从设计到交付的全流程中，我们是否是要一直使用 CMYK 色彩空间呢？

我认为的答案是在设计阶段依然选择 sRGB

逻辑如下：

从文印店的实际情况触发

普通的文印店不可能提供 ICC Profile 给你。

ICC Profile

它描述了“某种设备/油墨/纸张下，CMYK 数字值对应的真实颜色”。

如果你用 ICC 转换 RGB → CMYK，就能更准确地模拟印刷效果。

文印店多数是数码打印机（激光/喷墨复印机），不是传统四色胶印。这些数码机内部往往有多色墨盒（CMYK+额外的浅青、浅洋红，甚至橙/绿，例如拓展的 CMYKcm等等），驱动会自动做色彩转换和优化。

如果你交 sRGB

打印机驱动会根据自身 ICC / 内部算法做转换，尽量保留饱和度和细节。
如果机器支持多色墨盒，可能比传统 CMYK 打出来的效果更好（比如蓝色会更亮，绿色会更正）。
相当于“把选择权交给打印机”，往往比你自己手动转 CMYK 更好，尤其是非专业的文印店。

如果你交 CMYK

你交的数值就固定了，打印机不会再帮你优化。
如果你用的是普通 CMYK（比如 ISO Coated v2），就等于人为先把颜色砍掉一部分，可能比直接交 sRGB 更差。
打印效果 → 蓝、绿、橙、紫更容易显得暗淡。

所以在最开始的设计阶段，依然建议使用 sRGB 色彩空间进行设计。当然，在设计过程中，也有一些额外的注意事项。

但是，在我看来有下面这种情况更适用于使用 CMYK

如果你一开始就明确自己追求打印出来的颜色效果尽可能接近设计稿，并且自己确定不会使用过于鲜艳的蓝色、绿色、紫色、橙色等 CMYK 没有覆盖的颜色，那么你也可以选择在设计阶段就使用 CMYK 色彩空间进行设计。

当然，如果是只用于在网络上展示的设计稿，那当然肯定是使用 sRGB 色彩空间。

设计阶段

如果使用 sRGB 色彩空间进行设计，建议注意以下几点：

尽量避免使用过于鲜艳的蓝色、绿色、紫色、橙色等颜色。
如果必须使用，建议在设计软件中开启 CMYK 预览功能，查看这些颜色在 CMYK 下的表现。

如果使用 CMYK 色彩空间进行设计

避免使用超出 CMYK 色域的颜色

（Photoshop 会提示当前选取的颜色是否超出 CMYK 色域）

犀牛鸟与瞬间

Thu, 11 Sep 2025 01:30:00 GMT

一个偶然的机会，从西二那边的 Open-Source-Application 了解到了腾讯的犀牛鸟，便也想参与其中。

倒不是只是知道这个活动，此前其实也有了解过 OSPP 以及 GSoC 之类的开源活动，只是太菜了，一眼看过去就觉得自己不行，没敢尝试。而犀牛鸟相比就友好得多了，甚至入门的介绍视频是教 Git 的使用的，这甚至是欢迎几乎零基础的同学吗？这倒让我去想着——或许我也行？

https://docs.qq.com/aio/DTk1wUUFHUkZCQkZN?p=kBrlITmKIZYap9DtpMNaox

就从大前端的三个里面选了一个 Cherry，比较一眼看过去有点水水的？，毕竟看下去全都是样式的改进

这不就是改改 CSS 吗？所在我之前有接触 Typora 的主题的制作（刚好也是 markdown 编辑器），看着项目也颇为熟悉。

于是很自然的选择了这个项目

从一封邮件开始说起

我看到这个项目的时候其实早在 6 月中旬我就看到了，而这个活动其实在 7 月 10 日才正式开始 issue 的占用和验收。

或许确实是有自己的私心吧，因为这个项目看的就是谁抢的快，做的快，因为项目本身确实是没有什么技术含量的，我确实是是会担心可能会有人比我更快上手。所以我自己就想着早点开始准备，早点开始做。自己确实是是在那时候就已经准备好几个 issue 的相关代码了，就等着提交。不过，或许这个也不够，因为不仅仅是速度可能有人更快，质量也或许更高，数量更多。

所以我自己就想着，我或许可以并不只局限于这几个 issue，而是可以尝试着去做更多的事情，更深度的参与这个项目，于是我自己在解决犀牛鸟 issue 的过程中，去看看这个项目有什么问题，有什么需要的地方。

我最后是选取了 Cherry 的变量系统来讲的，发现当时的 Cherry 的变量系统并不完善，甚至可以说是非常的混乱。

所以我给 Cherry 的导师 @sunsonliu 发了一封邮件，详细阐述了我的想法和建议，部分邮件内容如下

邮件原文 我在 6 月 23 日向导师发的邮件

项目理解

我自己学习了一下 Cherry-markdown 的相关的样式，有发现了主要有如下问题：

虽然我在 variable.css 中看到了基础的变量系统，但是其并不完整，以及大量实际使用中很多都仍然是硬编码

比如：

没有规定统一的圆角值，实际使用中部分组件有圆角，部分没有

以 box-shadow 为代表的变量系统虽有定义，但大部分的实际使用也都是硬编码（每次使用都是一个新的阴影），甚至部分地方增加了很多不必要的多层阴影

改进方案

建立更加丰富的设计标记系统：定义完整的圆角、阴影、间距等的系统

重构现有的硬编码样式，逐步替换当前的硬编码的样式

建立组件基础库，例如建立个 cherry-card、cherry-button 这样的，统一规定其圆角、阴影，也方便后续开发减少工作量

我自己有上述的想法，并也有对应的能力去实现，所以我想请问是否有这样的计划，我能够独立去做出来，但是也有些顾虑——一来是这个工作量确实有点多，而且很多文件的修改会容易打乱同时期提交人的 PR；其次是这个项目据我所知有应用到有商业化的腾讯文档等地方，我不清楚是否会收到影响

上述意见也终归来自于一个只有些许经验的学生，如有意见，也恳求批评指正。我自己看到这个项目，就有想要参与成为 contributor 成员的冲动，即便或许不是通过犀牛鸟项目去着手这个项目。

虽然我不方便在这边展示后续的导师回信内容，乃至之后的交流内容，我想说的是 沟通是非常重要的

不论是提早和导师沟通，还是在遇到问题时及时寻求帮助，都是非常必要的。通过他，我也得到了很多的帮助和指导，甚至在后续的 PR 评审中也得到了很多的建议。甚至专门开了我上面提到的对应的变量系统的改进的实战任务 Issue

Collaborator!

从上面这个变量系统重构的 PR 开始，作为一个贡献者，就直接一发不可收拾了，截止整个犀牛鸟的活动结束，我一共参与了 27 个 PR，如果论 Commit 的数量，应该是有将近 200 个了（Squash 前）

（这个是直接拿我最后项目报告里面的 PPT）

甚至比较惊喜的发现在 Openomy 的数据评估下，我的分数已经达到了该仓库的第四。

（这个图片我特意换成会更新的，看看我的排名有没有变化？）

当然，上面的这些都不及一封邮件来得更令我欢喜了几天

这是导师给我发的 Collaborate 邀请

也从那时候开始，我也正式成为开发组的一员了，是对我过去付出的最大的认可，远超我以往所经历的任何瞬间，在那时，开源的意义也变得更加深刻了——一位位前辈带着我去走向更高的山，或许不知什么时候，我也能成为带领他人的那一位。

尾声

更新于 11 月 19 日

结果也如我所愿，拿到了犀牛鸟全部的奖项，在我可预见的未来中，或许我会一直把这段经历放在简历的最前面，虽然具体的工作其实是蛮简单的，但是也或许是最亮眼最深刻的经历了

昨天也收到了腾讯那边发来的包裹（终于到了）

不过奖金怎么还没发，Qwq（因为我至今都不清楚我会拿到多少钱），看着这个 11 月能有吧？

上传照片（服务端）

Tue, 02 Sep 2025 08:05:00 GMT

同样源自于大一的大作业 Shotmeld 项目

在原文中查看交互内容

先把最终流程摆出来吧

sequenceDiagram
    autonumber
    title Shotmeld 照片上传与智能处理流程

    participant Client as 客户端<br>(Web / App)
    participant Server as 服务端<br>(主控协调)
    participant OSSUploader as OSS同步模块<br>(异步上传)
    participant EXIFProcessor as EXIF处理模块<br>(坐标+逆地理)
    participant AITagger as AI标签模块<br>(图像识别)
    participant AliyunOSS as 阿里云OSS<br>(原图存储)
    participant GaodeAPI as 高德API<br>(逆地理编码)
    participant ImageAI as 阿里云图像识别API<br>(智能打标)

    Client ->> Server: 1. 上传图片 (multipart/form-data)
    activate Server
    Server ->> Server: 2. 关联相册 + 生成缩略图<br>快速响应准备
    Server -->> Client: 3. 返回“上传成功”
    deactivate Server

    Note over Client,Server: 第3步返回的图片URL指向<strong>服务端本地存储</strong>，<br>由服务端直接提供文件访问，确保用户“秒级预览”

    par OSS 上传流程
        Server ->> OSSUploader: 4. 异步：上传原图至OSS
        activate OSSUploader
        OSSUploader ->> AliyunOSS: 5. 上传原始图片
        AliyunOSS -->> OSSUploader: 6. 返回OSS URL
        OSSUploader ->> Server: 7. 更新数据库：图片URL切换至OSS地址
        deactivate OSSUploader
    and EXIF 解析流程
        Server ->> EXIFProcessor: 8. 异步：解析EXIF元数据
        activate EXIFProcessor
        EXIFProcessor ->> EXIFProcessor: 9. 火星坐标 → WGS84<br>坐标纠偏
        EXIFProcessor ->> GaodeAPI: 10. 请求逆地理编码<br>经纬度 → 省市区街道
        GaodeAPI -->> EXIFProcessor: 11. 返回结构化地址
        EXIFProcessor ->> Server: 12. 更新地理标签与拍摄地点
        deactivate EXIFProcessor
    and AI 标签识别流程
        Server ->> AITagger: 13. 异步：图像内容识别
        activate AITagger
        AITagger ->> ImageAI: 14. 提交图片URL<br>物体/场景/OCR识别
        ImageAI -->> AITagger: 15. 返回标签列表<br>如：“猫, 窗户, 阳光”
        AITagger ->> Server: 16. 保存AI标签至数据库
        deactivate AITagger
    end

    Note over Server,AliyunOSS: 第7步完成后，<strong>所有图片访问切换至阿里云OSS</strong>，<br>服务端释放存储与带宽压力，实现“前端快响应，后端稳迁移”

    Note right of Server: 最终成果：<br>• 图片通过OSS访问<br>• 带地理位置<br>• 带AI智能标签<br>• 支持搜索与推荐

下面开始讲讲思考

上传流程设计思路

初版云端上传流程与初步优化

最初的上传流程非常简单：

客户端直接上传图片至服务器。

随着功能迭代，我们意识到首页展示多张图片时，不应直接使用原图，因此增加了缩略图步骤：

客户端上传图片至服务器。
服务器创建一张体积小于 100KB 的缩略图。
首页加载缩略图，点击后加载原图。

然而，这并未解决原图访问速度慢的根本问题。更重要的是，后期我们集成了更多图片处理功能，使得流程愈发复杂：

客户端上传图片至服务器。
处理图片与相册的关联。
创建缩略图。
解析图片 EXIF 信息（拍摄时间、光圈、快门速度等）。
对 EXIF 中的经纬度进行火星坐标系转换。
将转换后的经纬度提交至高德 API 进行逆地理编码。
将图片提交至阿里云图像识别 API 以获取标签。
将识别出的标签存入图片关联数据库。
向客户端返回上传成功的响应。

在这一系列同步操作下，处理单张图片的时间飙升至致命的 15 秒。相比之下，这些操作在本地环境中几乎是瞬时完成的。这揭示了一个在纯本地开发时难以预见的性能瓶颈，也促使我们着手解决。

引入阿里云 OSS：提升访问速度

为解决服务器带宽和存储的瓶颈，我们引入了阿里云对象存储（OSS）服务。OSS 的以下特性对我们的项目尤为关键：

海量存储（Massive Storage）：OSS 采用“桶（Bucket）”和“对象（Object）”的扁平结构，理论上容量无限，可按需自动扩展，无需预估硬盘空间。
高可靠性（High Reliability）：阿里云承诺极高的数据持久性（12 个 9），通过多副本冗余机制将数据分散存储于不同物理设备和可用区，有效防止单点故障。同时支持版本控制，防止意外删除或覆盖。

最重要的是，OSS 能够显著提升用户访问图片的速度。经过一番文档研读和在 AI 辅助下的集成，我们将所有文件存储逻辑迁移到了 OSS。

迁移后效果显著：常规 5MB 大小的图片，访问时间能控制在 0.5 秒以内。

OSS 迁移后的新挑战：上传速度恶化

尽管访问速度大幅提升，但上传流程变为：

客户端上传图片至服务器。
服务器将图片上传至 OSS。
处理图片与相册的关联。
创建缩略图。
解析图片 EXIF 信息。
经纬度火星坐标转换与逆地理编码。
阿里云图像识别 API 获取标签。
保存标签至数据库。
向客户端返回上传成功的响应。

不难想到的是，尽管用户访问图片能获得更好的体验，由于增加了服务器到 OSS 的中转环节，图片上传时间反而延长至 20 秒，情况变得更糟。

最终解决方案：异步处理优化

为彻底解决上传耗时问题，我们设计并实施了最终的异步处理工作流：

即时响应阶段（同步处理）：
1. 客户端上传文件至服务器
2. 服务器处理相册关联等即时性操作
3. 服务器快速生成缩略图
4. 服务器立即向客户端返回上传成功的响应（此时图片暂时由服务器承载，优先保障用户能第一时间查看和操作）。
后台异步处理阶段：
1. OSS 同步模块：
  1. 将原图和缩略图异步上传至 OSS
  2. 待 OSS 上传完成后，更新数据库中图片的 URL 指向 OSS
  3. EXIF 处理模块：
    1. 异步解析图片 EXIF 信息
    2. 进行经纬度火星坐标转换
    3. 调用高德 API 进行逆地理编码
    4. 将处理后的 EXIF 数据更新至数据库
2. AI 标签模块：
  1. 异步调用阿里云图像识别 API 获取图片标签
  2. 将获取的标签保存至数据库

通过上述优化，对于一张约 2MB 的普通图片，我们成功将上传时间控制在 2 秒以内，同时保持了查看速度在 0.3 秒以内的优异表现。

Appendix

地图坐标转换

我们在 Exif 解析的时候，想要根据 Exif 中的信息来得到一个结构化的地址（例如福建省福州市福州大学（旗山校区）这样的具体名称），而非仅仅是经纬度坐标。为此，我们需要引入高德 API 进行逆地理编码。

但是在这之前，需要知道的是：

中国大陆境内采用的都是 GCJ-02 坐标系（火星坐标系），而非 WGS-84 坐标系（GPS 坐标系）
图片 Exif 中存储的经纬度信息是 WGS-84 坐标系
高德 API 的逆地理编码只支持 GCJ-02 坐标系，因此我们需要将 WGS-84 坐标系转换为 GCJ-02 坐标系

我自己是直接使用高德 API 提供的坐标转换接口来完成的，当然也可以直接本地转换

https://lbs.amap.com/api/webservice/guide/api/convert

在原文中查看交互内容

/**
 * 将GPS（WGS84）坐标转换为高德（GCJ-02）坐标系并获取位置名称
 * @param {number} longitude - GPS经度
 * @param {number} latitude - GPS纬度
 * @returns {Promise<{longitude: number, latitude: number, name: string|null}>} - 包含高德坐标和位置名称的对象
 */
async function convertGPSToAMap(originalLongitude, originalLatitude) {
  try {
    // 验证输入坐标的有效性
    if (typeof originalLongitude !== 'number' || typeof originalLatitude !== 'number' ||
        isNaN(originalLongitude) || isNaN(originalLatitude)) {
      throw new Error('无效的坐标值');
    }

    // 确保有API Key
    if (!config.AMAP_KEY) {
      console.warn('未配置高德地图API Key，无法进行坐标转换和逆地理编码');
      return { longitude: originalLongitude, latitude: originalLatitude, name: null };
    }

    let amapLongitude = originalLongitude;
    let amapLatitude = originalLatitude;
    let locationName = null;

    // 1. 坐标转换 (WGS84 to GCJ-02)
    const convertUrl = `https://restapi.amap.com/v3/assistant/coordinate/convert?key=${config.AMAP_KEY}&locations=${originalLongitude},${originalLatitude}&coordsys=gps`;
    try {
      const convertResponse = await axios.get(convertUrl);
      if (convertResponse.data && convertResponse.data.status === '1' && convertResponse.data.locations) {
        const [lon, lat] = convertResponse.data.locations.split(',');
        amapLongitude = parseFloat(lon);
        amapLatitude = parseFloat(lat);
      } else {
        console.error('高德地图坐标转换API返回错误:', convertResponse.data);
      }
    } catch (convertError) {
      console.error('高德地图坐标转换失败:', convertError);
    }
    
    // 2. 逆地理编码获取位置名称 (使用转换后的或原始的高德坐标)
    const locationStringForRegeo = `${amapLongitude},${amapLatitude}`;
    const regeoUrl = `https://restapi.amap.com/v3/geocode/regeo?key=${config.AMAP_KEY}&location=${locationStringForRegeo}&extensions=base`;
    
    try {
        const regeoResponse = await axios.get(regeoUrl);
        if (regeoResponse.data && regeoResponse.data.status === '1' && regeoResponse.data.regeocode) {
          locationName = regeoResponse.data.regeocode.formatted_address;
        } else {
          console.error('高德地图逆地理编码API返回错误:', regeoResponse.data);
        }
    } catch (regeoError) {
        console.error('高德地图逆地理编码失败:', regeoError);
    }

    // 返回转换后的高德经纬度和获取到的位置名称
    return {
      longitude: amapLongitude,
      latitude: amapLatitude,
      name: locationName
    };

  } catch (error) {
    console.error('获取位置名称或坐标转换主流程失败:', error);
    return { longitude: originalLongitude, latitude: originalLatitude, name: null }; 
  }
}

极低成本的“自然语言图像检索”实现

Sun, 24 Aug 2025 15:00:00 GMT

该实现方式是我在完成校内大作业的时候想到的，并已经在实际项目中得到了应用。通过将自然语言处理与图像检索相结合，我们能够以极低的成本实现高效的图像搜索功能。

项目 Github 链接：

在原文中查看交互内容

目前常规的“文搜图”基础普遍依赖“向量搜索（Vector Search）”的方式实现，但是势必依赖较好的服务端资源，可惜我们这边当时并没有那么好的条件 QwQ，所以只能使用非常投机取巧灵活的方式去实现这个功能。

常规实现——向量搜索

当然，我们用的不是这个方法，我只是这边贴一下，方便顺便学习。不过这个也是最主流，效果更好的方法，如果不差钱，这个是最推荐的。不过我的方法也是在这上面延伸出来的。

就算是正常的“向量搜索（Vector Search）”也会把“文搜图”工作分成如下几步：

理解图片 (Image Understanding)

当将照片存入相册或图库时，AI模型（如深度学习中的卷积神经网络CNN或Vision Transformer）会自动分析每一张照片。

它会识别出照片中的各种元素，例如：
- 物体: 猫、狗、汽车、桌子、电脑
- 场景: 海滩、城市街道、森林、室内房间
- 动作: 跑步、微笑、吃饭、弹吉他
- 属性: 蓝色、圆形、大的、模糊的
然后，AI会将这些复杂的视觉信息转换成一个数学表示，称为 “图像嵌入” (Image Embedding) 或“特征向量”。这个向量可以被看作是这张照片在AI“大脑”中的一个独一无二的“语义坐标”。
理解文字 (Text Understanding):
- 当在搜索框中输入文字，比如“在海边奔跑的金色小狗”时，另一个AI模型（如BERT或CLIP的文本部分）会来处理这段文字。
- 它会分析这段话的语法和语义，理解其中的关键概念（海边、奔跑、金色、小狗）。
- 同样地，AI也会将这段文字转换成一个数学表示，称为 “文本嵌入” (Text Embedding)。
匹配和搜索 (Matching and Searching):
- 现在，AI有了代表您搜索词的“文本向量”和代表每一张照片的“图像向量”。
- 最关键的一步是，这些向量存在于同一个“多模态语义空间”中。在这个空间里，意思相近的文本和图片，它们的向量坐标也相近。
- 因此，系统只需要计算您的文本向量与图库中所有图像向量的“距离”，然后将距离最近、最匹配的那些照片作为搜索结果返回给您。

上面的就是向量搜索的方法，也是业内主流采用的方式

奇技淫巧

正题开始！

仿照上面的思路，我将“文搜图”的工作分成了两步：

图片转描述词
搜索词匹配描述词

图片转描述词这步其实蛮简单的，只要把它理解成“图片打标”，就有许多现成的 API 可以用，比如我当时用的阿里家的

https://help.aliyun.com/zh/viapi/developer-reference/api-t057e7

接下来一步就很神奇，我们从 api 那边拿到了每个图片的标签，我们该如何用这些标签去匹配用户的搜索词呢？当然，正常的方法是词向量匹配，但是由于相同的原因，所以我就想到了用 LLM 来做这个匹配。

（当时没有使用词向量的原因和上面差不多，但是当时傻，不知道有文本向量特化模型，下面我会说到）

流程如下

graph TB
    subgraph A ["照片索引阶段 (一次性处理) "]
        direction LR
        Photos([个人照片库]) --> API{{调用图像打标 API, 如: 阿里云}}
        API --> Tags[返回图片标签, 例如: '河流', '小船']
        Tags --> DB[(标签数据库)]
        Photos -- 路径/ID --> DB
    end

    A --> B

    subgraph B ["用户搜索阶段 (实时查询) "]
        direction TB
        UserInput([用户输入自然语言: '在河边的日落']) --> Prompt
        DB -- 提取所有可用标签 --> Prompt
        Prompt{{组合成 Prompt}} --> LLM[请求 LLM 匹配]
        LLM --> MatchedTags[LLM 返回最匹配的标签,例如: '河流', '日落']
        MatchedTags --> SearchDB{{查询标签数据库}}
        DB -- 被查询 --> SearchDB
        SearchDB --> Results[找到所有匹配的图片]
        Results --> Display([向用户展示结果])
    end

    %% ====== 样式美化 ======
    style A fill:#fff8dc,stroke:#333,stroke-width:1px,rx:10,ry:10
    style B fill:#e6f2ff,stroke:#333,stroke-width:1px,rx:10,ry:10
    style DB fill:#f9c,stroke:#333,stroke-width:2px
    style LLM fill:#bbf,stroke:#333,stroke-width:2px
    style UserInput fill:#eee,stroke:#666,rx:8,ry:8
    style Display fill:#eee,stroke:#666,rx:8,ry:8

流程很好解决，接下来就是一些细节的处理

信息设计

输入信息

标签库：JSON 格式的标签列表，例如

{"tags": ["旅行", "时尚", "化妆", "风景", "美食"]}

搜索查询：用户输入的搜索内容，例如：“旅行”。

输出要求

以 JSON 格式返回匹配标签列表，格式为：
```
{"matched_tags": ["标签1", "标签2", ...]}
```
规则：
- 输出必须为合法 JSON，仅包含 matched_tags 数组。
- 不能包含解释、注释或额外文本。
- 若无匹配标签，则返回 {"matched_tags": []}。

提示词设计

这边就需要我们去用心设计一个提示词，因为我们需要保证 LLM 稳定地返回我们所需的内容。当然也有一个大家熟知的技巧，用 LLM 来帮我们写提示词。

除了规定其输出规则外，我这边也给了其核心匹配原则：

相关性联想：匹配与搜索词在功能、场景或属性上紧密相关的事物。例如，搜索“学习”时，可以关联到“书籍”、“课程”、“考试”等标签。
场景化匹配：关键在于理解搜索词背后的场景和需求。举个关键例子：如果用户搜索“湖水”，你不仅要匹配“湖”，更需要智能地联想到相关的“河”、“江”、“溪”、“水”等，因为它们都属于“水体”这一核心概念。

确保 AI 能给我更好的匹配效果

提示词

角色与目标 (Role & Goal):
你是一位专精于概念关联与语义理解的智能标签匹配引擎。你的核心任务是深入分析用户的搜索意图，并从一个给定的标签库中，广泛地匹配出所有相关的标签。

核心匹配原则 (Core Matching Principles):
你的匹配不应局限于字面上的同义词，而必须扩展到更广泛的语义关联维度：

相关性联想 (Associative Relevance): 匹配与搜索词在功能、场景或属性上紧密相关的事物。例如，搜索“学习”时，可以关联到“书籍”、“课程”、“考试”等标签。
场景化匹配 (Contextual Matching): 关键在于理解搜索词背后的场景和需求。举个关键例子：如果用户搜索“湖水”，你不仅要匹配“湖”，更需要智能地联想到相关的“河”、“江”、“溪”、“水”等，因为它们都属于“水体”这一核心概念。

输入信息 (Input Information):

所有标签的 JSON 文件如下：
${JSON.stringify({ tags: allTags }, null, 2)}

用户的搜索内容是：
${searchQuery}

输出要求 (Output Requirements):

请根据上述原则，匹配出与搜索内容相关的所有标签，并仅以 JSON 格式返回匹配的标签列表。

返回格式示例：
{ "matched_tags": ["tag1", "tag2"] }

严格遵守以下规则 (Strict Rules):

只返回 JSON：绝对不要添加任何解释、注释或额外的文字。
结果必须是有效的 JSON 数组。
若无相关标签：返回一个包含空数组的 JSON 对象，即 {"matched_tags": []}。

API 请求示例

请求示例代码

import OpenAI from "openai";

const openai = new OpenAI({
apiKey: process.env.API_KEY,
baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
});

async function main() {
const tags = ["旅行", "时尚", "化妆", "风景", "美食"];
const searchQuery = "旅行";
const prompt = `
 角色与目标 (Role & Goal):
  你是一位专精于概念关联与语义理解的智能标签匹配引擎。你的核心任务是深入分析用户的搜索意图，并从一个给定的标签库中，广泛地匹配出所有相关的标签。

 核心匹配原则 (Core Matching Principles):
  你的匹配不应局限于字面上的同义词，而必须扩展到更广泛的语义关联维度：
      相关性联想 (Associative Relevance): 匹配与搜索词在功能、场景或属性上紧密相关的事物。例如，搜索“学习”时，可以关联到“书籍”、“课程”、“考试”等标签。
      场景化匹配 (Contextual Matching): 关键在于理解搜索词背后的场景和需求。举个关键例子：如果用户搜索“湖水”，你不仅要匹配“湖”，更需要智能地联想到相关的“河”、“江”、“溪”、“水”等，因为它们都属于“水体”这一核心概念。
 输入信息 (Input Information):
     所有标签的 JSON 文件如下：
      ${JSON.stringify({ tags: allTags }, null, 2)}

      用户的搜索内容是：
      ${searchQuery}

 输出要求 (Output Requirements):
  请根据上述原则，匹配出与搜索内容相关的所有标签，并仅以 JSON 格式返回匹配的标签列表。

 返回格式示例：
  { "matched_tags": ["tag1", "tag2"] }

 严格遵守以下规则 (Strict Rules):
  只返回 JSON：绝对不要添加任何解释、注释或额外的文字。
  结果必须是有效的 JSON 数组。
  若无相关标签：返回一个包含空数组的 JSON 对象，即 {"matched_tags": []}。
   `;

const completion = await openai.chat.completions.create({
  model: "qwen-turbo",
  messages: [
    { role: "system", content: "你是一个智能助手。" },
    { role: "user", content: prompt },
  ],
});

console.log(completion.choices[0].message.content);
}

main();

这边我采用的是 qwen-turbo 模型，主要看中其速度，十次平均 420ms。

我虽然当时采用的是 qwen-turbo ，而实际上我们完全可以使用“阿里通用文本向量-v4(text-embedding-v4)”这类特化模型，他们不是思考，而是纯粹的数学计算，延迟更低，效果更好，可惜当时傻，我有时间会去重新做这一块。

不过这样上面的 API 请求什么都不一样，可以参考

https://bailian.console.aliyun.com/?spm=a2c4g.11186623.0.0.3adc55efAtoAJ4&tab=doc#/doc/?type=model&url=2842587

评估

优点

成本极低，无论是图像打标还是 LLM 对话
实现简单
效果好：利用大语言模型做“语义理解”的中间层，比传统的关键词匹配要智能得多

缺点

搜索的粒度和深度有限
- 关系丢失: 图像打标API通常返回的是离散的、名词性的标签，它们之间没有关系。比如一张“一个男人在追逐一只狗”的照片，标签可能是["男人", "狗", "奔跑", "草地"]。无法通过这些标签搜索“谁在追谁”这种带有关系和动作主体的复杂场景。系统可以找到同时包含这些标签的照片，但无法理解它们之间的逻辑。
- 属性和细节丢失: 对于“穿红色裙子的女孩”这样的搜索，如果打标API只返回了["女孩", "裙子"]而没有“红色”这个属性，搜索就会失败。标签的质量完全决定了搜索结果的上限。
结果排序困难

这个方案本质上是“布尔搜索”（要么匹配，要么不匹配）。如果多个结果都匹配了AI返回的标签（例如，10张照片都有“河流”和“日落”的标签），很难判断哪一张是最匹配用户描述的。而真正的向量搜索可以根据向量距离进行排序，给出最相关的结果。

后日谈

上面的内容产出都是我在当时做那个项目的时候思考的，也实际使用了，你也可以去试试看效果

https://shotmeld.seeridia.top

已经停止运营

当然我上面也提到了，我当时并不知道阿里云那边也有专门的文本向量模型，我知道词向量，但是由于服务器拉了没法本地跑就没用了。

而结果是这个模型更便宜，效果更好，延迟更低 QwQ，确实是有点小伤心的，不过在这边也学到蛮多的，没办法，有时间去换一换吧，之后再更新这篇文章

从网站的上线开始讲起（二）

Fri, 22 Aug 2025 22:00:00 GMT

我就从域名 → DNS → CDN → ESA 这条链路开始看看一个网站的上线，特别是在国内的网络环境下，如何保证用户能够快速、稳定地访问。不过本篇只会有域名和DNS，后续会补上CDN（这部分太多了）。

本文的部分内容和供图来自阿里云的帮助文档

域名（Domain Name）

概念

域名就是互联网的“门牌号”，让人们可以用文字来访问网站，而不用记一长串 IP 地址。

举例：seeridia.top 其实只是一个名字，它背后最终会对应到服务器的 IP（例如 172.31.49.252 ）。

域名属于 ICANN 统一管理，注册商（阿里云、腾讯云、Namecheap 等）相当于“代理商”。

关键知识点

域名层级
- 顶级域名（TLD）： .com, .cn, .top 等
- 二级域名：seeridia.top
- 子域名：api.seeridia.top, cdn.seeridia.top
注意：每一级域名都可以单独做解析配置。
域名注册与所有权

注册域名后，获得一定年限的使用权。必须定期续费，否则可能被别人抢注。
域名系统依赖 DNS

域名本身只是名字，必须依赖 DNS（域名系统）才能解析成 IP 地址，否则浏览器没法访问。

DNS（Domain Name System）

作用：把人类可读的域名（seeridia.top）转换成计算机可用的 IP 地址（172.31.49.252）

类比：就像电话簿，把“张三的名字”查成“张三的电话号码”

位置：DNS 位于整个访问链路的最开始，用户输入网址时，浏览器必须先通过 DNS 得到 IP 才能发起请求

解析流程

用户在Web浏览器中输入 example.com ，向本地域名服务器发起查询请求。若本地域名服务器存在缓存的解析数据，则直接将域名对应的IP地址返回给Web浏览器，跳至步骤9。若本地域名服务器没有查到缓存的解析数据，则继续步骤2。
本地域名服务器向根域名服务器进行查询。
根域名服务器将 .com 顶级域名服务器的地址，返回给本地域名服务器。
本地域名服务器向 .com 顶级域名服务器发起 example.com 的查询请求。
.com 顶级域名服务器将为 example.com 提供权威解析的权威域名服务器地址，返回给本地域名服务器。
本地域名服务器向权威域名服务器发起查询请求。
权威域名服务器将域名 example.com 对应的 IP 地址，返回给本地域名服务器。
本地域名服务器最后把查询的 IP 地址响应给 Web 浏览器。
Web 浏览器通过 IP 地址访问网站服务器。
网站服务器返回网页信息。

记录类型

类型	作用	示例	使用场景
A	把域名解析到 IPv4 地址	`seeridia.top → 203.0.113.10`	网站直连服务器，最常见的解析方式
AAAA	把域名解析到 IPv6 地址	`seeridia.top → 2400:3200::1`	网站支持 IPv6 访问
CNAME	把域名解析到另一个域名（别名）	`www.seeridia.top → seeridia.top` `cdn.seeridia.top → cdn.edgeone.com`	CDN/ESA 接入、统一指向一个目标域名
MX	指定邮件服务器	`seeridia.top → mail.seeridia.top （优先级 10）`	Gmail/Outlook 企业邮箱，自建邮箱
TXT	存放文本信息（验证/策略）	`seeridia.top TXT "v=spf1 include:_spf.google.com ~all"`	域名验证、邮件安全（SPF/DKIM/DMARC）
NS	指定权威 DNS 服务器	`seeridia.top → ns1.dnsprovider.com`	决定谁负责解析该域名（域名商 / DNS 服务商），一般用于将子域名交给其他 DNS 服务商解析

另外，还有一些其他类型的记录，如 SRV（服务定位）、PTR（反向解析）、CAA（签发证书）等，但不常用。

CNAME 与重定向并不同

CNAME 其实是说：这个域名其实是另一个域名的别名

对比项 CNAME 记录 HTTP 重定向 (301/302)

发生位置 DNS 层（浏览器还没发请求） HTTP 层（浏览器已经访问服务器）

返回内容返回另一个域名，继续解析 IP 返回新的 URL，让浏览器重新请求

用户是否可见对用户不可见，用户输入的域名不变用户地址栏会跳转到新的 URL

使用目的域名别名、接入 CDN、统一解析网站迁移、SEO、内容跳转

对比项	CNAME 记录	HTTP 重定向 (301/302)
发生位置	DNS 层（浏览器还没发请求）	HTTP 层（浏览器已经访问服务器）
返回内容	返回另一个域名，继续解析 IP	返回新的 URL，让浏览器重新请求
用户是否可见	对用户不可见，用户输入的域名不变	用户地址栏会跳转到新的 URL
使用目的	域名别名、接入 CDN、统一解析	网站迁移、SEO、内容跳转

Github Actions 自动化发布

Sun, 17 Aug 2025 12:00:00 GMT

我以下面这个 Tauri 应用为例，记录如何 Github Actions 实现自动化发布

在原文中查看交互内容

我分成两部分，一个是每次 Commit 都自动构建应用，另一个是每次发布 Release 时自动打包应用。

推送构建

只要在主分支有代码提交，或发起 Pull Request，就会触发构建，产物放在 Actions 的 Artifacts 中

# .github/workflows/build-test.yml

name: Build and Test

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    strategy:
      fail-fast: false
      matrix:
        platform: [macos-latest, ubuntu-latest, windows-latest]

    runs-on: ${{ matrix.platform }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Setup Rust
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: stable

      - name: Install Linux dependencies
        if: runner.os == 'Linux'
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            build-essential \
            curl \
            wget \
            file \
            libssl-dev \
            libgtk-3-dev \
            libwebkit2gtk-4.1-dev \
            libayatana-appindicator3-dev \
            librsvg2-dev

      - name: Install frontend dependencies
        run: npm install

      - name: Build Tauri application
        uses: tauri-apps/tauri-action@v0.5.22

      - name: Prepare artifact details
        id: prepare_artifact
        shell: bash
        run: |
          ARCH=$(echo "${{ runner.arch }}" | tr '[:upper:]' '[:lower:]')
          ARTIFACT_PATH=""
          ARTIFACT_NAME=""

          if [ "${{ runner.os }}" == "macOS" ]; then
            ARTIFACT_PATH=$(find src-tauri/target/release/bundle/dmg -name "*.dmg" -print -quit)
            ARTIFACT_NAME="clipboard-viewer-latest-mac-${ARCH}.dmg"
          elif [ "${{ runner.os }}" == "Windows" ]; then
            ARTIFACT_PATH=$(find src-tauri/target/release/bundle/msi -name "*.msi" -print -quit)
            ARTIFACT_NAME="clipboard-viewer-latest-win-${ARCH}.msi"
          elif [ "${{ runner.os }}" == "Linux" ]; then
            ARTIFACT_PATH=$(find src-tauri/target/release/bundle/appimage -name "*.AppImage" -print -quit)
            ARTIFACT_NAME="clipboard-viewer-latest-linux-${ARCH}.AppImage"
          fi
          
          echo "Found artifact at: ${ARTIFACT_PATH}"
          echo "New artifact name: ${ARTIFACT_NAME}"
          echo "path=${ARTIFACT_PATH}" >> $GITHUB_OUTPUT
          echo "name=${ARTIFACT_NAME}" >> $GITHUB_OUTPUT

      - name: Upload Build Artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ steps.prepare_artifact.outputs.name }}
          path: ${{ steps.prepare_artifact.outputs.path }}

发布构建

在推送 Release Tag 时，会自动触发构建并发布应用

# .github/workflows/release.yml

name: Create GitHub Release

on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+*'

permissions:
  contents: write
  actions: read

jobs:
  publish-release:
    strategy:
      fail-fast: false
      matrix:
        platform: [macos-latest, ubuntu-latest, windows-latest]

    runs-on: ${{ matrix.platform }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '18'
          cache: 'npm'

      - name: Setup Rust
        uses: actions-rust-lang/setup-rust-toolchain@v1
        with:
          toolchain: stable

      - name: Install Linux dependencies
        if: runner.os == 'Linux'
        run: |
          sudo apt-get update
          sudo apt-get install -y \
            build-essential \
            curl \
            wget \
            file \
            libssl-dev \
            libgtk-3-dev \
            libwebkit2gtk-4.1-dev \
            libayatana-appindicator3-dev \
            librsvg2-dev

      - name: Install frontend dependencies
        run: npm install

      - name: Build and publish release
        uses: tauri-apps/tauri-action@v0.5.22
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        with:
          tagName: ${{ github.ref_name }}
          releaseName: 'App Version ${{ github.ref_name }}'
          releaseBody: 'See the assets to download this version.'
          releaseDraft: false
          prerelease: false

注意

无需配置 GITHUB_TOKEN 等，Github Actions 会自动提供。
需要在 Settings > Actions > General > Workflow permissions 中，选择 "Read and write permissions"

AstrBot + NapCat 下的 QQBot

Sat, 16 Aug 2025 15:00:00 GMT

先贴出文档

得益于 AstrBot 和 NapCat 的强大功能，QQBot 的接入确实是非常方便了

NapCat 配置

安装 NapCat

在 Linux 下可以直接使用官方的一键支持脚本
```
 curl -o \
 napcat.sh \
 https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh \
 && sudo bash napcat.sh \
 --tui
```
按照指示安装即可，唯一要注意的是在 napcat 的日志里会显示 WebUI 链接，一般端口是 6099

启动

 # 启动 Napcat (需要图形环境或 Xvfb)
 sudo xvfb-run -a qq --no-sandbox


 # 后台启动 (使用 screen) (请使用 root 账户)
 #   启动
 screen -dmS napcat bash -c "xvfb-run -a qq --no-sandbox"

 #   带账号启动
 screen -dmS napcat bash -c "xvfb-run -a qq --no-sandbox -q QQ号码"

 #   附加到会话
 screen -r napcat

 #   停止会话
 screen -S napcat -X quit

配置
1. 添加网络配置
2. 如图配置

至此我们已经完成了 NapCat 的配置

AstrBot 配置

这边我直接在 1Panel 部署 AstrBot，因为其已经上架了 1Panel 的应用市场。

开放 6158 端口后，我们直接进到 Web UI 进行配置

在 消息平台 > 新增适配器 中选择 接入 QQ 个人号(aiocqhttp)，按照下图配置即可

至此，我们已经完成了所有的配置，接下来可以在 AstrBot 的 Web UI 中进行测试和使用。

这边附加一下，由于 Google 的相关 api 的免费额度很大，但是在国内服务器可能无法正常访问，这边有一个临时可用的反代：https://dynamic-halva-76bb38.netlify.app/，可以直接代替原本的 API Base URL。

可使用 gemma-3-27b-it，每天免费 14400 次。

毛玻璃文字

Fri, 15 Aug 2025 23:00:00 GMT

主要矛盾很早就开始了，我想给文字本身的颜色实现类似于 backdrop-filter 的毛玻璃效果，但这个效果在文字上并不能直接使用。（可恶）

后续也问了蛮多认识的佬，大多都是改变透明度、混色方式等等去实现貌似是这样的效果，但都不是我想要的。

最终想起了 stackoverflow ，还提了一个问题（虽然最后被指出是问题重复，有人已经提过了，但是根本搜不到好不好 QwQ）

这边先贴个链接：

StackOverflow 讨论链接

也先贴上解决方案：（在 stackoverflow 的基础上进行了改进）

<img src="https://picsum.photos/id/99/500/300">
<img class="clipped" src="https://picsum.photos/id/99/500/300">

<svg height="0" width="0">
    <defs>
        <clipPath id="svgTextPath">
            <text x="50" y="200" textLength="400px" font-family="Vollkorn" font-size="200px" font-weight="700"> Text </text>
        </clipPath>
    </defs>
</svg>

body {
  margin 10px;
}

.clipped {
  position: absolute;
  top: 10px;
  left: 10px;
  clip-path: url(#svgTextPath);
  filter: blur(10px) brightness(1.2); // 调节模糊和亮度
}

是不是，超级无敌好的效果！

本帖就先这样放着，后续我可能会继续完善这个效果。

从网站的上线开始讲起（一）

Fri, 15 Aug 2025 22:00:00 GMT

虽然标题叫做「从网站的上线开始讲起」，，但其实并不是或许你想象中的个人故事，毕竟我还啥都不会，也没什么经历和故事，所以，这章真的是——网站的上线

本文主要涉及的是一个个人的上线工作流，包含 CI、CD 等等

Vercel

太过于美妙的前端部署平台，支持 Next.js、React 等几乎所有的框架。在 Vercel 中添加 Github 仓库，Vercel 会自动识别项目类型并进行构建。随后就可以直接设置相关的域名和环境变量等。比如你现在面前所看到的网站就是用 Vercel 部署的

总结一下优缺点：

优点：
- 简单易用：只需将代码推送到 GitHub，Vercel 会自动构建和部署
- 支持多种框架：兼容 Next.js、React 等主流框架
- 自动化：内置 CI/CD 流程，无需手动配置
- Free!
缺点：
- 访问速度慢：在国内访问速度较慢，尤其是在某些地区（特别指出我所在的福建）

其实这一个缺点就足够致命了，尤其是对于需要频繁访问的项目，我对于重要的项目还是会选择部署在国内的服务器上。日后也会把这个博客放过去，目前在 Vercel 上的博客只是一个过渡。

Github Actions + 服务器部署

这个就麻烦多了

第一步：SSH 密钥

这个生成一次就好，之后就都用这个

1. 生成 SSH 密钥对

ssh-keygen -t rsa -b 4096 -C "github_actions_deploy_key"

接下来可以一直按回车，密钥会保存在默认位置 ~/.ssh/id_rsa 和 ~/.ssh/id_rsa.pub。

id_rsa：私钥 (Private Key)，这个绝对不能泄露
id_rsa.pub：公钥 (Public Key)，这个是用来配置在服务器上的

2. 授权公钥

将生成的公钥 id_rsa.pub 内容添加到服务器的 ~/.ssh/authorized_keys 文件中。

# 将公钥内容追加到 authorized_keys 文件中
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

# 确保文件权限正确，否则 SSH 服务会拒绝连接
chmod 600 ~/.ssh/authorized_keys

3. 获取私钥

cat ~/.ssh/id_rsa

完整地复制终端输出的所有内容，包括 -----BEGIN RSA PRIVATE KEY----- 和 -----END RSA PRIVATE KEY----- 这两行。

这个就是服务器私钥。

第二步：服务器配置

我最早都是用的 Nginx 来部署静态网站，但是发现网站很多的时候，Nginx 的配置就会变得非常复杂，所以现在直接用 1Panel 来管理服务器（其实是我不会，每次都叫 AI，确实有点麻烦了）

使用 1Panel 来管理网站、证书什么的，那叫一个舒适啊，这边点几下就成。

这边要注意一下这边的目录：/opt/1panel/www/sites/example.seeridia.top/index，我们待会配置 Github Actions 的时候要用到。

第三步：Github Actions

# .github/workflows/deploy.yml

# 工作流名称
name: Deploy to Production Server

# 触发条件：当有代码推送到 main 分支时
on:
  push:
    branches:
      - main

# 工作任务
jobs:
  build-and-deploy:
    # 运行环境：使用最新的 Ubuntu
    runs-on: ubuntu-latest

    steps:
      # 第一步：迁出代码
      - name: Checkout Code
        uses: actions/checkout@v4

      # 第二步：设置 Node.js 环境
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          # 使用与你服务器上相同的 Node.js 版本
          node-version: '22'

      # 第三步：安装依赖
      - name: Install Dependencies
        run: npm install 

      # 第四步：打包项目
      - name: Build Project
        run: npm run build

      # 第五步：部署到服务器
      - name: Deploy to Server
        uses: appleboy/scp-action@v1.0.0
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          source: "dist/*"
          target: ${{ secrets.TARGET_DIR }}
          strip_components: 1

# .github/workflows/deploy.yml

# 工作流名称
name: Deploy to Production Server

# 触发条件：当有代码推送到 main 分支时
on:
  push:
    branches:
      - main

# 工作任务
jobs:
  build-and-deploy:
    # 运行环境：使用最新的 Ubuntu
    runs-on: ubuntu-latest

    steps:
      # 第一步：迁出代码
      - name: Checkout Code
        uses: actions/checkout@v4

      # 第二步：设置 Node.js 环境
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          # 使用与你服务器上相同的 Node.js 版本
          node-version: '22'
          cache: 'yarn'

      # 第三步：安装依赖
      - name: Install Dependencies
        run: yarn install

      # 第四步：打包项目
      - name: Build Project
        run: yarn build

      # 第五步：部署到服务器
      - name: Deploy to Server
        uses: appleboy/scp-action@v1.0.0
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          source: "dist/*"
          target: ${{ secrets.TARGET_DIR }}
          strip_components: 1

同时我们需要在 Github 仓库的 Secrets 中添加以下变量：

SERVER_HOST：服务器的 IP 地址
SERVER_USER：服务器的用户名
SSH_PRIVATE_KEY：服务器的 SSH 私钥（刚刚获取的那个）
TARGET_DIR：服务器上部署的目标目录

OK，就这样，非常轻松的，Github Actions 会在每次代码推送到 main 分支时自动触发，执行上述步骤，将代码打包并部署到服务器上。