<?xml version="1.0" encoding="UTF-8"?><?xml-stylesheet href="/rss/feed.xsl" type="text/xsl"?><rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>余弦の博客</title><description>WA 的一声就哭了</description><link>https://koharu.cosine.ren</link><item><title>周刊 Vol.3：给摘要接上模型，再补一套自检</title><link>https://koharu.cosine.ren/post/weekly-vol-3</link><guid isPermaLink="false">weekly-vol-3</guid><description>本周做了两件让维护更省心的事：让文章摘要由模型生成，以及给部署加一套自检。
摘要接入
主题本身带摘要生成脚本，但接口地址是写死的本地服务。改成读环境变量之后，换成任何 OpenAI 兼容服务都能用。
实际跑下来，单篇成本可以忽略：正文截断到 6000 字符，输出限制 200</description><pubDate>Wed, 18 Nov 2026 15:00:00 GMT</pubDate><content:encoded>&lt;p&gt;本周做了两件让维护更省心的事：让文章摘要由模型生成，以及给部署加一套自检。&lt;/p&gt;
&lt;h2&gt;摘要接入&lt;a href=&quot;#摘要接入&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;主题本身带摘要生成脚本，但接口地址是写死的本地服务。改成读环境变量之后，换成任何 OpenAI 兼容服务都能用。&lt;/p&gt;
&lt;p&gt;实际跑下来，单篇成本可以忽略：正文截断到 6000 字符，输出限制 200 token，几十篇加起来不到一块钱。缓存按「内容哈希 + 模型名」校验，所以只有改动过的文章才会重新调用。&lt;/p&gt;
&lt;p&gt;一个容易踩的点：摘要面板原本优先显示手写 &lt;code&gt;description&lt;/code&gt;，模型生成的结果永远用不上。调整成 AI 优先之后，&lt;code&gt;description&lt;/code&gt; 仍然用于列表卡片和 SEO，分工反而更清楚。&lt;/p&gt;
&lt;h2&gt;自检脚本&lt;a href=&quot;#自检脚本&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;之前判断「部署是否完好」全靠手动 curl 和看日志。现在写成一个脚本，检查 12 项：5 个本地补丁是否在位、摘要数据、构建产物、服务状态与首页响应。&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;./verify.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;全绿返回 0，有异常时直接给出对应修复命令。升级流程最后一步会自动跑它，失败就打印回滚命令。&lt;/p&gt;
&lt;h2&gt;一点体会&lt;a href=&quot;#一点体会&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;维护成本往往不在于「做」，而在于「确认没坏」。把确认这件事自动化，比再写十个功能更有价值。&lt;/p&gt;
&lt;h2&gt;下周待办&lt;a href=&quot;#下周待办&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;观察一周内存曲线，确认 Caddy 常驻的低占用是否稳定&lt;/li&gt;
&lt;li&gt;清理构建时残留的临时日志&lt;/li&gt;
&lt;/ul&gt;</content:encoded><category>category:周刊</category><category>tag:周刊</category><category>tag:AI</category><category>tag:运维</category></item><item><title>文章修改与置顶指南</title><link>https://koharu.cosine.ren/post/post-edit-guide</link><guid isPermaLink="false">post-edit-guide</guid><description>记录这篇文章站上修改已有文章的三种方式、需要重跑哪些步骤，以及置顶与草稿的设置方法。
一、三种修改方式
方式一：CMS 后台（推荐）
ssh fnOS@192.168.8.169
cd /vol1/www/astro-koharu
pnpm cms
浏览器打开</description><pubDate>Wed, 18 Nov 2026 12:15:00 GMT</pubDate><content:encoded>&lt;p&gt;记录这篇文章站上修改已有文章的三种方式、需要重跑哪些步骤，以及置顶与草稿的设置方法。&lt;/p&gt;
&lt;h2&gt;一、三种修改方式&lt;a href=&quot;#一三种修改方式&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;h3&gt;方式一：CMS 后台（推荐）&lt;a href=&quot;#方式一cms-后台推荐&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;ssh&lt;/span&gt;&lt;span&gt; fnOS@192.168.8.169&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;pnpm&lt;/span&gt;&lt;span&gt; cms&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;浏览器打开 &lt;a href=&quot;http://192.168.8.169:4322&quot;&gt;http://192.168.8.169:4322&lt;/a&gt; ，左侧列出全部文章，点开即可编辑。保存后回到终端按 &lt;code&gt;Ctrl+C&lt;/code&gt; 停掉服务，再执行构建。&lt;/p&gt;
&lt;p&gt;适合：一次要改多篇、或者不熟悉 Markdown 语法。&lt;/p&gt;
&lt;h3&gt;方式二：SSH 直接编辑&lt;a href=&quot;#方式二ssh-直接编辑&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;ssh&lt;/span&gt;&lt;span&gt; fnOS@192.168.8.169&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 查看全部文章&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;find&lt;/span&gt;&lt;span&gt; src/content/blog&lt;/span&gt;&lt;span&gt; -name&lt;/span&gt;&lt;span&gt; &apos;*.md&apos;&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 编辑&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;nano&lt;/span&gt;&lt;span&gt; src/content/blog/note/blog-ops-guide.md&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;适合：只改一两句话，不想启动服务。&lt;/p&gt;
&lt;h3&gt;方式三：本地编辑后上传&lt;a href=&quot;#方式三本地编辑后上传&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;# 取下来&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;scp fnOS@192.168.8.169:&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;vol1&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;www&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;astro&lt;/span&gt;&lt;span&gt;-&lt;/span&gt;&lt;span&gt;koharu&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;src&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;content&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;blog&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;note&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;blog&lt;/span&gt;&lt;span&gt;-&lt;/span&gt;&lt;span&gt;ops&lt;/span&gt;&lt;span&gt;-&lt;/span&gt;&lt;span&gt;guide.md .\&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 用你习惯的编辑器改完后传回去&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;scp blog&lt;/span&gt;&lt;span&gt;-&lt;/span&gt;&lt;span&gt;ops&lt;/span&gt;&lt;span&gt;-&lt;/span&gt;&lt;span&gt;guide.md fnOS@192.168.8.169:&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;vol1&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;www&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;astro&lt;/span&gt;&lt;span&gt;-&lt;/span&gt;&lt;span&gt;koharu&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;src&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;content&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;blog&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;span&gt;note&lt;/span&gt;&lt;span&gt;/&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;适合：需要长时间编辑、或想用 IDE 的语法高亮与预览。&lt;/p&gt;
&lt;h2&gt;二、改完必须重新构建&lt;a href=&quot;#二改完必须重新构建&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;静态站点不会自动感知文件变化，必须重新构建才会更新到线上：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./build.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;约 2–3 分钟（图片缓存命中时）。构建完成后 8080 立即生效，不需要重启 Caddy。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;重要&lt;/strong&gt;：改的是 &lt;code&gt;src/content/blog/&lt;/code&gt; 下的源文件，不要改 &lt;code&gt;dist/&lt;/code&gt;。&lt;code&gt;dist/&lt;/code&gt; 每次构建都会被整体覆盖。&lt;/p&gt;
&lt;h2&gt;三、摘要要不要重新生成&lt;a href=&quot;#三摘要要不要重新生成&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;文章页顶部的摘要来自 &lt;code&gt;src/assets/summaries.json&lt;/code&gt;，按「内容哈希 + 模型名」缓存。改了正文或标题，哈希就变了，需要重跑：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;./generate-summaries.sh&lt;/span&gt;&lt;span&gt;    # 只处理内容变过的，几秒到十几秒&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./build.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;两条连着跑，合计约 3 分钟。如果只改了排版、不关心摘要是否同步，可以跳过第一步。&lt;/p&gt;
&lt;h2&gt;四、frontmatter 字段改动的影响&lt;a href=&quot;#四frontmatter-字段改动的影响&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;

















































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;字段&lt;/th&gt;&lt;th&gt;改了会怎样&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;title&lt;/code&gt;&lt;/td&gt;&lt;td&gt;标题、SEO、摘要标题同步变化&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;date&lt;/code&gt;&lt;/td&gt;&lt;td&gt;排序、归档日期、首页时间线变化&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;tags&lt;/code&gt; / &lt;code&gt;categories&lt;/code&gt;&lt;/td&gt;&lt;td&gt;标签页、分类页归属变化；周刊分类决定是否进 &lt;code&gt;/weekly/&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;link&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;strong&gt;URL 会变，旧链接失效&lt;/strong&gt;，慎改&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;description&lt;/code&gt;&lt;/td&gt;&lt;td&gt;只影响 SEO meta 与列表卡片，摘要面板仍优先用 AI 结果&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;cover&lt;/code&gt;&lt;/td&gt;&lt;td&gt;文章封面图&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;catalog&lt;/code&gt;&lt;/td&gt;&lt;td&gt;是否计入分类页的分类树与篇数&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;sticky&lt;/code&gt;&lt;/td&gt;&lt;td&gt;是否置顶到首页独立区域&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;draft&lt;/code&gt;&lt;/td&gt;&lt;td&gt;草稿，生产构建时自动过滤&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;excludeFromSummary&lt;/code&gt;&lt;/td&gt;&lt;td&gt;排除出 AI 摘要与相似度计算&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2&gt;五、置顶文章&lt;a href=&quot;#五置顶文章&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;在 frontmatter 里加一行：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;---&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;title&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; 重要公告&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;sticky&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; true&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;---&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;具体行为：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;首页多出一个「置顶文章」独立区域，置顶内容显示在最上方&lt;/li&gt;
&lt;li&gt;置顶文章之间按日期排序，最新的在前&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;不影响&lt;/strong&gt;分类页、标签页、归档页的排序&lt;/li&gt;
&lt;li&gt;多篇可以同时置顶&lt;/li&gt;
&lt;li&gt;取消置顶：改成 &lt;code&gt;sticky: false&lt;/code&gt; 或删掉这一行&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;完整示例：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;---&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;title&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; 站点迁移公告&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;link&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; site-migration&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;catalog&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; true&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;date&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; 2026-11-18 20:00:00&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;sticky&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; true&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;cover&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; /img/cover/2.webp&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;tags&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  -&lt;/span&gt;&lt;span&gt; 公告&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;categories&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  -&lt;/span&gt;&lt;span&gt; 随笔&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;---&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;改完同样需要 &lt;code&gt;./build.sh&lt;/code&gt;。&lt;/p&gt;
&lt;h2&gt;六、草稿&lt;a href=&quot;#六草稿&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;写一半不想发布时，加：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;draft&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; true&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;pnpm dev&lt;/code&gt; 预览时可见，卡片右上角显示 &lt;code&gt;DRAFT&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;&lt;code&gt;pnpm build&lt;/code&gt; 生产构建时自动过滤，不出现在任何列表与页面&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;七、改完如何确认&lt;a href=&quot;#七改完如何确认&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;# 构建有无报错&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;tail&lt;/span&gt;&lt;span&gt; -20&lt;/span&gt;&lt;span&gt; /tmp/build&lt;/span&gt;&lt;span&gt;*&lt;/span&gt;&lt;span&gt;.log&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 目标页面是否正常&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; -s&lt;/span&gt;&lt;span&gt; -o&lt;/span&gt;&lt;span&gt; /dev/null&lt;/span&gt;&lt;span&gt; -w&lt;/span&gt;&lt;span&gt; &apos;%{http_code}\n&apos;&lt;/span&gt;&lt;span&gt; http://192.168.8.169:8080/post/post-edit-guide/&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 全站自检&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./verify.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h2&gt;八、一句话流程&lt;a href=&quot;#八一句话流程&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;nano&lt;/span&gt;&lt;span&gt; src/content/blog/note/xxx.md&lt;/span&gt;&lt;span&gt;    # 改&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./generate-summaries.sh&lt;/span&gt;&lt;span&gt;              # 更新摘要&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./build.sh&lt;/span&gt;&lt;span&gt;                           # 发布&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;需要置顶就在 frontmatter 加 &lt;code&gt;sticky: true&lt;/code&gt;，想先藏起来就加 &lt;code&gt;draft: true&lt;/code&gt;。&lt;/p&gt;</content:encoded><category>category:笔记</category><category>tag:教程</category><category>tag:维护</category><category>tag:Markdown</category></item><item><title>变更记录：从 Docker 四服务迁移到主机直装</title><link>https://koharu.cosine.ren/post/changelog-2026-11-18</link><guid isPermaLink="false">changelog-2026-11-18</guid><description>记录这次博客部署方案的调整过程，包括为什么要换、换了什么、以及踩到的坑。
一、起点：Docker 四服务方案
最初按一份现成方案部署，用 Compose 编排四个服务：






























