CubeSandbox 服务管理与日志排查完整指南：systemd 单元、业务日志边界与故障恢复

CubeSandbox 服务管理与日志排查完整指南：systemd 单元、业务日志边界与故障恢复

发布时间：2026/9/16 13:02:47
CubeSandbox 服务管理与日志排查完整指南：systemd 单元、业务日志边界与故障恢复 CubeSandbox 服务管理与日志排查完整指南systemd 单元、业务日志边界与故障恢复【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox本指南面向已经通过新版systemd 托管一键安装包部署好 CubeSandbox 的运维与开发者系统讲解控制节点 / 计算节点上 14 个 systemd 单元的职责与依赖关系、配置修改后如何精准重启生效、业务日志/data/log/与启动期日志journalctl的边界划分以及服务挂掉、沙箱创建失败、Dashboard 无法访问等典型故障的排查路径。读完本页你将掌握整套服务的日常巡检、诊断打包与完整启停的实战方法。::: tip 适用范围 本页对应新版systemd 托管的一键安装包。若机器上仍以up-with-deps.sh/down-with-deps.sh作为日常入口说明还是 pre-systemd 老版本重新执行最新一键安装包即可平滑升级安装器内置了对老部署的接管逻辑。 :::TL;DR 一分钟备忘# 1. 看整台机器上 cube 系列服务都还活着吗 sudo systemctl --no-legend list-units cube-sandbox-* # 2. 改了配置 → 重启对应服务最常见的几个 sudo systemctl restart cube-sandbox-cube-api.service sudo systemctl restart cube-sandbox-cubemaster.service sudo systemctl restart cube-sandbox-cubelet.service # 3. 看业务行为日志请求/统计/审计/VMM—— 全都在 /data/log/不在 journal sudo tail -F /data/log/Cubelet/Cubelet-req.log sudo tail -F /data/log/CubeMaster/cubemaster-req.log sudo tail -F /data/log/CubeAPI/cube-api-$(date %F).log sudo tail -F /data/log/CubeVmm/vmm.log # 沙箱 VMM 创建过程 sudo tail -F /data/log/cube-proxy/error.log # 代理错误 # 4. 看启动失败 / 进程异常退出 → journalctl sudo journalctl -u cube-sandbox-cube-api.service -n 200 --no-pager # 5. 一键打包诊断信息含 /data/log 的 tail 配置 dmesg 进程快照 sudo /usr/local/services/cubetoolbox/scripts/cube-diag/collect-logs.sh::: warning 业务日志在/data/log/不在journalctl这是新用户最容易踩的一点CubeSandbox 各组件只把启动期 stdout/stderr 留给 journal请求 / 调度 / 统计 / 审计 / VMM 创建过程等业务日志全部直接写到/data/log/Module/。如果你想看「最近一小时谁创建了沙箱」要去/data/log/不要去journalctl。 :::服务总览新版一键安装会把 systemd 单元注册到/etc/systemd/system/并按节点角色聚合到两个 target 之下。这些单元文件的源码可以在仓库的 deploy/one-click/systemd/ 目录下直接查看。角色聚合 targetTarget作用节点角色cube-sandbox-control.target控制节点默认 all-in-one的全部服务controlcube-sandbox-compute.target计算节点的最小子集compute::: tip 这是怎么生效的 从仓库中的 cube-sandbox-control.target 可以看到Target 通过Wants列出自己要拉起的 service同时各 service 通过PartOfcube-sandbox-control.target反向声明归属。所以systemctl stop cube-sandbox-control.target会把所有PartOf的 service 一起停掉不需要逐个写名字。计算节点侧的 cube-sandbox-compute.target 只Wantscube-sandbox-cubelet.service与 egress 相关单元与文档所述「计算节点的最小子集」一致。 :::服务清单单元进程形态端口 / 监听出现在上游依赖cube-sandbox-mysql.serviceDocker 容器3306controldockercube-sandbox-redis.serviceDocker 容器6379controldockercube-sandbox-cubemaster.service宿主机进程8089controlmysql, rediscube-sandbox-cube-api.service宿主机进程3000E2B 兼容 APIcontrolcubemastercube-sandbox-cubelet.service宿主机进程9999gRPC、HTTP 诊断接口control / compute内置 network runtime /data/cubeletXFScube-sandbox-coredns.serviceDocker 容器127.0.0.54:53或169.254.254.53:53controldockercube-sandbox-cube-proxy.serviceDocker 容器443TLS/80/9090gRPCcontroldocker, rediscube-sandbox-dns.serviceoneshot无常驻进程—controlcorednsBindsTocube-sandbox-webui.serviceDocker 容器12088controldocker, cube-api补充说明可从仓库单元文件印证cube-sandbox-cubelet.service采用TypeforkingPIDFile/run/cube-sandbox-systemd/cubelet.pid并声明Delegateyes、KillModeprocess同时PartOfcube-sandbox-control.target cube-sandbox-compute.target即一个节点同时属于两个 target 也能被正确纳管。启动前通过ExecStartPre执行prepare-compute-role.sh准备计算节点角色并通过RequiresMountsFor/data/cubelet /data/cube-shim /data/snapshot_pack保证容器层存储挂载就绪见 cube-sandbox-cubelet.service。cube-sandbox-cubemaster.service显式设置了TimeoutStartSec60s/TimeoutStopSec30s注释说明这是为了覆盖发行版过短的默认值给 SIGTERM 留出排空 DB 连接、flush 状态的余量ExecStartPost有cubemaster-postcheck.sh健康检查见 cube-sandbox-cubemaster.service。cube-sandbox-cube-proxy.service的TimeoutStartSec180s是因为首次启动需要经 compose 构建 cube-proxy 镜像TimeoutStopSec30s则避免 OpenCloudOS 等发行版默认DefaultTimeoutStopUSec5s过短导致优雅关闭被 SIGKILL、留下孤儿 Exited 容器见 cube-sandbox-cube-proxy.service。cube-sandbox-dns.service是TypeoneshotRemainAfterExityesBindsTocube-sandbox-coredns.servicecoredns 一停它也会跟着停TimeoutStartSec120s是为 standalone-dnsmasq 后端的多次有界等待留出余量见 cube-sandbox-dns.service。启动依赖关系控制节点docker.service ├─ mysql.service ─┐ ├─ redis.service ─┼─ cubemaster.service ─ cube-api.service ─ webui.service │ └─ cube-proxy.service └─ coredns.service ─ dns.service (oneshot, BindsTo coredns) network-online.target └─ cubelet.service内置 network runtime依赖只通过After/Wants表达启动顺序运行期某个上游挂了不会自动把下游也带翻 —— 所以 cubelet 不会因为 cube-api 挂了而被一起重启反过来也是一样唯一的例外是dns.service与coredns.service之间的BindsTo强绑定关系。重启服务场景 A改了配置想让单个服务生效最常见的两种配置入口顶层环境/usr/local/services/cubetoolbox/.one-click.env组件原生配置Cubelet/config/config.toml、Cubelet/dynamicconf/conf.yaml、CubeMaster/conf.yaml、cubeproxy/global.conf、coredns/Corefile改完之后重启直接读这份配置的那个服务# 改了 cubelet 配置 sudo systemctl restart cube-sandbox-cubelet.service # 改了 cubemaster 配置 sudo systemctl restart cube-sandbox-cubemaster.service # 改了 .one-click.env 中的 CUBE_API_* sudo systemctl restart cube-sandbox-cube-api.service # 改了 cubeproxy/global.conf sudo systemctl restart cube-sandbox-cube-proxy.service # 改了 coredns/Corefile sudo systemctl restart cube-sandbox-coredns.service::: warning 改 systemd unit 文件本身的情况 如果你直接动了/etc/systemd/system/cube-sandbox-*.service文件本身需要先 reloadsystemd 才会读到新内容sudo systemctl daemon-reload sudo systemctl restart cube-sandbox-service.service但如果你只是改了 helper 脚本/usr/local/services/cubetoolbox/scripts/systemd/*.sh不需要daemon-reload下一次restart就会重新拉起脚本生效。 :::CubeMaster 配置项 {#cubemaster-settings}路径/usr/local/services/cubetoolbox/CubeMaster/conf.yamlone-click 包内来自仓库的 configs/single-node/cubemaster.yaml。cubelet_conf段中的主要超时字段配置项说明default_timeout_insec客户端不传timeout时集群默认的沙箱空闲 TTL秒。未配置或 0表示不设集群级空闲超时沙箱不会因空闲被自动回收除非客户端显式传timeout。仓库默认为-1即“无集群默认”。生产环境若需自动回收未带 TTL 的沙箱可改为正数如300。create_timeout_insec仅限制创建/调度 RPC 的截止时间不是沙箱空闲 TTL。未配置时默认600。common_timeout_insecCubeMaster 访问 Cubelet 的通用 RPC 超时非 create 专用。create_image_timeout_insecCubeMaster 调用单个计算节点下载镜像的超时时间。它包含下载、校验和保存 rootfs artifact 的时间。大镜像、低带宽或磁盘较慢时可适当调大。默认值300秒。app_snapshot_timeout_insecCubeMaster 调用单个计算节点创建模版的超时时间。它包含制作模版时启动临时虚拟机、等待 readiness probe、保存内存和磁盘状态、清理临时虚拟机并返回结果的总时间。未配置或配置为非正数时使用默认值300秒。网络较差或模版较大时可适当调大。这些字段在源码层面有直接对应CubeMaster的配置结构体 CubeMaster/pkg/base/config/config.go 中CubeletConf定义了CommonTimeoutInsec、CreateImageTimeoutInSec、AppSnapshotTimeoutInSec、DefaultTimeoutInsec、CreateTimeoutInsec等字段字段注释明确标注了「Server default idle TTL when the client omits timeout」服务端默认空闲 TTL与「Create RPC / scheduling deadline; decoupled from idle TTL」创建 RPC / 调度截止时间与空闲 TTL 解耦的语义差异。实际默认值-1、300、600等与配置模板一致可对照 CubeMaster/conf.yaml 查看完整配置。下载镜像和创建模版的 timeout 相互独立分别从对应 RPC 发起时开始计时。配置示例cubelet_conf: create_image_timeout_insec: 300 app_snapshot_timeout_insec: 600修改上述任一 CubeMaster 配置后需要重启 CubeMastersudo systemctl restart cube-sandbox-cubemaster.service相关说明见沙箱生命周期 — 设计与运维要点。场景 B服务挂了 / 反复重启每个 service 都配了Restarton-failureRestartSec2s进程崩一次会自动重启。但如果反复 fail需要先看清楚原因再重启。1. 先看一眼当前状态sudo systemctl status cube-sandbox-cube-proxy.service --no-pager重点看Active: failed/Active: activating (start-post)是不是还在尝试Restart Counter是否反复增长卡在重启循环输出末尾自动带的最近 10 条 journal2. 看启动期日志sudo journalctl -u cube-sandbox-cube-proxy.service -n 200 --no-pager适合定位脚本写法问题、ExecStart 报错、容器拉不到镜像、apk/apt网络问题、ExecStartPost 健康检查超时。3. 看业务日志如果服务能起来但行为异常业务日志在/data/log/不在 journalsudo tail -200 /data/log/Cubelet/Cubelet-req.log sudo tail -200 /data/log/CubeMaster/cubemaster-req.log sudo tail -200 /data/log/CubeAPI/cube-api-$(date %F).log4. 重置 failed 计数后再启sudo systemctl reset-failed cube-sandbox-cube-proxy.service sudo systemctl restart cube-sandbox-cube-proxy.service场景 C整套重启 / 整机维护后复位# 控制节点 sudo systemctl restart cube-sandbox-control.target # 计算节点 sudo systemctl restart cube-sandbox-compute.target或者发布包目录下sudo ./down.sh sudo systemctl start cube-sandbox-control.target::: tip 重启 target 等于按依赖顺序重启所有 PartOf 服务 target 本身没有进程restart target 时 systemd 会顺序重启所有PartOfcube-sandbox-control.target的 service。这条命令是替代「逐个写一长串 service 名」的快捷方式。 :::场景 D完整下线停止整套服务# 推荐用发布包内的脚本自动按角色走 sudo /root/cube-sandbox-one-click-version/down.sh # 等价命令 sudo systemctl stop cube-sandbox-control.target # 控制节点 sudo systemctl stop cube-sandbox-compute.target # 计算节点down.sh不会删除任何数据MySQL / Redis 数据卷、/data/cubelet、/data/log/...等都保留下次start即可恢复。查看日志CubeSandbox 有多种日志来源其中也包括各组件自己的容器内日志。宿主机侧主要有以下两个入口来源包含什么在哪里看业务行为日志推荐入口请求、调度决策、stat、audit、VMM 启动过程/data/log/Module/启动期日志systemd 拉起 / hook / ExecStartPost / 退出码 / 容器 build 输出journalctl -u unit/data/log/业务日志重点⚠️ Cubelet / CubeMaster / CubeAPI / CubeShim / VMM 的「业务请求 统计 审计 VMM 创建过程」日志全部都写到/data/log/不会进 journalctl请直接读文件。模块目录主要文件Cubelet/data/log/Cubelet/Cubelet-req.log请求Cubelet-stat.log指标/统计CubeMaster/data/log/CubeMaster/cubemaster-req.logCubeAPI/data/log/CubeAPI/cube-api-YYYY-MM-DD.log按天滚动CubeShim/data/log/CubeShim/cube-shim-req.log、cube-shim-stat.logHypervisor (VMM)/data/log/CubeVmm/vmm.log每次创建沙箱都会写 VMM 日志cube-proxy/data/log/cube-proxy/error.log、access.log见下文常用命令# 跟踪 Cubelet 收到的请求 sudo tail -F /data/log/Cubelet/Cubelet-req.log # 跟踪 CubeAPIE2B 兼容层按天滚动的日志 sudo tail -F /data/log/CubeAPI/cube-api-$(date %F).log # 沙箱启动慢 / 启动失败看 VMM 日志 sudo tail -200 /data/log/CubeVmm/vmm.logCubeShim 和 VMM 日志轮转CubeShim 和 VMM 运行期间会保持日志文件打开。CubeShim 通过内部每 30 分钟轮转事件 reopen。VMM 控制线程自己持有 monotonictimerfd每小时发出已有的LOG_CTRL_REOPEN控制记录。reopen 由固定周期驱动宿主机执行“renamecreate”后会在下一次计划中的 reopen 时切换到新文件而不是在任意一次写入时立即检测。该定时器由 VMM 控制线程持有不依赖延迟 logger 初始化也不会由 vCPU/API 线程创建。因此宿主机侧仍应按小时执行轮转并使用“renamecreate”方式不要使用copytruncate。例如将下面内容保存为/etc/logrotate.d/cubesandbox并确保宿主机每小时执行一次logrotate/data/log/CubeVmm/vmm.log /data/log/CubeShim/*.log { hourly rotate 24 missingok notifempty compress delaycompress create 0640 root root }rotate 24表示保留 24 个小时文件可按实际保留周期调整。delaycompress会将最新的轮转文件延迟一个周期压缩因为 writer 在下一次计划中的 reopen 之前可能仍使用旧 fd。CubeShim 每 30 分钟触发一次内部事件VMM 控制线程每小时发送一次 reopen 控制事件。不需要postrotate信号或重启服务该策略保证宿主机侧 retention 有界但不承诺对任意手工轮转立即响应也不支持copytruncate。示例使用root root因为随附的一键部署 systemd 服务以 root 运行。如果 CubeShim 或 VMM 使用其他账号运行请把create的 owner 和 group 改成对应账号否则新建文件可能无法被 reopen。示例中的0640只适用于logrotate创建的文件CubeShim 和 VMM writer 本身仍遵循进程的 umask。journalctl启动期日志journalctl 看的是进程被 systemd 拉起到稳定运行或失败退出期间的 stdout/stderr主要用于启动失败的退出码 / 异常信息ExecStart / ExecStartPost / ExecStop 各 hook 的输出容器拉镜像、docker build/apk update等失败信息服务被自动重启的次数与原因# 最近 200 行 sudo journalctl -u cube-sandbox-cubelet.service -n 200 --no-pager # 实时追踪 sudo journalctl -u cube-sandbox-cubemaster.service -f # 看「上次启动以来」全部 sudo journalctl -u cube-sandbox-cube-api.service -b::: warning journalctl 里没有业务请求日志 进程跑稳之后的 stdout/stderr 输出非常少因为各组件都把业务日志直接写到/data/log/Module/。如果你想看「最近一小时谁创建了沙箱」journalctl 是错的入口请去/data/log/CubeMaster/cubemaster-req.log或/data/log/Cubelet/Cubelet-req.log。 :::cube-proxy 宿主机日志cube-proxy是基于 OpenResty 的 nginx 容器。一键部署会将宿主机目录/data/log/cube-proxy/bind mount 到容器内同一路径容器重启后日志仍然保留可以直接从宿主机读取sudo tail -200 /data/log/cube-proxy/error.log sudo tail -200 /data/log/cube-proxy/access.log容器内仍使用同一个/data/log/cube-proxy/路径不需要重新构建镜像。一键打包诊断信息如果要拿一整套日志去问社区或提 issue用内置的诊断收集脚本sudo /usr/local/services/cubetoolbox/scripts/cube-diag/collect-logs.sh它会把以下内容统一收集到cube-diag-时间戳/目录下/data/log/CubeMaster|Cubelet|CubeAPI|CubeShim|CubeVmm/的 tail/data/log/cube-proxy/下的 access/error 日志dmesg/ 进程列表 / 端口 / 挂载 / cgroup / cpuinfo 等环境快照主要配置文件敏感信息已脱敏打包后整体上传tar czf cube-diag-ts.tar.gz cube-diag-ts/支持选择性收集例如只取 cubelet dmesgsudo /usr/local/services/cubetoolbox/scripts/cube-diag/collect-logs.sh \ --module cubelet --module dmesg --lines 500完整选项见--help。常用运维动作速查我想干什么命令列出当前角色全部 cube 服务systemctl --no-legend list-units cube-sandbox-*查看某个服务状态systemctl status cube-sandbox-service.service查看某个 target 的依赖图systemctl list-dependencies cube-sandbox-control.target启动 / 停止 / 重启单个服务systemctl {start\|stop\|restart} cube-sandbox-service.service启动 / 停止 / 重启整组systemctl {start\|stop\|restart} cube-sandbox-{control,compute}.target看启动失败原因journalctl -u cube-sandbox-service.service -n 200 --no-pager实时跟踪启动期日志journalctl -u cube-sandbox-service.service -f重置 failed 计数systemctl reset-failed cube-sandbox-service.service跑一轮健康检查sudo /root/cube-sandbox-one-click-*/smoke.sh或sudo /usr/local/services/cubetoolbox/scripts/one-click/quickcheck.sh完整下线sudo /root/cube-sandbox-one-click-*/down.sh收集诊断包sudo /usr/local/services/cubetoolbox/scripts/cube-diag/collect-logs.sh典型故障排查路径沙箱创建失败 / 超时按下面的顺序逐层排查角色 target 是否 activesudo systemctl status cube-sandbox-control.target跑一轮健康检查sudo /root/cube-sandbox-one-click-*/smoke.shCubeAPI 是否收到请求sudo tail -F /data/log/CubeAPI/cube-api-$(date %F).logCubeMaster 调度链路sudo tail -F /data/log/CubeMaster/cubemaster-req.log节点Cubelet是否在线、是否收到调度curl http://127.0.0.1:3010/internal/v1/nodes sudo tail -F /data/log/Cubelet/Cubelet-req.logVMM 启动是否报错sudo tail -200 /data/log/CubeVmm/vmm.log服务一直activating (start-post)起不来sudo systemctl status cube-sandbox-service.service sudo journalctl -u cube-sandbox-service.service -n 200 --no-pager常见根因容器镜像构建依赖外网如cube-proxy的apk update暂时不可达 → 检查网络或参阅部署相关排障ExecStartPost健康端口超时端口被占用 / 上游服务还没起来对cube-sandbox-cube-proxy.serviceCUBE_PROXY_HTTP_PORT与CUBE_PROXY_GRPC_PORT是 systemd 启动后 TCP 检查所关注的 nginx 监听端口。CUBE_PROXY_HOST_PORT已废弃且会被忽略如果需要改 HTTP 检查端口请改CUBE_PROXY_HTTP_PORT/data/log或/data/cubelet目录不存在 / 权限不对 / XFS 挂载错位Dashboard / API 无法访问# WebUI 容器是否在跑 sudo systemctl status cube-sandbox-webui.service sudo ss -lntp sport :12088 # CubeAPI 是否在监听 sudo systemctl status cube-sandbox-cube-api.service sudo ss -lntp sport :3000附录重要路径速查用途路径安装目录/usr/local/services/cubetoolbox/运行期环境文件/usr/local/services/cubetoolbox/.one-click.envsystemd unit 安装位置/etc/systemd/system/cube-sandbox-*systemd helper 脚本/usr/local/services/cubetoolbox/scripts/systemd/*.sh业务日志核心入口/data/log/Module/Cubelet 容器层存储XFS/data/cubelet/沙箱镜像 / 快照/data/cube-shim/disks/、/data/snapshot_pack/disks/systemd PID 文件/run/cube-sandbox-systemd/角色与服务对照服务control节点compute节点mysql/redis✅—cubemaster✅—cube-api✅—webui✅—cube-proxy/coredns/dns✅—cubelet✅✅相关文档快速开始 — 安装入口多机集群部署 — 计算节点的服务子集CubeMaster 调度器配置参考 — 节点选择、quota、label、评分和 template redo部署相关排障 — XFS / 网段冲突等环境问题模板相关排障 — 模板创建相关问题【免费下载链接】CubeSandboxInstant, Concurrent, Secure Lightweight Sandbox for AI Agents.项目地址: https://gitcode.com/GitHub_Trending/cu/CubeSandbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考