gongxiangp2/docs/部署脚本安全说明.md

部署脚本安全说明

更新时间：2026-05-07 当前默认部署脚本：scripts/git-incremental-deploy.ps1

1. 当前结论

当前 Git 增量部署脚本只负责同步源码、构建镜像、推送镜像、替换应用容器和清理 Docker 无用资源。它不直接改业务数据，不直接操作数据库，不直接操作 MinIO 桶，也不清理生产 uploads 目录。

普通上传、下载、转码等业务写入仍由应用运行时完成，不属于部署脚本的文件操作。

2. uploads 目录边界

生产 uploads 目录：

/mnt/PoolOne/youyidian-uploads

容器挂载：

-v /mnt/PoolOne/youyidian-uploads:/app/uploads

部署脚本的边界：

• 在创建候选容器前验证该路径确实是预期 ZFS 数据集，不是系统盘上的同名目录壳。
• 验证容器内 /app/uploads 与宿主机数据集的文件系统标识一致，再允许切流。
• 不对该目录执行 rm、mv、cp、find -delete 或清空操作。
• 不改变该目录内已有源文件、视频文件、压缩包和上传临时数据。

需要注意：容器内应用对 /app/uploads 不是只读挂载。上传、下载、转码和清理临时上传会按业务逻辑读写这个目录，这和部署脚本本身的操作边界是两件事。

3. 数据库边界

部署脚本不会执行下面操作：

• 不执行 SQL。
• 不运行 Prisma migrate / db push。
• 不停止、不删除 PostgreSQL 容器。
• 不进入数据库容器执行命令。

部署后应用容器会通过生产 .env 中的 DATABASE_URL 正常连接数据库，这是业务运行必需行为。

4. MinIO / S3 边界

部署脚本不会执行下面操作：

• 不执行 aws s3 或 mc 命令。
• 不停止、不删除 MinIO 容器。
• 不删除桶对象。
• 不迁移桶数据。

部署后应用容器会通过 S3_ENDPOINT、S3_BUCKET、S3_PUBLIC_DOMAIN 等环境变量正常访问对象存储，这是业务运行必需行为。

当前素材存储口径：

• 新素材预览 / 展示文件：写入新 MinIO 桶，公开 URL 统一为 https://s3.jiansun.vip/gongxiangpan/public-display/...。
• 旧 1080p.hk 桶：只用于极少数老素材兼容，不作为新素材写入目标。
• 源文件 / 下载型文件：落在生产机独立 ZFS uploads 数据集，即 /mnt/PoolOne/youyidian-uploads。

5. 构建机操作范围

构建机：192.168.40.206

Git 增量部署脚本会在构建机上使用下面目录作为 Git 工作区：

/root/youyidian-3d-git-build

脚本会在这个 Git 工作区内执行：

• git fetch --prune
• git reset --hard
• git clean -fdx
• docker build
• docker push

这些清理只针对构建机上的 Git 工作区和 Docker 虚拟资源，不涉及生产机 uploads、数据库或 MinIO 数据目录。

6. 生产机操作范围

生产机：192.168.58.20

脚本会在生产机上执行：

• 拉取构建机 Registry 中的应用镜像。
• 停止并删除旧应用容器。
• 用新镜像启动新应用容器。
• 调用 http://127.0.0.1:4320/api/health 或影子环境健康检查。
• 健康检查失败时，默认尝试用旧镜像回滚应用容器。

脚本只操作应用容器：

• 正式：youyidian-3d-material
• 影子：youyidian-3d-shadow

不会操作：

• PostgreSQL 容器
• Redis 容器
• MinIO 容器
• FRP 容器或服务
• uploads 目录内容

7. 清理策略

默认清理内容：

• 构建机悬空镜像。
• 生产机 6 小时前的旧镜像。
• 生产机 6 小时前的未使用容器。

默认不会清理：

• uploads 目录。
• MinIO 数据目录。
• PostgreSQL 数据目录。
• Docker volume。
• 当前运行中的应用容器和镜像。
• Docker build cache。

只有显式传入 -AggressiveBuildCacheCleanup 时，脚本才会额外清理较旧构建缓存。这个选项仍然只作用于 Docker 构建缓存，不作用于业务文件。

8. DryRun 安全性

DryRun 命令：

.\scripts\git-incremental-deploy.ps1 -DryRun

DryRun 只验证：

• 构建机 SSH 可达。
• 构建机能读取 Git 仓库。
• 构建机能连接生产机。
• 构建机 Registry 可用。

DryRun 不会：

• 同步代码到构建目录。
• 构建镜像。
• 推送镜像。
• 停止或重启生产容器。
• 修改业务文件。

9. 旧脚本说明

旧版 deploy-remote-build.ps1、deploy-local-build.ps1、deploy-public-build.ps1 这类 deploy-*.ps1 属于本地历史脚本名，受 .gitignore 保护，不作为仓库交付入口。它们对应的“本机打包源码上传到构建机”、本地构建、公网穿透构建等链路，只作为识别历史资料使用。历史文档中提到的镜像 tar 临时文件、deploy-build-server.ps1、deploy-local-build.ps1 对比口径，不再代表当前默认部署链路。

当前默认链路不再把镜像 tar 文件复制到生产机，而是由生产机直接从构建机 Registry 拉取提交标签镜像。

10. 出问题时怎么查

查看应用日志：

ssh root@192.168.58.20 'docker logs --tail 120 youyidian-3d-material'

检查健康接口：

ssh root@192.168.58.20 'curl -fsS http://127.0.0.1:4320/api/health'

检查 uploads 目录是否还在：

ssh root@192.168.58.20 'ls -la /mnt/PoolOne/youyidian-uploads | head -20'

检查 Docker 镜像和容器：

ssh root@192.168.58.20 'docker ps --format "table {{.Names}}\t{{.Image}}\t{{.Status}}"'
ssh root@192.168.58.20 'docker images | grep youyidian-3d-material'