module_bank/README.md

Python Module Bank - SQLite 模块打包系统

一个将 Python 模块打包到 SQLite 数据库，并支持从数据库直接导入模块的工具系统。支持 AES 字节码加密 和 PyArmor 代码混淆 双重保护机制。

🌟 特性

• 单文件分发 - 将所有模块打包到单个 SQLite 数据库文件
• AES 字节码加密 - 编译后的字节码使用 Fernet (AES-128-CBC) 加密存储
• PyArmor 代码混淆 - 支持使用 PyArmor 对 Python 源代码进行混淆保护
• 双层保护 - 可同时使用 PyArmor 混淆 + AES 字节码加密，提供双重安全保障
• 动态导入 - 运行时直接从数据库加载模块，无缝集成 Python 导入系统
• 完整包支持 - 支持包结构和子模块导入
• CLI 工具 - 提供完整的命令行接口

📦 安装

从源码安装

git clone http://124.71.68.6:3000/chakcy/module_bank.git
cd module-bank
pip install -e .

使用 uv（推荐）

git clone http://124.71.68.6:3000/chakcy/module_bank.git
cd module-bank
uv sync

可选依赖

• PyArmor (强烈推荐): uv add pyarmor 或 pip install pyarmor
  • 为模块提供 Python 源代码级别的混淆保护
  • 商业版可去除试用版水印

🚀 快速开始

1. 创建示例模块

# my_package/__init__.py
def hello():
    print("Hello from my_package!")
    return "success"

VERSION = "1.0.0"

# my_package/utils.py
def add(a, b):
    return a + b

2. 打包模块到数据库

使用 AES 加密（推荐）

# 生成密钥并打包
mbank pack my_package --db my_package.mbank --key "$(python -c "from module_bank.encryption import Encryption; print(Encryption.generate_key())")"

使用 PyArmor 混淆

# 使用 PyArmor 保护源代码
mbank pack my_package --db my_package.mbank --pyarmor

使用双层保护

# PyArmor 混淆 + AES 加密
mbank pack my_package --db my_package.mbank --pyarmor --key "your-encryption-key"

3. 从数据库导入

# import_example.py
from module_bank.python_to_sqlite import PythonToSQLite

packer = PythonToSQLite("my_package.mbank")
finder = packer.install_importer(key="your-encryption-key")  # 如果加密了需要提供密钥

from my_package import utils
from my_package import hello

print(hello())
print(utils.add(3, 4))

🛡️ 安全保护机制

第一层：PyArmor 代码混淆

PyArmor 对 Python 源代码进行混淆，将代码转换为难以阅读和逆向的形式：

• 混淆后的代码依赖运行时二进制文件（.pyd/.so），无法直接运行
• 支持混淆级别控制（代码混淆、模块混淆）
• 运行时文件会自动存储在数据库中，加载时自动部署

# 高级混淆选项
mbank pack my_module.py --name my_module --db modules.db \
    --pyarmor \
    --pyarmor-obf-code 1 \
    --pyarmor-obf-mod 1

第二层：AES 字节码加密

编译后的字节码使用 Fernet (AES-128-CBC) 加密：

# 生成密钥
python -c "from module_bank.encryption import Encryption; print(Encryption.generate_key())" > my_key.key

# 使用密钥打包
mbank pack my_module.py --name my_module --db modules.db --key "$(cat my_key.key)"

# 使用时提供密钥
mbank install --db modules.db --key "$(cat my_key.key)"

安全建议

1. 密钥管理：加密密钥不要硬编码在代码中，使用环境变量或密钥管理服务
2. 删除源代码：打包后可从数据库删除源代码，仅保留混淆后的代码：

# 删除所有模块的源代码
mbank delete_source --db modules.db

# 删除指定模块的源代码
mbank delete_source --db modules.db --module my_module

📖 详细使用

命令行工具

# 打包单个模块
mbank pack my_module.py --name my_module --db modules.db

# 打包整个目录（自动识别包结构）
mbank pack my_package/ --db modules.db

# 使用 PyArmor 混淆打包
mbank pack my_module.py --name my_module --db modules.db --pyarmor

# 使用 AES 加密打包
mbank pack my_module.py --name my_module --db modules.db --key "your-key"

# 双层保护
mbank pack my_module.py --name my_module --db modules.db --pyarmor --key "your-key"

# 列出数据库中的模块
mbank list --db modules.db

# 删除源代码
mbank delete_source --db modules.db
mbank delete_source --db modules.db --module my_module

# 安装导入器并进入交互模式
mbank install --db modules.db
mbank install --db modules.db --key "your-key"

编程接口

打包模块

from module_bank import PythonToSQLite
from module_bank.encryption import Encryption

# 生成加密密钥
key = Encryption.generate_key()

# 使用 AES 加密打包
packer = PythonToSQLite("modules.mbank", key=key)

# 或使用 PyArmor 混淆打包
packer = PythonToSQLite(
    "modules.mbank",
    pyarmor_obfuscate=True,
    pyarmor_obf_code=1,
    pyarmor_obf_mod=1,
)

# 打包单个模块
packer.pack_module("module.py", "module_name")

# 打包整个目录（自动识别包结构）
packer.pack_directory("my_package/")

