内网服务器要跑一个 Python 项目联网的开发机上conda create一路绿灯拷到机房那台机器上conda install直接甩你一脸PackagesNotFoundError。这不是运气问题是 Conda 环境离线部署这件事本身有几个容易被忽略的前提。我在过去几年里给不同规模的团队做过不少次这类环境搬迁从单台机器的临时救火到几十台机器的批量落地踩过的坑基本能覆盖三种主流方案各自的边界。这篇就把这三种企业级无网络环境下的 Conda 环境部署方案拆开讲环境快照搬迁conda-pack、内网自建本地 channel、pkgs 缓存预热加--offline每一种我会说清楚它解决什么问题、不适合什么场景、完整命令链路长什么样、以及我在实际操作中被卡住过的具体位置。适合手里有离线机器、又不想把整个 Python 生态重造一遍的开发和运维同学基础薄一点也没关系命令我都给全。1. 离线部署真正的难点不在装在解析很多人第一次做 Conda 环境离线部署思路很朴素把包装上不就行了。结果一上手就发现卡住的地方跟想象完全不一样。联网环境下 Conda 干活是两步——先根据 channel 里的repodata.json把依赖关系解出来再按解出来的清单去下载安装包。离线之后断掉的不是第二步的下载而是第一步的依赖解析。你没看错绝大多数离线失败的第一现场是找不到包而不是下载超时。1.1 联网能装不等于离线能跑路径绑定与动态链接Conda 环境的目录里到处埋着绝对路径。解释器的 shebang、bin/下脚本的头部、site-packages里某些包的.pth文件、编译期写入的RPATH全都是打包那一刻所在机器的路径。你直接tar一个环境目录拷到另一台机器解压后路径变了python可能还起得来但一堆脚本会报bad interpreter: No such file or directory。这就是为什么单纯的复制文件夹在企业环境里经常翻车。更隐蔽的是动态链接库的问题Python 解释器和一堆科学计算包依赖libstdc、libgfortran、libz这些库Conda 环境里自带了一份。如果目标机器是更老的发行版它的系统glibc版本低于打包机上 Conda 自带的那份所要求的版本你会看到类似version GLIBC_2.28 not found的报错。这个错误跟 Conda 本身没关系是二进制兼容性的硬约束任何方案都绕不过去只能靠打包机和目标机的操作系统大版本尽量接近来规避。1.2 repodata 才是离线后第一个断掉的东西conda install numpy在你眼里是一条命令在 Conda 眼里是一串动作读取每个 channel 的repodata.json把成千上万个包的元信息和依赖关系加载成一个索引跑 SAT 求解器算出安装方案然后按方案取包。离线机器上repodata.json根本没有Conda 连解都解不出来报错就是PackagesNotFoundError。理解了这一点三种方案的分野就清楚了conda-pack跳过解析和安装直接把已经解算好、已经装好的成品环境整体搬过去目标机不需要任何包管理动作。本地 channel把联网机上的repodata.json和对应的包文件一起搬到内网让离线机也能重新做一次完整的解析和安装本质是重建一个微型源站。pkgs 缓存预热把解算结果和包文件都放进 Conda 的本地缓存目录用--offline强制它在缓存里找属于半成品再利用。1.3 三种方案的适用边界先摆清楚选型之前先把边界画出来比后面撞墙再回头改要省事得多。下面这张表是我自己在做方案评估时最常用的对照你可以直接拿去和团队对齐预期。维度conda-pack 环境快照本地 channelpkgs 缓存预热目标机是否需要 Conda不需要解包即可用需要需要是否支持目标机重新解析依赖不支持支持有限支持环境体积偏大含冗余文件可控只存用到的包中等缓存会累积多环境复用差一个环境一份包好一个源服务所有机器一般跨操作系统基本不行可行分 subdir 存放基本不行增量更新难度高需重新打包低补包重新索引即可中需补下载最适合的场景单机/少量机器快速交付内网多机、长期维护临时救急、包量小的场景看清楚这张表你会发现三者不是替代关系而是覆盖不同规模。一台机器conda-pack 十分钟搞定三十台机器要长期维护本地 channel 才是正解手上只有几个包、临时要跑个脚本缓存预热最省事。下面逐个拆。2. 方案一conda-pack 整包搬迁最省心的成品搬运conda-pack 的思路非常直接把一个已经装好的 Conda 环境打成压缩包包里带有修正路径的脚本目标机解压后跑一次修正脚本就能用。它的最大价值是目标机器完全不需要 Conda也不需要网络甚至不需要 Python 环境管理器——只要解压和运行。2.1 打包之前必须先把环境洗干净这一步十个人里有八个会跳过然后卡在打包报错上。conda-pack 在打包时会检查环境里是否存在指向环境目录之外的文件链接如果发现就报Files managed by conda were found to have been deleted/overwritten。最常见的原因是环境里装了以开发模式editable install安装的包或者有人手动pip install了一个指向本地源码目录的包。我习惯在打包前跑一遍体检# 查看环境里是否有 editable 安装 conda list -n myenv | grep -i editable\|develop # 查看包的安装来源确认没有奇怪的本地路径 conda list -n myenv --show-channel-urls如果确实有 editable 包先pip uninstall掉把它挪到目标机上再单独装或者干脆改成正常安装。另一个常被忽略的点是环境要尽量干净别把一堆临时实验的包留在里面——conda-pack 是整包复制多一个包就多一份体积在只能靠移动硬盘拷贝的环境里体积就是时间。2.2 打包与解包的完整命令链路工具本身要先在联网机上装好。我一般不用全局装而是建一个专用的小环境避免污染业务环境# 联网机准备打包工具 conda create -n packer python3.10 -y conda activate packer pip install conda-pack # 打包指定环境名和输出文件 conda pack -n myenv -o /data/myenv.tar.gz --n-threads 4--n-threads是我后来养成习惯必加的参数。默认单线程压缩一个几个 GB 的环境能压十几分钟开四到八个线程能省一半以上时间。压出来的包直接拷到目标机# 离线机解包到指定目录 mkdir -p /opt/envs/myenv tar -xzf myenv.tar.gz -C /opt/envs/myenv # 激活并修正路径 source /opt/envs/myenv/bin/activate conda-unpackconda-unpack这一步是整包搬迁的灵魂绝对不能漏。它做的事是把环境里所有记录的旧前缀路径替换成当前实际路径包括脚本 shebang、.pth文件、二进制文件里的字符串常量。跑完之后可以用conda-unpack --check验证一下有没有残留输出为空就说明干净了。2.3 conda-unpack 只能跑一次这个坑我踩过conda-unpack有个特性它执行时会修改环境内部的一批文件包括自己的元数据。所以它只能执行一次。我第一次用的时候图省事解压后跑了一次觉得不放心又跑了一次第二次直接报错环境也没坏但那个报错信息很容易让人误以为环境有问题白白排查半小时。更麻烦的场景是环境目录被移动。比如你解压到/opt/envs/myenv跑完conda-unpack后来觉得目录名不合适mv成了/opt/envs/prod-env这时候环境就废了一半——路径记录里还是老路径而conda-unpack的有效状态已经用掉了没法再修正。正确的做法是要么一开始就定好目录要么重新解压一份再改目录。2.4 跨平台和跨 glibc 的硬边界conda-pack 的坑集中在平台兼容上这里必须说清楚不然容易在交付前一夜翻车。不能跨操作系统Linux 上打出来的包不能直接在 Windows 或 macOS 上用反过来也不行。二进制格式、路径分隔符、动态库后缀全都对不上。可以跨同架构的不同机器同是 x86_64 Linux内核版本的差异通常不影响。glibc 版本只能老打新用不能新打老用打包机的glibc版本要小于等于目标机的版本。反过来会报version GLIBC_2.xx not found。所以如果知道目标机是比较老的系统打包时就应该选一台同等或更老系统的机器来做别在最新的开发机上一顿操作。我个人的经验是面对一批不确定系统版本的离线机器先抽一台跑ldd --version看一下glibc然后专门准备一台老系统打包机作为标准打包环境。这件事前期花半小时后期能省掉一堆返工。3. 方案二自建本地 channel把内网改造成小型源站如果离线机器不止一台或者需要长期在内网维护环境conda-pack 就不合适了——每台机器一份包体积浪费严重加个包还要重新打。这时候要做的是在内网搭一个本地 channel让所有离线机指向它用起来跟公网源一样。3.1 为什么不直接拷 pkgs 目录非要走 conda indexConda 找包靠的是repodata.json这个索引文件里面记录了当前目录下所有包的名称、版本、构建号、依赖约束和文件校验和。你只把.conda或.tar.bz2文件拷过去没有索引Conda 等于看着一屋子书但没有目录卡扫不出来。conda index就是生成这个目录卡的工具。它扫描指定目录下的所有包文件解析每个包的元数据生成repodata.json和对应的.bz2压缩版。生成的索引会被 Conda 缓存后续解析直接读它。# 典型目录结构subdir 分层是必须的 /data/local-channel/ ├── linux-64/ │ ├── numpy-1.24.3-py310h...conda │ ├── numpy-1.24.3-py310h...tar.bz2 │ └── repodata.json ├── noarch/ │ ├── python-dateutil-2.8.2-pyhd...conda │ └── repodata.json └── win-64/ └── ... # 生成索引针对每个 subdir 单独跑 conda index /data/local-channel/linux-64 conda index /data/local-channel/noarchnoarch目录千万别忘。纯 Python 的包很多工具库都是放在noarch如果你的环境依赖里有纯 Python 包却没索引它解析阶段会直接失败报错还特别隐晦。3.2 从联网机下载依赖闭包的两种姿势问题来了怎么知道要下载哪些包有两种做法我会根据场景选。第一种是用目标环境的显式清单去下。联网机上先建一个临时环境装完需要的包后导出清单# 联网机构建参考环境并导出精确清单 conda create -n ref python3.9 numpy pandas scikit-learn -y conda list -n ref --explicit /tmp/ref-explicit.txt # 按清单批量下载--download-only 只下不装 conda create -n dl --download-only --file /tmp/ref-explicit.txt -y--explicit导出的清单是带完整 URL 和校验和的里面每一行就是一个确切版本的包。这种方式的可靠性最高因为版本已经锁死了不会出现联网机今天解析出来的版本和目标机明天解析出来的不一样。第二种是用名称约束让 Conda 自己解# 联网机只下载不安装包会落到 pkgs 目录 conda create -n dl2 --download-only -c conda-forge python3.9 numpy1.24 pandas -y这种方式的好处是省事坏处是版本可能漂移而且包会落在 Conda 的 pkgs 缓存目录里需要自己去翻。我一般只在临时实验的时候用它正式交付还是用--explicit。下载完成后把 pkgs 目录里的包文件按 subdir 分类拷到本地 channel 对应目录下。这里有个细节Conda 的 pkgs 缓存里同时存在.conda和.tar.bz2两种格式的同一个包你只需要留.conda新格式体积更小、解压更快删掉.tar.bz2能省不少空间。3.3 起一个静态文件服务配置 .condarc索引生成好之后最省事的发布方式是起一个静态 HTTP 服务。不需要什么复杂的服务端Python 自带的就够cd /data/local-channel nohup python -m http.server 8000 --bind 0.0.0.0 /var/log/channel.log 21 然后在离线机的.condarc里把这个地址加进去channels: - http://10.0.0.5:8000 - defaults channel_priority: strict show_channel_urls: truechannel_priority: strict值得单独说一句。默认的松散优先级下Conda 可能会为了满足某个依赖从后面的defaults去拿包而离线机上defaults根本不通结果就是一边解析一边卡住。设成strict之后它只在第一个 channel 里找行为可预测。不带网络服务也行直接挂本地目录channels: - file:///data/local-channel适合那种内网机器少、又不想额外跑服务的场景。缺点是共享不方便每台机器都得同步一份目录。3.4 优先级和缓存这两个雷区第一个雷是defaults放在最后一个 channel 位置。前面说过离线机连不上它只要解析走偏到那里就会长时间挂起直到超时看起来像卡死。我一般的做法是离线机上把defaults整个删掉只留内网源。第二个雷是 channel 缓存没刷新。conda index更新了repodata.json但客户端本地有pkgs/cache/下的旧副本会继续用旧索引导致明明刚放了包却找不到。清理方法conda clean -i # 只清索引缓存不动包 conda search numpy --override-channels -c http://10.0.0.5:8000排查时用--override-channels强制只查这一个源能看到包就说明索引和服务都没问题问题在客户端配置看不到就是服务端那边索引没生成好。4. 方案三pkgs 缓存预热 --offline最轻量的应急打法手上只有一台离线机需要的包也不多搭 channel 属于杀鸡用牛刀。这时候最轻的做法是把 Conda 自己的包缓存喂饱然后强制它离线工作。4.1 用 --download-only 把缓存和索引一起做出来关键在于理解--offline的机制它禁止 Conda 访问任何网络所有包和索引都从pkgs_dirs指向的本地目录里找。所以你不仅要放包文件还得把repodata.json的缓存也带过去。联网机上这么做# 联网机完整下载依赖闭包包会落在 pkgs_dirs 里 conda create -n tmp-dl --download-only python3.9 numpy pandas matplotlib -y # 找到缓存目录 conda info | grep pkgs directories假设输出是/home/user/miniconda3/pkgs这个目录里会有三样东西解压后的包目录、.conda/.tar.bz2原始文件、以及cache/子目录里的repodata.json缓存副本。三样都要拷缺一不可。拷贝到离线机后改离线机的.condarcpkgs_dirs: - /data/conda_pkgs offline: truepkgs_dirs放在pkgs默认位置也行但企业环境里系统盘往往不大我习惯单独挂一块数据盘专门放缓存顺便方便备份。4.2 离线机上执行安装的正确姿势配置好了之后安装命令加上--offlineconda create -n myenv python3.9 numpy pandas matplotlib --offline -y这里有个非常关键的经验版本约束写得越死成功率越高。--offline模式下 Conda 只能在自己的缓存里解算如果约束写成numpy它会去找缓存里最新的能满足依赖的版本但如果你的依赖链里有另一个包要求numpy1.23而缓存里恰好没有满足的组合解析就会失败。写成numpy1.24.3反而稳因为冲突空间被压缩了。4.3 --offline 报错的三条排查链路--offline失败基本集中在三种报错上我按出现频率排个序你可以照着链路查。第一条链路PackagesNotFoundError: The following packages are not available from current channels一路查下来是这样的顺序先用conda list确认包是不是真的在缓存里再用ls /data/conda_pkgs | grep 包名看文件名注意版本和构建号最后用conda search 包名 --offline看 Conda 能不能从本地索引里识别到它。如果ls看得到但conda search看不到那就是cache/里的索引缓存没拷过来或者过期了。第二条链路索引存在但解析失败报UnsatisfiableError这种不是缺包是版本组合无解。排查方法是先用--dry-run跑一遍看它推荐什么conda create -n test python3.9 numpy pandas --offline -y --dry-run输出的求解结果会告诉你它打算装哪些版本对照一下缓存里的版本就能看出是哪个包的约束卡住了。实在解不出来就把约束放宽一个层级比如python3.9改成python3.9.18。第三条链路报CondaHTTPError或者长时间卡住这说明offline: true没生效Conda 还在尝试访问网络。检查.condarc的offline字段是不是写在了正确的层级以及命令行上是不是漏了--offline。企业环境里如果HOME被设置成了别的位置.condarc可能根本没被读到用conda config --show-sources确认一下实际生效的配置文件路径。4.4 换成 micromamba 会有额外收益如果你的离线机器资源紧张或者环境很老micromamba是个值得考虑的替代。它是一个静态编译的单文件可执行程序不依赖 Python 环境就能跑体积只有几 MB离线分发的时候特别友好。它对离线的支持也做得更彻底--offline之外的很多行为可以直接通过环境变量控制。用法上跟 conda 命令基本兼容包缓存目录的机制也类似把同一份 pkgs 目录喂给它就能直接工作。我在做一些嵌入式或者容器内的最小化场景时会优先选它省掉装一整个 Conda 发行版的磁盘开销。5. 三种方案怎么选一张决策表和几条实战判断讲完三种方案回到选型。这张表是我实际交付时用的决策依据你可以直接对照自己的场景。判断条件推荐方案理由离线机 ≤ 3 台一次性交付conda-pack半小时能搞定不用搭服务离线机 ≥ 10 台需要长期用本地 channel一份源站服务所有机器目标机不允许装 Condaconda-pack解压即用零依赖需要频繁加包、改版本本地 channel补包重新索引增量成本低只是临时跑个脚本pkgs 预热配置最少一条命令目标机系统较老glibc 低本地 channel让 Conda 在目标机上自己解算避免二进制不兼容有 Windows 和 Linux 混合环境本地 channel分 subdir 管理一套服务两端用有几条判断是我吃过亏之后才认可的写在这里供参考。第一条能不跨平台就不跨平台。我见过为了省事想在一台 Linux 上打好的包直接给 Windows 机器用的方案折腾两天最后放弃。真遇到混合环境老老实实分 subdir 维护两个 channel。第二条打包机的系统版本要向下兼容。面对一批不确定版本的离线机选一台系统版本最老的机器做打包机成功率最高。这件事的收益会随着机器数量线性放大。第三条体积不是小事。一个完整的科学计算环境打包后常常有 1.5 GB 到 3 GB。在只能靠移动介质搬运的场景里这个体积直接决定了你要跑几趟。用--n-threads压缩、删掉重复的.tar.bz2、清理环境里用不到的包这些操作能省掉三成以上的体积。第四条把清单锁起来。无论用哪种方案我都会导出一份environment.yml和一份--explicit清单一起归档。前者的可读性好方便人看后者的可复现性好方便机器装。这份东西在半年后环境出问题、需要重建的时候价值极高。
