二次元宅男录

斗破127集夯爆了

Sat, 31 Oct 2026 14:25:00 GMT

无论是感情戏还是打斗群像都是夯爆了。经费炸裂，斗破官方你的钱花不完了是吧？给我爽到了。NB这样就让我很期待双帝之战了。这集已经没有什么可挑的，爽爆了。

1275

1268

1267

文章目录滑不动？锅在 flex，账在我头上

Sun, 11 Oct 2026 12:30:00 GMT

这周又攒了两个问题一起修：一个是 PC 端文章页的目录滑不动，一个是后台的内容列表慢半拍。两件事八竿子打不着，但排查完发现它们的剧本出奇地像——表面症状和真正的病灶，隔了好几层。老规矩，把过程记下来，给下次的自己抄作业。

一、目录滑不动：先给滚动条洗清冤屈#

现象很朴素：文章长了以后，PC 端右侧的目录显示不全，底部直接被裁掉，滚轮放上去毫无反应。移动端没事，就 PC 有。

我的第一反应是滚动条样式的问题——毕竟这个站的滚动条定制过，透明度调得很低，第一眼确实看不见。改了半天透明度，滚动条是看得见了，但目录还是滚不动。看得见摸不着，那就不是样式的问题。

回头把侧栏的布局翻出来看，才找到真凶。侧栏是个纵向 flex 容器，外面套着 max-height 和 overflow-y: auto，意图很直白：最多这么高，装不下就内部滚动。但 flex 有个不太直觉的默认行为——子元素默认 flex-shrink: 1，容器装不下的时候，所有子元素会按比例被压扁。

也就是说：目录卡片、作者卡片这些加起来比视口高的时候，flex 先做的不是触发外层滚动，而是把每个卡片均匀压扁。目录内容被裁掉一截之后，卡片内部的高度刚好没超出——没超出，自然就没得滚，滚动条委屈地认为「我没有活干」。

修复反而简单得可笑：

1
/* 子卡片禁止收缩，装不下就让侧栏整体滚 */
2
#left-sidebar-sticky > *,
3
#right-sidebar-sticky > * {
4
  flex-shrink: 0;
5
}

一行 CSS，目录恢复滑动。写这段布局的时候，我大概默认了「装不下就会滚动」，但 flex 的收缩优先级排在溢出前面。这个默认值，坑过的大概不止我一个。

二、修完压缩，又撞上「弹回去」#

以为完事了，实测时冒出了更迷惑的现象：我把目录往下滚到想看的小节，松手不到一秒，它自己弹回去了。

这个就不是 CSS 了，是交互逻辑打架。目录有个「自动跟随」功能——页面滚到哪个小节，目录就把对应条目滚到可视区中间，之前写的，一直工作得挺好。问题在于它太尽职：我手动滚动目录这个动作，在它眼里和「用户翻了页面」没区别，下一帧就坚持把活动项拉回中间。我的手和它的逻辑，只能活一个。

解法是给「用户的手」加发言权：在目录上监听 wheel 和 touchmove，一旦检测到手动滚动就打个时间戳，四秒之内自动跟随闭嘴：

1
private userScrollingUntil = 0;
2
private readonly markUserScrolling = () => {
3
  this.userScrollingUntil = Date.now() + 4000;
4
};
5

6
// scrollToActiveItem 开头：
7
if (Date.now() < this.userScrollingUntil) return;

四秒是试出来的。太短的话页面稍微一滚它又开始抢方向盘，太长的话点到新小节时目录跟不上趟。

顺手还对了另外两笔账：侧栏的 top 和 max-height 之前是各写各的，底部会超出视口几十像素，这次对齐了；滚动条透明度也从「隐身模式」调回到肉眼可见——一个用户看不见的滚动条等于没有滚动条，这是我第一节白忙活半小时换来的觉悟。

三、后台慢半拍：接口在替 git 排队#

第二个问题是后台的内容列表越用越慢，刷新一次要等好几秒，网络不好的时候直接超时。

排查时先看接口本身——查询逻辑没什么毛病，本地数据读取快得很。但每个读接口在干活之前都先干了一件事：同步一次内容仓库。当初的思路是「读之前先拉最新，保证内容新鲜」，听起来很负责，代价是每次请求都背一次网络往返。列表页一打开，好几个接口排着队跑网络。同步快的时候几百毫秒，慢的时候——就是你看到的转圈圈。

修复思路一句话：把慢的东西从关键路径上挪走。仓库同步不再跟着请求走，改成后台线程自己定期做，同步加硬超时，防止哪次网络抽风把线程挂死在一个请求上：

1
def _repo_sync_loop(interval=45):
2
    while True:
3
        try:
4
            gitops.pull()
5
        except Exception:
6
            pass  # 这轮失败了下轮再来，别影响主流程
7
        time.sleep(interval)

同步周期 45 秒。对个人后台来说，「内容最多延迟一分钟」和「每次打开都等几秒」之间，根本不用犹豫。改完之后列表页的响应从秒级等待回到毫秒级，终于像个本地工具该有的样子。

写在最后#

两件事修完，发现教训居然是同一句话：

症状出现在哪里，病灶不一定在哪里。看得见的问题（滚不动）可能藏在看不见的布局默认值里；等得起的耗时（内容同步）不该出现在等不起的地方（接口路径上）。

再补一条给写 CSS 的自己：flex 的默认值不会「大概按我想的来」。flex-shrink 这个属性我看了很多年，第一次真正理解它，是在自己博客的目录滚不动的那天。

我给博客换了链接，然后它挂了一早上

Thu, 01 Oct 2026 08:30:00 GMT

这周折腾了两件事，本来不想写成文章，但第二件事实在太有戏剧性——我把博客的链接全部翻新了一遍，第二天凌晨它就挂了九个小时。两件事还挺有因果关系的味道，一起记下来。

一、链接翻新：从「能访问」到「有规律」#

原来的链接有多随意#

先自曝家丑。这个站原来的链接长这样：

1
文章：/posts/how-i-built-this-blog/
2
标签：/archive/?tag=%E9%9A%8F%E7%AC%94
3
分类：/archive/?category=%E6%8A%80%E6%9C%AF

文章 slug 是标题转的英文，长短随缘；标签和分类点开更离谱——%E9%9A%8F%E7%AC%94 这是「随笔」的 URL 编码，一串百分号乱码，别说访客看不懂，搜索引擎对这种查询参数式链接也不太待见：它本质上是归档页的过滤参数，不是独立页面，没有自己的权重。

文章改数字编号#

第一个决定：文章 slug 全部改成纯数字，/posts/1/、/posts/2/，按发布顺序排。理由很简单——短、整齐、永远不重名。缺点是链接没了语义，但对个人博客来说，标题在列表和搜索结果里都有展示，URL 里那点语义没那么值钱。

改的时候给自己挖了个坑：旧链接全部 301 重定向到新地址，这个做了；但文章正文里的互相引用忘了改——三篇技术文互相链接用的还是旧 slug，全站扫描死链的时候才暴露出来。顺手把关于页里一个指向不存在的 /posts/ 的入口也修成了归档页。

教训：改 URL 结构，扫描器跑一遍全站比肉眼靠谱得多。全站 1928 个站内链接，人工根本看不过来。

分类标签建独立页面#

这是更大的一块。原主题根本没有分类详情页，所谓「点标签」就是跳归档页带个过滤参数。这次直接新建了两类静态页面：

1
分类：/categories/ji-shu/    （技术）
2
标签：/tags/sui-bi/          （随笔）

slug 的规则：中文转全拼小写，英文原样，短横线分隔。看名字就能拼出 URL，以后打新标签也自动按这个规则生成页面，规律是死的，不会因为手滑打出新格式。

实现上用的是 pinyin-pro（主题本来就带了）在构建期转换，页面静态生成、自动进 sitemap，每个分类和标签从此都有了自己可收录的落地页。

顺手把图压了#

审计图片的时候发现相册里有四张原图是原样发布的：一张 1.5MB 的 PNG、两张快 1MB 的 JPG。全部转成 WebP（质量 85，肉眼无感），整个相册从 4.2MB 降到 1.76MB，减了 58%。

二、宕机九小时：一次教科书级的连锁反应#

链接翻新的第二天凌晨 06<44>，博客挂了。而且不是慢，是完全打不开，一直挂到下午。

时间线还原#

翻了系统日志，链条其实很短：

1
06:44:05  系统自动安全更新（unattended-upgrade）启动，升级 openssl
2
06:44:18  openssl 是 nginx 的依赖库 → 触发 nginx 自动重启
3
06:44:18  重启瞬间 DNS 抖动：配置里的封面代理域名 t.alcy.cc 解析失败
4
06:44:18  nginx -t 报错：host not found in upstream → 启动失败
5
（然后呢？然后就没有然后了）

两个问题叠加成了九小时的宕机：

第一，nginx 启动时要解析配置里所有的 upstream 域名。 平时这不是问题，但「启动的那一刻 DNS 抖了一下」就够了——DNS 恢复后配置完全正常，可 nginx 已经躺在那里不会自己爬起来。

第二，nginx 的 systemd 重启策略是 Restart=no。 Ubuntu 的默认值。失败不重试，一次失败就是永久失败。

最讽刺的是：我明明有每分钟跑的监控脚本、有每 5 分钟的部署兜底任务，但没有任何一个东西负责「发现 nginx 挂了就把它拉起来」。监控和数据都在，就差最后一步。

三层修复#

修的时候就没打算只修「这一次」：

第一层，根治启动依赖。 封面代理的 upstream 改成「变量 + resolver」：

1
resolver 223.5.5.5 119.29.29.29 valid=300s ipv6=off;
2
set $alcy_upstream "t.alcy.cc";
3
rewrite ^/cover-proxy/alcy/(.*)$ /$1 break;
4
proxy_pass https://$alcy_upstream;

用变量做 upstream 时，域名解析推迟到运行时——启动时不再碰 DNS。以后 DNS 再抖，最坏也就是那一次封面图请求 502，nginx 本体稳如泰山。有个小坑：proxy_pass 带变量时不会自动剥离 location 前缀，必须手动 rewrite 补上，不然转发路径就是错的。

第二层，自动拉起。 给 nginx 的 systemd 加了 Restart=on-failure，挂掉 5 秒后自动重试。就算再来一次同样的故障，DNS 恢复的几秒内它就自己站起来了。

第三层，看门狗。 监控脚本旁边加了一个每分钟跑的看门狗：nginx 或后台服务不是 active 就直接拉起，写日志。它不聪明，但足够愣——专治各种「以为它会自己好」。

零损失的安慰#

复盘时最庆幸的一点：宕机的九个小时里没有发布任何内容，最后一次部署停在宕机前一晚，所有数据完好。而且部署兜底任务走的是 cron 直连，根本不经过 nginx——就算那九小时里我发了文章，内容也会照常上线，只是没人看得到而已。

写在最后#

这次折腾完，两件原本不相干的事最后落在了同一个认知上：

