沙箱（Sandbox / SandrPod）总览

License 提示

员工 PC 沙箱需要 sandbox.user_pc (PROFESSIONAL)；企业专用沙箱需要 sandbox.dedicated (ENTERPRISE)；AI 决策审计需要 sandbox.decision_audit (ENTERPRISE)；个人 MCP 需要 mcp.personal (STANDARD)。

Sira AI 的"沙箱"是 DeepAgents 智能体执行 Skill 脚本时使用的隔离环境。它能让 AI 真的去：

读 / 写一个目录里的文件
执行 shell 命令
打开 PTY 终端
同时被员工（通过原生权限弹框）和管理员（通过决策审计日志）实时监控

底层基于独立部署的 SandrPod（一个 Go 项目），Sira 仅持有它的连接配置，不打包它的运行时。

三种沙箱模式

DeepAgents 编排器在 deep_agents_config.backend_config.mode 中选择沙箱归属：

模式	何时选	归属	约束
`user_sandbox`	大多数对话场景：每位员工自己装一台沙箱	1:1（每用户每组织最多 1 台未撤销）	数据库 `partial unique` 索引保证唯一性
`dedicated_sandbox`	企业共享一台高配机器（如 GPU 跑 RAG）	企业级（`owner_type='corp'`）	编排器配置中指定 `sandbox_id`；License 需 `sandbox.dedicated`
`agent_direct`（旧版）	编排器在 `backend_config` 里直接写 `api_url` / `api_key`	不入库	不健康检查、不审计；通常仅本地调试用

离线即拒绝

当托管模式（user / dedicated）下沙箱不在线时，引擎抛 SandboxOfflineError 直接失败，不会自动降级。AI 会在对话里给员工返回一段友好的安装 / 排错提示（携带短链）。

涉及的数据表

表	角色
`corp_sandrpod_config`	每个组织一行：sandrpod 服务端 URL、token（Fernet 加密）、默认镜像
`sandboxes`	沙箱实例：`sandbox_name`（全局唯一）、`owner_type`、`status`、心跳时间
`sandbox_enrollments`	安装注册票据：`jti` 抗重放、10 分钟 TTL
`sandbox_audit_log`	平台动作审计：注册 / 撤销 / 路由 / PTY 打开等
`sandbox_decision_events`	AI 决策审计：员工 PC 上每次路径访问 / 命令执行的 allow/deny

这两条审计流不要混淆：
sandbox_audit_log 是平台/管理员行为
sandbox_decision_events 是 AI 在沙箱里实时被权限网关裁决的行为，量级大很多倍

管理员 Sandboxes 页面

路径：/agent-system/sandboxes，含 7 个标签：

标签	谁能看	内容
我的沙箱	全员	单槽位 UI——没装显示"添加我的电脑"，已装显示状态/操作（刷新状态 / 调试 / 解绑）
我的 MCP	全员	当前用户在自己沙箱上配的个人 MCP server 状态（在线/部分在线/离线/未配置 + 每 server 卡片 + 工具数 + 立即刷新，详见个人 MCP）
专用沙箱	全员读 / 管理员写	企业级 (corp) 沙箱列表，"+ 新建" 仅管理员；物理机类型支持引导安装（见下方）
全部	管理员	全企业沙箱总览（不含已撤销）
平台审计	管理员	查 `sandbox_audit_log`
AI 决策审计	管理员	查 `sandbox_decision_events`（详见决策审计）
配置	管理员	配置 sandrpod 服务端 URL / token（详见下方）

每个沙箱详情可看：状态、最后心跳、所有者、OS / 架构 / 主机名、work_dir，并提供文件浏览、单次命令执行、浏览器内 PTY 终端（受权限网关约束）。

物理机专用沙箱：create-first / bind-later 引导安装

agent_direct（物理机直连）类型的专用沙箱走"先建条目、后绑机器"的两段式流程：

