简介：面向银河麒麟操作系统的QGis离线安装资源包，适用于政务内网、涉密机房等无外网环境下的地理信息系统部署场景，也供运维人员处理依赖关系与国产CPU（如飞腾）架构兼容问题时参考。包内共95个文件，以89个deb安装包为主，覆盖QGis主程序、python3-gdal、libqgis系列等核心依赖；另有2个sh脚本用于自动化安装与配置，1个txt离线安装说明、1个sig校验文件和1个tar.gz依赖归档，总大小358.59MB。目前已有1249人学习、下载。这份资源将安装过程中可能涉及的版本确认、软件包校验、依赖冲突处理、国产架构适配等关键环节提前整理，对照说明与脚本即可逐步完成部署，无需再逐一到网上寻找依赖包，能显著降低特殊网络环境下的部署门槛；同时可验证数据读取、图层叠加、空间分析等基础功能是否正常，适合银河麒麟系统维护者与GIS项目实施人员直接参考使用。
1. 银河麒麟上离线装 QGIS 卡在哪：先看清它的依赖规模
银河麒麟系统上离线安装 QGIS，很多人第一反应是去改软件源或者找离线安装包，结果折腾一圈才发现，真正难的不是 QGIS 这个主包，而是它背后的几十个依赖库。QGIS 是典型的 Qt 桌面应用，底层挂着 GDAL、GEOS、PROJ、QScintilla 这些专业库，任何一个版本对不上，程序都起不来。内网机器没有外网，apt 的在线解析能力就会全部失效，于是“离线装 QGIS”就变成了一个纯粹的依赖搬运问题：把在线的依赖树完整克隆下来，再以目标机可识别的方式喂给 dpkg 或 apt。这个问题如果解决不好，连启动 QGIS 都做不到，更别提做图层编辑和制图。这篇就围绕这条搬运链路展开，把选型、命令、踩坑和验证一次讲清楚，适合正在折腾国产化内网 GIS 装备的项目组。
2. 离线安装方案选型：为什么首选“搬 deb 包”而不是源码编译
2.1 银河麒麟是 Debian 系，先确认 apt/dpkg 这套底子
先说底层。银河麒麟 V10 的桌面版和服务器版都构建在 Debian 体系之上，所以包管理命令仍然是 apt-get / apt / dpkg 这一套。你在麒麟终端里敲 apt-get install 能用的软件源，都是 Debian 格式的软件源；下载下来的软件包也是标准的 .deb 文件。这带来的最大好处是：离线安装不需要什么特殊工具，只要有另一台同样架构、同样源体系的 Debian 系机器，就能把包一个个下载下来，搬到内网去。
这里特别提醒一点：不要因为银河麒麟的界面长得像某些国产系统，就以为它和那些基于 RPM 的系统一样。系统里有没有 dpkg 命令，决定了后续所有操作路径。可以用下面几条命令确认底子，同时顺手看一下 QGIS 在源里的状态：
cat /etc/os-release dpkg --print-architecture apt-cache policy qgis第一条命令输出系统名称和版本；第二条命令输出 CPU 架构；第三条命令能看到软件源里是否有 qgis、候选版本是多少。如果apt-cache policy qgis输出的是 “N: Unable to locate package qgis”，就说明当前源里没有收录 QGIS，需要先把源换成麒麟官方源或合适的 Debian 源再继续。这一步看起来繁琐，但值得做，因为后续收集依赖的机器和目标机器的系统版本是否接近，直接决定了你会不会踩到后文说的版本冲突坑。
我一般会顺手记录这三个命令的输出，把它写到部署说明里。见过一些同事直接跳过检查，把一台 Ubuntu 机器当做依赖收集机，结果下载回来的库版本比目标机高，最后 dpkg -i 报错的时候，排查了半天也找不到原因。这个习惯不是多余，而是给后面的安装步骤买了份保险。
2.2 为什么不推荐源码编译 QGIS
QGIS 的源码编译，在联网机器上都不轻松，更不用说离线环境。它依赖的库包括 GDAL、GEOS、PROJ、Qt5、Python3、QScintilla、SIP 等，每个库又各自有一堆开发头文件和构建依赖。在离线机器上，光是把这些 devel 包凑齐，就要重走一遍我们现在要做的事。整个离线搬运依赖的过程一个不少，成本谈不上节省，出错面却更大。
而且编译阶段的报错往往很不直观。也许是编译器版本太高导致某个旧版库源码过不去，也许是某个头文件路径不对，也许是 Python3 和 Qt5 的绑定版本不匹配。我早些年给一个图像处理 Demo 做过一次 Qt 项目的离线编译，处理依赖的时间占了整个项目的一大半，最后运行阶段仍然冒出了新的问题。QGIS 的复杂度比那个 Demo 高得多，用到生产环境里，源码编译并不是一个工程上的好选择。除非你需要改 QGIS 源码本身，或者在某种特殊 CPU 平台上必须重新编译，否则老老实实装官方仓库里的 deb 是最稳的路线。
2.3 三条离线路线的选型对照
排除源码编译之后，剩下可行的路线其实可以压缩成三条：手动搬运 deb 包用 dpkg 装、搭一个本地 apt 软件源、用容器镜像整体迁移。它们各有适用场景，我先用一张表做对比，再说说我的取舍逻辑。
| 路线 | 适用场景 | 准备成本 | 后续维护 |
|---|---|---|---|
| 手动搬运 deb + dpkg -i | 单台机器、一次性部署 | 低 | 差，缺依赖要手动补 |
| 本地内网 apt 软件源 | 多台机器、重复部署 | 中 | 好，能自动解析依赖 |
| 容器镜像整体迁移 | 内网机器允许容器运行时 | 中高 | 好，但依赖宿主系统一致 |
如果目标环境只有一两台离线机器，又急着用 QGIS 出图，手动搬运最快；如果是一个项目组里七八台机器都要装，后面可能还要装其他 GIS 工具，那建议直接把 deb 目录变成内网源。容器路线听起来干净，但在国产化环境的很多内网机器上根本没有容器运行时，能用的前提是你已经有了可用的 runtime，并且目标机器的内核和依赖库版本足够一致，否则镜像里调用的系统调用或显卡库照样翻车。
所以本文默认的主线是前两种，也就是“手动收集 deb → 本地软件源”的路径。它的前期成本只是多敲几条命令，但换来的是后续给任意一台麒麟机器装 QGIS 都不会再返工。我自己在某个跨平台系统交付时就是这么干的，一次建源，后面陆续装了五六台机器，没再碰过依赖问题。
3. 用 apt 在联网机器上递归收集 QGIS 依赖包：从 download-only 到完整脚本
3.1 第一步检查架构和软件源候选版本
收集依赖的前提，是有一台可以联网的 Debian 系机器。我建议先在这台机器上执行三个检查命令，确定它和目标机器的“身份”是否匹配：
cat /etc/os-release dpkg --print-architecture apt-cache policy qgis这里要重点看架构。银河麒麟既有跑在 Intel/AMD 上的 x86_64 版本，也有跑在飞腾、鲲鹏上的 arm64 版本。dpkg --print-architecture输出amd64还是arm64，直接决定了后面下载的 deb 包是否能用。如果收集机是 x86，目标机是 ARM，那收集得再完整也白搭。
其次看apt-cache policy qgis输出的候选版本。不同的系统源里收录的 QGIS 版本可能差很多，有的是 3.10，有的是 3.22。版本新不代表必须追，生产环境我反而建议用和目标机同源同版本的包。如果你用 Ubuntu 最新源收集，拿到麒麟 V10 SP1 的目标机上装，版本冲突几乎是必然的。所以这一步不是走流程，是真的能省后面几小时的排错时间。
3.2 最快的方式：用 apt-get install --download-only 拉缓存目录
如果收集环境是一个刚装好的全新系统，或者是你临时启动的一个干净容器，最快的方式是让 apt 自己解析依赖并下载：
sudo apt-get clean sudo apt-get install --download-only -y qgis ls -l /var/cache/apt/archives/*.deb | wc -l执行完之后，/var/cache/apt/archives下会有一批 .deb 文件，数量一般能达到几十个以上。这个方案的优点是快，apt 自己算清楚了依赖顺序；缺点也有，它只下载当前机器“还没安装”的包。如果这台收集机不是干净的，桌面上已经带了一堆 Qt 库，那么这些库不会被下载下来，而目标机如果偏偏缺它们，安装就会失败。
所以我用它只有两个前提：一是收集机是新建的临时环境，二是目标机的软件环境我确认过不缺基础组件。否则我还是会用下面这种递归解析的方式，买一个确定性。
3.3 最稳的方式：递归解析依赖的收集脚本
递归收集的原理很简单：用apt-cache depends --recurse把 QGIS 的依赖树展开，得到一长串包名，然后逐个apt-get download下载。我把这个流程写成了脚本，放在联网机器上执行，输出目录就是你要搬到内网的完整 deb 集。
#!/bin/bash # collect_qgis_deps.sh # 在联网的 Debian / 银河麒麟机器上运行 # 用途：把 qgis 及其全部依赖的 .deb 下载到 ~/qgis-debs 目录 PKG=qgis OUT=~/qgis-debs mkdir -p "$OUT" cd "$OUT" || exit 1 # 递归展开依赖，只看 Depends 和 PreDepends，忽略 Recommends/Suggests # 注意保留了 |Depends: 这种可选依赖行，宁可多下，不能少下 deps=$(apt-cache depends --recurse --no-recommends --no-suggests \ --no-conflicts --no-breaks --no-replaces --no-enhances "$PKG" \ | grep 'Depends: ' \ | awk '{print $2}' \ | sed 's/:.*//g' \ | sort -u) # 把 qgis 本身也加进去 deps="$deps $PKG" deps=$(echo "$deps" | tr ' ' '\n' | sort -u) # 逐个下载，失败的就记录到 missing.txt for p in $deps; do if ! apt-get download "$p" 2>/dev/null; then echo "$p" >> missing.txt fi done echo "下载结束，共 $(ls *.deb | wc -l) 个 deb 包" echo "如果存在 missing.txt，请打开查看哪些包没有下载到"这个脚本有几个关键点要说清楚。--recurse会把依赖一点点往外扩，比如 qgis 依赖 qgis-providers，qgis-providers 又依赖 libqgis-core，这样一层层展开，直到铺满整棵依赖树。--no-recommends是为了不把推荐包全拉下来，否则 deb 数量会膨胀近一半，很多推荐包装上根本用不到。sed 's/:.*//g'是去掉包名后面的:amd64这样的架构后缀，因为apt-cache depends输出时经常带这个后缀，直接作为包名传给apt-get download会报找不到包。
跑完脚本后，missing.txt里可能会有内容。不要慌，这里面有两种情况：一种是真的缺失，比如源里没有启用某个组件；另一种是虚拟包，本身没有独立 deb 文件，只有依赖它的包才会被安装。我的习惯是打开 missing.txt 逐个人工过一遍，用apt-cache policy 包名看看它是真实包还是虚拟包，再决定要不要补。比如python3-pyqt5这类元包，它确实没有自己的 deb 内容，可以忽略；如果libqt5gui5出现在里面，说明源有问题，需要检查软件源组件。
3.4 拷贝到目标机并执行 dpkg 安装
收集完成后，把整个~/qgis-debs目录拷到 U 盘或内网共享目录，然后到离线目标机上执行：
# 在离线银河麒麟目标机上执行 sudo mkdir -p /opt/qgis-debs sudo cp -a /mnt/usb/qgis-debs/* /opt/qgis-debs/ cd /opt/qgis-debs # 第一次安装：能装的先装，依赖未就绪的会处于半配置状态 sudo dpkg -i *.deb # 第二次执行：把上一轮没配完的包继续配置完成 sudo dpkg -i *.deb # 最后刷新共享库缓存 sudo ldconfigdpkg -i执行两遍不是玄学，而是因为这批 deb 之间的依赖顺序不一定符合一次安装的排列顺序。第一遍 dpkg 会把能装的都装上，那些因为依赖还没就绪而失败的包会处于“半配置”状态；第二遍执行时，它们依赖的包已经就绪，dpkg 会继续完成配置。如果两遍之后仍报缺少依赖，就对照 missing.txt 和报错信息回到联网机器补充下载，再拷回来重试。
ldconfig也不要省略。QGIS 运行时要读取大量共享库，比如 libqgis_core.so 和 libqgis_gui.so，如果系统没有刷新动态链接器缓存，启动时可能提示找不到共享库文件，但包明明已经装好。这一步花不了几秒钟，却能避免一个非常容易误判的启动故障。
另外要提醒的是，别在离线机器上用apt-get install ./qgis-*.deb代替 dpkg -i。apt-get 解析依赖时会尝试访问网络源，在内网环境里一旦连不上就报错中断，反而把 dpkg 可以直接完成的安装复杂化了。
4. 银河麒麟离线装 QGIS 的避坑手册：5 个常见问题的现象与排查
4.1 依赖总是不齐：Depends 之外还有 Recommends
现象：sudo dpkg -i *.deb执行后报了一堆depends on缺失提示，但打开目录看，相关的包明明也在里面。
原因：很多运行期需要的库在 deb 里是 Recommends（推荐）级别，不是 Depends（必需）级别。我给的收集脚本里特意用了--no-recommends，就是要把这部分包挡在门外，但这也带来一个副作用：QGIS 的某些功能模块运行时需要这些推荐库，缺了之后功能会静默失败甚至闪退。
解决：分两步走。第一步，先把qgis-providers、qgis-server-common、libqt5sql5-sqlite、python3-pyqt5.qtsvg、qt5-image-formats-plugins这几个常见运行辅助包手动加进收集列表；第二步，安装时如果还有缺失，直接把报错信息里的包名拿到联网机器上apt-get download补下，拷回来再装。宁可多带几个包，也别为省几百兆 U 盘空间在目标机上折腾一夜。
4.2 用错源导致版本不满足
现象：内网机器执行 dpkg 时提示Depends: libgdal.so.30，但系统里已经装了libgdal.so.29，或者提示某个库版本低于预期，dpkg 直接拒绝安装。
原因：这是典型的收集机源与目标机源不一致。收集机用的是 Ubuntu 源或 Debian 官方源，目标机的银河麒麟用的是自家仓库编译的库版本，两边对同一个库的 ABI 版本号对不上。只看包同名没有用，底层 C++ 库的版本一旦不一致，QGIS 运行时就可能加载了错误版本的符号。
解决：收集依赖之前，对比两台机器的/etc/os-release。如果目标机是麒麟 V10 SP1，收集机最好也是同版本麒麟，或者至少是版本接近的 Debian。如果手头只有 Ubuntu 机器，那就把麒麟官方源加到这台 Ubuntu 机器上，用麒麟源里的包版本去收集。这里没有捷径，版本不一致的问题后面几乎没得商量。
4.3 x86 和 ARM 架构混用
现象：dpkg 报错package architecture (amd64) does not match system (arm64)，或者反过来。
原因：把 U 盘里的 deb 包复制到目标机时没区分架构。银河麒麟跑在 Intel/AMD 和飞腾、鲲鹏上，同一系列系统的 CPU 架构完全不同。收集机是 x86 的，目标机是 ARM 的，包搬过去完全不能用。
解决：收集前先dpkg --print-architecture，确认两边一致。如果项目里既有 x86 机器又有 ARM 机器，我建议给 deb 目录命名时就带上架构，比如qgis-debs-amd64和qgis-debs-arm64，每台机器只复制对应架构的那一份。名字看着多此一举，但能防止维护时拿错包。
4.4 dpkg 中断导致后续安装报 “dpkg frontend is locked”
现象：安装过程中被 Ctrl+C 打断，再执行 dpkg 命令时提示dpkg: error: dpkg frontend is locked by another process，安装完全进行不下去。
原因：上次安装进程被打断后，dpkg 数据库里有残留的锁和未完成事务，新的 dpkg 进程检测到锁就拒绝执行。
解决：先确认没有残留的包管理进程，然后执行修复：
sudo fuser -v /var/lib/dpkg/lock-frontend sudo fuser -v /var/lib/dpkg/lock如果输出显示 PID，确认这些进程确实已经不是当前安装任务了，再执行sudo dpkg --configure -a把未配置的包修复完，然后重新运行sudo dpkg -i *.deb。注意不要一上来就把 lock 文件删掉，如果还有进程在写数据库，删锁只会把状态弄得更乱。这个坑我踩过一次之后，就养成了安装期间不轻易快捷键打断的习惯，也让项目组里的同事尽量不要在传输大 U 盘时中途拔盘。
4.5 Qt 平台插件缺失导致 QGIS 起不来
现象：所有依赖都装完了，执行qgis却直接退出，终端提示Failed to load platform plugin "xcb"，而且没有其他更明确的报错。
原因：QGIS 是 Qt 程序，启动时要加载 xcb 平台插件才能连接图形界面。这个插件不在 QGIS 的直接依赖里，属于运行时按需加载，dpkg 检查依赖时不会强制安装它。麒麟桌面版一般自带 Qt 基础环境，但如果你在一个精简的服务器版上装 QGIS，缺这个插件就很常见。
解决：用 Qt 的调试模式启动一次，看看它到底在找哪个文件：
QT_DEBUG_PLUGINS=1 qgis 2>&1 | head -n 30输出里会列出搜索路径和缺失项，通常补装qt5-qpa-plugins、libqt5gui5和相关的libxcb-*库就能解决。如果是在没有图形桌面的服务器上跑，还要确认有没有配置 X 转发或 Wayland 环境，否则补再多 Qt 插件也无法在纯命令行环境里启动 GUI。
5. 把 deb 目录变成内网 apt 软件源：一次配置反复部署
5.1 为什么多台机器部署时别再依赖 dpkg -i
dpkg -i 在单机部署时够用，但一旦目标机器多了，问题就很明显：安装顺序靠人工反复执行，缺了依赖要回到联网机器补包，每一台机器都要重复同样的手工过程。如果你要在一个项目组里部署七八台离线机器，用 dpkg 逐台装 QGIS 是很痛苦的。
把 deb 目录变成一个内网 apt 源之后，事情就简单了。目标机像在线环境一样执行apt-get install qgis，apt 会读取本地源里的依赖关系，自动决定安装顺序，缺什么它自己去源里找。本质上，我们只是把“软件源地址”从互联网换成了本机或内网的一个目录，剩下的工作交给 apt 自己完成。
5.2 在目标机上生成 Packages 索引
建源的核心动作是为 deb 目录生成一个 Packages 索引文件。这个索引记录了目录里有哪些包、版本是多少、依赖什么，apt 正是靠它识别一个目录是不是合格的软件源。命令如下：
sudo mkdir -p /opt/offline-repo sudo cp /opt/qgis-debs/*.deb /opt/offline-repo/ cd /opt/offline-repo # 生成索引，需要 dpkg-dev 提供 dpkg-scanpackages sudo dpkg-scanpackages ./ | gzip > Packages.gz ls -l Packages.gzdpkg-scanpackages来自 dpkg-dev 包，如果目标机没有装，可以在联网收集阶段把dpkg-dev也加入下载列表。更省事的办法是在联网机器上生成好 Packages.gz，随 deb 目录一起拷到目标机。这样目标机不需要装额外工具，只要目录里有 Packages.gz 就能被 apt 识别。
这里有个细节值得注意：dpkg-scanpackages 的输出会写到标准输出，直接重定向到 gzip 压缩成 Packages.gz，apt 读取源时会自动解压。如果目录里存在重复版本的同名包，可以加-m参数忽略重复，但在本文的流程里一般不会出现，因为收集脚本已经用 sort -u 去重过。
5.3 添加本地软件源并安装 QGIS
索引生成完毕后，在目标机上建立软源配置并执行安装：
echo "deb [trusted=yes] file:///opt/offline-repo ./" | sudo tee /etc/apt/sources.list.d/offline.list sudo apt-get update sudo apt-get install qgis这条配置里，[trusted=yes]是必须的，因为本地源没有 GPG 签名，不加这个选项，apt-get update 之后会把整个源标记为不可信并跳过，到时候 apt-get install 还是会报找不到 qgis。末尾的./是固定写法，它告诉 apt 到这个目录的根下去找 Packages 或 Packages.gz。
安装过程中如果提示缺少依赖，不要重复之前的坑，回到联网机器的收集目录里把缺的包补进/opt/offline-repo，重新执行dpkg-scanpackages和apt-get update，再执行一次apt-get install qgis即可。这套流程比 dpkg -i 更可维护，因为它把依赖解析交给 apt，不再依赖人工调整安装顺序。
5.4 多台机器复用和版本快照
本地源建好后，整个/opt/offline-repo目录就是一个完整的离线性源。要给新机器装 QGIS，只需要把这个目录原样复制过去，然后写入同样的源配置，执行apt-get update && apt-get install qgis，其他机器就能装出与第一台完全相同的环境。
我建议每次做完一轮离线交付，就把 deb 目录和 Packages.gz 打包成一个 tar 文件保存下来，命名时带上日期、架构和 QGIS 版本信息。下次无论是补装、重装还是给新机器部署，都不需要重新上网收集依赖。这个习惯坚持下来之后，项目的离线部署环境基本就成为了一套可复用的资产，不再依赖某个人临时去查命令。
6. 装完不能叫完成：验证 QGIS 可用性的几个实用动作
6.1 用 qgis --version 和 qgis_process 做命令级验证
安装全部走完，先做命令级验证。打开终端，执行qgis --version，能正常打印出版本信息，说明核心库加载成功，至少程序主体是可用的。如果这一步就提示找不到共享库，优先检查ldconfig是否执行过，再看缺的具体库名，补装对应 deb。
接着用qgis_process验证插件引擎。这个命令是 QGIS 自带的命令行处理工具，用来调用 QGIS 的算法。如果它在 PATH 里，直接执行qgis_process plugins或qgis_process --help，能列出插件或帮助信息，说明 Python 环境和插件系统基本正常。如果命令不在 PATH，可以用find /usr -name qgis_process找到它的位置再执行。
这一步的价值在于，它能快速暴露出“安装成功但运行库有缺陷”的问题，不需要打开图形界面试错。命令行环境通常比 GUI 更早暴露问题，也更容易定位原因。
6.2 用真实数据跑一次空间处理，再打交付快照
命令级验证通过之后，我还会用一份真实的小数据做一次空间处理测试。随便准备一个本地的 GeoJSON 或 Shapefile，启动 QGIS，加载图层，执行一次裁剪或投影转换，导出结果文件。如果能顺利走完“加载 → 处理 → 导出”，说明 GDAL、PROJ 这些底层空间库都工作正常，QGIS 的制图和空间分析链路没有大问题。
这一步不能省。以前在某项目组帮同事排查一台离线机器，所有命令测试都通过了，但一打开矢量图层就闪退，最后发现是libgdal的某一个小版本补丁缺失导致驱动加载失败。用真实数据跑一遍，相当于把那些在命令层测不到的动态加载路径也验证了。
最后把离线源目录、源配置、验证命令和这一次用的 deb 清单写进部署说明，标记好架构和系统版本。这样下个月再来一台新机器，不需要重新想流程，直接把备份目录复制过去，跑一遍 apt 命令就能交差。我现在每次交付前都会先在隔离的虚拟机上完整装一遍，确认验证通过后才去动真机。这套流程走下来，离线环境里“装不上”、“起不来”的意外已经很少碰见了。希望帮到你。
本文还有配套的精品资源，点击获取
