三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

离线环境下VSCode远程Python开发与Docker容器配置全攻略

发布时间：2026/8/15 4:28:53 三亩地 编程学习日记
离线环境下VSCode远程Python开发与Docker容器配置全攻略

1. 项目背景与核心挑战：为什么要在离线环境下折腾？

最近接手了一个新项目，开发环境被限制在一个完全离线的内网环境中，目标服务器是一台远程的Linux机器，而且最终的应用需要跑在Docker容器里。我的主力开发工具是VSCode，语言是Python。这听起来像是一个标准的现代开发流程，对吧？但“离线”和“远程”这两个词组合在一起，就让一切变得复杂了起来。

你可能会想，直接用VSCode的Remote-SSH插件连上去不就行了？或者在服务器上装个Docker，本地写代码然后构建镜像。这些在能联网的情况下确实是标准操作。但在离线环境里，每一个步骤都变成了需要精心策划的“物资运输”任务：你需要把VSCode的插件、Python的解释器、pip的包、Docker的基础镜像，所有这些依赖，像蚂蚁搬家一样，从有网的机器上提前下载好，再搬运到内网服务器上。

这个过程的本质，是在搭建一个可移植、可复现且高效的离线开发沙箱。它要解决几个核心痛点：第一，开发环境与最终部署环境（容器）的高度一致，避免“在我机器上能跑”的问题；第二，在无法访问互联网的情况下，依然能享受VSCode强大的智能提示、调试和代码管理功能；第三，整个环境配置过程本身需要可脚本化、可文档化，以便团队其他成员或未来在新服务器上能快速复现。

所以，这篇内容不是简单的命令罗列，而是一份完整的“作战方案”。我会详细拆解从零开始，在离线环境中，于远程Linux服务器上配置好VSCode远程Python开发环境，并进一步在容器内配置同样环境的具体步骤、背后的原理，以及我踩过的那些坑。目标是把一个看似棘手的限制，变成一套稳定可靠的日常工作流。

2. 战前准备：物资清单与本地中转站搭建

在真正登录远程服务器之前，我们需要在本地（一台可以访问互联网的机器）完成所有“物资”的准备工作。这一步至关重要，准备得越充分，后续在离线环境的操作就越顺畅。

2.1 核心物资清单

我们需要下载以下几类文件：

  1. VSCode Server 离线包：这是VSCode Remote-SSH、Remote-Containers等远程扩展在目标服务器上运行的后端服务。
  2. VSCode 插件离线安装包：主要是Python扩展（ms-python.python）、Pylance、Docker扩展等。
  3. Python 解释器安装包：目标服务器系统对应版本的Python二进制安装包（如.tar.xz格式）。
  4. Python 依赖包：项目所需的pip包及其所有依赖。
  5. Docker 安装包：针对目标Linux发行版的Docker CE二进制安装包。
  6. Docker 镜像：项目需要的基础镜像（如python:3.9-slim）。

2.2 本地下载与打包

2.2.1 下载 VSCode Server

VSCode Server 没有直接的官方下载链接，但我们可以通过一个“巧劲”获取。在本地机器上，打开终端，执行以下命令。这个命令会模拟VSCode客户端的请求，获取指定版本Server的下载链接并下载。

# 替换 `$COMMIT_ID` 为你本地VSCode版本对应的提交ID。 # 在VSCode桌面版中，通过 `帮助` -> `关于` 查看提交ID。 # 替换 `$PLATFORM` 为服务器架构，例如 `linux-x64` (对于x86_64系统) 或 `linux-arm64`。 COMMIT_ID="你的提交ID" PLATFORM="linux-x64" wget -O vscode-server-${COMMIT_ID}.tar.gz "https://update.code.visualstudio.com/commit:${COMMIT_ID}/server-${PLATFORM}/stable"

注意：务必确保下载的Server版本与你本地使用的VSCode版本兼容。版本不匹配会导致连接失败。最稳妥的方式是使用与团队约定或服务器未来长期维护版本一致的VSCode。

2.2.2 下载 VSCode 插件

