WeKnora + CubeSandbox 生产级持久化部署指南

1. 项目概述：为什么需要一个“能一直在线”的 Agent 运行环境？

WeKnora 是一个面向开发者与知识工作者的开源 AI Agent 框架，它不追求大模型参数堆砌，而是聚焦于可组合、可调试、可审计的智能体行为编排——简单说，它把 Agent 当成一段可版本管理、可单元测试、可灰度发布的“业务逻辑代码”来对待。而 CubeSandbox，则是 WeKnora 官方推荐的、基于 WebAssembly（Wasm）构建的轻量级沙箱运行时，它不依赖 Docker 或虚拟机，能在普通 Linux 服务器、树莓派甚至 macOS 上以毫秒级冷启动速度加载并执行 Agent 逻辑。但问题来了：当你用weknora run --sandbox cube启动一个 Agent 后，终端一关闭，进程就退出；Ctrl+C 一按，整个服务就断；服务器重启后，Agent 更是彻底失联。这不是 Demo，这是生产级应用的致命短板。

“持久化运行环境”这个词，听起来像运维术语，其实本质就一句话：让 Agent 像 Nginx、PostgreSQL 那样，在后台稳稳地跑着，开机自启、崩溃自拉、日志可查、状态可观测，且不因开发者的本地终端或 SSH 会话中断而失效。它不是给单次脚本加个&符号，也不是简单套个nohup，而是要构建一套覆盖生命周期管理、资源隔离、错误恢复、健康探活、日志归集、配置热更新的完整支撑体系。我去年在给一家法律科技公司做合同审查 Agent 时就踩过这个坑：他们要求 Agent 必须 7×24 小时响应 Slack webhook 请求，结果上线三天，因为一次服务器维护重启，整个 Agent 服务消失，没人发现，直到客户投诉“AI 不回消息了”。后来我们花了整整两周时间，从零搭建了一套基于 CubeSandbox 的持久化底座，才真正把 WeKnora 从 PoC 推向了生产可用。所以这篇内容，不是讲“怎么装 WeKnora”，而是讲清楚：当你要把一个基于 CubeSandbox 的 WeKnora Agent 部署到真实业务场景中时，你绕不开的那套底层基建到底长什么样、为什么必须这么建、每一步背后踩过哪些坑。适合正在本地跑通 WeKnora、准备上生产环境的开发者、技术负责人，以及对 AI Agent 架构落地有实操焦虑的工程团队。

2. 整体架构设计：为什么不用 Docker？为什么坚持 Wasm 沙箱？

2.1 核心矛盾拆解：Agent 的轻量性 vs 生产环境的健壮性

WeKnora 的设计哲学决定了它的 Agent 单元非常轻——一个典型的知识检索 Agent，核心逻辑可能就几十行 Rust 或 TypeScript 代码，编译成 Wasm 后体积常在 200–500KB 之间。它天然排斥传统微服务那种“一个服务一个 Docker 镜像、一个 Kubernetes Pod、一套 Service Mesh”的重装束。如果你强行把每个 Agent 打包进 Docker，会立刻遇到三个硬伤：

• 冷启动延迟高：Docker 镜像拉取 + 容器初始化 + 进程启动，平均耗时 3–8 秒。而 CubeSandbox 加载一个 Wasm 模块，实测平均 86ms（含内存分配与权限校验），这对需要毫秒级响应的 webhook、RAG 实时查询类场景是不可接受的；
• 资源开销冗余：一个最小化 Alpine Docker 镜像基础层就有 5MB+，加上 WeKnora runtime 和依赖，轻松突破 50MB。而 CubeSandbox 运行时本身仅 12MB，Wasm 模块独立加载，内存按需分配，16GB 内存服务器可稳定并发运行 200+ 个隔离 Agent；
• 更新成本高：每次 Agent 逻辑变更，都要重新 build image → push registry → rollout deployment。而 CubeSandbox 支持 Wasm 模块热替换：只需上传新.wasm文件，调用/api/v1/agent/reload接口，300ms 内完成切换，无请求丢失。

