单机安装详解

deploy/quickstart.sh 在一台 Linux 机器上装好 OpenDsec 的全部组件。它用的是和多机集群相同的工具（opendsecops），所以装好的单机集群以后可以升级，也可以加机器。这一页说明它的要求、选项、具体做了什么、装在哪里，以及常见问题。简要步骤见快速开始。

1. 要求

项目	要求	检查方法
架构	x86_64	`uname -m`
内核	5.15 以上（Ubuntu 24.04 上完整验证过）	`uname -r`
init	systemd	`ls /run/systemd/system`
cgroup	v2（unified）	`stat -fc %T /sys/fs/cgroup` 输出 `cgroup2fs`
文件系统	支持 overlay	`grep overlay /proc/filesystems`
命令	`curl`、`tar`、`sha256sum`、`mkfs.ext4`、`ip`、`awk`（Ubuntu 自带）	—
编译	Go 1.27 以上、`make`（使用预编译程序或 `--release` 时不需要）	`go version`
权限	root	—
端口	7001、7002、7011、7100、7201、7400、9461–9464、9467 未被占用	`ss -ltn`
microVM	`/dev/kvm`：裸金属，或开启了嵌套虚拟化的云主机。没有时只装容器	`ls /dev/kvm`
资源	建议 4 核、8 GB 内存、40 GB 磁盘以上	—

脚本开始时会逐项检查并打印 [ok] 或 [x]，有 [x] 时停下，不改动机器。

2. 安装

sudo -i                                                   # 以下都以 root 执行
apt update && apt install -y make git python3-venv
curl -fsSL https://go.dev/dl/go1.27.3.linux-amd64.tar.gz | tar -C /usr/local -xz
git clone https://github.com/kernflux/opendsec && cd opendsec
deploy/quickstart.sh

在全新的 8 核虚拟机上约 8 到 11 分钟，大部分时间在编译。

选项

选项	说明
（无）	有 `/dev/kvm` 时装 container 和 microVM，没有时只装 container。guest 内核从 GitHub Release 下载，并按 `deploy/deps.lock` 校验 sha256
`--no-microvm`	只装 container
`--kernel FILE`	使用已有的 guest 内核文件，不下载
`--build-kernel`	自己编译 guest 内核（多几分钟，需要 `build-essential flex bison bc libelf-dev libssl-dev`）
`--release DIR`	使用打包好的版本目录，不编译（离线安装包用这个）
`--uninstall`	卸载，见 §6
`--help`	显示用法

环境变量

变量	默认	说明
`OPENDSEC_IMAGE`	`docker.io/library/python:3.12`	导入的基础镜像；也可以是镜像文件
`OPENDSEC_ADDR_IP`	默认路由的源地址	组件监听的地址。机器有多块网卡、或者要让其他机器访问时指定
`OPENDSEC_OPS`	`/root/opendsec-ops`	运维目录
`OPENDSEC_DEBS`	—	离线安装包里的软件包仓库（`debs/`），从它安装系统软件包而不是用 apt 源

例如只让本机访问：OPENDSEC_ADDR_IP=127.0.0.1 deploy/quickstart.sh。

3. 脚本做了什么

检查机器（§1 的各项），确定节点名（主机名）、地址、sandbox 状态目录（/data 是挂载点时用 /data/opendsec-state，否则 /var/lib/opendsec/edge-state）和是否装 microVM。
编译并打包：make build，然后 opendsecops release 把程序、systemd unit、Firecracker、jailer 和 guest 内核打成一个版本，放在 /root/opendsec-ops/releases/<版本>。
写配置：在运维目录生成 inventory（本机，ssh 地址为 local）、集群配置 opendsec.json 和管理员 token。配置要点：
- 单副本 IAM（Raft，以后可以扩成 3 副本），root 配额 10000 个 sandbox，token 最长 90 天；
- 镜像库在 /mnt/opendsec-images（本机目录）；
- 规则集 pypi，没有默认网络规则：sandbox 默认不能访问网络；
- container 后端（最多 2000 个，默认盘 1 GB）；有 KVM 时加 microvm 后端（最多 1000 个，默认盘 2 GB，开启 EROFS 镜像盘、pmem、内存回收）；
- E2B 网关，项目 root/demo，模板 base = root/py:3.12。
签证书并安装：opendsecops certs 生成 CA 和各组件证书；opendsecops install all 创建用户和目录，下发版本、配置、证书、systemd unit，设置节点参数（sysctl、模块、NFS 客户端标识等）。
启动：opendsecops start all，按 IAM → watcher → apiserver → E2B 网关 → edge 的顺序启动，等每个都就绪。
导入镜像：把 OPENDSEC_IMAGE 导入为 root/py:3.12。
建项目和调用方：项目 root/demo（配额 100 个 sandbox），身份 demo，授予它 root/demo 上的 sandbox.create、sandbox.operate、layer.publish 和 root 上的 layer.use。
检查：用 demo 身份各创建一个 container 和 microVM sandbox，执行 python3 -c 'print(6*7)'，确认输出 42，然后停止。

最后打印管理员和调用方的使用方法。

4. 装好之后

环境

. /root/opendsec-ops/env         # 管理员：admin token，项目 root
. /root/opendsec-ops/demo.env    # 调用方：项目 root/demo 的 token；也设置了 E2B_API_URL、E2B_SANDBOX_URL、E2B_API_KEY

