DNS on Sisy's Blog

自部署 Moe-Counter

Fri, 17 Apr 2026 00:00:00 +0000

前言

起因是看到 osu! 玩家 IamKwaN 的 profile 上有一个很像 shields.io 风格的访问计数器，让我想起非常多人都喜欢在自己的博客或者 GitHub Profile 上挂一个类似的 hit counter 来统计访问量。

他这个计数器点击之后会跳转到一个 bit.ly 托管的短链接（估计是为了隐藏真实链接防止屏蔽之类的），最终重定向落在一个叫 Flag Counter 的服务上，显示他这个 profile 关于访问次数和访客所属地区分布的详细信息。

我还是蛮喜欢这个小巧的 mini counter 的，比起他们普通的 flag counter 要美观很多。这个服务免费、很完善，且似乎自带一定的流量控制，短时间内重复访问不会多次计数————美中不足之处就是这个服务不是开源的（）。于是我就自己注册账号生成了一个唯一链接，结果又发现一个头疼的问题：

访问次数很少的时候，这个图片的长度居然与访问次数 6 位数时看起来差不多长！这样右边就有一坨空白，而且官方给的 url 链接配置参数里也没有什么能控制图片宽度的选项，感觉有点逆天。。。

于是我试图找到类似的 website hit counter 的开源替代品，结果回想起来很多 booru 站点甚至包括 Steam，都有类似 n 个二次元人物手举数字牌子的访问计数器，最后终于找到了 Moe-Counter 这个项目（没想到居然是国人写的项目）。

Moe-Counter 是一个支持多种主题的萌萌计数器，支持直接用他们自己的服务器和已部署到公网的 WebUI 生成一个唯一 id 的链接来用，另外 README 里也写了本身支持 Docker 部署。

看起来搭建不算复杂，但当我真正想把它跑在自己的服务器上、对公网开放访问、挂上自定义域名、提供 HTTPS 安全连接的时候，才发现从"能跑"到"能用"之间还有不少坑要踩。不过正好能顺便学一下用 Nginx 反代一个服务，以及用 Certimate 来自动化管理 HTTPS 证书，另外似乎还有一些 Cloudflare DNS 配置的细节也需要注意，还能练练 Docker compose ———— 嗯嗯。。。不错的实践机会。

那么下面就开始吧！

预备步骤

先拉下来熟悉一下结构。

1
2
3


git clone https://github.com/journey-ad/Moe-Counter.git
cd Moe-Counter
ll

项目结构

项目结构比较清晰，几个关键目录和文件：

路径	用途
`views/`	页面模板（Pug），首页展示逻辑在这里
`assets/`	静态资源，包括各种主题的数字图片
`utils/`	工具函数，主题加载逻辑
`db/`	数据库适配层（SQLite / MongoDB）
`index.js`	入口文件，路由定义
`.env.example`	环境变量配置模板
`Dockerfile`	Docker 构建文件
`docker-compose.yml`	Docker Compose 配置

看样子还能自己加主题，只要在 assets/ 里放一套 1-9 的数字图片，然后在 views/index.pug 里加个选项提供到 WebUI 首页上就行了。

现代的 Docker Compose 已经（详见这篇和这篇）

弃用了 docker-compose.yml 文件名，改使用 compose.yaml
compose 文件中也不推荐再使用 version 字段了，直接写服务定义就行了

不过这个项目里还是用的一些旧标准，不过也不影响使用————虽然我还是把这两个都改掉了。

配置一下

env 先复制一份：

1

cp .env.example .env

.env 文件的主要配置项：

1
2
3
4
5
6
7
8
9


# 这个 URL 是给生成的访问计数器图片链接用的，必须是公网可访问的 URL
# WebUI 中的各个示例计数器图片也都是基于这个 URL 拼接的
# 后面会用到 Cloudflare 反代，所以这里直接填最终访问的 URL 就行了
APP_SITE=https://moe.sisy.cc

APP_PORT=3000
DB_TYPE=sqlite
DB_INTERVAL=60
LOG_LEVEL=debug

它还支持 MongoDB，不过如果只是个人用，感觉 SQLite 完全够了。

因为我考虑后续需要编辑项目内容（增加访问次数去重逻辑、添加自定义主题之类的），所以不能直接 docker pull 官方镜像，而是要从源码本地构建。另外，他这个 docker-compose.yml 的内容本来也唐完，因此 compose.yaml 也得改，先看看原先的 docker-compose.yml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


version: '3' # 已经不推荐写 version 了
services:
 moe-counter:
 build: . # 得加一条 image 指定构建目标是本地镜像
 ports:
 - "3000:3000"
 volumes:
 - ./data:/app/data
 environment: # 额，首先这不优雅，其次你不是有 .env 文件了么
 - APP_PORT=3000
 - DB_TYPE=sqlite

改成下面这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


services:
 moe-counter:
 build: .
 image: moe-counter:local
 container_name: moe-counter
 ports:
 - "3000:3000" # 注意这里，后面用 Nginx 反代后会更优雅一些
 volumes:
 - ./data:/app/data
 env_file:
 - .env
 restart: unless-stopped

