feat: 云端图片存储（OSS/COS/七牛）+ 服务端代理读取，并补全文档

新增存储抽象层：图片可存本地或云对象存储，切换存储方式不影响已有图片。存储层 - lib/storage.php 存储门面：本地优先读取、URL 生成、上传/删除、批量迁移、服务端读取（storageRead）与访问方式判定（storageAccessMode） - lib/storage/{local,oss,cos,qiniu}.php 四种后端驱动；http.php 共用 cURL 客户端； meta.php 实例元数据鉴权（ECS RAM 角色 / CVM CAM 角色，免密钥） - lib/settings.php 设置读写；云厂商密钥以 enc:v1:gcm 密文落库（db/.settings.key） - 文件名改为内容指纹（md5 前 12 位_6 位随机[_角色].ext），内容不变则名不变，因此可下发 immutable 长缓存两种图片访问方式 - 直连存储：storageUrl() 产出对象存储地址（桶需允许匿名读） - 服务端代理：media.php 鉴权后由服务器签名读取并同源回吐，桶可保持私有 · 未登录返回 403 纯文本（刻意不用 302，否则 <img> 会拿到一段 HTML） · 对象键白名单防目录穿越；Content-Type 按扩展名白名单决定 + nosniff（防同源 XSS） · 透传 If-None-Match / Range，上游 304 直接短路；private + immutable 长缓存 · 鉴权后立即 session_write_close()，避免排他会话锁把并行图片请求串行化内网 endpoint 判定（修「开了代理后慢到不可用」） - 内网地址只在与桶同地域的 ECS 上可路由；跨地域时 DNS 能解析但 TCP 连不通，无脑「内网优先」会让每次读取先白等满一次连接超时（默认 10 秒） - 改为先比本机 ECS 地域与桶地域（零成本、结论确定）→ 不同即跳过；结论落缓存；内网只给 2 秒连接超时，传输层失败立刻标记且短期内不再重试 - 「测试连通性」升级为 PUT → GET 回读 → DELETE，并显式报出内网判定结论界面与页面 - settings.php 系统设置页：驱动选择、各云配置、图片访问方式、连接测试、迁移进度 - storage_api.php 提供 stat / migrate / test 三个 JSON 接口 - detail / edit / annual_report / persons 原先直接拼本地路径（file_exists / '/'.$path），迁云后会整块不渲染或 404，统一改为走存储门面 - js/main.js 增加破图占位兜底；config.php 统一下发 Referrer-Policy: same-origin 文档 - README 新增《图片存储与对象存储》整章：设计约定、两种访问方式取舍表、直连存储逐项配置说明（桶 ACL / 防盗链白名单 / 跨域 CORS 与 crossorigin / 强制下载 / endpoint 地域 / 自定义域名）与上线检查清单、服务端代理实现要点、迁移步骤、12 条踩坑记录、可直接复制的排障命令手册
2026-09-21 22:06:02 +08:00
parent dd957d45bd
commit 673a8abf78
21 changed files with 3746 additions and 57 deletions
@@ -19,6 +19,15 @@
 - **多图上传**：观影照片支持一次选择多张。
 - **头像兜底**：未上传头像的观影人自动生成"首字母 + 配色"的 SVG 头像，配色由姓名哈希决定，同名同色。
 - 上传目录按类型分离：`uploads/posters/`、`uploads/tickets/`、`uploads/photos/`、`uploads/avatars/`。
+- **破图兜底**：图片加载失败时由前端脚本替换为内联占位图，避免会话过期或权限异常时满屏破图刷屏控制台。
+
+### 图片存储（本地 / 云对象存储）
+- **四种存储后端**：本地硬盘（默认）、阿里云 OSS、腾讯云 COS、七牛云 Kodo，在「系统设置」页切换，**无需改代码**。
+- **免密钥鉴权**：部署在阿里云 ECS / 腾讯云 CVM 上时，可直接绑定 RAM/CAM 角色读取实例元数据获取临时凭据，**不必在站内保存长期密钥**。
+- **本地优先读取**：数据库里只存相对对象键（如 `uploads/posters/xxx.webp`）；本地存在就本地读，否则读云端。**因此切换存储方式不会影响已有图片**，迁移可以慢慢来。
+- **内容指纹命名**：文件名为 `md5(内容)前 12 位_6 位随机[_角色].ext`，内容不变则名字不变，可以放心下长缓存。
+- **一键迁移**：把已有本地图片上传到云端并自动改写数据库引用（分批执行、带进度、幂等可重入）。
+- **两种图片访问方式**：**直连存储**（浏览器直接访问对象存储）与**服务端代理**（经本站 `media.php` 鉴权后由服务器读取回吐，**桶可保持私有**）。两者的取舍与配置见下文《图片存储与对象存储》。

 ### 信息辅助
 - **OMDb 自动获取**：在添加页输入片名后点击「📡 自动获取」，自动填充年份、类型、片长、导演、主演、IMDb 评分与剧情简介，并预览海报（海报仅供参考，仍需本地上传）。
