docs(lobehub): 更新自托管部署文档说明 S3 配置要点

详细解释了 S3_SET_ACL 参数的作用机制，以及如何正确配置
S3_ENDPOINT 和 S3_PUBLIC_DOMAIN 来解决容器内外网络访问问题。

当 S3_SET_ACL=0 时，LobeHub 会基于 S3_ENDPOINT 生成预签名预览地址，
如果使用 host.docker.internal 则浏览器无法访问该地址。

新增关于网络配置的详细说明，包括：
- 使用 macmini 作为统一的主机访问地址
- 在 network-service 中添加 extra_hosts 映射
- 上传链路中浏览器直传目标的地址解析机制

提供了排查 hostname 解析问题的辅助脚本。

Author: mudssky

ai/self-hosted/lobehub/README.md

@@ -289,3 +289,54 @@ docker compose up --force-recreate rustfs-init
 - `APP_URL`
 
 把它们改成你本机浏览器可以直接访问的地址即可。
+
+另外还要确认当前 compose 没把 `S3_SET_ACL` 关掉。
+
+- 现在默认配置应当让 `S3_SET_ACL=1`
+- 原因是 LobeHub 在 `S3_SET_ACL=0` 时，会回退成基于 `S3_ENDPOINT` 生成预签名预览地址
+- 如果你的 `S3_ENDPOINT` 是 `http://host.docker.internal:9000`，那这个地址对容器可用，但对宿主机浏览器通常不可用
+- 典型现象就是上传成功后，前端马上拿到 `host.docker.internal` 开头的文件 URL，然后界面报错或显示 `Bad Gateway`
+
+还要注意一个更关键的上传链路差异：
+
+- 当前版本的附件上传会先调用 `upload.createS3PreSignedUrl`
+- 这个接口生成的浏览器直传目标，使用的也是 `S3_ENDPOINT`
+- 也就是说，`S3_ENDPOINT` 不只是“容器内访问 RustFS”的地址，它还会直接暴露给浏览器
+- 如果这里写成 `host.docker.internal`，浏览器通常会在上传前的 `OPTIONS/PUT` 阶段直接失败
+
+当前仓库默认建议改成：
+
+- `S3_ENDPOINT=http://macmini:9000`
+- `S3_PUBLIC_DOMAIN=http://macmini:9000`
+
+如果 `macmini` 是这台机器在 Tailscale / MagicDNS 里的稳定地址，推荐统一这样配置。
+
+同时要记得：
+
+- 浏览器侧会直接访问 `S3_ENDPOINT`
+- 容器侧也必须能解析 `macmini`
+- 当前 compose 使用了 `network_mode: service:network-service`
+- 因此主机名映射要加在 `network-service` 上，而不是 `lobe` 上
+
+当前默认做法就是：
+
+- `.env` 中 `S3_ENDPOINT=http://macmini:9000`
+- `.env` 中 `S3_PUBLIC_DOMAIN=http://macmini:9000`
+- `docker-compose.yml` 里的 `network-service.extra_hosts` 增加 `macmini:host-gateway`
+
+这样同一 Tailnet 里的其它客户端、宿主机浏览器和容器内服务都会统一使用 `macmini`，避免再出现上传直传地址和对外访问地址分裂的问题。
+
+排查时可以直接在宿主机执行：
+
+```bash
+python3 - <<'PY'
+import socket
+for host in ['host.docker.internal', 'localhost']:
+    try:
+        print(host, socket.gethostbyname(host))
+    except Exception as exc:
+        print(host, 'ERR', exc)
+PY
+```
+
+如果 `host.docker.internal` 在宿主机侧解析失败，而浏览器里看到的文件地址又正好是这个域名，根因基本就确定了。

ai/self-hosted/lobehub/docker-compose.yml

@@ -6,6 +6,10 @@ services:
     restart: always
     ports:
       - '${LOBE_PORT}:3210' # LobeChat
+    extra_hosts:
+      # `lobehub` 复用 `network-service` 的网络命名空间，
+      # 所以需要在这里补 `macmini -> host-gateway`，让容器内也能访问宿主机上的 RustFS。
+      - 'macmini:host-gateway'
     command: tail -f /dev/null
     networks:
       - lobe-network
@@ -57,7 +61,9 @@ services:
       - 'S3_ACCESS_KEY_ID=${RUSTFS_ACCESS_KEY}'
       - 'S3_SECRET_ACCESS_KEY=${RUSTFS_SECRET_KEY}'
       - 'LLM_VISION_IMAGE_USE_BASE64=1'
-      - 'S3_SET_ACL=0'
+      # 默认开启 ACL，让返回给浏览器的文件 URL 走 `S3_PUBLIC_DOMAIN`，
+      # 避免在宿主机浏览器里收到 `host.docker.internal` 这类仅容器内可解析的地址。
+      - 'S3_SET_ACL=${S3_SET_ACL:-1}'
       - 'SEARXNG_URL=http://searxng:8080'
       - 'REDIS_URL=${REDIS_URL}'
       - 'REDIS_PREFIX=lobechat'