3D 资产服务器教程：从 18 个来源搜索、比较并下载游戏资产

3d-asset-server 的功能

3d-asset-server 为 3D 模型、材质、纹理、HDRI、精灵、UI 资源、音频、字体和游戏资源包提供统一的搜索框。它会搜索 18 个提供商，合并并排列结果，报告每个来源的状态，并在提供商允许直接下载时下载资源。

你可以通过浏览器、使用 curl、通过命令行界面，或通过使用模型上下文协议（MCP）连接的 AI 助手来使用该项目。结果包括许可信息、价格状态、署名要求、格式、分辨率和提供商链接。

搜索工作原理

对于每个查询，服务器会选择相关提供商并行搜索。每个提供商都有自己的超时时间，因此某个网站响应缓慢或不可用时，不会阻止其他来源显示结果。

结果会根据文本相关性、提供商排名、结果来自 API 还是抓取器、是否免费、是否支持直接下载以及来源多样性进行排序。响应还包括每个提供商的报告，状态可能为 ok、error、timeout、skipped 或 link。

部分提供商支持直接下载。Poly Haven、ambientCG、Kenney、TextureCan 以及 BlenderKit 中的免费资源就是示例。其他提供商会返回完整元数据和资源页面链接，而 Fab、Poliigon 和 TurboSquid 会在机器人保护阻止自动搜索时，提供指向其自身搜索页面的链接。

支持的来源

提供商目录包含适用于不同内容类型的来源：

• HDRI 和 PBR 材质： Poly Haven、ambientCG、HDRMaps、HDRI Hub 和 3DTexel。
• 低多边形和游戏资源： Kenney、Quaternius、Fab、itch.io 和 BlenderKit。
• 纹理和扫描材质： CGBookcase、ShareTextures、TextureCan、Textures.com 和 3DTextures.me。
• 模型和资源市场： BlenderKit、CGTrader、TurboSquid、Fab 和 itch.io。

许可详情因条目而异。例如，Poly Haven、ambientCG 和 Kenney 提供 CC0 内容，而市场类提供商可能采用针对具体条目的许可。分发资源前，请务必查看返回的许可和署名信息。

安装和设置

项目需要 Node.js 20 或更高版本。克隆仓库、安装依赖并构建应用：

git clone https://github.com/arielshad/3d-asset-server.git
cd 3d-asset-server
npm install
npm run build

使用以下命令启动 Web UI、HTTP API 和 MCP 端点：

npm start

本地服务器默认运行于 http://localhost:8787。

Docker 设置

你也可以使用 Docker 构建并运行服务器：

docker build -t 3d-asset-server .
docker run -p 8787:8787 3d-asset-server

使用 Web UI

启动服务器后，打开 http://localhost:8787。托管版本位于 3d.shep.bot。

使用搜索页面输入查询，选择资源类型，将结果限制为免费资源，要求支持直接下载，或选择特定提供商。搜索状态会保存在 URL 中，因此可以将诸如 /search?q=sunset&type=hdri&free=true 的查询加入书签或分享。

打开结果的详情面板，查看其许可、作者、格式、多边形数量、标签、可用分辨率和估算文件大小。然后你可以选择格式和分辨率、下载资源、复制 curl 命令，或复制面向代理的提示词。

托管网站还提供文档、OpenAPI 参考、源信息和自托管指南。面向代理的文件包括 /AGENTS.md、/llms.txt、/llms-full.txt 和 /openapi.json。

使用 HTTP API 搜索

主要搜索端点是 GET /v1/search。提供查询，并可选用资源类型、是否免费、是否支持直接下载、提供商、结果数量限制和偏移量等筛选条件。

curl 'http://localhost:8787/v1/search?q=brick+wall&type=material&free=true&limit=5'

缩略后的响应包含排序后的结果和提供商报告：

