====== 02 环境准备与版本选择 ======

===== 先选 Rhino 版本 =====

Compute 源码分支必须与安装的 Rhino 主版本匹配：

^ 已安装 Rhino ^ 建议源码分支 ^
| Rhino 8 | ''8.x'' |
| Rhino 7 | ''7.x'' |

如果 Rhino 版本和 Compute 分支不匹配，常见结果是编译失败、启动时找不到 Rhino 组件、Grasshopper 插件加载异常，或者运行时返回 500。

===== Windows 本地开发环境 =====

本地开发和调试建议使用 Windows 工作站：

  * Windows 10/11 或兼容的 Windows 开发机。
  * Visual Studio 2022，用于打开解决方案、编译、断点调试。
  * Git，用于拉取 ''mcneel/compute.rhino3d''。
  * Rhino 7 或 Rhino 8，并已启动过一次以完成授权。
  * 可选：Python、Node.js、.NET SDK，用于测试客户端调用。

官方本地调试指南把本地开发定位为 Windows-only。虽然 2026 年的 Compute 指南目录已经出现 Linux Server 内容，但 Linux 版目前仍被标注为 WIP，不应把它当成稳定生产主线。

===== 获取源码 =====

<code bash>
git clone https://github.com/mcneel/compute.rhino3d.git
cd compute.rhino3d
git checkout 8.x
</code>

如果你使用 Rhino 7：

<code bash>
git checkout 7.x
</code>

当前工作区已有两个相关目录：

<code>
E:\tmp\compute.rhino3d
E:\tmp\compute.rhino3d-7.x
</code>

教学时可以把它们作为 Rhino 8 和 Rhino 7 分支对照材料。

===== 解决方案结构 =====

源码中最需要关注的目录：

^ 路径 ^ 说明 ^
| ''src\rhino.compute'' | 对外服务入口，管理子进程、认证、反向代理。 |
| ''src\compute.geometry'' | 真正加载 Rhino.Inside 并执行几何、Grasshopper、自定义端点。 |
| ''src\hops'' | Grasshopper Hops 组件项目。 |
| ''src\ghhops-server-py'' | Python Hops server 示例和库。 |
| ''script\production'' | Windows/IIS 生产部署脚本。 |

===== 环境变量速查 =====

^ 环境变量 ^ 作用 ^ 常见默认值或说明 ^
| ''RHINO_COMPUTE_KEY'' | API Key。配置后 POST 请求必须带 ''RhinoComputeKey'' header。 | 空值表示不启用认证，生产环境不建议为空。 |
| ''RHINO_TOKEN'' | Core-Hour Billing token。服务器计费授权使用。 | 生产服务器需要。 |
| ''RHINO_COMPUTE_TIMEOUT'' | 服务端请求超时秒数。 | 常见默认值 100 秒。 |
| ''RHINO_COMPUTE_MAX_REQUEST_SIZE'' | 最大请求体大小，单位 byte。 | 常见默认 52428800，约 50 MB。 |
| ''RHINO_COMPUTE_LOG_PATH'' | 日志目录。 | 本地和部署环境可不同。 |
| ''RHINO_COMPUTE_LOG_RETAIN_DAYS'' | 日志保留天数。 | 常见默认 10。 |
| ''RHINO_COMPUTE_DEBUG'' | 是否开启详细日志。 | 调试时设为 ''true''。 |
| ''RHINO_COMPUTE_LOAD_GRASSHOPPER'' | 启动时是否加载 Grasshopper。 | 默认 true；纯几何端点可设 false 加快启动。 |
| ''RHINO_COMPUTE_BLOCK_PRIVATE_URLS'' | 阻止服务端抓取私有、回环、链路本地地址。 | 对公网部署建议 true。 |

Windows 设置机器级环境变量示例：

<code powershell>
[System.Environment]::SetEnvironmentVariable('RHINO_COMPUTE_KEY', 'change-me-to-a-secret', 'Machine')
[System.Environment]::SetEnvironmentVariable('RHINO_COMPUTE_DEBUG', 'true', 'Machine')
</code>

设置后需要重启相关进程。IIS 部署时通常还需要回收应用池或重启 IIS。

===== 客户端依赖 =====

Python：

<code bash>
pip install rhino3dm compute-rhino3d
</code>

JavaScript / Node.js：

<code bash>
npm install rhino3dm compute-rhino3d
</code>

.NET：

  * 安装 ''Rhino3dm'' NuGet 包。
  * 安装 ''Newtonsoft.Json'' NuGet 包。
  * 引入官方 ''RhinoCompute.cs'' 客户端源文件或使用项目中已有封装。

===== 版本兼容原则 =====

  * Rhino 主版本、Compute 分支、Grasshopper 插件版本应保持一致。
  * 客户端库版本应与服务端能力接近，尤其是调用新 API 或 Rhino 8 特性时。
  * 服务器端安装第三方 Grasshopper 插件时，要保证插件版本、依赖、授权和加载路径都能在无界面环境中工作。
  * 不要在生产服务器上随意自动更新 Rhino 或插件，先在同版本测试环境验证。

===== 本章检查点 =====

  * 你是否已经确认 Rhino 主版本和 Compute 分支一致？
  * 你是否知道 API Key 是 ''RHINO_COMPUTE_KEY''，客户端 header 是 ''RhinoComputeKey''？
  * 你是否能解释哪些环境变量影响超时、请求体大小和日志？

===== 参考资料 =====

  * [[https://developer.rhino3d.com/en/guides/compute/development/|Running and Debugging Compute Locally]]
  * [[https://developer.rhino3d.com/guides/compute/compute-python-getting-started/|Calling Compute with Python]]
  * [[https://developer.rhino3d.com/guides/compute/compute-javascript-getting-started/|Calling Compute with JavaScript]]
  * [[https://developer.rhino3d.com/guides/compute/compute-net-getting-started/|Calling Compute with .NET]]