服务作用端口koharu-cmsWeb</description><pubDate>Wed, 18 Nov 2026 07:41:00 GMT</pubDate><content:encoded>&lt;p&gt;记录这次博客部署方案的调整过程，包括为什么要换、换了什么、以及踩到的坑。&lt;/p&gt;
&lt;h2&gt;一、起点：Docker 四服务方案&lt;a href=&quot;#一起点docker-四服务方案&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;最初按一份现成方案部署，用 Compose 编排四个服务：&lt;/p&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;服务&lt;/th&gt;&lt;th&gt;作用&lt;/th&gt;&lt;th&gt;端口&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;koharu-cms&lt;/td&gt;&lt;td&gt;Web 写作后台&lt;/td&gt;&lt;td&gt;4322&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;koharu-preview&lt;/td&gt;&lt;td&gt;Astro dev 预览&lt;/td&gt;&lt;td&gt;4321&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;koharu-web&lt;/td&gt;&lt;td&gt;Nginx 提供静态站&lt;/td&gt;&lt;td&gt;8080&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;builder&lt;/td&gt;&lt;td&gt;一次性构建任务&lt;/td&gt;&lt;td&gt;—&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;这套方案本身能跑通，但落地时改了四处才启动起来：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;部署包默认路径 &lt;code&gt;/docker/...&lt;/code&gt;，fnOS 实际是 &lt;code&gt;/vol1/docker&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;文档假设 Lucky 在 bridge 网络，实际是 &lt;code&gt;host&lt;/code&gt; 网络，无法按容器名反代，改成端口映射&lt;/li&gt;
&lt;li&gt;&lt;code&gt;builder&lt;/code&gt; 在 &lt;code&gt;profiles: [&quot;tools&quot;]&lt;/code&gt; 下，&lt;code&gt;docker compose run&lt;/code&gt; 必须显式加 &lt;code&gt;--profile tools&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;CMS 的 Host 校验只认 localhost，局域网访问 API 全部 403&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;二、意外：容器被批量清理&lt;a href=&quot;#二意外容器被批量清理&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;11-17 晚上 22:25，在 1Panel 里做了一次容器清理操作。docker events 记录：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;22:25:04  创建 koharu-cms-modify-backup-150d7cd94c7841dc…&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;22:28:02  删除 koharu-cms、koharu-preview&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;22:28:03  删除 1Panel-deepseek-harness&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;22:28:27  删除 koharu-web&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;22:28:43  删除镜像 astro-koharu-fnos:local&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;三个容器连同镜像、命名卷一起消失，1Panel 甚至删掉了自己的后台容器。&lt;/p&gt;
&lt;p&gt;源码目录还在，但恢复要重建 1.75 GB 镜像（约 15 分钟）再跑一次构建（约 8 分钟）。&lt;/p&gt;
&lt;h2&gt;三、决策：改为主机直装&lt;a href=&quot;#三决策改为主机直装&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;权衡后放弃 Docker，理由是这台设备上 Docker 的隔离优势没有价值，更新成本却很高：&lt;/p&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;环节&lt;/th&gt;&lt;th&gt;Docker 方案&lt;/th&gt;&lt;th&gt;主机直装&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;首次环境准备&lt;/td&gt;&lt;td&gt;拉镜像 + build 镜像 14m51s&lt;/td&gt;&lt;td&gt;装 Node + pnpm 约 2 分钟&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;版本更新&lt;/td&gt;&lt;td&gt;依赖变化要 rebuild 镜像 15 分钟&lt;/td&gt;&lt;td&gt;&lt;code&gt;pnpm install&lt;/code&gt; 4m29s&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;故障面&lt;/td&gt;&lt;td&gt;builder 版本、Dockerfile 阶段、卷覆盖、容器被误删&lt;/td&gt;&lt;td&gt;只有 Node 本身&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;常驻开销&lt;/td&gt;&lt;td&gt;dockerd + 三个容器&lt;/td&gt;&lt;td&gt;Caddy 13 MB&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2&gt;四、新架构&lt;a href=&quot;#四新架构&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;pre&gt;flowchart LR
    A[Markdown 文章] --&amp;gt; B[pnpm build]
    B --&amp;gt; C[dist 静态文件]
    C --&amp;gt; D[Caddy :8080]
    D --&amp;gt; E[浏览器]
    F[CMS :4322] -.写文件.-&amp;gt; A
    G[dev 预览 :4321] -.热更新.-&amp;gt; A
    H[DeepSeek API] -.生成摘要.-&amp;gt; I[summaries.json]
    I --&amp;gt; B&lt;/pre&gt;