这样就差不多能起了。

实现公网可达

1
2
3
4


docker compose up -d
docker logs -f moe-counter # 也可以不看日志，这个服务比较简单。
curl -I http://localhost:3000 # 应该返回 HTTP/1.1 200 OK
curl http://localhost:3000 # 或者用 Termius 的 Port Forwarding 直接在浏览器看效果也行

此时不仅能在 VPS 本地 curl 访问，而且其实已经可以成功从远端使用 http://<服务器 IP>:3000 访问到 WebUI 了，只不过还没有域名和 HTTPS，比较丑陋。

而且直接用 3000 端口将服务暴露出去也不太漂亮，后面用 Nginx 反代一下，把 80/443 的流量转到 3000，这样就能在单端口开多个服务，非常优雅。

不过在 Nginx 配置之前，先把这个服务的 3000 端口绑定在回环地址上，这样外网就无法直接访问了，所有流量都得走 Nginx 反代进来，也更安全。调整一下 compose 配置：

1
2
3
4


services:
 moe-counter:
 ports:
 - "127.0.0.1:3000:3000"

依旧验证：

1

curl -I http://127.0.0.1:3000 # return HTTP/1.1 200 OK

实现域名解析

既然已经能从公网访问了，下一步就是把域名指过来。

Cloudflare DNS 配置

DNS 服务用的是 Cloudflare，所以在 Cloudflare 里添加一条 A 记录：

类型	名称	内容	代理状态
A	moe	114.514.91.69	仅 DNS

访问 http://moe.sisy.cc，发现无法连接。这时反应过来浏览器访问域名时默认连的是 80 端口，而我的服务跑在 3000。自建服务跑在非标端口时，中间必须有一层反代来转发流量。

不过 Cloudflare DNS 侧已经无需再动，接下来把 Nginx 反代调通就完成域名解析了。

Nginx 反代

解决端口问题的标准做法是用 Nginx 做反向代理：浏览器访问 80/443 → Nginx 接住 → 转发到本地 3000 → Moe-Counter 处理 → 原路返回。由于暂时没有证书，我们的思路就是先监听 80，确认反代没问题后再配置证书，然后把 Nginx 配置也同步升级到 443 与 HTTPS 支持。

先安装一下：

1

sudo apt update && sudo apt install -y nginx

新建 /etc/nginx/sites-available/moe-counter 来放本站的 Nginx 配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


server {
 listen 80;
 server_name moe.sisy.cc;

 location / {
 proxy_pass http://127.0.0.1:3000;
 proxy_http_version 1.1;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 }
}

启用并重载：

1
2
3


sudo ln -s /etc/nginx/sites-available/moe-counter /etc/nginx/sites-enabled/
sudo nginx -t # 测试配置正确
sudo systemctl reload nginx # 热重载新配置

此时浏览器访问 http://moe.sisy.cc 就能返回 WebUI了，HTTP 就通了，接着往下做 HTTPS。

HTTPS: 证书与 ACME 自动化

HTTPS 这一步，感觉真是懒得渐进式优化了，直接上 ACME 自动化证书维护吧。横向对比了一圈，最终还是决定使用 Certimate 来管理证书。瞧瞧这优雅的工作流！（虽然我由于时间原因把工作流中的错误处理节点删了，等后续有机会再加回来吧）

为什么不用 Certbot？

Certbot 是最常用的 Let’s Encrypt 客户端，单机单域名场景下非常省事——一条命令就能申请证书并自动改写 Nginx 配置。但我选择了 Certimate，主要出于几个考虑：

DNS-01 验证：HTTP-01 验证需要 CA 直接访问 80 端口，而且没法签发通配符证书。DNS-01 只需要在 DNS 里加一条 TXT 记录，完全不走 HTTP 流量，还支持通配符证书。并且 Certimate 对 Cloudflare 的 DNS API 支持得很好，能自动增删改查 TXT 记录。
集中管理：其他域名、服务器需要证书，Certimate 可以统一管理，不需要每台机器都装一遍 Certbot。
Web 面板：比起 Certbot 的命令行，有个面板看着更直观，工作流的触发记录、证书状态一目了然。
定时任务：据可靠消息，Certimate 的定时任务应该比 Certbot 的更可靠一些。

当然 Certbot 本身完全够用，如果你只有一个域名、一台服务器，用 Certbot 反而更简单。

部署 Certimate

Certimate 本身也是一个 Web 应用，为优雅性，自然是用 Docker 跑。因为它能 SSH 你的服务器、调用 Cloudflare API 改 DNS，权限很大，并且 README 里提供了初始 Admin 账户的邮箱和密码，所以绝对不能把管理面板暴露到公网，否则被攻击就惨了。

先拉一下 Docker Compose。注意最好不要用官网的一键起容器的脚本，因为它会把面板暴露在 8090 端口上，直接暴露在公网是非常危险的。我们要改成只绑定在回环地址上，需要拉下来之后先改 compose 文件，这样外网就无法访问了，所有流量都得走 SSH 隧道进来。

1
2
3
4
5
6