@@ -72,6 +81,15 @@ MovieLog_Server/
 ├── lib/                    # 功能模块（被 config.php 统一引入，页面无需单独 require）
 │   ├── db.php              #   DB 连接、建表、字段与历史数据迁移、默认管理员
 │   ├── helpers.php         #   输出转义、文件名、颜色校验、上传/删除文件、图片 URL
+│   ├── settings.php        #   系统设置读写；云厂商密钥以 enc:v1:gcm 密文落库
+│   ├── storage.php         #   存储门面：本地优先读取、URL 生成、上传/删除、迁移、代理读取
+│   ├── storage/            #   各存储后端驱动
+│   │   ├── local.php       #     本地硬盘
+│   │   ├── oss.php         #     阿里云 OSS（签名 V1，支持 RAM 角色免密钥 / 内网 endpoint）
+│   │   ├── cos.php         #     腾讯云 COS
+│   │   ├── qiniu.php       #     七牛云 Kodo
+│   │   ├── http.php        #     共用 HTTP 客户端（cURL）与签名/编码工具
+│   │   └── meta.php        #     实例元数据鉴权（ECS RAM 角色 / CVM CAM 角色）与本机地域查询
 │   ├── auth.php            #   登录校验、管理员账号增删改
 │   ├── movies.php          #   电影/影院读取、搜索，以及表单关联数据的解析
 │   └── stats.php           #   统计仪表板与年度报告查询
@@ -91,10 +109,13 @@ MovieLog_Server/
 ├── login.php               # 登录
 ├── logout.php              # 退出
 ├── nav.php                 # 导航栏组件（被各页面 include）
+├── settings.php            # 系统设置页：存储后端选择、图片访问方式、连接测试、迁移
+├── storage_api.php         # 存储维护接口（stat / migrate / test），返回 JSON
+├── media.php               # 服务端图片代理：鉴权后由服务器读取对象并同源回吐
 ├── fetch_movie.php         # OMDb 代理接口，返回 JSON
 ├── test_crop.php           # 开发调试页：验证 Base64 图片落盘是否正常
 ├── css/style.css           # 全局样式
-├── js/main.js              # 公共脚本（含各页面共用的表单联动函数）
+├── js/main.js              # 公共脚本（含各页面共用的表单联动函数、破图兜底）
 ├── assets/.gitkeep         # 静态占位资源目录
 ├── db/movies.db            # SQLite 数据库（运行时自动生成，不纳入版本控制）
 └── uploads/                # 上传图片（运行时自动生成，不纳入版本控制）
@@ -110,7 +131,7 @@ MovieLog_Server/

 ## 数据库结构

-建表逻辑集中在 `config.php` 的 `initDB()`，每次请求都会执行 `CREATE TABLE IF NOT EXISTS` 与幂等的 `ALTER TABLE` 迁移，因此**升级代码无需手动改库**。
+建表逻辑集中在 `lib/db.php` 的 `initDB()`（由 `config.php` 在每次请求引导时调用），每次请求都会执行 `CREATE TABLE IF NOT EXISTS` 与幂等的 `ALTER TABLE` 迁移，因此**升级代码无需手动改库**。

 | 表 | 作用 | 关键字段 |
 | --- | --- | --- |
@@ -120,6 +141,15 @@ MovieLog_Server/
 | `persons` | 观影人 | `name`（唯一）、`color`、`avatar` |
 | `viewers` | 电影 ↔ 观影人关联 | `movie_id`、`person_id`、`name`（历史遗留字段） |
 | `movie_photos` | 电影多图 | `movie_id`、`photo_path`、`created_at` |
+| `settings` | 键值配置与缓存 | `name`（唯一）、`value`。存存储驱动选择、各云厂商配置、图片访问方式等；**云厂商密钥以 `enc:v1:gcm:` 前缀密文落库**（密钥文件 `db/.settings.key`，首次保存时自动生成，**丢失后密文不可恢复**） |
+
+`settings` 中除配置外的运行时缓存键（都可安全清空，程序会自动重建）：
+
+| 键 | 含义 | 有效期 |
+| --- | --- | --- |
+| `cache_meta_aliyun` / `cache_meta_tencent` | 实例角色换来的临时凭据 | 到期前 5 分钟失效 |
+| `cache_ecs_region` | 本机 ECS 所在地域（用于判断内网 endpoint 是否可用） | 1 小时 |
+| `cache_oss_internal` | 内网 endpoint 可用性判定结论 | 可用 1 小时 / 不可用 30 分钟 |

 外键约束：`movies.cinema_id → cinemas.id`（`ON DELETE SET NULL`）、`viewers.movie_id → movies.id`（`ON DELETE CASCADE`）、`movie_photos.movie_id → movies.id`（`ON DELETE CASCADE`）。

