trigo-web/ONNXRUNTIME_NODE_FIX.md

onnxruntime-node 安装问题修复方案

问题描述

onnxruntime-node@1.23.2 的 postinstall 脚本在下载二进制文件时无法正确处理 HTTP 302 重定向，导致安装失败：

Error: Failed to download build list. HTTP status code = 302

根本原因

Node.js 原生的 https.get() 不会自动跟随 HTTP 重定向。onnxruntime-node 的 install-utils.js 中的 downloadFile() 和 downloadJson() 函数缺少重定向处理逻辑。

解决方案

方案 A: 应用 Patch（推荐）

已创建 patch 文件来修复重定向问题：

cd ~/work/trigoRL/third_party/trigo/trigo-web/node_modules/onnxruntime-node/script
patch -p0 < ~/work/trigoRL/third_party/trigo/trigo-web/onnxruntime-node-redirect-fix.patch

Patch 修改内容：

1. 为 downloadFile() 和 downloadJson() 添加 maxRedirects 参数（默认值 5）
2. 检测 HTTP 状态码 300-399 并提取 Location 头
3. 递归调用自身跟随重定向，直到获得 200 状态码或达到最大重定向次数

方案 B: 跳过安装（仅用于不需要 ONNX 推理的场景）

yarn install --ignore-scripts

限制： onnxruntime-node 的 CUDA 和 TensorRT 二进制文件不会被下载，无法在 Node.js 中进行 GPU 推理。

修复验证

1. 测试安装脚本

cd ~/work/trigoRL/third_party/trigo/trigo-web/node_modules/onnxruntime-node
node ./script/install

预期输出：

Following redirect to https://nuget.azure.cn/v3/index.json
Following redirect to https://nuget.azure.cn/v3-flatcontainer/...
Downloading https://api.nuget.org/v3-flatcontainer/...
Extracting runtimes/linux-x64/native/libonnxruntime_providers_cuda.so to ...
Extracting runtimes/linux-x64/native/libonnxruntime_providers_shared.so to ...
Extracting runtimes/linux-x64/native/libonnxruntime_providers_tensorrt.so to ...

2. 验证模块加载

cd ~/work/trigoRL/third_party/trigo/trigo-web
node -e "const ort = require('onnxruntime-node'); console.log('Supported backends:', ort.listSupportedBackends());"

预期输出：

Supported backends: [
  { name: 'cpu', bundled: true },
  { name: 'webgpu', bundled: true },
  { name: 'cuda', bundled: false },
  { name: 'tensorrt', bundled: false }
]

3. 检查二进制文件

ls -lh ~/work/trigoRL/third_party/trigo/trigo-web/node_modules/onnxruntime-node/bin/napi-v6/linux/x64/*.so

预期输出：

-rw-rw-rw- 1 camus camus 352M libonnxruntime_providers_cuda.so
-rw-rw-rw- 1 camus camus  15K libonnxruntime_providers_shared.so
-rw-rw-rw- 1 camus camus 811K libonnxruntime_providers_tensorrt.so

技术细节

修改的函数

downloadFile()

添加递归重定向处理：

async function downloadFile(url, dest, maxRedirects = 5) {
  // 检查重定向次数
  if (maxRedirects < 0) {
    reject(new Error('Too many redirects'));
    return;
  }

  // 检测 300-399 状态码
  if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
    const redirectUrl = new URL(res.headers.location, url).toString();
    downloadFile(redirectUrl, dest, maxRedirects - 1).then(resolve).catch(reject);
    return;
  }
  // ...
}

downloadJson()

类似的重定向处理逻辑应用于 JSON 下载。

为什么需要这个修复

1. NuGet CDN 重定向： onnxruntime 使用 NuGet 包托管，某些 CDN 节点会返回 302 重定向
2. 代理环境： 在使用代理的网络环境中，重定向更为常见
3. 地理位置优化： NuGet 会根据地理位置重定向到最近的镜像服务器

未来维护

当 onnxruntime-node 更新到新版本时：

1. 检查是否已修复： 新版本可能已经包含重定向处理
2. 重新应用 patch： 如果未修复，需要在新版本的 install-utils.js 上重新应用 patch
3. 提交上游 PR： 可以向 onnxruntime 项目提交 Pull Request 来永久修复这个问题

相关文件

• Patch 文件： onnxruntime-node-redirect-fix.patch
• 原始脚本： node_modules/onnxruntime-node/script/install-utils.js
• 备份文件： node_modules/onnxruntime-node/script/install-utils.js.backup

环境信息

• 修复日期： 2025-11-21
• onnxruntime-node 版本： 1.23.2
• Node.js 版本： v24.11.1
• 操作系统： Ubuntu 22.04 (LXD container)
• GPU： 8x NVIDIA H20

状态

✅ 已彻底解决 - onnxruntime-node 的 CUDA 和 TensorRT 后端已成功安装并可用于 Node.js ONNX 模型推理。