OpenDsec 生产运维手册

本文是多机生产集群的安装、日常操作和故障处理手册。设计背景见 SPEC §27，组件说明见 deploy/README.md。只想在一台机器上试用，见 deploy/quickstart.sh（README「单机部署」）。

1. 拓扑

下面以示例清单 deploy/prod/inventory.example 为例：

节点	组件	说明
ctl-1、ctl-2、ctl-3	iam、watcher、apiserver、fleet 各一个副本；ctl-3 另跑 Prometheus 和 Alertmanager	管控节点，每个故障域一台，4 核 8G 起步，不跑 sandbox
node-a1、node-b1、node-c1 …	edge、节点代理	计算节点：裸金属或开了嵌套虚拟化的云主机，跑 sandbox

• 任意一台管控节点宕机，集群都能继续创建和使用 sandbox。计算节点宕机时，它上面的 sandbox 随之丢失，新的 sandbox 调度到其他节点。
• 小集群可以把管控组件和 edge 放在同一批机器上（inventory 里同一行写多个角色）。
• 共享存储（NAS）挂在所有 apiserver 和 edge 节点的 /mnt/opendsec-images，存放镜像和快照。
• 内网负载均衡（下文称 LB）监听 7100 端口（四层 TCP），后端是所有 apiserver。客户端只使用 LB 的地址。

端口（安全组只在 VPC 内放行）

端口	用途	谁来访问
7100	apiserver 公共 API（TLS）	LB、运维机
7001 / 7011	IAM gRPC / Raft 复制	所有组件 / IAM 副本之间
7002	watcher	apiserver、edge
7201	edge	watcher、apiserver、其他 edge、fleet
7300	fleet（集群管理，§6）	节点代理、apiserver、其他 fleet 副本
7400	E2B 网关（可选，§4）	用 E2B SDK 的调用方、LB
9461–9467	指标、/healthz、/readyz（iam、watcher、apiserver、edge、fleet、节点代理、E2B 网关）	Prometheus、LB 健康检查（9463，E2B 网关 9467）、节点代理（本机）
9100	node_exporter	Prometheus
9090 / 9093	Prometheus / Alertmanager	运维人员

基础设施要求

