# Lobe Sandbox Backend — 自托管沙箱后端

## What

替换 LobeChat 对 `market.lobehub.com` 云沙箱的依赖,改为公司 VPS(2.24.28.41)本地自托管的 **per-user Incus LXC** 工作区。

- **服务对象**:`ai.milejoy.com`(公司主)+ `lobehub.kang-kang.com`(个人备份,同 backend)
- **隔离粒度**:每个 LobeChat 用户一个 Incus 容器,跨对话共享文件系统(概念对标 ChatGPT Code Interpreter)
- **挂钩点**:better-auth `databaseHooks.user.create.after`(在 LobeChat 项目里改)

## Why 这个设计

- 三条路(a 自建 / b 走 LobeHub 白名单付费 / c 让员工个人账号 OAuth 授权),**a 省钱 + 数据不出公司 + 掌控力**
- 沙箱技术选 Incus LXC(不是 Docker / Firecracker / Daytona): 长命工作区 = 系统容器,公司已有 Incus 栈(hermes-box 同宿主),无新技术栈,CoW 省磁盘
- btrfs 存储驱动(不是 ZFS):Debian 13 内核原生支持,`apt install btrfs-progs` 零重启,CoW 效果等价

## 架构

```
LobeChat (Coolify) 
   ↓ HTTP 内网(X-Sandbox-Secret HMAC)
Sandbox Orchestrator(Bun 写的 HTTP 服务,systemd 跑在 VPS 宿主机)
   ↓ incus CLI(unix socket)
Incus 宿主(VPS 2.24.28.41)
   ├── lobe-sandbox project
   ├── lobe-sandbox-pool(btrfs 200GiB,CoW)
   ├── sandbox-default profile(2GB RAM / 2 CPU / 10GiB disk)
   └── sb-<userId> 容器 × N(默认 stopped,调用时起)
   ↓ exportFile
MinIO(192.168.2.221:9000)
```

## 生命周期

| 阶段 | 触发 | 动作 |
|---|---|---|
| 创建 | better-auth user.create | `incus copy lobe-sandbox-base → sb-<userId>`,不启动 |
| 激活 | 首次 tool 调用 | `incus start` 2-3 秒内可用 |
| 空闲 | 30min 无调用 | `incus stop`,rootfs 保留 |
| 删除 | 手动 / admin | 备份到 MinIO + `incus delete` |

## 部署目标

- VPS: `root@2.24.28.41`
- Orchestrator 端口: `127.0.0.1:8700`(内网,不对外暴露)
- Base 镜像: `lobe-sandbox-base`(Debian 13 + Python 3.13 + Node 20 + Bun + uv + 中文字体)
- Orchestrator 部署路径: `/opt/lobe-sandbox/orchestrator`(TBD)
- systemd unit: `sandbox-orchestrator.service`

## 关键决策 & 坑点

### 1. 存储池用 btrfs 不是 ZFS
原方案 ZFS,实发现 ZFS 在这台 Ubuntu 要 DKMS 编译,可能触发重启(用户规则:不频繁重启服务)。改用 btrfs,内核原生,一键 `apt install btrfs-progs` 零重启,CoW 效果一样。

### 2. ⚠️ UFW 挡了 incusbr0 的 DHCP/DNS(大坑)
**现象**:新容器用 `DHCP=true`,`DHCPDISCOVER` 发出去但 `No DHCPOFFERS received`,只拿到 IPv6 SLAAC。

**原因**:这台 VPS `iptables INPUT 策略=DROP`(UFW 默认)+ Docker 的 FORWARD chain。默认没放行 incusbr0 的 udp/67、udp/53、tcp/53,也没放 FORWARD。nftables 里 Incus 自己加的规则不生效(iptables 和 nft 都跑,都要通过)。

**绕开**:hermes-box 用**静态 IP**(`Address=10.146.223.10/24`),所以没触发这问题。

**修复**(已落盘到 `/etc/iptables/rules.v4`,通过 netfilter-persistent 持久):
```
iptables -I INPUT -i incusbr0 -p udp --dport 67 -j ACCEPT
iptables -I INPUT -i incusbr0 -p udp --dport 53 -j ACCEPT  
iptables -I INPUT -i incusbr0 -p tcp --dport 53 -j ACCEPT
iptables -I FORWARD -i incusbr0 -j ACCEPT
iptables -I FORWARD -o incusbr0 -j ACCEPT
```

修复后 DHCP 立即可用(容器拿到 `10.146.223.248`)。本地 `scripts/host-init.sh` 里写了这段幂等实现,新环境部署自动修。

### 3. Python 版本
Debian 13 默认 Python 3.13(不是计划的 3.12)。不影响功能,更新。

### 4. 沙箱是 per-user 不是 per-topic
对话跨 topic 共享工作区,对齐 ChatGPT Code Interpreter 的心智模型。

### 5. 基座"什么都不装"原则
- 只装必需的运行时(Python/Node/Bun/uv)+ 系统工具(git/curl/build-essential/中文字体)
- **不预装** pandas/numpy/torch/playwright/ffmpeg/libreoffice
- LLM 按需 `uv pip install xxx` — 后续加本地 PyPI 缓存镜像让它快到秒级(尚未做,列在 TODO)