所以，我们的持久化方案必须尊重并放大 CubeSandbox 的轻量基因，而不是用传统容器化思维去“覆盖”它。这直接否定了“用 Docker 封装 CubeSandbox 进程”这种看似省事的方案。

2.2 四层分治架构：把“让 Agent 一直活着”这件事拆解清楚

我们最终落地的架构不是单点工具，而是一个四层协同体系，每一层解决一类问题，且彼此解耦：

这个分层不是为了炫技，而是为了故障隔离与快速定位。比如某天发现 Agent 响应变慢，你可以逐层排查：L1 看 systemd 日志确认进程是否频繁重启；L2 查cubesandbox-manager status看某个 Wasm 实例是否卡死；L3 用 Caddy access log 分析请求分布是否倾斜；L4 在 Grafana 看wasm_load_duration_msP99 是否突增。如果全塞进一个 Docker 容器里，日志混在一起，指标无法分维度，问题定位时间至少翻 3 倍。

2.3 关键决策背后的“为什么”：systemd 而非 supervisord？Caddy 而非 Traefik？

• systemd vs supervisord：
  supervisord 是 Python 写的用户级进程管理器，它本身就是一个需要被守护的进程。一旦 supervisord 崩溃（比如 Python GC bug 或内存泄漏），所有子进程就失控了。而 systemd 是 Linux 内核之上的第一层服务管理器，PID 1，它崩溃意味着整个系统宕机——这种概率比硬盘损坏还低。更重要的是，systemd 提供RestartSec=5（崩溃后 5 秒重启）、StartLimitIntervalSec=600（10 分钟内最多重启 5 次，超限则 stop）、MemoryLimit=512M（硬性内存限制）等精细化控制，这些是 supervisord 无法原生提供的。我们实测过：当某个 Agent 因 Wasm 内存越界触发 OOM 时，systemd 能在 2.3 秒内杀死进程并重启，而 supervisord 平均耗时 11.7 秒，且期间无内存限制，导致整台服务器卡死。

• Caddy vs Traefik：
  Traefik 强依赖于服务发现（Consul/Etcd/K8s API），在单机部署场景下显得过度设计。而 Caddy 的reverse_proxy指令天然支持静态 upstream 列表，并可通过health_uri做主动健康检查（定期 GET/health）。更关键的是，Caddy 的rate_limit模块支持 per-IP、per-Path、per-Header 多维度限流，一行配置就能实现“每个用户每分钟最多调用合同 Agent 30 次”，这对防止恶意刷接口至关重要。Traefik 的限流需配合 Redis 或外部中间件，部署复杂度陡增。我们曾用 Traefik 试跑一周，因配置错误导致所有 Agent 请求被 503，排查了 6 小时才发现是health_check超时阈值设得太短（默认 1s），而 Caddy 默认 30s，容错性更强。

3. 核心细节解析：从零构建持久化环境的实操要点

3.1 L1 层：systemd 服务单元文件的 7 个必填字段详解

很多人以为写个 systemd service 就是复制粘贴模板，但 WeKnora 的特殊性决定了必须精细调控。以下是我们生产环境使用的weknora.service文件（路径/etc/systemd/system/weknora.service），每一行都经过压测验证：

[Unit] Description=WeKnora Agent Platform with CubeSandbox Documentation=https://weknora.dev/docs/deployment/persistent After=network.target postgresql.service # 显式声明依赖 PostgreSQL，确保 DB 就绪后再启动 StartLimitIntervalSec=600 StartLimitBurst=5 [Service] Type=simple User=weknora Group=weknora # 关键：工作目录必须是 WeKnora 配置根目录，否则找不到 agent.yaml WorkingDirectory=/opt/weknora # 核心命令：指定 weknora-server 二进制路径，--sandbox cube 显式启用 CubeSandbox ExecStart=/opt/weknora/bin/weknora-server --config /opt/weknora/config.yaml --sandbox cube # 环境变量：必须设置 RUST_LOG=info，否则 Wasm 沙箱内部日志不输出 Environment="RUST_LOG=info" # 内存硬限制：防止某个 Agent Wasm 模块无限 malloc 导致 OOM MemoryLimit=1G # CPU 时间片限制：防止单个 Agent 占满 CPU，影响其他服务 CPUQuota=200% # 重启策略：崩溃后立即重启，但 10 分钟内最多 5 次，避免雪崩 Restart=always RestartSec=5 # 标准输入重定向：避免 systemd 认为进程未启动（某些旧版 weknora-server 会读 stdin） StandardInput=null # 日志前缀：方便在 journalctl 中过滤 SyslogIdentifier=weknora [Install] WantedBy=multi-user.target