「它能跑」和「它挂了我能立刻知道、立刻站起来」是两码事。前者叫功能，后者才叫运维。

链接是给人和搜索引擎看的，规律比个性重要；服务是给凌晨四点的自动更新折腾的，兜底比侥幸重要。文章里如果有你也用得上的东西，欢迎翻翻这个系列的其他几篇——现在它们都在 /posts/1/ 到 /posts/6/ 里，链接干净得很。

博客正式上线了

Mon, 28 Sep 2026 04:30:00 GMT

🎉域名ICP备案总算是顺利通过啦!我的小站终于可以正式和大家见面咯～已经把备案等待期间写的所有文章都迁移过来啦，其实从提交备案申请那天开始，我就已经动笔攒内容了，熬到今天备案落地、完成全站迁移，说起来今天是正式开站的日子，但其实站子早在备案第一天就悄悄搭好骨架咯😂😂😂

这或许是最有性价比，最便捷的4k掌上副屏方案—索尼xzp

Thu, 24 Sep 2026 16:14:00 GMT

效果图#

国际惯例先来效果图

xzp

把我的4K老手机折腾成电脑副屏#

折腾起因：吃灰多年的日版神机#

我的日版手机自从百来块淘来之后，就一直在吃灰。4+64的存储配上骁龙835，根本带不动日常应用，更带不动这块4K屏幕。而且因为日版不能解锁，还无法全局开启4K。

转折：论坛发现可解锁#

但是逛了逛论坛，发现居然可以解锁了！解锁之后就刷EVO系统开全局4K。不过日版刷了会直接掉基带，只能刷回原版，没办法的事。

这配置应该也没人当主力机用了，我干脆把包里的谷歌全家桶、打电话拨号这些占用的东西全部删除，系统分区只剩1个多G，但还是很卡。

我也尝试过第三方开源开发的应用，虽然有全局4K，但手机性能还是带不动——看一会儿B站视频就卡、发热非常严重。

灵机一动：让电脑性能来带它#

既然手机性能带不动，那就拿电脑性能带它，当电脑副屏！毕竟这货可是实打实的4K呀。

我自己做了个模块配合 Spacedesk 使用，模块的作用大致是：

走 USB 连接
开机插线自动启动、自动连接显示
保证连接使用过程中屏幕不息屏

其实做模块的话，理论上可以实现不依靠第三方软件，直接当正常的显示屏连接。但是有点麻烦，所以怎么方便怎么来。

使用感受：很爽，但有两个缺陷#

电池容量太小，只能插线（不过电池容量大的话也只能插线，详情看第2点）
屏幕最高只有60Hz，还不能跑满，平均只能跑到50多

那这有什么用？#

肯定会有人问：花这么大劲折腾，到底有什么用？

我电脑是七彩虹橘宝 R16 Pro 2.5K屏，正好缺个4K屏看动漫追剧。但是当初选笔记本就是图便捷携带，不可能花大价钱去买一个4K显示屏——那样太不性价比，带起来也吃力。

不过索尼XZP这个屏幕尺寸真的非常适合看日漫，还是可以接受的。主要还是方便、便宜。

那发不发热呢？#

多多少少都会有点小热，可以接受。

使用模式#

使用场景	设备
游戏模式	自带屏
看番追剧	XZP

温馨提示：本文为设备折腾经验的分享，刷机、解锁、ROOT 等操作可能带来数据丢失、设备变砖、保修失效等风险，请务必在充分了解并备份后再操作。

论现代的奇葩脑回路

Thu, 24 Sep 2026 10:34:00 GMT

前几天和一位打游戏认识的高中年龄段女网友聊天，得知她和男朋友分手了——谈了七个月，散了。

这本不算什么稀奇事，现在这个年代，分分合合跟换头像一样频繁。真正让我愣住的是后面那段对话。

我问她怎么分的。她倒也不避讳，说早就在和自己的男闺蜜走得很近，聊天聊到半夜、周末单独出去吃饭看电影，男友介意，提了出来，吵了几次，最后就分了。我说，那你男闺蜜知道你们这个关系吗？她理直气壮：“我们只是好朋友啊，他是我男闺蜜，清清白白的。”

我不知道现在的社会到底怎么了。我不知道我接下来的话算不算苛责，但我真的想问：这个世界上，真的有男人能坦然接受自己的另一半，和另一个男生保持这种”比朋友近一点、比恋人远一点”的关系吗？

她整个人浑身上下都写着”我没做错什么”。我不明白我这一句话是不是不该说，但她反过来给我讲起了道理：时代变了，男女之间有纯友谊，是我思想老古董，是把人想得太龌龊。

那一刻我忽然意识到，我们俩讲的可能根本不是一回事。她讲的是”我又没出轨”，我讲的是”边界感”。

触网太早，心智没跟上#

放在几年前，我大概只会把这事归结为”人各有志”。但她是高中年龄段的人，这让我多想了一层：现在的未成年人，触网实在太早了。

我们这一代人，小时候顶多玩玩单机游戏，情感观是摔了跟头才慢慢长出来的。而现在的小孩，小学就有了自己的手机，短视频、社交平台无缝切换，成年世界的情感模式——暧昧、养鱼、快餐式恋爱——隔着屏幕直接灌进还没长好的心智里。

社会发展太快，环境一天一个样，但人的心智是要靠时间和经历一寸一寸长出来的。接受的信息量是成年的，处理信息的心智是未成年的，中间这道落差，就是各种”奇葩脑回路”的生长土壤。

她们不是不聪明，是太早学会了太多概念，却没机会真正理解那些概念背后的分量。“边界感""情绪价值""独立自我”，张口就来，可这些东西要踩过坑才懂。

不是奔着爱去的，是为新鲜感买单#

再回到她这件事本身。琢磨了几天，我的评价其实就一句话：她这段感情，从头到尾都不是奔着爱去的，而是在为自己的新鲜感买单。

恋爱七个月，男闺蜜全程在线；男友介意了，先沟通的明明是男友，她却把自己摘得干干净净。在她的逻辑里，恋爱是体验项目，男朋友是体验的一部分，男闺蜜也是体验的一部分，谁让她觉得新鲜、谁让她情绪舒服，她就往谁那边靠。

至于爱？爱是要负责任的，是要为对方收敛自由的，是要在”新鲜感消退”之后依然选择留下来的。而这些恰恰是网络短视频从来不教的部分——短视频只教”心动”，不教”守约”；只教”做自己”，不教”顾别人”。

新鲜感驱动的感情有个共同结局：热度一过，就要找下一个刺激源。这次是男闺蜜，下次还可以是别人。男朋友换了一个又一个，其实换的从来不是人，是那口新鲜气。

边界感不是清白，是分寸#

她一直在强调”清清白白”——没牵手、没接吻、没越界，所以没问题。但感情里的边界感，从来不是用法律标准来衡量的。

深夜的专属聊天、只对彼此说的悄悄话、电视剧里男女主角才有的相处模式，这些东西一样都没”越界”，但每一样都在把本该属于伴侣的情绪价值，外包给另一个人。恋爱里的安全感是有限的，你往外面漏一点，留给自己伴侣的就少一点。

说白了：出轨是结果，越界是过程。等到有”结果”的时候，早就不知道越了多少次界了。

讲道理讲不通的根源#

最让我无语的其实不是她的行为，而是那个逻辑闭环：

你提出疑问 → 她说你不信任她 → 你解释你介意的是相处模式 → 她说那是你的问题，她问心无愧 → 最后你反而成了那个”思想有问题”的人。

绕了一圈，话题从”这事合不合适”变成了”你心态好不好”。只要她一口咬定自己清白，任何讨论都无法进行——因为她根本不觉得这件事有讨论的必要。

后来我想通了：讲道理的前提，是双方承认同一套标准。她那套标准里，“没实质越界”就是满分答案；而我这套标准里，“让伴侣感到不安还毫不在意”本身就是问题。标准都不同，道理是讲不通的。

写在最后#

我不太担心她一个人，我担心的是这种状态不是个例。触网太早的一代正在批量长大，网络教给他们一整套成熟的恋爱话术，却没人在意他们有没有成熟的心智去撑起这些话术。

如果你也遇到了这样的人，别急着讲道理，先问自己一个问题：你要的是这个人，还是这段关系里随时会漏风的安全感？

想清楚这个，答案其实就不难选了。

《败犬女主》第 8、8.5、9 卷品鉴：全员神人，只有温八正常

Tue, 22 Sep 2026 12:10:00 GMT

这三卷我是连着读完的：台版实体书到手，先捧着把第八卷翻完，又连夜补完 8.5 和第九卷的汉化。

合上书的感受一句话就能说完：这三卷里，除了温八，没一个正常的。

第八卷，老马把话挑明；8.5 卷，全员假装无事发生；第九卷，樱井三人组把”神人”两个字焊死在书页上。而温水和八奈见，从头到尾都像误闯片场的一对正常少男少女——正常吃饭，正常拌嘴，正常地谁也不敢把那层纸捅破。

本篇全程剧透，三卷一起聊。没读到的朋友先去补课，回来我们接着品。

第八卷：老马的告白，全书最正面的一击#

第八卷主线是生徒会选举，马剃天爱星的政治题材。说实话选举本身我看得中规中矩，直到最后一击。

卷末，天爱星把话挑明了。我是捧着台版实体书读到这一段的——第 290 页，插画里老马双手交握在胸前，脸红得不行：

台版《敗北女角太多了！》第八卷第 290 页：老马告白的名场面

然后是这两句：

“温水同学，我喜欢你。”
“当然我指的是恋爱的喜欢。你愿意和我交往吗？”

不绕弯子，不打哑谜，是全系列到目前为止最正面、最不留退路的一次进攻。温水的内心是：

“我——被告白了。”
“只会在小说中出现过的事件，我现在成为当事人，在我眼前发生。”

注意，他没有拒绝。到第八卷收尾为止，这个答案就那么空着——这一空，就空出了整个 8.5 卷。

老马这一击的含金量，要放在”败犬”的坐标系里看：这个系列里其他女生表达喜欢的方式，是自动翻译、是天台让路、是”我不碍事”；只有天爱星，是把话放到台面上等你接。僵尸系学姐，全书唯一的直球选手。就冲这一段，第八卷封神不亏。

8.5 卷：全员悬置，温水的不体面现场#

8.5 卷是短篇集，讲告白之后的日常——或者说，讲所有人怎么假装那场告白没发生过。

最损的一场戏：老八主动开口试探温水——“温水君——怎么看马剃同学？“温水打个哈哈不接。然后八奈见顺着台阶自己翻译：”……如果那么想的话，我们也不能妨碍你啊。”

翻译翻译：你敢喜欢她，我就退出。

看，这就是败犬。试探完了，先替你把退路铺好，顺便把自己的心再埋深一寸。而温水两头都不敢接：不敢对老马的告白给答案，也不敢接老八递过来的那个”我不碍事”。他心里的自动翻译倒是转得飞快，把每一句危险发言都翻译成安全的日常对话，翻完糊弄过去，装作无事发生。

