CubeSandbox one-click systemd 部署用户指南：控制节点与计算节点的安装、运维与排障

CubeSandbox one-click systemd 部署用户指南控制节点与计算节点的安装、运维与排障【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox本文基于 CubeSandbox 开源仓库中的 deploy/one-click/USER_GUIDE_zh.md 编写围绕新版 one-click纯 systemd 模式展开。你将掌握如何用install.sh/install-compute.sh完成控制节点与计算节点的部署用systemctl/journalctl进行日常启停、状态查看与日志排障并了解env.example中关键配置项的真实作用与底层实现依据。文中所有命令与配置均可对照仓库源码直接验证。1. 你需要知道的版本变化新版 one-click 安装完成后不再以旧的 shellup/down脚本作为日常运行入口而是自动注册 systemd 单元统一托管所有服务。安装器按节点角色注册两个角色主 target节点角色systemd 主 target入口脚本控制节点controlcube-sandbox-control.targetinstall.sh计算节点computecube-sandbox-compute.targetinstall-compute.sh由此形成一套稳定的心智模型安装install.sh/install-compute.sh停机down.sh健康检查smoke.sh日常启停 / 排障systemctl/journalctlONE_CLICK_DEPLOY_ROLE只用于区分节点角色control/compute不再提供 systemd / 非 systemd 模式的切换开关新安装统一按 systemd 方式运行。这一点在install.sh中体现得很彻底安装器会先stop_existing_systemd_deployment清理旧部署再通过install_systemd_units把全部 unit 装进/etc/systemd/system/最后systemctl enable --now target拉起整条服务链参见 install.sh。从 systemd 单元定义可以直观看到控制节点 target 的依赖关系cube-sandbox-control.target[Unit] DescriptionCube Sandbox control-plane stack Afternetwork-online.target docker.service Wantsnetwork-online.target Wantscube-sandbox-mysql.service cube-sandbox-redis.service cube-sandbox-minio.service Wantscube-sandbox-cubemaster.service cube-sandbox-cube-api.service cube-sandbox-cubeops.service Wantscube-sandbox-cube-templatecenter.service Wantscube-sandbox-cubelet.service Wantscube-sandbox-cube-lifecycle-manager.service Wantscube-sandbox-cube-proxy.service cube-sandbox-coredns.service Wantscube-sandbox-dns.service cube-sandbox-webui.service Wantscube-sandbox-cube-egress-net.service cube-sandbox-cube-egress.service [Install] WantedBymulti-user.target所有cube-sandbox-*.service单元文件位于 deploy/one-click/systemd/共 18 个覆盖 cubelet、cubemaster、cube-api、cubeops、cube-proxy、coredns、dns、mysql、redis、minio、webui、cube-templatecenter、cube-egress、cube-lifecycle-manager 与 s3lvol。2. 控制节点安装2.1 安装步骤在目标机上解压发布包后执行tar -xzf cube-sandbox-one-click-version.tar.gz cd cube-sandbox-one-click-version cp env.example .env sudo ./install.sh固定安装目录为/usr/local/services/cubetoolbox安装完成后会自动完成三件事把 systemd unit 安装到/etc/systemd/system/按控制节点角色执行systemctl enable --now cube-sandbox-control.target运行一轮 quickcheck默认开启对应ONE_CLICK_RUN_QUICKCHECK1。控制节点安装成功后默认可通过 WebUI 访问http://目标机IP:12088其中12088即 env.example 中的WEB_UI_HOST_PORTWebUI 容器cube-webui由 nginx 反代到host.docker.internal:3010即 CubeOps。2.2 安装模式与配置优先级源码视角install.sh支持三种安装/升级模式install.sh模式行为--modeinstall全新安装重置既有配置--modeupgrade保留配置的升级要求已存在安装--modeauto缺省检测到已有安装则升级否则安装交互式终端会给出[Y/n]确认非交互环境直接走升级配置来源的优先级为CLI 命令行参数 .env文件 进程环境变量 内置默认值。安装器在解析参数、加载.env后会再次重放 CLI 覆盖确保命令行传入的值始终胜出install.sh。升级时还会基于env.example基线、旧的.one-click.env与新.env做三方合并three-way merge从而把用户自定义值与默认值区分开跨版本升级不丢配置。2.3 安装前的预检preflightinstall.sh在改动系统之前会先跑一组**快速失败fail-fast**预检install.sh主要包括硬件预检必须存在/dev/kvm否则提示使用deploy/pvm/pvm_setup.sh构建 PVM 环境系统内存至少 8GBCUBE_MIN_MEMORY_KB只能调大不能调小PVM 一致性预检若宿主已加载kvm_pvm内核模块则必须设置CUBE_PVM_ENABLE1使用 PVM 客体内核vmlinux-pvm否则 VM 模板创建会失败文件系统预检/data/cubelet必须位于XFS文件系统上cgroup v2 预检根 cgroup 需暴露cpu控制器multipathd等实时线程常导致无法写入cpueBPF 预检内核需支持bpf文件系统且/sys/fs/bpf已挂载Cubelet 内置网络运行时的 eBPF map 依赖它外部依赖连通性预检配置了外部 MySQL/PostgreSQL/Redis 时用mysqladmin/psql/redis-cli分别做连通性与凭证校验ONE_CLICK_EXTERNAL_DEP_TIMEOUT控制超时默认 5 秒CIDR 冲突预检CUBE_SANDBOX_NETWORK_CIDR必须是掩码在 /16~/24 之间的 IPv4 私网段且不与宿主接口冲突DNS 预检要求resolvectl或 NetworkManager或显式设置CUBE_PROXY_DNSMASQ_MODEstandalone。此外安装器还会把 CubeMaster 的conf.yaml、CubeTemplateCenter 的conf.yaml中的占位符替换为.env实际值MySQL/Redis 端口、账号、密码、监听地址等确保 TC 与 CubeMaster 指向同一个 CubeDB避免“静默分脑”。3. 计算节点安装计算节点只运行 compute 侧所需服务cubelet 内置 network runtime cube-egress 等不部署控制面组件也不部署 MinIO。3.1 安装步骤在计算节点机器上tar -xzf cube-sandbox-one-click-version.tar.gz cd cube-sandbox-one-click-version cp env.example .env至少修改.env中的两个关键项ONE_CLICK_DEPLOY_ROLEcompute ONE_CLICK_CONTROL_PLANE_IP10.0.0.11可选但强烈建议若要使用 S3 Volume把控制节点回填的CUBE_S3_*拷贝到计算节点.env# 在控制节点执行把输出拷贝到计算节点 .env grep ^CUBE_S3_ /usr/local/services/cubetoolbox/.one-click.env计算节点不部署 MinIO。缺失CUBE_S3_*时仅打印黄色警告并继续安装S3 卷插件在配置前不可用。如果要显式指定当前计算节点 IP避免安装器自动探测 eth0再补充CUBE_SANDBOX_NODE_IP10.0.0.12然后执行sudo ./install-compute.sh从源码看install-compute.sh本质上是设置ONE_CLICK_DEPLOY_ROLEcompute后直接exec同一个install.shinstall-compute.sh因此前面描述的全部预检、systemd 单元安装、quickcheck 逻辑同样生效只是按 compute 角色裁剪组件例如generate_cubemaster_config_ports、generate_templatecenter_config等控制面步骤会直接跳过。3.2 网络要求计算节点与控制节点之间有两条固定的 TCP 通路方向端口用途计算节点 → 控制节点8089/tcpCubeMaster HTTPREST控制节点 → 计算节点9999/tcpcubelet 内置网络运行时 / egress 策略下发等计算节点的 Cubelet 向 CubeOps 注册时默认使用ONE_CLICK_CONTROL_PLANE_IP:3010ONE_CLICK_CONTROL_PLANE_CUBEOPS_ADDR可显式覆盖CubeMaster 地址默认派生为ONE_CLICK_CONTROL_PLANE_IP:8089ONE_CLICK_CONTROL_PLANE_CUBEMASTER_ADDR可显式覆盖。安装器会把最终解析出的ONE_CLICK_CONTROL_PLANE_CUBEOPS_ADDR持久化到.one-click.envinstall.sh。4. 常用命令4.1 基础健康检查在发布包目录下执行sudo ./smoke.shsmoke.sh会加载当前目录.env然后直接调用安装目录中的 quickchecksmoke.shsudo /usr/local/services/cubetoolbox/scripts/one-click/quickcheck.shquickcheck 的检查范围详见 quickcheck.shsystemd units 是否activecontrol 角色会检查 cubelet、mysql、redis、minio、cubemaster、cube-templatecenter、cube-api、cubeops、cube-proxy、coredns、dns、webui 等全部单元控制节点依赖容器是否 readydocker inspect读取健康状态覆盖cube-sandbox-mysql、cube-sandbox-redis、cube-sandbox-minio、cube-proxy、cube-proxy-coredns、cube-webuicubelet内置 network runtime 的 egress dump 接口http://127.0.0.1:9998/v1/policies/dump、cubemaster /notify/health、cube-api /health、cubeops /health等健康接口socket/data/cubelet/cubelet.sock、配置文件与运行时资源Cubelet/config/config.toml、cube-shim/conf/config-cube.toml、cube-kernel-scf/vmlinux、cube-image/cube-guest-image-cpu.img、cube-agent/cube-agent.ext4、cubeproxy/global.conf等是否存在计算节点额外检查节点是否已在 CubeOps 完成注册查询http://ops_addr/internal/v1/nodes/node_id。重要quickcheck 的探测是重试型的而不是“探一次就失败”。它以一个共享的 wall-clock 预算默认CUBE_QUICKCHECK_READY_TIMEOUT120秒上限 3600 秒可通过CUBE_QUICKCHECK_READY_TIMEOUT0恢复严格 fail-fast覆盖全部探测从而消除服务刚启动时 systemd 已“active”但 socket/接口尚未就绪导致的偶发假失败。容器级 readiness 另有CUBE_QUICKCHECK_CONTAINER_TIMEOUT默认等于总预算可单独收紧。4.2 停止服务sudo ./down.shdown.sh会读取角色后按当前安装角色停止对应主 targetdown.sh控制节点cube-sandbox-control.target计算节点cube-sandbox-compute.target从源码看down.sh明确不删除s3lvol 的每节点状态/data/cubelet/rcow/wal_bdev.img、lvstore/bstore 元数据下次安装/启动时会重新 attach 并重放这是有意的数据保护设计。5. 用 systemd 管理服务5.1 查看角色主 target 状态控制节点sudo systemctl status cube-sandbox-control.target计算节点sudo systemctl status cube-sandbox-compute.target5.2 启动角色服务控制节点sudo systemctl start cube-sandbox-control.target计算节点sudo systemctl start cube-sandbox-compute.target说明安装时已经执行过enable --now一般不需要再手工enable。5.3 停止角色服务控制节点sudo systemctl stop cube-sandbox-control.target计算节点sudo systemctl stop cube-sandbox-compute.target5.4 查看常用单元状态控制节点常见单元sudo systemctl status \ cube-sandbox-cubelet.service \ cube-sandbox-cubemaster.service \ cube-sandbox-cube-api.service \ cube-sandbox-mysql.service \ cube-sandbox-redis.service \ cube-sandbox-minio.service \ cube-sandbox-cube-proxy.service \ cube-sandbox-coredns.service \ cube-sandbox-dns.service如果启用了 WebUI再看sudo systemctl status cube-sandbox-webui.service计算节点常见单元sudo systemctl status \ cube-sandbox-cubelet.service完整单元清单deploy/one-click/systemd/cube-sandbox-cubelet.service核心运行时含内置 network runtime计算与控制节点均有cube-sandbox-cubemaster.service/cube-sandbox-cube-api.service/cube-sandbox-cubeops.service控制面三件套cube-sandbox-cube-templatecenter.service镜像模板构建CubeMaster 无进程内构建回退属于必备单元cube-sandbox-cube-proxy.service/cube-sandbox-coredns.service/cube-sandbox-dns.service代理、沙箱内 DNS 解析与 dnsmasqcube-sandbox-mysql.service/cube-sandbox-redis.service/cube-sandbox-minio.service本地依赖容器systemd 托管 docker 容器cube-sandbox-webui.serviceWebUIWEB_UI_ENABLE1时cube-sandbox-cube-lifecycle-manager.service沙箱生命周期管理cube-sandbox-cube-egress.service/cube-sandbox-cube-egress-net.service透明出口 egress 策略与底层网络设备cube-sandbox-s3lvol.serviceS3 COW 块存储数据面默认 disabled由ONE_CLICK_ENABLE_S3LVOL控制5.5 查看日志例如sudo journalctl -u cube-sandbox-cubelet.service -n 200 --no-pager sudo journalctl -u cube-sandbox-cubemaster.service -n 200 --no-pager sudo journalctl -u cube-sandbox-cube-api.service -n 200 --no-pager实时追日志sudo journalctl -u cube-sandbox-cubelet.service -f6. 常见运维动作6.1 重启单个服务sudo systemctl restart cube-sandbox-cubelet.service控制节点上也常见sudo systemctl restart cube-sandbox-cubemaster.service sudo systemctl restart cube-sandbox-cube-api.service6.2 重做一轮健康检查sudo ./smoke.sh或sudo /usr/local/services/cubetoolbox/scripts/one-click/quickcheck.sh6.3 查看节点注册信息控制节点cubeopscli --address 127.0.0.1 --port 3010 node listcubeopscli与cubemastercli仅在控制节点安装时被链接到/usr/local/bin/计算节点会移除这两个软链见 install.sh。7. 手动更新核心二进制如果你拿到的是手动更新包例如cube-manual-update-*.tar.gz可以执行sudo ./deploy-manual.sh /path/to/cube-manual-update-*.tar.gz该脚本会备份当前核心二进制替换cubemaster/cubemastercli/cubelet/cubecli按角色处理network runtime 已内置在cubelet中用systemctl restart重启相关核心服务默认再跑一轮 quickcheck。如需跳过 quickchecksudo ONE_CLICK_SKIP_QUICKCHECK1 ./deploy-manual.sh /path/to/cube-manual-update-*.tar.gz更新脚本本体位于 deploy/one-click/deploy-manual.sh与install.sh、down.sh、smoke.sh一样是发布包内直接可执行的入口脚本。8. 推荐排障顺序当安装或运行异常时建议按下面顺序排查第一步看角色 targetsudo systemctl status cube-sandbox-control.target # 或 sudo systemctl status cube-sandbox-compute.target第二步跑 quickchecksudo ./smoke.sh第三步看关键服务日志sudo journalctl -u cube-sandbox-cubelet.service -n 200 --no-pager控制节点再补充sudo journalctl -u cube-sandbox-cubemaster.service -n 200 --no-pager sudo journalctl -u cube-sandbox-cube-api.service -n 200 --no-pager sudo journalctl -u cube-sandbox-mysql.service -n 200 --no-pager sudo journalctl -u cube-sandbox-redis.service -n 200 --no-pager第四步确认配置是否写对重点检查安装目录中的运行时环境文件/usr/local/services/cubetoolbox/.one-click.env尤其是以下几个关键项变量说明ONE_CLICK_DEPLOY_ROLE节点角色control或computeONE_CLICK_CONTROL_PLANE_IP计算节点指向的控制节点 IPONE_CLICK_CONTROL_PLANE_CUBEMASTER_ADDR计算节点显式指定的 CubeMaster 地址可选CUBE_SANDBOX_NODE_IP当前节点显式 IPWEB_UI_ENABLE是否启用 WebUIquickcheck 在探测失败时会打印精确的失败原因例如“systemd unit failed: ...”“endpoint not healthy: ...”“container is not ready: ...”“CubeOps node registration missing IP...”排障时优先阅读 quickcheck 输出可以大幅缩小范围。9. 重要说明9.1 新版本没有“是否启用 systemd”的开关不需要也不应该再通过环境变量选择 systemd / 非 systemd 模式。新安装统一按 systemd 方式运行。9.2 旧 shell 启停脚本不是新版本操作入口对于新版本用户日常操作请使用install.shinstall-compute.shdown.shsmoke.shsystemctljournalctl旧的 legacy shell 启停逻辑up.sh/up-compute.sh等仅用于安装器兼容历史版本升级不属于新版本的用户操作界面。install.sh中stop_existing_legacy_deployment正是为“升级前停止旧 nohup/pidfile 部署”保留的桥接路径install.sh。9.3 安装目录中的运行时环境文件安装后实际生效的环境文件是/usr/local/services/cubetoolbox/.one-click.env安装器会把.env的内容复制进去并补充运行期所需字段节点 IP、网卡名、控制面地址、MinIO 凭证、S3 配置、数据库驱动、模板回调 token、s3lvol 运行时参数等且该文件被chmod 600保护其中包含DATABASE_URL与外部依赖密码等敏感信息。安装器同时会把env.example作为基线副本保存到安装目录供下一次升级做三方合并。如果你后续修改了这里的配置通常需要按变更内容重启相关 systemd 服务后才会生效。10. 配置项深度解读env.example 关键变量发布包内的 env.example 是唯一的“目标机环境模板”安装前cp env.example .env并按需覆盖。以下按功能域整理核心变量及其默认值未注释项即默认值。10.1 安装与角色变量默认值说明ONE_CLICK_RUN_QUICKCHECK1安装完成后是否运行一轮 quickcheckONE_CLICK_DEPLOY_ROLEcontrolcontrol为全功能一体化节点compute为注册到既有控制面的纯计算节点ONE_CLICK_CONTROL_PLANE_IP空计算节点必填control 角色不需要ONE_CLICK_CONTROL_PLANE_CUBEMASTER_ADDR由 IP 派生:8089计算节点显式指定 CubeMaster HTTP 地址ONE_CLICK_CONTROL_PLANE_CUBEOPS_ADDR由 IP 派生:3010计算节点显式指定 CubeOps 注册地址CUBE_SANDBOX_NODE_IP自动探测 eth0显式指定当前节点 IPCUBE_PVM_ENABLE0是否安装 PVM 客体内核cube-kernel-scf/vmlinux10.2 健康检查调参变量默认值说明CUBE_QUICKCHECK_READY_TIMEOUT120quickcheck 共享就绪预算秒上限 36000恢复严格 fail-fastCUBE_QUICKCHECK_READY_INTERVAL2探测轮询间隔秒CUBE_QUICKCHECK_CONTAINER_TIMEOUT同总预算单个依赖容器的就绪预算可更早失败“卡死”的容器10.3 网络与 egress变量默认值说明CUBE_SANDBOX_NETWORK_CIDR192.168.0.0/18Cubelet 默认CubeVS 沙箱 IP 分配网段掩码必须 /16~/24CUBE_SANDBOX_CUBE_ROUTER_ENABLE0是否启用路由感知出口cube-router 设备走内核路由栈CUBE_L7_MARK_HTTP/CUBE_L7_MARK_HTTPS/CUBE_L7_MARK_MASK0xCE010000/0xCE020000/0xFFFF0000L7 egress 的 skb-mark写入/etc/cubeegress/l7-marks.conf安装器会校验取值合法性10.4 容器镜像与镜像源变量默认值说明CUBE_PROXY_COREDNS_IMAGE等cube-sandbox-image.tencentcloudcr.com/...依赖容器镜像可指向私有仓库或sha256摘要以支持离线安装MIRROR空国际仓库cn切换到中国区仓库只影响 cube-proxy / cube-lifecycle-manager / cube-egress 与 MinIOONE_CLICK_ENABLE_TENCENT_DOCKER_MIRROR0是否给 docker daemon 配置腾讯镜像加速器10.5 外部 MySQL / PostgreSQL / Redis默认install.sh启动本地 MySQL 与 Redis 容器systemd 托管。要复用既有服务设置CUBE_EXTERNAL_MYSQL_HOST/CUBE_EXTERNAL_POSTGRES_HOST/CUBE_EXTERNAL_REDIS_HOST或 Redis Sentinel 的CUBE_EXTERNAL_REDIS_MASTER_NAMECUBE_EXTERNAL_REDIS_SENTINEL_NODES。安装器会 patch CubeMasterconf.yaml、把 CubeAPI/CubeOps 的DATABASE_URL指向外部端点并mask 本地 MySQL/Redis systemd 单元避免 target 的Wants再次拉起本地容器install.sh。若使用外部端点却保留默认弱口令cube_pass/ceuhvu123安装器会打印显式警告。10.6 MinIO 与 S3 卷插件变量默认值说明CUBE_SANDBOX_MINIO_ENABLED1控制节点是否部署本地 MinIO 容器CUBE_SANDBOX_MINIO_ROOT_USER/_PASSWORDcubeminio/ 空密码为空时安装器生成 24 位随机串并写入.one-click.envCUBE_S3_ENDPOINT等CUBE_S3_*空S3 卷插件的事实来源volume-s3.conf控制节点启用 MinIO 时由安装器自动回填控制节点启用 MinIO 时安装器会用fill_s3_from_local_minio自动把CUBE_S3_*填充为本地 MinIO 的连接信息计算节点则按“控制节点grep ^CUBE_S3_”的方式手工拷贝。10.7 WebUI 与端口变量默认值说明WEB_UI_ENABLE1是否启用 WebUI 容器WEB_UI_HOST_PORT12088WebUI 对外端口即安装成功后的访问地址CUBEMASTER_ADDR/CUBEMASTER_HTTP_BIND127.0.0.1:8089/0.0.0.0CubeMaster 监听默认绑定 0.0.0.0 以便计算节点访问CUBE_API_BIND0.0.0.0:3000CubeAPI 监听CUBE_OPS_BIND0.0.0.0:3010CubeOps 监听WebUI nginx 通过 host.docker.internal 反代10.8 s3lvol可选ONE_CLICK_ENABLE_S3LVOL1会启用cube-sandbox-s3lvol.serviceS3/COS 之上的远程 COW 块存储NVMe/TCP 目标。相关RCOW_*变量WAL 镜像大小、日志镜像大小、薄供给容量、CPU mask、内存、监听地址等默认与rcow_common.sh对齐WAL 镜像在首次安装时创建且之后永不重建约 512GiB 稀疏文件由RCOW_WAL_MB RCOW_JOURNAL_MB RCOW_CACHE_MB决定。11. 最短操作清单控制节点cp env.example .env sudo ./install.sh sudo ./smoke.sh sudo ./down.sh sudo systemctl start cube-sandbox-control.target计算节点cp env.example .env # 编辑 ONE_CLICK_DEPLOY_ROLEcompute # 编辑 ONE_CLICK_CONTROL_PLANE_IPcontrol-node-ip sudo ./install-compute.sh sudo ./smoke.sh sudo ./down.sh sudo systemctl start cube-sandbox-compute.target12. 相关文件索引用户指南原文deploy/one-click/USER_GUIDE_zh.md环境变量模板deploy/one-click/env.example安装入口control/compute 共用deploy/one-click/install.sh计算节点安装包装器deploy/one-click/install-compute.sh停机脚本deploy/one-click/down.sh健康检查入口deploy/one-click/smoke.shquickcheck 探针实现deploy/one-click/scripts/one-click/quickcheck.shsystemd 单元目录deploy/one-click/systemd/手动更新脚本deploy/one-click/deploy-manual.sh相关源码组件CubeMasterCubeMaster/、CubeletCubelet/、CubeAPICubeAPI/、CubeOpsCubeOps/、CubeProxyCubeProxy/、CubeTemplateCenterCubeTemplateCenter/【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考