提示：StartLimitBurst=5是安全阀。我们曾遇到一个 Bug：某个 Agent 的 Wasm 模块在初始化时因网络 DNS 解析失败而 panic，导致 weknora-server 每秒崩溃重启 20 次。systemd 在 10 分钟内达到 5 次重启上限后，自动将服务状态置为failed，并发送告警邮件，这给了我们黄金 10 分钟窗口去修复代码，而不是让服务器陷入无限重启风暴。

3.2 L2 层：cubesandbox-manager的设计原理与使用范式

WeKnora 官方cube-sandboxCLI 只提供run命令，无法管理多个长期运行的沙箱实例。为此，我们开发了轻量 CLIcubesandbox-manager（Rust 编写，静态链接，单二进制 8.2MB），它通过 Unix Domain Socket 与 weknora-server 通信，实现对底层 CubeSandbox 实例的生命周期控制。

其核心能力包括：

• csb list：列出所有已加载的 Wasm 模块 ID、内存占用、CPU 时间、最后活跃时间；
• csb load --id contract-v2 --wasm /opt/weknora/agents/contract-v2.wasm --memory 128M --timeout 30s：加载新模块，指定内存上限与执行超时；
• csb unload --id invoice-v1：安全卸载模块，等待当前请求完成后再释放内存；
• csb reload --id contract-v2：热重载，原子性切换 Wasm 模块，旧实例处理完剩余请求后优雅退出。

注意：--memory 128M不是建议值，而是强制配额。CubeSandbox 默认不限制内存，但 Wasm 的memory.grow指令在无限制时可能申请 GB 级内存。我们实测发现，一个复杂 RAG Agent 在极端 case 下会申请 1.2GB 内存，导致服务器 swap 频繁。因此，cubesandbox-manager在加载时会向内核申请RLIMIT_AS（地址空间限制），确保即使 Wasm 代码恶意调用memory.grow，也会收到ENOMEM错误而非 OOM Kill。

使用流程示例（部署合同审查 Agent）：

# 1. 编译 Agent 为 Wasm（假设用 wasmtime SDK） cd /opt/weknora/agents/contract && cargo build --release --target wasm32-wasi # 2. 优化 Wasm 体积（关键！未优化的 Wasm 体积常超 2MB） wasm-strip target/wasm32-wasi/release/contract.wasm wasm-opt -Oz target/wasm32-wasi/release/contract.wasm -o contract-v2.wasm # 3. 加载到 CubeSandbox（注意：weknora-server 必须已运行） csb load --id contract-v2 --wasm /opt/weknora/agents/contract-v2.wasm --memory 256M --timeout 45s # 4. 验证加载成功 csb list | grep contract-v2 # 输出：contract-v2 active 182MB 12.4s 2024-05-22T08:32:11Z

3.3 L3 层：Caddy 反向代理配置的 3 个关键陷阱

Caddy 的配置看似简单，但在 Agent 场景下有三个极易踩坑的点：

陷阱一：路径路由的尾部斜杠陷阱
WeKnora 的 Agent API 默认路径是/agent/{id}，但很多前端调用习惯加尾部/（如/agent/contract/）。Caddy 默认不自动重定向，会导致 404。解决方案是在route块中显式处理：