VSCode 插件市场提供了直接的.vsix格式离线安装包下载。访问 Visual Studio Marketplace ，搜索你需要的插件，在详情页点击“Download Extension”即可获得.vsix文件。

核心插件列表建议：

  • ms-python.python(Python扩展)
  • ms-python.vscode-pylance(Pylance语言服务器)
  • ms-azuretools.vscode-docker(Docker扩展)
  • ms-vscode-remote.remote-ssh(如果你也通过SSH管理)
  • ms-vscode-remote.remote-containers(核心容器开发扩展)

2.2.3 下载 Python 和 Docker 安装包

  • Python: 前往 Python官方下载页面 ，下载对应版本的“Gzipped source tarball”。例如Python-3.9.13.tgz。对于生产环境，更推荐使用系统包管理器对应的预编译版本，但离线情况下源码编译是通用性最强的方案。如果知道服务器确切发行版（如Ubuntu 20.04），可以提前在有网环境下用apt download python3.9下载好deb包及其所有依赖。
  • Docker: 根据服务器发行版，参照 Docker官方文档 下载静态二进制包，或者下载对应发行版的离线安装包（如.deb、.rpm）及其所有依赖。

2.2.4 打包 Python 项目依赖

这是最容易出错的环节。在你的本地项目目录下，使用pip download命令将所有依赖包下载到本地，但不安装。

cd /path/to/your/local/project # 假设已有 requirements.txt pip download -r requirements.txt -d ./pip_packages --platform manylinux2014_x86_64 --python-version 39 --only-binary=:all:

参数解释：

  • -d ./pip_packages: 指定下载目录。
  • --platform manylinux2014_x86_64: 指定目标平台为Linux x86_64。这是关键，确保下载的是Linux兼容的二进制轮子（wheel），而不是源码包（sdist），避免在服务器上编译（可能缺少编译工具链）。
  • --python-version 39: 指定Python主次版本（3.9）。
  • --only-binary=:all:: 强制只下载二进制包，忽略源码包。

2.2.5 下载 Docker 基础镜像

在有网的机器上，使用docker pull拉取所需镜像，然后通过docker save导出为tar文件。

docker pull python:3.9-slim docker save -o python_3.9_slim.tar python:3.9-slim

2.2.6 最终打包

将以上所有下载好的文件，组织到一个清晰的目录结构中，然后打包。

mkdir offline_env_package cp vscode-server-*.tar.gz offline_env_package/ cp *.vsix offline_env_package/ cp Python-*.tgz offline_env_package/ cp docker-*.tgz offline_env_package/ # 或 docker-*.deb/rpm cp -r pip_packages offline_env_package/ cp python_3.9_slim.tar offline_env_package/ # 还可以包含一个 setup.sh 安装脚本 tar -czf offline_env_package.tar.gz offline_env_package/

现在，这个offline_env_package.tar.gz就是我们的“生存包”，将它通过U盘、内部文件服务器或其他允许的方式，传输到目标离线远程服务器。

3. 远程服务器攻坚战：基础环境与VSCode Server部署

登录到离线远程Linux服务器，我们将“生存包”解压，开始一步步构建环境。

3.1 解压与目录准备

# 假设包已上传到用户家目录 cd ~ tar -xzf offline_env_package.tar.gz cd offline_env_package

3.2 安装Python解释器

这里以编译安装Python源码为例，因为它通用性最强。如果你有对应发行版的离线包，使用dpkg -i或rpm -ivh安装会更简单。

# 安装编译依赖（如果你的服务器系统非常干净，这一步可能缺少很多包，需要提前在打包阶段也准备好这些系统依赖的离线包，这是另一个大坑） # 例如对于CentOS/RHEL系，需要 gcc, make, zlib-devel, openssl-devel, libffi-devel 等。 # 此处假设基本编译工具已存在。 tar -xzf Python-3.9.*.tgz cd Python-3.9.* ./configure --prefix=/usr/local/python39 --enable-optimizations make -j $(nproc) # 并行编译，加快速度 sudo make install

