From c8b9860d74e3579fa607d9ff92c0fa04570fed3e Mon Sep 17 00:00:00 2001
From: yourname <yourname@email.com>
Date: Tue, 7 Apr 2026 13:23:31 +0000
Subject: [PATCH] =?UTF-8?q?sync:=20d8d-dev=20=E6=8A=80=E8=83=BD=E6=9B=B4?=
 =?UTF-8?q?=E6=96=B0=20=E2=80=94=20NPM=20=E4=BB=A3=E7=90=86=E9=85=8D?=
 =?UTF-8?q?=E7=BD=AE=20+=20MinIO=20=E5=A4=96=E7=BD=91=E5=9C=B0=E5=9D=80?=
 =?UTF-8?q?=E6=B3=A8=E5=85=A5?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- phase-00-setup.md: 步骤 4.5 NPM block_exploits/WebSocket, 步骤 4.8 MinIO 外网地址
- platform-nextjs.md: §7 NPM 代理配置, §8 MinIO 外网地址配置

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .claude/skills/d8d-dev/phase-00-setup.md      | 20 +++++++++++++
 .../d8d-dev/reference/platform-nextjs.md      | 30 +++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/.claude/skills/d8d-dev/phase-00-setup.md b/.claude/skills/d8d-dev/phase-00-setup.md
index ff5c193..31712c5 100644
--- a/.claude/skills/d8d-dev/phase-00-setup.md
+++ b/.claude/skills/d8d-dev/phase-00-setup.md
@@ -177,6 +177,26 @@
    - 此步骤创建的 .env.local 不应提交到 git（应在 .gitignore 中排除）
    - 更新 pipeline-context.md 记录注入状态
 
+4.8. **MinIO 外网地址注入（⛔ 强制）**
+
+   检测容器环境变量 `MINIO_HOST`，将外网地址注入到 `.env` 中的 `S3_PUBLIC_URL`：
+
+   a. 检测 MINIO_HOST：
+      ```bash
+      echo $MINIO_HOST
+      ```
+   b. 探测 HTTPS 是否可用：
+      ```bash
+      curl -sf --max-time 5 https://$MINIO_HOST/minio/health/live && echo "HTTPS" || echo "NO-HTTPS"
+      ```
+   c. 注入到 `.env`（⚠️ 注意 K8S ingress 会将 HTTP 升级为 HTTPS，必须使用 HTTPS）：
+      ```
+      S3_PUBLIC_URL="https://{MINIO_HOST}"
+      ```
+   d. 代码中对外暴露的 URL（presigned URL、封面图 URL）必须使用 `S3_PUBLIC_URL`
+   e. 内部连接（S3Client endpoint）保持 `S3_ENDPOINT`（localhost:9000）
+   f. 详见 `reference/platform-nextjs.md` §8
+
 5. **初始化管道状态**
    - 创建 `{implementation_artifacts}/pipeline-state.yaml`：
      ```yaml
diff --git a/.claude/skills/d8d-dev/reference/platform-nextjs.md b/.claude/skills/d8d-dev/reference/platform-nextjs.md
index 6285b41..1fe2dcc 100644
--- a/.claude/skills/d8d-dev/reference/platform-nextjs.md
+++ b/.claude/skills/d8d-dev/reference/platform-nextjs.md
@@ -230,3 +230,33 @@ NPM 代理主机默认配置会阻断 WebSocket，导致：
 ### 验证
 
 `get_proxy_host` 确认：`block_exploits: false` + `allow_websocket_upgrade: true`
+
+---
+
+## 8. MinIO 外网地址配置（⛔ 强制）
+
+### 问题描述
+
+`S3_ENDPOINT` 默认为 `http://localhost:9000`（容器内部连接）。但对外暴露的 URL（presigned URL、封面图 URL）
+如果使用 `localhost:9000`，外网用户无法访问。
+
+容器环境提供 `MINIO_HOST` 环境变量（外网 MinIO 域名），需要注入为 `S3_PUBLIC_URL`。
+
+### 关键区分
+
+| 变量 | 用途 | 值 |
+|------|------|------|
+| `S3_ENDPOINT` | S3Client 内部连接 | `http://localhost:9000` |
+| `S3_PUBLIC_URL` | 对外暴露的 URL（presigned、封面） | `https://{MINIO_HOST}` |
+
+### 代码规则
+
+- **`getDownloadUrl()`**：返回内部 presigned URL（worker 下载用）
+- **`getPublicDownloadUrl()`**：返回外网 presigned URL（stream 路由用，替换域名）
+- **`uploadFile()` 返回值**：使用 `S3_PUBLIC_URL`（公开访问 URL）
+- **worker 中的封面 URL**：使用 `S3_PUBLIC_URL`
+
+### ⚠️ HTTPS 注意
+
+K8S ingress 会将 HTTP 升级为 HTTPS。`S3_PUBLIC_URL` 必须使用 `https://`，
+否则 presigned URL 签名会因重定向而失效。