银河麒麟离线APT环境搭建

适用范围：本文面向本人拥有或已获明确授权的银河麒麟系统，适用于基于 Debian/Ubuntu 软件包体系、使用 APT 的版本。银河麒麟不同产品线、系统版本、CPU 架构和软件源命名可能不同，操作前必须以 cat /etc/os-release、dpkg --print-architecture 和对应版本官方文档为准。

安全提醒：离线不等于可信。软件包、仓库元数据和移动介质仍可能被篡改。应优先使用银河麒麟官方或单位批准的软件源，保留签名与校验信息，不应把关闭签名验证或 [trusted=yes] 作为常规做法。

阅读说明：命令中的软件包名、目录、主机地址和发行版代号均为示例，必须替换为现场实际值。代码块中的 # 为用途注释，可以逐行执行命令，不要把示例提示符一起输入。

一、先确认系统与使用场景

离线 APT 的难点不只是“下载一个 .deb 文件”，而是同时满足软件包版本、依赖关系、CPU 架构和系统软件源的一致性。准备资源前，先在目标银河麒麟主机执行：

# 查看银河麒麟产品、版本及其基础发行版信息。
cat /etc/os-release

# 查看 APT 使用的软件包架构，例如 amd64 或 arm64。
dpkg --print-architecture

# 查看内核识别的硬件架构，例如 x86_64 或 aarch64。
uname -m