@@ -133,6 +163,10 @@ MovieLog_Server/

 - PHP 7.4+（推荐 8.x），需启用扩展：`pdo_sqlite`、`fileinfo`、`mbstring`、`curl`
 - Web 服务器：Apache / Nginx / PHP 内置服务器均可
+- **使用对象存储时额外需要**：
+  - `curl` 扩展可用，且系统存在可信 CA 证书（`/etc/ssl/certs/ca-certificates.crt`、`/etc/pki/tls/certs/ca-bundle.crt` 等常见路径之一）。找不到 CA 时程序会回退给 curl 自行处理，但部分精简系统需要手动安装 `ca-certificates`，否则 HTTPS 访问对象存储会失败。
+  - 若使用「实例角色（免密钥）」鉴权：服务器需运行在对应云上，且实例已绑定 RAM（阿里云）/ CAM（腾讯云）角色。
+- **`settings.php` 会写入 `db/`**：请确保 Web 用户对 `db/` 有写权限（密钥文件 `db/.settings.key` 首次保存时在此生成）。

 ### 步骤

@@ -160,7 +194,7 @@ php -S localhost:8000
 # 浏览器访问 http://localhost:8000/login.php
 ```

-> 用 PHP 内置服务器时，`config.php` 中 `posterUrl()` 等函数返回的是以 `/` 开头的根路径，建议直接从项目根目录启动，或通过站点根目录访问。
+> 用 PHP 内置服务器时，`posterUrl()`（`lib/helpers.php`）与 `storageUrl()`（`lib/storage.php`）返回的是以 `/` 开头的站点绝对路径（如 `/uploads/posters/xxx.webp`），建议从项目根目录启动，或通过站点根目录访问。

 ### Nginx 参考配置

@@ -227,6 +261,19 @@ CSV **共 9 列，顺序固定**：
 阿甘正传, , 万达影城, 2024-01-15, 张三 李四, (电影票/阿甘正传.jpg), (海报/阿甘正传.jpg), 经典励志片, (合影/阿甘正传.jpg)
 ```

+### 把图片放到对象存储（可选）
+
+不改也能用（默认本地硬盘）。想用云存储时：
+
+1. 进入**系统设置**，选择存储后端（阿里云 OSS / 腾讯云 COS / 七牛云 Kodo），填写 Bucket、Endpoint、对象前缀等。
+2. 选择鉴权方式：
+   - **实例角色（免密钥，推荐）**：服务器在对应云上并绑定了角色时选它，不用在站内保存任何长期密钥。
+   - **AccessKey**：手动填写密钥，入库即加密。
+3. 点**测试连通性**——它会执行「写入探针 → **读回校验** → 删除探针」，因此**同时验证了写和读两条链路**，并会明确报出内网 endpoint 的判定结论。
+4. 选择**图片访问方式**（直连存储 / 服务端代理），两个选项的取舍见《图片存储与对象存储》§2。
+5. 需要的话点**迁移**，把已有本地图片搬到云端（分批、可重入，建议先备份 `db/` 与 `uploads/`）。
+6. 迁移完成后**全站看图确认无误，再清理本地文件**——读取是本地优先的。
+
 ### 接口：`fetch_movie.php`

 供添加页前端调用，服务端代请求 OMDb 避免浏览器跨域。
@@ -253,6 +300,239 @@ CSV **共 9 列，顺序固定**：

 ---

