Python部署入门（一）：虚拟环境打包，requirements.txt生成

部署入门（一）：虚拟环境打包，requirements.txt 生成

——一个老架构师的“别再让国产化项目因依赖混乱翻车”的血泪忠告：在电科金仓支撑的政务/金融系统里，pip install -r requirements.txt 失败 = 验收延期 + 安全漏洞 + 国产数据库价值归零！

开场白：你的“部署脚本”还在靠 pip list 手抄？

看看你项目里的这些“灾难现场”：

# 场景1：开发机上跑得好好的，测试环境直接崩
$ python app.py
ModuleNotFoundError: No module named 'kingbase'

# 场景2：运维小哥问“到底要装哪些包？”
你：“呃… flask, sqlalchemy, 还有那个数据库驱动…”
运维：“哪个版本？”

# 场景3：安全扫描发现高危漏洞
CVE-2023-XXXX in urllib3==1.25.8 → 但没人知道谁装的！

# 场景4：国产 OS（麒麟 V10）上 pip 装不上社区驱动
ERROR: Could not build wheels for kingbase-python...

结果是什么？

• 环境不一致（开发 ≠ 测试 ≠ 生产）
• 依赖黑洞（不知道用了哪些包）
• 安全合规失败（等保三级要求依赖可审计）
• 国产化交付卡壳（驱动不兼容）

这不是部署问题——这是对国产化交付流程的裸奔！

今天，咱们就用 Python 虚拟环境 + 精准依赖管理，手把手打造一套 可复现、可审计、可国产化 的部署基线。

一、为什么必须用虚拟环境？全局安装是毒药！

💡 关键认知： 在国产化项目中，虚拟环境不是可选项——是等保三级“软件供应链安全”的硬性要求！

了解 KES 企业级能力：https://kingbase.com.cn/product/details_549_476.html

二、实战：从零搭建 KES 兼容的虚拟环境

步骤1：创建虚拟环境（国产 OS 适配）

# 在麒麟 V10 / 统信 UOS 上操作
cd /opt/my_kes_app

# 创建虚拟环境（推荐用 venv，Python 3.3+ 内置）
python3 -m venv venv_kes

# 激活环境
source venv_kes/bin/activate

# 验证（路径应包含 venv_kes）
which python
# 输出: /opt/my_kes_app/venv_kes/bin/python

📌 重要： 不要用 virtualenv！venv 是标准库，避免额外依赖！

步骤2：安装 KES 官方驱动（核心！）

# 下载电科金仓官方驱动（国产 CPU 必须用官方版！）
# https://www.kingbase.com.cn/download.html#drive

# 假设下载了 kingbase_python-9.1.0-cp310-cp310-linux_aarch64.whl（鲲鹏版）
pip install kingbase_python-9.1.0-cp310-cp310-linux_aarch64.whl

# 验证安装
python -c "import kingbase; print('KES 驱动加载成功！')"

📌 血泪教训： 社区版 psycopg2 在麒麟 V10 + 鲲鹏 920 上会导致连接池泄漏！ 必须用 KES 官方驱动！

步骤3：安装业务依赖（带版本锁定）

# 安装核心框架（指定版本！）
pip install "Flask==2.3.3" "SQLAlchemy==2.0.25"

# 安装其他工具
pip install "requests==2.31.0" "python-dotenv==1.0.1"

# 注意：不要用 pip install flask（无版本号 = 未来炸弹）

三、生成精准的 requirements.txt（不是 pip freeze！）

❌ 错误姿势：pip freeze > requirements.txt

# 问题：包含所有依赖（包括子依赖），无法区分直接/间接依赖
Flask==2.3.3
Werkzeug==2.3.7 # Flask 的依赖
SQLAlchemy==2.0.25
greenlet==3.0.3 # SQLAlchemy 的依赖
kingbase==9.1.0
…
# 结果：升级 Flask 时，Werkzeug 版本冲突！

✅ 正确姿势：只记录直接依赖 + 用 pip-tools 编译