mkdir -p ~/certimate && \
cd ~/certimate && \
curl -O https://raw.githubusercontent.com/certimate-go/certimate/refs/heads/main/docker/docker-compose.yml

mv docker-compose.yml compose.yaml
vim compose.yaml

改一下回环和版本号，其他默认：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


# version: "3.0" 不要这个
services:
 certimate:
 image: certimate/certimate:latest
 container_name: certimate
 ports:
 # - 8090:8090 不要这个
 - "127.0.0.1:8090:8090"
 volumes:
 - /etc/localtime:/etc/localtime:ro
 - /etc/timezone:/etc/timezone:ro
 - ./data:/app/pb_data
 restart: unless-stopped

这里 -p 127.0.0.1:8090:8090 保证面板只能从服务器本机访问。管理时，通过 SSH 端口转发就行了。保存之后直接起面板：

1
2
3


docker compose up -d
docker logs -f certimate
curl -I http://127.0.0.1:8090

我用的访问终端是 Termius，在 Port Forwarding 里加一条 Local 规则：

字段	值
Label	Certimate
Local Port number	8090
Local address	127.0.0.1
Intermediate Host	Host Name
Destination Host	127.0.0.1
Destination Port	8090

保持 SSH 连接后，在本地浏览器打开 http://127.0.0.1:8090 就能进入 Certimate 面板。断开 SSH 后面板自动不可达，安全性拉满。

熟悉一下 Certimate 面板

进来之后第一件事当然是先改掉默认的 Admin 账户和密码了。设置里还有一些全局的 ACME 配置项，基本不太需要动，之后写新的工作流的时候，直接细调工作流内局部的配置就行。

Certimate 的核心功能是工作流，它把申请证书、部署证书、续期检查这些操作都抽象成一个个节点，然后串成一个流程。我们的思路就是写一个工作流来实现以下流程的自动化：

1

申请证书 → 部署到 Nginx → 定时续期 (→ 检查和续签时发现错误 → 告警)

至于其他页面，都可以视为工作流涉及的其他附属内容了。比如证书页面能看到每个证书的详细信息和状态，仪表盘页面能看到每次工作流执行的日志，授权凭证页面能看到工作流中涉及的各种第三方服务的授权信息（Cloudflare API Token、SSH 密钥之类的），等等。

工作流各节点配置

先从一个默认模板开始就好。

开始节点

工作流的触发方式有分手动和自动，那显然是自动啊！所以选一下定时触发。Certimate 的定时任务使用 Cron 表达式，先设置成 30 1 * * *，每天凌晨 1:30 执行一次。至于为什么每天走一遍工作流，可以看下面的 TLS 续期策略部分。

申请节点

首先配置证书颁发给哪些域：这里除了用通配符 *.sisy.cc 之外，别忘了要加上根域 sisy.cc。

验证质询

由于 HTTP-01 质询需要 CA 直接访问 80 端口，而且不支持通配符证书，所以质询方式一般选 DNS-01，配合 Cloudflare API 来自动添加 TXT 记录。因此 DNS 提供商选 Cloudflare。

此时还需要添加一个 Cloudflare 颁发的 API Token 来授权 Certimate 通过这个 API Token 修改 Cloudflare 上的 DNS 记录。

配置 Cloudflare API Token

主要还是参考这一篇文章：Cloudflare Fundamentals - Create API token

在 Cloudflare → My Profile → API Tokens → Create Token 里用 “Edit zone DNS” 模板创建：

权限保持默认的 Edit 权限，因为我们需要 Certimate 自动增删改查 TXT 记录来完成 DNS-01 验证。唯一需要改的就是 Zone Resources，选择 Specific zone 并且只选 sisy.cc 这个域，而不是 All zones，否则一旦 Token 泄露了，攻击者就能更改 Cloudflare 账号下所有域名的 DNS 记录。最小权限原则是几乎零成本的安全加固。

不过客户端 IP 地址筛选可以不动他，限制一台部署 Certimate 的主机访问的确可以，但没什么必要。TTL 也不需要额外修改，此时点击 继续以显示摘要 按钮，确认权限和资源范围都正确后，点击 创建令牌，就能拿到这个 API Token 的值了。把它复制下来，填到 Certimate 的授权凭证里：

证书设置

Certimate 的证书设置里有几个参数需要选择，简单说一下每个怎么填：

私钥来源 → 随机生成。每次续期都生成新的私钥，万一某一代私钥泄露，影响范围更小，具有向前安全性。“复用私钥"是给 HPKP（已废弃）和 DANE/TLSA 这类特殊场景用的，普通网站不需要。

注意，以下颁发机构均使用 Google Trust Services，情欲先了解ACME EAB 账号获取的相关信息，难以完成则使用 Let’s Encrypt 即可。

颁发机构 → Google Trust Services。具体原因依旧可以看下面的 TLS 续期策略部分。

颁发机构授权：这个由于我们用的是 Google Trust Services，所以需要一个 ACME EAB 账号，拿到这个授权的 ID 和 Key 后把它们填到申请节点的对应字段里。关于如何获取，请参考使用 Public CA 和 ACME 客户端请求证书。

