利用 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` 这是构建时的配置文件，里面只需要简单的写如下内容即可： ```yml pkgout: ./ icon: ./logo.png ``` - `lzc-manifest.yml` 这是最重要的应用设置： ```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 ``` 然后通过下面的命令把应用安装到懒猫微服中（请确保你的电脑已经连接了懒猫微服）： ```sh lzc-cli project build lzc-cli app install ./my-dev-box-v1.103.1.lpk ``` 运行完成后，我们就可以在应用列表上看到刚才上传的应用了。 ![1761014939638.jpg](https://dl.playground.lazycat.cloud/guidelines/799/978af226-b1a7-4eef-87f1-6360151c2185.jpg "1761014939638.jpg") 注意，应用启动时，会去拉取镜像，如果你所在的网络不幸拉取失败： ![1761015797124.jpg](https://dl.playground.lazycat.cloud/guidelines/799/7bb57b8e-9778-48e5-b283-5849546ab71b.jpg "1761015797124.jpg") 可以试试下面的解决方式： ```sh lzc-cli appstore copy-image gitpod/openvscode-server:latest ``` 输入完用户名和密码后它会自动拉取，完成后会给你返回一个懒猫镜像仓库的地址 ``` 登录成功! uploading ... b268dd24: [####################################################################################################] 100% uploaded: registry.lazycat.cloud/scarlex/gitpod/openvscode-server:4ced994585627e2b ``` 我们可以使用这个镜像地址： ```diff services: openvscode-server: - image: gitpod/openvscode-server:latest + image: registry.lazycat.cloud/scarlex/gitpod/openvscode-server:4ced994585627e2b ``` 然后重新运行刚才的 `lzc-cli` 构建和安装应用的命令即可。当应用成功运行后，我们就能看到 OpenVSCode Server 的界面了： ![1761016450557.jpg](https://dl.playground.lazycat.cloud/guidelines/799/46909e77-247b-44fd-a80e-a59b7ef6e702.jpg "1761016450557.jpg") 对于开发者来说，我们经常在终端中运行常用的命令（如 `node`、`pnpm` 等），官方镜像并不会为我们预先安装这些命令： ![image.png](https://dl.playground.lazycat.cloud/guidelines/799/b3361ae8-dd7c-4732-ab66-257f19e3678c.png "image.png") 这时候我们就需要添加自定义的部分了。 ----- ## 2. 自定义开发环境要在 OpenVSCode Server 中添加自定义的工具，正确的做法是构建自定义镜像。在官方仓库的文档中建议我们通过这种方式去构建镜像： ```dockerfile FROM gitpod/openvscode-server:latest USER root RUN ... USER openvscode-server ``` 先切换成 `root` 用户，然后执行自定义的命令，最后切换会 `openvscode-server` 用户。这是面向生产环境的建议，作为开发环境，我认为直接使用 `root` 用户会更加方便。（~~我就是被 `openvscode-server` 的用户权限虐得不行才改用 `root` 的~~） ### 自定义 Docker 镜像我们先创建一份 `Dockerfile`: ```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`，把构建命令添加到里面后我们就能方便调试了 ```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` 随意）为它添加可执行权限并运行： ```sh chmod +x ./build-docker-image.sh ./build-docker-image.sh ``` 运行成功后会看到这样的输出 ![image.png](https://dl.playground.lazycat.cloud/guidelines/799/bae38ed8-4a1c-4223-9740-ea1b52c87c92.png "image.png") ### 使用自定义镜像这时候我们需要修改 `lzc-manifest.yaml` 文件 ```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..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` 然后运行刚才的安装脚本 ```sh lzc-cli project build lzc-cli app install ./my-dev-box-v1.103.1.lpk ``` 打开懒猫微服中的 DevBox ![image.png](https://dl.playground.lazycat.cloud/guidelines/799/6ea21db2-02bd-4512-83b0-196b76996e60.png "image.png") 我们刚才的改动生效了。试试使用 pnpm 创建项目并运行一下： ![image.png](https://dl.playground.lazycat.cloud/guidelines/799/0251255f-3984-4aea-a931-e93abd63ab0e.png "image.png") 我们启动了 vite 服务器，暴露了 5173 端口，这时候通过浏览器域名访问该端口 ![image.png](https://dl.playground.lazycat.cloud/guidelines/799/046eb14a-c9cf-4cbd-8be9-6d116f50dcc7.png "image.png") 这时候是无法从外部访问的。 ### 3. 局域网端口转发 #### 让开发服务器允许被外部访问默认情况下，vite 的开发服务器只能在 `localhost` 下访问，而它运行在 OpenVSCode Server 容器内，外部是无法访问的。我们需要在 openvscode-server 里面修改一下 `vite.config.ts` 的配置 ```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` 启动开发服务器。 #### 进行局域网端口转发我们需要使用「局域网端口转发工具」把宿主机的端口转发到应用内部的端口中。 https://appstore.lazycat.cloud/#/shop/detail/cloud.lazycat.app.forward ![image.png](https://dl.playground.lazycat.cloud/guidelines/799/76305d87-0cb3-492c-b391-b0ee58da55e9.png "image.png") 按照上图中的配置，配置后点击「测试连接」按钮，如果成功转发的话就会有成功的提示。转发成功后，我们就可以在浏览器中 `http://:` 的方式访问该项目的开发服务器了！ ![image.png](https://dl.playground.lazycat.cloud/guidelines/799/3a450fd4-e69a-44d7-b4d6-d943ac4048ab.png "image.png") 注意，此处我们需要使用 `http` 协议才能正常访问。 ## 结语通过上面的案例，我们可以实现一个远程开发环境的搭建，后续的玩法就留给大家发挥了。 Happy Coding ！