deploy_pkg 构建流程1.1 目标构建一个可在现场离线使用的 Python 环境包包含northland_deploy_pkg/ ├── bin/ │ └── uv ├── python/ │ └── Python 3.10.0 ├── wheelhouse/ │ └── 离线依赖 wheel 包 ├── requirements.lock.txt ├── install.sh └── run_env.sh说明目录/文件作用bin/uvuv 可执行文件用于创建虚拟环境和安装依赖python/随包携带的 Python 3.10.0wheelhouse/提前下载好的离线依赖包requirements.lock.txt固定版本后的依赖清单install.sh现场离线安装脚本run_env.sh现场激活虚拟环境脚本1.2 构建环境要求构建环境需要和现场机器架构一致。在构建机器执行uname -m命令说明命令说明uname -m查看 CPU 架构RK3568 通常应输出aarch64如果输出是x86_64则不能直接用于 RK3568 现场部署包构建。1.3 创建 deploy_pkg 目录mkdir -p /northland_deploy_pkg/{bin,python,wheelhouse} cd /northland_deploy_pkg命令说明命令说明bin存放 uvpython存放 Python 3.10.0wheelhouse存放离线依赖包1.4 安装并复制 uvcurl -LsSf https://astral.sh/uv/install.sh | sh命令说明命令说明curl -LsSf ...下载 uv 安装脚本sh执行安装脚本检查 uvwhich uv uv --version复制 uv 到部署包cp $(which uv) ./bin/uv chmod x ./bin/uv1.5 安装 Python 3.10.0要求 Python 版本必须是3.10.0不要只写3.10。export UV_PYTHON_INSTALL_DIR$PWD/python ./bin/uv python install 3.10.0命令说明命令说明export UV_PYTHON_INSTALL_DIR$PWD/python指定 Python 安装到当前部署包的 python/ 目录./bin/uv python install 3.10.0安装精确版本 Python 3.10.0查找 PythonPY310$(find $PWD/python -type f -name python3.10 | head -n 1) echo $PY310 $PY310 --version1.6 创建构建用虚拟环境./bin/uv venv .venv --python $PY310 --no-python-downloads --seed命令说明命令说明uv venv .venv创建虚拟环境--python $PY310使用部署包内的 Python 3.10.0--no-python-downloads禁止 uv 自动下载其他 Python--seed创建虚拟环境时安装 pip、setuptools、wheel 等基础工具检查版本.venv/bin/python --version .venv/bin/python -m pip --version1.7 安装依赖将项目的requirements.txt放到/northland_deploy_pkg/requirements.txt执行./bin/uv pip install --python .venv/bin/python -r requirements.txt如果需要安装开发依赖./bin/uv pip install --python .venv/bin/python -r requirements-dev.txt1.8 生成锁定依赖文件./bin/uv pip freeze --python .venv/bin/python requirements.lock.txt命令说明命令说明uv pip freeze输出当前虚拟环境中的完整依赖版本 requirements.lock.txt保存为固定版本依赖清单检查依赖冲突./bin/uv pip check --python .venv/bin/python1.9 下载离线依赖包.venv/bin/python -m pip download -r requirements.lock.txt -d wheelhouse命令说明命令说明pip download只下载依赖包不安装-r requirements.lock.txt按固定版本下载依赖-d wheelhouse将依赖包保存到 wheelhouse/ 目录1.10 处理源码包检查wheelhouse中是否还有源码包find wheelhouse -maxdepth 1 \( -name *.tar.gz -o -name *.zip \) -print命令说明命令说明find wheelhouse查找 wheelhouse 中的文件*.tar.gz / *.zip源码包格式没有输出表示依赖包都是 wheel适合离线安装如果存在源码包需要提前构建 wheel例如.venv/bin/python -m pip wheel --no-deps --no-build-isolation -w wheelhouse wheelhouse/psutil-5.9.8.tar.gz命令说明命令说明pip wheel将源码包构建成 wheel--no-deps不额外解析依赖--no-build-isolation不创建隔离构建环境-w wheelhouse将生成的 wheel 放回 wheelhouse构建成功后删除源码包rm -f wheelhouse/*.tar.gz wheelhouse/*.zip再次检查find wheelhouse -maxdepth 1 \( -name *.tar.gz -o -name *.zip \) -print如果无输出说明处理完成。1.11 本机离线模拟安装创建测试环境UV_OFFLINE1 ./bin/uv venv .venv_test --python $PY310 --no-python-downloads --seed离线安装依赖UV_OFFLINE1 ./bin/uv pip sync requirements.lock.txt --python .venv_test/bin/python \ --no-index \ --find-links wheelhouse \ --offline命令说明命令说明UV_OFFLINE1强制 uv 离线运行uv pip sync按 lock 文件同步安装依赖--no-index不访问 PyPI--find-links wheelhouse只从本地 wheelhouse 查找依赖--offline禁止联网检查依赖./bin/uv pip check --python .venv_test/bin/python测试核心依赖导入.venv_test/bin/python - PY import numpy import pandas import sklearn import scipy import torch import psutil import gflags print(offline dependency test ok) PY测试完成后删除测试环境rm -rf .venv_test1.12 编写 install.sh在/northland_deploy_pkg/install.sh中写入#!/usr/bin/env bash set -euo pipefail BASE$(cd $(dirname $0) pwd) UV$BASE/bin/uv export UV_OFFLINE1 export UV_LINK_MODEcopy PYTHON$(find $BASE/python -type f -name python3.10 | head -n 1) if [ -z $PYTHON ]; then echo ERROR: cannot find bundled python3.10 exit 1 fi echo Using Python: $PYTHON $PYTHON --version $PYTHON - PY import sys if sys.version_info[:3] ! (3, 10, 0): raise SystemExit(fERROR: Python version must be 3.10.0, current: {sys.version}) print(Python version check passed) PY $UV venv $BASE/.venv \ --python $PYTHON \ --no-python-downloads \ $UV pip sync $BASE/requirements.lock.txt \ --python $BASE/.venv/bin/python \ --no-index \ --find-links $BASE/wheelhouse \ --offline $UV pip check \ --python $BASE/.venv/bin/python echo Install finished. echo Activate with: echo source $BASE/.venv/bin/activate添加执行权限chmod x install.sh脚本说明内容说明set -euo pipefail遇到错误立即退出BASE...获取 install.sh 所在目录UV$BASE/bin/uv使用部署包内的 uvUV_OFFLINE1强制离线UV_LINK_MODEcopy使用复制模式避免硬链接问题find $BASE/python查找随包携带的 Pythonsys.version_info[:3] ! (3, 10, 0)严格校验 Python 必须是 3.10.0uv venv $BASE/.venv创建现场虚拟环境uv pip sync从本地 wheelhouse 安装依赖uv pip check检查依赖冲突1.13 编写 run_env.sh在/northland_deploy_pkg/run_env.sh中写入#!/usr/bin/env bash BASE$(cd $(dirname $0) pwd) source $BASE/.venv/bin/activate echo Virtual environment activated: which python python --version添加执行权限chmod x run_env.sh脚本说明内容说明source $BASE/.venv/bin/activate激活部署包中的虚拟环境which python查看当前使用的 Pythonpython --version确认 Python 版本1.14 打包 deploy_pkg打包前确认必要文件cd /northland_deploy_pkg ls bin/uv find python -type f -name python3.10 ls requirements.lock.txt ls install.sh run_env.sh find wheelhouse -maxdepth 1 -name *.whl | wc -l find wheelhouse -maxdepth 1 \( -name *.tar.gz -o -name *.zip \) -print要求检查项要求bin/uv必须存在python3.10必须存在requirements.lock.txt必须存在install.sh必须存在run_env.sh必须存在wheelhouse/*.whl必须存在*.tar.gz / *.zip最好没有输出打包# 返回northland_deploy_pkg的上一级 cd .. tar -zcvf northland_deploy_pkg.tar.gz \ --excludenorthland_deploy_pkg/.venv \ --excludenorthland_deploy_pkg/.venv_test \ --excludenorthland_deploy_pkg/.cache \ --excludenorthland_deploy_pkg/__pycache__ \ northland_deploy_pkg命令说明命令说明cd /进入根目录保证打包路径一致tar -zcvf使用 gzip 压缩打包--exclude.venv不打包构建用虚拟环境--exclude.venv_test不打包测试虚拟环境--exclude.cache不打包缓存northland_deploy_pkg需要打包的目录deploy_pkg 现场应用流程2.1 现场目录规划假设现场算法代码目录为/znv/newland/backendpackage/Northland-O_V2.10.001_20260513部署包建议解压到同级目录/znv/newland/backendpackage/northland_deploy_pkg最终结构/znv/newland/backendpackage/ ├── Northland-O_V2.10.001_20260513/ │ └── 现场算法代码 └── northland_deploy_pkg/ ├── bin/ ├── python/ ├── wheelhouse/ ├── requirements.lock.txt ├── install.sh └── run_env.sh说明目录说明Northland-O_V2.10.001_20260513原有算法代码目录northland_deploy_pkg离线 Python 环境包.venv执行 install.sh 后生成的虚拟环境2.2 上传部署包将以下文件上传到现场服务器/tmpnorthland_deploy_pkg.tar.gz2.3 解压部署包tar -zxvf northland_deploy_pkg.tar.gz -C /znv/newland/backendpackage解压后确认ls /znv/newland/backendpackage/northland_deploy_pkg应能看到bin python wheelhouse requirements.lock.txt install.sh run_env.sh2.4 执行 install.sh进入部署包目录cd /znv/newland/backendpackage/northland_deploy_pkg执行安装chmod x install.sh ./install.sh命令说明命令说明cd .../northland_deploy_pkg进入部署包目录chmod x install.sh给安装脚本添加执行权限./install.sh创建 .venv 并离线安装依赖安装成功后会生成/znv/newland/backendpackage/northland_deploy_pkg/.venv2.5 激活虚拟环境执行run_env.sh激活虚拟环境. run_env.sh检查当前 Pythonwhich python python --version期望结果/znv/newland/backendpackage/northland_deploy_pkg/.venv/bin/python Python 3.10.02.6 检查依赖如果当前 shell 已经激活.venv可以执行python -m pip check测试核心依赖python - PY import numpy import pandas import sklearn import scipy import torch import psutil import gflags print(dependency ok) PY2.7 运行现场算法激活虚拟环境后进入算法目录cd /znv/newland/backendpackage/Northland-O_V2.10.001_20260513然后按原有方式执行算法即可。如果原有启动命令是 shell 脚本例如./start.sh则执行source /znv/newland/backendpackage/northland_deploy_pkg/.venv/bin/activate cd /znv/newland/backendpackage/Northland-O_V2.10.001_20260513 ./start.sh注意如果start.sh中写死了/usr/bin/python3则不会使用虚拟环境 Python需要将启动脚本中的 Python 命令改成python或在启动脚本前显式激活虚拟环境。2.9 退出虚拟环境deactivate
