部署边界与运行形态

客户端经过反向代理访问 Server，由 Application 执行授权服务调用
客户端经过反向代理访问 Server，由 Application 执行授权服务调用放大查看

Server 与 Application 运行在能够加载 FastSim 和目标 Provider 的环境中。浏览器、TUI、自动化客户端或 MCP Gateway 可以位于其他进程或机器，只依赖公开协议，不导入仿真器 SDK。

能力发现优先。 客户端应先读取健康、版本、运行状态和 capability 接口，再决定是否显示场景、相机、几何、运动学或控制功能。不同 Run 和 Provider 可用能力不同，客户端不能把所有端点存在等同于本次实例可执行。

生命周期与 generation。 远程 start、pause、reset 和 stop 仍走 Application 生命周期。控制请求与 Operation 绑定当前 run/generation；reset 后客户端必须刷新状态、目标与订阅，不能继续发送旧 generation 的命令。

Server 的部署安全边界包括：

  • 监听地址、认证和反向代理属于部署配置，不应硬编码在 Run。
  • 外部写操作需要明确授权；只读发现不应隐式升级为控制权限。
  • 浏览器不直接加载资产目录或后端对象。
  • 生产部署应限制可信输出根、上传大小、会话和并发操作预算。

Server REST API 从当前插件源码生成方法、路径、处理器和状态信息。具体运行示例位于示例与教程目录，但协议合同以参考页与插件版本为准。

两种部署形态。 固定 Run 适合单个应用或调试：

bash
fastsim-server run.yaml

默认监听 127.0.0.1:8000，使用一个 Uvicorn worker 和一个 FastSim application loop。常驻启动服务则不必预装初始 Run，而是仅开放运维者命名的配置根：

bash
fastsim-server \
  --launch-root examples=/srv/fastsim/runs \
  --browser-origin http://127.0.0.1:8080

常驻模式同一时刻仍只有一个不可变 Run 槽位。客户端通过 launch operation 切换 Run；旧 slot generation 的写请求会被拒绝，避免误控新应用。

发现、状态与异步写操作

bash
curl -sS http://127.0.0.1:8000/health/live
curl -sS http://127.0.0.1:8000/health/ready
curl -sS http://127.0.0.1:8000/api/v1 | jq
curl -sS http://127.0.0.1:8000/api/v1/capabilities | jq

live 只说明 HTTP 进程存活；ready 与 application_opened 说明接纳状态；discovery 公布版本、链接与限制；capabilities 结合当前 authority、启动选项和 Run 能力。只读健康检查不会为了返回成功而打开仿真器。

写操作是异步 Operation。 生命周期和控制提交返回 202 Accepted、operation ID 与 Location。客户端轮询直到 succeeded、failed 或 cancelled。断开 TCP 连接不会自动取消已接纳操作；需要取消时对准确 operation 发送 DELETE。

动态 launch 和物理控制需要 Idempotency-Key。同一个 key 与同一请求返回原 Operation，同一个 key 搭配不同 payload 返回冲突。可替换槽位中的后续写操作还要发送 X-FastSim-Slot-Generation。

可选能力与生产部署

Scene、Frame 和 Geometry 默认不发布，需要 --planning-reads。浏览器低延迟视频使用安装了可选依赖的 WebRTC 模式；快照是明确的另一种媒体选择。未启用时不应导入对应依赖或给仿真热路径增加采样开销。

产物 API 需要运维者设置绝对 --output-root，每个 slot generation 使用隔离子目录。只有白名单内、非隐藏、非临时、非符号链接的正式文件可列出或下载；应在 terminal close 后把插件输出视为最终结果。

生产反向代理边界。 Server 默认回环监听适合由 nginx 等反向代理终止 TLS、限制请求体、连接与来源。--trusted-host 和 --browser-origin 应使用准确值；不要把通配监听、任意 CORS 和写权限一起暴露。

认证、速率限制、网络 ACL 与证书属于部署层；Application authority、slot generation、idempotency 和 Operation 属于协议层。两层都需要，不能用其中一层替代另一层。

客户端状态机。 客户端应先发现版本与限制，再读取 launch/run 与 capability；发起写请求后保存 operation ID；reset 或 slot 替换后刷新 generation、targets 和订阅；断线重连时用服务器事实恢复，而不是假设上一次请求失败。

验收清单

  • health、discovery、capability 与 OpenAPI 可访问且不会意外打开后端；
  • 写操作异步返回，幂等与 stale slot 请求行为正确；
  • 当前 authority 下未授权端点明确拒绝；
  • reset/replace 后旧客户端不能控制新 generation；
  • WebSocket/媒体在断线与 close 后释放订阅；
  • 输出只暴露当前允许 generation 的已提交文件；
  • 代理层限制、日志和 TLS 已验证。

准确端点、请求模型和状态码始终以Server REST API为准。