有效期 → 47 天。具体原因依旧可以看下面的 TLS 续期策略部分。

首选链 → 留空/默认。以前有人为了兼容老旧 Android 手动选链到 DST Root CA X3，但那条链 2024 年 9 月已经过期了，现在默认的 ISRG Root X1 兼容所有主流设备。

ACME 配置文件 → classic（默认）。classic 对应长有效期的传统证书。另一个选项 shortlived 是 7 天有效期的超短期证书，对自动化系统稳定性要求极高，个人项目没必要用。

阻止 CSR 包含主题通用名称 → 不勾选。这个选项会禁止在 CSR 里包含通配符证书的通用名称（CN），只把域名放在 Subject Alternative Name (SAN) 里。这个选项是为了兼容一些老旧 CA 的奇葩要求的，现代 CA 都没问题，所以不选。

重复申请

设置为当上次申请证书成功后、且证书剩余有效期大于 17 天，再次运行工作流时跳过此申请节点。具体原因依旧可以看下面的 TLS 续期策略部分。

踩坑：容器文件隔离

起初以为“部署节点”部分不怎么需要动，结果Certimate 第一次执行工作流后，虽然面板提示证书签发成功，路径是 /etc/ssl/certimate/cert.crt 和 /etc/ssl/certimate/cert.key，但是我直接在 Nginx 配置里填这两个路径，nginx -t 直接报错：

1
2


cannot load certificate "/etc/ssl/certimate/cert.crt": BIO_new_file() failed
(SSL: error:80000002:system library::No such file or directory)

排查了一下，发现问题是，事实上证书写在了 Certimate 容器内部的文件系统里，宿主机根本看不到。Docker 容器的文件系统和宿主机是完全隔离的，除非做了 volumes 挂载，否则两边的 /etc/ssl/certimate/ 是两个毫无关系的目录。然而即使挂载到宿主机，每次重新申请证书后，也无法触发宿主机上的 Nginx 重新加载，这样就需要在 Certimate 中配置一个 Webhook，还需要自己写一个脚本来监听这个 Webhook，收到通知后再执行 nginx -t && systemctl reload nginx，感觉极其麻烦。（理论上应该可以通过“部署后事件”来解决）

解决方案：在 Certimate 的工作流里改用 SSH 部署节点，让 Certimate 通过 SSH 把证书从容器内部推送到宿主机的真实路径。操作步骤：

在宿主机上生成一对 SSH 密钥：

1
2
3


ssh-keygen -t ed25519 -f ~/.ssh/certimate_deploy -N "" -C "certimate-deploy"
cat ~/.ssh/certimate_deploy.pub >> ~/.ssh/authorized_keys
cat ~/.ssh/certimate_deploy # 用于填充到 Certimate 面板里

Certimate 部署节点中，部署目标选择 SSH
主机提供商授权中输入服务器 IP、端口、用户，以及上一步生成的 SSH 私钥内容。
证书和证书密钥的输出路径还填 /etc/ssl/certimate/cert.crt 和 /etc/ssl/certimate/cert.key。

再次执行工作流，这次证书成功落到宿主机的目录下，Nginx 终于能读到了。

升级 Nginx 配置为 HTTPS

证书到位后，把 Nginx 配置升级为 HTTPS:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


# Redirect HTTP to HTTPS
server {
 listen 80;
 server_name moe.sisy.cc;
 return 301 https://$host$request_uri;
 }

 # HTTPS main service
 server {
 listen 443 ssl http2;
 server_name moe.sisy.cc;

 ssl_certificate /etc/ssl/certimate/cert.crt;
 ssl_certificate_key /etc/ssl/certimate/cert.key;

 # Recommended SSL params
 ssl_protocols TLSv1.2 TLSv1.3;
 ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;
 ssl_prefer_server_ciphers off;
 ssl_session_cache shared:SSL:10m;
 ssl_session_timeout 1d;

 location / {
 proxy_pass http://127.0.0.1:3000;
 proxy_http_version 1.1;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 }
}

测试并重载：

1
2


sudo nginx -t
sudo systemctl reload nginx

访问 https://moe.sisy.cc，浏览器里的证书锁和证书详情应该都会出现，这样 HTTPS 就大功告成了！

TLS 续期策略

我申请到的证书有效期是 47 天，截至我写这篇博客的时候，只有 Google Trust Services 一家提供了 47 天有效期的证书。秒选啊秒选。

关于为什么现代网络正在推行 90 -> 47 天的更短期证书，可以参考 CA/Browser Forum 上投票决定的结果，在这之前提出并推动此事的这篇文章，以及这篇分享此事的博客。

简单来说，2025 年早些时候，Apple 公司提出了一项缩短证书有效期的动议，该动议得到了 Sectigo、Google Chrome 团队和 Mozilla 的支持。该提案将在未来四年内逐步缩短证书的有效期，从截至 2025 年的 398 天需求，在 2029 年 3 月之前缩短到 47 天需求。这个提案的目标是最大限度地降低因证书数据过期、加密算法过时以及长期暴露于泄露凭证而带来的风险。此外，它还鼓励企业和开发者利用自动化手段来更新和轮换 TLS 证书，从而降低网站运行在过期证书上的可能性。

