darknight

你好，世界

Sun, 01 Nov 2026 00:00:00 GMT

站点的签名我填的是「你好，世界」。

没什么特别的理由。程序员的第一个程序是 Hello, World，那第一篇博客也应该叫这个。

为什么要搭这个博客#

大二之后开始有一件事变得很清楚：看过的东西不等于学会的东西。

课堂上听懂了，作业做完了，过两周还是一问三不知。但当我试着把某件事讲给别人——哪怕只是写下来写给两周后的自己——才会发现中间有多少环节其实是空的。写文章就是把空的地方照出来的过程。

所以这个博客首先是写给我自己的。有人恰好看到、觉得有用，是额外收获。

打算写些什么#

大概三类。

一类是技术笔记：代码、工具、踩过的坑。我现在的方向是 AI / 机器学习，会写一些正在学的东西。这类文章的标准是「两周后的我能看懂」，所以会尽量把前提说清楚，而不是堆术语。

一类是数学。专业课里的东西，或者自己看到的有意思的结论。数学这块我更在意解释，不追求严谨到可以发论文——那是课本该做的事，我要做的是让某个概念在脑子里有个具体的形状。

一类是没什么用但很想说的想法。杂记。分类就叫杂记，标签也叫杂记，不用来归档，只是不假装它有用。

关于这个站点#

样式参考了 rainzt.cn 所用的开源主题 Aemeath，代码是 MIT 协议，文字和图片是我自己的。

它跑在一台阿里云的服务器上，首页的壁纸和头像是生成的原创图。以后可能会换。

慢慢来。

这个博客是怎么跑起来的

Sun, 01 Nov 2026 00:00:00 GMT

搭完顺手记一下链路。以后忘了可以自己回来看。

整体思路#

静态博客。用户访问的永远是构建产物（一堆 HTML / CSS / JS），不需要跑 Node 服务。

同一份内容推两个地方，各走各的链路：

1
本地改内容
2
  ├─ npm run deploy:cf ──▶ 本地构建 dist ──▶ wrangler 上传 ──▶ Cloudflare Pages ──▶ darknight.website
3
  └─ git push server main ──▶ 服务器 post-receive 自己构建 ──▶ nginx ──▶ 101.37.208.65

为什么要两份：域名挂在内地服务器上备案走不通（那台 ECS 在朋友的账号里，个人账号之间没法授权备案服务码），而境外节点压根不产生备案义务。于是域名交给 Cloudflare，服务器留一个 IP 直连当备用出口，顺便练手 nginx。

下面先写 Cloudflare 这条，再写服务器那条。

Cloudflare Pages 这条链路#

npm run deploy:cf 一条命令做完所有事：生成图标和 LQIP、算友链头像底色、astro build、字体子集化、Pagefind 建索引，最后 wrangler pages deploy dist。

没有走「连 GitHub 自动构建」那条路，两个原因：这个仓库只有本地和服务器两个 remote，没往 GitHub 推；而且 Pages 的构建容器只有 4 GB 内存和 512 并发限制，不如在自己机器上构建快——笔记本跑完整构建一分多钟，上传 359 个文件半分钟。

第一次部署有个坑：wrangler 把文件全传完了（Success! Uploaded 359 files），最后注册 deployment 那一步网络抖了一下报 fetch failed。这时候项目是空的，访问返回 522，光看上传成功会误以为上线了。重跑一次即可，资产按哈希去重，秒传。

域名怎么接进来#

顺序不能反：

Cloudflare 面板 Add a site，填 darknight.website，Free 计划，拿到两个 *.ns.cloudflare.com
Pages 项目 → Custom domains 里把域名关联上（CF 自动建记录、自动签证书）
阿里云域名控制台 → 修改 DNS 服务器，换成第 1 步那两个 NS

第 2 步必须在第 3 步前面。NS 一切到 Cloudflare，流量就进边缘了，这时 Pages 还没跟域名建立关联，回源找不到目标直接 522。

另外改 NS 要求域名实名认证已经通过，实名没过阿里云会拒绝修改。

服务器上的目录#

所有东西都在 /srv/blog 下面，职责分得很开：

1
/srv/blog/
2
├── git/blog.git/       # bare 仓库，push 到这里
3
│   └── hooks/post-receive   # 部署脚本
4
├── app/                # 源码工作区（构建时占用）
5
│   └── node_modules/
6
├── releases/           # 每次构建的产物，按时间戳存
7
│   └── 20261101-121100/
8
├── current ─────▶ releases/20261101-121100
9
└── deploy.log          # 部署日志

current 是个软链接，nginx 只认它。切换版本就是把软链接指向新的 release，所以发布是瞬时的，不会出现「构建到一半用户看到半截页面」。

钩子做了什么#

post-receive 里几个值得说的细节。

只认 main 分支，其它分支推上去不触发部署：

Terminal window

