1. 项目概述：为什么需要一个“能一直在线”的 Agent 运行环境？
WeKnora 这个名字最近在 AI 工具圈里出现得越来越频繁，它不是另一个大模型 API 封装器，而是一个面向开发者、强调可组合性与可扩展性的 Agent 框架。它的核心设计哲学很朴素：Agent 不该是一次性脚本，而应是长期存活、状态可追溯、行为可审计的服务单元。但现实很骨感——绝大多数本地部署的 WeKnora 实例，只要终端窗口一关、SSH 断连、或者宿主机重启，整个 Agent 就“断线失联”，记忆清空、会话中断、定时任务停摆。这直接卡死了它在真实业务场景中的落地可能：比如你用 WeKnora 搭建了一个自动归档邮件的 Agent，它本该每天凌晨三点准时拉取 Gmail 并存入 Notion；又比如你配置了一个监听 Slack 频道关键词的 Hermes Agent，一旦检测到“紧急上线”就触发 Jenkins 构建。这些需求，都依赖一个“不掉线”的运行底座。
CubeSandbox 正是在这个痛点上切入的。它不是传统意义上的容器编排平台（比如 Kubernetes），也不是轻量级进程管理器（比如 pm2），而是一个专为 AI Agent 设计的沙盒化运行时环境抽象层。你可以把它理解成给每个 Agent “配发了一套独立身份证+隔离工位+24小时供电+自动续签工牌”的综合服务包。它负责三件关键事：第一，把 WeKnora 的 Agent 实例真正“钉”在系统里，哪怕你关掉所有终端、重启机器，它也能在后台静默拉起；第二，为每个 Agent 提供独立的文件系统视图、环境变量空间和网络策略，避免多个 Agent 之间因路径冲突、端口抢占或密钥混用导致的“互相污染”；第三，内置轻量级状态快照机制，让 Agent 的短期记忆（如对话上下文缓存、临时文件索引）能在进程重启后快速恢复，而不是从零开始“失忆”。
我第一次在本地部署 WeKnora 时，就是被这个问题绊倒的。当时用weknora serve启动后一切正常，但第二天早上打开电脑，发现所有 Agent 都显示离线，昨天还在跑的网页抓取任务也彻底中断。查日志才发现，根本不是代码问题，而是进程早就在昨晚系统休眠时被系统 kill 掉了。后来试过 nohup、screen、systemd 单元，都绕不开权限、路径、环境变量继承等一堆琐碎问题。直到接触 CubeSandbox，才意识到：我们缺的不是一个启动命令，而是一套为 Agent 生命周期量身定制的基础设施契约。它解决的不是“能不能跑”，而是“能不能稳、能不能管、能不能扩”。所以，“WeKnora 基于 CubeSandbox 的 Agent 持久化运行环境建设”，本质上是在搭建一套让 AI Agent 真正具备“服务属性”的生产级底座——它让 Agent 从“玩具脚本”走向“数字员工”。
2. 整体架构设计：CubeSandbox 如何重新定义 Agent 的“生存方式”
2.1 核心思路：从“进程管理”到“沙盒生命周期管理”
传统方案（如 systemd 或 supervisor）的底层逻辑是“守护进程”：它只关心一个二进制文件是否在运行，一旦进程退出就尝试拉起。这对 WeKnora 来说远远不够。WeKnora 的 Agent 是高度状态化的：它依赖本地 SQLite 数据库存储会话历史，依赖.weknora/cache/目录缓存网页解析结果，依赖~/.weknora/config.yaml中的 OIDC 认证令牌维持登录态。如果只是简单地重启进程，这些状态全丢了，Agent 就像一个失忆的员工，每次上岗都要重新学习一遍公司制度。
CubeSandbox 的破局点在于，它把 Agent 的“运行”拆解成了四个可独立控制、可版本化管理的维度：
- 执行单元（Executor）：封装 WeKnora 的二进制调用逻辑，包括参数注入、信号转发、标准流重定向。它不直接调用
weknora serve，而是通过 CubeSandbox 自定义的启动协议，确保每次拉起都携带一致的环境上下文。 - 存储卷（Volume）：为每个 Agent 分配专属的挂载点，例如
/var/lib/cubesandbox/agent-webarchiver/data。这个目录会被自动映射为 WeKnora 的--data-dir参数值，并在 Agent 进程内外保持路径一致性。更重要的是，CubeSandbox 会定期对这个目录做增量快照（基于 rsync + hardlink），默认每 6 小时一次，保留最近 7 天的快照链。 - 网络命名空间（NetNS）：为每个 Agent 创建独立的网络栈。这意味着 Agent A 可以监听
127.0.0.1:8080，Agent B 同样可以监听127.0.0.1:8080，互不干扰。外部访问则通过 CubeSandbox 统一的反向代理网关（默认 Nginx）按Host头或路径前缀路由，比如webarchiver.yourdomain.com路由到 Agent A，hermes.yourdomain.com路由到 Agent B。 - 安全上下文（Security Context）：强制为每个 Agent 进程设置
seccomp白名单（仅允许read,write,openat,mmap,clone等必要系统调用），并以非 root 用户（如cubesandbox-agent）身份运行。同时禁用CAP_NET_BIND_SERVICE，避免 Agent 直接绑定 1-1023 端口，所有端口暴露必须经由网关统一管控。
这种设计带来的直接好处是：Agent 的“死亡”与“重生”不再是原子事件，而是一次受控的状态迁移。当系统重启后，CubeSandbox 会按预设顺序依次恢复每个沙盒：先挂载存储卷，再加载最近一次快照，最后启动 Executor。整个过程对 WeKnora 本身完全透明，它只觉得自己从未中断过。
2.2 方案选型背后的硬核考量
为什么不用 Docker Compose？这是很多人第一反应。答案很实在：Docker 的抽象粒度太粗。一个docker-compose.yml文件通常对应一个“应用”，而 WeKnora 的典型使用模式是“一个实例托管数十个 Agent”。如果为每个 Agent 都启一个容器，资源开销（内存、CPU、磁盘 I/O）会指数级上升，且容器间通信、共享存储、统一日志收集变得异常复杂。更关键的是，Docker 的restart: always策略无法感知 WeKnora 内部的 Agent 状态——它只管容器进程是否存活，不管里面的 Agent 是否已因认证过期而“假死”。
那为什么不直接用 Kubernetes？K8s 是为微服务设计的，它的 Operator 模型、CRD 扩展、etcd 存储，对于单机或小规模部署来说，完全是杀鸡用牛刀。一个简单的 WeKnora 持久化需求，不该被迫引入 Helm Chart、Ingress Controller、PersistentVolumeClaim 这一整套概念。CubeSandbox 的定位非常清晰：它是 Kubernetes 的“单机精简版”，只保留最核心的沙盒隔离与生命周期管理能力，其余功能（如服务发现、自动扩缩容）全部下沉为可选插件。
我们做过对比测试：在一台 8C16G 的开发机上，同时运行 20 个 WeKnora Agent。用纯 systemd 管理，平均内存占用 3.2GB；用 Docker Compose（每个 Agent 一个容器），内存飙升至 5.8GB，且docker stats命令响应明显变慢；而 CubeSandbox 方案，内存稳定在 2.9GB，CPU idle 时间高出 15%。这个差距的核心，在于 CubeSandbox 复用了宿主机内核，没有容器 runtime 的额外开销，同时其存储快照采用硬链接去重，20 个 Agent 共享同一份基础镜像层，磁盘占用比 Docker 镜像小 40%。
提示：CubeSandbox 的“沙盒”本质是 Linux namespace + cgroups + overlayfs 的组合拳，但它把这套复杂机制封装成了
cubesandbox init、cubesandbox start这样直白的 CLI 命令。你不需要懂unshare或cgcreate，就像你不需要懂iptables才能用 Nginx 一样。
2.3 影响范围：不只是“让它不挂”，更是重构 Agent 的交付范式
这个项目的影响力，远超一个运维脚本。它正在悄然改变 WeKnora 生态的协作方式：
- 对开发者：Agent 的开发与部署解耦。以前，你写完一个 Agent，要手动改
config.yaml、手动启服务、手动配 nginx 反代。现在，你只需提供一个agent.yaml描述文件（定义名称、镜像、端口、环境变量、存储需求），CubeSandbox 就能全自动完成部署、启停、备份、升级。我们团队内部已将此流程集成进 GitOps 流水线：git push到agents/目录，ArgoCD 就会自动触发cubesandbox apply -f agents/webarchiver.yaml。 - 对运维者：Agent 从“黑盒进程”变成“可观察实体”。CubeSandbox 提供
/metrics端点，暴露每个沙盒的 CPU 使用率、内存 RSS、磁盘 I/O、网络连接数、最近一次快照时间等指标，可直接接入 Prometheus + Grafana。我们甚至基于这些指标写了告警规则：当某个 Agent 的内存 RSS 连续 5 分钟超过 512MB，且 CPU 使用率低于 1%，就判定为“内存泄漏型假死”，自动触发cubesandbox restart --force。 - 对安全团队：实现了真正的“最小权限原则”。每个 Agent 运行在独立用户下，无法读取其他 Agent 的数据目录；网络层面，Agent 之间默认禁止互访，只能通过明确声明的
depends_on关系，由 CubeSandbox 在 iptables 层面开通白名单端口。这比在config.yaml里写allowed_hosts可靠得多——后者是应用层校验，前者是内核层拦截。
一句话总结：CubeSandbox 不是给 WeKnora 加了个“开机自启”，而是为整个 Agent 生态构建了一套符合现代云原生理念的、轻量但坚实的运行契约。它让 WeKnora 从一个“本地开发框架”，真正具备了承载生产级 AI 工作流的能力。
3. 核心细节解析：从零搭建一个可信赖的持久化环境
3.1 环境准备与依赖安装：避开那些坑人的“默认值”
在正式安装 CubeSandbox 之前，有三个极易被忽略、却会导致后续所有步骤失败的前置条件，我必须强调：
第一，内核版本必须 ≥ 5.4。这不是 CubeSandbox 的硬性要求，而是其底层依赖的overlayfs和user_namespaces特性在旧内核中存在严重 Bug。我们曾在一个 Ubuntu 18.04（内核 4.15）的服务器上反复失败，日志里全是failed to create user namespace: Operation not permitted。升级到 5.4 后，问题瞬间消失。检查方法很简单：uname -r。如果低于 5.4，请务必升级，别试图打补丁。
第二，/etc/subuid和/etc/subgid必须正确配置。CubeSandbox 依赖 user namespace 来实现无 root 权限的沙盒隔离。这意味着它需要为普通用户分配一段 UID/GID 范围。默认情况下，很多发行版（尤其是 CentOS/RHEL）的这两个文件是空的。你需要为运行 CubeSandbox 的用户（比如deploy）添加一行：deploy:100000:65536。这表示为deploy用户分配从 100000 开始的 65536 个 UID。操作命令：
echo "deploy:100000:65536" | sudo tee -a /etc/subuid echo "deploy:100000:65536" | sudo tee -a /etc/subgid注意：
deploy是你的用户名，不是字面意思。请替换成你实际使用的用户名。这一步漏掉，cubesandbox init会报错user namespace not available，且错误信息极其晦涩。
第三，SELinux 必须处于permissive模式，或彻底禁用。CubeSandbox 的 overlayfs 挂载和 network namespace 创建，在 enforcing 模式下会触发大量 AVC denials。虽然可以通过audit2allow生成策略，但成本远高于直接切换模式。临时切换：sudo setenforce 0；永久禁用：编辑/etc/selinux/config，将SELINUX=enforcing改为SELINUX=disabled，然后重启。Debian/Ubuntu 用户无需考虑此条。
完成以上三步后，安装 CubeSandbox 本身就很轻松。官方推荐使用预编译二进制：
# 下载最新版（以 v0.8.2 为例） curl -L https://github.com/cubesandbox/cubesandbox/releases/download/v0.8.2/cubesandbox-linux-amd64 -o /usr/local/bin/cubesandbox sudo chmod +x /usr/local/bin/cubesandbox # 初始化全局环境 sudo cubesandbox initcubesandbox init会创建/var/lib/cubesandbox目录（存储所有沙盒数据）、/etc/cubesandbox（配置文件）、以及/usr/lib/systemd/system/cubesandbox.service（systemd 服务单元）。它还会自动启用并启动cubesandbox.service，确保 CubeSandbox 守护进程随系统启动。
3.2 WeKnora Agent 的标准化打包：告别git clone && npm install
WeKnora 官方文档推荐的本地开发方式是git clone仓库后npm install && npm run dev。这种方式在持久化环境中完全不可取——它把源码、node_modules、构建产物全部混在一起，既不利于版本控制，也不利于 CubeSandbox 的沙盒快照。我们必须将其改造为一个“可复现、可分发、可审计”的制品。
我们的标准流程是：用 Rust 编写的weknora-builder工具，将 Agent 打包成一个自包含的、静态链接的二进制文件。这个工具会做三件事：
- 解析
agent.yaml中声明的dependencies（如@weknora/core,@weknora/http-client），下载对应版本的 tarball。 - 将所有依赖的 JavaScript 源码、WeKnora Runtime 的 WASM 模块、以及用户编写的
index.ts，通过swc编译器进行树摇（Tree Shaking）和优化，最终输出一个单文件agent.wasm。 - 调用
wasmtime的wasi工具链，将agent.wasm与一个极简的 Rust 运行时（负责处理 HTTP 请求、文件 I/O、环境变量读取）链接，生成一个纯静态的agent二进制。
最终产物只有一个文件：agent。它不依赖 Node.js，不依赖任何动态库，ldd agent输出为空。你可以把它放在任何 x86_64 Linux 机器上直接运行。
打包后的agent.yaml示例：
name: webarchiver version: "1.2.0" image: ghcr.io/your-org/weknora-agents/webarchiver:v1.2.0 port: 8080 env: - WEKNORA_OIDC_CLIENT_ID=xxx - WEKNORA_OIDC_CLIENT_SECRET=yyy - NOTION_API_KEY=zzz volumes: - name: data mountPath: /app/data persistent: true - name: cache mountPath: /app/cache persistent: false其中image字段指向一个 OCI 镜像仓库（如 GitHub Container Registry），这个镜像是由 CI 流水线自动构建并推送的。cubesandbox在拉取镜像时，会自动解压其中的agent二进制到沙盒的/app/目录。
实操心得：我们曾尝试过直接用
docker build打包 WeKnora Agent，但发现体积太大（基础镜像就 500MB+），且docker pull在内网环境下速度极慢。改用weknora-builder后，单个 Agent 镜像压缩后仅 12MB，cubesandbox pull通常在 2 秒内完成。关键是，它把“构建”和“运行”彻底分离，CI 只负责构建，CD 只负责部署，职责清晰。
3.3 持久化配置详解：让 Agent 真正“记住自己”
CubeSandbox 的持久化能力，核心体现在volumes配置上。但这里有个关键陷阱：并非所有目录都需要持久化，也并非所有持久化都等同于“永不丢失”。
我们定义了三种 volume 类型：
persistent: true：这是真正的持久化。CubeSandbox 会将该 volume 的内容同步到/var/lib/cubesandbox/volumes/<volume-name>，并在每次沙盒启动时，从该路径挂载。它适用于存放 Agent 的核心状态数据，如 SQLite 数据库文件、长期缓存索引、OIDC refresh token。注意：这个目录必须由 CubeSandbox 管理，你绝不能手动修改它里面的内容，否则会破坏快照一致性。persistent: false：这是“半持久化”。CubeSandbox 会在沙盒启动时，从一个只读的基础镜像层（/var/lib/cubesandbox/base-images/<image-name>/cache）复制一份初始内容到沙盒的mountPath。沙盒运行期间的所有写入，都会保留在沙盒自己的 overlayfs 上层，但沙盒重启后，这些写入会丢失，下次启动又会从基础镜像层重新复制。它适用于存放临时下载的网页 HTML、图片缩略图等可再生数据，既能加速冷启动，又不会因垃圾文件堆积而膨胀。persistent: "host"：这是“主机直通”。CubeSandbox 会将宿主机上的一个绝对路径（如/mnt/nas/weknora-backups）直接 bind mount 到沙盒内。它适用于需要与外部系统共享数据的场景，比如将 Agent 导出的 Markdown 文件，实时同步到 NAS 上供 Obsidian 读取。风险提示：此模式下，宿主机路径的权限和 SELinux 上下文必须正确，否则沙盒内进程会因Permission denied而崩溃。
一个典型的 WeKnora Agent 配置，会混合使用这三种类型：
volumes: # 核心状态，必须持久化 - name: data mountPath: /app/data persistent: true # 临时缓存，半持久化，避免重复下载 - name: cache mountPath: /app/cache persistent: false # 导出文件，直通到 NAS，供 Obsidian 实时索引 - name: exports mountPath: /app/exports persistent: "host" hostPath: /mnt/nas/weknora-exports此外，env环境变量的持久化也至关重要。WeKnora 的 OIDC 认证流程会产生refresh_token，它被存储在WEKNORA_DATA_DIR/.oidc_tokens.json中。这个文件必须位于persistent: true的 volume 内，否则每次重启，Agent 都要重新走一遍 OAuth 授权流程，用户体验极差。我们在agent.yaml中显式声明了WEKNORA_DATA_DIR=/app/data，并确保/app/data对应的 volume 是persistent: true。
4. 实操过程：手把手完成一个 Hermes Agent 的持久化部署
4.1 准备工作：获取 Hermes Agent 镜像与配置
Hermes Agent 是 WeKnora 生态中一个广受欢迎的第三方工作台，它能将 WeKnora 的 Agent 能力无缝集成到 Obsidian、VS Code 等编辑器中。它的官方镜像托管在 GitHub Container Registry。首先，我们需要拉取它，并检查其结构：
# 登录 GHCR（需要个人访问令牌 PAT，scope 为 read:packages） echo $GHCR_TOKEN | docker login ghcr.io -u $GHCR_USERNAME --password-stdin # 拉取镜像 docker pull ghcr.io/hermes-agent/hermes:v0.5.1 # 查看镜像内文件（确认是否存在 /app/agent 二进制） docker run --rm -it ghcr.io/hermes-agent/hermes:v0.5.1 ls -l /app/ # 输出应包含：-rwxr-xr-x 1 root root 12345678 Jan 1 00:00 agent确认无误后，我们为它编写专属的hermes.yaml配置文件：
# hermes.yaml name: hermes version: "0.5.1" image: ghcr.io/hermes-agent/hermes:v0.5.1 port: 3000 env: - WEKNORA_API_URL=http://localhost:8000 - HERMES_OBSIDIAN_PORT=3001 - HERMES_LOG_LEVEL=info volumes: - name: data mountPath: /app/data persistent: true - name: obsidian-config mountPath: /app/obsidian-config persistent: "host" hostPath: /home/deploy/.obsidian/plugins/hermes-agent这里的关键点是obsidian-configvolume。Hermes 需要读取 Obsidian 的插件配置，而 Obsidian 的插件目录在宿主机上是固定的（~/.obsidian/plugins/hermes-agent）。我们通过persistent: "host"将其直通进沙盒，这样 Hermes 就能实时读取和更新 Obsidian 的配置文件，实现双向同步。
4.2 部署与验证：从零到“永远在线”
部署过程分为四步，全部通过cubesandboxCLI 完成：
第一步：应用配置
# 将 hermes.yaml 应用到 CubeSandbox cubesandbox apply -f hermes.yaml # 查看沙盒状态 cubesandbox list # 输出应类似： # NAME STATUS PORTS AGE # hermes Running 127.0.0.1:3000 -> 3000 10scubesandbox apply会自动完成：拉取镜像、创建沙盒目录、生成 systemd 服务单元、启动服务。整个过程约 5-10 秒。
第二步：配置反向代理CubeSandbox 默认不暴露端口到公网，所有流量需经由 Nginx 网关。编辑/etc/nginx/conf.d/hermes.conf：
upstream hermes_backend { server 127.0.0.1:3000; } server { listen 443 ssl http2; server_name hermes.yourdomain.com; ssl_certificate /etc/letsencrypt/live/yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/yourdomain.com/privkey.pem; location / { proxy_pass http://hermes_backend; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }然后重载 Nginx：sudo nginx -s reload。
第三步：验证持久化这是最关键的一步。我们来模拟一次“灾难性”重启：
# 1. 记录当前状态 cubesandbox logs hermes | tail -n 5 # 记下最后几行日志，比如 "INFO: Connected to WeKnora API" # 2. 强制重启宿主机 sudo reboot # 3. 等待机器启动后，立即检查 cubesandbox list # STATUS 应为 Running，AGE 应为几分钟（而非 0s） cubesandbox logs hermes | tail -n 5 # 日志应连续，最后几行应与重启前一致，证明状态未丢失 # 4. 访问 Web UI curl -k https://hermes.yourdomain.com/health # 应返回 {"status":"ok","timestamp":...}如果一切顺利，你会看到 Hermes 的 Web UI 在浏览器中完美加载，且所有之前配置的 WeKnora Agent 连接状态都是“Online”。这证明持久化完全生效。
第四步：启用自动快照默认的快照策略是每 6 小时一次。对于生产环境，我们建议调整为每 2 小时，并增加保留天数：
# 编辑全局配置 sudo nano /etc/cubesandbox/config.yaml # 修改以下字段： snapshot: interval: "2h" retention: 14然后重启 CubeSandbox 服务：sudo systemctl restart cubesandbox。你可以通过cubesandbox snapshot list hermes查看所有快照记录。
4.3 日常运维：监控、升级与故障恢复
一个“持久化”环境，其价值不仅在于“不挂”，更在于“易管”。CubeSandbox 提供了一套完整的运维接口：
监控：所有指标都暴露在http://localhost:9090/metrics（CubeSandbox 自带的 Prometheus exporter）。我们配置了如下关键告警：
cubesandbox_sandbox_memory_rss_bytes{job="cubesandbox"} > 1073741824（内存 > 1GB）cubesandbox_sandbox_disk_usage_percent{job="cubesandbox"} > 85（磁盘 > 85%）cubesandbox_sandbox_last_snapshot_age_seconds{job="cubesandbox"} > 7200（上次快照 > 2 小时）
升级：升级 Hermes Agent 只需两步：
# 1. 更新 hermes.yaml 中的 image 版本 # 2. 重新应用 cubesandbox apply -f hermes.yamlCubeSandbox 会自动执行滚动升级：先拉取新镜像，然后优雅停止旧沙盒（发送 SIGTERM，等待 30 秒），再启动新沙盒。整个过程对用户无感知。
故障恢复：如果某个 Agent 因未知原因进入“假死”（进程在，但 HTTP 响应超时），我们可以一键回滚到任意快照：
# 查看快照列表 cubesandbox snapshot list hermes # 回滚到 2 小时前的快照（假设 ID 为 snap-abc123） cubesandbox snapshot restore hermes snap-abc123 # 重启沙盒 cubesandbox restart hermes整个过程不到 10 秒，比重装 Agent 快一个数量级。
5. 常见问题与排查技巧实录：那些只有踩过才知道的坑
5.1 典型问题速查表
| 问题现象 | 可能原因 | 排查命令 | 解决方案 |
|---|---|---|---|
cubesandbox list显示Status: Error，日志中出现failed to setup network: failed to create netns | 宿主机内核未启用CONFIG_NET_NS=y | zcat /proc/config.gz | grep CONFIG_NET_NS或grep CONFIG_NET_NS /boot/config-$(uname -r) | 重新编译内核，或升级到已启用该选项的发行版 |
Agent 启动后立即崩溃，日志显示Error: EACCES: permission denied, open '/app/data/.oidc_tokens.json' | persistent: true的 volume 目录权限错误，宿主机上该目录属主不是cubesandbox-agent用户 | ls -ld /var/lib/cubesandbox/volumes/hermes-data | sudo chown -R cubesandbox-agent:cubesandbox-group /var/lib/cubesandbox/volumes/hermes-data |
通过 Nginx 访问 Agent Web UI，页面空白，浏览器控制台报Failed to load resource: the server responded with a status of 404 () | Nginx 的location /块未正确配置proxy_pass，或 Agent 的前端资源路径与后端 API 路径不匹配 | curl -v http://127.0.0.1:3000/(直连沙盒) vscurl -v https://hermes.yourdomain.com/(经 Nginx) | 检查 Agent 的baseURL配置，确保其与 Nginx 的server_name一致；或在 Nginx 中添加sub_filter重写前端资源路径 |
cubesandbox logs hermes无输出，或输出为No logs found for sandbox 'hermes' | CubeSandbox 的日志驱动未正确配置，或 systemd journal 被轮转清理 | sudo journalctl -u cubesandbox.service -n 50 --no-pager | 编辑/etc/cubesandbox/config.yaml，确保logging.driver为journald，并检查journalctl --disk-usage，必要时sudo journalctl --vacuum-size=1G |
5.2 独家避坑技巧分享
技巧一：“沙盒健康检查”脚本，5 行代码防患未然
我们写了一个极简的 Bash 脚本，每天凌晨 2 点自动运行，检查所有沙盒的 HTTP 健康端点：
#!/bin/bash for sandbox in $(cubesandbox list --format json \| jq -r '.[].name'); do port=$(cubesandbox list --format json \| jq -r ".[] \| select(.name==\"$sandbox\") \| .ports[0].hostPort") if ! curl -sf "http://127.0.0.1:$port/health" >/dev/null 2>&1; then echo "ALERT: Sandbox $sandbox is unhealthy!" \| mail -s "CubeSandbox Alert" admin@yourdomain.com fi done这个脚本比依赖 Prometheus 的复杂告警更直接、更可靠，因为它直接模拟了用户的真实访问路径。
技巧二：利用cubesandbox exec进行“外科手术式”调试
当 Agent 行为异常，但日志又看不出端倪时，不要急着重启。cubesandbox exec让你像docker exec一样，直接进入沙盒内部：
# 进入 hermes 沙盒的 shell cubesandbox exec hermes /bin/sh # 查看沙盒内的完整进程树 ps auxf # 检查网络连接 netstat -tuln # 手动触发一次 WeKnora API 调用，看是否超时 curl -v http://localhost:8000/api/v1/agents这比在宿主机上ps aux \| grep hermes有效得多，因为你能看到沙盒内部真实的网络和文件系统视图。
技巧三：快照的“黄金备份”策略
CubeSandbox 的本地快照是可靠的，但无法抵御硬盘物理损坏。我们建立了“快照即备份”的策略：每天凌晨 3 点，将/var/lib/cubesandbox/snapshots/目录下的最新快照，通过rclone同步到异地对象存储（如 AWS S3 或 Backblaze B2）：
# /etc/cron.d/cubesandbox-backup 0 3 * * * root /usr/bin/rclone sync /var/lib/cubesandbox/snapshots/ remote:backups/cubesandbox/ --backup-dir remote:backups/cubesandbox/old/ --exclude "*.tmp" --log-file=/var/log/cubesandbox-backup.log这样，即使整台服务器报废，我们也能在新机器上cubesandbox init，然后rclone sync拉回快照，cubesandbox snapshot restore，15 分钟内重建整个环境。
5.3 性能调优：让 20 个 Agent 在 4C8G 机器上稳如泰山
在资源受限的边缘设备（如 Intel NUC）上部署多个 Agent 时，性能是关键。我们总结了三条铁律：
第一，严格限制每个沙盒的 cgroup 资源上限。在hermes.yaml中添加resources字段：
resources: limits: memory: "512Mi" cpu: "500m" requests: memory: "256Mi" cpu: "250m"cpu: "500m"表示最多使用 0.5 个 CPU 核心。这能防止某个 Agent 因 bug 进入死循环，耗尽所有 CPU，拖垮其他 Agent。
第二，关闭 WeKnora 的冗余日志。WeKnora 默认开启debug级别日志，会产生海量 I/O。我们在env中添加：
env: - WEKNORA_LOG_LEVEL=warn - WEKNORA_LOG_FORMAT=jsonjson格式便于后续用 Loki 或 Fluentd 做结构化分析，而warn级别则大幅减少日志量。
第三，为 SQLite 数据库启用 WAL 模式。WeKnora 的本地数据库默认是DELETE模式，高并发写入时性能急剧下降。我们在 Agent 启动前，通过cubesandbox exec执行 SQL 命令：
cubesandbox exec hermes sqlite3 /app/data/weknora.db "PRAGMA journal_mode=WAL;"WAL 模式将写操作变为追加，极大提升了并发读写性能。实测在 10 个 Agent 同时写入的场景下，数据库响应时间从平均 120ms 降至 15ms。
我在实际部署中发现，很多用户卡在“环境初始化”这一步，反复重装系统、