我的证书工作流的时间策略为：

参数	值
工作流触发频率	每天 1 次
提前续期阈值	15 天

“每天触发"听起来很频繁，但 Certimate 会先检查证书的剩余有效期，没到阈值就跳过，不会真给 CA 发请求。这样设置的好处是

失败后有足够的重试窗口——如果某次续期因为网络抖动失败了，明天还会再试。设 15 天阈值意味着有 15 次重试机会。
失败后证书还有足够的剩余有效期，可以有充足的时间手动介入修复问题，不至于证书过期了才发现。

如果把触发频率设成 30 天，万一到了续期的那一次恰好失败，下一次触发时证书已经过期了——47 天的证书根本扛不住 30 天的触发间隔。

续期时间的把控则是另一种思路：既要保证充分利用证书的有效期，又要留足时间介入修复问题。根据大佬的经验法则，续期阈值设为证书有效期的 1/3 左右，平衡利用率和安全缓冲。对我来讲，47 ÷ 3 ≈ 15 天，刚好。

另外强烈建议在 Certimate 里配一个失败通知（邮件、Webhook 等），这样续期失败时能第一时间收到告警，不至于证书悄悄过期了几天才发现（额，虽然我还没配）。

最终架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


[浏览器]
 │
 │ HTTPS (443)
 ▼
[Cloudflare DNS]
 │
 │ HTTPS (443)
 ▼
[Nginx] ── Listening 80/443, TLS managed by Certimate
 │
 │ HTTP (Reverse Proxy to 3000)
 ▼
[Docker: Moe-Counter] ── 127.0.0.1:3000, SQLite Persistent Volume

[Docker: Certimate] ── 127.0.0.1:8090, managed by SSH Port Forwarding
 │
 │ DNS-01 (Cloudflare API) Certimate in Docker deploys certs to host via SSH
 ▼ ▼
[Google Trust Services] [Host /etc/ssl/certimate/]

整个架构里：

公网只开放 80/443 和 22（SSH），Moe-Counter 的 3000 和 Certimate 的 8090 都只绑在回环地址上，外网不可达。
HTTPS 证书由 Certimate 自动申请、部署、续期，不需要人工介入。
Cloudflare 提供 CDN 和 DDoS 防护，SSL 模式用最安全的 Full (Strict)。
通过 SSH 端口转发访问 Certimate 面板，管理界面零暴露。

涉及到三种（理论上如果配了告警应该还有更多）第三方授权服务：

Cloudflare API Token：用于 Certimate 的 DNS-01 验证，权限最小化只允许编辑 sisy.cc 的 DNS 记录。
SSH 密钥：用于 Certimate 的 SSH 部署节点，用于把证书从容器内部推送到宿主机的真实路径。
Google Trust Services EAB：CA 需要 EAB（外部账户绑定）来验证申请者的身份，Certimate 也支持配置 EAB 的 Key ID 和 Key Secret 来完成绑定。

从"能跑"到"能用”，确实比想象中多了不少环节。但每一层都有其存在的意义：Docker 隔离运行环境，Nginx 统一入口和端口管理，Certimate 自动化证书生命周期，Cloudflare 提供边缘防护…… 搞清楚每一层在干什么之后，以后再部署别的服务也是同一套模式，而且熟悉了会快很多，换个容器就行了。

长吁。。终于把这个博客的访问计数器部署好了，虽然过程比想象中复杂了不少，不过成果是令人欣慰的。之后就可以在自部署的环境中生成各种主题的访问计数器图片了！

喂，别忘了配置一下 Certimate 的续期失败通知啊（

将博客迁移至 Hugo

Thu, 19 Mar 2026 00:00:00 +0000

前言

我的博客之前用的是 Astro 的某个主题，但是 Astro 作为博客构建工具的使用体验并不好，因为它本身的设计哲学实际更侧重于为文档站点服务。

前段时间 MoonWX 在 Q 群里分享 ntzyz 大佬的博客站，感觉大佬这个很简洁干练，不是很花哨，但是又很有技术博客的 feeling，而且并不丑，相反还蛮好看的。（顺带一提这位还是 BGP 大神，之后有空还想 peer 一下）

博客底部标注了由 Hugo 构建，使用 Hugo Theme Stack 主题，而且 Hugo Theme Stack 的 Github README 里提供了一个 starter 项目，可以作为 template 使用。那么我就直接用这个 starter 来搭建我的博客吧，希望能有个更好的使用体验。

Stack 主题在 README 中提供了双语文档，这里不多赘述。

迁移过程

托管到 GitHub Pages

首先按照常规操作，想要托管到 GitHub Pages 的话，使用 starter 的 template 来创建新的仓库的时候，需要注意仓库的命名最好为 <username>.github.io，这里我就是 sisypheovo.github.io，以便于直接被识别为 GitHub Pages 的托管仓库。

创建好仓库之后，在仓库的 Settings -> Pages 页面中，将 Build and deployment 中的 Source选项设置为 GitHub Actions，以便自动化部署，毕竟 starter 里已经提供了 GitHub Actions 的 workflow 文件了。