&lt;p&gt;组件版本：&lt;/p&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;组件&lt;/th&gt;&lt;th&gt;版本&lt;/th&gt;&lt;th&gt;位置&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Node&lt;/td&gt;&lt;td&gt;22.23.5 arm64&lt;/td&gt;&lt;td&gt;&lt;code&gt;/opt/node22&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;pnpm&lt;/td&gt;&lt;td&gt;10.28.2&lt;/td&gt;&lt;td&gt;corepack&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Caddy&lt;/td&gt;&lt;td&gt;2.11.9&lt;/td&gt;&lt;td&gt;&lt;code&gt;/usr/local/bin/caddy&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;项目&lt;/td&gt;&lt;td&gt;astro-koharu v7.7.5&lt;/td&gt;&lt;td&gt;&lt;code&gt;/vol1/www/astro-koharu&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;Caddy 由 systemd 服务 &lt;code&gt;caddy-koharu.service&lt;/code&gt; 守护，已设开机自启。&lt;/p&gt;
&lt;h2&gt;五、五个本地补丁&lt;a href=&quot;#五五个本地补丁&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;上游代码有多处假设不适合当前环境，全部做成 &lt;code&gt;patches/apply.mjs&lt;/code&gt; 里的幂等补丁：&lt;/p&gt;









































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;补丁&lt;/th&gt;&lt;th&gt;文件&lt;/th&gt;&lt;th&gt;问题&lt;/th&gt;&lt;th&gt;改法&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;&lt;code&gt;cms/server.ts&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Host 只认 localhost，局域网访问 API 403&lt;/td&gt;&lt;td&gt;放行 RFC1918 私有网段，公网域名仍拒绝&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;&lt;code&gt;package.json&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code&gt;dev&lt;/code&gt; 只监听 &lt;code&gt;[::1]&lt;/code&gt;&lt;/td&gt;&lt;td&gt;追加 &lt;code&gt;--host 0.0.0.0 --port 4321&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;3&lt;/td&gt;&lt;td&gt;&lt;code&gt;src/scripts/generateSummaries.ts&lt;/code&gt;&lt;/td&gt;&lt;td&gt;API 地址硬编码指向本地 LM Studio&lt;/td&gt;&lt;td&gt;改读 &lt;code&gt;SUMMARY_*&lt;/code&gt; 环境变量&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;4&lt;/td&gt;&lt;td&gt;同上&lt;/td&gt;&lt;td&gt;连通性检查不带 Authorization，云端 API 401 被误判为不可用&lt;/td&gt;&lt;td&gt;补 &lt;code&gt;Bearer&lt;/code&gt; 请求头&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;5&lt;/td&gt;&lt;td&gt;&lt;code&gt;src/pages/post/[...slug].astro&lt;/code&gt;&lt;/td&gt;&lt;td&gt;摘要面板优先显示手写 description，AI 摘要用不上&lt;/td&gt;&lt;td&gt;改为 AI 摘要优先，description 作兜底&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;补丁脚本可重复执行，已存在的会跳过，匹配不上会明确报错。&lt;code&gt;update.sh&lt;/code&gt; 升级时自动重放。&lt;/p&gt;
&lt;h2&gt;六、接入 AI 摘要&lt;a href=&quot;#六接入-ai-摘要&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;项目自带摘要生成脚本，用的是 OpenAI 兼容接口，改完补丁 3、4 后可接任何服务。&lt;/p&gt;
&lt;p&gt;当前接的是 DeepSeek，模型 &lt;code&gt;deepseek-flash&lt;/code&gt;（&lt;code&gt;deepseek-chat&lt;/code&gt; 已下线）。&lt;/p&gt;
&lt;p&gt;实测数据：&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;项目&lt;/th&gt;&lt;th&gt;数值&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;3 篇生成耗时&lt;/td&gt;&lt;td&gt;6.0 秒&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;单篇 token&lt;/td&gt;&lt;td&gt;约 3k 输入 + 150 输出&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;3 篇成本&lt;/td&gt;&lt;td&gt;约 ¥0.02&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;全量 38 篇预估&lt;/td&gt;&lt;td&gt;约 ¥0.2&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;摘要按「内容 hash + 模型名」缓存，改过的文章重新生成，没动过的走缓存。&lt;/p&gt;
&lt;p&gt;需要注意摘要的显示优先级：&lt;strong&gt;写了 &lt;code&gt;description&lt;/code&gt; 的文章不会显示 AI 摘要&lt;/strong&gt;，面板会标注为 &lt;code&gt;description&lt;/code&gt;；只有不写 description 才会走 AI 摘要（标注 &lt;code&gt;ai&lt;/code&gt;）。&lt;/p&gt;
&lt;h2&gt;七、性能观察&lt;a href=&quot;#七性能观察&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;









































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;指标&lt;/th&gt;&lt;th&gt;数值&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;首次构建（含图片优化）&lt;/td&gt;&lt;td&gt;7 分 23 秒&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;增量构建（图片缓存命中）&lt;/td&gt;&lt;td&gt;2 分 13 秒（其中图片阶段仅 1 秒）&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;构建产物&lt;/td&gt;&lt;td&gt;307 页 / 1853 文件 / 181 MB&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;pagefind 索引&lt;/td&gt;&lt;td&gt;311 页&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;首页响应&lt;/td&gt;&lt;td&gt;约 25 ms，177–221 KB，gzip 压缩&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Caddy 内存&lt;/td&gt;&lt;td&gt;13 MB&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;CMS 内存&lt;/td&gt;&lt;td&gt;324 MB（仅使用时启动）&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;dev 预览内存&lt;/td&gt;&lt;td&gt;约 700 MB（仅使用时启动）&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;慢的主要来源是 108 张图片转 avif/webp 多尺寸，以及 pagefind 全文索引。这部分 Hexo 默认不做，所以对比构建速度时要算上功能差异。&lt;/p&gt;
&lt;h2&gt;八、清理动作&lt;a href=&quot;#八清理动作&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;删除旧 Docker 部署目录 590 MB、本地源码副本 72 MB&lt;/li&gt;
&lt;li&gt;清理构建缓存 1.754 GB，回收悬空镜像层约 8 GB&lt;/li&gt;
&lt;li&gt;删除旧后台项目（含明文凭据的部署脚本）&lt;/li&gt;
&lt;li&gt;磁盘 &lt;code&gt;/vol1&lt;/code&gt; 从 112 GB 降到 91 GB&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;九、遗留问题&lt;a href=&quot;#九遗留问题&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;无 &lt;code&gt;link&lt;/code&gt; 字段的文章，摘要生成脚本用的 key 是相对路径（如 &lt;code&gt;note/shoka-features&lt;/code&gt;），页面查找用的是另一套 slug 规则，两者是否始终一致尚未逐一验证。&lt;/li&gt;
&lt;li&gt;&lt;code&gt;pnpm koharu generate summaries&lt;/code&gt; 是交互式 TUI，脚本化调用必须绕过 CLI 直调 &lt;code&gt;tsx src/scripts/generateSummaries.ts&lt;/code&gt;。&lt;/li&gt;
&lt;li&gt;部分 Markdown 扩展（如脚注）渲染不完全，会退化为普通文本，不影响构建。&lt;/li&gt;
&lt;li&gt;设备温度在 CPU 68°C、DDR 69°C 附近，风扇策略由 fnOS 管理，暂未干预。&lt;/li&gt;
&lt;/ol&gt;
&lt;h2&gt;十、小结&lt;a href=&quot;#十小结&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;主机直装的核心收益不是”更快”，而是&lt;strong&gt;故障面变小&lt;/strong&gt;：从「Docker daemon + 镜像层 + Compose 编排 + 容器被误删」简化到「Node 进程 + 一个静态服务器」。代价是宿主多了一个 Node 运行时，通过独立目录 &lt;code&gt;/opt/node22&lt;/code&gt; 隔离，不碰系统包管理器。&lt;/p&gt;</content:encoded><category>category:笔记</category><category>tag:变更记录</category><category>tag:运维</category><category>tag:Docker</category></item><item><title>博客运维操作手册</title><link>https://koharu.cosine.ren/post/blog-ops-guide</link><guid isPermaLink="false">blog-ops-guide</guid><description>本文记录这台设备上 astro-koharu 博客的部署形态与日常操作，方便以后直接查命令。
一、访问地址
站点跑在局域网 192.168.8.169 上，端口如下：</description><pubDate>Wed, 18 Nov 2026 07:40:00 GMT</pubDate><content:encoded>&lt;p&gt;本文记录这台设备上 astro-koharu 博客的部署形态与日常操作，方便以后直接查命令。&lt;/p&gt;
&lt;h2&gt;一、访问地址&lt;a href=&quot;#一访问地址&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;站点跑在局域网 &lt;code&gt;192.168.8.169&lt;/code&gt; 上，端口如下：&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;用途&lt;/th&gt;&lt;th&gt;地址&lt;/th&gt;&lt;th&gt;说明&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;博客正式站&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;http://192.168.8.169:8080&quot;&gt;http://192.168.8.169:8080&lt;/a&gt;&lt;/td&gt;&lt;td&gt;Caddy 常驻，systemd 守护，开机自启&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;预览（热更新）&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;http://192.168.8.169:4321&quot;&gt;http://192.168.8.169:4321&lt;/a&gt;&lt;/td&gt;&lt;td&gt;需要手动启动，改完即刷新&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;CMS 后台&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;a href=&quot;http://192.168.8.169:4322&quot;&gt;http://192.168.8.169:4322&lt;/a&gt;&lt;/td&gt;&lt;td&gt;需要手动启动，图形化写文章&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;三者在同一局域网内访问，不暴露到公网。&lt;/p&gt;
&lt;h2&gt;二、连接设备&lt;a href=&quot;#二连接设备&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;ssh&lt;/span&gt;&lt;span&gt; fnOS@192.168.8.169&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h2&gt;三、日常命令&lt;a href=&quot;#三日常命令&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;h3&gt;启动 CMS（图形化写文章）&lt;a href=&quot;#启动-cms图形化写文章&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;pnpm&lt;/span&gt;&lt;span&gt; cms&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;启动约 40 秒，浏览器打开 &lt;a href=&quot;http://192.168.8.169:4322&quot;&gt;http://192.168.8.169:4322&lt;/a&gt; 即可使用。内存占用约 324 MB。&lt;/p&gt;
&lt;h3&gt;启动预览（实时看效果）&lt;a href=&quot;#启动预览实时看效果&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;pnpm&lt;/span&gt;&lt;span&gt; dev&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;启动约 1–2 分钟（首次编译较慢），浏览器打开 &lt;a href=&quot;http://192.168.8.169:4321%E3%80%82%E6%94%B9%E6%96%87%E4%BB%B6%E5%90%8E%E9%A1%B5%E9%9D%A2%E8%87%AA%E5%8A%A8%E5%88%B7%E6%96%B0%E3%80%82%E5%86%85%E5%AD%98%E5%8D%A0%E7%94%A8%E7%BA%A6&quot;&gt;http://192.168.8.169:4321。改文件后页面自动刷新。内存占用约&lt;/a&gt; 700 MB。&lt;/p&gt;
&lt;h3&gt;停止服务&lt;a href=&quot;#停止服务&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;在运行的终端按 &lt;code&gt;Ctrl+C&lt;/code&gt; 即可。如果终端已关闭，另开一个：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./stop.sh&lt;/span&gt;&lt;span&gt;          # 停止 CMS 与预览&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./stop.sh&lt;/span&gt;&lt;span&gt; cms&lt;/span&gt;&lt;span&gt;      # 只停 CMS&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./stop.sh&lt;/span&gt;&lt;span&gt; dev&lt;/span&gt;&lt;span&gt;      # 只停预览&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;注意&lt;/strong&gt;：关闭浏览器页面不会停止服务，进程仍在占用内存，必须显式停止。&lt;/p&gt;
&lt;h3&gt;新建文章（交互式）&lt;a href=&quot;#新建文章交互式&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;pnpm&lt;/span&gt;&lt;span&gt; koharu&lt;/span&gt;&lt;span&gt; new&lt;/span&gt;&lt;span&gt; post&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;按提示依次输入标题、Slug、描述、分类、标签，会在 &lt;code&gt;src/content/blog/&amp;lt;分类&amp;gt;/&lt;/code&gt; 下生成带 frontmatter 的 Markdown 文件。&lt;/p&gt;
&lt;p&gt;需要在真实终端里执行，管道或脚本中调用会因缺少 TTY 失败。&lt;/p&gt;
&lt;h3&gt;新建文章（手动写文件）&lt;a href=&quot;#新建文章手动写文件&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;直接在 &lt;code&gt;src/content/blog/&lt;/code&gt; 下建 &lt;code&gt;.md&lt;/code&gt; 文件，格式：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;---&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;title&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; 文章标题&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;link&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; custom-url&lt;/span&gt;&lt;span&gt;          # 可选，自定义路径&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;catalog&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; true&lt;/span&gt;&lt;span&gt;             # 显示目录&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;date&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; 2026-11-18 15:00:00&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;description&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; 摘要&lt;/span&gt;&lt;span&gt;          # 可选，写了就不走 AI 摘要&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;cover&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; /img/cover/7.webp&lt;/span&gt;&lt;span&gt;  # 可选封面&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;tags&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  -&lt;/span&gt;&lt;span&gt; 标签&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;categories&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  -&lt;/span&gt;&lt;span&gt; 笔记&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;---&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;分类目录对应关系见 &lt;code&gt;config/site.yaml&lt;/code&gt; 的 &lt;code&gt;categoryMap&lt;/code&gt;，现有：随笔、笔记、工具、周刊、前端、CSS、番剧。&lt;/p&gt;
&lt;h3&gt;生成 AI 摘要&lt;a href=&quot;#生成-ai-摘要&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./generate-summaries.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;增量执行：已生成过的走缓存，只处理新增或修改过的文章。摘要写入 &lt;code&gt;src/assets/summaries.json&lt;/code&gt;，&lt;strong&gt;必须重新构建才会显示&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;接口配置在 &lt;code&gt;.env.summary&lt;/code&gt;（DeepSeek，&lt;code&gt;deepseek-flash&lt;/code&gt;）。&lt;/p&gt;
&lt;p&gt;摘要显示规则（&lt;strong&gt;AI 摘要优先&lt;/strong&gt;）：&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;优先级&lt;/th&gt;&lt;th&gt;来源&lt;/th&gt;&lt;th&gt;面板标注&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;AI 摘要&lt;/td&gt;&lt;td&gt;&lt;code&gt;ai&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;frontmatter &lt;code&gt;description&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code&gt;description&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;3&lt;/td&gt;&lt;td&gt;正文自动提取&lt;/td&gt;&lt;td&gt;&lt;code&gt;auto&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;code&gt;description&lt;/code&gt; 仍用于列表卡片和 SEO 描述，只是不再覆盖文章页顶部的摘要面板。&lt;/p&gt;
&lt;h3&gt;更换 AI Key 或服务商&lt;a href=&quot;#更换-ai-key-或服务商&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;配置集中在项目根目录的 &lt;code&gt;.env.summary&lt;/code&gt;：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;nano&lt;/span&gt;&lt;span&gt; .env.summary&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;三个字段：&lt;/p&gt;





















