需先安装Docker Desktop并启用WSL2，再配置Qoder项目级Docker参数、镜像加速与私有仓库，最后通过构建、运行及健康检查验证全栈容器化流水线。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望在Qoder平台中实现全栈开发的容器化部署，但本地Docker环境尚未就绪或配置异常，则可能是由于Docker Desktop未安装、WSL2集成未启用、权限策略限制或端口映射未正确设置。以下是完成Qoder全栈开发容器化环境配置的步骤：
一、安装并验证Docker Desktop基础环境
Docker Desktop是Qoder容器化工作流的前提运行时，提供Linux容器支持、镜像管理及本地Kubernetes集群能力，所有Qoder生成的Dockerfile均依赖其构建与运行时环境。
1、访问Docker官网下载对应操作系统的Docker Desktop安装包。
2、Windows用户执行安装程序时勾选“Install WSL2 Linux kernel update”和“Enable Docker Desktop on Windows Subsystem for Linux (WSL2)”两项；macOS用户需确保系统为macOS 14+且已启用Full Disk Access权限。
3、安装完成后启动Docker Desktop，等待右下角鲸鱼图标变为绿色稳定状态，然后在终端执行docker --version与docker run hello-world，确认输出无报错且显示欢迎信息。
二、启用WSL2并配置Qoder兼容性模式
Qoder CLI在执行qodercli agent start或生成Docker化全栈应用时，会自动调用docker build命令；若宿主机为Windows且未启用WSL2后端，构建过程将因内核不兼容而失败。
1、以管理员身份打开PowerShell，依次执行：wsl --install、wsl --set-default-version 2、wsl --update。
2、进入Windows功能设置，启用“虚拟机平台”与“Windows Subsystem for Linux”；重启后在Microsoft Store中安装Ubuntu 22.04 LTS发行版。
3、在Ubuntu终端中运行sudo apt update && sudo apt install -y docker.io，再执行sudo usermod -aG docker $USER，退出并重新登录以生效组权限。
三、配置Qoder项目级Docker构建参数
Qoder默认生成的Dockerfile基于Alpine Linux与multi-stage构建，但部分Go/CGO项目或前端SSR服务需显式指定构建上下文、目标阶段及端口暴露策略，否则容器启动后无法响应Qoder Agent的HTTP探测请求。
1、在Qoder项目根目录创建.qoder/docker/config.yaml文件，写入以下内容：
2、设置构建参数：build_context: .、target_stage: production、expose_ports: ["3000:3000", "8080:8080"]。
3、如项目含前端+Node.js后端双服务，需在config.yaml中添加multi_service: true并为每个服务定义service_name与health_check_path字段。
四、启用Docker镜像加速与私有仓库绑定
Qoder在Quest Mode中拉取基础镜像（如qoder/node:18-alpine、qoder/go:1.25-slim）时若遭遇超时或校验失败，通常源于国内网络对Docker Hub直连不稳定，需配置镜像加速器并授权私有Registry。
1、Windows/macOS用户打开Docker Desktop设置 → Docker Engine，将registry-mirrors字段替换为：["https://docker.mirrors.ustc.edu.cn", "https://hub-mirror.c.163.com"]。
2、执行docker login registry.qoder.com，使用Qoder OAuth账号绑定的邮箱与个人访问令牌（PAT）完成认证。
3、在项目.qoder/config.yml中添加image_registry: registry.qoder.com/qoder-ai，确保后续qodercli build命令推送至企业级镜像仓库而非Docker Hub。
五、验证Qoder容器化流水线端到端可用性
该步骤用于确认Qoder生成的容器镜像可被正确构建、运行、健康检查通过，并能响应Agent任务触发的API调用，是容器化开发闭环的关键验证点。
1、在Qoder项目中执行qodercli quest "deploy a fullstack app with React frontend and Express backend"，等待CLI输出Dockerfile generated日志。
2、运行qodercli build --tag myapp:v1.0.0，观察控制台是否完成STEP 1/12 : FROM...至Successfully built xxxxx全流程。
3、执行docker run -d -p 3000:3000 --name qoder-test myapp:v1.0.0，随后立即调用curl http://localhost:3000/healthz，返回{"status":"ok"}即表示容器服务已就绪。
