From ea999680358ece9b1761eaf8a916d80fcfbdcc49 Mon Sep 17 00:00:00 2001
From: laoyang <i@yangyq.net>
Date: Tue, 6 Oct 2026 03:51:47 +0800
Subject: [PATCH] =?UTF-8?q?FamilyBook=20=E9=83=A8=E7=BD=B2=E9=93=BE?=
 =?UTF-8?q?=E8=B7=AF=EF=BC=9A=E8=A1=A5=20upload=5Fstage.php=20=E7=99=BD?=
 =?UTF-8?q?=E5=90=8D=E5=8D=95=20+=20=E6=9A=82=E5=AD=98=E7=9B=AE=E5=BD=95?=
 =?UTF-8?q?=E6=9D=83=E9=99=90=E5=87=86=E5=A4=87=EF=BC=88=E7=AC=AC=2020=20?=
 =?UTF-8?q?=E6=89=B9=E6=94=B6=E5=B0=BE=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

第 20 批（c3d00ad）的功能代码已在仓库里；这次是把**部署链路**补齐 ——
本轮部署实测连续踩到两个「代码没错、环境/流程没跟上」的坑：

① **打包白名单漏了 upload_stage.php**
   它是站点根下的独立入口（与 media.php 同类，不在 app/ 也不在 templates/），
   打包白名单是手写的，漏了它 → 部署脚本静态断言直接红「缺 upload_stage.php」，
   线上表现为"拖文件没反应"（比整页坏更难查）。
   → `familybook_push.sh` 的 tar 列表与"必需文件"清单都加上它。

② **`uploads/` 的 ACL mask 把 www 的写权限压掉了**
   · 站点根 `uploads/` 属主是 **family**，而 **PHP-FPM 跑在 www** 下（`ps` 实测）；
   · `getfacl` 显示 `user:www:rwx  #effective:r-x`，`mask::r-x` ——
     www **建不了新子目录**；
   · 而 `StagedUpload::stage()` 第一步就是 `mkdir uploads/_staging/<token>`
     → 建不出来 = 拖动上传**静默失败**（前端只看到"上传失败"）。
   → 部署脚本「6. 权限整理」段新增：放开 uploads 的 mask + 预建 `_staging/`
      + 给它 u:www:rwx 与默认 ACL。
   ⚠️ 同一处还踩了个"改了等于没改"的细节：**加完 setfacl 又 chmod 755** ——
      `chmod` 会重算 ACL 的 mask（755 → r-x），刚放开的 www 写权限立刻被压回去。
      已去掉 chmod，权限点全交给 setfacl。

验证：线上以 **www 身份**（临时探针页，用完即删并复验 404）实测
`uploads/_staging` 可 mkdir + 可写；部署脚本静态断言段本地空跑 305 条全过；
线上部署 19/19 自检全过。