{
  "query": "brick wall",
  "results": [
    {
      "id": "polyhaven:brick_wall_001",
      "title": "Brick Wall 001",
      "type": "material",
      "license": {
        "name": "CC0",
        "commercialUse": true,
        "attributionRequired": false
      },
      "resolutions": ["1k", "2k", "4k", "8k"],
      "downloadable": true
    }
  ],
  "providers": [
    {
      "provider": "polyhaven",
      "status": "ok",
      "count": 5
    }
  ]
}

使用 GET /v1/providers 获取提供商目录，使用 GET /v1/assets/{provider}:{id} 获取完整资源详情，并使用 GET /v1/assets/{id}/files 查看由格式和分辨率选择的文件。

通过 API 下载

对于单文件资源，下载端点会重定向到源文件。对于多文件资源，它会以流的形式传输包含资源及其配套文件的 zip：

curl -OJ 'http://localhost:8787/v1/assets/polyhaven:WoodenChair_01/download?format=gltf&resolution=1k'

API 还提供 /health、/openapi.json、/v1/catalog 和 /v1/stats。目录提供提供商和资源数量，统计端点则报告使用情况和来源健康状况。

使用 CLI

构建后的 CLI 支持 HTTP 服务、通过标准输入输出运行 MCP，以及从终端执行搜索。

node dist/cli.js search "low poly tree" --type model --free --limit 5

结果会显示评分、资源类型、免费状态、提供商标识符、标题和来源 URL。结果之后会打印提供商状态，以便查看哪些站点成功响应，哪些站点仅提供了链接。

要通过 CLI 运行完整的本地服务，请使用：

3d-asset-server serve

要通过标准输入和输出启动 MCP 服务器，请使用：

3d-asset-server mcp

将 MCP 与 AI 助手结合使用

MCP 允许 AI 助手搜索资源、查看资源详情，并下载获准的文件。可用工具包括：

• search_assets 使用查询、类型、提供商、许可证、可下载性和分页筛选器搜索资源提供商。
• get_asset 返回元数据、许可证信息、可用格式和分辨率，以及下载所选资源时将获取的文件。
• download_asset 将资源及其配套文件保存到配置的目录，并解压受支持的 zip 资源包。
• list_providers 描述每个提供商、其资源类型、定价、许可证和直接下载支持情况。

Claude Code

配置 Claude Code 以启动本地 MCP 进程，并将文件保存到当前项目的资源目录：

claude mcp add 3d-assets -e ASSET_DOWNLOAD_DIR="$PWD/assets" -- node /path/to/3d-asset-server/dist/cli.js mcp

Claude Desktop、Cursor 及其他 Stdio 客户端

将服务器条目添加到客户端的 MCP 配置中：

{
  "mcpServers": {
    "3d-assets": {
      "command": "node",
      "args": ["/path/to/3d-asset-server/dist/cli.js", "mcp"],
      "env": {
        "ASSET_DOWNLOAD_DIR": "/path/to/your/game/assets"
      }
    }
  }
}

远程 MCP

托管服务器支持可流式传输的 HTTP MCP：

claude mcp add --transport http 3d-assets https://3d.shep.bot/mcp

对于自行托管的服务器，请将客户端指向 http://<host>:8787/mcp。默认禁用远程 HTTP 下载，因为下载会将文件写入服务器磁盘。在此模式下，get_asset 会返回直接文件 URL 和 bundle zip URL。仅当服务器需要存储文件时，才设置 ASSET_SERVER_HTTP_DOWNLOADS=true。

了解下载行为

未指定格式时，服务器会优先选择实用的游戏和 Web 格式。模型优先使用 glb，其次是 gltf、fbx、obj 和 blend。HDRI 优先使用 hdr，其次是 exr。材质优先使用图像贴图或 zip，纹理优先使用 jpg、png、zip 或 exr，资源包则以解压后的 zip 文件形式下载。

默认分辨率为最接近 2K 的可用选项。配套文件会保留其相对路径，因此 glTF 文件无需手动重新整理即可找到其二进制文件和纹理文件。

