Altailab/safevm
GitHub: Altailab/safevm
SafeVM 是一个自托管的浏览器流式 Linux 桌面平台，通过持久工作区和一次性 microVM 沙箱为企业提供安全的远程办公与高风险文件隔离引爆环境。
Stars: 0 | Forks: 0
# SafeVM（工作名称）
**安全、通过浏览器流式传输的 Linux 工作区，内置一次性文件引爆沙箱。**
员工在一个隔离的、服务器端的 Ubuntu 风格桌面中工作，该桌面通过流式传输到
他们的浏览器——任何敏感信息都不会存在于他们的个人计算机上。高风险文件
（PDF、Office 文档、未知可执行文件、归档文件）将在一个**一次性的 microVM** 中
打开，并在之后被销毁，因此恶意软件无法持久化或触及企业网络。
**并且相同的基础架构也可运行 AI agent。** 那种使得打开恶意文件变得安全的隔离、egress 控制、审计
和实时接管功能，恰恰也是让 **AI agent 安全操作完整计算机** 的保障——参见 [`docs/ai-agents.md`](./docs/ai-agents.md)。
- **社区版（本仓库）：** 包含所有核心功能——工作区、一次性
沙箱、CDR、SSO、策略引擎、审计——专为**单一组织**（单租户）设计。**免费原样使用，包括商业用途。** 在 [SafeVM 社区许可证](./LICENSE) 下源代码可见——参见 [许可证](#license)。
- **云版（独立、商业）：** 提供多租户控制平面、托管式
自动伸缩、计费和 SLA。其他功能没有任何保留。
完整计划请参见 [`docs/`](./docs)。
## 目录
- [状态](#status)
- [架构一览](#architecture-at-a-glance)
- [技术栈](#tech-stack)
- [仓库布局](#repository-layout)
- [部署到服务器（单行命令）](#deploy-to-a-server-one-liner)
- [本地开发](#local-development)
- [更新](#update)
- [故障排除](#troubleshooting)
- [卸载](#uninstall)
- [许可证](#license)
## 状态
🚧 **第一阶段 — MVP 工作区（进行中）。** 基础架构已搭建：
控制平面 API、node-agent + 可插拔隔离 runtime、支撑服务。
目前尚不能端到端使用。参见 [`docs/roadmap.md`](./docs/roadmap.md)。
## 架构一览
```
Browser (thin client, WebRTC/WebSocket)
│
[ Gateway ] auth (OIDC/SAML), TLS, session routing
│
[ Control Plane ] Bun + Elysia API · Prisma/Postgres · Redis · RabbitMQ
│ (RabbitMQ job bus)
[ Node Agent ] per-host daemon, drives the isolation runtime
│
┌────┴──────────────────────────┐
│ Persistent workspace microVMs │ user's daily Ubuntu desktop
│ Disposable sandbox microVMs │ spawned per risky file, then destroyed
└────────────────────────────────┘
```
完整细节：[`docs/architecture.md`](./docs/architecture.md)。
## 技术栈
| 层级 | 选择 |
|---|---|
| Runtime / 语言 | **Bun** + TypeScript |
| API 框架 | **Elysia** |
| ORM / DB | **Prisma** + **PostgreSQL** |
| 缓存 / 状态 / pub-sub | **Redis** |
| 任务总线（控制平面 ↔ agent） | **RabbitMQ** |
| 隔离 | 可插拔 runtime：`mock`（逻辑）· `docker`（真实桌面，Mac 本地）· `firecracker`（强化的 microVM，Linux+KVM） |
| Web 控制台 | **React** + Vite + TanStack Router + shadcn/ui（基于 `satnaing/shadcn-admin`） |
| 部署 | 单机 Docker Compose / systemd |
## 仓库布局
```
packages/
control-plane/ Elysia API, Prisma schema, queue + redis clients
node-agent/ RabbitMQ consumer + pluggable isolation runtime (mock | firecracker)
web/ React dashboard (shadcn/ui) — Workspaces, Sessions, Images, Users, Audit
deploy/
docker-compose.yml Postgres + Redis + RabbitMQ
.env.example
firecracker/ host setup + image scripts for the microVM runtime (Linux)
hetzner/ one-command provisioning of a real Firecracker test box
docs/
architecture.md
roadmap.md
os-and-licensing.md
ai-agents.md AI agents operating full computers (the differentiator)
cloud-autoscaling.md on-demand Hetzner capacity (cloud tier)
decisions.md
```
## 部署到服务器（单行命令）
在一台全新的 **Ubuntu 22.04 / 24.04** 服务器上，只需一条命令即可安装所有内容（Docker、Bun、
Node.js、控制平面、node-agent、AI-agent runner 以及
nginx 后方的仪表板）——它会自动克隆仓库，生成密钥，运行
迁移，并以 systemd 单元的形式启动所有服务：
将 `PUBLIC_ADDR` 替换为您服务器的 IP 或域名，然后复制粘贴：
```
curl -fsSL https://raw.githubusercontent.com/Altailab/safevm/main/deploy/install-ubuntu.sh \
| sudo PUBLIC_ADDR=YOUR_SERVER_IP bash
```
这就是您需要做的全部操作。管理员登录名 + 密码会在最后打印出来。
### 可选选项
在 `bash` 之前添加以下任何变量（例如 `... PUBLIC_ADDR=1.2.3.4 SEED_ADMIN_EMAIL=you@co.com bash`）：
| 变量 | 默认值 | 作用 |
|---|---|---|
| `PUBLIC_ADDR` | 自动检测的公网 IP | 浏览器使用的域名或 IP（也用于标记桌面 URL） |
| `HTTP_PORT` | `80` | nginx 监听的明文 HTTP 端口（例如 `8000`） |
| `TLS_EMAIL` | _（无）_ | **仅限域名** — 获取 Let's Encrypt 证书并在 **443** 端口提供 HTTPS 服务。不能与纯 IP 一起使用。 |
| `SEED_ADMIN_EMAIL` | `admin@safevm.local` | 首位管理员登录账号 |
| `SEED_ADMIN_PASSWORD` | 自动生成（在最后打印） | 首位管理员密码 |
| `RUNTIME` | `docker` | 隔离级别：`docker` · `mock` · `firecracker` (Linux+KVM) |
| `WEBTOP_IMAGE` | `lscr.io/linuxserver/webtop:ubuntu-xfce` | 桌面容器镜像 |
| `APP_USER` | 调用 sudo 的用户 | 拥有/运行这些服务的 Unix 用户 |
| `INSTALL_DIR` | `/opt/safevm` | 仓库克隆到的位置 |
| `SAFEVM_REPO` | `https://github.com/Altailab/safevm.git` | 要克隆的仓库 |
| `SAFEVM_REF` | `main` | 要安装的分支/标签 |
带几个选项的示例——在自定义端口上的明文 HTTP：
```
curl -fsSL https://raw.githubusercontent.com/Altailab/safevm/main/deploy/install-ubuntu.sh \
| sudo PUBLIC_ADDR=YOUR_SERVER_IP HTTP_PORT=8000 SEED_ADMIN_EMAIL=admin@example.com bash
```
安装后的
强化说明请参见 [`deploy/install-ubuntu.sh`](./deploy/install-ubuntu.sh)。
完成后，脚本会打印如何访问该安装实例：
```
Dashboard: http://
(port 80, or 443 with TLS_EMAIL)
Login:
Password:
```
仪表板由 nginx 在 **`HTTP_PORT`**（默认为 **80**；如果设置了 `TLS_EMAIL`，则在
**443** 上使用 HTTPS）上提供服务；API 在同一个 origin 上进行反向代理，因此
不需要开放额外端口。随时可以使用
`systemctl status safevm-control-plane safevm-node-agent safevm-agent` 检查服务。
## 本地开发
```
# backing services
cp deploy/.env.example .env
docker compose -f deploy/docker-compose.yml up -d
# 安装 + 生成 Prisma client
bun install
bun run db:generate
bun run db:migrate # creates the schema
# 运行服务（独立终端）
bun run dev:cp # control plane -> :3001
bun run dev:agent # node agent (RUNTIME=mock | docker | firecracker)
bun run dev:web # dashboard -> :3000
```
冒烟测试：
```
curl localhost:3001/health
```
## 更新
要将服务器安装实例升级到新版本（在服务器上以 root 身份运行）：
```
sudo bash /opt/safevm/deploy/update-ubuntu.sh
```
与安装程序不同，这会**保留您的配置和数据**：它会保留 `.env`
（因此 `JWT_SECRET` 保持不变，现有登录仍然有效），**不**
重新进行 seed，并在应用迁移之前**备份 Postgres**。它会拉取新
代码，重新安装依赖，重新生成 Prisma client，重新构建仪表板，
应用新的迁移，并重启服务（停机时间仅为
迁移 + 重启的窗口期）。标志：
| 标志 | 效果 |
|---|---|
| `SAFEVM_REF=v1.2.0` | 更新到特定分支/标签/commit（默认为 `main`） |
| `SKIP_BACKUP=1` | 跳过迁移前的 `pg_dump` |
| `FORCE=1` | 即使已处于目标版本也重新构建 |
脚本完成时，会打印旧→新版本号和回滚提示（以及它所创建的
数据库备份的路径）。
## 故障排除
### 重置 / 忘记管理员密码
如果您因为忘记了管理员密码或在安装时输入错误而
无法登录（`invalid credentials`），请使用新密码重新运行 seed。该 seed 操作执行的是
**upsert**，因此它会在原地更新现有管理员的密码哈希——不会丢失
任何数据：
```
cd /opt/safevm/packages/control-plane
set -a; . /opt/safevm/.env; set +a
SEED_ADMIN_EMAIL=admin@example.com SEED_ADMIN_PASSWORD='new-password' \
/opt/bun/bin/bun run prisma/seed.ts
```
在 `SEED_ADMIN_EMAIL` 中使用您的管理员邮箱。然后验证其是否有效（应该返回
一个 token）：
```
curl -s localhost:3001/api/auth/login -H 'content-type: application/json' \
-d '{"email":"admin@example.com","password":"new-password"}'; echo
```
### 页面加载正常但登录失败
在服务器上直接测试 API 以隔离出问题层：
```
systemctl is-active safevm-control-plane # API up?
curl -s localhost:3001/health # control plane healthy?
docker compose -f /opt/safevm/deploy/docker-compose.yml ps # Postgres/Redis/RabbitMQ up?
journalctl -u safevm-control-plane -n 50 --no-pager # recent errors
```
## 卸载
要撤销服务器安装（在服务器上以 root 身份运行）：
```
sudo bash /opt/safevm/deploy/uninstall-ubuntu.sh
```
这会停止并移除 systemd 服务、所有桌面会话容器、
支撑服务（Postgres/Redis/RabbitMQ）、nginx 站点、Bun 以及克隆的
仓库。**默认情况下会保留数据卷。** 标志：
| 标志 | 效果 |
|---|---|
| `PURGE_DATA=1` | 同时删除 Postgres/Redis/RabbitMQ 数据卷 + 拉取的桌面镜像（**会破坏工作区数据**） |
| `KEEP_REPO=1` | 将仓库保留在 `/opt/safevm` |
| `REMOVE_DOCKER=1` | 同时 apt-purge Docker Engine 及其 apt 仓库/密钥 |
| `REMOVE_NGINX=1` | 同时 apt-purge nginx |
| `REMOVE_NODE=1` | 同时 apt-purge Node.js（为 Prisma CLI 安装） |
完全擦除（install-ubuntu.sh 触及的所有内容，包括数据和 Docker）：
```
sudo PURGE_DATA=1 REMOVE_DOCKER=1 REMOVE_NGINX=1 REMOVE_NODE=1 bash /opt/safevm/deploy/uninstall-ubuntu.sh
```
## 许可证
SafeVM 归 **Rufat Mammadli, founder of Altailab LLC** 所有，并基于
**[SafeVM 社区许可证](./LICENSE)** 授权——这是一种源代码可见的许可证：
- ✅ 当您运行**未经修改的**
社区版（本仓库中有限的、单租户功能集）时，**可免费使用，包括商业用途**。
- 🚫 **对_已修改_版本进行商业使用需要获取商业许可证**
来自 Altailab LLC。对于非商业用途，修改后的版本免费。
如需获取商业许可证（修改版本使用、企业条款或
多租户云版），请通过
[项目仓库](https://github.com/Altailab/safevm) 联系 Altailab LLC。
请注意，SafeVM 发布或构建的**客户机 OS 镜像**带有其各自的组件
许可证（Linux 内核为 GPLv2）；这些许可证独立于 SafeVM
社区许可证。参见 [`docs/os-and-licensing.md`](./docs/os-and-licensing.md)。标签：DAST, 微虚拟机, 恶意软件分析, 搜索引擎查询, 沙箱, 测试用例, 自动化攻击, 虚拟桌面, 请求拦截, 远程浏览器隔离