## 进度(2026-04-19 更新)

- ✅ Phase 0 Pre-flight(VPS 摸底:31GB RAM / 387GB 磁盘 / Incus 6.0.0 / hermes-box 已跑)
- ✅ Phase 1 宿主初始化(btrfs pool + project + profile + **UFW iptables 修复并持久化**)
- ✅ Phase 2 base 镜像 `lobe-sandbox-base` 已发布(500MiB,fingerprint `de8d9b6b73c4`)
  - Debian 13 trixie + Python 3.13.5 + Node 20.20.2 + Bun 1.3.12 + uv 0.11.7 + git/ripgrep/fd/bat + 中文字体 + zh_CN locale
  - **两个坑踩过并写进脚本**:
    1. `INSTALL_DIR` 装 uv 无效,要用 `UV_INSTALL_DIR` 环境变量
    2. `nohup bash -s <<EOF &` 脱不开 SSH,后续全改 `systemd-run --unit=xxx --slice=system.slice`
- ✅ Phase 3 Orchestrator(Bun + Hono,已部署 VPS systemd)
  - 服务:`sandbox-orchestrator.service` 监听 `127.0.0.1:8700`
  - 配置:`/etc/lobe-sandbox/orchestrator.env`(含 SANDBOX_ORCH_SECRET)
  - 端到端验证:POST /users → executeCode → runCommand + uv pip install numpy → writeLocalFile → listLocalFiles 全 OK
  - 已实现 13 工具(executeCode/runCommand/readLocalFile/writeLocalFile/editLocalFile/listLocalFiles/moveLocalFiles/renameLocalFile/searchLocalFiles/grepContent/globLocalFiles + ensureRunning 逻辑 + 30min idle reaper + HMAC auth + S3 export 占位)
  - **长驻命令(getCommandOutput/killCommand)留到 v2**,当前 runCommand 是同步 2min 超时
- ✅ Phase 4 LobeChat 侧接入代码已提交(分支 `feat/self-hosted-sandbox`,commit `12b53e90b1`)
  - `src/envs/app.ts` 新增 `SANDBOX_BACKEND_URL` + `SANDBOX_BACKEND_SECRET`
  - `src/server/services/sandbox/localSandbox.ts` 新 LocalSandboxService
  - `src/server/services/toolExecution/serverRuntimes/cloudSandbox.ts` env 分叉
  - `src/libs/better-auth/define-config.ts` user.create.after 追加 provision(fire-and-forget)
  - **注意**: main 分支 pre-commit 会跑全量 tsc 撑爆内存 + 碰到别人的 pre-existing TS 错误,所以必须在 feature branch 上 commit
- ⏸ Phase 5 待做(上线):
  - [ ] 确定 LobeChat docker 容器访问 orchestrator 的网络路径(host.docker.internal / docker0 网关 172.17.0.1 / 绑 0.0.0.0 + UFW 限制)
  - [ ] merge `feat/self-hosted-sandbox` 到 main(需先解决 main 上别人的 pre-existing TS 错误,或单独 deploy 这个 branch)
  - [ ] Coolify 里 LobeChat 容器加 `SANDBOX_BACKEND_URL` + `SANDBOX_BACKEND_SECRET` 环境变量
  - [ ] 重启 LobeChat(一次性,不要频繁重启)
  - [ ] 跑 `scripts/backfill-users.ts` 给存量用户补建沙箱
  - [ ] exportFile 接入:当前 `S3_ENDPOINT=192.168.2.221:9000` 是内网,VPS 够不着 → 改用 LobeChat 同机上的 RustFS(`lobemile2026/RustFS@2026MileSecure`)
  - [ ] 端到端 smoke:用户 ai.milejoy.com 发"写个 Python 打印 hello" → 查 orchestrator 日志命中 → 不是 market.lobehub.com

## 关键路径速查

### 本地
- 项目根:`/Users/kangwan/Projects/business/20260418-lobe-sandbox-backend/`
- 宿主初始化脚本:`scripts/host-init.sh`
- base 镜像构建脚本:`images/base/build.sh`

### VPS(2.24.28.41)
- 构建日志:`/var/log/build-sandbox-base.log`(第一次,卡 UFW)
- 续跑日志:`/var/log/build-sandbox-base.log.2`(第二次,SSH 断开死)
- 构建脚本副本:`/root/build-sandbox-base.sh`
- Incus 数据:`/var/lib/incus/`
- btrfs pool 文件:`/var/lib/incus/disks/lobe-sandbox-pool.img`(200GiB 稀疏)

### Incus 操作(切到 lobe-sandbox project)
```bash
incus list --project lobe-sandbox
incus profile show sandbox-default --project lobe-sandbox
incus image list --project lobe-sandbox
```

## 规划中的 / 待决
- PyPI 本地缓存镜像(nginx 反代清华源)—— 让 `uv pip install` 秒级
- npm 本地缓存(Verdaccio)
- exportFile 对接 MinIO 的 presigned URL 上传流
- 用户删除的手动清理脚本 + 定时 GC(better-auth 没有 user.delete hook)