PyArmor混淆代码部署Docker/K8s报__pyarmor__未定义错误如何解决

错误具体成因 #

__pyarmor__是PyArmor初始化运行环境时注入的内置标识，抛出该错误的本质是混淆代码运行前PyArmor引导流程未执行成功，对应你排查的4种场景触发逻辑如下：

• 主进程入口导入混淆模块前未执行引导代码：混淆后的代码依赖pytransform模块预先初始化运行环境，未执行引导直接导入混淆代码就会触发报错
• 子进程未单独加载引导：subprocess、multiprocessing创建的子进程是独立Python运行环境，不会继承主进程的PyArmor初始化状态，子进程内导入混淆代码前必须重新执行引导
• pytransform相关脚本被混淆：pytransform.py或pytransform包的__init__.py是引导代码的载体，本身如果被混淆会无法完成初始化，导致无法注入__pyarmor__标识
• 系统核心模块被误混淆：os、ctypes等Python内置系统模块是PyArmor引导代码的依赖，如果被误混淆会导致引导流程中断，无法完成环境初始化

Python包正确混淆操作步骤 #

1. 混淆前先确定需要排除的文件/目录，必须排除的内容包括：
   • PyArmor自带的pytransform相关文件
   • Python标准库路径（一般为虚拟环境的lib/pythonx.x/目录或者系统级Python库目录）
   • 所有主进程、子进程的入口脚本文件（需要在这些文件头部手动加引导代码）
2. 执行混淆命令，示例如下：

# --exclude指定需排除的路径，--output指定混淆后代码输出目录
pyarmor obfuscate --exclude pytransform --exclude /usr/local/lib/python3.10 --output ./obfuscated_output <your_package_name>

3. 混淆完成后校验：
   • 检查pytransform相关文件是否为明文
   • 检查排除的系统模块、进程入口文件是否为明文
   • 在所有入口脚本（包括主进程、子进程入口）的最开头加入引导代码：

from pytransform import pyarmor_runtime
pyarmor_runtime()

Docker/K8s部署正确操作方法 #

Docker镜像构建注意事项 #

• 基础镜像必须和本地混淆代码时使用的Python版本、操作系统架构完全一致，PyArmor的引导代码依赖对应平台的原生动态库，跨架构/跨版本会导致引导失败
• 构建镜像时需要将混淆后的所有代码（包括明文的pytransform相关文件、对应平台的动态库文件）完整复制到镜像工作目录，不要遗漏pytransform目录下的.so/.dll/.dylib动态库文件
• Dockerfile示例：

# 使用和本地混淆环境完全一致的Python基础镜像
FROM python:3.10-slim-bookworm
WORKDIR /app
# 复制混淆后的所有文件，包括pytransform相关内容
COPY ./obfuscated_output /app
# 安装业务依赖，注意不要覆盖pytransform相关文件
RUN pip install -r requirements.txt
# 启动命令直接运行已添加引导代码的入口脚本
CMD ["python", "main.py"]

K8s部署注意事项 #

• 确认集群节点的操作系统架构和镜像构建环境一致，避免出现x86架构构建的镜像部署到ARM节点的情况
• 不要启用会篡改Python运行环境的Sidecar注入，比如部分APM探针会修改Python模块导入逻辑，会导致PyArmor引导失败
• 如果用多进程部署（比如Gunicorn启动多个worker进程），需要在Gunicorn的配置文件头部加入PyArmor引导代码，确保每个worker进程启动时都先执行引导

内容的提问来源于stack exchange，提问作者shyam sundar