# NAS媒体刮削TMDB接口访问问题完整排查\+落地文档

# NAS 媒体刮削 TMDB 接口访问问题完整排查 \+ 落地文档

> 文档来源：本次全部对话记录整理，包含：故障现象、完整排错过程、根因分析、两套可落地解决方案、配置模板、验证命令、故障清单
> 环境：MacOS Clash Verge Rev、群晖 NAS（Mihomo\+Hysteria2 正常）、飞牛 fnOS（Docker 部署 MoviePilot、tinyMediaManager）
> 
> 

## 目录

1. 故障现象汇总

2. 前期网络排错全过程（curl、TLS、Hysteria2 排查）

3. 根因分析

4. 方案一【主方案｜推荐日常使用】飞牛容器复用群晖 Mihomo 代理

5. 方案二【备用兜底方案】Cloudflare Worker TMDB 中转（鉴权 \+ 缓存，无需代理）

6. 两套方案切换规则

7. 统一故障排查清单

8. 附录：测试命令、参考脚本

---

# 1\. 故障现象汇总

## 1\.1 网络侧现象

1. MacOS 客户端：Clash Verge Rev（Mihomo 内核），Hysteria2 节点，访问`api.themoviedb.org`正常，TMDB 接口可访问。

2. 群晖 NAS：部署 Mihomo，**同一份 config\.yaml、相同内核版本**，Hysteria2 节点正常，MoviePilot、TinyMediaManager 媒体刮削，TMDB 接口调用全部正常。

3. 飞牛 fnOS：

    - 飞牛系统无系统级全局代理；

    - 飞牛 Docker 内部署 Mihomo，订阅同样 Hysteria2 节点，节点列表加载成功，但所有 Hysteria2 节点 TLS 握手失败，`SSL_ERROR_SYSCALL`；

    - 在飞牛上部署 MoviePilot、tinyMediaManager，调用 TMDB API 接口全部超时失败，无法刮削媒体元数据。

> 测试现象：curl 访问`https://api.themoviedb.org`，TLS 握手卡在 Client Hello 后直接断开，报错：`curl: (35) OpenSSL SSL_connect: SSL_ERROR_SYSCALL`。
> 
> 

## 1\.2 测试过程关键现象

1. 裸网直接访问`api.themoviedb.org:443`：TCP 能建立连接，TLS 握手中断，SNI 被网络拦截。

2. 使用本地 SOCKS5 代理（7890），未使用`--socks5-hostname`：本地解析域名，拿到污染 IP，握手失败；使用`--socks5-hostname`，域名交由代理远端解析。

3. Hysteria2 依赖 UDP QUIC 协议；飞牛 fnOS 的 OVS 虚拟交换机 \+ 家庭路由器会拦截 UDP 出站，导致 HY2 QUIC 握手超时。

4. 飞牛 Docker 容器**不会自动继承宿主机的代理**，容器内程序（MoviePilot/TMM）不会自动走宿主机 Mihomo。

---

# 2\. 前期网络排错全过程记录

## 2\.1 基础 curl 裸网测试

```bash
# 测试80端口HTTP
curl -v api.themoviedb.org
# HTTPS裸网测试，TLS握手失败
curl -v https://api.themoviedb.org
```

现象：TCP 连接成功，发送 TLS Client Hello 之后直接断开，报错 `SSL_ERROR_SYSCALL`。

> 尝试指定 TLS 版本`--tls-max 1.2`，依旧握手失败。
> 
> 

## 2\.2 SOCKS 代理测试（本地 7890 端口）

```bash
# 错误：本地解析域名
curl -v --socks5 127.0.0.1:7890 https://api.themoviedb.org
# 正确：远端域名解析（socks5h）
curl -v --socks5-hostname 127.0.0.1:7890 https://api.themoviedb.org
# 验证代理出口IP
curl -v --socks5-hostname 127.0.0.1:7890 https://ifconfig.me
```

> 结论：`--socks5` 是本地解析域名，容易拿到污染 IP；**`--socks5-hostname`** 将域名解析交给远端代理服务器，规避 DNS 污染。
> 
> 

## 2\.3 协议选型评估：mieru /anytls/hysteria2

