稳定增量镜像层摘要

.dockerignore

@@ -8,6 +8,7 @@ runtime
 .idea
 .vscode
 node_modules
+vendor
 .caiwu-build
 public/js
 public/css/app.css

AGENTS.md

@@ -87,6 +87,7 @@
 - 生产应用固定使用主机端口 `18088`，访问地址为 `http://118.196.84.79:18088`；端口、健康检查和 `APP_URL` 必须保持一致。
 - `mariadb:11.4` 运行镜像由开发机缓存并仅随首次初始化全量包上传，服务器不得在发布时临时访问 Docker Hub。
 - 日常发布必须通过只监听 `127.0.0.1` 的服务器本机 Registry 和 SSH 隧道传输，仅上传 Registry 中不存在的镜像层；禁止每次上传完整 `docker save` 压缩包。
+- 日常增量包必须由 BuildKit 直接导出 OCI 分层格式；禁止用 `docker save` 作为日常增量源，因为其未压缩层在重复导入时会产生不同压缩摘要、破坏跨版本层复用。
 - 服务器保留当前镜像和上一个可回滚镜像，其他本项目旧镜像在发布成功后清理。
 - 服务器发布必须使用互斥锁；同一时间只允许一个人切换版本，禁止并发覆盖。
 

deploy/Dockerfile

@@ -58,7 +58,6 @@ LABEL com.caiwu.project="CaiWuXiTong" \
 
 WORKDIR /var/www/html
 
-COPY . /var/www/html
 COPY --from=vendor /build/vendor /var/www/html/vendor
 COPY --from=frontend /js /var/www/html/public/js
 COPY --from=frontend /css/app.css /var/www/html/public/css/app.css
@@ -66,6 +65,7 @@ COPY --from=frontend /mix-manifest.json /var/www/html/public/mix-manifest.json
 COPY deploy/apache-vhost.conf /etc/apache2/sites-available/000-default.conf
 COPY deploy/php.ini /usr/local/etc/php/conf.d/caiwu.ini
 COPY deploy/entrypoint.sh /usr/local/bin/caiwu-entrypoint
+COPY . /var/www/html
 
 RUN test -f public/js/auth/common.min.js \
     && test -f public/css/app.css \

docs/开发与部署SOP.md

@@ -41,6 +41,7 @@
 - 日常命令不带 `--pull` 和 `--no-cache`。
 - 首次初始化才上传应用和 MariaDB 的全量包；日常发布通过 SSH 隧道连接服务器本机 Registry。
 - Registry 按内容哈希判断镜像层是否已经存在，基础环境、PHP 依赖和未变化的前端层不会重复上传。
+- 日常传输使用 BuildKit 原生 OCI 分层包，保持未变化层的压缩摘要稳定；`docker save` 全量包只用于首次初始化。
 - Registry 只监听服务器 `127.0.0.1:5000`，公网无法直接访问；发布脚本退出时会关闭 SSH 隧道。
 - 每次发布后只保留当前和上一个 Registry 版本，并回收旧版本不再引用的镜像层。
 

scripts/deploy-from-workstation.ps1

@@ -317,7 +317,20 @@ try {
             ssh -i $keyFullPath -o BatchMode=yes $sshTarget "chmod 700 '$RemotePath/'*.sh && (curl -fsS -o /dev/null http://127.0.0.1:5000/v2/ || '$RemotePath/setup-incremental-registry.sh' '$RemotePath' '$RemotePath/registry-config.yml')"
         } '服务器增量镜像仓库初始化失败。'
 
-        Invoke-Native { docker save --output $localTar $fullImage } '导出本次应用镜像失败。'
+        # docker save 导出未压缩层，每次导入重新压缩会改变摘要，导致 Registry 无法复用。
+        # 直接导出 BuildKit 原生 OCI 层，让未变化层的压缩摘要跨版本保持稳定。
+        Invoke-Native {
+            docker buildx build `
+                --builder $BuilderName `
+                --output "type=oci,dest=$localTar" `
+                --tag $fullImage `
+                --build-context 'frontend=.caiwu-build/public' `
+                --build-arg "VCS_REF=$deploySha" `
+                --build-arg "BUILD_DATE=$buildDate" `
+                --label 'com.caiwu.project=CaiWuXiTong' `
+                --file deploy/Dockerfile `
+                .
+        } '导出稳定分层的 OCI 应用镜像失败。'
         $regctlPath = Get-RegctlPath
         $localRegistryPort = Get-AvailableLocalPort
         $sshTunnel = Start-RegistryTunnel -LocalPort $localRegistryPort