FastAPI 项目使用 PyArmor 外置许可证混淆与授权

lyj

发布 2025-07-29

120

分享

> Python 3.13.5 > Pyarmor 9.1.8 (trial) ## 一、背景与目标 在向多家企业交付 FastAPI 服务时，我们既要**保护源码**避免泄露，又要**灵活控制授权**（机器绑定 + 到期）。PyArmor 8.5+ 的 **外置许可证（Runtime Key）** 机制可以让我们 **一次混淆代码、多次下发钥匙**，极大降低维护成本。 > **核心思路：** > - **代码包**：一次 `pyarmor gen --outer` 生成，所有客户通用。 > - **授权钥匙**：每台服务器独立生成 `.mcp.lic`（或默认 `pyarmor.rkey`），绑定硬件指纹并设置有效期。 > - **升级 / 续费**：替换钥匙即可，无需重新打包。 --- ## 二、PyArmor 运行原理快速回顾 1. `pyarmor gen` 将每个 `.py` 文件替换为 **加密块 + 引导 stub** 并复制运行时包 `pyarmor_runtime_000000/`。 2. 应用入口先导入 `pyarmor_runtime`，它会 - 读取同目录的外置钥匙文件； - 校验 **Machine ID、到期日、并发数**； - 调用 `pytransform.so` 解密字节码生成 `code object` 并交给 CPython 执行。 3. **Machine ID** 由 PyArmor 通过网卡 MAC、硬盘 SN 等信息自行哈希生成，与系统 `/etc/machine-id` 无关。 4. `-e <天数|日期>` 只精确到「天」；分钟级测试需用外置 Key + 自定义插件实现。 --- ## 三、实操步骤（假设项目顶层包名 app/） ### 1. 环境准备 ```bash python -m venv .venv && source .venv/bin/activate pip install -U pyarmor==9.1.8 # Trial 版即可 pip install -r requirements.txt # FastAPI 等依赖 ``` ### 2. 获取 PyArmor Machine ID ```bash python -m pyarmor.cli.hdinfo # 输出示例：Machine ID: 'm863ce555e8152dd2886df2604e733911' MID="m863ce555e8152dd2886df2604e733911" ``` `python -m pyarmor.cli.hdinfo` 打印的 Machine ID（以 m 开头的 33 位字符串）是 PyArmor 自己计算 的硬件指纹；它不是 Linux 的 `/etc/machine-id` 文件。PyArmor 生成或校验许可证时，只认它计算出的 Machine ID，不读取 `/etc/machine-id`。 **PyArmor 的 Machine ID 从哪来** | 组成字段 | 说明 | | ------------ | ------------ | | 默认 MAC 地址 | hdinfo 会取 第一块网卡 的 MAC，再做 MD5 并加前缀 m | | 硬盘序列号 | 若能读取到固定 SN，会一并参与哈希 | | 主机域名 | localdomain 等信息也可能混入 | | 其它补充 | 如果 MAC/SN 拿不到，PyArmor 会退化到随机字符串导致每次重启都变 ID（常见于 WSL、云主机） | ### 3. 一次混淆代码（外置许可证） ```bash pyarmor gen -r -O build/linux_x64 --outer app ``` - `-r` 递归混淆子包 - `--outer` 让运行时在启动时再加载外置钥匙 ### 4. 生成 180天有效 的授权钥匙 ```bash EXP=$(date -d '+180 days' '+%Y-%m-%d') # 动态计算明天 pyarmor gen key -b "$MID" -e "$EXP" --period 30s -O build/linux_x64/pyarmor_runtime_*/ ``` 生成文件 `build/linux_x64/pyarmor_runtime_000000/pyarmor.rkey` （若已用 `pyarmor cfg outer_keyname=".mcp.lic"` 改名，这里会输出 `.mcp.lic`。） `--period N` 用来给 外置 Key 或内置许可证 加一个 “心跳”： 脚本每 N 个单位（默认 1 小时）自动重新检查授权文件。 - 没设置 --period ⇒ 只在「启动瞬间」做一次校验，之后即使到期、换机器进程也继续跑； - 设置了 --period 60s（或 1m、1h 等）⇒ 运行时会按照设定的周期重新加载 Key，一旦发现到期或指纹不符就抛 PyarmorError 并 立即退出。 | 形式 | 等价 | 说明 | | ------------ | ------------ | ------------ | | --period 1 | --period 1h | 默认单位是 小时 | | --period 60m | --period 1h | 60 分钟 | | --period 3600s | --period 1h | 3 600 秒 | | --period 30s | -- | 半分钟，用于快速测试 | 支持三个单位：s（秒）、m（分钟）、h（小时）。填纯数字就是小时。 ### 5. 启动验证 ```bash cd build/linux_x64 uvicorn app.app:create_app ``` 到期或指纹不符时会抛出 `PyarmorError` 并退出。 --- ## 四、多客户交付流程 | 场景 | 动作 | |------|------| | 新客户部署 | 复制通用 **代码包** + 针对其机器的 `.mcp.lic` | | 续费或延长试用 | 重新 `pyarmor gen key -b <MID> -e <新日期>` 覆盖旧钥匙 | | 跨平台 (Win/macOS/ARM) | 用 `pyarmor gen --platform <target>` 分别打包各平台 | --- ## 五、常见问题与排错 | 症状 | 原因 | 解决 | |------|------|------| | `not this machine` | 用错指纹生成钥匙 | 必须使用 `hdinfo` 打印的 Machine ID | | 每次重启 ID 都变 | 云主机网卡 MAC 不固定 | 绑定自定义 `--bind-mdata` 或固定 MAC | | `missing license key` | 运行时找不到外置钥匙文件 | 确认文件名与 `outer_keyname` 配置一致 | | 跨平台启动失败 | `.so` 架构不匹配 | 重新 `gen --platform` 打包 | --- ## 六、附录：修改钥匙文件名 ```bash pyarmor cfg outer_keyname=".mcp.lic" ``` - 影响 **后续生成** 的运行时代码与钥匙文件名 - 已发布版本：把旧 `pyarmor.rkey` 改名为 `.mcp.lic` 即可继续使用 --- > **到此，FastAPI 项目即可「一份混淆代码、多张授权钥匙」在不同企业服务器安全运行，运维只需替换钥匙文件即可完成续费或迁移。**