🚀 使用 Docker Compose 部署 custom code server（Web 版 VS Code）

🚀 使用 Docker Compose 部署 Code-Server

本文将详细介绍如何使用 Docker Compose 部署 Code-Server——一个允许您通过浏览器在任何地方使用 VS Code 的 Web IDE。采用 Docker 部署可以避免环境配置的麻烦，并保证开发环境的一致性。

📝 项目简介

Code-Server 是一个开源项目，它将在服务器端运行 VS Code，然后通过浏览器提供访问。这意味着您可以在具有一致开发环境的任何设备上编写代码，并利用云服务器的计算资源进行测试、编译等任务。

核心特点：

跨平台访问：在任何有浏览器的设备上访问您的开发环境
一致体验：提供与本地 VS Code 几乎相同的使用体验和丰富的插件支持
服务器资源：充分利用服务器性能进行编译、测试等密集型任务
数据持久化：通过卷挂载确保您的代码和配置不会丢失
多语言支持：通过预配置环境支持多种开发语言

📝 项目简介2

custom-code-server 是基于 官方 code-server（Web 版 VS Code）自定义构建的开发环境容器，核心优势是 “开箱即用的多语言开发能力”—— 通过 Dockerfile 预装了 C/C++（gcc/gdb）、Python、Node.js、Java、Go 等主流开发工具，无需手动配置环境，可通过浏览器直接访问 VS Code 界面，实现 “随时随地编码”。

核心特点

Web 化编码体验：无需安装本地 VS Code，浏览器访问 http://服务器IP:端口 即可使用完整 VS Code 功能（代码高亮、自动补全、终端、扩展安装）；
多语言开发支持：预装 gcc（C/C++）、Python3+pip、Node.js、OpenJDK 17、Go 1.22.2，覆盖后端、前端、嵌入式等开发场景；
数据持久化：项目代码（./project）、VS Code 配置（./config）、扩展（./config/code-server）均通过本地目录挂载，容器删除后数据不丢失；
灵活权限与安全：以 root 用户运行，支持调试（SYS_PTRACE 权限），解除 seccomp 限制（适配调试工具），同时可通过 PUID/PGID 调整用户权限；
资源可控：支持配置内存限制（默认 2G），避免开发过程中资源占用过高；
自定义可扩展：基于 Dockerfile 可按需添加工具（如 Rust、PHP），或升级开发工具版本，适配个性化需求。

🔧 部署前准备

系统环境要求

操作系统：支持 Linux、Windows、macOS
Docker 引擎：版本 20.10+
Docker Compose：版本 2.0+
硬件资源：
内存：至少 2GB（根据配置）
存储空间：至少 10GB 可用空间
网络：稳定的互联网连接

环境检查

检查 Docker 服务状态

   systemctl status docker

确保 Docker 服务处于 active (running) 状态

检查 Docker 版本

   docker --version

   mkdir -p /home/compose/code-server && cd /home/compose/code-server

⚙️ 配置 Docker Compose

准备 Dockerfile

创建 Dockerfile 文件，内容如下：

# 基础镜像：官方 code-server 4.8.3 版本（稳定版，避免自动更新导致兼容性问题）
FROM codercom/code-server:4.8.3

# 切换到 root 用户（需安装系统工具，普通用户无权限） # 切换到 root 安装工具
USER root

# 安装基础开发工具（C/C++、Python、Node.js、Java）# 安装开发工具
RUN apt-get update && apt-get install -y \
    build-essential gcc gdb python3 python3-pip nodejs openjdk-17-jdk

# 安装 Go 1.22.2（手动下载解压，避免 apt 源版本过旧）# 安装 Go
ARG GO_VERSION=1.22.2  # Go 版本（可修改为最新版，如 1.23.0）
RUN curl -OL https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz \
    && tar -C /usr/local -xzf go${GO_VERSION}.linux-amd64.tar.gz \  # 解压到 /usr/local/go
    && rm go${GO_VERSION}*  # 删除安装包，减少镜像体积