# 验证包结构
packer.verify_package_structure()

导入模块

from module_bank import PythonToSQLite

# 如果数据库中的模块被 AES 加密了，需要提供密钥
packer = PythonToSQLite("modules.mbank")

# 安装导入器到 sys.meta_path
finder = packer.install_importer(key="your-key")

# 列出所有可用模块
modules = packer.list_modules()
for module in modules:
    package_flag = " [包]" if module["is_package"] else ""
    print(f"  - {module['module_name']}{package_flag}")

# 直接导入数据库中的模块（就像普通模块一样）
import my_package
import my_package.submodule

print(my_package)
my_package.hello()

🏗️ 架构设计

核心组件

src/module_bank/
├── python_to_sqlite.py         # 主打包类
├── sqlite_module_importer.py   # 数据库存储管理器
├── sqlite_meta_path_finder.py  # 元路径查找器
├── sqlite_module_loader.py     # 模块加载器
├── encryption.py               # AES 密钥管理
├── pyarmor_encryption.py       # PyArmor 混淆封装
├── cli.py                      # 命令行接口
└── __init__.py                 # 模块导出

数据流

1. 打包阶段:
   .py 文件 → (可选: PyArmor 混淆) → 编译为字节码 → (可选: AES 加密) → 存储到 SQLite

2. 导入阶段:
   导入请求 → MetaPathFinder 查找 → ModuleLoader 加载 → (AES 解密) → (PyArmor 运行时部署) → 执行模块

数据库模式

-- 模块表
CREATE TABLE python_modules (
    module_name TEXT PRIMARY KEY,
    source_code TEXT,               -- 源代码（PyArmor 混淆后）
    bytecode BLOB,                  -- 编译后的字节码（可选 AES 加密）
    is_package BOOLEAN,             -- 是否是包
    metadata TEXT,                  -- 元数据（JSON 格式）
    encrypted INTEGER DEFAULT 0,    -- AES 是否已加密
    pyarmor_protected INTEGER DEFAULT 0,  -- 是否已 PyArmor 混淆
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- PyArmor 运行时存储表
CREATE TABLE pyarmor_runtime (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    runtime_name TEXT UNIQUE NOT NULL,
    pyd_data BLOB,                  -- 原生二进制文件（.pyd/.so）
    init_data TEXT,                 -- __init__.py 内容
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

🔧 高级功能

排除模式

# 打包时排除特定文件
packer.pack_directory(
    "my_project/",
    exclude_patterns=["*_test.py", "*.pyc", "__pycache__"],
)

元数据存储

# 为模块添加元数据
packer.importer.add_module(
    "my_module",
    source_code,
    is_package=False,
    metadata={"version": "1.0", "author": "me"},
)

混合导入

# 数据库导入器默认插入到 meta_path 开头，优先级高于文件系统
import sys
from module_bank import PythonToSQLite

packer = PythonToSQLite("modules.db")
finder = packer.install_importer()

# 如果需要文件系统优先，将查找器追加到末尾
sys.meta_path.remove(finder)
sys.meta_path.append(finder)

验证运行时完整性

from module_bank.sqlite_module_importer import SQLiteModuleImporter

importer = SQLiteModuleImporter("modules.db")
runtimes = importer.list_runtimes()
for rt in runtimes:
    print(f"运行时: {rt['runtime_name']} (创建于: {rt['created_at']})")

⚠️ 注意事项

安全性

• 模块字节码直接执行，确保数据库来源可信
• AES 加密密钥必须安全保管，丢失后将无法解密模块
• PyArmor 混淆提供源代码级别的保护，但商业版才能去除试用版水印
• 生产环境建议 PyArmor 混淆 + AES 加密同时使用

兼容性

• 字节码不跨 Python 版本兼容（3.12 编译的模块无法在 3.11 加载）
• 不支持 C 扩展模块
• PyArmor 运行时文件与操作系统相关（Windows 用 .pyd，Linux 用 .so）
• 运行时文件需在目标系统上重新打包

性能

• 启动时：有一次性数据库查询和反序列化/运行时部署开销
• 运行时：与传统导入性能相同（使用 sys.modules 缓存）
• 最佳适用：长期运行的服务、桌面应用

更新模块

# 重新打包会自动更新
packer.pack_module("updated_module.py", "module_name")

删除模块

-- 直接从数据库删除
DELETE FROM python_modules WHERE module_name = 'module_to_remove';

备份与恢复

# 数据库是单个文件，易于备份
cp modules.mbank modules.backup.mbank

# 恢复
cp modules.backup.mbank modules.mbank

📚 应用场景

1. 商业软件分发 - PyArmor 混淆保护源代码知识产权
2. 安全敏感环境 - AES 加密确保即使数据库泄露也无法还原代码
3. 插件系统 - 动态加载数据库中的加密/混淆插件模块
4. 教育平台 - 安全分发练习代码，防止学生抄袭
5. 微服务 - 打包多个服务模块到单个加密文件
6. 嵌入式系统 - 减少文件系统依赖，提高安全性

---

注意: 本工具主要用于模块分发和部署场景，不适合开发阶段的频繁修改。

许可证: MIT License