这样就完成了托管，在 https://sisypheovo.github.io/ 就可以直接访问到博客了，只不过内容还全是一些示例和模板，而且侧边栏之类的相比 ntzyz 大佬的博客也差远了.

使用自定义域名

常规来讲，要将任何普通内容部署到自己的域名下，最常用的做法肯定还是通过面板，比如 1Panel 之类的。购买并配置域名之后，把编译产物上传到服务器上就行了，然后配一配 DNS 解析、HTTPS 和反向代理等等配置就行了。

但是因为是使用 GitHub Pages 的静态博客，而且域名托管在 Cloudflare，就我知道的而言，有两种方法：

用 CNAME 文件配置自定义域名，并在 Cloudflare 中添加 CNAME 记录，指向 <username>.github.io，服务器只做 DNS 解析。
服务器使用反向代理，将自定义域名的请求转发到 GitHub Pages 的 URL 上。

我个人感觉第一种方法更简单一些，毕竟不需要额外的服务器来做反向代理了，而且有 Github Pages 提供的各种自动化和安全服务，还有免费的 HTTPS 和证书。

第二种就是可以自己做缓存、加速，自定义后端逻辑之类的，还能隐藏真实托管源，但是我也不太需要这些功能，所以就直接用第一种方法了。

首先去到 Cloudflare 的管理面板，在 域注册 -> 管理域 中选择对应的域名（我这里就是 sisy.cc），进入到域名的管理页面中，在 DNS -> 记录 选项卡中添加一条 CNAME 记录：

类型	名称	内容	代理状态	TTL	操作
CNAME	blog	sisypheovo.github.io	仅 DNS	自动	编辑

添加完成之后，还是回到仓库的 Settings -> Pages 页面中，将 Build and deployment 中的 Custom domain选项设置为 blog.sisy.cc，勾选上 Enforce HTTPS 选项，这样就完成了自定义域名的配置，过一段时间之后访问 blog.sisy.cc 就可以访问到博客了。

顺带一提，如果不是用 GitHub Pages，而是自己搭建的服务器，那么配置自定义域名的方式会有所不同，比如需要在编译产物的根目录下放置 CNAME 文件，内容是 blog.sisy.cc。

配置

这个主题我说白了用明白还是蛮好用的（等于不好上手吧，额），但是前期配置比较痛苦，因为它各个功能的配置项都比较分散，文档也不全，配置项上的注释也没几个字，很多东西莫名其妙的。

一些普通的配置解读

config/_default/markup.toml 文件中配置了 Markdown 的渲染方式，使用了 Goldmark 这个渲染器，并且启用了各种扩展功能，比如 Latex、表格、脚注、定义列表等等。
config/_default/modules.toml: 这个是 Hugo Modules 的配置文件，里面指定了使用的 Hugo Theme Stack 主题的版本和路径。
config/_default/permalinks.toml 文件中配置了文章的 URL 结构，比如 posts 的 URL 就是 /posts/:slug/，也就是 https://blog.sisy.cc/posts/xxx/ 这样的结构；page 的 URL 就是 /:slug/，也就是 https://blog.sisy.cc/xxx/。
config/_default/related.toml: 不知道，看不懂，先放着

`config.toml`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


baseurl = "https://blog.sisy.cc/" # 博客的基础 URL，用于生成链接和资源路径
languageCode = "zh" # 博客的默认语言代码，这里设置为中文
title = "Sisy's Blog" # 博客的标题，会显示在浏览器标签页、页脚的标注、头像下面的标题

# Theme i18n support
# See all available values at https://github.com/CaiJimmy/hugo-theme-stack/tree/master/i18n
defaultContentLanguage = "zh"

# Set hasCJKLanguage to true if DefaultContentLanguage is in [zh ja ko]
# This will make .Summary and .WordCount behave correctly for CJK languages.
hasCJKLanguage = true

# Disqus 评论系统的短名称，在 Disqus 上添加站点的时候会生成一个短名称，用于标识这个站点的评论系统
disqusShortname = "sisypheovo"

[pagination]
 pagerSize = 5

`_language.toml`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# Rename this file to languages.toml to enable multilingual support
[zh]
 languageName = "中文" # 语言名称，会显示在页面左下角的语言切换器中
 languagedirection = "ltr" # 语言的书写方向，ltr 表示从左到右，rtl 表示从右到左
 title = "Sisy's Blog" # 博客标题，在中文环境下会覆盖掉 config.toml 中的 title 配置
 weight = 1 # 语言的权重，数值越小优先级越高。

[en]
 languageName = "English"
 languagedirection = "ltr"
 title = "Sisy's Blog"
 weight = 2

特别对于权重而言，像这样不是 en 权重最大的话，创建各个博客文章的 index markdown 文件的时候，必须要有 index.en.md、index.zh.md，而不是 index.md 和 index.zh.md，否则默认的 index.md 文件会被视为 zh 的版本。也要记得跟普通的 i18n 情况不一样，index.md 不再是 en 的默认版本了。

另外，对于如上配置，各语言下内容的 URL 结构为 /xxx/ 和 /en/xxx/。