短篇集的好处在这里体现得淋漓尽致：告白之后的每一段日常，读者都知道底下压着什么，但角色们个个若无其事。这种全桌人都在装傻的悬置感，比任何误会冲突都折磨人——折磨的同时，糖也是真没停过。温水和老马的关系在微妙地升温，温水和老八的相处也在微妙地变味，所有人都在”少しずつ”（一点点地）动。

而全卷糖分最高的一场戏，我必须单拎出来讲：8.5 卷加笔短篇《把秘密塞进口袋》，老八和烧盐在社办边啃鱿鱼干边复习的日常回。八奈见一边嘎吱嘎吱嚼着鱿鱼干，一边状似无意地开口试探：”……那个呀，那天晚上你和温水君一起出去了对吧？“——名古屋那一晚，她记到现在。结果试探没进行三句，烧盐头都没抬，反手就是一枪：“测验结束后不是有花火大会吗……我要不要约阿温呢？”

老八当场僵住，连”咦”都是破音的。烧盐还嫌不够，收尾补刀：“事后才慌张的话，我可不管哦。“我读到这段直接拍腿：平时看烧盐是文艺部吉祥物，真坐上感情牌桌，她才是全场牌最顺的人——句句装傻，句句带刺，把老八那点”若无其事式试探”的小心思一次性击穿。老八最后只能借口买奶茶落荒而逃。

但这篇真正的杀招在结尾。温水把老八叫住，支支吾吾、眼神乱飘，手还下意识往她手边碰——八奈见内心都开始 “某种事件正在发生”了，紧张到整理头发。结果递过来的，是一块虎鲸形状的名古屋特产最中饼：“八奈见同学从名古屋回来时想买，但是没钱买不了吧？我买来当给家里人的土产，所以想分你一个。”

她以为要被告白，结果是点心。气得当场炸毛：“你的问题就出在这里！温水君！”

可下一秒，她把最中饼塞进口袋，丢下一句”不是说要对大家保密吗”，脚步轻盈地走了。标题的”秘密”就藏在这——品品这个细节：温水的温柔从来不走嘴，他记得的是老八在名古屋盯着最中饼却没钱买的那一眼。对一个从小让球让到大、连贪吃都要顾着面子的姑娘来说，有人默默接住她这点小心思，比一百句情话都致命。而且你把 8.5 的这块最中饼和 9 卷旅馆那句”可是我的啊”连起来看，根本是同一套连招：先让她尝到糖，再让她喊出心声。雨森老贼，你小子是懂饲养败犬的。

然后第九卷告诉你：装傻是要还的。

第九卷·温八篇：全员神人中唯一的正常糖#

第九卷主线看起来很扯：樱井的女友小春想跟樱井”制造既成事实”，拉五个人搞飞驒高山旅行，计划让小两口错过末班车共处一室。结果樱井看穿一切淡定上车，真正错过末班车的是温水和八奈见——房订好了，就剩他俩。

同宿这一夜，雨森写得非常干净。没有越界，没有俗套的意外碰撞，就是两个高中生在同一家旅馆的同一间房里，尴尬、拌嘴、谁都不肯先睡、又谁都不舍得先睡。第二天早上那副鸡飞狗跳的样子——老八的表情管理当场碎掉，温水假装镇定其实耳朵通红——是我这半年来在轻小说里看到过的最好笑也最好嗑的一章。

然后是名场面。小春家出跑到温水家蹭住，当面质问八奈见：“我确认一下，八奈见同学没有和温水君交往吧？那么，我和温水君进旅馆也没问题吧？”

八大王当场破防：

“温水君可是我的啊？！”

喊完她自己僵在原地，双手乱摇：“不对不对不对，不是那个意思，你明白我的意思吧？”

分析一下这四秒钟。九卷以来，老八的人设是什么？是每一次心动都能自动翻译成”朋友”的嘴硬王者，是把”我们只是青梅竹马”当护身符的标准败犬。而这一句失态，是九年伪装的第一次系统报错——报错之后秒怂，怂完之后躲着温水好几天不敢见面。

这一连串反应比任何直球告白都真实。真心的流露从来不是设计好的告白，是防不住的那一句。而且你注意，她躲的不是丢脸，是”被他知道”——躲了好几天之后两个人又若无其事地聊回去了，谁都没提那一晚。这种默契的不提，比提了更甜。

还有一场隐藏高光：有人问温水”如果有人叫你不要见我，你会怎么做”，他的回答绕开了所有人——连亲妹妹都可以摆到局外人位置去。这个嘴巴很严的男人，宁可把妹妹划出去，也没把八奈见划出去。答案早就在选择题里了，只是他不承认。

对照着看更有意思：老马在第八卷选择了最直球的告白，老八在第九卷只有靠破防才漏出半句真心。两个路线，两种败法。所以我说温八是这三卷里唯一的正常：正常的吃醋，正常的别扭，正常的装傻，正常的谁也不捅破——放在这群神人中间，这份正常甜得发光。

第九卷·神人组：樱井、小春、放虎原#

现在讲让我血压拉满的主线——这三个人，一个比一个神人。

先看他们的操作有多离谱。小春，樱井的女友，想跟男朋友更进一步，手段是委托男朋友的哥们儿帮忙设局制造既成事实；设局失败后直接家出，搬进这个哥们儿家里住了五天，用意是刺激男朋友。这五天里她还顺手把”我和温水进旅馆也没问题吧”甩在老八脸上。见了两面加一天旅行就敢上门住，“朋友妻”这个身份也太好用了——我第一次读到这儿，合上手机缓了半天。

但小春的离谱，是有账本的。回忆杀揭开的那一刻，我血压直接转向心酸——

初一那年的秋天，放虎原家里出事，父亲把哥哥逐出家门，撂下”别再跨进这个家门”。她一个人躲进田边小屋，在雨里哭。冒雨追来的是小学六年级的樱井，把自己的衣服脱下来借给淋透的她。然后——放虎原从背后环住他的手臂，樱井把手覆了上去。那一晚，两个人待到了天亮。

对，你们没看错，一个初一，一个小学六年级。这配置放在任何一部作品里都是重量级。

要我复述那一晚具体干了什么？我都不想说。主要是雨森也没让我有说的余地——写到”把手覆上去”就断章了！就这四个字，信息量直接拉满，剩下的全靠读者自己脑补。我盯着这段看了得有一分钟，脑子里只有一个声音：写清楚啊！……不对，你别写了，你还是留白吧，写清楚了我以后没法直视樱井了。

更绝的还在后面。两家父亲的反应速度，比这两人的感情进展快多了——第二天就为遗产撕破脸，一个喊”云雀诱拐了小学生弘人”，一个喊”我女儿被玷污了”。好家伙，恋爱还没个说法呢，大人已经把它换算成官司的筹码了。没有一个人问那两个孩子昨晚经历了什么，一个都没有。

在孩子们抱团取暖的地方，大人们只看得见把柄。吐槽归吐槽，这一段是真的狠——我见过很多写”大人丑恶”的，写这么直白的，这是头一份。

替孩子们收场的，又是另一个孩子。小春冲进骂战，一句”当时我也在场""我和弘人在交往”，把”诱拐”和”玷污”两个帽子同时摘了。她用一句编造的恋爱，给放虎原和樱井挡了刀——然后把自己钉死在这个谎上八年。

八年。她跟樱井的交往始于救场，不是始于喜欢。所以她才执着于”既成事实”，执着于”更进一步”——她要的不是那种事，是一个八年都没等到的确认：弘人心里到底有没有我。

樱井的回答？“等云雀姐毕业。”

让女朋友等另一个女人毕业。看到这儿我人都麻了——你逃避就逃避吧，你别两头抓啊。烟花大会上小春一头槌撞散了”再给我一次机会”，喊出分手，那一下我居然松了口气：八年了，这个女孩终于替自己喊了一次。

顺带一提，支线也神人浓度超标：姬宫听说温八同宿，专程跑来给温水”传授经验”，确认啥也没发生才闭嘴。这本书就没有正常人在谈恋爱。

三卷连评：一场安排好的过山车#

单独看，第八卷是政治+告白，8.5 是发糖短篇，第九卷是神人修罗场。但连起来看，你才发现这三卷是一个完整的结构：

第八卷把雷埋下（老马告白），8.5 卷把雷按住（全员悬置），第九卷在雷上跳舞（神人狂欢+温八突破）。

雨森的算计在于：老马的直球把温水的”迟钝”逼到失效，8.5 的悬置把温水”装糊涂”的成本越垒越高，到第九卷，樱井三人组直接给他看了一场”装糊涂二十年”的现场版——放虎原就是一个把喜欢烂在心里、计划毕业就离开丰桥的青梅竹马，这个配置跟老八像得我后背发凉。温水看着樱井线的结局，等于看着自己和小八的”如果放任不管”版本。

所以樱井线根本不是水剧情：那是杀鸡给猴看，鸡是樱井，猴是温水和屏幕前的我们。

打分的话：第八卷五星（告白一击封神），8.5 卷四星（糖管够但体量小），第九卷四星半（樱井线收得偏急，扣半星）。三卷连读的体验，五星。

最终评价还是那句话：

这三卷，除了温八能让我感到正常，其他人真的都太神人了。

老马的神人在于敢把所有败犬不敢说的话一口气说完；小春的神人、樱井的神人、放虎原的神人，在于把八年的错位谈成了一场谁也退不出困局；连姬宫都在支线里神人。全员疯批狂欢里，只有温泉旅馆那一夜的两个人，在认真地尴尬、认真地别扭、认真地不敢说。

第十卷，老马的答案不能再拖了，佳树要登场了，温八只差一个命名。台版实体书我已经开始收了——这三卷，值得摆在书架上。

零依赖服务器监控面板：不用现成工具，自己写一个

Mon, 21 Sep 2026 09:20:24 GMT

《从零搭建个人博客》里提过，我的服务器是 2 核 2G 的小机型。想在博客里放一个服务器状态面板，现成方案不少——beszel、netdata、dashdot 都很漂亮——但动辄吃掉几百 MB 内存，还得单独开端口、配登录。2G 内存的机器经不起这么造。

最后的方案：一段 bash 脚本 + 一段 Nginx 配置 + 一个博客页面，零依赖、零端口、零额外内存占用，效果见本站的「状态」页。这篇把完整实现过程和踩过的坑记录下来。

一、整体架构#

先想清楚数据从哪来、到哪去：

1
┌─ 服务器 ────────────────────────────┐
2
│  monitor.sh（cron 每 30 秒）          │
3
│    ↓ 读 /proc 内核数据，算出指标       │
4
│    ↓ 写成 JSON 文件（原子替换）        │
5
│  Nginx 把这个 JSON 以固定路径暴露      │
6
└──────────────┬──────────────────────┘
7
               ↓ HTTP（浏览器 fetch）