# 设置 Go 环境变量（确保全局可调用 go 命令） # 设置环境变量
ENV PATH="/usr/local/go/bin:${PATH}"

# 切换回 code-server 默认用户 coder（避免长期使用 root 带来的安全风险）# 切换回 coder 用户
USER coder

# 验证工具安装（确保所有开发工具可正常调用，便于排查安装问题）# 验证安装
RUN gcc --version && node --version && python3 --version && go version && java -version

构建自定义镜像

docker build -t custom-code-server .

准备 docker-compose.yml

创建 docker-compose.yml 文件，内容如下：

#version: '3'
services:
  custom-code-server:
    container_name: vscode-web  # 容器名称，便于管理（如停止/查看日志）
    restart: always  # 容器退出后自动重启（保障开发环境稳定，避免意外中断）
    ports:
      - 8083:8080  # 端口映射：主机 8083 → 容器 8080（容器内 code-server 默认端口为 8080）
    volumes:
      # 1. 项目代码目录：本地 ./project → 容器 /home/coder/project（开发项目存储在此）
      - ./project:/home/coder/project
      # 2. VS Code 全局配置目录：本地 ./config → 容器 /home/coder/.config（主题、快捷键）
      - ./config:/home/coder/.config
      # 3. VS Code 扩展目录：本地 ./config/code-server → 容器对应路径（安装的插件持久化）
      - ./config/code-server:/home/coder/.config/code-server
      # 仅挂载项目目录，不需要挂载工具二进制文件
    environment:
      - XDG_DATA_HOME=/home/coder/.local/share  # 数据存储路径（扩展、缓存）
      - EXTENSIONS_DIR=/home/coder/.local/share/code-server/extensions  # 扩展安装路径
      - PASSWORD=aaaaaa  # Web 登录密码！建议修改为强密码（如 VSCode@2024!）
      - TZ=Asia/Shanghai  # 时区同步（确保终端时间与本地一致，避免日志时间错乱）
      - PUID=0  # 用户 ID（0 为 root，可改为普通用户 ID，如 1000）
      - PGID=0  # 用户组 ID（与 PUID 一致）
    image: custom-code-server  # 使用本地构建的自定义镜像（非官方镜像）  # 使用你构建的镜像
    user: root  # 以 root 用户运行（便于安装系统工具、调试程序）
    cap_add:
      - SYS_PTRACE  # 赋予调试权限（gdb 调试程序必需，删除后无法调试）  # 用于调试
    security_opt:
      - seccomp:unconfined  # 解除 seccomp 安全限制（适配调试工具，避免调试时权限报错）
    deploy:
      resources:
        limits:
          memory: 2G  # 内存限制（避免开发时内存占用过高，可根据服务器配置调整为 4G/8G）

#打开命令终端，cd进项目，运行.c生成文件
#cd project
#gcc test.c -o test

关键配置说明

镜像选择：基于官方 codercom/code-server:4.8.3 镜像构建自定义镜像
端口映射：8083:8080 将容器内的 8080 端口映射到宿主机的 8083 端口
数据持久化：
./project:/home/coder/project：项目代码目录
./config:/home/coder/.config：VS Code 配置目录
./config/code-server:/home/coder/.config/code-server：Code-Server 特定配置
环境变量：
PASSWORD：设置访问密码
TZ：设置时区为上海
PUID 和 PGID：设置用户和组 ID
开发工具：Dockerfile 中预装了 GCC、Python、Node.js、Java 和 Go 等多语言开发环境

🚀 启动与验证

启动服务

docker compose up -d

验证服务状态

检查容器运行状态 bash docker ps 应该看到 vscode-web 容器处于 Up 状态
查看服务日志 bash docker compose logs -f
访问 Web 界面 在浏览器中访问 http://你的服务器IP:8083

初始登录

输入配置文件中设置的密码：aaaaaa
成功登录后将看到熟悉的 VS Code 界面

（2）访问 Web 版 VS Code 界面

