在 Windows WSL2 环境下部署京东智能体框架

最近在公司内部做智能体平台，需要把前端、后端、Python 工具链和若干微服务全部封装进 Docker。开发环境是 Windows，所以最终方案是：Windows + WSL2 + Docker Desktop。这篇文章记录整个过程，包括中途踩到的一些坑，希望对后来者有帮助。
最终修改了dockerfile解决了问题。

---

一、基础环境准备

1. 安装 WSL2

Windows Terminal 输入：

wsl --install

重启后安装好 Ubuntu（我用的是 Ubuntu 22.04）。

2. 安装 Docker Desktop

Docker Desktop 默认支持 WSL2，只要勾选 “Use WSL2 based engine” 即可。
安装完成可用以下命令检查：

docker version

如果返回客户端 + 服务端版本号，说明正常。

---

二、项目结构说明

京东智能体项目分成三部分：

模块	说明
genie-ui	前端（Node + Vite + pnpm）
genie-backend	后端（Spring Boot）
genie-client / genie-tool	Python 工具链（使用 uv 管理依赖）

整体需要打包成一个多阶段 Dockerfile，并在最终镜像中启动所有服务。

---

三、切换 Debian 源（解决 apt 502）

前段时间 Docker 构建经常报：

502  Bad Gateway [IP: 151.101.90.132 80]

典型发生在 openjdk 或 gcc 下载的时候。
解决办法是把 Debian 源统一换成阿里云。

在 Dockerfile 中加入：

RUN rm -rf /etc/apt/sources.list.d/* && \
    echo "deb https://mirrors.aliyun.com/debian/ bookworm main contrib non-free non-free-firmware" > /etc/apt/sources.list && \
    echo "deb https://mirrors.aliyun.com/debian-security bookworm-security main contrib non-free non-free-firmware" >> /etc/apt/sources.list && \
    echo "deb https://mirrors.aliyun.com/debian/ bookworm-updates main contrib non-free non-free-firmware" >> /etc/apt/sources.list

另外最好加一个重试：

apt-get update -o Acquire::Retries=3

这样能显著减少构建失败。

---

四、前端构建相关问题

前端采用 pnpm + Vite。有一个问题非常典型：
TypeScript 中未使用的变量会导致构建失败（exit code 1）。

错误类似：

TS6133: 'useEffect' is declared but its value is never read.

由于我们不希望为了构建去修改业务代码，因此 Docker 中使用较宽松的方式：

RUN pnpm build --force || true

这样即便有 TS 警告也不会中断。

同时，前端源镜像配置为：

RUN npm config set registry https://registry.npmmirror.com
RUN npm install -g pnpm@7.33.1

保证依赖下载顺畅。

---

五、后端构建

后端使用 Maven + OpenJDK 17，比较简单：

FROM maven:3.8-openjdk-17 as backend-builder
WORKDIR /app
COPY genie-backend/pom.xml .
COPY genie-backend/src ./src
COPY genie-backend/build.sh genie-backend/start.sh ./
RUN chmod +x build.sh start.sh
RUN ./build.sh

编译输出会进入 /app/backend/target。

---

六、Python 工具链（uv）

这一部分比较新：团队采用了 uv（比 pip 更快）管理依赖。
在 Docker 中先把 uv 装好：

RUN pip install uv

然后进入不同 Python 组件执行：

uv venv .venv
source .venv/bin/activate
uv sync

所有 Python 模块（client + tool）都是这样处理的。

特别注意：uv 默认连官方 PyPI，对国内机器来说需要切换清华源：

export UV_DEFAULT_INDEX="https://pypi.tuna.tsinghua.edu.cn/simple"

不然后续包下载会非常慢。

---

七、最终镜像

前端构建、后端构建、Python 工具链全部完成后，进入最终镜像：

• 安装 Node（给前端 UI 配置代理和服务使用）
• 安装 OpenJDK（后端 Jar 运行必备）
• 启动脚本 start_genie.sh 启动全部服务

最终暴露三个端口：

EXPOSE 3000 8080 1601

健康检查：

HEALTHCHECK \
    CMD curl -f http://localhost:3000 || exit 1

如果前端页面能正常访问，说明整个框架都运转了。

---

八、启动容器

Dockerfile 构建：

docker build -t jd-genie:latest .

运行：

docker run -d \
    -p 3000:3000 \
    -p 8080:8080 \
    -p 1601:1601 \
    --name jd-genie \
    jd-genie:latest

启动后访问：

• http://localhost:3000 → UI
• http://localhost:8080 → 后端
• 1601 → 工具链内部通信

---

九、常见问题记录

1. WSL 中找不到 docker 命令

说明系统仍然是 WSL1，升级：

wsl --set-version Ubuntu 2

2. pnpm build 出现 TS 警告导致构建中断

使用：

RUN pnpm build --force || true

3. apt 下载中途失败（502）

统一换阿里云源 + 增加重试（文章前半部分已写）。

---

十、结语

这次在 Windows + WSL2 做智能体框架的 Docker 部署，整体比直接在 Windows 下开发稳定许多。
遇到最多的问题其实都集中在包管理和网络源上，换了国内镜像之后构建成功率提升明显。