1840 字
9 分钟
不用 GitHub:用 PowerShell 和 SSH 一键更新 Astro 博客

个人博客部署到云服务器后,发布一篇文章需要完成两件事:把 Markdown 文件上传到服务器,再重新构建 Astro 静态站点。

手动执行时,完整流程大致如下:

选择文章 → SCP 上传 → SSH 登录 → pnpm build → 检查 Nginx → 打开网站验证

步骤并不复杂,但每次重复输入路径和命令很容易出错。更重要的是,Astro 构建会更新整个 dist 目录,如果构建中途失败,线上站点可能只剩下一份不完整的产物。

为了解决这些问题,我给博客增加了两个脚本:

  • Windows PowerShell 上传脚本:选择 Markdown、判断目标目录、执行 SCP,并远程触发构建;
  • Linux 服务器更新脚本:加锁、备份旧版本、执行构建、失败回滚、检查 Nginx 和线上地址。

现在,发布一篇博客只需要一条本地命令。

当前目录结构#

我把正在编辑的 Markdown 集中保存在:

X:\path\to\blog-content

其中包含普通文章和 About 页面:

X:\path\to\blog-content\
├─ about.md
├─ first-post.md
└─ deployment-notes.md

服务器上的 Astro 项目位于:

/var/www/example-blog

两个内容目录分别是:

/var/www/example-blog/src/content/posts # 普通文章
/var/www/example-blog/src/content/spec # About 等特殊页面

脚本会根据文件内容和文件名自动选择目录。about.md 会进入 spec,带有 Astro Frontmatter 的其他 Markdown 会进入 posts。

准备 SSH 别名#

本地 SSH 配置文件位于:

C:\Users\<USERNAME>\.ssh\config

对应配置如下:

Host blog-server
HostName 203.0.113.10
User deploy
IdentityFile C:\Users\<USERNAME>\.ssh\id_ed25519
IdentitiesOnly yes

配置后,不再需要每次输入 IP、用户名和密钥路径:

Terminal window
ssh blog-server

测试成功后,SCP 也可以使用相同别名:

Terminal window
scp .\example.md blog-server:/tmp/

私钥只保存在本机,不能上传到博客目录或 GitHub。服务器的 authorized_keys 中只需要保存公钥。

安装服务器更新脚本#

服务器脚本的本地位置是:

X:\path\to\blog-project\scripts\update-blog.sh

先在 Windows PowerShell 中上传:

Terminal window
scp -F "$env:USERPROFILE\.ssh\config" `
"X:\path\to\blog-project\scripts\update-blog.sh" `
blog-server:/tmp/update-blog.sh

然后登录服务器:

Terminal window
ssh -F "$env:USERPROFILE\.ssh\config" blog-server

将脚本安装为系统命令:

Terminal window
install -o root -g root -m 755 \
/tmp/update-blog.sh \
/usr/local/bin/update-blog

检查是否安装成功:

Terminal window
update-blog --help

以后即使使用 MobaXterm 手动上传文件,也只需要在服务器执行:

Terminal window
update-blog

服务器脚本做了什么#

服务器脚本首先固定项目地址和正式域名:

Terminal window
BLOG_DIR="${BLOG_DIR:-/var/www/example-blog}"
SITE_URL="${SITE_URL:-https://blog.example.com/}"
BACKUP_DIR="${BLOG_BACKUP_DIR:-/var/backups/example-blog}"
KEEP_BACKUPS="${KEEP_BACKUPS:-5}"

这些值都可以通过环境变量覆盖,但平时不需要修改。

防止重复构建#

如果不小心连续运行两次更新,两个 pnpm 进程可能同时修改 dist。脚本使用 flock 创建部署锁:

Terminal window
exec 9>"/var/lock/example-blog-update.lock"
flock -n 9 || {
echo "已有更新任务正在运行"
exit 1
}

只要已有任务没有退出,第二个任务就不会继续执行。

构建前备份#

如果当前站点已经存在,脚本会把 dist 打包:

Terminal window
timestamp="$(date '+%Y%m%d-%H%M%S')"
backup_file="/var/backups/example-blog/dist-$timestamp.tar.gz"
tar -czf "$backup_file" \
-C /var/www/example-blog/dist .

默认只保留最近五份备份,防止长期更新占满磁盘。

使用正式域名构建#

博客通过 SITE_URL 生成规范链接、RSS 和 Sitemap,因此每次构建都显式传入正式域名:

Terminal window
cd /var/www/example-blog
SITE_URL="https://blog.example.com/" pnpm run build

随后检查首页构建产物:

Terminal window
test -f /var/www/example-blog/dist/index.html

只有 dist/index.html 存在,构建才会被视为成功。

失败自动回滚#

脚本通过 trap 捕获构建错误和中断信号。如果 Astro 构建失败,会删除残缺的 dist,再从刚才的备份恢复:

Terminal window
rm -rf /var/www/example-blog/dist
mkdir -p /var/www/example-blog/dist
tar -xzf "$backup_file" \
-C /var/www/example-blog/dist