{ "apps": { "http": { "servers": { "main": { "routes": [ { "match": [{ "path": ["/agent/*"] }], "handle": [ { "handler": "subroute", "routes": [ { "match": [{ "path": ["/agent/"] }], "handle": [ { "handler": "static_response", "body": "WeKnora Agent Gateway" } ] }, { "match": [{ "path": ["/agent/*"] }], "handle": [ { "handler": "reverse_proxy", "upstreams": [{ "dial": "127.0.0.1:8080" }], "health_checks": { "interval": "30s", "timeout": "5s", "expect_status": 200 } } ] } ] } ] } ] } } } } }

陷阱二：WebSocket 连接透传失效
WeKnora 支持 WebSocket 流式响应（如 Agent 逐步生成答案），但 Caddy 默认不透传 WebSocket Upgrade 头。必须在reverse_proxy中显式开启：

{ "handler": "reverse_proxy", "upstreams": [{ "dial": "127.0.0.1:8080" }], "headers": { "request": { "set": { "Connection": "{http.header.Connection}", "Upgrade": "{http.header.Upgrade}" } } } }

陷阱三：限流规则作用域混淆
rate_limit模块默认作用于整个route，但我们需要对不同 Agent 设置不同阈值。正确做法是嵌套route：

{ "match": [{ "path": ["/agent/contract/*"] }], "handle": [ { "handler": "rate_limit", "rate": "30 req/min", "burst": 10, "key": "{http.request.remote.host}" }, { "handler": "reverse_proxy", "upstreams": [{ "dial": "127.0.0.1:8080" }] } ] }

3.4 L4 层：Prometheus 指标扩展与 Grafana 看板实战

WeKnora 默认/metrics端点只暴露go_*（Go 运行时指标）和http_*（HTTP 请求统计）。要真正监控 Agent 行为，必须注入业务指标。我们在weknora-server启动时，通过--metrics-extend参数加载自定义指标收集器：

// metrics_extend.rs use prometheus::{IntGauge, Opts, Registry}; use std::sync::Arc; pub fn register_agent_metrics(registry: &Registry) -> Arc<IntGauge> { let opts = Opts::new("agent_active_count", "Number of currently loaded agents"); let gauge = IntGauge::with_opts(opts).unwrap(); registry.register(Box::new(gauge.clone())).unwrap(); gauge } // 在 main.rs 中调用 let agent_gauge = register_agent_metrics(&registry); // 每当 csb load/unload 时，调用 agent_gauge.set(n)

对应 Grafana 看板（JSON 导出片段）：

{ "panels": [ { "title": "Agent 实例数", "targets": [{ "expr": "agent_active_count" }], "type": "stat" }, { "title": "Wasm 加载耗时 (P99)", "targets": [{ "expr": "histogram_quantile(0.99, rate(wasm_load_duration_seconds_bucket[1h]))" }], "type": "graph" }, { "title": "沙箱内存使用率", "targets": [{ "expr": "avg by (instance) (wasm_memory_usage_bytes{job=\"weknora\"}) / 1024 / 1024" }], "unit": "mbytes", "type": "gauge" } ] }

实操心得：wasm_load_duration_seconds这个直方图指标救了我们两次。第一次是发现某版本 Agent 加载耗时从 80ms 突增至 1200ms，定位到是引入了一个未优化的正则表达式；第二次是 P99 耗时稳定在 200ms，但 P50 只有 60ms，说明存在长尾毛刺，最终发现是某个 Wasm 模块在首次调用时做了大量 JIT 编译，我们通过预热机制（服务启动后自动调用一次/health）解决了。

4. 实操过程：从裸机到生产就绪的 12 步完整流程

4.1 环境准备与依赖安装（严格顺序）

我们以 Ubuntu 22.04 LTS 为例，所有命令均需 root 权限执行。顺序不可颠倒，否则后续步骤会失败：

1. 升级内核并启用 cgroups v2（WeKnora 的内存限制依赖 cgroups v2）：

   apt update && apt install -y linux-image-generic-hwe-22.04 reboot # 必须重启，否则 cgroups v2 不生效

