03 本地运行与调试

本章目标

本章讲如何在 Windows 开发机上运行 RhinoCompute，并确认服务是否可用。生产部署请看 06 Windows/IIS 生产部署。

官方本地调试指南建议访问以下端点确认服务：

http://localhost:6500/version
http://localhost:6500/healthcheck
http://localhost:6500/activechildren
http://localhost:6500/sdk

如果 /sdk 能打开，说明 Compute 已经列出可调用的 SDK 方法和扩展端点。

rhino.compute 支持多个命令行参数。常用项如下：

示例：

.\rhino.compute.exe --port 6500 --childcount 2 --spawn-on-startup --apikey local-dev-key

compute.geometry 是实际加载 Rhino.Inside 的进程。直接调试它可以帮助定位几何端点、Grasshopper 求解、插件加载问题。

常见启动参数：

.\compute.geometry.exe --port:8081 --apikey:local-dev-key

注意：在完整服务链中，通常由 rhino.compute 负责启动和管理多个 compute.geometry 子进程。直接启动 compute.geometry 更适合低层调试。

如果服务配置了 API Key，POST 请求必须携带 header：

RhinoComputeKey: local-dev-key

PowerShell 测试示例：

$headers = @{ RhinoComputeKey = 'local-dev-key' }
Invoke-WebRequest -Uri 'http://localhost:6500/healthcheck' -UseBasicParsing

/healthcheck 是 GET，一般不验证 API Key。真正验证 POST 时，应调用一个需要 POST 的几何或 Grasshopper 端点。

本地调试时优先看控制台输出。部署或后台运行时查看日志目录。

如果需要详细日志：

[System.Environment]::SetEnvironmentVariable('RHINO_COMPUTE_DEBUG', 'true', 'Machine')

然后重启 Compute。

日志中要重点观察：

现象	可能原因	处理方式
访问 `/version` 失败	服务未启动或端口不对	看控制台端口，检查端口占用。
启动时报授权错误	Rhino 未授权或服务器环境缺 `RHINO_TOKEN`	本地启动 Rhino 完成授权；服务器配置 core-hour token。
Hops 调用失败但 `/healthcheck` 正常	Grasshopper 未加载、定义错误、插件缺失	查看 Compute 控制台和 Hops 组件错误。
POST 返回 401	缺 `RhinoComputeKey` 或 key 不匹配	检查服务端 `RHINO_COMPUTE_KEY` 和客户端 header。
大模型或大几何请求失败	请求体超过限制	调整 `RHINO_COMPUTE_MAX_REQUEST_SIZE` 并重启。