文件和目录

路径	内容
`/root/opendsec-ops/`	运维目录：inventory、`opendsec.json`、`admin.token`、`pki/`（含 CA 私钥）、`releases/`、`env`、`demo.env`。含有密钥，请妥善保管和备份
`/opt/opendsec/current`	当前版本（指向 `/opt/opendsec/releases/<版本>`）：`bin/`、`vm/`（guest 内核）、`agents/`、`units/`
`/usr/local/bin/opendsec-*`、`opendsecctl`	指向当前版本的程序
`/etc/opendsec/`	本机使用的配置、证书、`admin.token`
`/var/lib/opendsec/iam`	IAM 数据（Raft 日志和快照）
`/data/opendsec-state` 或 `/var/lib/opendsec/edge-state`	sandbox 的磁盘、快照和记录
`/mnt/opendsec-images`	镜像库
`/var/log/opendsec/audit`	审计日志
`/var/backups/opendsec`	IAM 每日备份

服务

unit	端口（指标、`/readyz`）
`opendsec-iam@0`	7001、Raft 7011（9461）
`opendsec-watcher@0`	7002（9462）
`opendsec-apiserver@0`	7100（9463）
`opendsec-edge`	7201（9464）
`opendsec-e2b@0`	7400（9467）
`opendsec-iam-backup.timer`	每天 03:00 备份 IAM

systemctl status 'opendsec-*'
journalctl -u opendsec-edge -f
deploy/prod/opendsecops status          # 每个组件是否就绪
opendsecctl status                      # 集群快照（先 . /root/opendsec-ops/env）

让其他机器访问

安装时用 OPENDSEC_ADDR_IP 指定其他机器能访问的地址（默认就是默认路由的地址）。
把 /root/opendsec-ops/pki/ca.crt、调用方的 token 和地址交给调用方；调用方设置 OPENDSEC_ADDR=<地址>:7100、OPENDSEC_CA=<ca.crt 路径>。
防火墙只放行 7100（以及用 E2B SDK 时的 7400）。

重启机器

所有服务开机自启。重启后 sandbox 全部丢失（包括暂停中的），镜像、项目、身份和 token 都保留。

5. 升级

单机集群没有 fleet，用 opendsecops 升级：

cd opendsec && git pull
make build && deploy/prod/opendsecops release bin/
deploy/prod/opendsecops upgrade <新版本>          # 版本号在上一条命令的输出里
deploy/prod/opendsecops status

升级时各组件逐个重启，运行中的 sandbox 不受影响。回退：deploy/prod/opendsecops rollback <旧版本>。升级前请看 CHANGELOG.md 里的「Breaking」一节。

6. 卸载

deploy/quickstart.sh --uninstall

停止并禁用所有服务，杀掉残留的 sandbox，删除 nftables 表、网络接口和命名空间、挂载点，以及 /etc/opendsec、/opt/opendsec、/var/lib/opendsec、/var/log/opendsec、/var/backups/opendsec、运维目录、镜像库和 sandbox 状态目录。

保留的：节点参数（/etc/sysctl.d、udev 规则、/etc/modules-load.d、networkd 文件），以及 Go、make 等你自己装的软件。

7. 常见问题

现象	原因与处理
`[x] command make`	`apt install -y make`
`[x] Go 1.27+ to build`	按 §2 安装 Go；或者在别处编译好，把 `bin/` 拷过来
`[x] cgroup v2`	系统还在用 cgroup v1：内核参数加 `systemd.unified_cgroup_hierarchy=1` 后重启
`[x] port 7100 is in use`	有其他程序占用端口；或者之前装过：先 `--uninstall`
`[x] /root/opendsec-ops already holds a cluster`	之前装过：先 `--uninstall`，或者用 `opendsecops` 管理已有的集群
`warning: no /dev/kvm: containers only`	机器不支持 KVM。云主机请开启嵌套虚拟化，或者改用裸金属
`could not fetch the guest kernel pinned in deploy/deps.lock`	访问不了 GitHub：用 `--kernel FILE`、`--build-kernel`，或 `--no-microvm`
导入 `python:3.12` 很慢或失败	访问 Docker Hub 慢：用 `OPENDSEC_IMAGE` 指定国内镜像源的地址，或者先 `docker save` 成文件再用文件路径
`python3 -m venv` 报 ensurepip 不可用	`apt install -y python3-venv`
最后的检查报 `... sandbox ... python printed '...', want 42`	sandbox 建好了但命令没有得到预期输出：看 `journalctl -u opendsec-edge` 和 `opendsecctl status`，再手动执行 `opendsecctl exec <id> python3 -c 'print(6*7)'` 看报错
microVM 创建失败	`journalctl -u opendsec-edge` 里看具体原因；`ls -l /dev/kvm` 确认存在；云主机确认嵌套虚拟化已开启

更多问题见故障排查。

单机安装详解 ​

1. 要求 ​

2. 安装 ​

选项 ​

环境变量 ​

3. 脚本做了什么 ​

4. 装好之后 ​

环境 ​

文件和目录 ​

服务 ​

让其他机器访问 ​

重启机器 ​

5. 升级 ​

6. 卸载 ​

7. 常见问题 ​