打开浏览器，输入 http://服务器IP:8083（如本地测试：http://localhost:8083，远程服务器：http://192.168.1.100:8083）；
输入 docker-compose.yml 中配置的 PASSWORD（如默认 clxr20），点击「Submit」登录；
登录后进入 VS Code 界面（与本地 VS Code 布局一致，含左侧活动栏、中间编辑区、底部终端），说明服务正常。

（3）验证开发工具是否可用

通过 VS Code 内置终端验证预装工具（关键！确保开发环境可用）：

1.打开终端：点击界面底部「Terminal」→「New Terminal」； 2.执行以下命令，查看工具版本（均需正常输出，无 “command not found”）：

    # 验证 C 编译器
    gcc --version
    # 验证 Python
    python3 --version && pip3 --version
    # 验证 Node.js
    node --version && npm --version
    # 验证 Java
    java --version && javac --version
    # 验证 Go
    go version

🔌 基础配置与使用

开发环境验证

1.创建测试文件在终端中执行：

   cd project
   echo '#include <stdio.h>

   int main() {
       printf("Hello, Code-Server!\\n");
       return 0;
   }' > test.c

2.编译和运行

   gcc test.c -o test
   ./test

应该看到输出：Hello, Code-Server!

多语言开发环境

您的环境已预配置：

语言	版本验证命令	用途
C/C++	`gcc --version`	系统编程
Python	`python3 --version`	脚本开发
Node.js	`node --version`	JavaScript 开发
Java	`java -version`	企业级应用
Go	`go version`	后端开发

扩展管理

通过 VS Code 扩展市场安装所需插件：

点击左侧活动栏的扩展图标
搜索需要的扩展（如 Python、ESLint、Go 等）
点击安装

项目管理

工作区设置：默认工作区为 /home/coder/project
终端使用：使用内置终端执行命令和脚本
版本控制：集成 Git 支持，方便代码管理

🔌 基础配置与使用2

custom-code-server 用法与本地 VS Code 基本一致，新手可从 “创建项目、编写代码、编译运行” 入手：

1. 步骤 1：创建第一个 C 语言项目（示例）

左侧活动栏点击「资源管理器」→「打开文件夹」→ 选择 /home/coder/project（容器内项目目录，对应本地 ./project）；
右键点击 project 目录 →「新建文件」→ 命名为 test.c；
输入以下 C 语言代码：

运行

    #include <stdio.h>
    int main() {
        printf("Hello, custom-code-server!\n");
        return 0;
    }

2. 步骤 2：编译与运行代码

通过内置终端执行编译命令（与用户配置中的说明一致）：

# 进入项目目录（容器内路径，与本地 ./project 同步）
cd /home/coder/project

# 用 gcc 编译 test.c，生成可执行文件 test
gcc test.c -o test

# 运行可执行文件
./test

若终端输出 Hello, custom-code-server!，说明编译运行成功，开发环境正常。

3. 步骤 3：安装 VS Code 扩展（可选）

如需增强功能（如代码补全、格式化），可安装扩展：

1.左侧活动栏点击「扩展」（图标类似方块）； 2.搜索需要的扩展（如 Python、C/C++、Go、Java Extension Pack）； 3.点击「Install」安装，扩展会自动存储在 ./config/code-server 目录，容器重启后不丢失。

4. 步骤 4：修改 Web 登录密码（安全必需）

默认密码安全性低，建议登录后修改：

1.打开终端，执行以下命令（替换 新密码 为你的强密码）：

    # 修改 code-server 密码（容器内执行）
    code-server --auth password --password "新密码"

2.重启容器生效：

    # 服务器终端执行（非 VS Code 内置终端）
    cd /opt/custom-code-server && docker compose restart

🛠️ 维护与管理

日常维护操作

服务启动/停止 ```bash # 停止服务 docker compose down

# 启动服务 docker compose up -d ```