assets/
└── polyhaven-WoodenChair_01/
    ├── WoodenChair_01_2k.gltf
    ├── WoodenChair_01.bin
    └── textures/
        ├── WoodenChair_01_diff_2k.jpg
        ├── WoodenChair_01_nor_gl_2k.jpg
        └── WoodenChair_01_arm_2k.jpg

下载器只获取公开的 http 和 https URL，拒绝私有地址和回环地址，强制执行可配置的大小限制，并拒绝诸如 ../ 的不安全归档路径。它不会绕过登录页面、结账流程或防盗链保护。

配置

在启动服务器前设置环境变量，以控制其网络地址、提供商、下载、安全性和性能。

• PORT 和 HOST 控制 HTTP 绑定地址。默认值分别为 8787 和 0.0.0.0。
• ASSET_SERVER_PROVIDERS 接受逗号分隔的列表，例如 polyhaven,ambientcg,kenney。
• ASSET_DOWNLOAD_DIR 将默认的 MCP 下载目录从 ./assets 更改为其他目录。
• ASSET_SERVER_MAX_DOWNLOAD_BYTES 设置单次下载的大小限制，默认值为 2 GiB。
• ASSET_SERVER_PROVIDER_TIMEOUT_MS 和 ASSET_SERVER_HTTP_TIMEOUT_MS 调整提供商和 HTTP 超时时间。
• ASSET_SERVER_CACHE_TTL_MS 控制内存中 HTTP 缓存的持续时间。
• BLENDERKIT_API_KEY 可解锁 BlenderKit 方案资源和已购买资源。
• NODE_USE_ENV_PROXY=1 使 Node 使用已配置的 HTTPS_PROXY。

身份验证和速率限制

设置 ASSET_SERVER_API_KEY 以保护 /v1/* 和 /mcp。客户端可以将密钥作为 Bearer 令牌、x-api-key 标头或 api_key 查询参数发送。请谨慎使用查询参数，因为浏览器历史记录和服务器日志可能会包含这些参数。

默认情况下启用速率限制：每个客户端在 60 秒窗口内最多 120 个请求。配置 ASSET_SERVER_RATE_LIMIT 和 ASSET_SERVER_RATE_LIMIT_WINDOW，或将限制设置为 0 以禁用速率限制。

代理和提供商故障排查

CGTrader 可能会屏蔽云服务和数据中心的 IP 地址。从家庭网络连接通常可以正常使用；在服务器上使用时，请配置代理并设置 NODE_USE_ENV_PROXY=1。抓取型提供商也可能更改其 HTML。如果某个来源出现故障，其他来源仍会继续返回结果；运行 npm run test:live 可以检查提供商是否可用。

高级监控

将 METRICS_PORT 设置为在单独的端口上公开 Prometheus 指标。服务器会记录搜索、提供商请求、下载、资源查看、MCP 工具调用、HTTP 请求和页面查看的有界标签指标。它还会记录结构化搜索事件，但不会记录 IP 地址、密钥或 Cookie。

如果配置了 PROMETHEUS_URL，统计信息端点可以报告跨副本的汇总数据。未配置时，统计信息仅代表当前进程自上次重启以来的数据。

推荐工作流程

1. 使用描述性查询进行广泛搜索，例如 sunset、low poly tree 或 brick wall。
2. 按资源类型、是否免费、是否支持直接下载或选定的提供商进行筛选。
3. 查看许可证、署名要求、格式、分辨率和文件列表。
4. 为你的游戏或网站选择合适的格式和分辨率。
5. 下载资源；如果提供商不允许直接下载，则复制其来源链接。
6. 将所有必需的署名和许可证文件与项目一同保存。

结论

3d-asset-server 将分散的资源发现整合为单一工作流程。其 Web UI、HTTP API、CLI 和 MCP 工具支持搜索多个提供商、比较许可证和下载信息，并获取可直接使用的模型、纹理、HDRI 和资源包。你可以先使用 Node.js 或 Docker 在本地启动，然后为生产部署配置提供商、身份验证、下载路径、速率限制和监控。