利用 OpenVSCode Server 打造远程开发环境

简介

OpenVSCode Server 是 VSCode 的浏览器化版本，只需要一个容器即可在任意设备上获得接近桌面版的开发体验。这正好可以把开发环境托管在懒猫微服里，通过浏览器随时接入。

本文围绕懒猫微服给出一套完整的 OpenVSCode Server 部署玩法：从选择合适的镜像、准备项目文件、到构建自定义镜像与端口转发，帮助你把懒猫微服升级成随取随用的远程开发工作站。

---

版本选择

目前社区比较主流的有两个镜像来源，它们都能在懒猫微服上顺利运行，但侧重点略有差异：

• Gitpod 官方镜像：https://github.com/gitpod-io/openvscode-server
  • 更新节奏快，第一时间同步上游 OpenVSCode Server 的功能与安全修复
  • 预装扩展较少，适合作为「白纸」按需扩展；默认容器用户为 openvscode-server
  • 如果你打算完全自定义开发工具链、自己管理依赖，这个版本更容易作为基线
• LinuxServer 社区镜像：https://github.com/linuxserver/docker-openvscode-server
  • 内建 linuxserver.io 家族常见的 PUID / PGID 权限管理，适合多用户或需要和主机目录共享文件的场景
  • 额外提供健康检查、日志目录等默认配置，上手即用但镜像体积略大
  • 如果你希望少改动、快速使用并保留 LinuxServer 生态的一致体验，可以选择它

无论选择哪一版，都建议先按文档演练一次原始镜像的部署流程；后续需要扩展开发工具时再基于原镜像构建自定义版本即可。

---

0. 准备工作

搭建开发环境，详细的步骤请参考官方的开发者手册：https://developer.lazycat.cloud/lzc-cli.html

---

1. 让 OpenVSCode Server 跑起来

先准备三个文件：

• logo.png 这是应用图标

• lzc-build.yml 这是构建时的配置文件，里面只需要简单的写如下内容即可：

pkgout: ./
icon: ./logo.png

• lzc-manifest.yml 这是最重要的应用设置：

lzc-sdk-version: '0.1'
name: MyDevBox
package: my.devbox
version: 1.103.1
description: My Dev Box
application:
  background_task: true
  subdomain: devbox
  routes:
    - /=http://openvscode_server.my.devbox.lzcapp:3000

services:
  openvscode_server:
    image: gitpod/openvscode-server:latest
    container_name: openvscode_server
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - CONNECTION_TOKEN= #optional
      - CONNECTION_SECRET= #optional
      - SUDO_PASSWORD=password #optional
      - SUDO_PASSWORD_HASH= #optional
    binds:
      - /lzcapp/var/config:/config
      - /lzcapp/var/workspace:/home/workspace
    ports:
      - 3000:3000
    restart: unless-stopped

然后通过下面的命令把应用安装到懒猫微服中（请确保你的电脑已经连接了懒猫微服）：

lzc-cli project build
lzc-cli app install ./my-dev-box-v1.103.1.lpk

运行完成后，我们就可以在应用列表上看到刚才上传的应用了。

注意，应用启动时，会去拉取镜像，如果你所在的网络不幸拉取失败：

可以试试下面的解决方式：

lzc-cli appstore copy-image gitpod/openvscode-server:latest

输入完用户名和密码后它会自动拉取，完成后会给你返回一个懒猫镜像仓库的地址