安装完成后，创建软链接或修改PATH，确保python3和pip3指向新版本。

sudo ln -sf /usr/local/python39/bin/python3.9 /usr/local/bin/python3 sudo ln -sf /usr/local/python39/bin/pip3.9 /usr/local/bin/pip3

3.3 安装Docker引擎

如果使用静态二进制包安装Docker：

sudo tar -xzf docker-*.tgz --strip-components=1 -C /usr/local/bin/

如果使用离线deb/rpm包安装，需要先安装所有依赖包，再安装Docker主包。这需要你提前在有网环境下用apt-rdepends或yum deplist理清依赖关系并全部下载，过程较为繁琐。静态二进制包是离线环境下最干净的选择。

启动Docker服务：

sudo groupadd docker 2>/dev/null || true sudo usermod -aG docker $USER sudo systemctl enable docker sudo systemctl start docker # 加载我们之前准备的基础镜像 sudo docker load -i python_3.9_slim.tar

3.4 部署VSCode Server并手动“激活”

这是最关键也最易出错的一步。VSCode Remote 扩展在连接远程主机时，会自动检查~/.vscode-server/bin/目录下是否存在与客户端版本匹配的Server。如果不存在，它会尝试从互联网下载。我们的目标就是提前把Server放进去，让它“以为”已经下载好了。

  1. 创建目录并解压：

    mkdir -p ~/.vscode-server/bin/ cd ~/.vscode-server/bin/ tar -xzf ~/offline_env_package/vscode-server-${COMMIT_ID}.tar.gz --strip-components=1

    解压后，目录名应该就是${COMMIT_ID}。你可以通过mv操作确保目录名正确。

    # 如果解压后目录名不对，进行重命名 mv $(ls -d */ | head -n 1) ${COMMIT_ID}/

  2. 手动运行安装脚本：解压后的目录里有一个bin子目录，里面通常有一个脚本（如code-server）。但为了让VSCode客户端完全识别，我们需要确保安装过程完成。一个可靠的方法是，在目录内创建一个“标记”文件，这个文件通常会在自动下载安装后生成。

    cd ${COMMIT_ID} # 创建一个空的标记文件，具体文件名可能因版本而异，常见的有 .obsolete 或一个版本号文件 # 更稳妥的方法是，查看一下解压出来的目录结构，有时运行 `./bin/code-server --version` 也会完成初始化 echo ${COMMIT_ID} > .version

  3. 安装VSCode插件：在服务器上，我们可以使用VSCode命令行工具来离线安装插件，但前提是Server已经“就绪”。一个更直接的方法是在本地VSCode安装插件时，选择“安装到SSH: [你的服务器]”。然而在完全离线环境下，我们可以通过命令行手动安装。 首先，确保VSCode Server的bin目录在PATH中，或者使用绝对路径。但更简单的方法是：在第一次通过Remote-SSH连接时，虽然Server已就位，但插件市场不可用。此时，我们可以在本地VSCode的扩展视图里，点击“...”选择“从VSIX安装”，然后选择我们上传到服务器的.vsix文件。这个操作会将插件安装到远程服务器的~/.vscode-server/extensions/目录下。

    手动安装的备选方案（如果图形界面操作不便）：

    # 在服务器上找到VSCode Server的命令行工具 ~/.vscode-server/bin/${COMMIT_ID}/bin/code-server --install-extension ~/offline_env_package/ms-python.python-*.vsix

    踩坑记录：手动安装插件时，务必注意插件依赖。例如ms-python.python可能依赖其他插件。最好按顺序安装，或者一次性安装所有上传的.vsix文件。如果安装失败，查看服务器上的~/.vscode-server/data/logs目录下的日志，是排查问题的关键。

4. 连接与配置：建立远程开发会话

完成上述步骤后，在本地可以联网的电脑上，使用VSCode，确保已安装Remote-SSH扩展。

  1. 配置SSH连接：编辑~/.ssh/config文件，添加你的服务器配置。
  2. 在VSCode的远程资源管理器中选择配置好的SSH主机进行连接。