非内容的各个字符串（比如页脚文本）的翻译，可以通过在 i18n/ 目录下创建对应语言的 TOML 文件来配置，比如 i18n/zh.toml 中可以配置中文环境下的各种字符串的翻译。默认部分可以直接从示例仓库的这里复制整个文件过来，非常方便。

`menu.toml`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# 像这样在左侧菜单中添加一个不指向任何页面的链接菜单项
# 像这里我就做了一个 RSS 的链接，权重设置为 99，确保它在菜单的最下面显示。不过 icon 需要自己找一找。
# Hugo 的 RSS 订阅链接通常是 `/index.xml`，内容是由 Hugo 自动生成的，不需要手动创建。
[[main]]
 identifier = "rss"
 name = "RSS"
 url = "/index.xml"
 weight = 99

 [main.params]
 icon = "rss"

# 这个很好理解，是显示在头像和简介下方的社交链接，样例也给了两个 icon 状的示范。
[[social]]
 identifier = "github"
 name = "GitHub"
 url = "https://github.com/SisypheOvO"

 [social.params]
 icon = "brand-github"

关于自定义菜单内容，还可以参考这篇文档，除了在 menu.toml 文件中配置以 main 标识的这种非页面的链接菜单项之外，指向正常页面的菜单项是通过在各个页面（仓库中 /content/page/ 下的各个内容）各自的 index.md 文件前言部分中的 menu 字段来配置的。也就是说，各个 page 和每个菜单项是同步创建且一一对应的（除了在 menu.toml 中配置的项）。如以下这个简单的配置：

1
2
3
4
5
6
7


---
menu:
 main: # 默认是 main 就行
 weight: 4 # 标识这个 page 的排序，需要跨文件管理它们
 params:
 icon: people # 显示在菜单项左边的图标，默认是 svg 格式，放在 `static/icons/` 目录下
---

需要注意的是，如果想要添加一些自定义布局的页面，还最好需要额外创建一个 layouts/ 目录，在里面放置对应的自定义布局 HTML 文件。

以下是一个配置好的菜单示例：

`params.toml`

这个文件的配置项就比较多了，内容也比较杂乱，比如博客的主页显示、RSS 输出、favicon、文章排序、页脚信息、日期格式、侧边栏信息、文章信息、页面小部件、社交媒体信息、配色方案等等。关于这里配置的指导，在官方文档的这个 Config 部分解释的还是比较全面的，可以优先参考。

以下我挑一些非常适合新手起步的配置项来讲，其他要么已经解释的很清楚，要么就无需过多调整：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


favicon = "img/favicon.png" # 显示在浏览器标签页上的图标，写过 web 都懂

# 显示在所有页脚的内容
[footer]
 since = 2023 # 博客开始运营的年份，最终会显示为 "© 2023 - 2026 博客标题"
 customText = "sisy's blog" # 显示在 since 这一行下方

# 显示在博客右半侧的各种小组件，分为主页显示的和在子页面显示的组件两种
[widgets]
 homepage = [
 { type = "search" },
 { type = "archives", params = { limit = 5 } },
 { type = "categories", params = { limit = 10 } },
 { type = "tag-cloud", params = { limit = 10 } },
 ]
 page = [{ type = "toc" }]

[comments]
 enabled = true
 provider = "disqus" # 评论系统提供商

各个页面是否开启评论也可以通过在对应文件的前言中添加 comments: false 来单独控制，是否开启 toc 也是一样的，添加 toc: false 就行了。

以下是一个配置好的小组件示例：

优化

配置阶段就基本完结了，接下来就可以简单优化一下美观性了，比如我很想要 select 元素原始的下拉箭头，可以在 assets/scss/custom.scss 中添加：

1
2
3
4


.menu-bottom-section #i18n-switch select {
 appearance: auto;
 -webkit-appearance: auto;
}

Stack 主题适合用的两个 icon 源：Tabler、SVG Repo.

这一系列流程下来，博客就基本上安定下来，后续唯一的工作就是将旧的文章转移过来，然后写点新东西了。

使用 Cloudflare + Gmail 搭建邮件转发

Tue, 10 Mar 2026 00:00:00 +0000

前言

前段时间简单玩了一下 Cloudflare 的管理面板，其中一个 Email Routing 功能能够让用户通过 Cloudflare 的邮件服务器来转发邮件到自己的邮箱里。这一步从操作上实际比较简单，不过可以顺带了解一下邮件转发的原理和一些相关的概念，比如 MX 记录、SPF 记录、DKIM 记录等等。

后续发现在使用自定义邮箱身份的时候，用其他邮箱来发邮件给别人会带来困惑，因为对方无法确定邮件的来源，所以就在想能不能通过自定义域名来代发邮件呢？（话说为什么我一开始没有想到这个问题。。。一个自定义邮件名称的邮箱能收邮件，就一定可以发邮件，还是很自然的）

于是陆续把正反向邮件转发都搭建了一下。

自定义域名代收