|协议|特点|本次环境适配性|
|---|---|---|
|Hysteria2|QUIC/UDP，速度好；**强依赖 UDP 出站**|Mac / 群晖正常；飞牛 fnOS 受 OVS、路由器 UDP 拦截，无法稳定运行|
|AnyTLS|TCP 隧道，不依赖 UDP；存在内层 TLS1\.3 报文被篡改风险|UDP 不通场景备选，稳定性弱于 HY2|
|Mieru|TCP 隧道，抗干扰；同样 TCP 底层，TLS1\.3 握手存在概率异常|备选|

> 结论：飞牛环境不适合本地部署 Hysteria2，放弃在飞牛本机跑代理。
> 
> 

## 2\.4 Mihomo 日志排查方法（飞牛 Docker）

1. 修改 Mihomo 配置，开启 debug 日志

```yaml
log-level: debug
external-controller: 127.0.0.1:9090
```

2. 查看容器实时日志

```bash
# 查看容器名
docker ps | grep mihomo
# 实时跟踪日志
docker logs -f --tail 100 mihomo
# 导出日志到文件
docker logs mihomo > mihomo-debug.log
```

3. 关键词识别

- `quic: connection timed out` → UDP 出站被拦截（本次核心问题）

- `unsupported proxy type: hysteria2` → Mihomo 内核版本过低

- `tls: certificate verify failed` → 需要`skip-cert-verify: true`

> 验证连通性（飞牛容器内 curl 测试）
> 
> 

```bash
docker exec -it moviepilot curl -v --socks5-hostname 群晖IP:7890 https://api.themoviedb.org/3/movie/550?api_key=你的TMDBKEY
```

---

# 3\. 根因分析

1. 飞牛 fnOS 自带 OVS 虚拟交换机，会拦截 UDP 数据包；家庭路由器 / 光猫也会限制 UDP 出站，Hysteria2（QUIC/UDP）无法正常建立隧道。

2. 飞牛 Docker 容器隔离：容器内程序不会自动复用宿主机代理，MoviePilot、TMM 裸网访问 TMDB，遭遇 DNS 污染 \+ SNI 阻断。

3. Mac、群晖网络环境 UDP 不受限，所以同样配置、同样节点可以正常工作。

> 最终方案思路：**不再在飞牛部署 Mihomo 代理**，采用双冗余架构：
> ✅ 主方案：飞牛容器内 MoviePilot/TMM 直接复用**群晖 Mihomo 的 SOCKS5 代理**
> ✅ 备用方案：CF Worker 中转 TMDB API，**完全不需要代理**，群晖 / 代理故障时兜底刮削。
> 
> 

---

# 4\. 方案一【主方案｜推荐日常使用】飞牛容器复用群晖 Mihomo 代理

## 4\.1 群晖 Mihomo 前置配置（必须）

群晖 Mihomo `config.yaml` 关键配置，**允许局域网访问**

```yaml
mixed-port: 7890
allow-lan: true
listen-address: 0.0.0.0
ipv6: false
```

> 要求：群晖防火墙放行 7890 端口；飞牛与群晖在同一局域网，无跨 VLAN 隔离。
> 
> 

## 4\.2 MoviePilot docker\-compose\.yml（飞牛 fnOS）

> 修改：`192.168.1.100` 替换为**群晖内网 IP**；修改 volume 路径为飞牛实际路径
> 
> 

```yaml
version: "3.8"
services:
  moviepilot:
    image: jxxghp/moviepilot:latest
    container_name: moviepilot
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - /volume1/moviepilot:/app/config
    environment:
      - TZ=Asia/Shanghai
      # socks5h = 远端域名解析，规避DNS污染
      - PROXY_HOST=socks5h://192.168.1.100:7890
      # Github资源加速，解决插件下载失败
      - GITHUB_PROXY=https://mirror.ghproxy.com/
    network_mode: bridge
```

### MoviePilot WebUI 配置

- TMDB 地址保持官方默认，**PROXY\_HOST 已由环境变量注入，无需重复填写**

- 填入你的 TMDB API Key

> 启动命令：`docker-compose up -d`
> 
> 