+## 图片存储与对象存储（OSS / COS / 七牛）
+
+> **这一节回答两个问题**：① 想用「直连存储」，对象存储那边到底要怎么配？② 我们在这条路上踩过的坑分别长什么样、怎么排。
+
+### 1. 几个设计约定（先理解这个，后面的现象才好解释）
+
+| 约定 | 说明 |
+| --- | --- |
+| **库里只存相对对象键** | `movies.poster_path` 等字段保存的是 `uploads/posters/xxxx.webp` 这种**相对键**，不含域名、不含 bucket、不含前缀。所以改域名 / 换 bucket / 改前缀都不用动数据库 |
+| **本地优先读取** | `storageUrl()` / `storageExists()` 先看本地 `uploads/` 里有没有这个文件：有 → 走站内路径 `/uploads/...`；没有 → 交给当前存储驱动。**这是「切换存储方式不影响已有图片」和「可以慢慢迁移」的根本原因** |
+| **内容指纹命名** | 文件名为 `md5(内容)前 12 位_6 位随机[_角色].ext`。内容不变则名字不变 → 可以下发 `immutable` 长缓存 |
+| **门面 + 驱动** | 页面只调用 `lib/storage.php` 门面（`storageUrl` / `storageExists` / `storagePutFile` / `storageDelete` / `storageRead` / `storageAccessMode` …），不直接碰 SDK。加云厂商 = 加一个 `lib/storage/*.php` 驱动 |
+| **密钥加密落库** | 云厂商 AccessKey 以 `enc:v1:gcm:` 密文存进 `settings` 表，密钥文件 `db/.settings.key`。**该文件丢失后密文不可恢复**，只能重新填写密钥。用实例角色（免密钥）则不存在这个问题 |
+| **对象前缀** | 桶内可再套一层目录（如 `movielog/`）。前缀只在驱动层拼接，库中键始终干净。同一个桶给多个站点用时靠它隔离 |
+
+### 2. 两种图片访问方式：怎么选
+
+| | **直连存储**（direct） | **服务端代理**（proxy） |
+| --- | --- | --- |
+| 图片 URL | `https://<bucket>.oss-….aliyuncs.com/movielog/uploads/…` | `/media.php?k=uploads/…`（同源） |
+| 桶权限要求 | **必须公共读**（或对每个对象签名，但那样 URL 会过期） | **可以私有**，服务器用实例角色/AK 签名读取 |
+| 防盗链白名单 | 需要包含本站域名，或保持「允许空 Referer」（本项目统一下发 `Referrer-Policy: same-origin`，跨域请求不带 Referer） | 不需要（浏览器根本不访问对象存储） |
+| 跨域 CORS | 只有想在浏览器里**读像素**（裁剪）时才需要 | **完全不需要**（同源） |
+| 谁能看到图 | 任何拿到 URL 的人 | 必须登录本站 |
+| 流量路径 | 浏览器 ⇄ 对象存储（不走服务器带宽） | 浏览器 ⇄ 你的服务器 ⇄ 对象存储（**双倍流量、占服务器带宽**） |
+| 额外延迟 | 无 | 每张图多一次服务器到存储的往返（同地域约 10–30 ms；跨地域约 60–100 ms） |
+| 适用 | 对性能敏感、图片可公开、愿意维护桶策略 | **希望桶保持私有**、不想维护防盗链/CORS、图片需要登录才可见 |
+
+> **建议**：个人/家庭站点优先选**服务端代理**——桶私有、免防盗链、免 CORS、裁剪天然可用。只有当图片确实可以公开、且希望省下服务器中转带宽与流量时，才用直连。
+>
+> 选择位置：**系统设置 → 图片访问方式**。切换后无需重启，立即生效（回滚就是切回另一项）。
+
+### 3. 直连存储：对象存储必须怎么配（重点）
+
+直连模式下，图片是**浏览器直接去对象存储取**的。因此下面每一项都会直接影响「图片能不能显示」。逐项过一遍。
+
+#### ① 桶读写权限：必须允许匿名读取
+
+浏览器请求对象存储时**不带任何身份**，所以桶（或该目录下的对象）必须允许匿名 GET。
+
+| 云 | 控制台位置 | 要选的值 |
+| --- | --- | --- |
+| 阿里云 OSS | Bucket → **读写权限**（ACL） | **公共读** |
+| 腾讯云 COS | 存储桶 → **权限管理** → 访问权限 | **公有读私有写** |
+| 七牛 Kodo | 空间设置 → 访问控制 | **公开** |
+
+⚠️ 改成公共读意味着**任何人拿到 URL 就能看图**。如果存的是私人内容，请用服务端代理而不是直连。
+
+#### ② 防盗链（Referer 白名单）：开了就必须放行本站
+
+防盗链是对象存储的「只允许特定来源引用」策略。**开了但没把本站域名加进白名单，就会出现最迷惑的现象**：
+
+> 把图片 URL 直接粘到浏览器地址栏 → **能打开**；同一个 URL 放在页面 `<img>` 里 → **403**。
+
+原因是浏览器对子资源（`<img>`/`<script>`）会带上当前页面的 `Referer`，而地址栏直接访问不带。**这几乎总是防盗链造成的，不是图片坏了。**
+
+| 云 | 控制台位置 |
+| --- | --- |
+| 阿里云 OSS | Bucket → **数据安全** → 防盗链 |
+| 腾讯云 COS | 存储桶 → **安全管理** → 防盗链设置 |
+| 七牛 Kodo | 域名管理 → **防盗链** |
+
+配置要点：
+
+1. 把站点域名加进白名单，例如 `movie.example.com`，需要子域时写 `*.example.com`。
+2. **不要图省事直接关掉防盗链** —— 如果这个桶还给别的用途（比如当备份盘）用，加白名单是加法，更安全。
+3. 确认「**允许空 Referer**」是开着的（各家默认开启）。本项目 `config.php` 里统一下发了 `Referrer-Policy: same-origin`，即**跨域请求不带 Referer、同源请求照常带**，所以即使白名单里漏配了本站，页面里的图片也能正常显示。这算一层兜底，但**不要拿它替代白名单**。
+
+#### ③ 跨域 CORS：只有「裁剪 / 读像素」才需要
+
+这不是防盗链，是**另一个开关**，两者经常被混为一谈。
+
+浏览器里 `cropper.getCroppedCanvas()` + `canvas.toDataURL()` 需要**读取图片的像素**。如果图片来自别的域名且未获授权，Canvas 会被标记为「被污染」（tainted），读取时抛 `SecurityError`，表现就是「点了裁剪保存没反应 / 弹错误」。
+
+**要让直连模式下的裁剪可用，必须同时满足两件事**（缺一不可）：
+
+1. **桶上配置 CORS 规则**：来源 `https://你的域名`，方法 `GET`（`HEAD` 建议一起），允许的请求头建议 `*`，暴露的响应头至少 `ETag`、`Content-Length`，缓存时间 600 秒。
+2. **图片标签声明跨域模式**：`<img src="…" crossorigin="anonymous">`。**只配 CORS 而不加这个属性，Canvas 依然会被污染**；反之只加属性而不配 CORS，图片会**直接加载失败**（比不能裁剪更糟）。
+
+> ⚠️ **本仓库当前没有给图片加 `crossorigin="anonymous"`**，因此**直连存储模式下裁剪功能不可用**，只能上传原图、不能二次裁剪。
+> 如果你需要裁剪，最省事的做法是**改用服务端代理**（图片同源，两个条件全免）；坚持直连则要自行在 `add.php` / `edit.php` / `persons.php` 的裁剪预览 `<img>` 上加 `crossorigin="anonymous"`，并先在桶上把 CORS 配对。
+
+#### ④ 强制下载（`x-oss-force-download` / `Content-Disposition: attachment`）
+
+桶级「强制下载」**不影响 `<img>` 正常显示**（浏览器对子资源忽略该头），但会让「点击图片看原图」变成弹下载框。想恢复成预览就把桶的强制下载关掉。
+
+#### ⑤ Endpoint 必须与桶所在地域一致
+
+`oss-cn-beijing.aliyuncs.com` 这类 endpoint 里的地域**必须和桶实际所在地域对应**，否则报
+`The bucket you are attempting to access must be addressed using the specified endpoint`。
+Endpoint 在 OSS 控制台「概览」页可以看到，填写时**不要带 `https://`**。
+
+#### ⑥ 自定义域名 / CDN（可选）
+
+绑定了自定义域名或 CDN 才填；填了之后图片 URL 会使用该域名。**填一个没绑定的域名会直接报错**（`CnameDenied` / `SecondLevelDomainForbidden`）。七牛云**必须**绑定域名（它不提供默认外链域名）。
+
+#### ⑦ 直连模式检查清单
+
+- [ ] 桶 ACL = 公共读 / 公有读私有写 / 公开
+- [ ] 防盗链白名单包含本站域名，或该桶未开防盗链
+- [ ] 桶地域与填写的 endpoint 地域一致
+- [ ] 系统设置页点「测试连通性」→ 提示可读写
+- [ ] 首页 / 详情 / 编辑预览 / 统计 / 年度报告 / 头像 逐页看图
+- [ ] 需要裁剪的话：桶 CORS + `<img crossorigin="anonymous">` 两者都到位
+- [ ] 知道这个桶的图片对任何拿到 URL 的人可见
+
+### 4. 服务端代理是怎么回事
+
+图片 URL 变成 `/media.php?k=uploads/posters/xxx.webp`，请求打到本站，由服务器去对象存储取，再**同源**吐给浏览器。因此：桶可以私有、不需要防盗链、不需要 CORS。
+
+`media.php` 做对的几件事（都值得保留，改动时别退化）：
+
+- **未登录直接 403 纯文本**（刻意不用 302 跳登录页 —— 否则 `<img>` 会拿到一段 HTML，控制台刷满「HTML 当图片解析失败」的噪声，掩盖真正原因）。
+- **鉴权后立刻 `session_write_close()`**：PHP 的会话文件锁是**排他**的，如果一直持有到脚本结束，浏览器并行为一张张图片开的连接会全部串行等待，页面图片越多越慢（见下方坑 5）。
+- **对象键白名单**：只允许 `uploads/{posters,tickets,photos,avatars}/` 下的纯文件名，并显式拒绝 `..`。否则 `?k=../config.php` 就是任意文件读取。
+- **Content-Type 由本地扩展名白名单决定**，绝不采信上游返回的类型。否则桶里若被塞进 `.html` / `.svg`，就会以 `text/html` 在**本站域名下**执行（同源 XSS）。同时下发 `X-Content-Type-Options: nosniff`。
+- **条件请求透传**：`If-None-Match` / `If-Modified-Since` / `Range` 转给上游，上游回 304 就短路返回，省流量。
+- **长缓存**：对象名是内容指纹，永不原地变更，所以下发 `Cache-Control: private, max-age=31536000, immutable`（`private` 必须有，因为内容是按登录会话授权的）。
+
+#### 内网 endpoint 只在与桶同地域时可用
+
+服务器与桶**在同一地域**时，把请求地址换成 `oss-<地域>-internal.aliyuncs.com` 可以走内网：**流量免费、延迟更低**。设置页 OSS 面板有「服务端读取走内网 endpoint」开关。
+
+但注意：**内网 endpoint 只在与桶同地域的 ECS 上可路由**。跨地域时 DNS 会照常解析出一个地址（毫秒级，看起来毫无异常），TCP 却**永远连不上**。所以程序会：
+
+1. 先比**本机 ECS 地域**（实例元数据 `region-id`）与**桶地域**，不同就直接跳过内网（零成本、结论确定）；
+2. 地域相同或无法判定时，才真的发一个签名 `HEAD` 到桶根探测一次（连接超时 2 秒）；
+3. 结论缓存起来，并显示在**系统设置 → 当前状态 →「服务端读取通道」**；
+4. 万一判断失效，内网尝试只等 2 秒就回退公网（不是默认的 10 秒）。
+
+### 5. 迁移已有图片到云端
+
+**系统设置 → 图片存储 → 迁移**：
+
+1. 先把本地 `uploads/` 与 `db/` **备份一份**（迁移会改写数据库里的图片引用）。
+2. 迁移是**分批**执行的（前端循环调用 `storage_api.php?action=migrate` 并显示进度），中断了可以直接重跑——已迁移的记录会被跳过，不会重复计数。
+3. 迁移过程中会把文件重命名为内容指纹名，并**同步改写数据库引用**。
+4. 迁移完成后**本地文件不会自动删除**，因为读取是「本地优先」的：本地还在就继续走本地，删掉本地文件后才真正走云端。**删本地文件前先全站看图确认。**
+
+### 6. 踩坑记录（按现象索引）
+
+#### 坑 1 · 图片在页面上 403，URL 粘到地址栏却能打开
+**对象存储的防盗链（Referer 白名单）**。浏览器对 `<img>` 会带 `Referer`，地址栏直粘不带。
+→ 解法见 §3②（加白名单）；临时绕法是在统一引导文件下发 `Referrer-Policy: same-origin`（本项目已做）；根治是改用服务端代理。
+**诊断**：`curl` 分别带 / 不带 `Referer` 各打一次，对比状态码，并把 403 的响应体打出来 —— 里面会直接写 `You are denied by bucket referer policy.` 之类的原始判决。
+
+#### 坑 2 · 迁到云端之后，某些图「整块消失」或 404
+代码还在把数据库里的**对象键当本地路径**拼：`file_exists(__DIR__.'/'.$path)` 在迁云后必然为假 → **整个图库区块不渲染**（比 404 更隐蔽，因为页面上什么都没有）；`'/'.$path` 则会拼出一个不存在的站内路径 → 404。
+→ 解法：所有地方统一走门面 `storageExists()` / `storageUrl()`。**只要绕过门面直接拼路径，迁云后就一定会出问题**，改动时务必全局搜一遍。
+
+#### 坑 3 · 防盗链修好了，裁剪还是不能用
+**裁剪要的是 CORS，不是 Referer。** 两者是不同的开关。
+→ 见 §3③（桶 CORS + `<img crossorigin>`）；或者直接切服务端代理。
+
+#### 坑 4 · 开了服务端代理后「慢到无法接受」
+**内网 endpoint 跨地域**：服务器在 `cn-qingdao`、桶在 `cn-beijing`，程序却按桶的地域推导出 `oss-cn-beijing-internal.aliyuncs.com` 并「内网优先」，于是**每张图都先白等满一次连接超时（默认 10 秒）**才回退公网。
+**这个地址的 DNS 是能解析的**（0.001 秒返回 A 记录），所以从日志上看不出任何异常，只会看到「很慢」。
+→ 解法见 §4「内网 endpoint 只在与桶同地域时可用」。本仓库已改为「先比地域、结论缓存、内网只等 2 秒」。
+
+#### 坑 5 · 图片数量越多越慢，慢得不成比例
+**会话锁**。代理页都要登录，`session_start()` 在请求开头；PHP 的会话文件锁是**排他**的，若持有到脚本结束（而取存储的耗时操作就在锁内），浏览器为同源图片同时开的约 6 条连接会**全部卡在同一把锁上**——总耗时 ≈ 图片数 × 单张耗时。
+→ 解法：鉴权通过后立刻 `session_write_close()`。本仓库 `media.php` 已处理。
+
+#### 坑 6 · 控制台刷满「图片解析失败」，但服务端一切正常
+代理页未登录时返回了 **302 跳登录页**，`<img>` 拿到的是 HTML。
+→ 解法：图片接口未授权要返回 **403 纯文本**；前端再加一层坏图占位兜底。
+
+#### 坑 7 · 想当然地平铺上游的 `Content-Type`，等于开了同源 XSS
+桶里若被放进 `.html` / `.svg`，并且你把它返回的类型原样透传，浏览器会以 `text/html` 在**本站域名下**执行它。
+→ 解法：**只按扩展名白名单**决定响应类型，并加 `X-Content-Type-Options: nosniff`。
+
+#### 坑 8 · `?k=../config.php` 能读到任意文件
+对象键没有校验，`k` 参数直接被拼进存储请求。
+→ 解法：严格白名单（限定目录前缀 + 字符集 + 拒绝 `..`）。
+
+#### 坑 9 · JSON 接口突然解析失败，报 `Unexpected token '<'`
+`display_errors` 开着时，PHP 的 **Warning** 会以 HTML 形式打在 JSON 前面。触发源常常是宝塔等环境注入的 `.user.ini`：`open_basedir=/站点目录/:/tmp/`，此时对 `/etc/ssl/…` 这类**站外路径**调用 `is_file()` 会抛 `open_basedir restriction in effect` 警告。
+→ 解法：探测系统文件之前**自己先判断 `open_basedir` 允不允许**（`storagePathAllowed()`），并且所有探测加 `@` 抑制。生产环境还应关闭 `display_errors`。
+
+#### 坑 10 · 用命令行排查时「图片根本不在云上」——假象
+`db/.settings.key` 的属主是 Web 用户（如 `www`，权限 600）。换一个用户跑 `php` 或 PHP 脚本，**解密失败** → 读出的云存储配置是空的 → 门面回退本地 → 表现为「404、耗时 0 秒」，很容易误判成「对象没上传成功」。
+→ 解法：**必须以 Web 用户身份**跑诊断代码（临时放一个带随机 token 门禁、用完即删的诊断页，或用 Web 用户执行 CLI）。
+
+#### 坑 11 · 桶名看错了一个字母，排查了半天
+Bucket 名称是全局唯一标识，**字母一个都不能错**，而拼错时通常不会给出「你拼错了」这种提示，只会得到 404 / 403（阿里云会回 `NoSuchBucket`）。
+→ 在响应体里找 `<BucketName>`，或直接以控制台实际显示为准，别凭记忆填写。
+
+#### 坑 12 · 部署脚本「备份成功」但实际没备份
+`cp -p` 多级路径（`lib/storage/oss.php`）到备份目录时，**子目录不存在会静默失败**，脚本继续往下走覆盖了线上文件，事后才发现没有可回滚的副本。
+→ 解法：备份循环里先 `mkdir -p "$BK/$(dirname "$f")"`；备份后**递归统计文件数并与预期条数比对**，数量不符立即中止（这是覆盖前的最后一道止损闸）；覆盖后再逐文件比对 sha256。
+
+### 7. 排障手册（可直接复制的命令）
+
+```bash
+# ① 判断是不是防盗链：A / B 对比（把 URL 换成你的）
+URL="https://<bucket>.oss-cn-xxx.aliyuncs.com/movielog/uploads/posters/xxx.webp"
+curl -sS -o /dev/null -w "无 Referer   %{http_code}\n" "$URL"
+curl -sS -o /dev/null -w "带本站 Referer %{http_code}\n" -H "Referer: https://你的域名/" "$URL"
+curl -sS -o /dev/null -w "带陌生 Referer %{http_code}\n" -H "Referer: https://evil.example.com/" "$URL"
+# 403 时把响应体打出来，里面有云厂商的原始判决
+curl -sS -H "Referer: https://你的域名/" "$URL"
+
+# ② 是否配了 CORS（裁剪用）
+curl -sS -D - -o /dev/null -H "Origin: https://你的域名" "$URL" | grep -i "access-control"
+
+# ③ 在服务器上量内外网可达性与耗时（诊断「代理很慢」第一步）
+curl -o /dev/null -s -w 'dns=%{time_namelookup} conn=%{time_connect} tls=%{time_appconnect} total=%{time_total} code=%{http_code}\n' \
+  --max-time 20 https://<bucket>.oss-cn-xxx-internal.aliyuncs.com/
+curl -o /dev/null -s -w 'public conn=%{time_connect} tls=%{time_appconnect} total=%{time_total} code=%{http_code}\n' \
+  --max-time 20 https://<bucket>.oss-cn-xxx.aliyuncs.com/
+
+# ④ 本机 ECS 地域（与桶地域对比，不同就别走内网）
+curl -s --max-time 5 http://100.100.100.200/latest/meta-data/region-id
+
+# ⑤ 端到端计时：在**服务器本机**打自己的站点，排除公网 RTT
+#    （Cookie 用浏览器里已登录的 PHPSESSID）
+curl -sk -H "Host: 你的域名" -H "Cookie: PHPSESSID=xxxx" -o /dev/null \
+  -w "ttfb=%{time_starttransfer} total=%{time_total} size=%{size_download}\n" \
+  "https://127.0.0.1/media.php?k=uploads/posters/xxx.webp"
+```
+
+**读结果的方法**：`time_namelookup` 很快但 `time_connect` 拿不到 → 目标不可路由（典型就是跨地域内网）；
+单张图服务端耗时应当在**几百毫秒内**；若接近 10 秒、或总耗时随图片数量线性增长，回去看坑 4 与坑 5。
+
+### 8. 部署与运维注意
+
+- **改桶权限前先确认代码已上线**：直连↔代理的切换顺序建议「先部署代码 → 切访问方式 → 确认图片正常 → 最后才改桶 ACL / 防盗链」，每一步都可单独回滚。
+- **代理模式会占服务器出网带宽**：图片流量走一遍服务器。用「阿里云内网 endpoint + 同地域 ECS」可以免掉云端到服务器的流量费；跨地域则要计费。
+- **`uploads/` 与 `db/` 不要暴露**：见《安全注意事项》。
+- **迁移/删除本地文件是有损操作**：先备份 `db/` 与 `uploads/`，再动手。
+
+---
+
 ## 安全注意事项

 部署到公网前请务必处理以下事项：
