1. 项目缘起与整体部署思路1.1 为什么要在离线环境折腾这套东西DataAI Portal 这套东西说白了就是一个面向数据与 AI 场景的门户平台通常包含数据接入、任务调度、模型管理、可视化看板等模块。在线环境下部署它并不复杂几条命令拉镜像、装依赖就能跑起来。但真正到了生产现场尤其是内网隔离环境事情就完全不一样了——没有外网、没有软件源、没有 pip 源甚至连系统时间同步都得手动搞。我这次接到的任务就是在一台 Ubuntu 24 x86_64 的机器上把 DataAI Portal 完整地离线部署起来并跑通测试。先说说为什么选 Ubuntu 24。Ubuntu 24.04 LTS 是长期支持版本内核版本较新对 x86_64 架构的支持非常成熟社区文档也齐全。相比一些国产化操作系统Ubuntu 在离线包管理、依赖解析上的坑相对少一些尤其是 apt 的离线缓存机制做得比较完善。当然如果你面对的是银河麒麟高级服务器操作系统 V10 这类环境思路是相通的只是包管理工具从 apt 换成了 yum 或 dnf后面我会顺带提一下差异点。离线部署的核心矛盾在于在线部署时那些“顺手就下载了”的依赖在离线环境里全部需要提前准备好并且版本必须严格匹配。这就像你要去一个没有超市的地方生活一个月出发前必须把柴米油盐酱醋茶全部列清单、买齐、打包少一样到了地方就抓瞎。所以整个项目的重点不在于“装”而在于“备”——准备工作做扎实了现场部署就是按部就班的事。1.2 整体方案选型与架构拆解我采用的方案是“离线包预构建 本地源挂载 容器化交付”三件套。具体来说离线包预构建在一台有外网的 Ubuntu 24 x86_64 机器上把 DataAI Portal 所需的所有 deb 包、Python wheel 包、Docker 镜像全部下载下来打包成一个完整的离线资源目录。本地源挂载在现场机器上把 deb 包做成一个本地 apt 源把 wheel 包做成一个本地 pip 源这样安装时就不需要访问外网。容器化交付DataAI Portal 的核心服务用 Docker 镜像交付镜像在预构建阶段就导出成 tar 文件现场直接docker load导入。为什么这么设计因为 DataAI Portal 的依赖链条很长涉及 Python 运行时、数据库驱动、消息队列客户端、前端构建产物等。如果纯用裸机安装依赖冲突的概率极高而且离线环境下排查依赖问题非常痛苦。容器化能把大部分依赖封装在镜像内部减少对宿主机环境的污染。但容器本身和 Docker 引擎还是需要宿主机安装的所以 deb 离线源这部分省不掉。另外我特意把“预构建”和“现场部署”分成两个阶段中间用一份详细的资源清单衔接。这份清单记录了每个包的名称、版本、来源和校验值现场部署时逐项核对避免出现“包拿错了”这种低级但致命的问题。1.3 适用人群与前置知识这套流程适合以下人群参考一是在内网隔离环境做平台部署的运维工程师二是需要交付 AI 平台到客户现场的交付工程师三是对离线部署流程感兴趣、想了解完整方法论的技术爱好者。前置知识方面你需要熟悉 Linux 基本命令、了解 apt 和 pip 的基本用法、知道 Docker 的常用操作。如果这些都不太熟也没关系我会把每一步的命令和意图都写清楚照着做基本能跑通。但有一点要提醒离线部署最怕的就是“想当然”每一步都要验证不能凭感觉跳过。2. 离线资源准备的核心细节2.1 预构建机器的环境对齐预构建机器的环境必须和现场机器尽可能一致这是整个离线部署成败的关键。我见过太多案例预构建用的是 Ubuntu 22.04现场是 Ubuntu 24.04结果 deb 包依赖版本对不上装到一半报一堆dependency not satisfiable。所以第一步就是确认现场机器的精确信息# 查看系统版本 lsb_release -a # 查看内核版本 uname -r # 查看架构 dpkg --print-architecture # 查看已安装的关键包版本 dpkg -l | grep -E libc6|libssl|python3把这些信息记录下来然后在预构建机器上对照调整。如果预构建机器版本不一致最稳妥的办法是直接用 Ubuntu 24.04 的官方 ISO 重装一台虚拟机确保libc6、libssl这些底层库版本完全一致。别嫌麻烦这一步省下来的时间后面排查依赖问题时会加倍还回去。提示如果现场机器是银河麒麟 V10 这类基于 RPM 的系统预构建机器也要换成对应的系统版本包管理工具从 apt 换成 yum/dnf但整体思路不变。2.2 deb 离线包的完整下载方法Ubuntu 下下载 deb 包我推荐用apt-get download配合apt-rdepends递归下载所有依赖。具体操作如下# 安装必要工具 sudo apt-get install -y apt-rdepends dpkg-dev # 创建离线包目录 mkdir -p /opt/offline-repo/debs cd /opt/offline-repo/debs # 递归下载某个包及其所有依赖 apt-get download $(apt-rdepends docker.io | grep -v ^ | grep -v ^docker.io$ | sort -u)这里有个坑apt-rdepends输出的依赖列表里会包含一些虚拟包virtual package这些包没有实际的 deb 文件直接下载会报错。解决办法是过滤掉那些apt-get download找不到的包或者用--print-uris先看看能不能下载。我通常的做法是写一个小脚本逐个尝试下载失败的记录下来手动处理。另外apt-get download下载的包默认放在当前目录文件名格式是包名_版本_架构.deb。下载完成后用dpkg-scanpackages生成 Packages 索引cd /opt/offline-repo dpkg-scanpackages debs /dev/null | gzip -9c debs/Packages.gz这样本地 apt 源就做好了。现场机器上把这个目录拷贝过去在/etc/apt/sources.list.d/下加一行deb [trustedyes] file:/opt/offline-repo/debs ./然后apt-get update就能识别了。2.3 Python wheel 包的离线打包DataAI Portal 的 Python 依赖通常通过requirements.txt管理。离线打包 wheel 包的命令是# 在有网机器上 pip download -r requirements.txt -d /opt/offline-repo/wheels --platform manylinux2014_x86_64 --python-version 3.12 --only-binary:all:这里有几个关键参数需要解释--platform manylinux2014_x86_64指定目标平台确保下载的 wheel 包能在 x86_64 Linux 上运行。--python-version 3.12指定 Python 版本Ubuntu 24.04 默认是 Python 3.12。--only-binary:all:只下载二进制 wheel 包避免下载源码包后现场编译离线环境编译往往缺编译器或头文件。如果某些包没有对应的 wheel只能下载源码包sdist那就需要现场编译。这时候要提前把build-essential、python3-dev这些编译工具也加入 deb 离线包列表。现场安装时用pip install --no-index --find-links/opt/offline-repo/wheels -r requirements.txt即可从本地目录安装。2.4 Docker 镜像的导出与导入DataAI Portal 的 Docker 镜像导出比较简单# 在有网机器上拉取镜像 docker pull dataai/portal:latest docker pull dataai/worker:latest docker pull postgres:16 docker pull redis:7 # 导出为 tar 文件 docker save -o /opt/offline-repo/images/dataai-portal.tar dataai/portal:latest docker save -o /opt/offline-repo/images/dataai-worker.tar dataai/worker:latest docker save -o /opt/offline-repo/images/postgres.tar postgres:16 docker save -o /opt/offline-repo/images/redis.tar redis:7现场导入docker load -i /opt/offline-repo/images/dataai-portal.tar docker load -i /opt/offline-repo/images/dataai-worker.tar docker load -i /opt/offline-repo/images/postgres.tar docker load -i /opt/offline-repo/images/redis.tar注意docker save导出的 tar 文件可能很大几个 GB 很正常。拷贝到现场时建议用移动硬盘别用 U 盘速度差太多。另外导入后记得用docker images确认镜像标签是否正确有时候导入后标签会变成none需要手动docker tag修复。2.5 资源清单的编制与校验所有资源准备好后必须编制一份清单记录每个文件的名称、大小、SHA256 校验值。现场部署前逐项核对确保文件完整、未被篡改。校验命令# 生成校验值 sha256sum /opt/offline-repo/debs/*.deb /opt/offline-repo/checksums.txt sha256sum /opt/offline-repo/wheels/*.whl /opt/offline-repo/checksums.txt sha256sum /opt/offline-repo/images/*.tar /opt/offline-repo/checksums.txt # 现场校验 sha256sum -c /opt/offline-repo/checksums.txt这一步看似繁琐但能避免很多“莫名其妙”的安装失败。我曾经遇到过一次离线包在拷贝过程中损坏导致 Docker 镜像导入后启动报错排查了半天才发现是文件不完整。从那以后校验这一步我从来不敢省。3. 现场部署实操全流程3.1 系统基础环境配置现场机器拿到手先做基础配置。首先是网络配置离线环境通常只有内网需要手动设置静态 IP# 编辑网络配置Ubuntu 24 使用 netplan sudo vim /etc/netplan/01-netcfg.yaml配置内容示例network: version: 2 ethernets: ens33: addresses: - 192.168.1.100/24 routes: - to: default via: 192.168.1.1 nameservers: addresses: - 192.168.1.1应用配置sudo netplan apply然后是主机名和 hosts 配置DataAI Portal 的各个组件之间通常通过主机名通信提前配好能省不少事sudo hostnamectl set-hostname dataai-portal sudo vim /etc/hosts # 添加 192.168.1.100 dataai-portal时间同步也很重要离线环境没法用 NTP 公网服务器如果内网有 NTP 服务器就指向它没有的话就手动设置时间并关闭自动同步sudo timedatectl set-time 2025-01-01 12:00:00 sudo timedatectl set-ntp false3.2 本地 apt 源挂载与依赖安装把离线资源目录拷贝到现场机器的/opt/offline-repo然后配置本地 apt 源# 备份原有源 sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak sudo rm /etc/apt/sources.list.d/*.list # 添加本地源 echo deb [trustedyes] file:/opt/offline-repo/debs ./ | sudo tee /etc/apt/sources.list.d/offline.list # 更新源 sudo apt-get update如果apt-get update报错常见原因是 Packages.gz 没有生成或者路径不对。检查/opt/offline-repo/debs/Packages.gz是否存在以及 sources.list 里的路径是否指向包含 Packages.gz 的目录。更新成功后安装 Docker 和其他基础依赖sudo apt-get install -y docker.io docker-compose-plugin sudo systemctl enable docker sudo systemctl start docker验证 Docker 是否正常docker version docker run --rm hello-world如果hello-world镜像没有提前导入这一步会失败。所以要么提前导入这个测试镜像要么跳过这步直接用 DataAI Portal 的镜像测试。3.3 Docker 镜像导入与服务编排导入镜像cd /opt/offline-repo/images for img in *.tar; do echo Loading $img ... docker load -i $img done导入完成后检查镜像列表docker images接下来是服务编排。DataAI Portal 通常用 docker-compose 管理编排文件docker-compose.yml需要提前准备好。一个典型的编排配置如下version: 3.8 services: postgres: image: postgres:16 environment: POSTGRES_USER: dataai POSTGRES_PASSWORD: dataai123 POSTGRES_DB: dataai_portal volumes: - ./data/postgres:/var/lib/postgresql/data ports: - 5432:5432 restart: always redis: image: redis:7 ports: - 6379:6379 restart: always portal: image: dataai/portal:latest depends_on: - postgres - redis environment: DB_HOST: postgres DB_PORT: 5432 DB_USER: dataai DB_PASSWORD: dataai123 DB_NAME: dataai_portal REDIS_HOST: redis REDIS_PORT: 6379 ports: - 8080:8080 restart: always worker: image: dataai/worker:latest depends_on: - postgres - redis environment: DB_HOST: postgres DB_PORT: 5432 DB_USER: dataai DB_PASSWORD: dataai123 DB_NAME: dataai_portal REDIS_HOST: redis REDIS_PORT: 6379 restart: always启动服务docker compose up -d查看服务状态docker compose ps docker compose logs -f portal3.4 数据库初始化与数据导入DataAI Portal 首次启动时通常需要初始化数据库表结构。如果镜像内置了初始化脚本启动时会自动执行如果没有需要手动导入 SQL 文件# 拷贝 SQL 文件到 postgres 容器 docker cp /opt/offline-repo/sql/init.sql postgres:/tmp/init.sql # 执行初始化 docker exec -it postgres psql -U dataai -d dataai_portal -f /tmp/init.sql初始化完成后验证表是否创建成功docker exec -it postgres psql -U dataai -d dataai_portal -c \dt如果有多张表说明初始化成功。接下来可以导入一些测试数据验证读写是否正常。3.5 前端访问与功能验证DataAI Portal 的前端通常通过 8080 端口访问。在浏览器里打开http://192.168.1.100:8080如果能看到登录页面说明前端服务正常。登录后依次验证以下功能数据源管理能否添加数据源、测试连接。任务调度能否创建任务、手动触发、查看日志。模型管理能否上传模型、查看模型列表。看板展示能否正常渲染图表。每个功能都点一遍别嫌麻烦。离线部署最怕的就是“看起来启动了实际功能不可用”。我遇到过前端页面能打开但后端 API 全部 500 的情况最后发现是数据库连接配置写错了。所以验证一定要全面。4. 常见问题与排查技巧实录4.1 apt 源相关故障排查问题一apt-get update报Release file for ... is not valid yet这个错误通常是系统时间不对导致的。离线环境时间容易漂移检查date命令输出如果时间明显不对手动校正sudo date -s 2025-01-01 12:00:00 sudo hwclock --systohc问题二apt-get install报Unable to locate package先确认包名拼写是否正确然后检查本地源是否包含该包ls /opt/offline-repo/debs/ | grep 包名如果包存在但找不到可能是 Packages.gz 没有更新。重新生成cd /opt/offline-repo dpkg-scanpackages debs /dev/null | gzip -9c debs/Packages.gz sudo apt-get update问题三依赖冲突报but it is not going to be installed这是最头疼的问题通常是预构建机器和现场机器的底层库版本不一致。解决办法是查看具体冲突的包手动下载对应版本的 deb 包补充到离线源里。如果冲突太严重建议重新对齐预构建环境。4.2 Docker 相关故障排查问题一docker load报invalid tar header说明 tar 文件损坏或不完整。用sha256sum -c校验如果校验失败重新拷贝文件。问题二容器启动后立即退出查看日志docker compose logs 服务名常见原因包括数据库连接失败、配置文件缺失、端口被占用。逐一排查。问题三docker compose up报no such image说明镜像没有导入成功或者镜像标签不匹配。用docker images确认镜像是否存在如果标签是none手动打标签docker tag image_id dataai/portal:latest4.3 Python 依赖相关故障排查问题一pip install报Could not find a version that satisfies the requirement说明本地 wheel 目录里没有对应的包。检查包名和版本是否匹配必要时重新下载。问题二安装时报编译错误说明下载的是源码包现场编译缺工具。安装编译依赖sudo apt-get install -y build-essential python3-dev或者重新下载对应平台的 wheel 包。4.4 常见问题速查表问题现象可能原因排查方法解决方案apt update 失败时间不对/源路径错检查 date 和 sources.list校正时间/修正路径包找不到Packages.gz 未更新检查 Packages.gz 是否存在重新生成索引依赖冲突环境版本不一致查看冲突包版本补充对应版本 deb 包docker load 失败tar 文件损坏sha256sum 校验重新拷贝文件容器启动退出配置错误/端口占用docker logs 查看修正配置/换端口pip 安装失败wheel 缺失检查 wheels 目录重新下载 wheel前端打不开服务未启动/防火墙docker ps/检查防火墙启动服务/开放端口API 报 500数据库连接失败查看后端日志修正数据库配置4.5 独家避坑经验分享第一个经验预构建阶段一定要多下载一些“可能用到”的包。比如vim、curl、net-tools这些常用工具现场很可能需要但离线环境装不了。多下载几个包占不了多少空间但能省很多事。第二个经验Docker 镜像的导出顺序有讲究。如果多个镜像共享基础层先导出基础镜像再导出上层镜像导入时按同样顺序能减少存储占用。不过docker save默认会包含所有层所以这个优化效果有限但养成好习惯没坏处。第三个经验现场部署前先做一次“空跑”。找一台同样配置的机器完整走一遍部署流程记录每一步的耗时和问题。正式部署时心里有底遇到问题也不慌。第四个经验日志目录一定要挂载到宿主机。容器重启后日志会丢失挂载出来方便排查问题。在 docker-compose.yml 里加 volume 映射即可。第五个经验数据库数据目录也要挂载。否则容器删除后数据全丢重新初始化很麻烦。这个坑我踩过当时测试数据全没了只能重新导入。5. 部署后的优化与扩展建议5.1 性能调优的几个关键参数DataAI Portal 跑起来之后如果发现响应慢可以从以下几个方向调优数据库连接池调整后端服务的数据库连接池大小默认值通常偏小。在环境变量里设置DB_POOL_SIZE20、DB_MAX_OVERFLOW10。Redis 缓存确认 Redis 是否正常工作缓存命中率低会导致频繁查库。用redis-cli info stats查看命中率。Worker 并发数如果任务队列积压增加 Worker 实例数量或调整并发参数。在 docker-compose.yml 里用deploy.replicas扩展。JVM 参数如果 Portal 是 Java 应用调整堆内存-Xms2g -Xmx4g根据机器内存合理设置。5.2 离线环境的持续维护离线部署不是一锤子买卖后续还有维护需求。建议做好以下几件事建立离线包版本库每次更新都保留旧版本方便回滚。定期校验文件完整性用 sha256sum 定期检查防止存储介质损坏。记录每次变更谁在什么时候改了什么配置都要有记录。离线环境排查问题全靠这些记录。准备应急恢复方案数据库备份、镜像备份、配置文件备份一个都不能少。5.3 从 Ubuntu 迁移到其他系统的注意事项如果后续需要把这套方案迁移到银河麒麟 V10 或其他基于 RPM 的系统主要差异在包管理部分deb 包换成 rpm 包用yumdownloader或dnf download下载。本地源配置从sources.list换成/etc/yum.repos.d/下的.repo文件。依赖解析工具从apt-rdepends换成repoquery。Python 环境可能默认版本不同需要额外安装 Miniconda 或指定版本的 Python。Miniconda 在离线环境的安装也是个常见需求。下载 Miniconda 的 sh 安装包拷贝到现场bash Miniconda3-latest-Linux-x86_64.sh -b -p /opt/miniconda3静默安装然后配置本地 pip 源即可。这个方案在银河麒麟 V10 上同样适用我实测过没什么大问题。5.4 自动化部署脚本的编写思路如果经常需要部署建议把整个流程脚本化。脚本的核心逻辑是检查系统版本和架构。挂载本地 apt 源安装基础依赖。导入 Docker 镜像。生成配置文件从模板替换变量。启动服务。健康检查验证各组件是否正常。脚本里要加足够的日志输出和错误处理每一步失败都要有明确的提示。别写那种“一路往下跑错了也不知道哪错了”的脚本离线环境排查问题本来就难脚本再不友好就是给自己找罪受。我个人在实际操作中的体会是离线部署这件事技术难度其实不算高难的是细心和耐心。准备工作做得越充分现场就越顺利。每次部署完我都会把遇到的问题和解决办法记录下来下次遇到类似情况就能快速定位。这套 DataAI Portal 的离线部署方案我在多个项目里复用过了整体稳定可靠希望对你也有帮助。