员工 PC 沙箱：安装指南

谁可以看到这个流程

• 员工：在 /agent-system/sandboxes → "我的沙箱" 标签里点"一键安装"
• 管理员：可以代员工生成安装短链转发出去

整体流程

员工点"一键安装"
    │
    ▼
后端签发 10 分钟有效的 JWT (jti 抗重放)
    │
    ▼
前端展示一行 shell / PowerShell 命令
    │
    ▼
员工在 PC 上粘贴执行
    │
    ▼
脚本下载 sandrpod-agent + sandrpod-tray 二进制
    │
    ▼
注册系统服务 (LaunchAgent / systemd-user / NSSM)
    │
    ▼
长 token 存入 Keychain / Secret Service / Credential Manager
    │
    ▼
sandrpod-agent 用 yamux + WebSocket 反向连接 SandrPod 服务端
    │
    ▼
Sandboxes 页面状态从 pending 变为 online

前置条件

1. 管理员已经配置好"配置"标签里的 api_url / agent_facing_url / api_token（详见 总览）
2. 后端环境变量 SIRA_PUBLIC_BASE_URL 已正确设置——员工那边能解析到的公网地址
3. 当前 License 包含 sandbox.user_pc（PROFESSIONAL 起）

员工操作

第一步：发起注册

进入 /agent-system/sandboxes，"我的沙箱"标签，点击"一键安装"。

单槽位

每个员工每个组织最多有一个未撤销的 user 沙箱。如果你已有沙箱，会得到 409 UserSandboxAlreadyExists。先撤销旧的再装新的。

第二步：复制并执行安装命令

弹窗显示两条命令任选其一：

macOS / Linux：

curl -fsSL https://your-sira-host/api/agent-system/sandboxes/install/sandrpod-agent.sh \
  | SIRA_ENROLL='<10-min-jwt>' bash

Windows PowerShell：

iwr -UseBasicParsing https://your-sira-host/api/agent-system/sandboxes/install/sandrpod-agent.ps1 | iex
Install-SiraSandbox -EnrollToken '<10-min-jwt>'

JWT 有效期 10 分钟——超时只能回去重新点"一键安装"。

第三步：脚本做了什么

• 下载二进制：
  • sandrpod-agent（核心）：从 /install/bin/{os}/{arch} 拉
  • sandrpod-tray（GUI 弹框 + 本地设置页）：从 /install/tray/{os}/{arch} 拉
  • Windows 还会拉 NSSM（/install/nssm/{arch}）
• 注册自启服务：
  • macOS：写 LaunchAgent plist
  • Linux：写 ~/.config/systemd/user/sandrpod-agent.service + loginctl enable-linger
  • Windows：用 NSSM 注册 Service
• 工作目录：~/.sira-sandbox/{user_hash}（user_hash = sha256(user_id)[:8]）
• 长有效期 token 落入操作系统密钥库：
  • macOS Keychain
  • Linux Secret Service / libsecret（无 GUI 时回退 chmod 600 ~/.sira/token）
  • Windows Credential Manager

第四步：验收

回到"我的沙箱"标签，状态会从 pending 变为 online（首次心跳通常几秒内）。如果一直卡在 pending，常见原因：

• 员工 PC 防火墙阻断到 agent_facing_url 的出口连接
• SIRA_PUBLIC_BASE_URL 配错，安装脚本里的地址员工解析不到
• 公司代理需要配置（参见 sandrpod-agent 的代理参数）

撤销 / 卸载

管理员撤销

在 Sandboxes 页面找到对应沙箱，点"撤销"。状态立即变为 revoked，对应 sandrpod 服务端会拒绝继续路由。

员工自助卸载

员工 PC 上有一份长有效期的 revoke_token（HS256 JWT，aud sira-sandbox-revoke，TTL 1 年）。卸载脚本会调用：

POST /api/agent-system/sandboxes/self-revoke
{ "revoke_token": "..." }

这是个公开端点——只验证 JWT 签名即可撤销，幂等。这样即使员工离开公司、Sira 后端停机，员工仍能干净卸载。

公开端点速查

端点	鉴权	用途
POST /enrollment	需登录	管理员 / 自己生成 10 分钟 JWT
GET /enrollment/{id}	需登录	轮询注册状态
DELETE /enrollment/{id}	需登录	取消还没消费的注册
POST /enrollment/consume	公开	sandrpod-agent 用 JWT 换 sandbox_name + 长 token
GET /install-info?token=<jwt>	公开	sandbox-install 网页用，仅验签不消费
POST /self-revoke	公开	长 token 撤销自己
GET /install/bin/{os}/{arch}	公开	下载 sandrpod-agent 二进制
GET /install/tray/{os}/{arch}	公开	下载 sandrpod-tray 二进制
GET /install/nssm/{arch}	公开	Windows NSSM
GET /install/sandrpod-agent.{sh,ps1}	公开	安装脚本模板

公开端点都做了签名校验或 JWT 验证，并被 LicenseExpirationMiddleware 白名单豁免——保证 License 过期时员工仍能继续连接 / 卸载。

二进制文件没有？

如果 /install/bin/{os}/{arch} 返回 503 BINARY_NOT_AVAILABLE，说明运维还没把对应平台的 sandrpod 二进制放到后端 app/extensions/agent_system/static/sandbox_agent_bin/{os}/{arch}/ 目录下。这是部署任务，不是运行时 bug。

支持矩阵：

OS	架构
darwin	amd64 / arm64
linux	amd64 / arm64
windows	amd64（arm64 自动回落到 amd64）

公共安装页 /sandbox-install?token=...

如果员工不方便登录 Sira（出差只带个 PC），管理员可以把 /sandbox-install?token=<jwt> 短链直接发给他。这个页面：

• 不需要登录——只验 JWT 签名
• 显示一键安装命令（bash + PowerShell 两版）
• 显示 JWT 剩余有效期

URL 安全

JWT 在短链里以 query 参数明文传递。注意：

• 短链只在 10 分钟内有效，过期就失效
• jti 一次性消费——员工装完一台后，同一 JWT 不能再被用一次
• 管理员可以提前 DELETE /enrollment/{id} 撤销没用过的票