这样,即使新文章的 Frontmatter 写错,线上站点仍然保持为上一次成功构建的版本。

检查服务状态#

构建成功后,脚本检查并重新加载 Nginx:

Terminal window
nginx -t
systemctl reload nginx

最后访问正式地址进行健康检查:

Terminal window
curl --fail --location --head \
--max-time 20 \
https://blog.example.com/

如果网站暂时无法访问,脚本会打印警告,但不会把一次成功构建误判成构建失败。

使用本地上传脚本#

本地 PowerShell 脚本位于:

X:\path\to\blog-project\scripts\upload-blog.ps1

它默认从下面的目录寻找 Markdown:

X:\path\to\blog-content

因此发布文章时只需要提供文件名。

上传单篇文章#

Terminal window
powershell -ExecutionPolicy Bypass -File `
"X:\path\to\blog-project\scripts\upload-blog.ps1" `
"new-article.md"

上传这篇教程本身则执行:

Terminal window
powershell -ExecutionPolicy Bypass -File `
"X:\path\to\blog-project\scripts\upload-blog.ps1" `
"upload-astro-blog-with-ssh-script.md"

脚本会依次显示上传、服务器构建和网站检查结果。

批量同步全部文章#

Terminal window
powershell -ExecutionPolicy Bypass -File `
"X:\path\to\blog-project\scripts\upload-blog.ps1" `
-All

批量模式会扫描 X:\path\to\blog-content 下的所有 .md 文件,并进行分类:

  • about.md 自动上传到 src/content/spec;
  • 包含 title、published 和完整 Frontmatter 的文件上传到 src/content/posts;
  • 普通命令备忘录或缺少 Frontmatter 的 Markdown 会被跳过。

这项检查可以避免把一个普通笔记误当成 Astro 文章,导致服务器构建失败。

依赖发生变化时#

平时上传 Markdown 不需要重新安装依赖。如果同时修改了 package.json 或 pnpm-lock.yaml,可以增加参数:

Terminal window
powershell -ExecutionPolicy Bypass -File `
"X:\path\to\blog-project\scripts\upload-blog.ps1" `
"example.md" `
-InstallDeps

服务器会在构建前执行:

Terminal window
pnpm install --frozen-lockfile

新文章的最小格式#

上传脚本会检查普通文章是否包含 Astro Frontmatter。一个最小的博客文件如下:

---
title: "文章标题"
published: 2026-09-20
description: "文章简介"
tags: [Astro, 教程]
category: 开发记录
draft: false
lang: zh_CN
---
这里开始写正文。

将文件保存到:

X:\path\to\blog-content\example.md

随后运行:

Terminal window
powershell -ExecutionPolicy Bypass -File `
"X:\path\to\blog-project\scripts\upload-blog.ps1" `
"example.md"

常见问题#

PowerShell 禁止运行脚本#

如果出现“系统上禁止运行脚本”,使用本文命令中的:

Terminal window
-ExecutionPolicy Bypass

它只对本次 PowerShell 进程生效,不会永久修改系统执行策略。

提示找不到文件#

脚本默认只在 X:\path\to\blog-content 中寻找相对文件名。先确认文件确实存在:

Terminal window
Get-ChildItem "X:\path\to\blog-content\*.md"

也可以直接传入完整路径。

文件被跳过#

普通文章必须:

  • 以 --- 开始;
  • 包含 title:;
  • 包含 published:;
  • 使用第二个 --- 结束 Frontmatter。

about.md 是特殊页面,不需要这些字段。

服务器提示 pnpm 不存在#

在服务器执行:

Terminal window
corepack enable
corepack prepare pnpm@9.14.4 --activate
pnpm --version

版本应与项目 package.json 中声明的版本一致。

构建失败#

服务器脚本会显示 Astro 或 Pagefind 的原始错误,并自动恢复上一个 dist。修正文档后重新上传即可。

可以查看最近的备份:

Terminal window
ls -lht /var/backups/example-blog

上传成功但看不到新文章#

依次检查:

Terminal window
ls -l /var/www/example-blog/src/content/posts
ls -l /var/www/example-blog/dist/index.html
curl -I https://blog.example.com/

浏览器仍显示旧内容时,可以尝试强制刷新页面,或者清除浏览器缓存。

这套流程带来的变化#

最初更新博客需要记住服务器目录、构建命令和正式域名。现在,本地脚本负责“把内容送到哪里”,服务器脚本负责“怎样安全地发布”。两边的职责很清楚:

本地 Markdown
↓ SCP
服务器源码目录
↓ 自动备份与构建
Astro dist
↓ Nginx
https://blog.example.com/

自动化的价值不只是少输入几条命令。部署锁避免重复构建,Frontmatter 检查减少无效上传,备份和回滚保护线上版本,健康检查则让每次发布都有明确结果。

对于个人博客,这套方案已经足够轻量:不依赖额外的持续集成平台,也不要求每篇文章先提交到 GitHub。写完 Markdown,运行一条命令,剩下的工作交给脚本完成。