OpenSumi 在 Windows 11 下 Docker 部署问题分析与解决方案

问题背景

OpenSumi 是一款优秀的开源 IDE 框架，但在 Windows 11 系统下通过 Docker 部署时，开发者可能会遇到端口访问异常的问题。具体表现为：虽然容器编译过程没有报错，8000 端口可以访问但返回 404 错误，而 8080 和 8899 端口则完全无法访问。

问题分析

经过深入排查，发现问题的根源在于 OpenSumi 的默认启动配置和 Docker 环境变量设置不当。具体原因如下：

1. 启动命令不匹配：默认的 yarn start 命令仅监听 localhost，不适用于容器化部署场景
2. WebSocket 连接失败：前端尝试连接 WebSocket 服务时使用了错误的地址（0.0.0.0）
3. 端口映射配置：虽然 Dockerfile 中声明了 EXPOSE，但运行时未正确映射所有必要端口

解决方案

1. 修改启动命令

将 Dockerfile 中的启动命令从 yarn start 改为 yarn start:remote，这是专门为远程/容器化部署设计的启动脚本：

CMD [ "yarn", "start:remote" ]

2. 确保端口映射完整

运行容器时必须正确映射所有三个关键端口：

docker run -d --name=sumi1 -p 8080:8080 -p 8000:8000 -p 8899:8899 sumi-core

3. 优化后的完整 Dockerfile

以下是经过验证可用的 Dockerfile 配置：

FROM node:lts as builder

# 用户工作空间，用于打包到前端工作空间地址
ENV WORKSPACE_DIR workspace
ENV EXTENSION_DIR extensions
ENV WEBIDE /app/webide

# 设置各种镜像和下载主机
ENV ELECTRON_MIRROR https://npmmirror.com/mirrors/electron/
ENV PUPPETEER_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries
ENV sass_binary_site=https://npm.taobao.org/mirrors/node-sass/
ENV sharp_binary_host=https://mirrors.cloud.tencent.com/npm/sharp/-/sharp-0.31.1.tgz
ENV sentrycli_cdnurl=https://mirrors.cloud.tencent.com/npm/sentry-cli/
ENV electron_mirror=https://mirrors.cloud.tencent.com/npm/electron/
ENV chromedriver_cdnurl=https://mirrors.cloud.tencent.com/npm/chromedriver
ENV operadriver_cdnurl=https://mirrors.cloud.tencent.com/npm/operadriver
ENV python_mirror=https://pypi.tuna.tsinghua.edu.cn/simple/
ENV electron_builder_binaries_mirror=https://mirrors.cloud.tencent.com/npm/electron-builder-binaries/
ENV node_sqlite3_binary_host_mirror=https://mirrors.cloud.tencent.com/npm
ENV puppeteer_download_host=https://mirrors.cloud.tencent.com/npm
ENV sqlite3_binary_site=https://mirrors.cloud.tencent.com/npm/sqlite3/
ENV selenium_cdnurl=https://mirrors.cloud.tencent.com/npm/selenium
ENV node_inspector_cdnurl=https://mirrors.cloud.tencent.com/npm/node-inspector

# 创建目录
RUN mkdir -p ${WORKSPACE_DIR} &&\
    mkdir -p ${EXTENSION_DIR}
RUN mkdir -p ${WEBIDE}

# 复制所有项目文件
COPY . ${WEBIDE}

WORKDIR ${WEBIDE}

# 配置npm镜像
RUN yarn config set -H npmRegistryServer "https://registry.npmmirror.com" && \
    yarn --network-timeout 1000000

# 安装必要的库
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
    libsecret-1-dev && \
    rm -rf /var/lib/apt/lists/*

# 设置PKG_CONFIG_PATH环境变量
ENV PKG_CONFIG_PATH /usr/lib/x86_64-linux-gnu/pkgconfig:/usr/lib/pkgconfig

# 分步执行构建命令
RUN yarn install && echo "yarn install completed"
RUN yarn run rebuild:node && echo "yarn run rebuild:node completed"
RUN yarn run init && echo "yarn run init completed"

# 暴露端口
EXPOSE 8080
EXPOSE 8000
EXPOSE 8899
ENV HOST 0.0.0.0

# 使用远程启动命令
CMD [ "yarn", "start:remote" ]

技术要点解析

1. start vs start:remote：

   • start：默认开发模式，仅监听localhost
   • start:remote：专为远程访问设计，监听0.0.0.0

2. 端口作用：

   • 8080：主应用端口，提供Web界面
   • 8000：WebSocket服务端口，用于实时通信
   • 8899：扩展服务端口，支持插件功能

3. Windows特定问题：

   • Windows的Docker实现与Linux有差异，需要特别注意端口映射
   • Windows防火墙可能会阻止容器间通信，需要适当配置

验证部署成功

成功部署后，您应该能够：

1. 通过8080端口访问Web界面
2. 开发者工具中不再出现WebSocket连接错误
3. 所有功能模块正常工作

总结

在Windows 11环境下部署OpenSumi时，正确配置启动命令和端口映射是关键。通过使用start:remote命令并确保所有必要端口正确映射，可以解决大多数访问问题。这个解决方案不仅适用于Windows，对于其他操作系统下的Docker部署也有参考价值。