## 4\.3 TinyMediaManager \(TMM\) docker\-compose\.yml（飞牛 fnOS）

```yaml
version: "3.8"
services:
  tinymediamanager:
    image: tinymediamanager/tinymediamanager:latest
    container_name: tinymediamanager
    restart: unless-stopped
    ports:
      - "4000:4000"
    volumes:
      - /volume1/tmm:/config
    environment:
      - TZ=Asia/Shanghai
      - ALL_PROXY=socks5h://192.168.1.100:7890
      - NO_PROXY=127.0.0.1,localhost,192.168.0.0/16
    network_mode: bridge
```

### TMM WebUI 代理配置（推荐优先使用网页内配置，比环境变量更稳定）

- Proxy type: `SOCKS5`

- Host：群晖内网 IP

- Port：7890

- ✅ 勾选：Resolve hostnames remotely（远端域名解析，等价 socks5h）

## 4\.4 连通验证命令

```bash
docker exec -it moviepilot curl -v --socks5-hostname 192.168.1.100:7890 https://api.themoviedb.org/3/movie/550?api_key=你的TMDB密钥
```

> 返回 JSON 代表链路正常。
> 
> 

---

# 5\. 方案二【备用兜底方案】Cloudflare Worker TMDB 中转（鉴权 \+ 缓存，无需代理）

> 适用场景：群晖关机、代理节点失效、UDP 链路彻底不可用。仅接管 TMDB 接口，Github、豆瓣等其他外网 API 仍然需要代理。
> 免费限制：CF Worker 免费版每日 10 万次请求，日常刮削完全够用。
> 
> 

## 5\.1 主中转 Worker 脚本（鉴权 \+ 缓存）

登录 Cloudflare 后台 → Workers \& Pages → 创建 Worker，清空原有代码粘贴下面代码

```javascript
export default {
  async fetch(request, env) {
    // ========== 自定义你的访问密钥，自行修改 ==========
    const ACCESS_SECRET = "自定义随机密钥";
    // 缓存有效期，单位秒：3600=1小时；600=10分钟；86400=24小时
    const CACHE_TTL = 3600;
    // ================================================

    const auth = request.headers.get("X-Tmdb-Secret");
    if (!auth || auth !== ACCESS_SECRET) {
      return new Response("Access Denied", { status: 403 });
    }

    const targetHost = "api.themoviedb.org";
    const url = new URL(request.url);
    url.hostname = targetHost;
    const newReq = new Request(url, request);
    newReq.headers.set("Host", targetHost);

    // GET请求开启缓存，提升速度、节约额度
    if (request.method === "GET") {
      const cacheKey = new Request(newReq.url, newReq);
      const cache = caches.default;
      let response = await cache.match(cacheKey);

      if (!response) {
        response = await fetch(newReq);
        response = new Response(response.body, response);
        response.headers.set("Cache-Control", `s-maxage=${CACHE_TTL}`);
        await cache.put(cacheKey, response.clone());
      }
      return response;
    }
    // POST等其他请求直接透传，不缓存
    return await fetch(newReq);
  }
}
```

保存部署，得到 worker 域名，示例 `tmdb-proxy.xxx.workers.dev`

## 5\.2 缓存清理三种方案

1. **单影片临时绕过缓存（最简单）**
请求地址末尾追加：`&_nocache=随机数字`
示例：
`https://tmdb-proxy.xxx.workers.dev/3/movie/550?api_key=xxx&_nocache=20260925`

2. **全局一键清空全部缓存（批量重刷媒体库）**
修改 Worker 代码任意一行，重新部署；CF 所有边缘节点缓存自动全部失效。

3. **精准单条缓存删除（进阶 Purge Worker）**
新建独立 Worker（tmdb\-purge），粘贴下面代码，密钥和主 Worker 保持一致

