银河麒麟V10离线环境下的Python项目迁移：从Windows依赖到ARM架构适配

1. 项目迁移背景与挑战最近接手了一个从Windows环境迁移到银河麒麟V10系统的Python项目整个过程踩了不少坑。这个项目原本在Windows上跑得好好的但客户要求必须部署到国产化平台的离线环境中而且还是ARM架构aarch64。刚开始觉得不就是换个环境运行嘛结果实际操作起来才发现远没有想象中简单。最大的挑战来自三个方面首先是系统架构差异Windows用的x86架构而银河麒麟是ARM架构很多二进制包完全不兼容其次是离线环境没法直接pip安装所有依赖都得提前准备好最后是银河麒麟V10自带的Python环境比较干净连pip都没有更别说virtualenv这些工具了。我记得第一次尝试直接拷贝Windows的虚拟环境过去结果一堆报错这才意识到需要从头开始规划迁移方案。2. 基础环境准备2.1 获取离线安装包在联网机器上我首先下载了pip的源码包。这里有个小技巧一定要选择.tar.gz格式的源码包而不是.whl文件因为源码包兼容性更好。我用的pip-22.0.1.tar.gz这个版本比较稳定。下载地址直接在PyPI官网搜索pip就能找到。setuptools是pip的依赖所以也得提前准备好。我下载的是setuptools-60.2.0.tar.gz这个版本和pip-22.0.1配合得很好。两个包下载好后用U盘拷贝到银河麒麟系统中我习惯放在/home/mypackage目录下方便管理。2.2 安装pip和setuptools安装顺序很重要必须先装setuptools再装pip。解压setuptools包后进入目录执行cd /home/mypackage/setuptools-60.2.0 python3 setup.py install等setuptools安装完成后同样的方法安装pipcd /home/mypackage/pip-22.0.1 python3 setup.py install安装完成后验证一下是否成功pip3 --version如果看到版本号输出说明基础工具链已经准备好了。3. 虚拟环境搭建3.1 安装virtualenv及其依赖在离线环境下安装virtualenv有点麻烦因为它有多个依赖包。我整理了一份完整的依赖清单zipp-3.6.0-py3-none-any.whltyping_extensions-4.3.0-py3-none-any.whlimportlib_metadata-4.11.3-py3-none-any.whldistlib-0.3.4-py2.py3-none-any.whlplatformdirs-2.5.1-py3-none-any.whlfilelock-3.6.0-py3-none-any.whlvirtualenv-20.14.1-py2.py3-none-any.whl这些whl文件都需要提前下载好而且安装顺序不能乱。我试过跳过前面的依赖直接装virtualenv结果各种报错。正确的安装命令应该是pip3 install zipp-3.6.0-py3-none-any.whl pip3 install typing_extensions-4.3.0-py3-none-any.whl # ...其他依赖同理 pip3 install virtualenv-20.14.1-py2.py3-none-any.whl3.2 创建隔离环境依赖装好后就可以创建项目专用的虚拟环境了。我习惯把虚拟环境放在/home/pyprojects目录下virtualenv --pythonpython3 /home/pyprojects/aiproject创建完成后激活环境source /home/pyprojects/aiproject/bin/activate这时候命令行提示符前面会出现(aiproject)的标识说明已经在虚拟环境里了。4. 项目依赖迁移4.1 导出Windows环境依赖在原来的Windows开发环境中用PyCharm的终端执行pip freeze requirements.txt这会把所有已安装的包及其版本号导出到requirements.txt文件。但要注意这个文件里的包有些是Windows专用的不能直接在银河麒麟上用。4.2 获取ARM架构兼容包接下来是关键步骤获取ARM架构的兼容包。在联网的Linux机器上最好是ARM架构的创建一个临时目录然后执行pip wheel --wheel-dir/tmp/wheelhouse -r requirements.txt这样会把所有依赖包编译成whl文件。但有些包可能需要额外处理比如numpy、pandas这些包含C扩展的包必须下载预编译的ARM版本。我常用的源有官方PyPI的ARM兼容包第三方提供的ARM架构whl文件有时甚至需要从源码编译4.3 替换不兼容包把生成的whl文件拷贝到银河麒麟系统的/home/requirement目录。这时候要仔细检查每个包特别是那些带win、win32、win_amd64字样的必须找到对应的linux_aarch64版本替换掉。5. 项目部署与验证5.1 安装项目依赖在银河麒麟的虚拟环境中执行pip install --no-index --find-links/home/requirement -r requirements.txt这个命令会从本地目录安装所有依赖不会尝试联网下载。如果一切顺利所有依赖都应该正确安装。但实际情况是总会遇到几个包装不上。这时候就需要手动处理检查是否有对应的ARM版本尝试从源码编译安装寻找功能类似的替代包5.2 代码适配与测试依赖问题解决后就是代码本身的适配了。银河麒麟V10自带的Python是3.7版本和Windows下的高版本可能有些语法差异。常见问题包括f-string的用法差异类型注解的兼容性系统路径的处理方式不同建议先用pylint检查一遍代码修复所有语法警告。然后重点测试涉及系统调用的部分比如文件操作、进程管理等。6. 常见问题解决6.1 依赖冲突处理在离线环境下依赖冲突特别让人头疼。我遇到过一个典型情况包A需要numpy1.20而包B需要numpy1.20。解决方案是找到两个包都能接受的numpy版本范围如果实在找不到交集考虑升级或降级其中一个包极端情况下可能需要修改包代码6.2 性能优化建议ARM架构下的Python性能调优有些特殊技巧使用--enable-optimizations编译Python针对NEON指令集优化关键代码考虑使用Cython重写性能瓶颈6.3 部署后的维护离线环境下的维护比较麻烦我的经验是建立完整的依赖树文档保留所有下载的whl文件定期检查安全更新考虑搭建本地PyPI镜像整个迁移过程虽然复杂但完成后对Python跨平台兼容性的理解会深刻很多。记得第一次看到项目在银河麒麟上跑起来时那种成就感真的难以形容。现在回头看最大的经验就是耐心检查每个环节做好详细记录遇到问题多查ARM架构相关的解决方案。