@@ -268,6 +548,14 @@ CSV **共 9 列，顺序固定**：
   ```
 7. **限制上传目录执行权限**：确保 `uploads/` 下不允许执行 PHP。

+### 与对象存储相关的额外事项
+
+8. **桶不要长期开公共读**：直连存储要求桶允许匿名读取，等于**任何拿到 URL 的人都能看图**。私人 / 家庭内容请改用「服务端代理」，把桶设为**私有**——那才是真正的访问控制。
+9. **防盗链不是访问控制**：`Referer` 是客户端可伪造的普通请求头，`curl -H Referer` 就能绕过。它只能挡住「别的网站盗链」，不能保护内容。别把它当成安全边界。
+10. **保护好 `db/.settings.key`**：云厂商 AccessKey 以密文存在数据库里，这个文件是唯一的解密密钥。应随 `db/` 一起纳入访问控制与备份策略；优先改用实例角色（RAM / CAM 角色）**免密钥**方案，从根上不落长期密钥。
+11. **`media.php` 是新增的对外接口**：它按 `k` 参数从对象存储取对象。仓库里已做**对象键白名单**（防目录穿越）与**类型白名单**（防同源 XSS）两层校验，改动此文件时**务必保留**，不要把 `$_GET['k']` 直接拼进存储请求。
+12. **不要把上游 `Content-Type` 原样透传**：桶里若有 `.html` / `.svg`，透传类型会让它在本站域名下执行（同源 XSS）。始终按扩展名白名单决定，并加 `X-Content-Type-Options: nosniff`。
+
 ---

 ## 已知限制与待改进
@@ -278,6 +566,10 @@ CSV **共 9 列，顺序固定**：
 - `config.php` 的 `initDB()` 在每次请求都会跑一遍建表与迁移，数据量或并发上升后可改为一次性迁移脚本。
 - 无「回收站」，删除电影与其图片文件不可恢复。
 - `assets/placeholder-poster.jpg`、`assets/default-avatar.png` 为代码中的兜底引用，当前仓库未包含这两个文件；由于页面在检测到 placeholder 时会改用 CSS 占位块渲染，正常使用不受影响。
+- **「直连存储」模式下裁剪功能不可用**：裁剪需要读取图片像素，直连时图片来自对象存储域名，必须同时满足「桶配 CORS」与「`<img crossorigin="anonymous">`」两个条件才能读像素；本仓库未加 `crossorigin` 属性，因此直连模式下只能上传、不能二次裁剪。需要裁剪请改用「服务端代理」（同源，两个条件全免）。详见《图片存储与对象存储》§3③。
+- **服务端代理模式下所有图片流量经服务器中转**，会占用服务器出网带宽，并给每张图增加一次服务器↔存储的往返（同地域约 10–30 ms，跨地域约 60–100 ms）。图片量大且可公开时可考虑改回直连。
+- **内网 endpoint 只在服务器与桶同地域时生效**。跨地域部署下这条免费通道用不了，程序会自动跳过并走公网（详见 §4）。
+- 迁移到云端后**本地文件不会自动删除**，需要自行确认后再清理；本地优先策略意味着本地文件存在时始终读本地，云端副本仅作备份。

 ---