```javascript
export default {
  async fetch(request, env) {
    const ACCESS_SECRET = "和主Worker相同的密钥";
    const auth = request.headers.get("X-Tmdb-Secret");
    if (!auth || auth !== ACCESS_SECRET) {
      return new Response("Access Denied", { status: 403 });
    }

    const url = new URL(request.url);
    const targetPath = url.searchParams.get("path");
    if (!targetPath) {
      return new Response("Missing ?path=/3/movie/550", { status: 400 });
    }
    // 替换为你的主worker域名
    const cacheUrl = new URL(`https://tmdb-proxy.xxx.workers.dev${targetPath}`);
    const cacheReq = new Request(cacheUrl);
    const cache = caches.default;
    await cache.delete(cacheReq);
    return new Response(`Purged: ${cacheUrl.toString()}`);
  }
}
```

调用示例：

```bash
curl -v -H "X-Tmdb-Secret: 自定义随机密钥" "https://tmdb-purge.xxx.workers.dev/?path=/3/movie/550?api_key=你的TMDBKEY"
```

## 5\.3 MoviePilot 切换 CF Worker 配置

1. 清空 PROXY\_HOST（关闭代理）

2. TMDB API 地址：`https://tmdb-proxy.xxx.workers.dev/3`

3. 自定义请求头添加一行：
`X-Tmdb-Secret: 自定义随机密钥`

4. 保留原有 TMDB API Key

## 5\.4 TMM 切换 CF Worker 配置

1. TMDB API URL 替换为 worker 地址 `https://tmdb-proxy.xxx.workers.dev/3`

2. Custom HTTP Headers 添加：`X-Tmdb-Secret: 自定义随机密钥`

3. 关闭 TMM 内部代理设置

## 5\.5 curl 测试命令

```bash
curl -v -H "X-Tmdb-Secret: 自定义随机密钥" "https://tmdb-proxy.xxx.workers.dev/3/movie/550?api_key=你的TMDBKEY"
```

返回 JSON 即为正常。

---

# 6\. 两套方案切换规则

|方案|适用场景|优点|缺点|
|---|---|---|---|
|复用群晖 Mihomo（主方案）|日常长期使用，群晖保持开机|全覆盖 TMDB/Github/ 豆瓣，无额度限制，速度稳定|依赖群晖在线，群晖关机则刮削失效|
|CF Worker 中转（备用）|群晖关机、代理节点故障、UDP 被拦截|零代理依赖，不受 UDP/OVS 限制，自带缓存加速|仅 TMDB 接口生效，CF 免费版有每日额度上限|

> 使用策略：日常使用主方案；代理故障 / 群晖关机，临时切换到 CF Worker 兜底刮削。
> 
> 

---

# 7\. 统一故障排查清单

1. ❌ 容器内不要填写`127.0.0.1`作为代理地址，容器内 \[127\.0\.0\.1\]\(127\.0\.0\.1\) 指向容器自身，必须填写群晖内网 IP。

2. ✅ 群晖 Mihomo 必须开启`allow-lan: true`，监听地址`0.0.0.0`，否则飞牛无法访问 7890 端口。

3. ✅ 飞牛环境关闭 IPv6，规避 TLS 握手异常。

4. ❌ 放弃飞牛本地部署 Hysteria2，OVS \+ 路由器 UDP 拦截属于硬限制。

5. ✅ MoviePilot/TMM 优先使用软件原生内置代理配置，优于`ALL_PROXY`环境变量。

6. 测试链路优先使用`--socks5-hostname`，远端解析域名，规避 DNS 污染。

7. 代理测试失败优先查看 Mihomo debug 日志，定位是 UDP 超时、证书错误还是鉴权错误。

---

# 8\. 附录：常用命令汇总

```bash
# 查看docker容器
docker ps | grep mihomo
docker ps | grep moviepilot
# 实时查看mihomo日志
docker logs -f --tail 100 mihomo
# 进入moviepilot容器curl测试代理连通
docker exec -it moviepilot curl -v --socks5-hostname 群晖IP:7890 https://api.themoviedb.org/3/movie/550?api_key=你的TMDBKEY
# 测试CF Worker中转
curl -v -H "X-Tmdb-Secret: 自定义密钥" "https://tmdb-proxy.xxx.workers.dev/3/movie/550?api_key=你的TMDBKEY"
```

---

如果你想要，我可以再输出 **Markdown 纯文本版本**（不带任何 canvas 标签，直接复制到 Typora/Obsidian/ 语雀保存）。你要 Markdown 版本吗？

> （注：部分内容可能由 AI 生成）