# 部署与运行隔离

在服务端托管运行时，管理身份、并发、持久化和取消后的资源回收。

## 最小部署单元

一个服务端工作进程需要 Go 宿主、bridge 依赖、运行时可执行文件、工作目录以及模型访问配置。Bridge 是库，不是独立的多租户服务；它不替你建立 HTTP 认证、任务队列或用户隔离。

```text
已认证的用户请求
  → 宿主校验用户和任务范围
  → 分配工作目录与运行身份
  → NewSession / ResumeSession
  → 单一读取者消费消息
  → 保存结果并关闭或保留会话
```

先让一个工作进程可靠地完成一条任务，再增加队列和并发。不要在每次轮询进度时新建运行时进程。

## 文件与用户身份

为用户选择独立的工作目录，校验上传文件和输出路径。工作目录本身不是隔离机制：同一 OS 身份下的进程可能仍能访问其他可读文件。需要操作系统权限、容器或其他实际隔离措施限制访问。

Bridge 只传递 SandboxSettings，不执行沙箱。配置必须由运行时在目标平台落实，不能只因为 Go 类型里有 Enabled 就对用户宣称已隔离。Go 自定义工具在宿主中运行，仍要执行自己的授权检查。

## 进程与运行时来源

运行时路径由可信部署配置提供，不能直接使用用户提交的命令。nxs 需来自发布包或授权来源；固定版本并记录实际部署的二进制来源。Claude Code 的安装和模型访问遵循其自身部署方式。

同一 OS 身份下，bridge 默认管理进程信号。跨身份启动时，宿主需要通过 WithProcessSignalHandler 提供可信的信号边界，并验证 PID 归属后再转发，避免给其他用户进程发送信号。

## 配置与秘密

将模型凭据和 MCP 凭据保存在部署环境的秘密配置中。不要把它们放入任务提示词、前端响应或普通诊断日志。只为进程提供所需环境，不把完整服务环境传给不相关的工具。

内联或自动生成的 MCP 配置会通过受限参数文件传递，减少命令行参数暴露。宿主仍需保护持久目录、备份和诊断输出。

## 并发和背压

每个 Session 使用一个输出读取者。并发用户使用独立 Session；同一会话内的后续任务应由宿主排队。输出不能无限堆积：慢客户端的进度可以合并，最终结果和失败状态应持久保存。

限制同时运行的任务数，设置执行 deadline 和关闭期限。遇到超时先发中断并确认状态，随后清理资源。长时 control 的取消需要响应同一请求身份，不能无限重试未知结果的操作。

## 恢复与发布

恢复需要 Session ID、同一数据位置以及对应运行身份。备份时保存必要会话文件与业务关联信息，但不要把可恢复会话误当作运行中的进程快照。

升级 bridge 或运行时后，至少验证只读任务、权限拒绝、自定义工具、流式终态、取消清理和会话恢复。只有使用的能力得到验证，才把工作进程切换到新版本。

## 服务验收

验收不仅检查进程能启动，还要检查另一用户无法恢复不属于自己的会话、审批页面关闭不会默认放行、客户端断开后任务按策略停止或继续、工作进程退出后没有遗留子进程。

这些是宿主的部署职责。运行时协议边界见[运行时与能力](/docs/sdk-runtimes)，故障记录见[错误处理](/docs/sdk-errors)。