====== 03 本地运行与调试 ======

===== 本章目标 =====

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

===== 编译前检查 =====

  * Rhino 已安装并能正常启动。
  * Rhino 已完成授权或已登录 Cloud Zoo。
  * Compute 源码分支与 Rhino 主版本一致。
  * Visual Studio 2022 已安装必要的 .NET 桌面开发组件。
  * 没有旧的 ''rhino.compute.exe'' 或 ''compute.geometry.exe'' 占用端口。

===== 用 Visual Studio 启动 =====

  - 打开源码目录下的解决方案文件。
  - 设置配置为 ''Debug''。
  - 编译解决方案。
  - 将 ''rhino.compute'' 设置为启动项目。
  - 启动调试。
  - 等待控制台完成 Rhino、Grasshopper、插件加载。

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

<code>
http://localhost:6500/version
http://localhost:6500/healthcheck
http://localhost:6500/activechildren
http://localhost:6500/sdk
</code>

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

===== 命令行启动参数 =====

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

^ 参数 ^ 说明 ^
| ''--port 6500'' | 指定 rhino.compute 监听端口。 |
| ''--childcount 4'' | 管理多少个 ''compute.geometry'' 子进程。 |
| ''--idlespan 3600'' | 子进程空闲多久后关闭，单位秒。 |
| ''--spawn-on-startup'' | 服务启动时立即启动子进程。 |
| ''--timeout 100'' | 请求超时时间，单位秒。 |
| ''--max-request-size 52428800'' | 请求体大小限制，单位 byte。 |
| ''--apikey your-key'' | 为当前启动会话设置 API Key。 |
| ''--load-grasshopper false'' | 启动时不加载 Grasshopper，纯几何服务可用。 |
| ''--block-private-urls'' | 阻止服务端访问私有/回环/链路本地地址。 |

示例：

<code powershell>
.\rhino.compute.exe --port 6500 --childcount 2 --spawn-on-startup --apikey local-dev-key
</code>

===== 单独理解 compute.geometry =====

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

常见启动参数：

<code powershell>
.\compute.geometry.exe --port:8081 --apikey:local-dev-key
</code>

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

===== 认证测试 =====

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

<code>
RhinoComputeKey: local-dev-key
</code>

PowerShell 测试示例：

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

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

===== 日志观察 =====

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

如果需要详细日志：

<code powershell>
[System.Environment]::SetEnvironmentVariable('RHINO_COMPUTE_DEBUG', 'true', 'Machine')
</code>

然后重启 Compute。

日志中要重点观察：

  * Rhino 版本和 Compute 版本。
  * RhinoCore 是否成功启动。
  * Grasshopper 是否加载。
  * 第三方插件是否加载。
  * 子进程端口和数量。
  * 请求路径、HTTP 状态码、异常堆栈。

===== 常见本地问题 =====

^ 现象 ^ 可能原因 ^ 处理方式 ^
| 访问 ''/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'' 并重启。 |

===== 调试建议 =====

  * 先用 ''/version'' 和 ''/healthcheck'' 确认服务活着，再测业务端点。
  * 先在本机无 API Key 跑通最小调用，再加 API Key。
  * 如果涉及 Grasshopper，先在 Rhino/Grasshopper 图形界面内打开定义，确认本地求解无错。
  * 如果涉及第三方插件，先确认插件能在普通 Rhino 中加载，再确认无界面 Compute 中加载。
  * 不要一开始就把 IIS、HTTPS、反向代理、业务系统全部接上；先让 Compute 自身可观测。

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

  * ''/version'' 是否能打开？
  * ''/healthcheck'' 是否返回健康？
  * ''/activechildren'' 是否能看到子进程状态？
  * 配置 API Key 后，错误 key 是否能稳定返回 401？

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

  * [[https://developer.rhino3d.com/en/guides/compute/development/|Running and Debugging Compute Locally]]
  * [[https://developer.rhino3d.com/guides/compute/compute-faq/|Compute FAQ]]