在 Cloudflare 面板的 域注册 -> 管理域 中选择对应的域名（我这里就是 sisy.cc），进入到域名的管理页面中，在左侧选择 电子邮件 -> 电子邮件路由 选项卡。这个页面如果没用过的话先点击开始使用，进入真正管理电子邮件路由的页面。

进入 路由规则，在 自定义地址 版块中点击 创建地址，输入自定义地址（比如以 i@sisy.cc 代表本人），操作这一栏选择 发送到电子邮件（另一个选项 发送到 Worker 是用于将邮件发送到 Cloudflare Worker，以实现复杂邮件处理逻辑的），目标填写自己的 Gmail 邮箱地址，点击保存。这将会创建一个新的邮件转发规则：

自定义地址	操作	目标	状态
i@sisy.cc	发送到电子邮件	sisyphe.dev@gmail.com	活动

这样一来，他人向 i@sisy.cc 发送邮件时，邮件将会被转发到 sisyphe.dev@gmail.com。这一步的本质是，创建邮件转发规则后，Cloudflare 会自动生成一些 DNS 记录来支持邮件转发功能，包括 MX 记录、TXT 记录 (SPF 记录、DKIM 记录) 等。如下图中，可以看到 Cloudflare 已经自动添加了三条 MX 记录和两条 TXT 记录：

三条 MX 记录分别指向 route1.mx.cloudflare.net.、route2.mx.cloudflare.net. 和 route3.mx.cloudflare.net.，优先级分别为 4、88 和 84。这些 MX 记录告诉其他邮件服务器，当有人向 i@sisy.cc 发送邮件时，邮件将会被转发到 sisyphe.dev@gmail.com。而两条 TXT 记录则分别是 SPF 记录和 DKIM 记录，用于验证邮件的真实性，防止邮件被伪造或被标记为垃圾邮件。

自定义域名代发

简易的说明教程，可以看 Gmail 帮助：通过其他地址或别名发送电子邮件

邮件代发的原理是，在发送邮件时，使用自定义域名作为发件人地址，并通过某个邮件服务器（比如 Cloudflare 的邮件服务器）来发送邮件。这样一来，收件人就能够看到邮件是从自定义域名发送的，而不是 Gmail 的地址。事实上 Cloudflare 也确实提供了邮件发送功能，只不过要氪金，所以还是从 Gmail 这一边来下手吧。

添加发送地址

在 Gmail 设置页面中，进入 账户和导入 选项卡，找到 “发送邮件地址” 版块（如上图），点击"添加其他电子邮件地址"。这将会呼出一个弹窗。

在弹出的窗口中，输入计划用来代发的自定义邮件地址（比如 i@sisy.cc ），以及显示名称（比如 Sisy）。点击下一步，进入 SMTP 服务器设置页面。

这里 SMTP 服务器地址默认会被识别为 Cloudflare 的收件地址 route1.mx.cloudflare.net，端口 587，但是 Cloudflare Email Routing 只负责收件，它不提供 SMTP 发件服务。route1.mx.cloudflare.net 是它的接收邮件服务器（MX），不是发件服务器（SMTP）。所以需要改为 Gmail 的 SMTP 服务器地址，例如 smtp.gmail.com 或 smtp.your-school.edu，端口还是填 587（TLS 加密发件的标准端口）。

为什么希望用自定义域名代发邮件，这里却要填 Gmail 的 SMTP 服务器地址？这里的核心逻辑是：Gmail 本身不提供“直接用外部域名发信”的 SMTP 服务。当想用自定义域名发邮件时，Gmail 的机制是：

由 Gmail 的服务器（smtp.gmail.com）实际执行发件操作
但在邮件头里，把“发件人”声明为 i@sisy.cc

这里我就拿 smtp.gmail.com 来管理。用户名和密码则是 Gmail 的账户名和密码，用以验证发件身份，证明这个发件请求确实是由本人授权的。输入完成后点击 添加账号。

Tips: 这里很容易遇到问题，尤其是 Google 账号开启了两步验证的情况下。提示类似于：

1
2


身份验证错误。请检查您的用户名和密码。
服务器返回错误: "535-5.7.8 Username and Password not accepted. For more information, go to 535 5.7.8 https://support.google.com/mail/?p=BadCredentials 46e7d38a34.3 - gsmtp , code: 535"。

即登录凭据被拒。这时候需要用到一个叫做 “应用专用密码” 的东西。Google 账号的安全设置里有一个 “应用专用密码” 的选项，可以生成一个专门用于第三方应用（比如 Gmail SMTP，额，为什么这算第三方应用）的密码。生成后把这个密码填到上面的密码输入框里，就可以成功验证了。点击这个链接来生成应用专用密码。

验证地址

添加账号之后，Gmail 会向目标自定义邮箱地址（我这里就是 i@sisy.cc）发送一封验证邮件。因为之前已经设置了邮件转发，所以这封验证邮件会直接被转发到 Gmail 的收件箱里，这样就又回到了 Gmail。打开这封邮件，点击里面的验证链接，完成验证过程就行。这样一来，就成功把自定义域名添加为 Gmail 的一个发件地址了。之后通过 Gmail 发送邮件时，可以在发件人地址处选择 Gmail 地址或者自定义域名地址两种。