2.6 沙箱管理与企业配置

端用户的沙箱章节 讲的是"我自己的电脑装一个沙箱"。本章讲管理员视角:配置企业级 sandrpod 连接、创建专用沙箱、查阅审计日志、复核 AI 决策。

进入路径:左侧主导航 → 沙箱(/agent-system/sandboxes)。 权限:Tab 不同权限不同(见下表)。

---

2.6.1 页面 Tab 结构

整页 7 个 Tab(顺序如下),按权限可见性:

Tab	可见者	内容
我的沙箱	所有用户	个人沙箱面板(同 端用户章节)
我的 MCP	所有用户	个人沙箱内的 MCP 工具面板(组件 PersonalMcpPanel)
专用沙箱	所有用户(管理员可创建)	组织共享的专用沙箱
全部	管理员	全组织 / 全平台所有沙箱(scope=all)
平台审计	管理员	沙箱平台操作审计(分配、撤销、路由)
AI 决策审计	管理员	AI 在沙箱里的决策日志(路径访问、命令执行、PTY)
配置	管理员	SandrPod 企业级配置

📝 管理员判定依据 currentOrganization.roles 或 user.roles 是否包含:admin / super_admin / owner / 管理员 / 超级管理员 / 组织拥有者。

---

2.6.2 专用沙箱

用途:为编排器准备的"企业共享沙箱",绑定到编排器的 deep_agents_config.backend_config.sandbox_id。所有用户共享同一个沙箱(典型场景:跑共享数据库查询、批处理任务)。

表格列

列	说明
名称	沙箱标识
所有者	创建者(管理员)
状态	🟢 在线 / 🔴 离线 / 🟡 等待安装
类型	dedicated
设备	OS + 主机名
创建时间
操作	重新生成 token、卸载、详情

创建专用沙箱

入口:Tab 顶部「创建专用沙箱」按钮。

字段:

字段	必填	说明
名称	✓	内部标识
显示名称	✓	UI 名称
描述
安装目标	✓	单选:管理员电脑 / 企业服务器 / 其他指定机

提交后生成 enrollment JWT,流程同 一键安装,只是 scope 为 dedicated 而不是 user。

绑定到编排器

创建后,编辑一个 DeepAgents 编排器:

1. 进入 编排器设计器
2. Backend Config 选 sandpod
3. sandbox_id 下拉选刚创建的专用沙箱

⚠️ 一个专用沙箱可以被多个编排器共享。注意资源争用 — 一台机器同时跑 10 个 AI 任务可能不堪重负。

物理机专用沙箱(引导安装)

(2026-06-14 起)除了云端/容器型专用沙箱,还支持把一台物理机作为专用沙箱(agent 直连)。流程:

1. 「创建专用沙箱」对话框 → 类型选 物理机(agent 直连)(agent_pc)
2. 点 创建
3. 在该沙箱上点 「引导安装」 按钮 → 生成绑定票据 + 一行安装命令
4. 复制安装命令,在目标物理机上运行
5. 等待该物理机心跳上线(沙箱状态变为 🟢 在线)
6. 编排器即可以「专用沙箱」模式绑定它(同上「绑定到编排器」)

💡 未绑定的专用沙箱也有「引导安装」入口 — 先创建空壳沙箱,稍后再在目标物理机执行引导安装即可。

---

2.6.3 全部 Tab

仅管理员可见。展示当前组织(或 super_admin 看全平台)所有沙箱:

• 用户型(每用户最多 1 个)
• 专用型
• agent_direct 型(编排器直接配置的特殊沙箱)

表格列同专用沙箱 Tab,多一列所属用户(用户型显示为用户邮箱,专用型显示为「共享」)。

用途:

• 看哪些用户已经装好沙箱
• 看离线超过 N 天的沙箱(可考虑回收)
• 跨组织资源审视(super_admin)

---

2.6.4 平台审计 Tab

仅管理员可见。记录沙箱平台操作:

• 创建 enrollment(谁给谁生成了注册链接)
• 沙箱激活(谁在哪台机器装好了)
• 撤销 token
• 卸载
• 路由请求(哪个编排器路由到哪个沙箱)

ℹ️ 这个流和 行为审计 主流是分开的,但内容互补 — 沙箱平台审计更具体到 sandrpod 协议层。

---

2.6.5 AI 决策审计 Tab

这是 Sira 沙箱体系的核心审计能力。

记录什么:AI 在沙箱里做出的每一个具体决策 — 想读什么路径、想执行什么命令、想启动什么 PTY,以及最终是被允许还是拒绝。

数据来源

• 每个 sandrpod-agent 在本机写 NDJSON 到 ~/.sandrpod/audit/active.log(8MiB 滚动)
• 每 30 秒批量上传到 POST /api/agent-system/sandboxes/audit/decisions/batch
• 后端存到 sandbox_decision_events 表
• 前端通过 GET /api/agent-system/sandboxes/audit/decisions 查询

表格视图