方法1：手动维护（简单项目）

# requirements.in（只写直接依赖）
Flask==2.3.3
SQLAlchemy==2.0.25
requests==2.31.0
python-dotenv==1.0.1
# KES 驱动特殊处理（见下文）

方法2：用 pip-tools（推荐！生产级）

# 安装 pip-tools
pip install pip-tools

# 创建 requirements.in
echo "Flask==2.3.3" >> requirements.in
echo "SQLAlchemy==2.0.25" >> requirements.in
echo "requests==2.31.0" >> requirements.in
echo "python-dotenv==1.0.1" >> requirements.in

# 编译锁定版本
pip-compile requirements.in

# 生成 requirements.txt（含完整依赖树 + 哈希校验）
cat requirements.txt

📌 KES 驱动特殊处理： 官方 .whl 文件无法放入 requirements.txt！ 解决方案：

四、生产部署：一键复现环境

步骤1：将依赖打包到部署包

# 项目结构
my_kes_app/
├── app/
├── requirements.txt
├── wheels/ # KES 驱动放这里
│ └── kingbase_python-9.1.0-...whl
└── deploy.sh

步骤2：编写部署脚本（国产 OS 适配）

#!/bin/bash
# deploy.sh
set -e

APP_DIR="/opt/my_kes_app"
VENV_DIR="$APP_DIR/venv_kes"

# 1. 创建虚拟环境
python3 -m venv $VENV_DIR

# 2. 激活并安装依赖
source $VENV_DIR/bin/activate
pip install –upgrade pip

# 3. 安装依赖（–no-index 加速国产网络）
pip install \\
–no-index \\
–find-links file://$APP_DIR/wheels \\
-r $APP_DIR/requirements.txt

# 4. 验证 KES 驱动
$VENV_DIR/bin/python -c "import kingbase; print('✅ KES 驱动验证通过')"

echo "✅ 部署完成！"

步骤3：运行应用

# 启动脚本（确保用虚拟环境 Python）
#!/bin/bash
source /opt/my_kes_app/venv_kes/bin/activate
exec python /opt/my_kes_app/app/main.py

五、避坑指南：国产化部署三大陷阱

❌ 陷阱1：忽略 Python 版本（国产 OS 默认 Python 3.6）

# 危险！麒麟 V10 默认 Python 3.6，但 KES 驱动要 3.8+
python –version # Python 3.6.9

# 正确：先升级 Python（或用容器）
# 参考：https://www.kingbase.com.cn/solution/details_522_491.html

❌ 陷阱2：requirements.txt 包含开发依赖

# 危险！生产环境装了 pytest/flake8
pytest==7.4.0
flake8==6.0.0

# 正确：分离生产/开发依赖
# requirements-prod.txt（生产）
Flask==2.3.3
kingbase==9.1.0

# requirements-dev.txt（开发）
-r requirements-prod.txt
pytest==7.4.0

❌ 陷阱3：未处理国产 CPU 架构

# 危险！在 x86_64 上生成 requirements.txt，拿到鲲鹏上跑
pip install -r requirements.txt # 失败！manylinux 不兼容

# 正确：在目标架构生成依赖
# 在鲲鹏服务器上执行 pip-compile！

六、特别提醒：电科金仓合规要求

结语：部署不是拷贝代码，是国产化交付的生命线

在电科金仓支撑的核心系统里，“能跑就行”的部署脚本是安全漏洞的温床。

记住三条铁律：

下次打包前，问自己：

“这套部署包能在麒麟 V10 + 鲲鹏 920 上一键跑起来吗？”

如果答案不确定—— 用虚拟环境 + 精准依赖 + 电科金仓 KES，让部署成为你的国产化交付盾牌。

作者：一个坚信“可复现即可靠”的技术架构师 环境：Python 3.10 + venv + 电科金仓 KES V9R1（某省政务云平台验证） 注：所有实践均来自等保三级项目，拒绝“玩具示例”！✅