文章

本站架构、维护与使用说明

2026/6/18

#astro#nginx#git#backup#uptime-kuma

1. 架构目标

本站的目标很简单：稳定发布内容，并且在出问题时可以快速恢复。

当前方案采用 Astro + Nginx + Git + 自动备份 + Uptime Kuma。Astro 负责生成静态页面，Nginx 负责对外服务，Git 负责源码历史，备份脚本负责快照，Uptime Kuma 负责可用性和任务心跳监控。

这套架构不依赖数据库，也不需要 Node.js 常驻进程服务页面。构建完成后，线上只需要 Nginx 分发静态文件，运行面更小，故障点更少。

2. 技术分层

Astro

Astro 是内容层。文章放在 src/content/posts，页面模板放在 src/pages 和 src/layouts，全局样式放在 src/styles。

执行 npm run build 后，Astro 会把源码编译成 dist 目录。这个目录就是 Nginx 最终发布的静态站点。

Nginx

Nginx 是服务层。当前服务器已有站点配置，线上目录是 /var/www/html，域名配置指向 nununununu.top，HTTPS 入口当前监听 8443。

Nginx 不保存源码，只保存构建产物。这样可以避免生产目录里混入开发依赖、脚本和 Git 元数据。

Git

Git 是变更历史层。源码目录是 /home/ubuntu/blog，后续所有文章、模板和脚本调整都应该先改这里，再构建发布。

建议把仓库推送到远程 Git 服务。服务器本地 Git 负责现场回滚，远程仓库负责异地保管。

自动备份

备份脚本是恢复层，位置是 scripts/backup.sh。

脚本会优先生成 Git bundle。如果仓库还没有提交，脚本会自动回退为源码 tar.gz。如果已经存在 dist，脚本还会备份一份构建产物快照。

Uptime Kuma

Uptime Kuma 是监控层。建议监控三个对象：

首页 /，确认站点可以正常访问。
健康检查 /health.txt，确认发布产物可用。
备份 Push monitor，确认定时备份任务按时成功。

3. 目录说明

/home/ubuntu/blog
├── src/                       # Astro 源码
│   ├── content/posts/          # Markdown 文章
│   ├── layouts/                # 页面布局
│   ├── pages/                  # 路由页面
│   └── styles/                 # 全局样式
├── public/                     # 原样复制到站点根目录的静态资源
├── scripts/                    # 发布和备份脚本
├── docs/                       # Nginx 与运维说明
├── monitoring/uptime-kuma/     # Uptime Kuma Docker Compose 配置
├── dist/                       # 构建产物，不手工编辑
├── package.json                # npm 脚本和依赖
└── astro.config.mjs            # Astro 配置

4. 日常写作流程

新增文章时，在 src/content/posts 下创建 Markdown 文件。

文章头部需要包含标题、描述、发布时间和标签：

---
title: 新文章标题
description: 一句话描述文章内容
pubDate: 2026-06-18
tags:
  - note
---

如果文章暂时不想发布，加上：

draft: true

本地预览命令：

cd /home/ubuntu/blog
npm run dev

构建命令：

cd /home/ubuntu/blog
npm run build

5. 发布流程

推荐发布顺序如下：

修改 /home/ubuntu/blog 中的源码或文章。
执行 npm run build，确认 Astro 能成功生成 dist。
执行发布脚本或手工同步 dist 到 /var/www/html。
检查首页和 /health.txt。
执行一次备份脚本，确认新版本可恢复。

手工发布命令：

cd /home/ubuntu/blog
npm run build
sudo rsync -a --delete dist/ /var/www/html/

项目也提供了脚本：

WEB_ROOT=/var/www/html /home/ubuntu/blog/scripts/deploy.sh

发布会覆盖 /var/www/html 里的旧静态文件，因此发布前要确认当前线上页面可以被替换。

6. 备份策略

备份脚本默认使用这些变量：

BACKUP_DIR：备份目录，建议使用 /home/ubuntu/blog-backups。
RETENTION_DAYS：保留天数，默认 14 天。
UPTIME_KUMA_PUSH_URL：Uptime Kuma Push monitor 地址，可为空。

手工执行：

BACKUP_DIR=/home/ubuntu/blog-backups RETENTION_DAYS=14 /home/ubuntu/blog/scripts/backup.sh

建议每天凌晨执行一次 cron：

0 3 * * * BACKUP_DIR=/home/ubuntu/blog-backups RETENTION_DAYS=14 /home/ubuntu/blog/scripts/backup.sh

如果已经在 Uptime Kuma 创建 Push monitor，把 Push URL 加进去：

0 3 * * * BACKUP_DIR=/home/ubuntu/blog-backups RETENTION_DAYS=14 UPTIME_KUMA_PUSH_URL="https://monitor.example.com/api/push/xxx" /home/ubuntu/blog/scripts/backup.sh

7. 恢复方式

如果有 Git bundle，可恢复成一个新仓库：

git clone /home/ubuntu/blog-backups/blog-YYYYMMDDTHHMMSSZ.bundle restored-blog

如果是源码 tar.gz，解压后重新安装依赖并构建：

mkdir restored-blog
tar -xzf /home/ubuntu/blog-backups/blog-src-YYYYMMDDTHHMMSSZ.tar.gz -C restored-blog
cd restored-blog
npm install
npm run build

如果只是恢复线上静态文件，可以解压 blog-dist-*.tar.gz，再同步到 /var/www/html。

8. 监控建议

Uptime Kuma 可以用 Docker Compose 启动，配置在 monitoring/uptime-kuma/docker-compose.yml。

当前 Compose 文件使用 3001:3001。服务器上 3000 已被其他服务占用，所以这里避开 3000。

启动命令：

cd /home/ubuntu/blog/monitoring/uptime-kuma
docker compose up -d

建议创建这些监控项：

HTTP(s)：https://nununununu.top:8443/
HTTP(s)：https://nununununu.top:8443/health.txt
Push：备份脚本心跳

9. 常见维护命令

查看 Nginx 配置：

sudo nginx -t

重载 Nginx：

sudo systemctl reload nginx

查看 Nginx 状态：

systemctl status nginx --no-pager

查看 Docker 容器：

sudo docker ps

查看源码变更：

cd /home/ubuntu/blog
git status

10. 故障排查顺序

如果网站打不开，先按这个顺序查：

检查 Nginx 是否运行。
检查域名和端口是否正确。
检查 /var/www/html/index.html 是否存在。
在 /home/ubuntu/blog 重新执行 npm run build。
检查 dist/health.txt 是否存在。
重新同步 dist 到 /var/www/html。
如果发布产物损坏，从最近一次 blog-dist-*.tar.gz 恢复。