列	说明
时间	决策发生时间
沙箱	沙箱名 + 所属用户
决策源	path_access / exec / pty / network / clipboard / ...
详情	简述(如:read ~/Documents/budget.xlsx)
决策	🟢 允许 / 🔴 拒绝 / 🟡 询问后允许
来源 AI	哪个 Agent / Orchestrator / Application 触发

筛选器

• 沙箱:全部 / 指定沙箱
• 决策源:path_access / exec / pty / network / ...
• 决策结果:全部 / 仅允许 / 仅拒绝

行点击 → 详情 Drawer

字段	说明
完整时间戳	含毫秒
Event ID	唯一标识,UNIQUE 用于幂等
沙箱完整信息	sandbox_id + name + 主机名 + OS
决策类型
详情完整数据	路径 / 命令 / 参数
决策	+ 拒绝原因(如适用)
触发链路	Application → Orchestrator → Agent → SubAgent → 此决策
Session ID	对话上下文
User	当前请求的发起用户

用法示例

场景 1:为什么 AI 没读到我的文件?

筛选:沙箱=张三的沙箱、决策=拒绝 按时间倒序,找到刚才那次决策 → 看拒绝原因(可能是路径在硬锁列表 / 用户在 prompt 弹窗点了拒绝)

场景 2:AI 是否在乱跑命令?

筛选:决策源=exec 浏览近期的所有命令 → 看是否合理。 异常命令(rm -rf /、curl ... | sh 这类)即使被允许也要警惕。

场景 3:某个 deny 是不是该改成 allow?

去 端用户章节 提到的本机权限设置页,把该路径加入"总是允许"。下次同决策会自动通过。

红色高亮

deny 行左边框红色且优先排序在顶部,方便快速扫到异常。

---

2.6.6 配置 Tab

仅管理员可见。配置企业级 sandrpod 连接参数。

字段

字段	必填	说明
api_url	✓	sandrpod-server 的管理 API URL,如 https://sandrpod.example.com:8443/api/v1
agent_facing_url	✓	agent 反向连接用的 URL,如 wss://sandrpod.example.com:8443/agent
corp_token	✓	企业 token,用于和 sandrpod-server 互信
默认权限模式		off / prompt(推荐) / strict — 影响新装沙箱的初始模式
决策审计开关		启用后才上传审计批次
心跳间隔(秒)		默认 60
离线超时(秒)		默认 300,超过此时间未心跳的沙箱标记离线

敏感字段处理

corp_token 使用 Fernet 加密存储在 corp_sandrpod_config 表。

• 创建时:必填,提交后加密
• 编辑时:输入框留空表示不变,填新值则重新加密覆盖
• 永远不在前端回显明文

测试连接按钮

发起一次健康检查到 api_url,验证 corp_token 是否有效。成功显示绿色 toast + sandrpod-server 版本号,失败显示具体错误。

公网基础 URL

页面提示需要配置环境变量 SIRA_PUBLIC_BASE_URL(在 backend 启动环境中设置)。这个 URL 用于:

• 生成沙箱安装公开页 URL
• 错误消息里嵌入的"点此安装沙箱"链接

⚠️ 配置后不重启不生效。改完联系运维 reload backend。

---

2.6.7 沙箱常见问题(管理员视角)

Q1:用户装不上沙箱?

按可能性:

1. agent_facing_url 配置错或网络不通(从用户那台机能不能 ping/telnet)
2. corp_token 不匹配(看 sandrpod-server 日志)
3. enrollment JWT 过期(10 分钟内得用完)
4. 用户系统不支持(理论上 macOS/Linux/Windows 都支持,但偶发硬件兼容问题)

Q2:决策审计批次上传失败?

检查清单:

• 配置 Tab 的"决策审计开关"是否开启
• 用户那台机能连 Sira backend(不是 sandrpod-server)
• backend 的 sandbox_decision_events 表是否存在(应该已通过 migration 011)
• 看 sandrpod-agent 本地日志 ~/.sandrpod/logs/

Q3:有大量 deny,是不是该改 strict 模式?

不一定。deny 多有几种情况:

• 用户主动在 prompt 弹窗点了"拒绝" → 业务正常
• AI 试探未授权路径 → 业务正常,这就是闸门的意义
• AI 反复同一路径被拒 → 可能 prompt 没人在,应让用户改成"总是允许"或干脆把目录加入工作目录

改 strict 模式会让"路径首次访问"完全失败,适合高敏感场景(财务、HR)。一般业务保持 prompt 即可。

Q4:能远程踢掉一个沙箱吗?

可以。「全部」Tab 找到那个沙箱 → 撤销 token → 下次心跳时 agent 收到信号自动停止。物理卸载需要本机用户配合。

Q5:专用沙箱 vs 用户沙箱怎么选?

场景	推荐
AI 助理日常对话(每个员工独立场景)	用户沙箱
跑批处理 / 共享数据查询 / 自动化运维	专用沙箱
AI 操作员工本地文件 / 邮件 / IDE	用户沙箱
AI 在公共服务器跑长任务	专用沙箱

Q6:沙箱卸载后审计日志还在吗?

在。审计日志独立于沙箱本身,卸载沙箱不删除审计记录。