8
┌─ 博客页面 ──────────────────────────┐
9
│  JS 每 30 秒拉取 JSON → 渲染卡片       │
10
└────────────────────────────────────┘

关键认识：数据采集根本不需要 SSH，也不需要在浏览器端连服务器。脚本跑在服务器本地，读 /proc 虚拟文件——那是内核自己维护的运行时账本，数据最权威。浏览器端只是一个普通 HTTP 请求拉 JSON。

二、第一步：采样脚本#

完整脚本如下，可以直接抄（保存为 /opt/server-mon/monitor.sh，记得 chmod +x）：

1
#!/usr/bin/env bash
2
# 读取 /proc 生成服务器状态 JSON，由 cron 定时执行
3
set -u
4
OUT=/var/www/mon/status.json
5
STATE=/var/lib/server-mon/prev.txt
6

7
# 自动识别默认网卡
8
IFACE=$(ip route show default 2>/dev/null | awk '{print $5; exit}')
9
[ -z "${IFACE:-}" ] && IFACE=eth0
10

11
# --- CPU 计数器 ---
12
read -r _ user nice system idle iowait irq softirq steal _ < /proc/stat
13
CPU_TOTAL=$((user + nice + system + iowait + irq + softirq + steal + idle))
14
CPU_BUSY=$((user + nice + system + iowait + irq + softirq + steal))
15

16
# --- 内存 ---
17
memtotal=$(awk '/^MemTotal:/{print $2}' /proc/meminfo)
18
memavail=$(awk '/^MemAvailable:/{print $2}' /proc/meminfo)
19

20
# --- 磁盘（根分区）---
21
dtotal=$(df -kP / | tail -1 | awk '{print $2}')
22
dused=$(df -kP / | tail -1 | awk '{print $3}')
23
davail=$(df -kP / | tail -1 | awk '{print $4}')
24

25
# --- 网络计数器 ---
26
RX=$(grep "^[[:space:]]*$IFACE:" /proc/net/dev | awk '{print $2}')
27
TX=$(grep "^[[:space:]]*$IFACE:" /proc/net/dev | awk '{print $10}')
28

29
# --- 负载 / 运行时长 ---
30
load1=$(cut -d' ' -f1 /proc/loadavg)
31
UPTIME=$(cut -d. -f1 /proc/uptime)
32
TS=$(date +%s)
33

34
# --- 读上次采样，算差值 ---
35
prev_ct=0; prev_cb=0; prev_rx=0; prev_tx=0; prev_ts=0
36
[ -f "$STATE" ] && read -r prev_ct prev_cb prev_rx prev_tx prev_ts < "$STATE"
37

38
dct=$((CPU_TOTAL - prev_ct)); dcb=$((CPU_BUSY - prev_cb))
39
drx=$((RX - prev_rx));        dtx=$((TX - prev_tx))
40
dt=$((TS - prev_ts))
41
[ "$dt"  -lt 1 ] && dt=1
42
[ "$dtx" -lt 0 ] && dtx=0
43
[ "$drx" -lt 0 ] && drx=0
44

45
if [ "$prev_ts" -eq 0 ] || [ "$dct" -le 0 ]; then
46
  cpu_pct=-1; rx_s=0; tx_s=0
47
else
48
  cpu_pct=$(awk -v b="$dcb" -v t="$dct" 'BEGIN{p=b/t*100; if(p<0)p=0; if(p>100)p=100; printf "%.1f", p}')
49
  rx_s=$(awk -v r="$drx" -v t="$dt" 'BEGIN{printf "%.1f", r/t/1024}')
50
  tx_s=$(awk -v r="$dtx" -v t="$dt" 'BEGIN{printf "%.1f", r/t/1024}')
51
fi
52

53
printf '%s %s %s %s %s\n' "$CPU_TOTAL" "$CPU_BUSY" "$RX" "$TX" "$TS" > "$STATE"
54

55
MEM_PCT=$(awk -v t="$memtotal" -v a="$memavail" 'BEGIN{printf "%.1f", (t>0)? (t-a)/t*100 : 0}')
56
DISK_PCT=$(awk -v u="$dused" -v a="$davail" 'BEGIN{t=u+a; printf "%.1f", (t>0)? u/t*100 : 0}')
57
TOTRX=$(awk -v r="$RX" 'BEGIN{printf "%.2f", r/1073741824}')
58
TOTTX=$(awk -v t2="$TX" 'BEGIN{printf "%.2f", t2/1073741824}')
59

60
mkdir -p /var/www/mon
61
# 注意：JSON 里刻意不写主机名、IP、网卡名，避免泄露服务器信息
62
printf '{"ts":%s,"uptime":%s,"load1":"%s","cpu":{"usage":%s},"mem":{"total_kb":%s,"avail_kb":%s,"used_pct":%s},"disk":{"total_kb":%s,"used_kb":%s,"used_pct":%s},"net":{"rx_kbps":%s,"tx_kbps":%s,"total_rx_gb":%s,"total_tx_gb":%s}}\n' \
63
  "$TS" "$UPTIME" "$load1" "$cpu_pct" "$memtotal" "$memavail" "$MEM_PCT" \
64
  "$dtotal" "$dused" "$DISK_PCT" "$rx_s" "$tx_s" "$TOTRX" "$TOTTX" > "$OUT.tmp"
65
mv "$OUT.tmp" "$OUT"

展开收起

几个准确性设计，都是查过资料才定的：

CPU 用两次计数差值，不是瞬时值。 /proc/stat 的 CPU 时间是开机以来的累计值，单次读没有任何意义。脚本把上次计数存在 prev.txt，这次减上次，差值才是这段时间的真实占用率。这也是为什么页面刚上线时 CPU 会显示几秒的 ”…”——第一次运行还没有差值，用 -1 标记，前端识别后显示省略号而不是错误数据。

内存用 MemAvailable 口径。 Linux 会把空闲内存拿去做文件缓存（buff/cache），free 命令里的”可用”就是 MemAvailable：等于空闲 + 可回收缓存。用它算占用率才贴近真实体验，直接拿 MemTotal - MemFree 会把缓存算成”已用”，2G 机器看起来永远 90%+。

磁盘百分比和 df 命令同口径。 有两种算法：used/total 和 used/(used+avail)。后者才是 df 命令显示的那个百分比——因为 total 里含一部分 root 保留块（普通用户写不进去），分母用 used+avail 才不会把面板显示得比实际乐观。

JSON 用「写临时文件 + mv」原子替换。 如果前端 fetch 的瞬间脚本正写到一半，会拿到半截 JSON 直接解析报错。先写 .tmp 再 mv，mv 在同一分区是原子操作，任何时刻文件都是完整的。

计数器回绕保护。 服务器重启后 /proc/net/dev 的流量计数会归零，差值算出负数，[ "$dtx" -lt 0 ] && dtx=0 把它钳到 0，面板不会出现负速率。

三、第二步：定时采样#

cron 最小粒度是一分钟，想要 30 秒采样有个经典技巧——一条规则里执行两次，第二次延后半分钟：

Terminal window

1
* * * * * /opt/server-mon/monitor.sh >/dev/null 2>&1; sleep 30; /opt/server-mon/monitor.sh >/dev/null 2>&1

用 crontab -e 添加后，crontab -l 确认。采样间隔缩短一半有两个好处：网速/CPU 的统计窗口更短，短时突发流量更能捕捉到；页面每 30 秒刷新时每次都能拿到新数据，而不是同样的数字看一分钟。

脚本的差值逻辑天然支持任意间隔（用实际时间差 dt 做除数），所以就算 cron 延迟几分钟跑，速率计算依然准确。

四、第三步：Nginx 暴露数据#

JSON 文件在 /var/www/mon/status.json，在站点 Nginx 配置里加一个 location：

1
# 路径里那串随机字符是「路径令牌」，防止端点被扫描，需与博客配置一致
2
location ^~ /server-status/<随机令牌>/ {
3
    alias /var/www/mon/;
4
    add_header Cache-Control "no-store";
5
    add_header X-Robots-Tag "noindex, nofollow" always;
6
}

三个细节：

no-store：状态数据永远不能被缓存，否则访客看到的是几分钟前的旧数据；
noindex, nofollow：告诉搜索引擎不要收录这个数据端点；
路径令牌：JSON 的真实地址里拼一段随机字符串。改完 nginx -t 测试语法，再 systemctl reload nginx 平滑生效，站点不中断。

五、第四步：博客展示页#

页面是 Astro 写的（其他框架同理，核心就是 fetch + 渲染）。骨架：

1
const DATA_URL = "/server-status/<随机令牌>/status.json";
2
const REFRESH_SEC = 30;
3
const STALE_SEC = 180;      // 数据超过 3 分钟没更新视为异常
4
const WARN_THRESHOLD = 60;  // 占用 60% 进度条转黄
5
const HIGH_THRESHOLD = 85;  // 占用 85% 转红
6

7
async function refresh() {
8
  try {
9
    const res = await fetch(DATA_URL + "?t=" + Date.now(), { cache: "no-store" });
10
    if (!res.ok) throw new Error(res.status);
11
    const d = await res.json();
12
    render(d);  // 按 CPU/内存/磁盘/网络分块渲染
13
    const stale = Date.now() / 1000 - d.ts > STALE_SEC;
14
    setStatus(!stale, stale ? "数据延迟（采样服务可能异常）" : "运行正常");
15
  } catch {
16
    setStatus(false, "无法获取状态数据");
17
  }
18
}
19
refresh();
20
setInterval(refresh, REFRESH_SEC * 1000);

展开收起

?t=时间戳 是防止浏览器或中间层自作聪明缓存请求。渲染上有两个容错设计：每个字段赋值前都判空，某个字段缺失只跳过那一处，不会让整个面板白屏；进度条按占用分三档变色（正常主题色 → 黄 → 红），一眼就能看出哪项吃紧。

六、第五步：配置化#

把所有参数收进博客的统一配置文件（src/config/index.ts 的「服务器状态」模块），页面和导航都从这里读：

1
export const serverStatusConfig = {
2
  enable: true,        // 总开关：关闭后导航隐藏入口，页面跳转 404
3
  title: "服务器状态",
4
  dataUrl: "...",      // 由路径令牌拼出
5
  refreshSec: 30,
6
  staleSec: 180,
7
  warnThreshold: 60,
8
  highThreshold: 85,
9
  cards: { cpu: true, mem: true, disk: true, net: true },  // 卡片开关
10
};

导航栏入口也写成条件渲染——enable 一关，导航上「状态」直接消失，不需要再改第二个文件。

七、关于防泄露#

面板数据是公开的（所有访客都能看），所以做了四层处理：

措施	防什么
JSON 路径拼随机令牌	扫描器批量猜 `/server-status/status.json` 这类常见路径，直接 404
`noindex` 响应头	搜索引擎不收录数据端点
JSON 字段脱敏	不输出主机名、IP、网卡名、系统版本，只有资源占用指标
总开关联动	关闭后整个站不再出现数据地址

