内网离线移植步骤

1. 迁移原则

不要直接拷贝现有 .venv 到内网服务器。Ubuntu 20.04 默认 Python 版本偏低，而本项目要求 python >= 3.10，且虚拟环境对路径和系统 ABI 敏感。推荐迁移“项目源代码 + uv.lock + 离线 wheel 包 + Python 运行时”。

2. 在线准备机打包

在一台可联网机器上完成一次完整解析与下载：

deactivate  # 如果当前 shell 里已经激活了 uv 创建的虚拟环境
uv sync
uv export --frozen --no-dev -o requirements.txt
sudo apt-get update
sudo apt-get install -y python3-pip build-essential libxml2-dev libxslt1-dev zlib1g-dev python3-dev
/usr/bin/python3 -m pip wheel -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt -w wheelhouse

不要使用当前 .venv/bin/python3，它可能没有 pip 模块。/usr/bin/python3 必须配合系统包 python3-pip 使用。

如果 lxml 仍报 “No matching distribution found”，先强制走官方 PyPI，再单独构建一次：

/usr/bin/python3 -m pip wheel -i https://pypi.org/simple -r requirements.txt -w wheelhouse
/usr/bin/python3 -m pip wheel -i https://pypi.org/simple "lxml==6.1.0" -w wheelhouse

这类报错通常是准备机的镜像源不全，或者镜像源没有同步到当前 Python 版本对应的二进制包。

同时打包以下内容：

app/
scripts/
tests/
GJB438C-2021_prd_skills/
configs/
pyproject.toml
uv.lock
requirements.txt
wheelhouse/
uv 可执行文件（Linux x86_64）

如果目标机没有 Python 3.10+，还要额外准备一个可移植的 Python 3.10/3.12 运行时目录。推荐在准备机上先安装并验证该运行时，再打包整目录，例如：

sudo /home/zjz/.local/bin/uv python install 3.12 --install-dir /opt/python-3.12
find /opt/python-3.12 -path '*/bin/python3.12' -print
/opt/python-3.12/cpython-3.12.13-linux-x86_64-gnu/bin/python3.12 --version
/opt/python-3.12/cpython-3.12.13-linux-x86_64-gnu/bin/python3.12 -m ensurepip --upgrade
tar -C /opt -czf python-3.12-runtime.tar.gz python-3.12

将 python-3.12-runtime.tar.gz 拷到内网服务器后解压到同一路径，例如 /opt/python-3.12，然后再用它创建虚拟环境：

tar -C /opt -xzf python-3.12-runtime.tar.gz
./uv venv .venv --python /opt/python-3.12/cpython-3.12.13-linux-x86_64-gnu/bin/python3.12
./uv sync --frozen --offline

如果你的准备机还没有现成的 /opt/python-3.12，就先从官方安装包、源码编译产物或已验证的便携发行版生成该目录，再做打包。

如果你不想使用绝对路径，也可以先把 uv 复制到 root 可见的位置：

sudo cp /home/zjz/.local/bin/uv /usr/local/bin/uv
sudo uv python install 3.12 --install-dir /opt/python-3.12

3. 目标机落地

将打包内容拷贝到 Ubuntu 20.04 内网服务器，例如 /opt/docx-analyzer。

cd /opt/docx-analyzer
chmod +x uv

如果系统已有 Python 3.10+：

UV_CACHE_DIR=/opt/docx-analyzer/.uv-cache ./uv sync --frozen --offline

如果系统没有满足版本的 Python：

./uv venv .venv --python /opt/python-3.12/cpython-3.12.13-linux-x86_64-gnu/bin/python3.12
UV_CACHE_DIR=/opt/docx-analyzer/.uv-cache ./uv sync --frozen --offline

如果内网机器不能使用 uv sync 拉取依赖，可直接用 wheel 包安装：

/usr/bin/python3 -m pip install --no-index --find-links wheelhouse -r requirements.txt

4. 启动与验证

启动服务：

UV_CACHE_DIR=/opt/docx-analyzer/.uv-cache ./uv run uvicorn app.main:app --host 0.0.0.0 --port 8010

验证命令：

UV_CACHE_DIR=/opt/docx-analyzer/.uv-cache ./uv run pytest
curl http://127.0.0.1:8010/

分析样例文件时，确认 configs/api_config.yaml 中的 intranet 配置指向内网模型地址，且网络可访问。

5. 运维建议

用 systemd 把 uvicorn 注册成服务。
把 uploads/、outputs/、.uv-cache/ 放在独立目录并定期清理。
首次上线先用 use_model=false 验证本地流程，再切到 intranet 模型。

4.1 KiB Raw Permalink Blame History Unescape Escape