从零搭一个个人博客:架构和踩过的坑

#建站#运维

Co-authored-by: Claude

这个博客从写第一行代码到上线,用的是 Next.js + Payload CMS + SQLite,跑在一台 1 核 1G 的 VPS 上。这篇记录两件事:整体架构长什么样,以及过程中真正值得注意的几个坑。

整体架构

flowchart TD
  A["浏览器"] -->|"HTTPS (443)"| B["Caddy<br/>自动证书 · http→https · www→主域名"]
  B -->|"127.0.0.1:3000(只在本机可见)"| C["Docker 容器<br/>Next.js + Payload:前台、/admin、/api"]
  C --> D[("/srv/blog/data(挂载在容器外)<br/>blog.db + media/")]

几个组件各自的理由:

  • Next.js + Payload:后台、数据库访问、API、前台都在同一个 TypeScript 项目里。Payload 根据集合定义自动生成后台界面和 REST 接口,前台页面在服务端直接查数据库,不走 HTTP。
  • SQLite:单人博客的数据量和并发都很小,一个文件就够了,不用另外运行数据库服务。备份也只是备份文件。
  • Caddy:HTTPS 证书全自动,配置文件只有十行。
  • Docker:服务器上只需要装 Docker,不用管 Node.js 版本。

发布流程:

flowchart TD
  P["git push"] --> K["检查:类型 · ESLint · 测试"] --> B["构建镜像,推到 GHCR"] --> D["部署脚本:备份 → 切换 → 健康检查"]
  D -. "失败" .-> R["自动回滚"]

另外每天凌晨会用 sqlite3 .backup 给数据库做一次快照(异地备份还在搭建中)。

踩过的坑

1. 自定义校验把「必填」吃掉了

现象:一篇文章没填 slug 也发布成功了,链接变成了 /posts/null。

原因:在 Payload 里,字段一旦写了自定义 validate,就会替换掉自带的校验,required: true 的检查也在其中。我写的格式校验对空值直接放行,于是 required 形同虚设。

解决:先调用自带的校验,再做自己的检查(简化后的写法):

TypeScript
import { text } from 'payload/shared'

validate: (value, options) => {
  const builtIn = text(value, options) // 自带校验:必填、长度
  if (builtIn !== true) return builtIn
  return !value || /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value) || '只能包含小写英文、数字和短横线'
}

另外,开了草稿功能后,数据库里这些列都允许为空(草稿本来就可以不完整),所以数据库不会兜底,规则只能靠应用层守住。

2. 开发用 push,生产必须用迁移

Payload 在开发模式下会自动对比集合定义和数据库,直接改表(push 模式)。很方便,但它只知道「最终要长什么样」,不知道你的意图:把字段改个名,它会理解成「删一列、加一列」,数据就没了。

所以生产环境要用迁移:改完字段执行 payload migrate:create,生成的 SQL 提交进 git,部署时只执行还没跑过的那几个。

一定要人工检查生成的 SQL。 给用户加 role 字段时,自动生成的语句是:

SQL
ALTER TABLE users ADD role text DEFAULT 'writer' NOT NULL;

照这样执行,已有的管理员账号会变成 writer,部署完就进不了后台了。需要在迁移里手动补一句数据修正:

SQL
UPDATE users SET role = 'admin';

自动生成的迁移只管表结构,不管已有的数据。

3. 运行中的 SQLite 不能直接复制

博客运行时可能正在写数据库,这时 cp 拿到的可能是写了一半的文件。要用 SQLite 自带的在线备份:

Shell
sqlite3 /srv/blog/data/blog.db ".backup /srv/blog/backup/blog.db.tmp"
sqlite3 /srv/blog/backup/blog.db.tmp "PRAGMA integrity_check;"   # 应输出 ok
mv /srv/blog/backup/blog.db.tmp /srv/blog/backup/blog.db

先写临时文件、校验通过再 mv,任何时候来拿备份的人都不会拿到半成品。

4. 数据必须放在容器外面

容器里写入的文件跟着容器一起生灭,而每次部署都会删掉旧容器、创建新容器。数据库和图片要挂载到服务器的目录上:

YAML
volumes:
  - /srv/blog/data:/app/data

两个细节:

  • 容器里用非 root 用户(uid 1001)运行,服务器上的数据目录要 chown 1001:1001,否则写不进去。
  • SQLite 不会自动创建父目录。data/ 被 .gitignore 忽略后,新 clone 的项目启动就会报错,所以在里面放一个 .gitkeep,让空目录也能进 git。

5. 小内存服务器上不要构建

next build 很吃内存(项目的构建脚本把 Node 的内存上限设到了 8GB),1G 的机器很可能撑不住。所以服务器只负责拉镜像和运行,构建交给 GitHub Actions。

还有一个容易忽略的点:CPU 架构。在 Apple Silicon 的 Mac 上构建出来的镜像是 arm64 的,而大多数 VPS 是 amd64,拿过去直接跑不起来。临时从本机构建要加 --platform linux/amd64;放到 CI 上构建则天然没有这个问题。

6. fail2ban 在运行,却什么都没看到

Debian 12 默认不再写 /var/log/auth.log,登录日志在 systemd 的 journal 里。fail2ban 按默认配置去读文件,服务显示正常运行,实际上一次失败登录都没记到。

INI / 配置文件
# /etc/fail2ban/jail.local
[DEFAULT]
backend = systemd

改完之后要验证:故意用错误的用户名登录一次,再看 fail2ban-client status sshd 里的失败次数有没有加一。安全措施最怕的就是「看起来在工作」。

7. Docker 映射的端口会绕过防火墙

ufw 只放行了 SSH、80 和 443,但 Docker 映射出来的端口是 Docker 自己改 iptables 规则开出来的,不经过 ufw。如果写成 3000:3000,博客的 3000 端口会直接暴露在公网上,可以绕过 Caddy 访问。

所以只绑定到本机:

YAML
ports:
  - '127.0.0.1:3000:3000'

外网流量只能从 Caddy 进来。

小结

回头看,真正花时间的不是写页面,而是这几类问题:数据会不会丢(迁移、备份、挂载),安全措施是不是真的生效(fail2ban、端口),以及开发环境和生产环境的差异(push 与迁移、CPU 架构、内存)。它们共同的特点是:出错时不报错,等发现时已经晚了。所以每做完一步,都要实际验证一次。