主题
静态站发布:为什么不用 git pull,而是 tar + rsync
发布静态站有很多种做法:
- 服务器上
git pull && npm run build; - 本地构建,
scp -r dist/*传上去; - 本地构建,打包,上传,远端
rsync镜像; - 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 = """..."""发布时:
- 读取现有配置,如果已经包含需要的规则就跳过;
- 需要改写时先备份成
emphant.conf.bak-<时间>; - 上传新配置;
nginx -t,失败就cp回备份并退出;- 通过才
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 脚本就可以退休了。以现在的规模,它够用、够简单、也够可靠。
发布的具体命令和环境变量见项目文档。