登录成功!
uploading
...
b268dd24: [####################################################################################################] 100%

uploaded:  registry.lazycat.cloud/scarlex/gitpod/openvscode-server:4ced994585627e2b

我们可以使用这个镜像地址：

  services:
    openvscode-server:
-     image: gitpod/openvscode-server:latest
+     image: registry.lazycat.cloud/scarlex/gitpod/openvscode-server:4ced994585627e2b

然后重新运行刚才的 lzc-cli 构建和安装应用的命令即可。

当应用成功运行后，我们就能看到 OpenVSCode Server 的界面了：

对于开发者来说，我们经常在终端中运行常用的命令（如 node、pnpm 等），官方镜像并不会为我们预先安装这些命令：

这时候我们就需要添加自定义的部分了。

---

2. 自定义开发环境

要在 OpenVSCode Server 中添加自定义的工具，正确的做法是构建自定义镜像。在官方仓库的文档中建议我们通过这种方式去构建镜像：

 FROM gitpod/openvscode-server:latest

 USER root

 RUN ...

 USER openvscode-server

先切换成 root 用户，然后执行自定义的命令，最后切换会 openvscode-server 用户。

这是面向生产环境的建议，作为开发环境，我认为直接使用 root 用户会更加方便。 （我就是被 openvscode-server 的用户权限虐得不行才改用 root 的）

自定义 Docker 镜像

我们先创建一份 Dockerfile:

FROM gitpod/openvscode-server:latest

USER root

# 更新包列表并安装必要的依赖
RUN sed -i "s/deb.debian.org/mirrors.ustc.edu.cn/g" "/etc/apt/sources.list" && \
    sed -i "s/archive.ubuntu.com/mirrors.ustc.edu.cn/g" "/etc/apt/sources.list" && \
    sed -i "s/security.ubuntu.com/mirrors.ustc.edu.cn/g" "/etc/apt/sources.list" && \
    apt-get update && \
    curl -fsSL https://deb.nodesource.com/setup_lts.x | bash - && \
    apt-get install -y nodejs zsh && \
    rm -rf /var/lib/apt/lists/*

ENV NPM_HOME="/root/.local/share/npm"
ENV PNPM_HOME="/root/.local/share/pnpm"
ENV PATH="$PNPM_HOME:$NPM_HOME/bin:$PATH"

RUN npm config set prefix $NPM_HOME && \
    npm config set registry https://registry.npmmirror.com && \
    npm install -g pnpm@latest-10 && \
    pnpm config set store-dir $PNPM_HOME/store

这份 Dockerfile 包含这些功能：

• 改用清华的源，加速 apt-get
• 安装 node.js 和 pnpm
• 设置缓存目录，方便重用依赖

然后创建一份 build-docker-image.sh，把构建命令添加到里面后我们就能方便调试了

USERNAME="lzc"
APPNAME="openvscode-server-devbox"
BOXNAME=$(lzc-cli box default)
docker build --platform linux/amd64 -t lzc/$APPNAME:latest . --no-cache
docker tag $USERNAME/$APPNAME:latest dev.$BOXNAME.heiyu.space/$USERNAME/$APPNAME:latest
docker push dev.$BOXNAME.heiyu.space/$USERNAME/$APPNAME:latest

它主要干了两件事：

• 构建自定义镜像
• 把构建好的镜像推送到懒猫微服中（注意 USERNAME 必须为 lzc， APPNAME 随意）

为它添加可执行权限并运行：

chmod +x ./build-docker-image.sh
./build-docker-image.sh

运行成功后会看到这样的输出

使用自定义镜像

这时候我们需要修改 lzc-manifest.yaml 文件

lzc-sdk-version: '0.1'
name: DevBox
package: my.devbox
version: 1.103.1
description: My Dev Box
application:
  background_task: true
  subdomain: devbox
  routes:
    - /=http://openvscode_server.my.devbox.lzcapp:3000

services:
  openvscode_server:
    image: dev.<DEVICE>.heiyu.space/lzc/openvscode-server-devbox:latest
    container_name: openvscode_server
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Etc/UTC
      - CONNECTION_TOKEN= #optional
      - CONNECTION_SECRET= #optional
      - SUDO_PASSWORD=password #optional
      - SUDO_PASSWORD_HASH= #optional
    binds:
      - /lzcapp/var/config:/config
      - /lzcapp/var/workspace:/home/workspace
      - /lzcapp/var/pnpm-store:/root/.local/share/pnpm/store
    user: root
    restart: unless-stopped

注意两个地方：

• image 改成 dev.$BOXNAME.heiyu.space/$USERNAME/$APPNAME:latest 的值
• user 改成 root

然后运行刚才的安装脚本

lzc-cli project build
lzc-cli app install ./my-dev-box-v1.103.1.lpk

打开懒猫微服中的 DevBox

我们刚才的改动生效了。

试试使用 pnpm 创建项目并运行一下：

我们启动了 vite 服务器，暴露了 5173 端口，这时候通过浏览器域名访问该端口

这时候是无法从外部访问的。

3. 局域网端口转发

让开发服务器允许被外部访问

默认情况下，vite 的开发服务器只能在 localhost 下访问，而它运行在 OpenVSCode Server 容器内，外部是无法访问的。

我们需要在 openvscode-server 里面修改一下 vite.config.ts 的配置

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vite.dev/config/
export default defineConfig({
  plugins: [vue()],
  server: {
    host: '0.0.0.0',
    port: 5173,
    allowedHosts: ['微服名.heiyu.space'], 
  }
})

这样才能在外部访问 vite 的开发服务器。其中 allowedHosts 我们等一会会使用到这个被允许的域名。

修改完成后，使用 pnpm dev 启动开发服务器。

进行局域网端口转发

我们需要使用 「局域网端口转发工具」把宿主机的端口转发到应用内部的端口中。

按照上图中的配置，配置后点击「测试连接」按钮，如果成功转发的话就会有成功的提示。

转发成功后，我们就可以在浏览器中 http://<微服域名>:<端口号> 的方式访问该项目的开发服务器了！

注意，此处我们需要使用 http 协议才能正常访问。

结语

通过上面的案例，我们可以实现一个远程开发环境的搭建，后续的玩法就留给大家发挥了。

Happy Coding ！