workbuddy容器化部署要求docker engine≥24.0.0（推荐24.0.7–24.0.9），docker-compose≥v2.20.0，containerd≥v1.7.18，runc为1.1.12或1.1.13，且cgroup v2与kernel≥5.15需启用。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您尝试在Linux服务器上通过Docker容器化方式部署WorkBuddy，但服务无法启动或镜像拉取失败，则可能是由于Docker版本不满足最低运行要求。以下是验证与适配Docker版本的详细步骤：
一、官方明确支持的Docker版本范围
Docker版本过低会导致容器运行时兼容性异常，例如无法解析多架构镜像清单、gRPC通信初始化失败或挂载卷权限拒绝。WorkBuddy官方严格限定Docker运行时版本下限，且仅对特定小版本组合完成全链路测试。
1、Docker Engine必须为24.0.0或更高版本，低于24.0（如23.0、20.10）将触发启动校验失败并中止容器初始化。
2、推荐使用Docker 24.0.7–24.0.9稳定子版本，该区间已通过腾讯云CI/CD流水线全场景回归验证，包括arm64多架构镜像加载、Claw Token动态注入、ext4文件系统挂载一致性等关键路径。
3、Docker Desktop不在支持范围内，所有容器化部署仅面向Linux服务器原生Docker Engine，Windows/macOS上的Docker Desktop因内核桥接与cgroup v2模拟缺陷，会导致workbuddy-service进程崩溃退出。
二、docker-compose版本协同要求
docker-compose作为编排工具，其YAML解析器与Docker API客户端版本需与底层Docker Engine严格对齐，否则会出现服务定义字段被忽略、健康检查未生效或环境变量注入为空等问题。
1、docker-compose必须为v2.20.0或更高版本，低于v2.19.0将无法识别workbuddy-service配置中的x-claw-extensions扩展字段。
2、禁止混用独立二进制版docker-compose与Docker Desktop内置版本，须统一通过curl -L https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose方式安装。
3、执行docker-compose version命令后，输出中“docker-compose version”与“docker-py version”两行必须同时存在且无警告提示，缺失任一则表明Python依赖未就绪。
三、运行时组件兼容性验证步骤
即使Docker与docker-compose版本达标，若底层容器运行时（containerd或runc）版本陈旧，仍可能引发沙箱隔离失效、信号传递中断或内存限制不生效等深层问题。
1、执行containerd --version，确认输出版本不低于v1.7.18；低于此版本需升级containerd并重启docker服务。
2、执行runc --version，确认runc版本为1.1.12或1.1.13，v1.1.14存在ARM64平台SIGCHLD丢失缺陷，已被WorkBuddy服务端主动屏蔽。
3、运行docker info | grep -E "(Cgroup|Kernel)"，确保Cgroup版本为v2且Kernel版本≥5.15，否则需在GRUB中添加systemd.unified_cgroup_hierarchy=1参数并重启。