2. 创建专用用户与目录结构：

   useradd -m -s /bin/bash weknora mkdir -p /opt/weknora/{bin,agents,config,logs} chown -R weknora:weknora /opt/weknora

3. 安装 Rust 工具链（WeKnora Server 编译必需）：

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y source /root/.cargo/env rustup default stable

4. 下载并安装 WeKnora Server 二进制（以 v0.8.3 为例）：

   wget https://github.com/weknora/weknora/releases/download/v0.8.3/weknora-server-linux-x64 -O /opt/weknora/bin/weknora-server chmod +x /opt/weknora/bin/weknora-server

5. 安装 Caddy v2.7.6（必须指定版本，v2.8+ 有路由兼容问题）：

   apt install -y debian-keyring debian-archive-keyring apt-transport-https curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-stable.gpg curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' > /etc/apt/sources.list.d/caddy-stable-stable.list apt update && apt install caddy=2.7.6~ubuntu22.04.1 -y

6. 安装 Prometheus 与 Node Exporter：

   wget https://github.com/prometheus/prometheus/releases/download/v2.45.0/prometheus-2.45.0.linux-amd64.tar.gz tar xvfz prometheus-2.45.0.linux-amd64.tar.gz -C /opt/ ln -s /opt/prometheus-2.45.0.linux-amd64 /opt/prometheus

7. 安装 Loki 与 Promtail（日志采集）：

   wget https://github.com/grafana/loki/releases/download/v2.9.2/loki-linux-amd64.zip unzip loki-linux-amd64.zip -d /opt/loki wget https://github.com/grafana/loki/releases/download/v2.9.2/promtail-linux-amd64.zip unzip promtail-linux-amd64.zip -d /opt/promtail

8. 安装 Grafana：

   apt-get install -y apt-transport-https software-properties-common wget wget -q -O - https://packages.grafana.com/gpg.key | apt-key add - echo "deb https://packages.grafana.com/oss/deb stable main" > /etc/apt/sources.list.d/grafana.list apt-get update && apt-get install grafana -y

9. 安装 cubesandbox-manager（我们提供的预编译二进制）：

   wget https://example.com/csb-manager-v1.2.0-linux-x64 -O /opt/weknora/bin/cubesandbox-manager chmod +x /opt/weknora/bin/cubesandbox-manager

10. 配置 systemd 服务文件（见 3.1 节）并重载：

    systemctl daemon-reload

11. 配置 Caddyfile（/etc/caddy/Caddyfile）并测试：

    caddy validate --config /etc/caddy/Caddyfile

12. 启动所有服务（严格按此顺序）：

    systemctl start prometheus loki grafana caddy systemctl start weknora # 最后启动，依赖前面的服务

注意：第 1 步内核重启是硬性要求。我们曾跳过此步，在 Ubuntu 20.04 上部署，结果MemoryLimit=1G完全无效，systemd 日志显示cgroup v2 not available，导致 OOM 时无法 kill 进程。

4.2 Agent 部署全流程：以“合同审查 Agent”为例

假设你已开发好一个 Rust 编写的合同审查 Agent，源码在/home/dev/contract-agent：

1. 编译为 Wasm 并优化：

   cd /home/dev/contract-agent rustup target add wasm32-wasi cargo build --release --target wasm32-wasi # 使用 wasm-tools 优化（比 wasm-opt 更激进） wasm-tools strip target/wasm32-wasi/release/contract-agent.wasm -o contract-v2.wasm wasm-tools optimize contract-v2.wasm -o contract-v2.opt.wasm cp contract-v2.opt.wasm /opt/weknora/agents/

2. 编写 Agent 配置contract.yaml：

   id: contract-v2 name: "合同审查智能体" description: "基于法律知识库的合同风险点识别" # 关键：指定 sandbox 类型为 cube，否则走默认 WASI sandbox: cube # 指定 Wasm 模块路径（相对 weknora-server 工作目录） wasm_path: "agents/contract-v2.opt.wasm" # 资源配额（与 csb load 参数一致） memory_limit: "256M" timeout: 45 # 环境变量（传递给 Wasm 模块） env: LEGAL_DB_URL: "postgres://weknora:pass@127.0.0.1:5432/legal"