要诚实说明边界：令牌会出现在网页源码里，所以它防的是扫描器和顺手试探，不防决心翻你源码的人。这是「隐藏入口」不是「加密认证」，对个人博客是成本收益比最高的一档。真要更严格，可以上 Nginx 的 secure_link 模块做签名校验，或者限制访问 IP——对个人博客来说通常没必要。

另外，想换令牌随时可以：改博客配置里的一处 + Nginx 配置里的一处，reload 即可，旧地址立刻作废，相当于换门牌号。

八、踩过的坑#

记录几个调试时真实撞上的问题：

Windows 编辑的脚本在 Linux 跑不了：报 integer expected。Windows 换行是 CRLF，bash 把 \r 当成了内容的一部分。修复：sed -i 's/\r$//' monitor.sh。写服务器脚本最好直接在服务器上用 nano/vim 写，或传完必跑一次这条命令。
网速永远是 0：/proc/net/dev 每行行首有空格，直接 awk -F'[: ]+' '{print $2}' 会把空字段算进去取错列。修复：先用 grep "^[[:space:]]*eth0:" 锁定网卡那一行，再用默认分隔符取列。
磁盘百分比和 df 对不上：算法口径问题，见前文，改用 used/(used+avail)。
内存显示 1.69 TB：前端单位换算错位——1048576 KB 是 1 GB 不是 1 TB，把 2G 内存显示成了 1.69 TB。修完的换算表：KB → 1024 → MB → 1024 → GB → 1024 → TB，写的时候直接把 1073741824 这类常数标注在代码注释里。
文章时间偏移 8 小时：CI 在 UTC 时区构建，frontmatter 里的时间不写时区就会被按 UTC 解析。修复：所有 published 明确写 +08:00。

九、小结#

这套面板的全部成本：约 70 行 bash + 一段 Nginx 配置 + 一个页面组件，运行时内存占用约等于零（脚本每 30 秒跑一次，跑完就退）。准确度上因为直接读内核数据、用差值法和标准口径，数字和 free、df 完全对得上。

适合的场景很明确：小内存服务器、想要和博客风格统一的轻量面板、不想多开端口和服务。如果你需要历史曲线、告警通知，那还是上 beszel 这类专业工具——但我 2G 的小机器，这个刚好。

系列文章：《从零搭建个人博客》 · 《blog 日常使用指南》

博客日常使用指南：写文章、发动态、加书签（自用记录）

Mon, 21 Sep 2026 04:07:42 GMT

上一篇《从零搭建个人博客》记录了怎么把站搭起来。这篇是手把手使用手册：每一步都给出可以直接复制的命令和模板，照着做就行，不用动脑子（划掉）不用查资料。

记住一个总原则：所有站点配置都集中在 src/config/index.ts 一个文件里（按模块分区、带编号注释），所有内容都在 src/content/ 目录下。改完保存，本地开发页面即时热更新。

第 0 步：把网站跑起来#

写文章之前，先让网站在本地转起来。只需要做一次。

1. 确认环境#

打开终端（Windows 用 PowerShell），分别输入这两条命令检查版本：

Terminal window

1
node -v   # 需要 v22.23 以上
2
pnpm -v   # 需要 11.22 以上

如果提示「不是内部或外部命令」，说明还没安装：去 nodejs.org 装 Node.js（会自带核心），再输入 npm install -g pnpm 装 pnpm。装完重开一个终端再检查一次。

2. 启动网站#

Terminal window

1
cd D:\blog\Firefly    # 换成你的项目文件夹路径
2
pnpm install          # 第一次运行才需要，安装依赖
3
pnpm dev              # 启动本地开发服务器

看到终端里出现 Local http://localhost:4321/ 就说明成功了。用浏览器打开这个地址，你看到的就是自己的网站。

热更新：只要 pnpm dev 开着，你改任何文件保存，浏览器页面会自动刷新。写文章时建议左边开编辑器、右边开浏览器，改一段看一眼。

按 Ctrl + C 停止开发服务器。

第 1 步：写第一篇文章#

文章放在哪里#

所有文章都是 src/content/posts/ 目录下的 Markdown 文件，一个 .md 文件就是一篇文章。不需要注册或登记，文件放进去就自动出现在首页、归档和 RSS 里。

目录按分类建了文件夹：

1
src/content/posts/
2
├── tech/     # 技术类：建站、教程、运维
3
├── daily/    # 日常随笔
4
└── anime/    # 追番相关

以后想加新分类，在 posts/ 下新建一个文件夹就行，不需要改任何配置。

方法一：用脚手架创建（推荐）#

在项目根目录的终端里执行（把 tech/my-first-post 换成你的文件名）：

Terminal window

1
pnpm new-post -- tech/my-first-post

这条命令会自动做三件事：

在 src/content/posts/tech/ 下创建 my-first-post.md；
写好 frontmatter 模板（标题、日期、slug 都是现成的）；
如果文件名里写了中文，会自动转成拼音作为 URL，比如 我的笔记 → wo-de-bi-ji。

文件名可以带子文件夹前缀（如 tech/xxx），也可以不带（直接生成在 posts/ 根目录，再手动挪进分类文件夹）。

方法二：手动创建#

在 src/content/posts/tech/ 里直接新建一个 我的文章.md，把下面的模板整个粘进去，然后按注释逐行改：

1
---
2
title: 我的第一篇文章            # 必填，显示在列表和浏览器标签页
3
published: 2026-09-22           # 必填，发布日期
4
description: 一两句话的摘要       # 建议填，列表页和分享卡会显示
5
tags: [建站, 随笔]               # 标签，方括号里逗号分隔，可以多个
6
category: 技术                  # 分类，和所在文件夹保持一致
7
draft: false                    # false = 正式发布；true = 草稿
8
slug: my-first-post             # 可选，自定义 URL；不填就用文件名
9
---
10

11
正文从这里开始，标准 Markdown 语法……

脚手架用户注意：pnpm new-post 生成的模板里有一行 image: ''（空值 = 不显示封面）。想要随机二次元封面，就把这一行删掉；想指定封面再填图片直链。

frontmatter 字段速查#

frontmatter 就是文件开头两行 --- 之间的那段 YAML，是文章的”身份证”。常用字段：

字段	必填	作用	说明
`title`	✅	文章标题	列表、页面标题都用它
`published`	✅	发布日期	决定排序和归档年份
`description`	建议	摘要	列表页显示；不填会截取正文开头
`tags`	可选	标签	`[标签A, 标签B]` 格式
`category`	建议	分类	一篇只归一类，建议与文件夹同名
`draft`	可选	草稿开关	`true` 只在本地预览可见，构建时排除
`slug`	建议	URL 地址	见下方「URL 规则」
`image`	可选	封面图	删掉这行 = 随机封面；填直链 = 指定封面；`''` = 无封面
`pinned`	可选	置顶	`true` 固定在文章列表最前面
`updated`	可选	最后编辑时间	改过文章后填新日期
`series`	可选	系列名	同名系列自动组成系列页，配合 `seriesOrder: 1` 排序
`password`	可选	访问密码	填了则文章加密，读者需输密码；`passwordHint` 可给提示

几个要点：

URL 规则：tech/docker-basics.md 不写 slug 时地址是 /posts/tech/docker-basics/；写了 slug: docker-basics 则是干净的 /posts/docker-basics/。建议每篇都写 slug，以后调整文件夹不影响链接；
中文文件名可以用（脚手架会自动转拼音），但手动建文件时建议文件名用英文短横线风格，URL 更好看；
时区坑点：published 只写日期没问题；如果精确到几点几分，必须写成 2026-09-21T09:00:00+08:00 带时区的格式。因为构建机在 GitHub 的 UTC 时区，不带时区会被当成 UTC，时间全部偏移 8 小时。

保存，看效果#

保存文件，浏览器（http://localhost:4321）会自动刷新——首页列表里出现你的新文章了。点进去检查排版，改到满意为止。

第 2 步：正文常用写法#

正文就是标准 Markdown，下面每种给一个最小可复制示例。

基础排版#

1
## 二级标题（一级标题留给文章大标题，正文从二级开始）
2

3
普通段落，**加粗**、*斜体*、~~删除线~~、`行内代码`。
4

5
- 无序列表项
6
- 另一项
7

8
1. 有序列表项
9
2. 另一项
10

11
> 引用块，适合放注意事项或台词
12