create-first：管理员在「专用沙箱」Tab 新建一个物理机类型沙箱条目——此时还没有真实机器连上。创建成功后立即弹出引导安装对话框（生成绑定票据 + 一行安装命令）。
bind-later：把安装命令拿到目标物理机上执行；机器回连后，沙箱条目从"未绑定"变为在线。

未绑定的专用沙箱卡片上保留**「引导安装」** 入口，随时可重新打开对话框拿绑定票据 / 安装命令。

部署前置：配置 SandrPod 连接

在前端"配置"标签里填入：

字段	说明
`api_url`	Sira 后端 → SandrPod 的内部地址（容器网络可达）
`agent_facing_url`	员工 PC → SandrPod 的对外地址（Docker 开发环境的 `host.docker.internal` 员工那边访问不到，所以两个 URL 通常不同）
`api_token`	SandrPod 的 admin token（Fernet 加密落库）
`default_image`	docker 类型沙箱的默认镜像（仅 docker 模式用到）
`enabled`	关闭时整个组织的沙箱功能停摆

Token 加密密钥优先取环境变量 SANDBOX_TOKEN_ENC_KEY，未设置则派生自 settings.secret_key 的 SHA-256。

后端必须设置环境变量 SIRA_PUBLIC_BASE_URL——它用来构造员工安装一键命令、错误提示中的安装短链。如果不设置，安装 URL 可能指向只在容器网络内有效的地址。

跨渠道用户解析

不同渠道（企微 / 飞书 / 微信客服 / Web / OpenAI API）的用户 ID 都会通过 users.external_ids[platform_key] 映射回同一个 Sira 用户，从而找到这个用户对应的 user_sandbox。

新增渠道不需要改用户解析代码——只需在 channel_platform_keys.PlatformKey 加一项即可。

自动建档

当一个未注册的渠道用户首次和 AI 对话时，平台会自动建档生成一个占位 Sira 用户（provider="auto_provisioned"，邮箱后缀 .invalid 永不投递），这样 AI 不会因为"用户没注册"而无法响应。员工后续装沙箱时自然挂到这个占位用户上。

错误如何反馈给员工

DeepAgents 执行抛 SandboxRoutingError 时，平台会在用户对话里返回一段渠道友好的提示。例如最常见的"我没有沙箱"：

您还没有安装 Sira 沙箱。

点击下方链接在 10 分钟内完成一键安装：
https://your-sira/sandbox-install?token=eyJhbGciOi...

安装后这条消息您可以重新发送。

token 是即时签发的 10 分钟入门 JWT（详见安装指南）。这条短链会被节流，避免每条消息都换一个新的注册票。

心跳与状态机

沙箱状态：pending → online → offline → revoked

pending：员工已下发安装指令但 agent 还没回连
online：agent 正常心跳（默认 30 秒同步一次）
offline：心跳超时（PC 关机、断网等）
revoked：被撤销，不能再被路由到

后端有一个 SandboxHeartbeatService 后台线程每 30 秒同步一次状态，确保管理面板实时反映在线情况。

子页面

员工 PC 沙箱：安装指南 —— 一键安装 / 撤销 / 自助卸载
权限网关 —— 三种权限模式 / 默认硬锁路径 / 弹框机制
AI 决策审计 —— 实时记录 AI 在沙箱里每个动作的 allow/deny
个人 MCP：员工指南 —— 员工怎么写 mcp.json / 看 UI 状态 / 排查 npx 问题
个人 MCP：管理员指南 —— IT 部署前置 / DB schema / 故障排查手册 / 合规边界

沙箱（Sandbox / SandrPod）总览 ​

三种沙箱模式 ​

涉及的数据表 ​

管理员 Sandboxes 页面 ​

物理机专用沙箱：create-first / bind-later 引导安装 ​

部署前置：配置 SandrPod 连接 ​

跨渠道用户解析 ​

错误如何反馈给员工 ​

心跳与状态机 ​

子页面 ​

相关文档 ​