&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;字段&lt;/th&gt;&lt;th&gt;说明&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;SUMMARY_API_BASE_URL&lt;/code&gt;&lt;/td&gt;&lt;td&gt;接口地址，DeepSeek 为 &lt;code&gt;https://api.deepseek.com/v1/&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;SUMMARY_MODEL&lt;/code&gt;&lt;/td&gt;&lt;td&gt;模型名，当前 &lt;code&gt;deepseek-flash&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;SUMMARY_API_KEY&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code&gt;sk-&lt;/code&gt; 开头的密钥&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;改完不需要重启任何服务，直接重新生成：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;./generate-summaries.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;只换 Key、模型不变&lt;/strong&gt;时缓存继续有效，已生成的摘要不会重复调用。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;换模型或换服务商时必须清缓存&lt;/strong&gt;，否则旧摘要会被判定为有效而跳过：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;rm&lt;/span&gt;&lt;span&gt; -f&lt;/span&gt;&lt;span&gt; .cache/summaries-cache.json&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./generate-summaries.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;想强制全部重新生成，加 &lt;code&gt;--force&lt;/code&gt;：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;./generate-summaries.sh&lt;/span&gt;&lt;span&gt; --force&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;生成后构建发布：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;./build.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;验证新 Key 是否可用：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;.&lt;/span&gt;&lt;span&gt; ./.env.summary&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; -s&lt;/span&gt;&lt;span&gt; -o&lt;/span&gt;&lt;span&gt; /dev/null&lt;/span&gt;&lt;span&gt; -w&lt;/span&gt;&lt;span&gt; &apos;%{http_code}\n&apos;&lt;/span&gt;&lt;span&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  -H&lt;/span&gt;&lt;span&gt; &quot;Authorization: Bearer &lt;/span&gt;&lt;span&gt;$SUMMARY_API_KEY&lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  &quot;&lt;/span&gt;&lt;span&gt;${SUMMARY_API_BASE_URL}&lt;/span&gt;&lt;span&gt;models&quot;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;返回 &lt;code&gt;200&lt;/code&gt; 说明 Key 有效，&lt;code&gt;401&lt;/code&gt; 表示无效或额度不足。&lt;/p&gt;
&lt;p&gt;换服务商时参考下表填写：&lt;/p&gt;



































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;服务&lt;/th&gt;&lt;th&gt;&lt;code&gt;SUMMARY_API_BASE_URL&lt;/code&gt;&lt;/th&gt;&lt;th&gt;常用模型&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;DeepSeek&lt;/td&gt;&lt;td&gt;&lt;code&gt;https://api.deepseek.com/v1/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code&gt;deepseek-flash&lt;/code&gt;、&lt;code&gt;deepseek-v4-pro&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;硅基流动&lt;/td&gt;&lt;td&gt;&lt;code&gt;https://api.siliconflow.cn/v1/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code&gt;Qwen/Qwen2.5-7B-Instruct&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;智谱&lt;/td&gt;&lt;td&gt;&lt;code&gt;https://open.bigmodel.cn/api/paas/v4/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code&gt;glm-4-flash&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;本地 Ollama&lt;/td&gt;&lt;td&gt;&lt;code&gt;http://127.0.0.1:11434/v1/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code&gt;qwen2.5:1.5b&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;OpenAI&lt;/td&gt;&lt;td&gt;&lt;code&gt;https://api.openai.com/v1/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code&gt;gpt-4o-mini&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;code&gt;.env.summary&lt;/code&gt; 权限为 &lt;code&gt;600&lt;/code&gt;，且已写入 &lt;code&gt;.git/info/exclude&lt;/code&gt;，不会随 git 操作丢失或被提交。&lt;/p&gt;
&lt;h3&gt;构建发布&lt;a href=&quot;#构建发布&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./build.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;约 2–3 分钟（图片缓存命中时），首次或图片变动约 7–8 分钟。构建完成后 8080 立即更新，不需要重启 Caddy。&lt;/p&gt;
&lt;h2&gt;四、升级与补丁&lt;a href=&quot;#四升级与补丁&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;h3&gt;升级上游版本&lt;a href=&quot;#升级上游版本&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./update.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;流程：暂存本地改动 → 拉上游 → 恢复改动 → 重打补丁 → 装依赖 → 构建。&lt;/p&gt;
&lt;h3&gt;重新应用本地补丁&lt;a href=&quot;#重新应用本地补丁&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./reapply-patches.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;补丁清单：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;CMS 局域网访问&lt;/strong&gt; — 放行私有网段，否则局域网保存文章会 403&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;dev 绑定 0.0.0.0&lt;/strong&gt; — 否则预览只监听 IPv6 回环&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;AI 摘要读环境变量&lt;/strong&gt; — 否则接口地址写死为本地 LM Studio&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;连通性检查带认证&lt;/strong&gt; — 否则云端 API 因 401 被误判为不可用&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;补丁脚本幂等，可重复执行。&lt;/p&gt;
&lt;h2&gt;五、目录结构&lt;a href=&quot;#五目录结构&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;/vol1/www/astro-koharu/&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;├── src/content/blog/     文章 Markdown（按分类分目录）&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;├── config/site.yaml      站点配置（标题、导航、评论、SEO…）&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;├── config/i18n-content.yaml  多语言文案&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;├── src/assets/summaries.json  AI 摘要数据&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;├── dist/                 构建产物（Caddy 直接读取）&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;├── .env.summary          AI 接口配置（git 忽略）&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;├── build.sh              构建发布&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;├── update.sh             升级上游&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;├── stop.sh               停止服务&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;├── generate-summaries.sh 生成 AI 摘要&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;├── reapply-patches.sh    重打补丁&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;└── patches/apply.mjs     补丁实现&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;运行环境：Node 22.23.5（&lt;code&gt;/opt/node22&lt;/code&gt;）+ pnpm 10.28.2 + Caddy 2.11.9（systemd 服务 &lt;code&gt;caddy-koharu&lt;/code&gt;）。&lt;/p&gt;
&lt;h2&gt;六、故障排查&lt;a href=&quot;#六故障排查&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;





























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;现象&lt;/th&gt;&lt;th&gt;排查方向&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;8080 打不开&lt;/td&gt;&lt;td&gt;&lt;code&gt;systemctl status caddy-koharu&lt;/code&gt;，检查 &lt;code&gt;dist/&lt;/code&gt; 是否存在&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;CMS 能打开但存不了&lt;/td&gt;&lt;td&gt;确认补丁 1 已应用，&lt;code&gt;/api/cms/*&lt;/code&gt; 返回 403 即未生效&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;预览局域网打不开&lt;/td&gt;&lt;td&gt;确认补丁 2 已应用，&lt;code&gt;ss -tln | grep 4321&lt;/code&gt; 应显示 &lt;code&gt;0.0.0.0&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;内存吃紧&lt;/td&gt;&lt;td&gt;&lt;code&gt;./stop.sh&lt;/code&gt; 停掉 CMS 与预览，博客常驻仅占 13 MB&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;构建失败&lt;/td&gt;&lt;td&gt;看 &lt;code&gt;/tmp/build*.log&lt;/code&gt;，多为 Node 版本或依赖问题&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2&gt;七、常用检查命令&lt;a href=&quot;#七常用检查命令&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;# 服务状态&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;systemctl&lt;/span&gt;&lt;span&gt; status&lt;/span&gt;&lt;span&gt; caddy-koharu&lt;/span&gt;&lt;span&gt; --no-pager&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; -s&lt;/span&gt;&lt;span&gt; -o&lt;/span&gt;&lt;span&gt; /dev/null&lt;/span&gt;&lt;span&gt; -w&lt;/span&gt;&lt;span&gt; &apos;%{http_code}\n&apos;&lt;/span&gt;&lt;span&gt; http://192.168.8.169:8080/&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 端口监听&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;ss&lt;/span&gt;&lt;span&gt; -tlnp&lt;/span&gt;&lt;span&gt; |&lt;/span&gt;&lt;span&gt; grep&lt;/span&gt;&lt;span&gt; -E&lt;/span&gt;&lt;span&gt; &apos;:(8080|4321|4322)&apos;&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 内存&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;free&lt;/span&gt;&lt;span&gt; -h&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 磁盘&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;df&lt;/span&gt;&lt;span&gt; -h&lt;/span&gt;&lt;span&gt; /vol1&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h2&gt;八、备份与恢复&lt;a href=&quot;#八备份与恢复&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;h3&gt;打包备份&lt;a href=&quot;#打包备份&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;tar&lt;/span&gt;&lt;span&gt; -czf&lt;/span&gt;&lt;span&gt; /tmp/astro-koharu-&lt;/span&gt;&lt;span&gt;$(&lt;/span&gt;&lt;span&gt;date&lt;/span&gt;&lt;span&gt; +%Y%m%d&lt;/span&gt;&lt;span&gt;)&lt;/span&gt;&lt;span&gt;.tar.gz&lt;/span&gt;&lt;span&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  --exclude=&apos;astro-koharu/node_modules&apos;&lt;/span&gt;&lt;span&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  --exclude=&apos;astro-koharu/dist&apos;&lt;/span&gt;&lt;span&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  --exclude=&apos;astro-koharu/.astro&apos;&lt;/span&gt;&lt;span&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  --exclude=&apos;astro-koharu/.cache&apos;&lt;/span&gt;&lt;span&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;ls&lt;/span&gt;&lt;span&gt; -lh&lt;/span&gt;&lt;span&gt; /tmp/astro-koharu-&lt;/span&gt;&lt;span&gt;*&lt;/span&gt;&lt;span&gt;.tar.gz&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;源目录 6.2 GB，打包后约 &lt;strong&gt;63 MB&lt;/strong&gt;（压缩掉可重建部分），耗时约 15 秒。&lt;/p&gt;
&lt;p&gt;取回到本地：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;scp&lt;/span&gt;&lt;span&gt; fnOS@192.168.8.169:/tmp/astro-koharu-&lt;/span&gt;&lt;span&gt;*&lt;/span&gt;&lt;span&gt;.tar.gz&lt;/span&gt;&lt;span&gt; ./&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;备份包含：源码、全部文章、图片、&lt;code&gt;.git&lt;/code&gt;、&lt;code&gt;config/&lt;/code&gt;、运维脚本、&lt;code&gt;patches/&lt;/code&gt;、&lt;code&gt;system/&lt;/code&gt;、&lt;code&gt;.env.summary&lt;/code&gt;。&lt;/p&gt;
&lt;p&gt;排除项：&lt;code&gt;node_modules&lt;/code&gt;（5.8 GB）、&lt;code&gt;dist&lt;/code&gt;（188 MB）、&lt;code&gt;.astro&lt;/code&gt;、&lt;code&gt;.cache&lt;/code&gt;，这些都能重建。&lt;/p&gt;
&lt;h3&gt;system/ 目录&lt;a href=&quot;#system-目录&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;项目内 &lt;code&gt;system/&lt;/code&gt; 保存&lt;strong&gt;项目目录之外&lt;/strong&gt;的部署配置，随备份一起走：&lt;/p&gt;





























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;文件&lt;/th&gt;&lt;th&gt;内容&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;caddy/Caddyfile&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code&gt;:8080&lt;/code&gt; 静态服务配置（压缩、缓存头、404 回退）&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;systemd/caddy-koharu.service&lt;/code&gt;&lt;/td&gt;&lt;td&gt;守护单元&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;env-info.txt&lt;/code&gt;&lt;/td&gt;&lt;td&gt;组件版本清单&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;install.sh&lt;/code&gt;&lt;/td&gt;&lt;td&gt;一键安装，按实际项目路径与目录属主生成配置&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;README.md&lt;/code&gt;&lt;/td&gt;&lt;td&gt;从零重建全套环境的完整命令&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3&gt;从备份恢复&lt;a href=&quot;#从备份恢复&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;# 1. 解压&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;tar&lt;/span&gt;&lt;span&gt; -xzf&lt;/span&gt;&lt;span&gt; astro-koharu-YYYYMMDD.tar.gz&lt;/span&gt;&lt;span&gt; -C&lt;/span&gt;&lt;span&gt; /vol1/www&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;chown&lt;/span&gt;&lt;span&gt; -R&lt;/span&gt;&lt;span&gt; fnOS:Users&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 2. 依赖、补丁、构建&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;export&lt;/span&gt;&lt;span&gt; PATH&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;/opt/node22/bin:$PATH&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;pnpm&lt;/span&gt;&lt;span&gt; install&lt;/span&gt;&lt;span&gt; --frozen-lockfile&lt;/span&gt;&lt;span&gt; --prod=false&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;node&lt;/span&gt;&lt;span&gt; patches/apply.mjs&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;pnpm&lt;/span&gt;&lt;span&gt; build&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 3. 重建 Caddy 与 systemd&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;sudo&lt;/span&gt;&lt;span&gt; ./system/install.sh&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 4. 自检&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./verify.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h3&gt;从裸机重建&lt;a href=&quot;#从裸机重建&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;system/README.md&lt;/code&gt; 里记录了完整顺序：安装 Node 22（arm64 tar）、安装 Caddy、恢复项目、装依赖、打补丁、构建、装系统服务。&lt;/p&gt;
&lt;h3&gt;不在备份内的&lt;a href=&quot;#不在备份内的&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;






























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;项&lt;/th&gt;&lt;th&gt;大小&lt;/th&gt;&lt;th&gt;重建方式&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Node 运行时&lt;/td&gt;&lt;td&gt;197 MB&lt;/td&gt;&lt;td&gt;&lt;code&gt;system/README.md&lt;/code&gt; 第 1 步&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Caddy 二进制&lt;/td&gt;&lt;td&gt;47 MB&lt;/td&gt;&lt;td&gt;&lt;code&gt;system/README.md&lt;/code&gt; 第 2 步&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;node_modules&lt;/td&gt;&lt;td&gt;5.8 GB&lt;/td&gt;&lt;td&gt;&lt;code&gt;pnpm install&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;dist&lt;/td&gt;&lt;td&gt;188 MB&lt;/td&gt;&lt;td&gt;&lt;code&gt;pnpm build&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3&gt;备份注意事项&lt;a href=&quot;#备份注意事项&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;.env.summary&lt;/code&gt; 含明文 API Key，备份包不要放网盘或公共位置&lt;/li&gt;
&lt;li&gt;备份前建议先 &lt;code&gt;./verify.sh&lt;/code&gt; 确认当前状态正常，避免把故障状态存成基线&lt;/li&gt;
&lt;li&gt;设备上的 &lt;code&gt;/tmp/astro-koharu-*.tar.gz&lt;/code&gt; 取回本地后及时删除，避免重复打包占空间&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;九、音乐歌单管理&lt;a href=&quot;#九音乐歌单管理&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;歌单页面（&lt;code&gt;/music&lt;/code&gt;）和右下角的 BGM 播放器都使用&lt;strong&gt;本地音频文件&lt;/strong&gt;，不依赖任何在线音乐接口。&lt;/p&gt;
&lt;h3&gt;目录与格式&lt;a href=&quot;#目录与格式&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;项&lt;/th&gt;&lt;th&gt;说明&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;存放目录&lt;/td&gt;&lt;td&gt;&lt;code&gt;public/music/&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;支持格式&lt;/td&gt;&lt;td&gt;mp3 / m4a / flac / ogg / wav / aac / opus&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;显示歌名&lt;/td&gt;&lt;td&gt;取文件名（去掉扩展名），改名即改显示名&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;排序&lt;/td&gt;&lt;td&gt;按文件名中文排序&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3&gt;添加歌曲&lt;a href=&quot;#添加歌曲&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;# 1. 上传（也可以用 fnOS 文件管理器拖拽）&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;scp&lt;/span&gt;&lt;span&gt; &quot;C:\Music\*.mp3&quot;&lt;/span&gt;&lt;span&gt; fnOS@192.168.8.169:/vol1/www/astro-koharu/public/music/&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 2. 同步生成歌单页与 BGM 配置&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./sync-music.sh&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 3. 发布&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./build.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;sync-music.sh&lt;/code&gt; 会同时改写两个地方：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code&gt;src/pages/music.md&lt;/code&gt; —— 歌单页&lt;/li&gt;
&lt;li&gt;&lt;code&gt;config/site.yaml&lt;/code&gt; 的 &lt;code&gt;bgm.audio&lt;/code&gt; 段 —— 全局播放器&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;两条命令即可，不需要手动编辑 YAML。&lt;/p&gt;
&lt;h3&gt;无损格式转换&lt;a href=&quot;#无损格式转换&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;flac 体积大（实测一首 96kHz 的 85 MB），浏览器加载明显偏慢，建议转成 192 kbps mp3：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;ffmpeg&lt;/span&gt;&lt;span&gt; -y&lt;/span&gt;&lt;span&gt; -i&lt;/span&gt;&lt;span&gt; &quot;input.flac&quot;&lt;/span&gt;&lt;span&gt; -vn&lt;/span&gt;&lt;span&gt; -ar&lt;/span&gt;&lt;span&gt; 44100&lt;/span&gt;&lt;span&gt; -codec:a&lt;/span&gt;&lt;span&gt; libmp3lame&lt;/span&gt;&lt;span&gt; -b:a&lt;/span&gt;&lt;span&gt; 192k&lt;/span&gt;&lt;span&gt; &quot;output.mp3&quot;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;其中 &lt;code&gt;-vn&lt;/code&gt; 用于跳过内嵌封面图——带封面的 flac 不加这个参数，ffmpeg 容易卡住不退出。&lt;/p&gt;
&lt;p&gt;实测：85 MB flac → 5.4 MB mp3，4 首合计 129 MB → 23 MB。&lt;/p&gt;
&lt;h3&gt;为什么不接在线歌单&lt;a href=&quot;#为什么不接在线歌单&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;





















&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;平台&lt;/th&gt;&lt;th&gt;实测结果&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;QQ 音乐&lt;/td&gt;&lt;td&gt;meting 接口返回 &lt;code&gt;upstream url empty&lt;/code&gt;，拿不到音频流（版权限制）&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;网易云&lt;/td&gt;&lt;td&gt;公共 meting 的 &lt;code&gt;type=url&lt;/code&gt; 已失效；官方外链只对免费歌返回真实地址，VIP 歌 302 到 &lt;code&gt;/404&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;自建 meting&lt;/td&gt;&lt;td&gt;常见镜像只有 amd64，本机 arm64 报 &lt;code&gt;exec format error&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;本地文件没有版权限制、不依赖网络，是个人博客最稳的方案。&lt;/p&gt;
&lt;h3&gt;升级时的保护&lt;a href=&quot;#升级时的保护&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;音乐相关的改动分三层保护，&lt;code&gt;./update.sh&lt;/code&gt; 升级后不需要手工重配：&lt;/p&gt;





















&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;内容&lt;/th&gt;&lt;th&gt;保护方式&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;meting.ts&lt;/code&gt; 的直链支持&lt;/td&gt;&lt;td&gt;&lt;code&gt;patches/apply.mjs&lt;/code&gt; 补丁 6，升级自动重打&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;music.md&lt;/code&gt; 与 &lt;code&gt;bgm.audio&lt;/code&gt;&lt;/td&gt;&lt;td&gt;由 &lt;code&gt;sync-music.sh&lt;/code&gt; 生成，&lt;code&gt;update.sh&lt;/code&gt; 第 7 步自动重建&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;public/music/&lt;/code&gt; 音频文件&lt;/td&gt;&lt;td&gt;已加入 &lt;code&gt;.git/info/exclude&lt;/code&gt;，&lt;code&gt;git pull&lt;/code&gt; 不会碰&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;升级流程里第 2 步会主动丢弃 &lt;code&gt;music.md&lt;/code&gt; 和 &lt;code&gt;site.yaml&lt;/code&gt; 的本地改动（避免 pull 冲突），第 7 步再用 &lt;code&gt;sync-music.sh&lt;/code&gt; 重建。所以这两个文件不需要手动备份。&lt;/p&gt;
&lt;p&gt;如果升级后歌单异常，手动补一次即可：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;./sync-music.sh&lt;/span&gt;&lt;span&gt; &amp;amp;&amp;amp;&lt;/span&gt;&lt;span&gt; ./build.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h2&gt;十、个性化配置&lt;a href=&quot;#十个性化配置&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;站点的标题、作者、副标题等&lt;strong&gt;不要直接改&lt;/strong&gt; &lt;code&gt;config/site.yaml&lt;/code&gt;，改为修改 &lt;code&gt;config/personal.yaml&lt;/code&gt;，再用脚本写回。&lt;/p&gt;
&lt;h3&gt;为什么&lt;a href=&quot;#为什么&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;site.yaml&lt;/code&gt; 是上游跟踪的文件，每次 &lt;code&gt;./update.sh&lt;/code&gt; 升级时会被丢弃重建（否则 pull 会因本地改动而失败）。直接改它，升级后就丢了。&lt;/p&gt;
&lt;p&gt;&lt;code&gt;config/personal.yaml&lt;/code&gt; 是本地的权威来源，已加入 &lt;code&gt;.git/info/exclude&lt;/code&gt;，升级不受影响。&lt;code&gt;update.sh&lt;/code&gt; 第 7 步会用 &lt;code&gt;sync.sh&lt;/code&gt; 把它写回 &lt;code&gt;site.yaml&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;修改流程&lt;a href=&quot;#修改流程&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;vi&lt;/span&gt;&lt;span&gt; config/personal.yaml&lt;/span&gt;&lt;span&gt;     # 改完保存&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./sync.sh&lt;/span&gt;&lt;span&gt;                   # 写回 site.yaml&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./build.sh&lt;/span&gt;&lt;span&gt;                  # 发布&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;code&gt;sync.sh&lt;/code&gt; 只替换字段的值，保留 &lt;code&gt;site.yaml&lt;/code&gt; 的行尾注释和字段顺序。&lt;/p&gt;
&lt;h3&gt;可配置字段&lt;a href=&quot;#可配置字段&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;





























































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;字段&lt;/th&gt;&lt;th&gt;说明&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;title&lt;/code&gt;&lt;/td&gt;&lt;td&gt;网站名称&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;alternate&lt;/code&gt;&lt;/td&gt;&lt;td&gt;网站英文名（页脚、Logo、@ handle）&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;subtitle&lt;/code&gt;&lt;/td&gt;&lt;td&gt;网站副标题&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;name&lt;/code&gt;&lt;/td&gt;&lt;td&gt;作者名称&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;description&lt;/code&gt;&lt;/td&gt;&lt;td&gt;网站描述&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;avatar&lt;/code&gt;&lt;/td&gt;&lt;td&gt;网站头像路径&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;showLogo&lt;/code&gt;&lt;/td&gt;&lt;td&gt;是否显示图形 Logo&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;author&lt;/code&gt;&lt;/td&gt;&lt;td&gt;作者名（文章页、SEO 用）&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;url&lt;/code&gt;&lt;/td&gt;&lt;td&gt;站点完整 URL（RSS、SEO 用）&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;defaultOgImage&lt;/code&gt;&lt;/td&gt;&lt;td&gt;默认社交分享图&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;startYear&lt;/code&gt;&lt;/td&gt;&lt;td&gt;建站年份（页脚版权区间）&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;timezone&lt;/code&gt;&lt;/td&gt;&lt;td&gt;时区（IANA 格式）&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;keywords&lt;/code&gt;&lt;/td&gt;&lt;td&gt;全局 SEO 关键词列表&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3&gt;改完如何确认&lt;a href=&quot;#改完如何确认&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &apos;^  title:&apos;&lt;/span&gt;&lt;span&gt; config/site.yaml&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; -s&lt;/span&gt;&lt;span&gt; http://192.168.8.169:8080/&lt;/span&gt;&lt;span&gt; |&lt;/span&gt;&lt;span&gt; grep&lt;/span&gt;&lt;span&gt; -o&lt;/span&gt;&lt;span&gt; &apos;&amp;lt;title&amp;gt;[^&amp;lt;]*&amp;lt;/title&amp;gt;&apos;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;第一条看 &lt;code&gt;site.yaml&lt;/code&gt; 是否已同步，第二条确认构建后的页面标题。&lt;/p&gt;
&lt;h3&gt;与升级的关系&lt;a href=&quot;#与升级的关系&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;./update.sh&lt;/code&gt; 的流程保证了配置不会丢：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;第 2 步&lt;/strong&gt;：丢弃 &lt;code&gt;site.yaml&lt;/code&gt;（连同所有本地改动），避免 pull 冲突&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;第 3 步&lt;/strong&gt;：拉取上游最新代码&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;第 7 步&lt;/strong&gt;：执行 &lt;code&gt;./sync.sh&lt;/code&gt;，用 &lt;code&gt;personal.yaml&lt;/code&gt; 重建站点配置、用 &lt;code&gt;public/music/&lt;/code&gt; 重建歌单&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;第 9 步&lt;/strong&gt;：&lt;code&gt;./verify.sh&lt;/code&gt; 自检 12 项&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;所以升级后配置会自动回来，不需要手工对比 &lt;code&gt;/tmp&lt;/code&gt; 里的备份。&lt;/p&gt;
&lt;h3&gt;如果要加新的个性化项&lt;a href=&quot;#如果要加新的个性化项&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;比如导航、社交链接、评论配置这些也在 &lt;code&gt;site.yaml&lt;/code&gt; 里，但目前不在 &lt;code&gt;personal.yaml&lt;/code&gt; 的覆盖范围内。&lt;/p&gt;
&lt;p&gt;需要长期保留的改动，两种做法：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;加进 &lt;code&gt;scripts/sync-config.mjs&lt;/code&gt;（适合标量字段，脚本会按段替换）&lt;/li&gt;
&lt;li&gt;写成 &lt;code&gt;patches/apply.mjs&lt;/code&gt; 里的补丁（适合复杂结构）&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;临时改动可以先直接改 &lt;code&gt;site.yaml&lt;/code&gt;，但记得升级前备份：&lt;code&gt;cp config/site.yaml /tmp/site.yaml.bak&lt;/code&gt;。&lt;/p&gt;
&lt;h3&gt;system/ 与 config/ 的分工&lt;a href=&quot;#system-与-config-的分工&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;目录&lt;/th&gt;&lt;th&gt;内容&lt;/th&gt;&lt;th&gt;升级影响&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;config/personal.yaml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;站点名称、作者、URL 等&lt;/td&gt;&lt;td&gt;不受影响（git 忽略）&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;config/site.yaml&lt;/code&gt;&lt;/td&gt;&lt;td&gt;完整站点配置&lt;/td&gt;&lt;td&gt;会被丢弃重建&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code&gt;system/&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Caddy、systemd 配置&lt;/td&gt;&lt;td&gt;不受影响（git 忽略）&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2&gt;十一、追番页面&lt;a href=&quot;#十一追番页面&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;追番页（&lt;code&gt;/bangumi&lt;/code&gt;）从 Bangumi.tv &lt;strong&gt;实时拉取&lt;/strong&gt;你的收藏，不需要手工维护数据。&lt;/p&gt;
&lt;h3&gt;配置&lt;a href=&quot;#配置&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;只需要一个 bgm.tv 用户名（或数字 ID）：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;# config/personal.yaml&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;bangumi&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  userId&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; x24moe&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;然后：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./sync.sh&lt;/span&gt;&lt;span&gt;      # 写入 site.yaml&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./build.sh&lt;/span&gt;&lt;span&gt;     # 发布&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;&lt;strong&gt;怎么找 userId&lt;/strong&gt;：登录 bgm.tv，打开自己的个人主页，地址栏 &lt;code&gt;https://bgm.tv/user/xxxxx&lt;/code&gt; 里的 &lt;code&gt;xxxxx&lt;/code&gt; 就是用户名。数字 ID 在「设置 → 个人资料」里也能看到。&lt;/p&gt;
&lt;h3&gt;数据来源&lt;a href=&quot;#数据来源&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;项&lt;/th&gt;&lt;th&gt;说明&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;接口&lt;/td&gt;&lt;td&gt;&lt;code&gt;https://api.bgm.tv/v0/users/{userId}/collections&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;认证&lt;/td&gt;&lt;td&gt;不需要 token，公开收藏直接可读&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;请求方&lt;/td&gt;&lt;td&gt;&lt;strong&gt;浏览器端&lt;/strong&gt;（&lt;code&gt;client:load&lt;/code&gt;），不经过本站服务器&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;分页&lt;/td&gt;&lt;td&gt;每页 50 条，最多 20 页（上限 1000 条）&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;抓取类型&lt;/td&gt;&lt;td&gt;动画、书籍、音乐、游戏、三次元（有数据才显示对应 tab）&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;封面&lt;/td&gt;&lt;td&gt;&lt;code&gt;lain.bgm.tv&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;因为没有服务端参与，API 的速率限制和可用性直接由你的浏览器承受，本站不产生流量。&lt;/p&gt;
&lt;h3&gt;bgm.tv 更新后如何生效&lt;a href=&quot;#bgmtv-更新后如何生效&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;不需要重新构建，也不需要重启服务。&lt;/strong&gt;&lt;/p&gt;
&lt;p&gt;数据是每次打开页面时实时请求的：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;在 bgm.tv 把某部番标记为「看过 / 在看 / 想看」&lt;/li&gt;
&lt;li&gt;回到博客打开 &lt;code&gt;/bangumi/&lt;/code&gt;，或直接刷新页面&lt;/li&gt;
&lt;li&gt;新数据立即出现&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;如果没变化，按 &lt;code&gt;Ctrl + F5&lt;/code&gt; 强制刷新，绕过浏览器缓存。&lt;/p&gt;
&lt;p&gt;已确认组件没有任何客户端缓存：&lt;code&gt;useBangumiData&lt;/code&gt; 的 &lt;code&gt;useEffect&lt;/code&gt; 依赖 &lt;code&gt;[userId, trigger]&lt;/code&gt;，每次挂载都会重新拉取全部类型；也没有使用 &lt;code&gt;localStorage&lt;/code&gt; 或 &lt;code&gt;sessionStorage&lt;/code&gt;。API 响应头为 &lt;code&gt;cf-cache-status: BYPASS&lt;/code&gt;，Cloudflare 不缓存。&lt;/p&gt;
&lt;h3&gt;什么时候才需要重新构建&lt;a href=&quot;#什么时候才需要重新构建&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;只有改了&lt;strong&gt;配置&lt;/strong&gt;才需要：&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;改动&lt;/th&gt;&lt;th&gt;需要的操作&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;追番内容变化（标记新番）&lt;/td&gt;&lt;td&gt;无需操作，刷新即可&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;换 &lt;code&gt;userId&lt;/code&gt;&lt;/td&gt;&lt;td&gt;&lt;code&gt;./sync.sh &amp;amp;&amp;amp; ./build.sh&lt;/code&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;改导航显示名或图标&lt;/td&gt;&lt;td&gt;同上&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;主题升级&lt;/td&gt;&lt;td&gt;&lt;code&gt;./update.sh&lt;/code&gt; 自动处理（&lt;code&gt;personal.yaml&lt;/code&gt; 会重建配置）&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3&gt;可选的显示项&lt;a href=&quot;#可选的显示项&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;&lt;code&gt;site.yaml&lt;/code&gt; 的 &lt;code&gt;bangumi&lt;/code&gt; 段还支持两个字段，默认被注释：&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;bangumi&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  userId&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; x24moe&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  label&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; 追番&lt;/span&gt;&lt;span&gt;              # 导航显示名称&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  icon&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; ri:bilibili-fill&lt;/span&gt;&lt;span&gt;   # Iconify 图标&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;要启用就在 &lt;code&gt;personal.yaml&lt;/code&gt; 里一起写上，&lt;code&gt;sync.sh&lt;/code&gt; 会一并写入。注意 &lt;code&gt;site.yaml&lt;/code&gt; 里这两行原本是注释状态，同步脚本只替换已存在的字段，不会自动解除注释——需要手动去掉 &lt;code&gt;#&lt;/code&gt; 后再跑 sync。&lt;/p&gt;
&lt;h3&gt;关闭追番页面&lt;a href=&quot;#关闭追番页面&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;代码里 &lt;code&gt;bangumi.astro&lt;/code&gt; 有 &lt;code&gt;if (!bangumiConfig) return Astro.redirect(&apos;/404&apos;)&lt;/code&gt;，所以只要 &lt;code&gt;site.yaml&lt;/code&gt; 里没有 &lt;code&gt;bangumi&lt;/code&gt; 段，页面和导航就会自动隐藏。&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;长期关闭的完整做法&lt;/strong&gt;（否则升级后会被 &lt;code&gt;personal.yaml&lt;/code&gt; 重新写回）：&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;从 &lt;code&gt;config/personal.yaml&lt;/code&gt; 删掉 &lt;code&gt;bangumi:&lt;/code&gt; 段&lt;/li&gt;
&lt;li&gt;编辑 &lt;code&gt;config/site.yaml&lt;/code&gt;，注释掉整个 &lt;code&gt;bangumi:&lt;/code&gt; 段&lt;/li&gt;
&lt;li&gt;&lt;code&gt;./build.sh&lt;/code&gt;&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;数据不显示怎么排查&lt;a href=&quot;#数据不显示怎么排查&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;# 1. 账号是否存在&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; -s&lt;/span&gt;&lt;span&gt; &quot;https://api.bgm.tv/v0/users/x24moe&quot;&lt;/span&gt;&lt;span&gt; |&lt;/span&gt;&lt;span&gt; head&lt;/span&gt;&lt;span&gt; -c&lt;/span&gt;&lt;span&gt; 120&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 2. 是否有收藏数据&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; -s&lt;/span&gt;&lt;span&gt; &quot;https://api.bgm.tv/v0/users/x24moe/collections?subject_type=2&amp;amp;limit=1&quot;&lt;/span&gt;&lt;span&gt; \&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  |&lt;/span&gt;&lt;span&gt; node&lt;/span&gt;&lt;span&gt; -e&lt;/span&gt;&lt;span&gt; &quot;let s=&apos;&apos;;process.stdin.on(&apos;data&apos;,d=&amp;gt;s+=d).on(&apos;end&apos;,()=&amp;gt;{const j=JSON.parse(s);console.log(&apos;total:&apos;,j.total)})&quot;&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;# 3. 构建产物里是否注入了 userId&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;curl&lt;/span&gt;&lt;span&gt; -s&lt;/span&gt;&lt;span&gt; http://192.168.8.169:8080/bangumi/&lt;/span&gt;&lt;span&gt; |&lt;/span&gt;&lt;span&gt; grep&lt;/span&gt;&lt;span&gt; -o&lt;/span&gt;&lt;span&gt; &apos;x24moe&apos;&lt;/span&gt;&lt;span&gt; |&lt;/span&gt;&lt;span&gt; head&lt;/span&gt;&lt;span&gt; -1&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;p&gt;三条都正常但页面仍空白，打开浏览器控制台看是否有 CORS 或网络错误。API 的 CORS 是 &lt;code&gt;allow-origin: *&lt;/code&gt;，正常情况下不会被拦截。&lt;/p&gt;
&lt;h3&gt;一个已知限制&lt;a href=&quot;#一个已知限制&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;p&gt;页面会同时请求 5 种类型（动画/书籍/音乐/游戏/三次元），每种最多 20 页。如果你的收藏非常多（单类型超过 1000 条），超出部分不会显示。&lt;/p&gt;</content:encoded><category>category:笔记</category><category>tag:运维</category><category>tag:教程</category><category>tag:部署</category></item><item><title>Markdown 渲染测试报告</title><link>https://koharu.cosine.ren/post/markdown-render-test</link><guid isPermaLink="false">markdown-render-test</guid><description>本文用于验证 astro-koharu 在当前部署环境下的 Markdown 渲染是否完整。每个小节对应一个能力项，可直接对照页面显示效果。
一、测试清单</description><pubDate>Wed, 18 Nov 2026 07:10:00 GMT</pubDate><content:encoded>&lt;p&gt;本文用于验证 astro-koharu 在当前部署环境下的 Markdown 渲染是否完整。每个小节对应一个能力项，可直接对照页面显示效果。&lt;/p&gt;
&lt;h2&gt;一、测试清单&lt;a href=&quot;#一测试清单&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;



















































































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;序号&lt;/th&gt;&lt;th&gt;能力项&lt;/th&gt;&lt;th&gt;语法来源&lt;/th&gt;&lt;th&gt;预期结果&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;标题层级&lt;/td&gt;&lt;td&gt;标准 MD&lt;/td&gt;&lt;td&gt;h2–h6 正常 + 锚点&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;文本样式&lt;/td&gt;&lt;td&gt;标准 + Shoka&lt;/td&gt;&lt;td&gt;样式生效不串行&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;3&lt;/td&gt;&lt;td&gt;列表嵌套&lt;/td&gt;&lt;td&gt;标准 MD&lt;/td&gt;&lt;td&gt;缩进层级正确&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;4&lt;/td&gt;&lt;td&gt;任务列表&lt;/td&gt;&lt;td&gt;GFM&lt;/td&gt;&lt;td&gt;复选框可显示&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;5&lt;/td&gt;&lt;td&gt;表格对齐&lt;/td&gt;&lt;td&gt;GFM&lt;/td&gt;&lt;td&gt;左/中/右对齐&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;6&lt;/td&gt;&lt;td&gt;代码高亮&lt;/td&gt;&lt;td&gt;Shiki&lt;/td&gt;&lt;td&gt;多语言着色&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;7&lt;/td&gt;&lt;td&gt;数学公式&lt;/td&gt;&lt;td&gt;KaTeX&lt;/td&gt;&lt;td&gt;行内与块级渲染&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;8&lt;/td&gt;&lt;td&gt;图表&lt;/td&gt;&lt;td&gt;Mermaid&lt;/td&gt;&lt;td&gt;SVG 绘制成功&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;9&lt;/td&gt;&lt;td&gt;图片&lt;/td&gt;&lt;td&gt;Astro Image&lt;/td&gt;&lt;td&gt;LQIP 占位&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;10&lt;/td&gt;&lt;td&gt;容器块&lt;/td&gt;&lt;td&gt;directive&lt;/td&gt;&lt;td&gt;样式区块&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;11&lt;/td&gt;&lt;td&gt;内联 HTML&lt;/td&gt;&lt;td&gt;rehype-raw&lt;/td&gt;&lt;td&gt;原样输出&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;12&lt;/td&gt;&lt;td&gt;加密内容&lt;/td&gt;&lt;td&gt;自定义插件&lt;/td&gt;&lt;td&gt;需密码解锁&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2&gt;二、标题层级&lt;a href=&quot;#二标题层级&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;下面是三到六级标题，均会自动生成锚点，可点击标题右侧链接直达。&lt;/p&gt;
&lt;h3&gt;三级标题&lt;a href=&quot;#三级标题&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;h4&gt;四级标题&lt;a href=&quot;#四级标题&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h4&gt;
&lt;h5&gt;五级标题&lt;a href=&quot;#五级标题&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h5&gt;
&lt;h6&gt;六级标题&lt;a href=&quot;#六级标题&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h6&gt;
&lt;h2&gt;三、文本样式&lt;a href=&quot;#三文本样式&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;基础样式：&lt;strong&gt;粗体&lt;/strong&gt;、&lt;em&gt;斜体&lt;/em&gt;、删除线、&lt;code&gt;行内代码&lt;/code&gt;、&lt;a href=&quot;https://astro.build&quot;&gt;外部链接&lt;/a&gt;、&lt;strong&gt;粗体里嵌 &lt;em&gt;斜体&lt;/em&gt; 再嵌 &lt;code&gt;代码&lt;/code&gt;&lt;/strong&gt;。&lt;/p&gt;
&lt;p&gt;Shoka 扩展样式：&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;高亮：&lt;mark&gt;这段文字应该带高亮背景&lt;/mark&gt;&lt;/li&gt;
&lt;li&gt;下划线：这段文字应该带下划线&lt;/li&gt;
&lt;li&gt;上标与下标：水的化学式 H&lt;sub&gt;2&lt;/sub&gt;O，质能方程 E=mc^2&lt;/li&gt;
&lt;li&gt;注音：&lt;ruby&gt;漢字&lt;rp&gt;(&lt;/rp&gt;&lt;rt&gt;かんじ&lt;/rt&gt;&lt;rp&gt;)&lt;/rp&gt;&lt;/ruby&gt; 应显示上方假名&lt;/li&gt;
&lt;li&gt;隐藏文字：鼠标悬停才显示 以及 &lt;span&gt;模糊效果&lt;/span&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;四、列表&lt;a href=&quot;#四列表&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;h3&gt;无序列表（三层嵌套）&lt;a href=&quot;#无序列表三层嵌套&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;第一层 A
&lt;ul&gt;
&lt;li&gt;第二层 A-1
&lt;ul&gt;
&lt;li&gt;第三层 A-1-a&lt;/li&gt;
&lt;li&gt;第三层 A-1-b&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;第二层 A-2&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;li&gt;第一层 B&lt;/li&gt;
&lt;/ul&gt;
&lt;h3&gt;有序列表（含混合嵌套）&lt;a href=&quot;#有序列表含混合嵌套&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;准备环境&lt;/li&gt;
&lt;li&gt;安装依赖
&lt;ol&gt;
&lt;li&gt;安装 Node 22&lt;/li&gt;
&lt;li&gt;安装 pnpm&lt;/li&gt;
&lt;/ol&gt;
&lt;/li&gt;
&lt;li&gt;构建站点&lt;/li&gt;
&lt;li&gt;启动服务&lt;/li&gt;
&lt;/ol&gt;
&lt;h3&gt;任务列表&lt;a href=&quot;#任务列表&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt; 部署 Node 运行时&lt;/li&gt;
&lt;li&gt; 安装项目依赖&lt;/li&gt;
&lt;li&gt; 首次构建通过&lt;/li&gt;
&lt;li&gt; 完成渲染验证&lt;/li&gt;
&lt;li&gt; 撰写正式内容&lt;/li&gt;
&lt;/ul&gt;
&lt;h2&gt;五、表格&lt;a href=&quot;#五表格&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;左对齐&lt;/th&gt;&lt;th&gt;居中&lt;/th&gt;&lt;th&gt;右对齐&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;a&lt;/td&gt;&lt;td&gt;b&lt;/td&gt;&lt;td&gt;1&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;较长的一列内容&lt;/td&gt;&lt;td&gt;中&lt;/td&gt;&lt;td&gt;22&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;x&lt;/td&gt;&lt;td&gt;y&lt;/td&gt;&lt;td&gt;333&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2&gt;六、引用&lt;a href=&quot;#六引用&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;blockquote&gt;
&lt;p&gt;一级引用：静态站点在构建期把 Markdown 编译为 HTML。&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;二级引用：因此内容更新需要重新构建，而不是刷新页面。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;回到一级引用。&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2&gt;七、代码块&lt;a href=&quot;#七代码块&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;h3&gt;带标题与高亮行&lt;a href=&quot;#带标题与高亮行&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;div&gt;&lt;span&gt;greet.js&lt;/span&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;function&lt;/span&gt;&lt;span&gt; greet&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;)&lt;/span&gt;&lt;span&gt; {&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  // 下面三行应高亮&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  const&lt;/span&gt;&lt;span&gt; time &lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt; new&lt;/span&gt;&lt;span&gt; Date&lt;/span&gt;&lt;span&gt;()&lt;/span&gt;&lt;span&gt;.&lt;/span&gt;&lt;span&gt;toISOString&lt;/span&gt;&lt;span&gt;()&lt;/span&gt;&lt;span&gt;;&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  const&lt;/span&gt;&lt;span&gt; msg &lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt; `Hello, &lt;/span&gt;&lt;span&gt;${&lt;/span&gt;&lt;span&gt;name&lt;/span&gt;&lt;span&gt;}&lt;/span&gt;&lt;span&gt;`&lt;/span&gt;&lt;span&gt;;&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  return&lt;/span&gt;&lt;span&gt; {&lt;/span&gt;&lt;span&gt; msg&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;span&gt; time &lt;/span&gt;&lt;span&gt;};&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;}&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h3&gt;命令行提示符&lt;a href=&quot;#命令行提示符&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;pnpm&lt;/span&gt;&lt;span&gt; install&lt;/span&gt;&lt;span&gt; --frozen-lockfile&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;pnpm&lt;/span&gt;&lt;span&gt; build&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h3&gt;JSON&lt;a href=&quot;#json&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;{&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  &quot;&lt;/span&gt;&lt;span&gt;site&lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; &quot;astro-koharu&quot;&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  &quot;&lt;/span&gt;&lt;span&gt;renderer&lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; &quot;Astro 7&quot;&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;  &quot;&lt;/span&gt;&lt;span&gt;features&lt;/span&gt;&lt;span&gt;&quot;&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; [&lt;/span&gt;&lt;span&gt;&quot;gfm&quot;&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;span&gt; &quot;katex&quot;&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;span&gt; &quot;mermaid&quot;&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;span&gt; &quot;shiki&quot;&lt;/span&gt;&lt;span&gt;]&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;}&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h3&gt;Python&lt;a href=&quot;#python&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;def&lt;/span&gt;&lt;span&gt; fib&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;n&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;span&gt; int&lt;/span&gt;&lt;span&gt;)&lt;/span&gt;&lt;span&gt; -&amp;gt;&lt;/span&gt;&lt;span&gt; list&lt;/span&gt;&lt;span&gt;[&lt;/span&gt;&lt;span&gt;int&lt;/span&gt;&lt;span&gt;]:&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;    seq &lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt; [&lt;/span&gt;&lt;span&gt;0&lt;/span&gt;&lt;span&gt;,&lt;/span&gt;&lt;span&gt; 1&lt;/span&gt;&lt;span&gt;]&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;    while&lt;/span&gt;&lt;span&gt; len&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;seq&lt;/span&gt;&lt;span&gt;)&lt;/span&gt;&lt;span&gt; &amp;lt;&lt;/span&gt;&lt;span&gt; n&lt;/span&gt;&lt;span&gt;:&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;        seq&lt;/span&gt;&lt;span&gt;.&lt;/span&gt;&lt;span&gt;append&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;seq&lt;/span&gt;&lt;span&gt;[&lt;/span&gt;&lt;span&gt;-&lt;/span&gt;&lt;span&gt;1&lt;/span&gt;&lt;span&gt;]&lt;/span&gt;&lt;span&gt; +&lt;/span&gt;&lt;span&gt; seq&lt;/span&gt;&lt;span&gt;[&lt;/span&gt;&lt;span&gt;-&lt;/span&gt;&lt;span&gt;2&lt;/span&gt;&lt;span&gt;])&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;    return&lt;/span&gt;&lt;span&gt; seq&lt;/span&gt;&lt;span&gt;[:&lt;/span&gt;&lt;span&gt;n&lt;/span&gt;&lt;span&gt;]&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;print&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;fib&lt;/span&gt;&lt;span&gt;(&lt;/span&gt;&lt;span&gt;10&lt;/span&gt;&lt;span&gt;))&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;
&lt;h2&gt;八、数学公式&lt;a href=&quot;#八数学公式&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;行内公式：质能等价 &lt;span&gt;&lt;span&gt;E=mc2E = mc^2&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;E&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;m&lt;/span&gt;&lt;span&gt;&lt;span&gt;c&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;2&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;，欧拉恒等式 &lt;span&gt;&lt;span&gt;eiπ+1=0e^{i\pi} + 1 = 0&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;e&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;iπ&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;+&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;1&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;0&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;。&lt;/p&gt;
&lt;p&gt;块级公式：&lt;/p&gt;
&lt;span&gt;&lt;span&gt;&lt;span&gt;∫−∞∞e−x2 dx=π\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;∫&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;−&lt;/span&gt;&lt;span&gt;∞&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;∞&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;​&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;e&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;−&lt;/span&gt;&lt;span&gt;&lt;span&gt;x&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;2&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;d&lt;/span&gt;&lt;span&gt;x&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;π&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;​&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;
&lt;p&gt;矩阵：&lt;/p&gt;
&lt;span&gt;&lt;span&gt;&lt;span&gt;(abcd)(xy)=(ax+bycx+dy)\begin{pmatrix}
a &amp;amp; b \\
c &amp;amp; d
\end{pmatrix}
\begin{pmatrix}
x \\
y
\end{pmatrix}
=
\begin{pmatrix}
ax + by \\
cx + dy
\end{pmatrix}&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;(&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;a&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;c&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;​&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;b&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;d&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;​&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;)&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;(&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;x&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;y&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;​&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;)&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;=&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;(&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;a&lt;/span&gt;&lt;span&gt;x&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;+&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;b&lt;/span&gt;&lt;span&gt;y&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;c&lt;/span&gt;&lt;span&gt;x&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;+&lt;/span&gt;&lt;span&gt;&lt;/span&gt;&lt;span&gt;d&lt;/span&gt;&lt;span&gt;y&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;​&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;&lt;span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;span&gt;&lt;span&gt;)&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;
&lt;h2&gt;九、Mermaid 图表&lt;a href=&quot;#九mermaid-图表&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;h3&gt;流程图&lt;a href=&quot;#流程图&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;pre&gt;flowchart LR
    A[编写 Markdown] --&amp;gt; B[pnpm build]
    B --&amp;gt; C{构建成功?}
    C --&amp;gt;|是| D[输出 dist]
    C --&amp;gt;|否| E[查看日志]
    E --&amp;gt; A
    D --&amp;gt; F[Caddy 提供服务]&lt;/pre&gt;
&lt;h3&gt;时序图&lt;a href=&quot;#时序图&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;pre&gt;sequenceDiagram
    participant U as 浏览器
    participant C as Caddy
    participant F as dist 文件
    U-&amp;gt;&amp;gt;C: GET /post/note/markdown-render-test
    C-&amp;gt;&amp;gt;F: 读取 HTML
    F--&amp;gt;&amp;gt;C: 返回内容
    C--&amp;gt;&amp;gt;U: 200 OK&lt;/pre&gt;
&lt;h3&gt;饼图&lt;a href=&quot;#饼图&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h3&gt;
&lt;pre&gt;pie title 内容类型占比
    &quot;技术笔记&quot; : 45
    &quot;生活随笔&quot; : 30
    &quot;项目记录&quot; : 15
    &quot;其他&quot; : 10&lt;/pre&gt;
&lt;h2&gt;十、图片&lt;a href=&quot;#十图片&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;图片应带有 LQIP 占位，加载完成后淡入：&lt;/p&gt;
&lt;figure&gt;&lt;img src=&quot;/img/cover/3.webp&quot; alt=&quot;示例封面&quot; loading=&quot;lazy&quot; /&gt;&lt;figcaption&gt;示例封面&lt;/figcaption&gt;&lt;/figure&gt;
&lt;h2&gt;十一、容器块&lt;a href=&quot;#十一容器块&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;div&gt;
&lt;p&gt;信息块：这是 &lt;code&gt;:::info&lt;/code&gt; 容器的渲染效果。&lt;/p&gt;
&lt;/div&gt;
:::tip
提示块：如果该容器未生效，会退化为普通段落文本，不影响构建。
:::
&lt;div&gt;
&lt;p&gt;警告块：用于强调需要注意的内容。&lt;/p&gt;
&lt;/div&gt;
&lt;h2&gt;十二、内联 HTML&lt;a href=&quot;#十二内联-html&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;键盘按键：&lt;kbd&gt;Ctrl&lt;/kbd&gt; + &lt;kbd&gt;C&lt;/kbd&gt; 可中断前台进程。&lt;/p&gt;
&lt;p&gt;内联高亮标签：&lt;mark&gt;这段由 mark 标签标记&lt;/mark&gt;。&lt;/p&gt;

点击展开（details 折叠）
&lt;p&gt;折叠内部的内容，验证原生 HTML 是否被保留。&lt;/p&gt;

&lt;h2&gt;十三、加密内容&lt;a href=&quot;#十三加密内容&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;下面这段使用 AES-256-GCM 在构建期加密，密码为 &lt;code&gt;demo&lt;/code&gt;：&lt;/p&gt;
&lt;div&gt;&lt;/div&gt;
&lt;h2&gt;十四、脚注&lt;a href=&quot;#十四脚注&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;静态站点在构建期完成渲染[&lt;sup&gt;build]，因此页面打开速度与数据库无关[&lt;/sup&gt;static]。&lt;/p&gt;
&lt;hr /&gt;
&lt;h2&gt;结论&lt;a href=&quot;#结论&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;以上各节若均按预期显示，说明渲染管线（Markdown → remark/rehype → Astro → HTML）完整可用。&lt;/p&gt;
&lt;p&gt;如果某一项显示为原始文本（例如 &lt;code&gt;:::info&lt;/code&gt; 原样出现），说明该容器语法在当前版本未启用，但不影响其他内容构建。&lt;/p&gt;</content:encoded><category>category:笔记</category><category>tag:Markdown</category><category>tag:测试</category></item><item><title>周刊 Vol.2：一次构建到底慢在哪里</title><link>https://koharu.cosine.ren/post/weekly-vol-2</link><guid isPermaLink="false">weekly-vol-2</guid><description>本周做了一件很基础的事：把构建耗时拆开看，确认哪一步在拖后腿。
拆解结果
首次构建总耗时 7 分 23 秒，其中：

























阶段耗时说明渲染页面约 4 分钟300 多页 Markdown 转 HTML图片优化2 分 47 秒108 张图转</description><pubDate>Wed, 11 Nov 2026 14:30:00 GMT</pubDate><content:encoded>&lt;p&gt;本周做了一件很基础的事：把构建耗时拆开看，确认哪一步在拖后腿。&lt;/p&gt;
&lt;h2&gt;拆解结果&lt;a href=&quot;#拆解结果&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;首次构建总耗时 7 分 23 秒，其中：&lt;/p&gt;

























&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;阶段&lt;/th&gt;&lt;th&gt;耗时&lt;/th&gt;&lt;th&gt;说明&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;渲染页面&lt;/td&gt;&lt;td&gt;约 4 分钟&lt;/td&gt;&lt;td&gt;300 多页 Markdown 转 HTML&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;图片优化&lt;/td&gt;&lt;td&gt;2 分 47 秒&lt;/td&gt;&lt;td&gt;108 张图转 avif/webp 多尺寸&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;pagefind 索引&lt;/td&gt;&lt;td&gt;约 8 秒&lt;/td&gt;&lt;td&gt;全文搜索索引&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;真正的大头是图片。每张图要生成多个尺寸、两种格式，总计超过 400 个变体。&lt;/p&gt;
&lt;h2&gt;缓存的价值&lt;a href=&quot;#缓存的价值&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;第二次构建只用了 2 分 13 秒，因为图片全部命中缓存（日志里显示 &lt;code&gt;reused cache entry&lt;/code&gt;），图片阶段从 2 分 47 秒降到 1.04 秒。&lt;/p&gt;
&lt;p&gt;这意味着：&lt;strong&gt;只要不改图片，日常写文章的构建成本其实只有 2 分钟左右&lt;/strong&gt;。之前担心的「改一句话等 8 分钟」，只会在新增或替换图片时出现。&lt;/p&gt;
&lt;h2&gt;一点体会&lt;a href=&quot;#一点体会&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;性能问题先别猜，把耗时按阶段列出来，答案通常很直接。这次如果不是拆开看，很容易误以为是 Astro 本身慢，从而做出错误的技术选型判断。&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;# 观察图片是否命中缓存&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;grep&lt;/span&gt;&lt;span&gt; &apos;reused cache entry&apos;&lt;/span&gt;&lt;span&gt; /tmp/build&lt;/span&gt;&lt;span&gt;*&lt;/span&gt;&lt;span&gt;.log&lt;/span&gt;&lt;span&gt; |&lt;/span&gt;&lt;span&gt; wc&lt;/span&gt;&lt;span&gt; -l&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;</content:encoded><category>category:周刊</category><category>tag:周刊</category><category>tag:性能</category></item><item><title>周刊 Vol.1：把博客从 Docker 搬回裸机</title><link>https://koharu.cosine.ren/post/weekly-vol-1</link><guid isPermaLink="false">weekly-vol-1</guid><description>这是周刊的第一期，记录本周把博客部署从 Docker Compose 换回主机直装的过程与判断依据。
起因
原本用四个容器（CMS、预览、静态站、构建器）编排，能跑，但每次改一行配置都要面对镜像层、命名卷、Compose 的 profiles</description><pubDate>Wed, 04 Nov 2026 13:00:00 GMT</pubDate><content:encoded>&lt;p&gt;这是周刊的第一期，记录本周把博客部署从 Docker Compose 换回主机直装的过程与判断依据。&lt;/p&gt;
&lt;h2&gt;起因&lt;a href=&quot;#起因&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;原本用四个容器（CMS、预览、静态站、构建器）编排，能跑，但每次改一行配置都要面对镜像层、命名卷、Compose 的 &lt;code&gt;profiles&lt;/code&gt; 这些额外概念。更麻烦的是一次批量清理把容器和镜像一起删了，恢复要重建 1.75 GB 镜像。&lt;/p&gt;
&lt;h2&gt;判断&lt;a href=&quot;#判断&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;这台设备是 4 核 Cortex-A55 加 3.7 GB 内存，Docker 的隔离收益几乎为零，而更新成本很高：依赖变化就要重建镜像，实测 14 分 51 秒。换成主机直装后，同样是装依赖，&lt;code&gt;pnpm install&lt;/code&gt; 只要 4 分 29 秒，而且没有镜像层这一层抽象。&lt;/p&gt;
&lt;h2&gt;结果&lt;a href=&quot;#结果&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;现在架构是 Node 运行时加一个 Caddy 静态服务器，Caddy 常驻只占 13 MB 内存。故障面从「Docker daemon + 镜像层 + Compose 编排 + 容器被误删」缩减到「Node 进程 + 一个反向代理」。&lt;/p&gt;
&lt;h2&gt;一点体会&lt;a href=&quot;#一点体会&quot;&gt;&lt;span&gt;&lt;/span&gt;&lt;/a&gt;&lt;/h2&gt;
&lt;p&gt;工具带来的便利是有成本的，成本通常体现为「出问题时要多理解一层」。对单机个人服务来说，把这一层去掉往往更划算。&lt;/p&gt;
&lt;div&gt;&lt;div&gt;&lt;/div&gt;&lt;pre&gt;&lt;code&gt;&lt;span&gt;&lt;span&gt;# 现在的发布流程&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;cd&lt;/span&gt;&lt;span&gt; /vol1/www/astro-koharu&lt;/span&gt;&lt;/span&gt;
&lt;span&gt;&lt;span&gt;./build.sh&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;</content:encoded><category>category:周刊</category><category>tag:周刊</category><category>tag:部署</category></item></channel></rss>