3. 加载 Agent 到 CubeSandbox：

   sudo -u weknora csb load \ --id contract-v2 \ --wasm /opt/weknora/agents/contract-v2.opt.wasm \ --memory 256M \ --timeout 45s \ --env LEGAL_DB_URL=postgres://weknora:pass@127.0.0.1:5432/legal

4. 验证 Agent 可用性：

   curl -X POST http://localhost:2019/agent/contract-v2 \ -H "Content-Type: application/json" \ -d '{"input": "甲方应于2024年12月31日前支付全部款项"}' # 期望返回：{"output":"【风险提示】付款期限未明确具体时间点，建议补充‘当日24:00前’"}

5. 配置 Caddy 路由（编辑/etc/caddy/Caddyfile）：

   your-domain.com { reverse_proxy /agent/contract-v2* 127.0.0.1:8080 @contract_rate_limit { header_regexp ip {http.request.remote.host} ^\d+\.\d+\.\d+\.\d+$ } route @contract_rate_limit { rate_limit 30 1m {http.request.remote.host} } }

6. 重载 Caddy 配置：

   caddy reload

7. 在 Grafana 中导入预置看板（ID18245，WeKnora Agent Dashboard）：

   • 访问http://your-server:3000
   • Settings → Dashboards → Import → 输入18245→ Load

8. 设置告警规则（Prometheusalerts.yml）：

   groups: - name: weknora-alerts rules: - alert: AgentLoadHighLatency expr: histogram_quantile(0.99, rate(wasm_load_duration_seconds_bucket[1h])) > 1.5 for: 5m labels: severity: warning annotations: summary: "Wasm 加载 P99 耗时超过 1.5s" - alert: SandboxOOMKilled expr: count by (instance) (rate(process_start_time_seconds{job="weknora"}[1h])) == 0 for: 1m labels: severity: critical annotations: summary: "WeKnora 进程被 OOM Killer 终止，请检查 MemoryLimit 配置"

4.3 健康检查与日常运维 SOP

每日巡检清单（DevOps 工程师执行）：

• systemctl status weknora：确认 Active: active (running)，且Main PID无频繁变化；
• csb list：确认所有 Agentstatus为active，memory_usage无持续增长（排除内存泄漏）；
• journalctl -u weknora -n 50 --no-pager：检查最近 50 行日志，搜索ERROR、panic、OOM关键字；
• curl -s http://localhost:9090/healthz：Prometheus 健康检查端点，返回ok；
• curl -s http://localhost:3100/readyz：Loki 就绪检查，返回ready；
• Grafana 看板中Agent 实例数是否与预期一致（如应为 5，实际为 3，则需排查csb load失败原因）。

紧急故障处理手册：

• 现象：所有 Agent 返回 502 Bad Gateway
  → 先curl http://127.0.0.1:8080/health，若失败，则systemctl restart weknora；
  → 若仍失败，journalctl -u weknora -n 100查看是否因配置文件语法错误导致启动失败（常见于config.yaml缩进错误）。

• 现象：某个 Agent 响应极慢，但其他正常
  →csb list | grep <agent-id>，查看last_active是否陈旧（>5min），若是，则csb unload --id <id>后csb load重载；
  → 若重载后仍慢，csb stats --id <id>查看cpu_time_ms是否异常高（>10s/req），确认是否 Agent 逻辑存在死循环。

• 现象：Caddy 日志大量upstream failed
  →ss -tlnp | grep :8080确认 weknora-server 进程监听端口；
  →netstat -anp | grep :8080查看连接数是否达上限（默认 1024），若满，则修改weknora-server启动参数--max-connections=4096。

5. 常见问题与排查技巧实录：那些文档里不会写的坑

5.1 Wasm 模块加载失败的 5 种真实原因与诊断法

WeKnora 的错误日志有时很模糊，比如只报Failed to load Wasm module。以下是我们在生产环境中总结的 5 种高频原因及精准定位方法：