数据备份 bash # 备份项目代码和配置 tar -czf code-server-backup-$(date +%Y%m%d).tar.gz ./project ./config
服务更新 ```bash # 进入部署目录 cd /home/compose/code-server

# 重新构建镜像（如需要更新工具版本） docker build -t custom-code-server .

# 重启服务 docker compose down docker compose up -d ```

监控与日志

查看实时日志 bash docker compose logs -f
监控资源使用 bash docker stats vscode-web
检查存储空间 bash df -h # 检查磁盘空间 du -sh ./project # 查看项目目录大小

🐛 常见问题排查

1. 无法访问 Web 界面

问题现象：浏览器访问 http://IP:8083 无响应

解决方案： - 检查防火墙设置： bash # 开放 8083 端口 ufw allow 8083 - 验证容器状态：docker ps - 查看服务日志：docker compose logs

2. 密码认证失败

问题现象：无法使用配置的密码登录

解决方案： - 检查环境变量配置是否正确 - 验证密码是否包含特殊字符需要转义 - 查看容器内配置文件： bash docker exec vscode-web cat /home/coder/.config/code-server/config.yaml

3. 扩展安装失败

问题现象：VS Code 扩展无法安装

解决方案： - 检查网络连接 - 验证用户权限 - 查看扩展安装日志

4. 编译工具找不到

问题现象：终端中提示命令未找到

解决方案： - 验证 Dockerfile 构建是否成功 - 检查环境变量 PATH 设置 - 重新构建镜像并部署

5. 内存不足问题

问题现象：容器异常退出或性能下降

解决方案： - 增加内存限制：在 deploy.resources.limits.memory 中调整 - 监控内存使用情况 - 优化运行的应用和扩展

通过本教程，您应该已经成功部署并配置了功能完整的 Code-Server 开发环境。现在您可以在任何有浏览器的设备上访问这个强大的 Web IDE，享受一致的开发体验。如果在使用过程中遇到其他问题，可以参考 Code-Server 官方文档或相关社区资源。

🐛 常见问题排查2

1. Web 界面无法访问（ERR_CONNECTION_REFUSED）

原因 1：8083 端口未开放或被占用。解决：
1. 检查端口占用：sudo lsof -i :8083，若占用则停止对应服务；
2. 重新开放端口：sudo ufw allow 8083/tcp，云服务器同步安全组。
3. 原因 2：容器未正常启动（State 为 Exited）。解决：查看日志 docker compose logs custom-code-server，修复权限或端口冲突后重启。

2. 编译代码时提示 “权限不足”（Permission denied）

原因：项目目录权限不足，或代码文件为只读。

解决： 1. 服务器终端执行：sudo chmod -R 777 /opt/custom-code-server/project； 2. VS Code 内置终端执行：chmod +x test（给可执行文件添加执行权限）。

3. 扩展安装失败（提示 “Failed to install extension”）

原因 1：网络问题（无法访问 VS Code 扩展市场）。解决：在 VS Code 中配置扩展市场镜像（如阿里云镜像）：
1. 按 Ctrl+, 打开设置 → 搜索 Extension: Registry；
2. 将「Extension Registry URL」改为 https://marketplace.visualstudio.com/_apis/public/gallery（或阿里云镜像 https://vscode.aliyun.com/marketplace）。
3. 原因 2：扩展目录权限不足。解决：服务器终端执行：sudo chmod -R 777 /opt/custom-code-server/config/code-server。

4. 内存不足导致容器崩溃（日志提示 “Out of memory”）

原因：配置的内存限制过低，或项目编译占用内存过高。

解决： 1. 编辑 docker-compose.yml，提高内存限制（如服务器内存为 8G，设 memory: 6G）； 2. 关闭不必要的扩展（如 unused 的语言插件），减少内存占用； 3. 重启容器：docker compose restart。

通过以上步骤，新手可快速搭建 Web 版 VS Code 开发环境，实现多语言编码与调试。custom-code-server 尤其适合 “无本地开发环境”“多设备协同开发” 场景，如需深入功能（如远程调试、Git 集成），可参考官方 code-server 文档。