# 记录当前已启用的软件源，便于在联网准备机上匹配。
grep -RhsE '^[[:space:]]*deb([[:space:]]|$)' \
  /etc/apt/sources.list /etc/apt/sources.list.d/*.list 2>/dev/null

这里的 \ 表示同一条命令在下一行继续，不是两条命令。

根据规模选择方案：

需求	推荐方案	特点
临时安装少量软件	下载软件包及依赖	准备快，但后续维护较繁琐
单台或少量主机定期更新	apt-offline	可由目标机生成准确的下载清单
多台主机长期处于隔离网	局域网本地 APT 源	初期准备较多，后续安装和版本管理更方便

无论使用哪种方案，联网准备机都应尽量与离线目标机保持相同的银河麒麟版本、APT 软件源和软件包架构。仅仅“都是 Linux”并不能保证软件包兼容。

二、准备可信的传输与回退条件

开始前应准备：

1. 一台能够访问批准软件源的联网主机或虚拟机。
2. 经单位允许使用的移动介质或受控摆渡方式。
3. 足够的存储空间。
4. 目标系统的重要数据和 APT 配置备份。
5. 软件包来源、下载时间、操作者和校验值记录。

在目标机备份 APT 配置：

# 创建本次操作的备份目录。
sudo mkdir -p /root/apt-backup

# 备份主软件源配置；文件不存在时跳过。
sudo cp -a /etc/apt/sources.list /root/apt-backup/ 2>/dev/null || true

# 备份分目录保存的软件源配置。
sudo cp -a /etc/apt/sources.list.d /root/apt-backup/

# 导出当前已安装软件包及版本，便于审计和回退分析。
dpkg-query -W -f='${binary:Package}\t${Version}\n' \
  | sudo tee /root/apt-backup/installed-packages.tsv >/dev/null

不要在尚未验证离线源可用时删除原有软件源。若必须避免 APT 尝试访问外网，可以临时禁用对应的 .list 或 .sources 文件，并保留可恢复的备份。

三、方案一：临时下载软件包及依赖

该方案适合安装数量少、目标明确的软件。最稳妥的做法是在与目标机版本和架构一致的联网环境中，让 APT 解析依赖并只下载不安装。

3.1 在联网准备机下载

# 刷新联网准备机的软件包索引。
sudo apt-get update

# 创建独立下载目录，避免与系统缓存中的旧包混在一起。
mkdir -p ~/kylin-offline-packages

# 进入下载目录。
cd ~/kylin-offline-packages

# 只下载目标软件及APT判定需要安装的依赖，不在准备机安装。
# 将 <package-name> 替换为实际软件包名。
sudo apt-get install --download-only --reinstall \
  -o Dir::Cache::archives="$PWD" <package-name>

如果准备机已经安装了某些依赖，APT 可能不会重新下载它们。因此，条件允许时应使用与目标机状态一致的干净虚拟机或容器；也可以根据现场情况使用 --reinstall，但仍需核对下载清单是否完整。

单独使用 apt-get download <package-name> 通常只下载指定软件包，不会自动取得完整依赖，因此不宜把它当成完整的离线依赖解决方案。

3.2 生成校验清单并传输

# 在联网准备机上为全部 DEB 包生成 SHA-256 校验清单。
sha256sum ./*.deb > SHA256SUMS

# 查看下载到的包、版本和架构。
for file in ./*.deb; do
  dpkg-deb -f "$file" Package Version Architecture
done

把整个目录通过批准的方式传入离线环境。在目标机安装前先验证：

# 进入摆渡进来的软件包目录。
cd /path/to/kylin-offline-packages

# 验证文件与联网准备机生成的校验清单一致。
sha256sum -c SHA256SUMS

3.3 在离线目标机安装

# 使用 APT 安装目录中的本地 DEB 包，使 APT 按依赖关系处理。
sudo apt install ./*.deb

# 检查是否存在未配置完成或依赖异常的软件包。
sudo dpkg --audit

# 查看目标软件包的安装状态和版本。
dpkg-query -W -f='${Status}\t${Package}\t${Version}\n' <package-name>

如果 APT 报告仍缺少依赖，不要使用强制忽略依赖的参数继续安装。应记录缺失包名和版本，在联网准备机补齐后重新传输。

四、方案二：使用 apt-offline

apt-offline 可以在离线目标机生成请求文件，再由联网主机按请求下载软件包和索引，适合少量主机的定期维护。

4.1 准备 apt-offline

先检查目标系统的软件源是否提供该工具：

# 查询软件源中是否存在 apt-offline 及其候选版本。
apt-cache policy apt-offline

若离线目标机尚未安装 apt-offline，需要先从与目标机匹配的可信软件源下载 apt-offline 及其依赖，再按上一章的方法离线安装。不要照搬固定版本号，仓库中的实际版本可能不同。

4.2 在离线目标机生成请求

# 为更新软件包索引生成请求文件。
sudo apt-offline set update.sig --update

# 为安装指定软件生成请求文件。
# 可在 --install-packages 后列出一个或多个实际软件包名。
sudo apt-offline set install.sig \
  --install-packages <package-name>

# 同时请求更新索引和安装软件。
sudo apt-offline set full.sig --update \
  --install-packages <package-name>

这里的 \ 表示同一条命令续行。生成请求前，目标机必须已经配置正确、与自身版本相匹配的软件源地址；即使目标机当前不能联网，这些地址仍用于描述需要从哪些仓库取得数据。

4.3 在联网主机下载资源

联网主机也需安装 apt-offline：

# 刷新软件包索引。
sudo apt-get update

# 安装 apt-offline。
sudo apt-get install apt-offline

# 按目标机生成的请求下载资源并打包。
apt-offline get full.sig --bundle offline-bundle.zip

# 为下载包生成额外的传输校验值。
sha256sum offline-bundle.zip > offline-bundle.zip.sha256

把 offline-bundle.zip 和校验文件传回目标机。

4.4 在离线目标机导入

# 验证摆渡文件在传输过程中没有变化。
sha256sum -c offline-bundle.zip.sha256

# 将下载的软件包和索引导入目标机的 APT 环境。
sudo apt-offline install offline-bundle.zip

# 根据实际目的执行安装；软件包名必须与请求阶段一致。
sudo apt install <package-name>

apt-offline 的具体参数会随版本变化。执行前应使用 apt-offline --help、apt-offline set --help、apt-offline get --help 和 apt-offline install --help 核对当前版本支持的选项。

五、方案三：搭建局域网本地 APT 源

该方案适合隔离网内有多台同版本、同架构银河麒麟主机的场景。下面使用“平铺式仓库”演示最小可用结构，它比完整的 Debian 归档目录简单，适合单位内部维护一组经过审批的软件包。

5.1 准备仓库服务器

仓库服务器需要预先安装 dpkg-dev，由联网准备环境取得该工具及目标软件包后，再一并传入隔离网。

# 安装生成 Packages 索引所需的工具。
sudo apt install dpkg-dev

# 创建本地仓库目录。
sudo mkdir -p /srv/kylin-repo/packages

# 把经过审核的 DEB 包复制到仓库目录。
sudo cp /path/to/approved-debs/*.deb /srv/kylin-repo/packages/

# 进入仓库根目录，以便索引中的 Filename 使用相对路径。
cd /srv/kylin-repo

# 扫描 DEB 包并生成压缩的 Packages 索引。
sudo sh -c \
  'dpkg-scanpackages packages /dev/null | gzip -9c > packages/Packages.gz'

这里的 \ 表示同一条命令续行。每次增加、替换或删除 .deb 文件后，都要重新生成 Packages.gz。

5.2 先用 file 源验证单机仓库

如果仓库目录就在目标机本地，可以创建独立配置文件：

# 写入本地 file 源；平铺式仓库的发行版字段使用 ./。
echo 'deb [trusted=yes] file:/srv/kylin-repo/packages ./' \
  | sudo tee /etc/apt/sources.list.d/kylin-offline.list

# 读取本地仓库索引。
sudo apt-get update

[trusted=yes] 会让 APT 无条件信任该源，降低认证保护。这里只用于说明尚未签名的最小验证环境，且仅限受控测试。正式环境应为仓库生成并签署 Release/InRelease 元数据，在客户端导入专用公钥，并使用 signed-by= 限定信任范围；不应长期保留 [trusted=yes]。

5.3 通过 HTTP 向隔离网客户端提供服务

可使用单位现有、已批准的 Web 服务发布 /srv/kylin-repo。以 Nginx 为例，站点应把 /repo/ 映射到 /srv/kylin-repo/packages/。完成服务端配置后，客户端添加：

# 添加隔离网仓库地址；替换为实际仓库服务器地址。
echo 'deb [trusted=yes] http://192.0.2.10/repo ./' \
  | sudo tee /etc/apt/sources.list.d/kylin-offline.list

# 更新索引并观察是否只访问预期的内网仓库。
sudo apt-get update

# 查看某个软件包是否已从本地源获得候选版本。
apt-cache policy <package-name>

# 从本地源安装软件。
sudo apt install <package-name>

示例使用文档保留地址 192.0.2.10，不能直接用于生产网络。正式部署还应限制仓库访问范围、保留访问日志，并按单位安全要求启用 HTTPS 或其他传输保护。

5.4 正式环境的签名原则

生产或长期使用的仓库应至少做到：

1. 使用专用仓库签名密钥，不复用个人日常密钥。
2. 离线保管私钥，限制签名操作权限。
3. 生成包含哈希值的 Release 文件，并创建 InRelease 或 Release.gpg。
4. 客户端把仓库公钥保存到单独的 keyring 文件。
5. 软件源通过 signed-by=/path/to/keyring.gpg 只信任指定密钥。
6. 密钥轮换、软件包审批和仓库变更均应留痕。

完整的 dists/、pool/ 仓库结构和签名流程与发行版代号、组件、架构及所用仓库工具有关。应根据当前银河麒麟版本选用 apt-ftparchive、reprepro 或其他经过批准的工具，不应把其他 Debian/Ubuntu 版本的仓库配置直接套用到银河麒麟。

六、验证离线环境

部署完成后，不要只以“命令没有报错”判断成功。至少检查以下项目：

# 检查 APT 配置语法和软件源更新结果。
sudo apt-get update

# 查看目标软件包的来源、候选版本和已安装版本。
apt-cache policy <package-name>

# 模拟安装，不实际修改系统。
sudo apt-get install --simulate <package-name>

# 检查 dpkg 数据库中是否有未完成的配置。
sudo dpkg --audit

# 检查指定软件包的文件校验结果；无输出通常表示未发现变化。
sudo dpkg --verify <package-name>

同时确认：

• APT 没有尝试连接未经批准的外网地址。
• 下载或导入的软件包架构与目标机一致。
• 软件包来源和版本符合单位基线。
• 服务能够正常启动，配置文件和数据未被意外覆盖。
• 回退所需的软件包、配置备份和操作记录完整。

七、常见问题

7.1 Unable to locate package

通常表示索引没有更新、软件源配置不匹配、仓库中没有该包，或包名错误。先执行 apt-cache policy 和 apt-cache search，再检查 apt-get update 的完整输出。

7.2 Depends: ... but it is not installable

说明依赖包缺失、版本不匹配或仓库组件不完整。应在联网准备机补齐与目标系统匹配的依赖，不要使用 dpkg --force-depends 绕过。

7.3 package architecture ... does not match system

说明软件包架构不兼容。重新核对 dpkg --print-architecture 和 .deb 文件的 Architecture 字段。除非有明确的多架构需求和官方支持，不要随意执行 dpkg --add-architecture。

7.4 签名或哈希校验失败

先停止安装并重新核对来源、时间、传输介质和校验文件。不要通过关闭认证、跳过哈希验证或允许不安全仓库来消除报错。

7.5 仓库新增软件后客户端仍看不到

仓库端需要重新生成 Packages.gz，客户端再执行 apt-get update。还要检查 Web 服务是否提供了最新索引，以及代理或缓存是否仍返回旧文件。

八、方案选择建议

• 只安装一次、软件很少：使用“下载软件包及依赖”方案。
• 目标机状态复杂，需要由目标机精确提出更新需求：使用 apt-offline。
• 多台主机长期维护：建设带签名、审批和版本控制的局域网 APT 源。
• 关键生产系统：先在同版本测试环境验证，再按变更流程分批实施。

离线 APT 环境的关键不是简单绕过联网限制，而是把“可信来源、版本匹配、依赖完整、传输校验、可审计和可回退”做成固定流程。这样搭建出的离线软件管理环境才适合长期运维。