Qoder Docker 部署需按场景选择五种方案：一、CLI 无 GUI 实例；二、Ubuntu+X11 桌面级 GUI；三、多实例桥接网络隔离；四、NVIDIA GPU 加速；五、只读根文件系统安全强化。

☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

如果您希望在 Docker 环境中稳定运行 Qoder（注意：非 QoderWake，此处指 Qoder 主线产品）应用，但遇到容器启动失败、服务不可达、配置不生效或跨实例状态冲突等问题，则很可能是由于基础镜像兼容性、GUI 依赖缺失、X11 转发未配置或环境变量未正确注入所致。以下是针对 Qoder 容器化部署的高级实操路径：

一、使用官方 CLI 镜像启动无 GUI 沙盒实例

该方式适用于仅需调用 Qoder 核心引擎 API、执行自动化脚本或集成至 CI/CD 流水线的场景，完全规避图形界面依赖，实现最小化资源占用与最高隔离等级。

1、拉取经验证的轻量级 CLI 镜像：
docker pull registry.cn-hangzhou.aliyuncs.com/qoder/qoder:26.4.0-cli

2、创建专用配置挂载目录：
mkdir -p /opt/qoder/config-a /opt/qoder/data-a

3、启动容器并映射配置与数据卷：
docker run -d \
  --name qoder-instance-a \
  --restart unless-stopped \
  -v /opt/qoder/config-a:/app/config \
  -v /opt/qoder/data-a:/app/data \
  -e QODER_ENV=production \
  -e QODER_API_KEY=your_actual_api_key_here \
  -p 8081:8080 \
  registry.cn-hangzhou.aliyuncs.com/qoder/qoder:26.4.0-cli

4、验证容器内服务健康状态：
docker exec qoder-instance-a curl -s http://localhost:8080/health | jq .status

二、基于 Ubuntu+X11 转发的桌面级容器部署

该方式用于需要完整 GUI 交互、屏幕捕获、鼠标模拟等能力的生产级数字员工场景，通过宿主机 X11 socket 挂载与 DISPLAY 环境变量透传，使容器内 Qt 应用窗口可直接渲染至宿主桌面。

1、确认宿主机已启用本地 X11 访问控制：
xhost +local:

2、获取当前用户 DISPLAY 值：
echo $DISPLAY

3、构建支持 OpenGL 与 X11 的定制镜像，在 Dockerfile 中添加：
RUN apt-get update && apt-get install -y \
  libx11-xcb1 libxcb-xfixes0 libxcb-render0 libxcb-shape0 \
  libxcb-xinerama0 libxcb-randr0 libxcb-xtest0 libxcb-xkb1 \
  libxkbcommon-x11-0 libgl1-mesa-glx libegl1-mesa && \
  rm -rf /var/lib/apt/lists/*

4、运行容器时挂载 X11 socket 并设置显示变量：
docker run -d \
  --name qoder-gui-a \
  --privileged \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -e DISPLAY=unix$DISPLAY \
  -e QT_QPA_PLATFORM=xcb \
  -e GDK_BACKEND=x11 \
  -v $HOME/.qoder-profile-a:/root/.qoder \
  -p 8082:8080 \
  qoder-ubuntu-gui:26.4.0

三、多实例网络隔离与服务发现部署

当需在同一宿主机运行多个 Qoder 实例并要求彼此网络不可见、端口不冲突、且能通过内部 DNS 名称相互调用时，应采用自定义桥接网络配合 docker-compose 编排，避免默认 bridge 网络下的端口争抢与广播干扰。

1、创建专用网络：
docker network create --driver bridge --subnet 172.20.0.0/16 qoder-net

Agent CLI (Cursor + Qoder)

代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。

下载

2、编写 docker-compose.yml，为每个实例分配固定 IP 和独立配置卷：
version: '3.8'
services:
  qoder-prod:
    image: registry.cn-hangzhou.aliyuncs.com/qoder/qoder:26.4.0-cli
    container_name: qoder-prod
    networks:
      qoder-net:
        ipv4_address: 172.20.0.10
    volumes:
      - /opt/qoder/prod/config:/app/config
      - /opt/qoder/prod/data:/app/data
    environment:
      - QODER_ROLE=production
      - QODER_SERVICE_NAME=qoder-prod
  qoder-test:
    image: registry.cn-hangzhou.aliyuncs.com/qoder/qoder:26.4.0-cli
    container_name: qoder-test
    networks:
      qoder-net:
        ipv4_address: 172.20.0.11
    volumes:
      - /opt/qoder/test/config:/app/config
      - /opt/qoder/test/data:/app/data
    environment:
      - QODER_ROLE=test
      - QODER_SERVICE_NAME=qoder-test

3、一键启动全部实例：
docker-compose up -d

4、在 qoder-prod 容器内验证对 qoder-test 的 DNS 可达性：
docker exec qoder-prod ping -c 3 qoder-test

四、基于 NVIDIA Container Toolkit 的 GPU 加速部署

当 Qoder 实例需执行图像识别、OCR 或视频流处理等计算密集型任务时，必须启用 GPU 支持。此方案要求宿主机已安装 NVIDIA 驱动与 nvidia-container-toolkit，并在容器内加载 CUDA 运行时库。

1、验证宿主机 GPU 可见性：
nvidia-smi

2、安装 nvidia-container-toolkit：
curl -sL https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
curl -sL https://nvidia.github.io/nvidia-docker/ubuntu20.04/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-docker2
sudo systemctl restart docker

3、运行启用 GPU 的 Qoder 容器：
docker run -d \
  --name qoder-gpu-a \
  --gpus all \
  --device=/dev/video0 \
  -v /opt/qoder/gpu/config:/app/config \
  -e QODER_ENABLE_GPU=true \
  -e NVIDIA_VISIBLE_DEVICES=all \
  registry.cn-hangzhou.aliyuncs.com/qoder/qoder:26.4.0-gpu

4、进入容器确认 CUDA 工具包加载成功：
docker exec qoder-gpu-a nvidia-smi -L

五、安全强化型只读根文件系统部署

面向金融、政务等高合规要求场景，需禁用容器内任意写操作，强制所有运行时状态落盘至显式挂载的只读配置卷与临时内存卷，杜绝恶意篡改或持久化后门植入风险。

1、准备只读配置模板：
cp -r /path/to/template-config /opt/qoder/readonly-config
chmod -R 555 /opt/qoder/readonly-config

2、启用 tmpfs 存储运行时缓存：
docker run -d \
  --name qoder-secure-a \
  --read-only \
  --tmpfs /app/cache:rw,size=128m,exec \
  --tmpfs /app/logs:rw,size=64m,exec \
  -v /opt/qoder/readonly-config:/app/config:ro \
  -v /opt/qoder/secrets:/run/secrets:ro \
  -e QODER_CONFIG_SOURCE=mounted \
  -e QODER_DISABLE_WRITE_FS=true \
  registry.cn-hangzhou.aliyuncs.com/qoder/qoder:26.4.0-cli

3、验证根文件系统是否真正只读：
docker exec qoder-secure-a touch /test-write && echo "FAIL" || echo "PASS"