Skip to content

静态站发布:为什么不用 git pull,而是 tar + rsync ​

发布静态站有很多种做法:

  1. 服务器上 git pull && npm run build;
  2. 本地构建,scp -r dist/* 传上去;
  3. 本地构建,打包,上传,远端 rsync 镜像;
  4. CI 构建,推对象存储,CDN 回源。

这个项目选的是第 3 种。下面说清楚为什么,以及这套脚本具体做了什么。

为什么不在服务器上构建 ​

服务器是 2C4G,跑 nginx 很轻松,但跑 vite build 很痛苦:

  • 构建 100+ 个 HTML 页面需要 1~2 分钟,期间 CPU 打满,nginx 响应变慢;
  • 需要装 Node、npm 依赖,服务器上多一套运行时;
  • 构建失败时线上是半成品状态;
  • 每次构建都在服务器上产生 node_modules、缓存,磁盘越用越紧。

本地构建、只上传产物的好处是:服务器只负责发文件,不参与任何计算。它也不需要 Node。

为什么不用 scp -r ​

scp -r dist/* /var/www/emphant/ 有三个问题:

  • 不会删除旧文件。上一版有、这一版没有的页面会一直留着,用户可能访问到过期内容;
  • 不是原子操作。传到一半失败,线上就是新旧混合;
  • 慢。每次都全量传,几十 MB 的 assets 重复上传。

rsync -a --delete 解决这三个问题:增量同步、删除多余文件、一次镜像。

完整流程 ​

bash
./deploy.sh            # 构建 + 发布
./deploy.sh docs       # 只发文档站
./deploy.sh --dry-run  # 只看计划

脚本内部:

1. 构建          npm run build(在对应目录)
2. 打包          tar czf deploy-<app>-<时间>.tar.gz dist/
3. 上传          SFTP → /tmp/deploy-<app>-<时间>.tar.gz
4. 解包          /tmp/deploy-<app>-<时间>/
5. 备份          当前 /var/www/emphant-* → /var/www/.releases/<app>-<时间>.tar.gz
6. 镜像          rsync -a --delete <解包目录>/ <目标目录>/
7. 修权限        目录 755、文件 644
8. 校验          index.html、assets、关键页面是否存在
9. reload        nginx -t && systemctl reload nginx

第 5 步在镜像之前,第 8 步在镜像之后。顺序不能错:备份必须在覆盖前完成。

主站的特殊处理 ​

电脑版和手机版在同一台服务器、两个目录:

/var/www/emphant      ← 电脑版
/var/www/emphant/m    ← 手机版

发布电脑版时,rsync --delete 会把 /m/ 当成「目标目录里多余的文件」删掉。所以:

python
'rsync_exclude': '--exclude=/m/',

同理,备份时也要排除:

python
'backup_exclude': './m'
bash
tar czf backup.tar.gz -C /var/www/emphant --exclude=./m --exclude=./m/* .

tar 的 --exclude 必须写在成员参数(.)之前,否则 GNU tar 只对它后面的成员生效。这个坑踩过一次:备份里混进了手机版,解包回滚时把手机版覆盖成了旧版本。

权限 ​

rsync 默认保留源文件权限。本地 macOS 上文件是 644、目录是 755,一般没问题,但 npm 有时会产出 600 的文件(尤其是临时文件重命名后)。服务器上的 nginx 以 www-data 运行,读不了 600。

所以发布后统一修一遍:

bash
chown -R root:root /var/www/emphant
find /var/www/emphant -type d -exec chmod 755 {} +
find /var/www/emphant -type f -exec chmod 644 {} +

nginx 配置也进流水线 ​

配置文件不在服务器上手改,而是由 deploy.py 里的模板生成:

python
NGINX_CONF = """..."""

发布时:

  1. 读取现有配置,如果已经包含需要的规则就跳过;
  2. 需要改写时先备份成 emphant.conf.bak-<时间>;
  3. 上传新配置;
  4. nginx -t,失败就 cp 回备份并退出;
  5. 通过才 systemctl reload nginx。

这样「配置改坏了导致全站 502」的概率降到很低——最坏情况是发布失败,线上仍是旧配置。

回滚 ​

每次发布都会留一份 tar.gz:

/var/www/.releases/docs-20261120-103000.tar.gz

回滚就是解包回去:

bash
tar xzf /var/www/.releases/docs-20261120-103000.tar.gz -C /var/www/emphant-docs

静态站回滚不需要 reload nginx,文件换掉立即生效。备份保留最近 5 份,由 KEEP_BACKUPS 控制。

这套方案的代价 ​

  • 依赖本地环境。必须在有 Node 和源码的机器上发布,不能「在任何地方改一行就上线」;
  • 上传耗时。全量 tar 包几十 MB,家宽上传需要几十秒到几分钟;
  • 没有审计。谁在什么时候发了什么版本,只能靠备份文件名和文档里的更新日志。

如果将来要多人协作或更高频发布,会换成「CI 构建 + 对象存储 + CDN」,那时这套 tar + rsync 脚本就可以退休了。以现在的规模,它够用、够简单、也够可靠。

发布的具体命令和环境变量见项目文档。

记录方案,而不是记录结论。