1. 一次访问经过哪些层#

博客页面和动态服务走的是两条不同的路径：

1
浏览器
2
  ├── blog.xqcherry.top
3
  │     → Cloudflare Pages（静态产物）
4
  │
5
  └── 评论 / 图片 / 资料
6
        → Cloudflare（DNS / TLS / 防护）
7
        → Cloudflare Tunnel
8
        → cloudflared（VPS 容器）
9
        → Docker 内网
10
        → Nginx
11
        ├── Artalk 评论服务（VPS）
12
        └── MinIO 对象存储（家庭主机，经 WireGuard）

博客正文本身不会回到 VPS：Pages 直接返回构建好的静态文件。只有评论、图片和资料请求需要经过 Tunnel 和 Nginx，再分别转发给 Artalk 或家庭主机上的 MinIO。

1
浏览器 → Cloudflare → Cloudflare Tunnel
2
→ cloudflared → Docker 内网 → Nginx

2. 站点本身：Astro + Fuwari#

站点基于 Astro 5 和 Fuwari 主题，构建结果是静态 HTML、CSS 和少量客户端脚本。

内容用 Astro 的 content collections 管理，目前有六类：

每类集合在 src/content/config.ts 里都有对应的 Zod schema。必填字段、枚举值和默认值由 schema 约束，写错 frontmatter 会在 astro check 或构建阶段直接报错，而不是等到页面上线后才发现。

页面之外还接了几样东西：

• Pagefind：构建完成后对 dist/ 建全文索引，搜索完全在前端完成，不需要额外服务。
• RSS 与 sitemap：都在构建阶段生成。
• Swup：站内跳转不整页刷新，只替换主内容区。
• Expressive Code + KaTeX：代码块、行号、折叠区和数学公式都在构建阶段处理。
• GitHub Actions：在 Node.js 22 和 23 上分别跑 astro check 与 astro build，把类型和构建问题挡在合并之前。

本地构建命令只有一条：

1
pnpm build

它实际执行 astro build && pagefind --site dist。产物由 Cloudflare Pages 从仓库构建并发布，构建过程不依赖评论服务或对象存储。

3. 服务器与内外网#

1
公网：Cloudflare Pages → 静态页面
2
公网：Cloudflare → Tunnel → Nginx → Artalk / MinIO 只读
3
私网：WireGuard / SSH 隧道 → 管理入口

4. MinIO：图片和资料不放进 Git#

早期图片直接放在仓库里，文章一多，Git 体积增长得很快，而且同一张图可能在构建产物和源文件里各存一份。现在图片和资料统一放 MinIO，仓库里只保留 Markdown 和元数据。

MinIO 以容器方式跑在家庭主机上，使用固定版本的自定义镜像，数据目录单独持久化。它只绑定 WireGuard 地址上的 S3 端口，不加入公网 Docker 网络，也不开放浏览器控制台；VPS 的 Nginx 通过私有网络访问它，对外只暴露读取域名。

桶的权限分成两类：

• 匿名访问：只允许 GetObject，不能列目录，也不能写入。
• 上传账号：本地 CLI 使用单独的账号，不使用 root；账号权限按上传需要配置。

上传通过仓库里的 CLI 完成：

1
# 文章配图
2
pnpm image --slug blog-architecture-self-hosting ./images/arch-1.png
3

4
# 资料归档
5
pnpm material --title "示例资料" --slug sample-material \
6
  --category 资料 --file ./sample.pdf

图片命令会计算文件内容的 SHA-1，把对象 key 组织成：

1
images/posts/<slug>/<哈希前缀>-<文件名>.<扩展名>
2
materials/<slug>/<slug>-<哈希前缀>.<扩展名>

key 里带内容哈希，意味着文件内容一变就会产生新对象，不会和旧缓存冲突。因此对象可以放心设置一年期的 immutable 缓存，更新时换 URL 即可。代价是旧对象不会自动消失，需要定期清理。

命令执行完会直接打印 Markdown 片段或 gallery 配置，粘贴进正文即可。上传成功后本地源文件应当删除，仓库里不保留副本。构建阶段也不会访问 MinIO：对象存储挂了，页面仍然能构建和打开，只是图片加载失败。

目前的限制主要来自入口：CLI 默认单文件上限 50 MB，Cloudflare 代理的请求体大小也有上限。更大的文件需要另开不经代理的路径，或者换用对象存储的其他接入方式。

5. Artalk：评论是独立服务#

评论没有塞进静态站，而是自托管了一套 Artalk。它作为独立容器接在 VPS 的 web 网络上，由 Nginx 按评论域名反向代理，数据目录单独挂载持久化，同样不映射宿主机端口。容器还限制了内存上限并配置了日志轮转，避免评论服务拖垮整台小机器。

前端集成在 Comments.astro 里，几个细节值得说明：

• 懒加载：评论容器进入视口前 400 px 时才动态 import("artalk")，首屏不加载评论库。
• 配合 Swup：在 content:replace 前销毁实例，在 page:view 后重新初始化，避免站内跳转后出现重复的评论框。
• 主题同步：监听 <html> 的 class 变化，把暗色状态传给 Artalk。
• 页面标识：默认使用 window.location.pathname 作为 pageKey，每篇文章和留言板各自拥有独立评论区。
• 头像：站点所有者的邮箱哈希映射到本地头像，其他访客交给第三方头像服务生成。

评论是客户端渲染的，所以文章正文可以先出来，评论区域稍后加载。Artalk 服务不可用时，影响范围仅限于评论区，不会阻塞页面阅读。

6. 备份与故障边界#

这套结构里，不同组件失效的表现并不一样：

因此备份要覆盖三类数据：仓库本身（GitHub 和本地各一份）、家庭主机上的 MinIO 数据目录、VPS 上的 Artalk 数据目录。对象存储可以额外用 mc mirror 做一次异地副本；备份真正有价值的前提是做过恢复演练，否则只能算“有一份文件”。

另一个容易被忽略的点是凭证。MinIO 的 root 账号只用于管理，日常上传使用单独账号；.env 被 .gitignore 排除，密钥不进入构建产物。凭证一旦泄露，正确做法是删除旧账号、重建并轮换，而不是只改一个密码。

7. 关于本文的隐私边界#

这篇文章只描述结构和取舍，不写真实 IP、私网地址、端口、密钥、内部主机名和数据目录。文中出现的地址、端口和配置都是占位符或通用示例，不能直接用于访问这套系统。

对个人博客来说，公开的是内容，不是基础设施。把“哪些东西应该暴露、哪些只该留在私网”想清楚，比多装一个监控组件更重要。