1. 为什么离线部署DataAI Portal值得单独写一篇在Ubuntu 24.04 LTS上做DataAI Portal的离线部署这件事听起来像是把安装包拷进去、跑个脚本就完事了但真正动过手的人都知道离线环境下的坑远比在线安装密集得多。在线安装时apt、pip、docker pull这些命令背后都有网络兜底缺什么补什么而离线环境里你面对的是一个完全封闭的软件供应链任何一个依赖缺失都会让整个部署卡在半路而且报错信息往往指向的不是真正的问题根源。DataAI Portal这类数据与AI能力门户平台通常包含前端Web服务、后端API服务、数据库、缓存、任务调度、模型推理服务等多个组件部署链路长、依赖层次深。把它放到一台没有外网连接的x86_64 Ubuntu 24机器上你需要提前把所有依赖想清楚、备齐、验证。这篇文章就是把我自己在Ubuntu 24.04 x86_64上做DataAI Portal离线部署测试的完整过程拆开来讲包括环境准备、依赖梳理、离线包制作、部署执行、验证方法以及那些只有踩过才知道的坑。适合谁看如果你手上有内网服务器、隔离环境、专有网络里的Ubuntu机器需要部署类似的数据AI平台或者你正在做离线交付的技术验证这篇内容可以直接当操作手册用。即使你用的不是DataAI Portal而是其他需要离线部署的平台类产品里面的依赖梳理思路和排查方法同样适用。先说一个反直觉的结论离线部署最难的不是装而是确认装全了。在线环境下你不需要知道一个服务到底依赖了哪些系统库因为包管理器会帮你解决离线环境下你必须自己成为那个包管理器而且要保证依赖树是闭合的。这是整件事的核心难点也是后面所有步骤围绕展开的主线。2. 离线部署前必须锁死的环境基线2.1 Ubuntu 24.04 x86_64的版本确认与最小化原则动手之前第一件事确认目标机器的架构和系统版本。x86_64架构虽然通用但Ubuntu 24.04和22.04在glibc版本、系统库路径、默认Python版本上都有差异离线包如果按22.04的依赖编译拿到24.04上很可能因为glibc版本不匹配直接报GLIBC_2.xx not found。确认命令很简单uname -m lsb_release -a cat /etc/os-releaseuname -m输出x86_64说明架构正确lsb_release -a会显示Ubuntu 24.04.x LTS。这里有个细节Ubuntu 24.04的默认Python是3.12而很多AI类平台的依赖包对Python版本有严格要求如果DataAI Portal的后端是基于Python 3.10或3.11构建的你就需要在离线环境里额外准备对应版本的Python运行时不能直接用系统自带的3.12。我的建议是离线部署环境尽量保持最小化安装。也就是说装系统时不要选带桌面环境的完整版用Server版最小化安装然后按需补包。原因很实际——桌面环境会带入大量图形库和无关服务一方面增加依赖冲突的概率另一方面让离线依赖清单变得难以维护。你很难判断某个库到底是平台需要的还是桌面环境自带的。注意如果你拿到的是已经装好桌面环境的机器不要急着卸载图形库很多AI推理框架会间接依赖一些底层图形加速库。正确做法是先记录当前已安装包列表部署完成后再对比差异而不是提前做减法。2.2 磁盘、内存与内核参数的预检DataAI Portal这类平台对资源有基本要求离线部署前把资源确认清楚避免装到一半发现磁盘不够。典型的最低配置参考如下资源项最低要求推荐配置说明CPU4核8核以上推理服务吃CPU内存16GB32GB以上数据库与缓存占用大系统盘100GB200GB镜像与离线包占空间数据盘按业务量独立挂载数据库与模型文件分离磁盘检查用df -h内存用free -h。这里有个容易忽略的点离线包本身可能就有几个GB解压后占用翻倍Docker镜像导入后又是另一份空间。所以系统盘预留空间要按离线包解压镜像运行数据四份来算别只按安装包大小估。内核参数方面DataAI Portal如果包含Elasticsearch或类似的搜索组件需要调整vm.max_map_count如果包含大量网络连接的服务需要调整文件描述符限制。这些参数在离线环境里同样要提前配好# 查看当前值 sysctl vm.max_map_count ulimit -n # 临时调整 sysctl -w vm.max_map_count262144 ulimit -n 65536永久生效需要写入/etc/sysctl.conf和/etc/security/limits.conf。这一步在在线环境里经常被跳过因为出问题了可以随时查文档补但离线环境里你查文档都费劲所以提前配好是省事的选择。2.3 时间同步与主机名解析的隐性影响离线环境没有外网NTP但集群内部组件之间的时间必须一致否则会出现token过期、证书校验失败、日志时间错乱等一堆莫名其妙的问题。如果DataAI Portal是多节点部署务必在内网搭一个NTP源或者至少保证所有节点时间手动对齐。主机名解析同样关键。很多平台组件之间通过主机名通信离线环境没有DNS就需要在/etc/hosts里把各节点的主机名和IP写死。我遇到过因为/etc/hosts里少写了一个节点导致某个服务一直连不上注册中心日志里只报连接超时排查了半天才发现是解析问题。# /etc/hosts 示例 192.168.1.10 dataai-master 192.168.1.11 dataai-worker01 192.168.1.12 dataai-worker02提示主机名不要用下划线某些组件对主机名格式有校验下划线会导致注册失败。用短横线或纯字母数字最稳妥。3. 离线依赖清单的梳理与打包策略3.1 从在线环境反向导出依赖树离线部署的核心工作是把在线环境能自动搞定的事情提前在离线包里准备好。最可靠的方法不是凭经验列清单而是在一台与目标环境同版本的在线Ubuntu 24.04 x86_64机器上完整跑一遍在线部署然后把所有下载下来的东西反向导出。具体做法分几层第一层是系统包。用apt安装的所有依赖可以通过以下方式导出清单# 记录部署前已安装包 dpkg --get-selections /tmp/before.txt # 执行在线部署... # 记录部署后已安装包 dpkg --get-selections /tmp/after.txt # 对比差异 diff /tmp/before.txt /tmp/after.txt差异部分就是部署引入的系统包。然后把这些包用apt-get download下载成.deb文件或者用apt-get install --download-only配合本地仓库的方式打包。第二层是Python依赖。如果平台用pip管理Python包用pip download把依赖下载到本地目录pip download -r requirements.txt -d ./offline_packages \ --platform manylinux2014_x86_64 \ --python-version 3.11 \ --only-binary:all:这里--platform和--python-version必须和目标环境严格一致否则下载的wheel包在目标机器上装不上。如果某些包没有预编译wheel需要源码编译那还要把编译工具链和头文件一起打包这是最容易漏的部分。第三层是容器镜像。如果DataAI Portal用Docker或containerd运行用docker save把镜像导出成tar包docker save -o dataai-portal-images.tar \ dataai/portal-web:1.0 \ dataai/portal-api:1.0 \ dataai/portal-worker:1.0镜像导出时要注意如果镜像是在线构建的里面可能引用了外网的base image层docker save会把所有层都打包进去所以导出的tar包通常比镜像本身大不少空间要留够。3.2 依赖闭合性检查避免装到一半发现缺东西依赖清单整理完之后最关键的一步是验证闭合性。所谓闭合就是清单里的所有依赖其自身的依赖也都在清单里形成一个自洽的集合。检查方法是在一台干净的、与目标环境同版本的离线机器上用这份清单做一次完整安装看是否报缺包。这一步我强烈建议单独找一台测试机做不要直接在目标生产机上试。因为验证过程中可能需要反复调整清单在生产机上折腾风险太大。测试机的配置可以低一些但系统版本和架构必须和目标机完全一致。验证时重点关注几类容易漏的依赖动态链接库用ldd检查二进制文件的依赖比如ldd /usr/local/bin/dataai-server看有没有not found的项。Python的C扩展依赖某些Python包依赖系统级的开发库比如libpq-dev、libssl-dev这些不在pip清单里但编译或运行时会用到。字体和locale如果平台有报表导出、PDF生成功能缺少中文字体会导致导出乱码需要提前装好fonts-noto-cjk之类的字体包。时区和locale数据离线环境如果locale没配好某些程序会报编码错误。3.3 离线包的组织结构与校验机制依赖包多了之后管理是个问题。我的做法是按类型分目录并生成校验文件offline-bundle/ ├── debs/ # 系统deb包 ├── pypi/ # Python wheel包 ├── images/ # 容器镜像tar包 ├── binaries/ # 独立二进制文件 ├── configs/ # 配置文件模板 ├── scripts/ # 部署脚本 └── MANIFEST.sha256 # 全量校验文件生成校验文件find . -type f -exec sha256sum {} \; MANIFEST.sha256传输到目标机器后先校验sha256sum -c MANIFEST.sha256这一步看着多余但离线包在拷贝、U盘传输、网络中转过程中损坏的概率不低尤其是大文件。提前校验能避免装到一半报解压失败这种浪费时间的问题。注意离线包里的文件权限也要注意。如果打包时用了root权限解压到目标机器后普通用户可能读不了。建议打包时统一用普通用户或者解压后统一chmod调整。4. 在Ubuntu 24.04上执行离线部署的完整链路4.1 本地APT源与系统依赖的离线安装目标机器上第一步是配置本地APT源让apt能从离线包里装系统依赖。把debs目录拷到目标机比如/opt/offline/debs然后生成Packages索引cd /opt/offline dpkg-scanpackages debs /dev/null | gzip -9c debs/Packages.gz接着配置APT源指向本地目录echo deb [trustedyes] file:///opt/offline/debs ./ /etc/apt/sources.list.d/offline.list apt-get update[trustedyes]是因为本地包没有签名加上这个选项跳过签名校验。生产环境如果对安全性要求高可以自己建本地签名密钥但离线测试阶段用trustedyes更省事。然后安装依赖apt-get install -y --no-install-recommends package-list--no-install-recommends很重要它会跳过推荐包只装必需依赖减少不必要的包引入。离线环境里每多装一个包就多一份潜在冲突。这一步常见的报错是依赖版本冲突比如某个包要求libssl3但系统里是libssl3t64。Ubuntu 24.04做了一次比较大的库重命名t64后缀很多为22.04准备的离线包在24.04上会因为这个报错。解决办法是找对应24.04版本的包或者用dpkg -i --force-depends强制安装后手动补依赖但后者有风险能不用就不用。4.2 Python运行时与虚拟环境的离线搭建如果平台后端是Python建议用独立的虚拟环境不要污染系统Python。离线创建虚拟环境需要先有python3-venv包这个在系统依赖阶段装好。然后python3 -m venv /opt/dataai/venv source /opt/dataai/venv/bin/activate离线安装pip包pip install --no-index --find-links/opt/offline/pypi -r requirements.txt--no-index禁止pip访问网络--find-links指定本地包目录。这两个参数配合使用确保pip只用离线包。这里有个坑requirements.txt里如果写了版本范围而不是固定版本pip在离线环境下可能因为找不到满足范围的包而失败。离线部署前一定要把依赖版本全部锁定用pip freeze导出精确版本。另一个坑是pip自身的版本。Ubuntu 24.04自带的pip版本可能比较新而某些老包在新pip下安装会报metadata generation failed。如果遇到可以在虚拟环境里先降级pippip install --no-index --find-links/opt/offline/pypi pip23.3.24.3 容器镜像导入与运行时配置DataAI Portal的容器镜像导入docker load -i /opt/offline/images/dataai-portal-images.tar导入后确认镜像列表docker images | grep dataai如果平台用docker-compose编排把compose文件和配置模板放到对应目录然后启动docker compose -f /opt/dataai/docker-compose.yml up -d离线环境下docker-compose文件里的镜像地址要改成导入后的本地镜像名不能保留原来的registry地址否则docker会尝试去外网拉取。这个改动很小但很容易忘忘了就是一直卡在Pulling状态。如果平台用Kubernetes部署离线环境需要先把镜像导入到所有节点的容器运行时然后确保Pod的imagePullPolicy是IfNotPresent或Never避免k8s尝试从外网拉镜像。4.4 配置文件与密钥的离线注入平台部署离不开配置文件离线环境里配置文件的处理有几个要点第一数据库连接、缓存地址、服务端口这些配置要在部署前就确定好写进配置模板。离线环境里改配置比在线麻烦因为改完可能要重启多个服务。第二密钥和证书。如果平台组件之间用TLS通信证书要提前生成好并分发到各节点。自签名证书在离线环境里很常见生成时注意SANSubject Alternative Name要包含所有节点的主机名和IP否则证书校验会失败。openssl req -x509 -newkey rsa:4096 -nodes \ -keyout dataai.key -out dataai.crt -days 3650 \ -subj /CNdataai-portal \ -addext subjectAltNameDNS:dataai-master,IP:192.168.1.10第三环境变量。很多平台通过环境变量注入配置离线环境里这些变量要写进systemd unit文件或docker-compose的environment段不要依赖登录shell的profile因为服务启动时不一定加载了profile。5. 部署后的验证与常见故障排查5.1 服务健康检查的分层验证方法部署完成后不要急着点Web界面按层次逐级验证更高效。我的验证顺序是进程层、端口层、接口层、业务层。进程层看服务有没有起来systemctl status dataai-portal docker ps | grep dataai端口层看监听是否正常ss -tlnp | grep -E 8080|8443|5432|6379接口层用curl打健康检查接口curl -s http://localhost:8080/health curl -s http://localhost:8080/api/v1/status业务层才是登录Web界面做实际操作。这样分层的好处是出问题时能快速定位是哪一层的问题而不是对着一个打不开的页面瞎猜。5.2 离线环境特有的报错与对应处理离线部署的报错和在线环境有明显区别下面这张表是我实际遇到过的典型问题报错现象根本原因处理方式GLIBC_2.xx not found离线包按其他版本编译换对应24.04的包或源码重编No matching distribution foundpip找不到离线包检查--find-links路径和包名版本镜像一直Pullingcompose文件保留了远程地址改为本地镜像名服务启动后立即退出配置文件路径或权限错误查journalctl日志定位数据库连接超时/etc/hosts缺解析补全主机名映射中文乱码缺中文字体或locale装字体包并配locale排查时优先看日志journalctl -u service -n 200看systemd服务日志docker logs container看容器日志。离线环境里日志是你唯一的线索来源所以部署前确保日志级别调到合适程度太简略看不到问题太详细又刷屏。5.3 从能跑到跑得稳的收尾检查服务能起来只是第一步离线环境还要确认几件事重启后能否自动恢复手动reboot一次看所有服务是否自动拉起。离线环境里服务依赖顺序很重要数据库没起来之前应用起来会失败需要配好systemd的After和Requires。资源占用是否正常用top、free、iostat观察一段时间确认没有内存泄漏或磁盘疯涨。日志轮转是否配置离线环境磁盘空间宝贵日志不轮转会很快把盘写满。配好logrotate或容器日志的max-size。备份是否可用数据库和配置文件的备份脚本要跑一遍确认备份文件能正常生成和恢复。6. 几次离线部署踩坑后的个人体会做离线部署这件事最大的感受是准备工作占八成执行占两成。在线部署时你可以边装边调离线部署时你必须把问题想在前面。我现在的习惯是每次离线部署前先列一张检查清单把系统版本、架构、依赖清单、镜像列表、配置文件、证书、主机名解析这些逐项打勾确认无误再动手。另一个体会是离线包一定要版本化管理。不要用latest这种标签所有包、镜像、配置都带上明确的版本号并且和部署文档对应。否则过几个月再部署一次你根本记不清当时用的是哪个版本出了问题也无从追溯。还有一点离线环境的测试机和生产机要尽量保持一致包括系统版本、内核版本、磁盘布局。我遇到过测试机和生产机磁盘挂载点不同导致数据库数据目录路径不一致服务起不来的情况。这种问题在在线环境里改个配置就行离线环境里可能要重新打包分发成本高很多。最后分享一个小技巧离线部署完成后把整个部署过程反向导出成一份部署快照包括所有已安装包列表、镜像列表、配置文件、服务状态。下次再部署或者排查问题时这份快照就是最可靠的参照。生成方法很简单dpkg --get-selections deploy-snapshot/packages.txt docker images deploy-snapshot/images.txt systemctl list-units --typeservice deploy-snapshot/services.txt cp -r /opt/dataai/config deploy-snapshot/config这份快照不占多少空间但关键时刻能省下大量排查时间。离线部署的复杂度决定了你不可能记住所有细节把状态固化下来比依赖记忆靠谱得多。