• NAS：使用 NFS 4.1 及以上版本，并且必须关闭 root squash（权限组里设为「不限制 root」）。edge 以 root 身份写快照，apiserver 要删除这些快照。
  • 挂上之后、迁移之前先跑 opendsecctl image store-check -store /mnt/<新挂载点>（不需要连集群），必需项全部 ok 才能用。不支持 trusted.* xattr 没关系（SPEC §29.5）。
  • 挂载参数：vers=4.2,nconnect=8,hard,timeo=600,lookupcache=positive,_netdev。4.1 也能用，但找不到稀疏文件里的空洞：在另一台节点上用内存快照创建 sandbox 时，要把磁盘和内存按全尺寸读一遍（实测慢一倍多，store-check 会提示）。lookupcache=positive 让客户端不缓存「文件不存在」：不加的话，一台节点在镜像登记之前查过它，之后最长约一分钟内可能仍然找不到（SPEC §30）。
  • fstab 写法：<nas>:/ /mnt/opendsec-images nfs4 vers=4.2,nconnect=8,hard,timeo=600,lookupcache=positive,_netdev 0 0。
  • 每个节点的 NFS 客户端标识必须不同。没有设置标识时，NFSv4 客户端用主机名标识自己，主机名相同的节点（比如从同一个镜像克隆出来的）会被服务端当成同一个客户端，互相作废对方的打开文件和锁（SPEC §33.4）。deploy/node/install.sh 用 /etc/machine-id 设置标识（/etc/modprobe.d/opendsec-nfs.conf），新的标识要等重新挂载、且旧挂载没有人在用之后才生效，最简单的是重启节点。检查方法：在 NFS 服务端看 /proc/fs/nfsd/clients/*/info 里的 name，每个节点应该各不相同；或者看服务端 syslog 里 rpc.mountd 的 client attached/detached 是否在不停地刷。
• LB（云上的四层负载均衡，或自建的 HAProxy / LVS）：配置如下。
  • 监听 TCP 7100，不能用七层 HTTP/gRPC 监听：TLS 由 apiserver 自己终结。
  • 健康检查用 HTTP，端口 9463，路径 /readyz，间隔 2 秒，连续 2 次失败即判定不健康。
  • 空闲超时不低于 30 秒：apiserver 每 20 秒给空闲连接发一次 ping，安静的流（批量创建、长命令）因此不会被 LB 断开。
  • 如果 LB 支持，请保留客户端源地址，否则按地址限流的认证失败会集中算到 LB 上（见 deploy/README.md「准入与限流」）。
  • apiserver 的证书必须包含 LB 的地址：执行 opendsecops certs <LB地址>，再执行 opendsecops push-config all 和 opendsecops restart。

不能访问外网的机房：用离线安装包（deploy/offline/README.md，SPEC §38）。步骤和下文相同，只是软件包用 OPENDSEC_DEBS、版本用 opendsecops release-add、镜像从文件导入。

2. 运维机与 opendsecops

运维机可以是任意一台能 ssh 到所有节点的机器（也可以是某台管控节点），目录默认是 /root/opendsec-ops，可以用 OPENDSEC_OPS 改为其他位置；ssh 私钥默认 /root/.ssh/opendsec-ops（OPENDSEC_SSH_KEY）。目录内容：

inventory      节点与角色（参照 deploy/prod/inventory.example）
opendsec.json      集群配置（参照 deploy/prod/cluster.example.json）
admin.token    管理员 token，权限 0600
pki/           集群 CA（ca.key 只放在这里）
releases/      打包好的版本
backups/       IAM 备份
current ->     releases/<当前版本>

deploy/prod/opendsecops help 会列出全部命令。常用命令：

命令	作用
opendsecops release bin/	把 make build 的产物打包成一个版本（版本号来自 opendsecctl version）
opendsecops certs [LB地址]	生成 CA 和证书；指定 LB 地址时，重签 apiserver 的证书
opendsecops install all	首次安装：创建用户和目录，下发版本、配置、证书、systemd unit 和节点准备脚本。不启动任何服务
opendsecops start all	按 IAM → watcher → apiserver → edge 的顺序启动，并等待全部就绪
opendsecops status	检查每个组件的 /readyz，并显示当前的 IAM leader
opendsecops versions	每个组件正在运行的版本
opendsecops upgrade <版本>	滚动升级
opendsecops rollback <旧版本>	回滚。过程与升级相同，只是换成旧版本
opendsecops push-config all + opendsecops restart	修改配置或证书后，下发并滚动重启
opendsecops backup	立即备份一次 IAM 到运维机
opendsecops rotate-ca 1|2|3	不停服轮换集群 CA（见 §4「证书」）
opendsecops monitor [webhook]	安装 node_exporter、Prometheus 和 Alertmanager，告警发往 webhook

每个节点只会拿到 ca.crt 和本机组件的证书与私钥。admin.token 只下发到 IAM 节点，因为 IAM 启动时需要它；集群配置里只写 admin_token_file，不写 token 本身。

3. 首次安装

make build && deploy/prod/opendsecops release bin/
# 编辑 $OPENDSEC_OPS/inventory、opendsec.json，写入 admin.token（dsk.admin.<随机 32 位十六进制>）
deploy/prod/opendsecops certs <LB地址>
deploy/prod/opendsecops install all
# 各节点挂载 NAS 到 /mnt/opendsec-images（写入 fstab）
deploy/prod/opendsecops start all
deploy/prod/opendsecops monitor <告警 webhook>
deploy/prod/opendsecops status

从单机 IAM（iam.state 文件）迁移到 3 副本：

1. 在旧集群上执行 opendsecctl iam backup -out iam.json.gz。
2. 停掉旧服务，用新配置执行 install 和 start。新 IAM 会用同一个 admin token 自举。
3. 执行 opendsecctl iam restore iam.json.gz。
4. 配额租约不在备份里。edge 上已有的 sandbox 会在下一轮对账（reconcile_interval，默认 30 秒）时被 IAM 重新登记。

4. 日常操作

升级

make build && deploy/prod/opendsecops release bin/
deploy/prod/opendsecops upgrade <新版本>

• 执行顺序：
  1. 把新版本下发到所有节点并校验 sha256；
  2. 逐个重启组件，每个都等到 /readyz 返回 200 才继续下一个；
  3. IAM 先重启 follower，最后重启 leader；
  4. 然后依次是 watcher、apiserver、edge。每台 edge 重启后，还要等它在集群快照中恢复为 healthy。
• 任何一步超时（OPENDSEC_READY_TIMEOUT，默认 180 秒）就停下，不再继续。已经升级的组件保持新版本；要回滚就执行 opendsecops rollback <旧版本>。
• apiserver 收到 SIGTERM 后先让 /readyz 失败，再继续服务 6 秒，等 LB 把它摘掉，然后给进行中的请求最多 30 秒完成。SDK 会对断开的请求做重试和流续传（SPEC §26）。
• edge 重启不会影响 sandbox：前提是配置了 keep_sandboxes_on_exit 和 persist_state，unit 使用 KillMode=process。新 edge 进程启动后会重新接管这些 sandbox。
• 每个节点保留最近 3 个版本，OPENDSEC_KEEP_RELEASES 可以调整。已经在运行的 sandbox 继续使用它启动时挂载的那一版 agent。

维护一台机器

opendsecctl edge drain node-a1   # 停止往 node-a1 调度新 sandbox，已有的照常运行
# 等存量 sandbox 结束；暂停中的可以迁走（SPEC §26.2）
systemctl stop opendsec-edge                # 在 node-a1 上；管控节点则停 opendsec-{apiserver,watcher,fleet,iam}@<id>
# 维护……然后启动这些服务并执行：
opendsecctl edge drain node-a1 -undo

同一时间只能维护一台 IAM 节点，否则会失去多数派。

需要重启整机时，步骤同上（drain → systemctl reboot → 检查 → drain -undo）。开机后的检查：/data、/mnt/opendsec-images 和 swap 都已挂上，sysctl vm.swappiness 是 10，四个 /readyz 都返回 200，opendsecctl status 里这台 edge 恢复 healthy。

注意：

• 整机重启后，这台机器上的 sandbox 全部丢失，暂停中的 microVM 也一样：edge 接管时发现它的网络命名空间已不存在，于是把它连同快照一起清掉，调用方再访问会得到 not_found。
• 重启期间 Prometheus 会触发 OpenDsecComponentDown、OpenDsecEdgeUnhealthy 等告警；Alertmanager 要配好接收方（opendsecops monitor <webhook>），否则告警不会发给任何人。
• 一次实测（裸金属，固件自检约 107 秒）见 SPEC §27。

证书

• 组件证书有效期 825 天，但不会超过 CA 的到期时间。CA 有效期 10 年。到期前 30 天会触发 OpenDsecCertExpiringSoon 告警。

• 续期组件证书：在运维机上删除对应的 .crt 和 .key，执行 opendsecops certs 重新签发（LB 地址会保留），然后执行 opendsecops push-config all 和 opendsecops restart。

• 轮换 CA，不停服：依次执行下面三步，每一步都包含一次下发配置和滚动重启。

  1. opendsecops rotate-ca 1：生成新 CA，所有节点同时信任新旧两个 CA，组件证书暂时不变。
  2. opendsecops rotate-ca 2：用新 CA 重签全部组件证书。
  3. opendsecops rotate-ca 3：移除旧 CA。

  第 1 步之后，把 $OPENDSEC_OPS/pki/ca.crt（同时含新旧两个 CA）发给所有客户端；第 3 步之后，再发一次（只含新 CA）。

  • 为什么要分三步：组件在重启前一直使用旧的证书和信任列表。如果直接用新 CA 重签，已经重启和尚未重启的组件之间会互相校验失败。

扩容 edge

启用 fleet（§6）之后，加机器用 opendsecops add-node 和 opendsecctl fleet node accept，见 §6.3。下面是启用之前的做法：

1. 在 opendsec.json 的 edges 里加一项，在 inventory 里加一行。
2. 执行 opendsecops certs（会补签新 edge 的证书）。
3. 依次执行 opendsecops install <节点>、opendsecops push-config all、opendsecops restart、opendsecops start <节点>。

接入新租户

export OPENDSEC_ADDR=<LB地址>:7100 OPENDSEC_TOKEN=$(cat $OPENDSEC_OPS/admin.token) OPENDSEC_CA=$OPENDSEC_OPS/pki/ca.crt
opendsecctl project create root <名字> -quota sandboxes=<N>
opendsecctl principal create root/<名字> <调用方> -kind agent          # 输出里的 token 只显示这一次
opendsecctl grant root/<名字> <调用方> sandbox.create,sandbox.operate
opendsecctl grant root <调用方> layer.use                            # 允许使用 root/ 下的镜像

• 给调用方的接入包建议包括：docs/USER_GUIDE.md（填好地址和项目）、SDK wheel、ca.crt、sdk/python/examples/quickstart.py 和 token。token 单独通过安全渠道发送。
• token 最长 90 天（max_token_ttl_s）。到期前用 opendsecctl token create <调用方> 换发，等对方换上新 token 后，用 opendsecctl token revoke 撤销旧的。

用量（SPEC §41）

opendsecctl usage root/<名字> -from 2026-10-01 -to 2026-10-31          # 每个项目在这段时间的合计
opendsecctl usage root -from 2026-10-01 -daily -csv > usage.csv        # 按天、按项目，CSV

• 列出项目自己和全部子项目：启动的 sandbox 数、sandbox·小时、CPU 核·小时、内存 GB·小时、GPU·小时。按 UTC 日期统计，每行只算这个项目自己的 sandbox，子项目单独成行，最后一行是合计。
• 计的是配额租约：sandbox 占着资源的时间都算，暂停中也算（容量是它的）。还在运行的算到查询时刻。
• 需要在该项目上有 project.admin。数据保留 400 天，在 IAM 里随 Raft 复制，不会因为节点重启或故障切换而丢失。
• Python SDK：await client.get_usage("root/<名字>", start="2026-10-01", end="2026-10-31")。

入口

• 有 LB：SDK 配置 OPENDSEC_ADDR=<LB地址>:7100。
• 没有 LB：SDK 配置所有 apiserver 的地址，如 OPENDSEC_ADDR=10.0.0.11:7100,10.0.0.12:7100,10.0.0.13:7100，SDK 自动轮询并在故障时切换（SPEC §27.8）。
• 对公网开放：只放行 TCP 7100，并且只对调用方的来源地址放行；apiserver 证书要包含公网地址或域名（opendsecops certs）。其他端口一律不对外开放：IAM、watcher、edge、fleet 的端口，9461–9466、9100、9090、9093。
• 从直连切到 LB：
  1. 执行 opendsecops certs api.opendsec.internal,<LB地址>,...；
  2. 执行 opendsecops push-config all 和 opendsecops restart；
  3. 通知调用方把 OPENDSEC_ADDR 改成 LB 地址；
  4. 等旧地址上没有流量后，再收紧安全组。

E2B 网关（可选，SPEC §37）

让用 E2B SDK 的调用方直接接入。

1. 在集群配置里加 e2b 一节，按 §6.2 用 fleet 下发：

   "e2b": {
     "gateways": [{"addr": "10.0.0.11:7400"}, {"addr": "10.0.0.12:7400"}],
     "project": "root/e2b",
     "templates": {"base": {"image": "root/py:3.12", "backend": "microvm", "cpu": 2, "memory_mb": 1024}},
     "max_timeout_s": 86400
   }

2. 给机器加上角色，一台一台来：opendsecctl fleet node set <名字> -roles <原有角色>,e2b=<序号>（序号对应 gateways 里的位置），再执行 opendsecctl fleet node sync <名字>。节点代理会把这台机器同步到它应有的版本和配置，启用并启动 opendsec-e2b@<序号>，就绪后再做下一台。
3. 前面放 LB：转发 TCP 7400，健康检查用 HTTP 9467 的 /readyz，空闲超时不低于 60 秒（SDK 的流每 50 秒保活一次）。对外要用 HTTPS 时，在 LB 上终止 TLS，或者在 gateways 里配 tls_cert 和 tls_key。
4. 调用方的设置：E2B_API_URL 和 E2B_SANDBOX_URL 都指向网关，E2B_API_KEY 用他的 OpenDsec token。这个 token 需要在 project 上有 sandbox.create、sandbox.operate，在镜像所在项目上有 layer.use。要用快照（create_snapshot()）的，还要在 project 上有 layer.publish：快照存成这个项目里的镜像。

网关不保存状态，每个请求都用调用方自己的 token 调 apiserver，所以权限、配额、审计和直接用 OpenDsec SDK 完全一样。

E2B code interpreter（e2b_code_interpreter 包）要一个专门的 template：

1. 下载 E2B 的 code-interpreter 仓库，用 deploy/e2b/build-code-interpreter.py 构建镜像。它会建一个 microVM，装好 Jupyter 和 E2B 的服务，拍成带内存的快照 root/code-interpreter:v1。需要能访问外网（pip、apt），以及在 root 上的 layer.publish 权限。
2. 在 e2b.templates 里加上 "code-interpreter-v1": {"image": "root/code-interpreter:v1", "backend": "microvm", "cpu": 2, "memory_mb": 2048}。cpu 和 memory_mb 必须和快照一致。
3. 按 §6.2 下发配置。用 test/e2e/testdata/e2b_code_interpreter_check.py 验收。

5. 故障处理

一台 IAM 节点宕机

• 剩下的两个副本继续服务。会触发 OpenDsecIAMQuorumAtRisk 告警，这时不能再有第二台宕机。
• 机器能恢复：启动 opendsec-iam@<id>，它会自动追上进度。
• 机器无法恢复（换一台新机器、新地址），以替换副本 2 为例，新副本 id 用 3：

  opendsecctl iam member remove 2
  # opendsec.json：把 replicas 里 id 2 的那项改成 id 3 的新地址；inventory 也相应修改
  opendsecops certs && opendsecops install <新节点>
  echo 'OPENDSEC_IAM_FLAGS=-join' > /etc/opendsec/iam.env      # 在新节点上
  opendsecops start <新节点>      # 不会自举，等待被加入；/readyz 在加入前返回失败，所以这一步会超时，属于正常现象
  opendsecctl iam member add 3 -raft-addr <新IP>:7011 -iam-addr <新IP>:7001
  rm /etc/opendsec/iam.env       # 加入之后数据目录里已有 Raft 状态，-join 不再起作用
  opendsecops push-config all && opendsecops restart     # 让其他组件使用新的地址列表

• 原机器保留原地址、只是换了盘：在它上面用 -join 启动即可。它仍在成员列表里，leader 会用快照把状态补给它。

IAM 全部丢失（灾难恢复）

1. 清空每个副本的 /var/lib/opendsec/iam，然后启动。新集群会用 admin token 自举。
2. 执行 opendsecctl iam restore <最近的备份>。备份位置：每台 IAM 节点的 /var/backups/opendsec，以及运维机的 backups/。
3. 等一轮对账，edge 上存活的 sandbox 会被重新登记到配额里。
4. 备份之后才创建的 principal、token 和项目会丢失，需要重建。

一台计算节点宕机

• 其他节点继续服务。
• 宕机机器上的 sandbox 随之丢失。超过 lost_edge_grace（120 秒）后，watcher 会释放它们占用的配额。
• 机器恢复后，edge 会接管仍在运行的 sandbox（只要整机没有重启）。整机重启后什么都接管不了，暂停中的 microVM 也会被清掉（见「维护一台机器」）。

NAS 不可用

• 已经在运行的 microVM 不受影响：它们从本地的镜像副本和快照缓存运行。
• 已经在运行的容器也不受影响：它们挂的是镜像层在节点本地的副本（layer_cache，默认开启）。关闭了 layer_cache 的话，容器的只读层直接挂在镜像库上，读取不在页缓存里的文件会卡住，直到 NAS 恢复（SPEC §33 实测：NFS 中断 60 秒时，一条命令卡了 88 秒）。
• 依赖镜像库的操作会卡住，直到 NAS 恢复或者调用超时，包括：新建 sandbox（实测创建在中断期间最长等了 94 秒，恢复后全部成功）、pack、snapshot、跨节点 fork。
• 告警 NodeImageStoreMissing。NFS 用 hard 挂载，所以 NAS 恢复后卡住的 IO 会继续完成。

系统盘

• 审计日志在 audit_dir（默认 /var/log/opendsec/audit），每个 apiserver 最多保留 audit_keep 个文件（默认 8 个、每个 256 MB）。需要长期保存的，要定期转存到别处。
• 每个 sandbox 都会产生一些内核消息和 networkd 消息。deploy/node/install.sh 让它们只留在 journal 里（journal 默认最多占用文件系统的 10%），并关掉没有配置脚本的 networkd-dispatcher。不这样做的话，负载下 /var/log/syslog 每天增长 1 GB 以上（SPEC §33.2）。

告警与处理

告警	首先检查
OpenDsecComponentDown / NotReady	opendsecops status；在节点上执行 journalctl -u <unit>。curl <ip>:<端口>/readyz 会返回不就绪的原因
OpenDsecIAMNoLeader	在线副本是否少于 2 个；副本之间 7011 端口是否通
OpenDsecEdgeUnhealthy	那台机器是否在线，opendsec-edge 是否在运行
OpenDsecCreateErrors / CreateSlow	opendsec_apiserver_create_seconds 按 reason 看错误分布；查看 edge 的 opendsec_edge_create_phase_seconds
OpenDsecCapacityLow / EdgeUnderPressure	扩容 edge，或者调低项目配额
OpenDsecCertExpiringSoon	按 §4「证书」续期
OpenDsecIAMBackupStale	systemctl status opendsec-iam-backup；查看 /var/backups/opendsec
OpenDsecSLOCreateBurnFast / BurnSlow、SLORuntimeBurnFast / BurnSlow	错误预算消耗过快（docs/SLO.md）：同 CreateErrors，按 reason 和 method 看是哪类错误、从什么时候开始；同一时间有没有发版、改配置或节点故障

6. 集群管理服务 fleet（SPEC §28）

机器多了以后，升级和改配置不再由运维机逐台 SSH，而是由 fleet 服务分批推进，每台机器上的节点代理在本机执行。opendsecops 保留，用于首次安装、签发证书、加机器和应急。

6.1 组成

• opendsec-fleet@<id>：与 IAM 一起放在控制面节点上，3 个副本，端口 7300（指标 9465）。持有 IAM 锁 fleet-controller 的副本是 leader，其他副本把请求转给它。期望状态存在 IAM 的键值区里，随 IAM 一起备份。
• opendsec-nodeagent：每台机器一个，以 root 运行（指标 9466）。每 10 秒向 fleet 上报一次，并执行 fleet 下发的操作：下载版本、切换版本、写 /etc/opendsec/{opendsec.json,edge.env}、重启 opendsec-* 服务。它只接受这几种操作。
  • 节点代理运行的是 /opt/opendsec/agent/opendsec-nodeagent，不随版本切换；新版本里的节点代理先通过 -check 自检，才会替换它。
  • fleet 全挂时，节点代理不做任何改动，组件和 sandbox 照常运行。
• 命令行：opendsecctl fleet ...，经 apiserver 访问，需要 root 项目上的 fleet.view（查看）或 fleet.operate（操作）权限，project.admin 同时具备两者。所有操作都写入审计日志。apiserver 全挂时，在运维机上用 -direct -fleet <副本地址> -pki $OPENDSEC_OPS/pki -ops-id ops 直连 fleet。

6.2 发布和升级

make build && deploy/prod/opendsecops release bin/      # 打包，带上 deploy/deps.lock 锁定的 firecracker、jailer、内核
opendsecctl fleet release push $OPENDSEC_OPS/releases/<版本>
opendsecctl fleet rollout create -release <版本>        # 默认：试点 1 台、观察 5 分钟、每批 5%、批间 60 秒
opendsecctl fleet rollout status [-steps]

• 顺序：先让全部目标机器下载新版本；控制面节点逐台升级，IAM leader 所在的节点最后；然后 edge 先升 1 台试点，观察结束后按批升级，每批里同一故障域最多占一半。

• 每台 edge 升级前先暂停调度（drain），升级后等本机 /readyz 和 watcher 快照都正常，再恢复调度。edge 重启不影响已有的 sandbox。

• 每批开始前检查：本次已升级的机器仍然正常，所有控制面组件就绪。配置了 fleet.prometheus_url 和 fleet.gates 时，观察期内还会检查这些 PromQL。

• 出问题时：失败的机器自动回到原版本并被锁定（pinned），升级暂停。之后可以：

  • opendsecctl fleet rollout resume <id>：接受这些失败，继续升级其余机器；
  • opendsecctl fleet rollout rollback <id>：把已升级的机器按相反顺序分批退回原版本；
  • opendsecctl fleet rollout abort <id>：停在当前位置。

  查明原因后，用 opendsecctl fleet node unpin <名字> 解除锁定。

• 只改配置：opendsecctl fleet config put opendsec.json -note ... 生成新的配置代数，再执行 opendsecctl fleet rollout create -config-gen <代数>。配置里不能有 service_token 或 iam.admin_token。

• 有 fleet 副本时，opendsecops upgrade 和 restart 会拒绝执行；应急时可以加 OPENDSEC_FORCE=1。

6.3 加机器、维护、下线

deploy/prod/opendsecops add-node n17 <ssh地址> <私网地址> edge=n17   # 签证书、安装、启动节点代理
opendsecctl fleet nodes -state pending                               # 节点代理上报后出现在这里
opendsecctl fleet node accept n17 -roles edge=n17 -domain az2        # 下发当前版本和配置并启动

• 新的 edge 不用写进 edges：集群配置里的 edge_template 适用于所有未列出的 edge。
• 给已有机器加角色（例如 e2b）：node set <名字> -roles ... 之后执行 node sync <名字>，一台一台来。只改角色不会启动任何东西，要等这台机器下一次被 rollout 或 sync 才部署。0.11.0-202610230504 及之前的 fleet，在多台机器同时加了角色时，rollout 会互相等待对方的新单元就绪而卡住（SPEC §37.7），这种情况要用 sync。
• 维护：opendsecctl fleet node cordon <名字> 暂停调度（fleet 会一直保持），维护完执行 node uncordon；node evacuate <名字> 在 cordon 之后等这台机器上的 sandbox 全部结束。
• 下线：先 node evacuate <名字>，等 sandbox 全部结束后再 opendsecctl fleet node retire <名字>，节点代理会停掉并禁用这台机器上的组件。没有 evacuate 完（没 cordon、还有 sandbox）时 fleet 拒绝下线；已经不上报心跳的机器可以直接下线。带控制面角色的机器要先把这些角色迁走。

6.4 从 opendsecops 迁到 fleet（一次性，不停机）

1. inventory 里给控制面节点加上 fleet=<id>，opendsec.json 里加上 fleet 段（参照 deploy/prod/cluster.example.json），并把 microvm 的 firecracker、jailer、kernel 指向 /opt/opendsec/current/...。
2. opendsecops certs：补签 fleet、节点代理和 ops 证书。
3. 用 opendsecops 做最后一次滚动升级（带 fleet 和节点代理的版本）：opendsecops release bin/、opendsecops push-config all、OPENDSEC_FORCE=1 opendsecops upgrade <版本>，再 opendsecops start all 启动 fleet 副本。
4. opendsecops install-agent all：每台机器启动节点代理。
5. 导入：opendsecctl fleet release push $OPENDSEC_OPS/releases/<版本>；opendsecctl fleet config put $OPENDSEC_OPS/opendsec.json；opendsecctl fleet import -inventory $OPENDSEC_OPS/inventory -release <版本> -config-gen 1 -domain <故障域>。
6. opendsecctl fleet nodes：确认每台机器都在上报，RUNNING 与 RELEASE 一致，UNITS 全部就绪。