第一次连接的成功关键：

  • 如果之前手动部署的VSCode Server版本完全匹配，连接会很快进入，并提示安装扩展。这时选择“从VSIX安装”来安装我们准备好的Python等扩展。
  • 如果连接失败，并提示“正在下载VSCode Server”，说明版本不匹配或手动部署的Server目录未被正确识别。需要立刻取消连接，然后去服务器上检查~/.vscode-server/bin/下的目录名和.version文件内容是否与客户端提交ID完全一致。不一致是导致此问题的主要原因。

连接成功后，你会看到VSCode左下角显示“SSH: [你的服务器]”。现在，打开服务器上的一个Python项目文件夹。

5. 容器内环境配置：在隔离沙箱中开发

远程环境直接配置好了，但我们最终目标是在容器里开发。VSCode的Remote-Containers扩展完美支持这一点。不过，在离线环境下，需要额外配置。

5.1 准备离线开发的Dev Container配置

在项目根目录下创建.devcontainer文件夹，并在其中创建devcontainer.json配置文件。这个文件定义了开发容器的属性。

{ "name": "Offline Python 3.9", "build": { "dockerfile": "Dockerfile", "context": "..", "args": { // 可以传递一些构建参数 } }, "settings": { "python.defaultInterpreterPath": "/usr/local/bin/python", "python.pythonPath": "/usr/local/bin/python" }, "extensions": [ "ms-python.python", "ms-python.vscode-pylance" ], "remoteUser": "vscode" // 通常容器内会创建一个vscode用户 }

关键点在于Dockerfile。我们需要编写一个能利用本地离线资源的Dockerfile。

5.2 编写离线友好的Dockerfile

# 使用我们已加载到本地的镜像 FROM python:3.9-slim # 避免在构建过程中尝试apt-get update（因为离线） RUN rm -f /etc/apt/sources.list.d/*.list # 将宿主机（即远程服务器）上准备好的pip包拷贝到镜像中 COPY ./pip_packages /tmp/pip_packages/ # 安装项目依赖（从本地目录） RUN pip install --no-index --find-links=/tmp/pip_packages -r /tmp/pip_packages/requirements.txt \ && rm -rf /tmp/pip_packages # 设置工作目录 WORKDIR /workspace # 创建非root用户（可选，但推荐） RUN useradd -m -s /bin/bash vscode && chown -R vscode:vscode /workspace USER vscode

这个Dockerfile的关键在于：

  1. FROM使用我们之前docker load进来的镜像。
  2. 禁用apt更新源，防止构建因网络超时失败。
  3. 通过COPY将宿主机上提前下载好的pip_packages目录复制到镜像内。
  4. 使用pip install --no-index --find-links从本地目录安装所有依赖，完全绕过PyPI。

5.3 在离线环境下重建容器镜像

由于修改了Dockerfile，并且构建上下文依赖于宿主机上的pip_packages目录，我们需要在服务器上执行构建。

# 在项目根目录（包含 .devcontainer 和 pip_packages 的目录） docker build -t my-python-app-dev -f .devcontainer/Dockerfile .

5.4 在VSCode中重新打开项目到容器

在VSCode中，确保已连接到远程SSH主机，并且打开了服务器上的项目文件夹。 然后，按下F1，输入“Reopen in Container”，选择“Reopen in Container”。VSCode会读取.devcontainer/devcontainer.json配置，并使用我们刚刚本地构建的my-python-app-dev镜像来创建和连接开发容器。

如果一切顺利，几秒钟后，你的VSCode就会在一个全新的、基于容器且包含了所有项目依赖的隔离环境中运行了。左下角会变成“Dev Container: Offline Python 3.9”。

6. 离线环境下的调试、测试与依赖管理进阶

环境搭好了，日常开发才是重头戏。离线环境下的工作流需要一些调整。

6.1 Python解释器与调试配置

在容器内，VSCode的Python扩展会自动发现解释器。你可以在命令面板（Ctrl+Shift+P）输入“Python: Select Interpreter”来选择容器内的Python路径（通常是/usr/local/bin/python）。

调试配置（launch.json）和在线环境没有区别，因为调试器（debugpy）已经作为依赖被pip install到容器环境里了。你可以正常设置断点、启动调试。

6.2 离线环境下如何管理新增依赖？

这是离线开发中最常见的后续需求。假设你需要给项目添加一个新包new-package。

  1. 在本地有网环境操作：

    # 在本地项目目录，更新requirements.txt或直接下载 pip download new-package -d ./pip_packages --platform manylinux2014_x86_64 --python-version 39 --only-binary=:all: # 更新 requirements.txt echo "new-package==x.x.x" >> requirements.txt

  2. 将新增的.whl文件和更新的requirements.txt传输到远程服务器。

  3. 在远程服务器上更新镜像：

    • 将新的.whl文件放入服务器的pip_packages目录。
    • 更新服务器上项目目录中的requirements.txt。
    • 重新构建Docker镜像（可以利用Docker层缓存，如果只是新增包，构建会很快）：
      docker build -t my-python-app-dev -f .devcontainer/Dockerfile .
    • 在VSCode中，使用“Rebuild Container”命令来应用新的镜像。

6.3 离线环境下的Git操作

Git本身不依赖网络即可进行本地提交、分支操作。但如果你需要与远程仓库同步，就需要在离线网络和在线网络之间搭建一个“桥接”。常见的做法是：在离线开发机上使用Git，将更改提交到本地仓库。然后，通过经过安全审核的介质（如内部Git服务器或特定传输流程）将本地仓库的变更推送/拉取到中心仓库。VSCode的源代码管理面板在离线环境下可以正常使用，用于暂存、提交和查看差异。

7. 避坑指南与实战心得

回顾整个配置过程，以下几个坑点值得特别关注：

  1. 版本一致性是生命线：VSCode Client、VSCode Server、Python扩展、Python解释器、pip包之间的版本兼容性必须严格保证。尤其是VSCode Server的提交ID，差一个字符都无法连接。最佳实践是，为整个团队冻结一套版本组合（例如VSCode 1.8x + Python扩展 2022.x + Python 3.9.x），并完整打包存档。

  2. 系统依赖的“隐形炸弹”：编译Python或安装某些Python包的二进制轮子（如psycopg2-binary,cryptography）可能需要特定的系统库（如libpq,libssl）。在离线服务器上，这些库可能缺失。因此，在准备阶段，最好在与目标服务器同版本、同架构的干净系统上进行一次模拟的pip download和pip install --target测试，确保所有底层依赖都能被满足。必要时，需要提前下载好这些系统库的离线安装包。

  3. Docker镜像的存储与版本管理：离线环境下，Docker镜像就是宝贵的黄金镜像。建议将docker save导出的.tar文件进行版本命名（如python-3.9-slim_base_v1.tar），并存储在版本控制或文件服务器中。.devcontainer.json和Dockerfile也应该纳入项目的版本控制，确保开发环境可复现。

  4. 离线插件市场的替代：除了手动安装.vsix，还可以搭建一个本地的VSCode插件市场服务，但这增加了复杂度。对于小团队，维护一个已知可用的.vsix文件仓库是更简单的方法。

  5. 性能考量：VSCode Remote 和 Dev Container 在离线局域网内通常性能很好。但如果服务器资源紧张，容器的启动和VSCode扩展的加载可能会变慢。确保服务器有足够的内存和CPU资源。对于资源极度受限的情况，或许直接使用远程SSH开发（不通过容器）是更轻量的选择。

配置这样一个离线远程容器开发环境，初看步骤繁多，但一旦搭建完成，它带来的收益是巨大的：绝对一致的环境、隔离的沙箱、以及完整的IDE体验。整个过程实际上是将“在线环境的便利性”通过“离线环境的准备工作”进行了前置。对于需要在内网、保密环境或网络不稳定地区进行开发的团队来说，这套方法论是提升效率和减少环境问题的有效武器。最关键的是，所有步骤都可以脚本化，让新成员入职或新服务器部署变得有章可循。

编程学习 学习日记 实战经验
← 返回列表