AgentENV常见问题排查快速定位KVM、权限与网络故障的实用清单【免费下载链接】AgentENVAgentENV (AENV) is a distributed platform for running agent environments at scale.项目地址: https://gitcode.com/gh_mirrors/age/AgentENV部署 AgentENVAENV这个分布式 Agent 环境运行时平台时最常卡住的三类问题就是KVM 设备不可用、网络命名空间权限被拒、沙箱创建超时。本文整理成一份可逐条对照的排查清单帮你在 10 分钟内定位根因。官方问题清单见 docs/src/troubleshooting/common-issues.md内核与虚拟化检查逻辑在 src/setup/kvm.rs。一、KVM 设备缺失或无法访问症状启动时报KVM device not found (/dev/kvm)或/dev/kvm is not accessible for read/write。排查步骤确认设备是否存在ls -l /dev/kvm设备存在但打不开通常是运行用户不在kvm组。把用户加入组后重新登录会话sudo usermod -aG kvm $USER云服务主机往往不暴露标准 KVM未开启嵌套虚拟化。此时按 PVM 部署文档 准备 PVM 主机内核并加载kvm_pvm模块随后设置AENV_VIRTUALIZATION_MODEpvm。 PVM 模式仅支持 x86_64且kvm_pvm模块未加载时 PVM 无法启动kvm_pvm已加载时标准 KVM 模式也会被拒绝启动。二、虚拟化模式与主机不匹配症状日志提示 KVM 无法启动但 PVM 模块已加载或反过来。解决方法常规安装保持默认 KVM 模式即可已按 PVM 文档准备过主机的节点确保服务环境含AENV_VIRTUALIZATION_MODEpvm环境变量优先于 TOML 中的virtualization_mode参考 docs/src/configuration/env-vars.md 与 config/default.toml集群内不要混用 KVM 与 PVM 节点快照和暂停沙箱只能在创建它的模式下恢复。三、网络操作 Permission Denied症状创建沙箱时报网络命名空间或 iptables 权限错误。解决方法AgentENV 服务需要在 effective、permitted 和 inheritable 三组中都具备CAP_NET_ADMIN与CAP_SYS_ADMIN官方安装脚本写入的 systemd unit 已自动配置这两个 capability见 scripts/install.sh源码检出场景请使用make start-server或 scripts/run-with-capabilities.sh 包裹启动不要直接以 root 运行整个服务同时确认运行账户属于kvm组、可打开/dev/kvm和/dev/ublk-control。大规模部署时还需关注内核参数ARP 表、conntrack 表、pid_max 等AgentENV 会在启动时按 src/setup/network_capacity.rs 中的阈值做容量检查并给出警告。四、沙箱网络命名空间消失了症状沙箱明明在运行但ip netns list里看不到对应命名空间。解决方法AgentENV 把命名空间挂载点放在$AENV_RUNTIME_PATH/netns安装服务默认为/run/aenv/netns而不是系统默认的/var/run/netns。直接查看该目录按路径进入命名空间sudo nsenter --net/run/aenv/netns/agentenv-ns-slot ip addr沙箱网络的完整数据面veth/TAP 拓扑、命名空间防火墙、egress 代理说明见 docs/src/internals/networking.md。五、其他高频启动问题症状原因解决方法Error: config file not found默认读取config/default.toml在仓库根目录运行或设置AENV_CONFIG_PATHAddress already in use8000 端口被占用停掉占用进程或API_ADDR0.0.0.0:8001 make start-serverPOST /sandboxes超时运行时资产Firecracker、内核、rootfs未下载成功运行cargo run --bin server -- --setup-only手动补下并查看详细错误envd 初始化超时rootfs 过大默认 60 秒不够调大 config/default.toml 中[envd].init_timeout_secs六、快速自查清单ls -l /dev/kvm—— 设备是否存在且当前用户可读写id—— 运行账户是否在kvm组改组后需重启会话uname -r—— 内核是否 6.8PVM 场景是否进入 PVM 内核sudo journalctl -u aenv -f—— 观察启动阶段报的第一个错误curl http://127.0.0.1:8000/health—— 确认服务健康查看/run/aenv/netns—— 确认沙箱命名空间按预期创建⚠️ 生产服务器更换 PVM 内核前务必保留控制台访问等恢复手段。完成以上排查后仍无法解决可参考 手动编译部署文档 重新走一遍完整启动流程绝大多数问题都会在某个步骤的错误日志中暴露出来。【免费下载链接】AgentENVAgentENV (AENV) is a distributed platform for running agent environments at scale.项目地址: https://gitcode.com/gh_mirrors/age/AgentENV创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