1
while read -r _old new ref; do
2
  [ "$ref" = "refs/heads/main" ] || continue
3
  # ...
4
done

用 nice -n 19 跑构建。这台机器内存只有 1.7 GB，Astro 构建会吃满 CPU。不加 nice 的话构建期间服务器基本没法用。同时给 Node 设了上限：

Terminal window

1
nice -n 19 env NODE_OPTIONS=--max-old-space-size=1200 pnpm build

先检查再重载 nginx。构建失败就退出，软链接不动，线上还是上一个好版本：

Terminal window

1
if sudo -n nginx -t >/dev/null 2>&1; then
2
  sudo -n systemctl reload nginx
3
else
4
  log "WARN nginx -t failed, NOT reloading"
5
fi

只保留最近 3 个 release，防止磁盘被历史版本塞满：

Terminal window

1
ls -1dt "$REL_ROOT"/*/ | tail -n +4 | xargs -r rm -rf

回滚就是从 releases/ 里挑一个旧时间戳，把软链接重新指过去。

缓存策略#

/_astro/ 下的文件名带 content hash，内容变了名字就变，所以可以放心设很长的缓存：

1
location /_astro/ {
2
  add_header Cache-Control "public, max-age=31536000, immutable";
3
}

图片没 hash，设一周。/pagefind/ 是全文搜索的索引，每次构建整体替换，设 300 秒——太长会导致刚发的文章搜不到。

Cloudflare 那边用 public/_headers 声明同样的规则，构建时会被拷进 dist。这里有个和 nginx 完全不同的行为：所有匹配上的规则都会生效并且叠加，不是后面的覆盖前面的。所以 /* 和 /_astro/* 同时写了 Cache-Control 的话，响应头里会出现两个值拼在一起：

1
Cache-Control: public, max-age=31536000, immutable, public, max-age=0, must-revalidate

浏览器取哪一个就不好说了。正确做法是通配规则里只放安全头，Cache-Control 只在具体路径上写。HTML 不写也没关系，Pages 默认就给 max-age=0, must-revalidate。

全文搜索#

用的 Pagefind。它扫构建好的 HTML 建静态索引，不需要后端、不需要 API key，查询全在浏览器里完成。代价是索引体积会随文章数增长，现在这个量级完全无所谓。

已知的坑#

备案这件事最后没走通。 卡在第 5 步选云产品实例——那台 ECS 在朋友的阿里云账号里，而跨账号授权备案服务码要求对方是企业实名认证，个人账号只能给自己账号下的服务器生成。买付费服务码也不行，它必须绑定在同一个账号里符合条件的实例上。所以只剩两条路：在朋友账号里以我的身份提交（会永久占掉那个账号唯一的主体名额），或者自己买台便宜的内地机。目前选了第三条：域名不碰内地节点，直接挂 Cloudflare，境外节点不产生备案义务。

Cockpit 占了 443。 服务器的 Web 管理面板反代在 https://<IP>/start，博客不跟它抢，用 80。

本地构建其实能跑。 原先以为主题的字体在构建时要从 jsdelivr 拉、笔记本连不上，所以一直只在服务器上构建。实际试下来 astro build 在本地一次过，字体子集化和 Pagefind 也都正常，那条判断是错的。

还没做的#

评论（Waline）和访问统计（Umami）都没上，先把纯静态链路跑通。HTTPS 在 Cloudflare 侧是自动签发的，不用管；内地那台如果以后要上证书再走 certbot。

国内访问速度目前没测。真觉得慢再考虑套一层 Cloudflare 优选 IP，或者上腾讯云 EdgeOne Pages 回源——但那是等有人抱怨慢以后再说的事。

怎么写文章并发布

Sun, 01 Nov 2026 00:00:00 GMT

以后忘了就查这篇。核心只有一句：在本地改文件，然后 npm run deploy:cf 上线。

域名走 Cloudflare Pages，服务器那份是 IP 直连的备用出口。平时只管 Cloudflare 这条，两边都要更新就再补一次 git push。

准备工作#

博客源码在本地 D:\服务器测试\blog。远程仓库在服务器上：

Terminal window

1
cd /d/服务器测试/blog
2
git remote -v
3
# server  ssh://darknight@101.37.208.65/srv/blog/git/blog.git (push)

如果显示的是这个，直接往下走。

写一篇新文章#

Terminal window

1
cd /d/服务器测试/blog
2
corepack pnpm new-post my-first-note

会在 src/content/posts/ 下生成一个带 frontmatter 模板的 my-first-note.md。文件名就是文章网址：posts/my-first-note。

用英文小写加连字符做文件名，别用中文和空格——URL 里中文会被转义成一长串 %XX，不好分享。

frontmatter 怎么写#

1
---
2
title: 文章标题
3
published: 2026-11-02
4
description: 摘要，会出现在列表页和搜索结果的分享卡片里
5
aiPolished: false          # 不是 AI 润色过的就填 false，否则文章顶部会有提示
6
image: /assets/images/wallpaper/darknight-rain.webp   # 封面图，留空则不显示
7
tags: [机器学习]
8
category: 技术笔记
9
draft: false               # true = 只存在本地，不发布
10
pinned: false              # true = 首页置顶
11
lang: zh-CN
12
---

只有 title 和 published 必填，其它都有默认值。

写完正文提交，然后部署。

发布#

Terminal window

1
cd /d/服务器测试/blog
2
git add src/content/posts/
3
git commit -m "posts: 新增《文章标题》"
4
npm run deploy:cf

最后这条会先把整条构建链跑一遍（图标 → LQIP → 友链底色 → astro build → 字体子集 → Pagefind），再把 dist 传给 Cloudflare。本地跑完整构建一分多钟，上传半分钟，比服务器快得多。看到

1
✨ Deployment complete! Take a peek over at https://xxxxxxxx.darknight-alp.pages.dev

就算成功了。生产地址是 https://darknight-alp.pages.dev，前面那串哈希是这次部署的快照，用来验证改动不影响别人。

如果上传显示成功但站点打不开、返回 522，说明最后注册 deployment 的请求丢了。重跑一次 npm run deploy:cf，文件按哈希去重，秒完。

顺手更新服务器那份（可选）#

想让 IP 直连那份也同步，再推一次：

Terminal window

1
git push server main

push 完输出里会出现 remote:，那就是部署日志在实时往外打。大概长这样：

1
remote: [2026-11-01 12:34:56] ===== deploy 20261101-123456 start =====
2
remote: [2026-11-01 12:35:02] pnpm install
3
remote: [2026-11-01 12:36:40] pnpm build
4
remote: [2026-11-01 12:39:11] live -> /srv/blog/releases/20261101-123456
5
remote: [2026-11-01 12:39:12] nginx reloaded
6
remote: [2026-11-01 12:39:12] ===== deploy 20261101-123456 OK =====

三四分钟是正常的，服务器只有 1.7G 内存，构建慢。看到 OK 就行，刷新页面。

部署失败了怎么办#

Cloudflare 这条如果失败，报错会直接打在终端里，构建阶段的错和上传阶段的错一眼能分开。构建没过就按报错改，改完重跑；上传阶段网络断了也直接重跑，dist 没变的话是秒传。

服务器那条先看 push 输出里有没有 FAIL。没看到的话上服务器查完整日志：

Terminal window

1
ssh darknight@101.37.208.65 'tail -50 /srv/blog/deploy.log'

最常见的两种：

构建报错，站点没更新。 放心，这时线上还是上一个正常版本——软链接只在构建成功后才切换。按日志里的报错改 Markdown 或配置，重新 push。

frontmatter 校验没过。 一般是日期格式写错了（必须是 YYYY-MM-DD）或者 tags 没写成列表。

改配置#

站点级的东西都在 src/config/ 下，一个文件管一块：

文件	管什么
`siteConfig.ts`	站名、签名、URL、功能开关
`profileConfig.ts`	头像、昵称、简介、社交链接
`backgroundWallpaper.ts`	首页壁纸、标题文字、打字机
`navBarConfig.ts`	顶部菜单
`sidebarConfig.ts`	侧边栏小组件
`themeColor.ts`	主题色
`licenseConfig.ts`	文章版权声明

改完同样 npm run deploy:cf 上线。

siteConfig.ts 里的 pages 是功能开关，比如想开相册就把 gallery 改成 true：

1
pages: {
2
    friends: true,
3
    guestbook: true,
4
    gallery: false,
5
    bangumi: false,
6
}

换壁纸、加图片#

放进 public/assets/images/ 或者它的子目录，然后用绝对路径引用，比如 /assets/images/wallpaper/xxx.webp。

用 webp，别用 png。 同样的观感，体积能小一大半，首页加载全靠它。

转格式可以用 sharp-cli：

Terminal window

1
corepack pnpm dlx sharp-cli -i in.png -o out.webp -q 82

本地预览#

改样式、看排版，起本地开发服务器最快：

Terminal window

1
cd /d/服务器测试/blog
2
corepack pnpm dev

pnpm 没单独装，用 corepack 前缀调，它会按 package.json 里的 packageManager 字段拉 9.14.4。

之前一直以为本地构建跑不起来——主题字体要在构建时从 jsdelivr 拉，怀疑笔记本连不上它，所以只在服务器上构建。实测是错的，本地 astro build、字体子集化、Pagefind 全都能一次过，所以现在的部署才改成本地构建再上传。

别做的事#

不要直接在服务器上改文件。/srv/blog/app 是部署时 checkout 出来的，下次 push 会被 checkout -f 覆盖掉。要改就改本地、提交、推上去。