13
[链接文字](https://example.com)

图片#

1
![图片说明](https://example.com/photo.jpg)   # 网络图片，直接贴直链
2
![本地图片](/assets/images/photo.jpg)        # 本地图片放到 public/assets/images/ 下

代码块#

三个反引号开头，后面跟语言名：

1
```js
2
console.log("Hello, blog!");
3
```

支持语法高亮和复制按钮。超过 15 行的长代码会自动折叠（显示前 8 行 + 展开按钮），也可以在语言名后面写 collapse 手动控制。

提示框（callout）#

> [!类型] 开头的引用块会渲染成彩色提示框，支持五种类型：

1
> [!NOTE]
2
> 补充说明，蓝色。
3

4
> [!TIP]
5
> 小技巧，绿色。
6

7
> [!IMPORTANT]
8
> 重要信息，紫色。
9

10
> [!WARNING]
11
> 警告内容，黄色。
12

13
> [!CAUTION]
14
> 危险操作，红色。

表格#

1
| 姓名 | 作用 |
2
| --- | --- |
3
| Astro | 静态站点框架 |
4
| Svelte | 前端交互框架 |

数学公式#

1
行内公式：$E = mc^2$
2

3
独立公式块：
4
$$
5
\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}
6
$$

流程图（Mermaid）#

1
```mermaid
2
graph LR
3
    A[写文章] --> B[git push]
4
    B --> C[自动构建]
5
    C --> D[自动上线]
6
```

时序图（PlantUML）#

1
```plantuml
2
@startuml
3
游客 -> 网站 : 打开文章
4
网站 --> 游客 : 返回内容
5
@enduml
6
```

每篇文章自带的「AI 智能总结」#

文章页顶部有个「AI 智能总结」卡片，不需要你做任何事：

摘要在网站构建时用免费 AI 预先生成好，直接烘进页面，访客秒开；
只在你改了文章内容后，下次构建才会重新生成那篇的摘要；
开关、接口、字数、逐字特效等参数都在 src/config/index.ts 的「AI 总结」模块；
只在构建时把正文发给 AI 一次，不收集任何访客信息。

第 3 步：发布上线#

本地满意后，三连发布：

Terminal window

1
git add -A                                        # 1. 把所有改动放进暂存区
2
git commit -m "post: 新文章「我的第一篇文章」"       # 2. 打包成一个存档点
3
git push                                          # 3. 推送到 GitHub

推送后 GitHub 会自动构建，构建完成后服务器自动拉取上线，约两三分钟后刷新你的线上网站就能看到新文章——不需要登录服务器做任何操作。

修改已发布的文章也一样：改文件 → 重新三连即可，链接不变（这就是建议写 slug 的原因）。

常见问题排查#

改了内容但页面没变？

先确认 pnpm dev 还开着、浏览器开着的是 localhost:4321；
还不行就 Ctrl + C 停掉，重新 pnpm dev（改 frontmatter 后偶尔需要）；
再不行删掉项目根目录的 .astro 文件夹后重启——这是构建缓存，删了没副作用。

线上要等才生效？ 记住分界线：pnpm dev 里的改动只存在于你电脑；只有 git push 之后才会上线。另外改 src/config/index.ts 里的构建类配置（如 AI 总结），本地也要重新 pnpm build 才能验证。

发布日期不对？ 见上方时区坑点，时间精确到分时必须带 +08:00。

文章不想让人看到？ draft: true 转草稿，只在本地可见。

发动态#

动态是短内容随手记，和文章分开管理，存放在 src/content/dynamic/。

一行命令发一条：

Terminal window

1
pnpm new-dynamic -- "今天给博客加了个状态页，折腾了一下午，值！"

会在动态目录生成一个按时间命名的 .md 文件，内容就是你刚才输入的文字，published 时间自动填好。也可以手动建文件，frontmatter 只有两三个字段：

1
---
2
published: 2026-09-21T20:30:00+08:00   # 必填，精确到分记得带时区
3
pinned: false                          # 可选，true 置顶在动态流最前
4
location: 上海                         # 可选，显示在动态卡片上
5
---
6

7
这里写动态内容，支持 Markdown。图片地址写在正文里会自动渲染成图片墙。

小坑：删除或修改动态后页面没变化，是构建缓存问题——删掉 .astro 目录重启 pnpm dev 就好。

添加书签导航#

书签导航页（/booknav/）的数据在 src/config/index.ts 的「书签导航」模块，按「分类组 → 书签项」两级组织。把下面示例粘进去改成自己的书签即可：

1
export const booknavConfig: BooknavGroup[] = [
2
  {
3
    // —— 分类组 ——
4
    id: "dev", // 唯一标识
5
    name: "开发", // 分类名称
6
    icon: "material-symbols:code-rounded", // 分类图标（Iconify 格式）
7
    desc: "写代码时离不开的站点", // 分类描述，可省略
8
    weight: 100, // 排序权重，越大越靠前
9
    items: [
10
      {
11
        // —— 书签项 ——
12
        title: "MDN Web Docs",
13
        url: "https://developer.mozilla.org",
14
        desc: "最权威的 Web 技术文档", // 可省略
15
        weight: 9, // 组内排序
16
      },
17
      {
18
        title: "Astro 文档",
19
        url: "https://docs.astro.build",
20
      },
21
    ],
22
  },
23
];

展开收起

图标不用手动找图：书签项没写 icon 时会自动抓取目标站点的 favicon。

其他常用配置速查#

想做什么	改哪里
站名 / 副标题 / 主题色 / 域名	`src/config/index.ts` ① 站点基础（站名改 `SITE_TITLE` 一处即可）
头像 / 昵称 / 社交链接	`src/config/index.ts` ② 用户资料（首页横幅链接同步生效）
开关某个页面（如相册、友链）	① 站点基础里的 `pages` 字段
导航栏菜单与顺序	`src/config/index.ts` ④ 导航栏
侧边栏组件与顺序	`src/config/index.ts` ⑥ 侧边栏布局（桌面与移动端共用的组件在 `WIDGETS` 里改一处）
首页壁纸与横幅文案	`src/config/index.ts` ⑦ 背景壁纸
相册	`src/config/index.ts` ⑮ 相册 + 图片放 `public/gallery/`
页脚文字	`src/config/FooterConfig.html`
关于页 / 友链页	`src/content/spec/about.md` / `friends.mdx`

两个通用规律：

pages 开关是总闸：把某个页面设为 false，导航、sitemap 里都会自动消失，不用到处删链接；
图标统一用 Iconify 语法：图标集:图标名，如 material-symbols:home、fa7-brands:bilibili，全站通用。

把这篇当手册用：写文章走第 1～3 步，忘语法查第 2 步，出问题查 FAQ，改配置查速查表。后续有新的配置心得，我会持续更新这篇文章。

从零搭建个人博客：手把手完整教程与踩坑记录

Mon, 21 Sep 2026 01:24:17 GMT

这篇文章把我从零搭建这个博客的全过程记录下来：每一步怎么操作、用什么命令、为什么这么做、踩过哪些坑。照着做就能复现出一模一样的系统，也当作我自己的运维手册。

日常使用（写文章、发动态）在《博客日常使用指南》，这篇只讲「怎么把站搭起来、怎么自动化」。

全文涉及敏感信息的地方（服务器 IP、密码等）都用 <占位符> 代替，实际操作时替换成你自己的。

一、整体规划#

先想清楚要什么，再动手：

静态博客：文章是 Markdown，构建后是纯 HTML。没有数据库、没有后端、没有登录入口，黑不掉也慢不了，维护成本约等于零；
国内云服务器托管：文章推到 GitHub 仓库，GitHub Actions 构建完成后，服务器自动拉取构建产物上线，服务器只负责 Nginx 托管静态文件；
全自动发布：git push 之后构建、分发、上线全部自动，我只负责写文章。

技术栈一句话：Astro + Firefly 主题 + GitHub Actions + Git + Nginx。

二、环境准备#

我的本地环境是 Windows + PowerShell。需要装三样东西，每样都有验证方法。

1. Node.js（≥ 22）#

去 Node.js 官网下载 LTS 安装包，一路下一步。装完重开一个终端验证：

Terminal window

1
node -v   # 输出 v22.x.x 即可
2
npm -v

老版本不够就先卸载再装新版，Node 多版本共存工具（nvm-windows）是进阶玩法，入门没必要。

2. pnpm（≥ 11）#

Node 自带 npm，用它装 pnpm：

Terminal window

1
npm install -g pnpm
2
pnpm -v

坑点：如果项目用 .npmrc 锁定了 pnpm 版本，直接运行 pnpm 时它会自动切换到项目要求的版本，不用手动降级。

3. Git#

去 git-scm.com 下载安装，安装选项保持默认即可。第一次用 Git 需要配置身份（每条提交记录的署名）：

Terminal window

1
git config --global user.name "你的用户名"
2
git config --global user.email "你的邮箱"

坑点：Windows 下有些终端装完 Git 后找不到命令，重开一个终端窗口就好；还不行就把 Git 的 cmd 目录加进 PATH 环境变量。

三、初始化项目#

1. 拿到主题代码#

在 GitHub 上把 Firefly 主题仓库 Fork（或右上角 Use this template）到自己账号下，然后克隆到本地：

Terminal window

1
git clone https://github.com/<你的用户名>/<仓库名>.git
2
cd <仓库名>

建议直接在 GitHub 上把仓库设为 Private——文章草稿、服务器配置这些不需要公开。

2. 安装依赖并启动#

Terminal window

1
pnpm install    # 第一次运行，下载所有依赖，可能要几分钟
2
pnpm dev        # 启动本地开发服务器

浏览器打开 http://localhost:4321，看到主题默认首页就成功了。dev server 支持热更新：改代码保存，页面自动刷新。

3. 认识目录结构#

几千个文件里，你日常只需要碰这几处：

1
├── astro.config.mjs        # Astro 全局配置（构建、插件、trailingSlash 等）
2
├── src/
3
│   ├── config/
4
│   │   ├── index.ts        # ★ 站点所有配置都在这一个文件（按模块分区编号）
5
│   │   └── FooterConfig.html  # 页脚文字（唯一的例外）
6
│   ├── content/
7
│   │   ├── posts/          # ★ 文章（Markdown，按分类建文件夹）
8
│   │   ├── dynamic/        # 动态（短内容随手记）
9
│   │   └── spec/           # 关于页/友链页等固定页面
10
│   └── styles/             # 样式微调
11
└── public/                 # 纯静态资源（favicon、壁纸、相册图片）

记住一条：想改任何功能和文案，先打开 src/config/index.ts 找编号注释，九成能找到。

四、站点配置#

配置都是改 TypeScript 文件，保存即时生效。所有配置集中在 src/config/index.ts，按模块编号分区。

1. 站点基本信息（① 站点基础模块）#

1
// 站点名称：站点信息、导航栏标题、首页横幅共用这一处
2
const SITE_TITLE = "你的博客名";
3

4
export const siteConfig: SiteConfig = {
5
  title: SITE_TITLE,
6
  subtitle: "一句话简介",
7
  site_url: "https://你的域名.com",   // 有域名填域名，暂时没有可以先填 IP 方案
8
  themeColor: {
9
    hue: 220,          // 0-360 色相，一个数字全站变色（220 是蓝色）
10
    defaultMode: "light",
11
  },
12
  siteStartDate: "2026-09-20",       // 建站日期，页脚的运行天数从这里算
13
  // ...
14
};

pages 字段是各功能页的总闸，用不到的设为 false——导航、sitemap 里会自动消失，不用到处删链接：

1
const pages = resolvePageToggles({
2
  friends: true,     // 友链
3
  dynamic: true,     // 动态
4
  gallery: true,     // 相册
5
  booknav: true,     // 书签导航
6
  bilibili: true,    // 追番
7
});

2. 作者信息（② 用户资料模块）#

头像图片放进 src/assets/images/，然后在配置里引用：

1
export const profileConfig: ProfileConfig = {
2
  avatar: "assets/images/avatar.png",
3
  name: "你的昵称",
4
  bio: "一句话介绍自己",
5
  links: [
6
    // 图标用 Iconify 格式，showName: false 只显示图标
7
    { name: "QQ群", icon: "fa7-brands:qq", url: "https://qm.qq.com/xxx", showName: false },
8
    { name: "Email", icon: "fa7-solid:envelope", url: "mailto:你的邮箱" },
9
  ],
10
};

这份 links 会同时用在侧边栏资料卡和首页横幅上，只改这一处。

3. 其他常用模块#

配置文件里每个模块都有中文注释，改之前读一遍注释就够了。我启用了几个值得一说的：

AI 总结（⑩）：构建时调用免费 AI 接口给每篇文章生成摘要，无需密钥，参数都在注释里；
随机封面（⑪）：文章不写 image 字段就自动配随机二次元封面，图源是按顺序备用的公共 API 列表；
追番页（Bilibili UID）：siteConfig 的 bilibili.uid 填自己的 B 站 UID，追番进度自动同步。

4. 写一篇文章试手#

文章就是 src/content/posts/ 下的 Markdown 文件，头部 frontmatter 是元信息：

1
---
2
title: 我的第一篇测试文章
3
published: 2026-09-21
4
description: 摘要，会显示在列表页
5
tags: [标签1, 标签2]
6
category: 技术
7
draft: false
8
slug: my-first-post   # 不填则用「文件夹+文件名」当 URL
9
---
10

11
正文用 Markdown 写……

保存后回浏览器看效果。完整的逐字段说明、正文语法、发布流程都在使用指南里，这里不重复。

五、踩坑记录#

搭的过程中遇到的三个印象最深的坑，写下来防止后人（和未来的我）重踩。

坑 1：不带斜杠的 URL 404#

Astro 配置了 trailingSlash: "always" 后，/posts/xxx（无斜杠）直接 404。而生产环境静态托管对无斜杠请求一般会自动 301 补斜杠，本地却不行，行为不一致。

解决：把配置改成 "ignore"，再加一个中间件统一重定向：

src/middleware.ts展开收起

1
import { defineMiddleware } from "astro:middleware";
2

3
export const onRequest = defineMiddleware((context, next) => {
4
  const parsed = new URL(context.request.url);
5
  const { pathname } = parsed;
6
  const last = pathname.split("/").pop() ?? "";
7
  // 跳过：根路径 / 已带斜杠 / 带扩展名的文件 / Astro 与 Vite 内部端点
8
  if (
9
    pathname === "/" || pathname.endsWith("/") ||
10
    last.includes(".") ||
11
    pathname.startsWith("/@") || pathname.startsWith("/_")
12
  ) return next();
13
  return context.redirect(pathname + "/" + parsed.search,
14
    import.meta.env.DEV ? 302 : 301);
15
});

展开收起

坑中坑：重定向状态码在开发环境要用 302，别用 301——301 会被浏览器永久缓存，万一重定向规则写错了，之后怎么改都跳旧地址，只能清缓存。

坑 2：主题色改了但浏览器没变#

改了色相值刷新还是旧颜色，其实是浏览器 localStorage 缓存了旧值（主题把用户的色相选择存在里面）。清站点数据或 Ctrl+F5 强刷即可。不是代码的问题。

坑 3：dev server 莫名崩溃#

Windows 上有个系统临时文件在盘符根目录，被 Vite 的文件监听扫到时会抛 EINVAL 直接把 dev server 搞崩。

解决两步走：在 astro.config.mjs 里把该文件加入 server.watch.ignored 忽略列表（治本），再写个循环脚本崩溃后自动重启（兜底）：

Terminal window

1
while ($true) { pnpm dev; Start-Sleep -Seconds 3 }

教训：玄学崩溃先看完整报错栈，定位到具体文件路径，别急着怀疑自己的代码。

六、服务器选购与初始化#

1. 配置选择#

静态博客对配置要求极低，我选的是国内云厂商的入门款：

项	配置	说明
CPU/内存	2核 2G	纯静态托管绰绰有余
带宽	固定 3 Mbps	个人博客流量足够，以后可套 CDN
系统盘	40G SSD	用不满
系统	Ubuntu 26.04 LTS	生态最省心
价格	百元级/年	新人活动价

注意：国内服务器绑定域名需要 ICP 备案，备案期间可以先用 IP 访问调试（备案只管域名，IP 直连不受影响）。

买完第一件事：在控制台重置服务器密码，记下来，下面 SSH 要用。

2. 放行端口#

云服务器默认只开 SSH(22)。去控制台 安全组 → 入方向 → 添加规则，放行：

80/80（HTTP）
443/443（HTTPS，以后用）

协议 TCP，源 0.0.0.0/0。

坑点：服务器内装好一切却访问不了，八成是安全组没放行——在服务器里 curl 是通的，外面就是连不上。系统自带的防火墙（ufw）一般是关闭的，问题基本都出在云平台的安全组这一层。

3. SSH 免密登录#

每次输密码太麻烦，配一下密钥登录：

Terminal window

1
# 本地生成密钥对（一路回车）
2
ssh-keygen -t ed25519
3

4
# 把公钥装到服务器上（这一步需要输一次密码）
5
ssh <用户名>@<服务器IP> "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys" < ~/.ssh/id_ed25519.pub
6

7
# 测试：不再要密码即成功
8
ssh <用户名>@<服务器IP> "echo ok"

原理：登录时服务器用你的公钥验证客户端持有的私钥，密码不再参与。

七、首次部署#

1. 本地构建#

Terminal window

1
pnpm build

产物在 dist/ 目录：每个页面是 目录名/index.html，带哈希的 CSS/JS 在 _astro/ 下。可以本地先看看产物长什么样。

2. 服务器装 Nginx 并上传#

Terminal window

1
# 服务器上安装 Nginx 并建站点目录
2
ssh <用户名>@<服务器IP> "apt update && apt install -y nginx && mkdir -p /var/www/blog"
3

4
# 本地打包上传（比逐个文件 scp 快得多）
5
tar -czf dist.tar.gz dist
6
scp dist.tar.gz <用户名>@<服务器IP>:/tmp/
7

8
# 服务器上解压
9
ssh <用户名>@<服务器IP> "tar -xzf /tmp/dist.tar.gz -C /var/www/blog --strip-components=1"

3. Nginx 站点配置#

在服务器上创建 /etc/nginx/sites-available/blog：

1
server {
2
    listen 80 default_server;
3
    server_name _;
4
    root /var/www/blog;
5
    index index.html;
6
    charset utf-8;
7
    error_page 404 /404.html;      # Astro 会构建出 404.html
8

9
    gzip on;                        # 文本资源压缩，HTML/CSS/JS 体积减 70% 左右
10
    gzip_types text/css application/javascript application/json image/svg+xml;
11

12
    # 带哈希的静态资源：内容变了文件名就变，可以放心长缓存
13
    location ^~ /_astro/ {
14
        expires 30d;
15
        add_header Cache-Control "public, immutable";
16
    }
17
}

展开收起

启用并重载：

Terminal window

1
ln -sf /etc/nginx/sites-available/blog /etc/nginx/sites-enabled/blog
2
rm -f /etc/nginx/sites-enabled/default   # 移除默认站点，避免抢占 80 端口
3
nginx -t                                  # 语法检查，必须显示 ok
4
systemctl reload nginx

浏览器打开 http://<服务器IP>，应该就能看到博客了。

Nginx 的工作方式：收到请求后按 root 找文件——/posts/xxx/ 对应 /var/www/blog/posts/xxx/index.html；请求目录但没带斜杠时自动 301 补斜杠；找不到文件就走 error_page 的 404 页。

八、全自动发布：原理详解#

这是整套系统最核心的部分，值得讲透。

1. Git 基础：一次 push 背后发生了什么#

先建立心智模型。Git 把文件的管理划分成几个「区域」，一次 push 的旅程是这样的：

1
工作区                本地仓库                     远程仓库
2
(你编辑的文件)   git add→  暂存区  git commit→  (历史记录)  git push→  GitHub
3
 src/content/            (准备打包)            (.git 目录)

工作区：就是硬盘上看得见的文件，你用编辑器改 Markdown 就是在改工作区；
暂存区（stage）：下次要打包进提交的文件清单。改动必须先经过它；
本地仓库：git commit 会在本机生成一个不可变的快照（提交），包含改动了什么、谁改的、什么时候；
远程仓库：GitHub 上的仓库。git push 把本地的新提交上传过去。

2. 日常发文完整命令流#

以新写一篇文章为例，完整走一遍：

Terminal window展开收起

1
# ① 先看看当前状态（哪些文件改了、哪些是新增的、哪些还没跟踪）
2
git status
3

4
# ② 把改动加入暂存区
5
git add src/content/posts/my-new-post.md   # 精确添加单个文件
6
# 或 git add -A                            # 添加全部改动（含删除、改名）
7

8
# ③ 再看一眼：改动已进入暂存区（绿色），确认没有误加的东西
9
git status
10

11
# ④ 提交：把暂存区内容固化为一个本地快照，-m 后面是提交说明
12
git commit -m "post: 新文章标题"
13

14
# ⑤ 推送到 GitHub
15
git push origin master

展开收起

逐个解释 git push origin master 里的两个词：

origin 是远程仓库的别名，git clone 时自动指向你克隆来的那个 GitHub 地址（用 git remote -v 查看）；
master 是分支名，可以理解成仓库的主时间线。这条命令的意思是：把本地 master 分支上的新提交，同步到 GitHub 的 master 分支。

第一次 push 时 Git 会要求登录 GitHub。HTTPS 方式下 Windows 的凭证管理器会弹出授权窗口，登录一次之后凭证会被记住，以后不用再输。

3. 提交前后常用的辅助命令#

Terminal window

1
git diff                 # 看工作区改了什么（还没 add 的）
2
git diff --staged        # 看暂存区里有什么（已 add 未 commit 的）
3
git log --oneline -5     # 最近 5 条提交历史，一行一条
4
git show                 # 看最新一次提交的完整改动内容

提交说明（-m 里的内容）建议写清楚这次改了什么，比如 post: 新文章标题、fix: 修复导航样式。以后翻历史时，这些说明就是你的操作日志。

4. 出错了怎么办#

Terminal window

1
# 情况一：忘了 add 就 commit，或者提交说明写错了
2
git commit --amend -m "正确的说明"    # 修补最近一次提交（仅限还没 push）
3

4
# 情况二：改动不想要了，想恢复到上次提交的样子
5
git checkout -- 文件名                # 丢弃某文件未提交的改动（慎用）
6

7
# 情况三：push 被拒绝（rejected），通常是 GitHub 上有你本地没有的提交
8
git pull --rebase origin master      # 先把远端的新提交拉下来合并，再重新 push
9

10
# 情况四：已经 push 的提交想撤销
11
git revert <提交ID>                  # 生成一个"反向提交"抵消它，安全且可追溯

原则：只用安全的撤销手段（revert、新建提交覆盖）。git push --force 之类会重写历史的强操作，个人博客偶尔可救急，但一定要清楚自己在干什么。

到这里，代码已经在 GitHub 上了。但 git push 本身只负责把代码传到仓库，它不知道任何部署的事。真正触发自动部署的，是下面这个机制。

5. GitHub Actions：构建并发布到 dist 分支#

仓库里有三个 workflow 文件，各司其职：

.github/workflows/deploy.yml — 构建站点并把产物发布到仓库的 dist 分支（核心）；
.github/workflows/build.yml — 质量检查：Node 22/23 双版本跑 astro check，防手残；
.github/workflows/biome.yml — 代码风格检查（biome）。

deploy.yml 的开头声明了触发条件：

1
on:
2
  push:
3
    branches: [ master ]   # master 分支有新 push 就触发

git push 后 GitHub 收到新提交，匹配到 workflow 就起一个全新的临时虚拟机（runner）按 yaml 逐步执行：安装依赖 → pnpm build → 把 dist/ 目录整体提交到仓库的 dist 分支。

为什么要经过 dist 分支中转？服务器只有 2G 内存，每次都在服务器上构建又慢又吃力；而且如果让 Actions 直接 SSH 登录服务器部署，每次构建机的境外 IP 登录都会触发阿里云的「异地登录」告警。改成「GitHub 构建 → dist 分支 → 服务器拉取」，构建交给强劲的 CI 机器，服务器只做拉取和同步，全程没有任何境外登录。
附带的好处：dist 分支的提交历史就是部署历史，哪次构建改了什么一目了然；出问题把服务器回退到旧的 dist 提交即可回滚。

6. 服务器端拉取部署#

deploy.yml 里「发布 dist 分支」这一步的写法：

1
- name: Publish dist/ to dist branch
2
  run: |
3
    git config user.name "github-actions[bot]"
4
    git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
5
    git fetch origin dist --depth 1 || echo "首次构建：dist 分支还不存在"
6
    if git rev-parse -q --verify origin/dist >/dev/null; then
7
      git worktree add /tmp/publish origin/dist
8
    else
9
      git worktree add --orphan -b dist /tmp/publish
10
    fi
11
    rsync -a --delete --exclude .git dist/ /tmp/publish/
12
    cd /tmp/publish
13
    git add -A
14
    if git diff --cached --quiet; then
15
      echo "构建产物无变化，跳过推送"
16
    else
17
      git commit -m "build: ${GITHUB_SHA::7}"
18
      git push origin HEAD:dist
19
    fi

展开收起

原理：git worktree 在不碰主工作区的前提下开一个临时工作目录指向 dist 分支，用本次构建产物整体替换后提交推送。推送用的 GITHUB_TOKEN 由 GitHub 自动注入，只对本仓库有效且永不过期，不需要在 Secrets 里配置任何密钥。

服务器这边，核心是拉取脚本 scripts/deploy.sh（已放在仓库里）：发现 dist 分支有新提交，就同步到 Nginx 站点目录——注意它只做拉取和复制，不构建，几秒内完成：

1
#!/usr/bin/env bash
2
set -euo pipefail
3

4
SITE_DIR="/opt/site"          # dist 分支的克隆（构建产物）
5
DEPLOY_DIR="/var/www/blog"    # Nginx 站点目录
6
BRANCH="dist"
7

8
log() { echo "[$(date '+%F %T')] $*"; }
9

10
# 文件锁：上一轮还没跑完就跳过本轮
11
exec 9>/tmp/blog-deploy.lock
12
flock -n 9 || exit 0
13

14
if [ ! -d "$SITE_DIR/.git" ]; then
15
  log "站点产物仓库不存在，请先执行：git clone -b dist --single-branch git@github.com:Carlinhosjoga/blog.git $SITE_DIR"
16
  exit 1
17
fi
18

19
cd "$SITE_DIR"
20
git fetch origin "$BRANCH"
21
LOCAL=$(git rev-parse HEAD)
22
REMOTE=$(git rev-parse "origin/$BRANCH")
23

24
if [ "$LOCAL" = "$REMOTE" ]; then
25
  log "没有新构建产物，跳过"
26
  exit 0
27
fi
28

29
log "发现新构建 $LOCAL -> $REMOTE，同步上线"
30
git reset --hard "origin/$BRANCH"
31
rsync -az --delete --exclude .git "$SITE_DIR"/ "$DEPLOY_DIR/"
32
log "部署完成"

展开收起

安全性三件事：

只读拉取：服务器用一把「只读 Deploy Key」访问私有仓库，即使密钥泄露，别人也只能读，推不上去、删不掉仓库；
构建在 GitHub 完成：服务器上不需要 Node 和 pnpm，也不怕构建失败——dist 分支没更新，服务器什么都不做，线上永远是最近一次成功构建的版本；
rsync —delete：站点目录与构建产物严格一致，不会残留已删除页面的旧文件。

服务器初始化手把手（只需做一次，因为不构建，比在服务器上装 Node 的方案轻得多）：

Terminal window展开收起

1
# ① 装 git 和 rsync（Ubuntu 一般已自带）
2
apt install -y git rsync
3

4
# ② 生成只读拉取密钥
5
ssh-keygen -t ed25519 -f ~/.ssh/blog_pull_key -N "" -C "blog-server-pull"
6
cat >> ~/.ssh/config <<'EOF'
7
Host github.com
8
  IdentityFile ~/.ssh/blog_pull_key
9
  IdentitiesOnly yes
10
EOF
11
cat ~/.ssh/blog_pull_key.pub
12
# 把输出的公钥添加到 GitHub 仓库：Settings → Deploy keys → Add deploy key
13
# （不要勾选 Allow write access）
14

15
# ③ 克隆两个仓库：/opt/blog 放源码和脚本，/opt/site 放构建产物
16
git clone git@github.com:Carlinhosjoga/blog.git /opt/blog
17
git clone -b dist --single-branch git@github.com:Carlinhosjoga/blog.git /opt/site
18

19
# ④ 手动跑一次，确认能同步上线
20
bash /opt/blog/scripts/deploy.sh
21

22
# ⑤ 加入定时任务：每 5 分钟兜底检查一次
23
(crontab -l 2>/dev/null; \
24
 echo "*/5 * * * * bash /opt/blog/scripts/deploy.sh >> /var/log/blog-deploy.log 2>&1") | crontab -

展开收起

坑点：如果 git clone 或 fetch 报 Permission denied (publickey)，检查三处——公钥是否已添加为 Deploy key、~/.ssh/config 是否写对了 IdentityFile、blog_pull_key 权限是否是 600。另外国内服务器访问 GitHub 偶尔网络抖动，多试两次或换个时间段即可。

7. Webhook：让部署从「分钟级」变「秒级」#

cron 兜底意味着最多等 5 分钟才上线。想秒级触发，给服务器加一个 webhook 接收器：GitHub 在 dist 分支更新时主动 POST 一个 HTTP 请求给服务器——这只是访问一个网址，不是登录，不会触发任何异地登录告警。服务器收到请求立刻执行部署脚本。

接收器是几十行 Python（放在服务器 /opt/blog-webhook/hook.py），只监听本机回环地址，由 Nginx 反代对外：

1
#!/usr/bin/env python3
2
import hmac, hashlib, json, subprocess
3
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
4

5
TOKEN = "<URL令牌>"       # 与 Nginx 反代路径一致
6
SECRET = "<webhook密钥>"   # 与 GitHub webhook 的 Secret 一致
7
DEPLOY = "/opt/blog/scripts/deploy.sh"
8
LOG = "/var/log/blog-deploy.log"
9

10
class Handler(BaseHTTPRequestHandler):
11
    def do_POST(self):
12
        path = self.path
13
        if path.startswith("/webhook/"):
14
            path = path[len("/webhook"):]  # Nginx 反代会带上 /webhook 前缀
15
        if path != "/" + TOKEN:
16
            self.send_response(404); self.end_headers(); return
17
        body = self.rfile.read(int(self.headers.get("Content-Length", 0)))
18
        expect = "sha256=" + hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest()
19
        if not hmac.compare_digest(self.headers.get("X-Hub-Signature-256", ""), expect):
20
            self.send_response(403); self.end_headers(); return
21
        event = self.headers.get("X-GitHub-Event", "")
22
        if event == "ping":
23
            self.send_response(200); self.end_headers(); return
24
        if event == "push" and json.loads(body).get("ref") == "refs/heads/dist":
25
            with open(LOG, "ab") as lf:
26
                subprocess.Popen(["bash", DEPLOY], stdout=lf, stderr=lf, start_new_session=True)
27
        self.send_response(204); self.end_headers()
28

29
    def log_message(self, *args):
30
        pass  # 静默访问日志
31

32
ThreadingHTTPServer(("127.0.0.1", 8787), Handler).serve_forever()

展开收起

安全校验两层：URL 路径里有随机令牌（外人猜不到入口），请求体用 GitHub webhook Secret 做 HMAC-SHA256 签名验证（伪造请求直接 403）。而且只有 dist 分支的 push 事件才触发部署——你平时推 master 触发的 webhook 会被它自动忽略。

用 systemd 常驻（/etc/systemd/system/blog-webhook.service）：

1
[Unit]
2
Description=Blog deploy webhook receiver
3
After=network.target
4

5
[Service]
6
ExecStart=/usr/bin/python3 /opt/blog-webhook/hook.py
7
Restart=always
8
RestartSec=3
9

10
[Install]
11
WantedBy=multi-user.target

启用：systemctl daemon-reload && systemctl enable --now blog-webhook。

Nginx 加一段反代（/etc/nginx/sites-available/blog）：

1
    # GitHub webhook 部署通知（路径含随机令牌，仅 dist 分支事件触发部署）
2
    location = /webhook/<URL令牌> {
3
        proxy_pass http://127.0.0.1:8787;
4
        add_header X-Robots-Tag "noindex, nofollow" always;
5
    }

nginx -t && systemctl reload nginx 生效。最后到 GitHub 仓库：Settings → Webhooks → Add webhook，Payload URL 填 http://<服务器IP>/webhook/<URL令牌>，Content type 选 application/json，Secret 填与脚本一致的密钥，触发事件保持默认（Just the push event）。

之后每次发布的时序：git push → GitHub 构建（约 2 分钟）→ dist 分支更新 → webhook 秒达 → 服务器同步上线。全程无登录、无手工操作。

8. 完整数据流#

1
本地写文章 (src/content/posts/xxx.md)
2
        │
3
        │  git add / commit / push (master)
4
        ▼
5
GitHub 仓库 ←── build.yml / biome.yml 质量检查
6
        │
7
        │  deploy.yml：pnpm build → 产物提交到 dist 分支
8
        ▼
9
dist 分支更新 ──webhook 秒级通知──▶ 服务器执行 deploy.sh
10
        │                              │
11
        │                              │ cron 每 5 分钟兜底
12
        ▼                              ▼
13
        └──────▶ git 拉取 dist → rsync → /var/www/blog → Nginx → 访客

构建永远在 GitHub 完成：服务器只做几秒钟的拉取同步，2G 内存毫无压力；产物和源码永远一一对应，出问题回滚就是把服务器 reset 到旧的 dist 提交。

九、日常更新流程#

配置完之后，写文章只剩三步：

Terminal window

1
# 1. 写文章：在 src/content/posts/ 新建 .md 文件
2
# 2. 提交：
3
git add -A && git commit -m "post: 文章标题"
4
# 3. 推送：
5
git push

约两三分钟内自动上线：GitHub 构建（约 2 分钟）→ dist 分支更新 → webhook 秒级触发服务器同步。看进度两个渠道：GitHub 仓库 Actions 标签页看构建日志（绿勾 = 构建成功）；服务器上 tail -f /var/log/blog-deploy.log 看部署日志。

十、后续计划#

域名备案通过后：DNS 解析到服务器，Nginx 配置 server_name，用 certbot 免费签发 HTTPS 证书（自动续期）；
追番页数据是构建时拉取的，计划加一个每日定时构建（即使没有新文章也刷新一次），追番进度自动更新；
流量起来后在服务器前套一层国内 CDN，源站带宽压力趋近于零。

整个搭下来最大的感受：静态博客的复杂度不在写页面，而在把「写完之后的事」自动化。一旦发布管道跑通，写文章这件事就变得毫无心理负担——这也正是坚持输出的前提。