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
@@ -0,0 +1,207 @@
+<?php
+// ============================================
+// 文件: lib/storage/meta.php
+// 说明: 云主机实例元数据鉴权（免密钥访问对象存储）
+//         - 阿里云 ECS：RAM 角色 → STS 临时凭据
+//         - 腾讯云 CVM：CAM 角色 → 临时密钥
+//       服务器不在对应云上时，元数据地址不可达，会返回明确错误。
+// ============================================
+
+// 元数据地址不可达时的超时（秒）——必须短，避免拖慢页面
+const STORAGE_META_TIMEOUT = 3;
+
+/**
+ * 阿里云 ECS：获取 RAM 角色的 STS 临时凭据。
+ *
+ * @param string $roleName 指定的 RAM 角色名；留空则自动发现实例绑定的第一个角色
+ * @param bool   $force    忽略缓存强制刷新
+ * @return array ['ok'=>bool,'id'=>string,'secret'=>string,'token'=>string,'expires'=>int,'error'=>string]
+ */
+function aliyunEcsRamCredentials($roleName = '', $force = false) {
+    static $memo = [];
+    $roleName = trim((string)$roleName);
+    $memoKey = 'aliyun:' . $roleName;
+    if (!$force && isset($memo[$memoKey])) return $memo[$memoKey];
+
+    // 跨请求缓存（临时凭据有效期通常 >= 1 小时）
+    if (!$force) {
+        $cached = getSettingJson('cache_meta_aliyun', []);
+        if (!empty($cached['expires']) && $cached['expires'] > time() + 300
+            && ($cached['role'] ?? '') === $roleName) {
+            return $memo[$memoKey] = $cached + ['ok' => true, 'error' => ''];
+        }
+    }
+
+    $base = 'http://100.100.100.200/latest/meta-data/ram/security-credentials/';
+
+    // IMDSv2：先取一次性 token（实例关闭 v1 时必须）
+    $token = '';
+    $t = storageHttp('PUT', 'http://100.100.100.200/latest/api/token',
+        ['X-aliyun-ecs-metadata-token-ttl-seconds: 21600'], null, STORAGE_META_TIMEOUT);
+    if ($t['ok'] && trim($t['body']) !== '') {
+        $token = trim($t['body']);
+    }
+    $authHeader = $token !== '' ? ["X-aliyun-ecs-metadata-token: {$token}"] : [];
+
+    // 角色名
+    if ($roleName === '') {
+        $r = storageHttp('GET', $base, $authHeader, null, STORAGE_META_TIMEOUT);
+        if (!$r['ok']) {
+            return $memo[$memoKey] = aliyunMetaFail($r, '无法访问 ECS 元数据服务');
+        }
+        $first = trim(strtok($r['body'], "\r\n"));
+        if ($first === '') {
+            return $memo[$memoKey] = aliyunMetaFail(null, '该实例未绑定 RAM 角色');
+        }
+        $roleName = $first;
+    }
+
+    $r = storageHttp('GET', $base . rawurlencode($roleName), $authHeader, null, STORAGE_META_TIMEOUT);
+    if (!$r['ok']) {
+        return $memo[$memoKey] = aliyunMetaFail($r, "获取 RAM 角色 {$roleName} 的临时凭据失败");
+    }
+    $json = json_decode($r['body'], true);
+    if (!is_array($json) || empty($json['AccessKeyId']) || empty($json['AccessKeySecret'])) {
+        $returned = is_array($json) ? ($json['Code'] ?? '') : '';
+        return $memo[$memoKey] = aliyunMetaFail(null, '元数据返回内容异常' . ($returned ? "（{$returned}）" : ''));
+    }
+
+    $expires = !empty($json['Expiration']) ? (int)strtotime($json['Expiration']) : time() + 1800;
+    $cred = [
+        'ok' => true,
+        'id' => (string)$json['AccessKeyId'],
+        'secret' => (string)$json['AccessKeySecret'],
+        'token' => (string)($json['SecurityToken'] ?? ''),
+        'expires' => $expires,
+        'error' => '',
+        'role' => $roleName,
+    ];
+    setSettingJson('cache_meta_aliyun', $cred);
+    return $memo[$memoKey] = $cred;
+}
+
+function aliyunMetaFail($resp, $prefix) {
+    $detail = $resp === null ? '' : ($resp['error'] ?? '');
+    return [
+        'ok' => false, 'id' => '', 'secret' => '', 'token' => '', 'expires' => 0,
+        'error' => $prefix . ($detail ? "：{$detail}" : '')
+            . '（请确认服务器位于阿里云 ECS，且实例已绑定 RAM 角色；否则请改用 AccessKey 方式）',
+    ];
+}
+
+/**
+ * 当前 ECS 所在地域 ID（如 cn-qingdao、cn-beijing）。不在阿里云 ECS 上时返回空串。
+ *
+ * 用途：判断「内网 endpoint 能不能用」。`oss-<region>-internal.aliyuncs.com`
+ * **只在与该桶同地域的 ECS 上可路由**；跨地域时 DNS 照常解析（秒回 A 记录）
+ * 但 TCP 永远连不通，于是每次读取都要先白等一次连接超时——这是「服务端代理
+ * 慢到不可用」的典型成因。先比地域，可以完全免掉这类探测。
+ *
+ * 地域不会变，结果缓存 1 小时。
+ *
+ * @param bool $force 忽略缓存强制重取
+ * @return string 地域 ID，未知时为空串
+ */
+function aliyunEcsRegion($force = false) {
+    static $memo = null;
+    if (!$force && $memo !== null) return $memo;
+
+    if (!$force) {
+        $cached = getSettingJson('cache_ecs_region', []);
+        if (!empty($cached['expires']) && $cached['expires'] > time()) {
+            return $memo = (string)($cached['region'] ?? '');
+        }
+    }
+
+    $r = storageHttp('GET', 'http://100.100.100.200/latest/meta-data/region-id',
+        [], null, STORAGE_META_TIMEOUT, false, 2);
+    $region = $r['ok'] ? trim((string)$r['body']) : '';
+    if ($region !== '' && !preg_match('#^[A-Za-z0-9-]+$#', $region)) $region = '';
+
+    setSettingJson('cache_ecs_region', ['region' => $region, 'expires' => time() + 3600]);
+    return $memo = $region;
+}
+
+/**
+ * 腾讯云 CVM：获取 CAM 角色的临时密钥。
+ *
+ * @param string $roleName 指定的 CAM 角色名；留空则自动发现
+ * @param bool   $force    忽略缓存强制刷新
+ * @return array ['ok'=>bool,'id'=>string,'secret'=>string,'token'=>string,'expires'=>int,'error'=>string]
+ */
+function tencentCvmCamCredentials($roleName = '', $force = false) {
+    static $memo = [];
+    $roleName = trim((string)$roleName);
+    $memoKey = 'tencent:' . $roleName;
+    if (!$force && isset($memo[$memoKey])) return $memo[$memoKey];
+
+    if (!$force) {
+        $cached = getSettingJson('cache_meta_tencent', []);
+        if (!empty($cached['expires']) && $cached['expires'] > time() + 300
+            && ($cached['role'] ?? '') === $roleName) {
+            return $memo[$memoKey] = $cached + ['ok' => true, 'error' => ''];
+        }
+    }
+
+    // 腾讯云元数据服务需要先获取会话 token
+    $token = '';
+    $t = storageHttp('PUT', 'http://metadata.tencentyun.com/latest/api/token',
+        ['X-ttc-metadata-token-ttl-seconds: 21600'], null, STORAGE_META_TIMEOUT);
+    if ($t['ok'] && trim($t['body']) !== '') {
+        $token = trim($t['body']);
+    }
+    $authHeader = $token !== '' ? ["X-ttc-metadata-token: {$token}"] : [];
+
+    $base = 'http://metadata.tencentyun.com/latest/meta-data/cam/security-credentials/';
+
+    if ($roleName === '') {
+        $r = storageHttp('GET', $base, $authHeader, null, STORAGE_META_TIMEOUT);
+        if (!$r['ok']) {
+            return $memo[$memoKey] = tencentMetaFail($r, '无法访问 CVM 元数据服务');
+        }
+        $first = trim(strtok($r['body'], "\r\n"));
+        if ($first === '') {
+            return $memo[$memoKey] = tencentMetaFail(null, '该实例未绑定 CAM 角色');
+        }
+        $roleName = $first;
+    }
+
+    $r = storageHttp('GET', $base . rawurlencode($roleName), $authHeader, null, STORAGE_META_TIMEOUT);
+    if (!$r['ok']) {
+        return $memo[$memoKey] = tencentMetaFail($r, "获取 CAM 角色 {$roleName} 的临时密钥失败");
+    }
+    $json = json_decode($r['body'], true);
+    if (!is_array($json) || empty($json['TmpSecretId']) || empty($json['TmpSecretKey'])) {
+        $returned = is_array($json) ? ($json['Code'] ?? '') : '';
+        return $memo[$memoKey] = tencentMetaFail(null, '元数据返回内容异常' . ($returned ? "（{$returned}）" : ''));
+    }
+
+    $cred = [
+        'ok' => true,
+        'id' => (string)$json['TmpSecretId'],
+        'secret' => (string)$json['TmpSecretKey'],
+        'token' => (string)($json['Token'] ?? ''),
+        'expires' => !empty($json['ExpiredTime']) ? (int)$json['ExpiredTime'] : time() + 1800,
+        'error' => '',
+        'role' => $roleName,
+    ];
+    setSettingJson('cache_meta_tencent', $cred);
+    return $memo[$memoKey] = $cred;
+}
+
+function tencentMetaFail($resp, $prefix) {
+    $detail = $resp === null ? '' : ($resp['error'] ?? '');
+    return [
+        'ok' => false, 'id' => '', 'secret' => '', 'token' => '', 'expires' => 0,
+        'error' => $prefix . ($detail ? "：{$detail}" : '')
+            . '（请确认服务器位于腾讯云 CVM，且实例已绑定 CAM 角色；否则请改用 SecretId 方式）',
+    ];
+}
+
+// 清除元数据凭据缓存（设置页"重新探测"时使用）
+function clearMetaCredentialCache() {
+    deleteSetting('cache_meta_aliyun');
+    deleteSetting('cache_meta_tencent');
+    deleteSetting('cache_ecs_region');
+    deleteSetting('cache_oss_internal');
+}