# 离线安装
> 在没有互联网访问的环境中，使用离线安装包安装 Pigsty
---
LLMS index: [llms.txt](/llms.txt)
---
Pigsty 默认从互联网上游 [**安装**](/docs/setup/install/) 所需软件包，但有些环境与互联网隔离。
为了解决这个问题，Pigsty 支持使用 [**离线软件包**](#离线软件包) 进行离线安装。
您可以将其视作 Linux- 原生版本的 Docker 镜像。
----------------
## 概览
**离线软件包** 打包了所有需要的 RPM/DEB 软件包及其依赖；它是常规 [**安装**](/docs/setup/install/) 后的本地 APT / YUM 仓库的快照。
在 [**严肃的生产环境部署**](/docs/deploy) 中，我们 **强烈推荐** 您使用离线安装包进行安装。
它可以确保后续所有新节点的软件版本与现有环境保持一致，
并且可以避免上游变动导致的在线安装失败（相当常见！）
确保您能独立自主运行它至地老天荒。
使用离线软件包的优点
- 可以简单方便的在互联网隔离的环境中交付实施。
- 一次性预下载所有软件包，可以有效加速安装过程。
- 无需担心上游依赖项的变动导致依赖错漏/安装失败。
- 如果有多个节点，那么所有软件包只需要下载一次，节省带宽资源。
- 可以通过本地仓库确保所有节点的软件版本一致，实行统一版本管理
使用离线软件包的缺点
- 离线安装包针对 **特定的操作系统小版本制作**，通常不能跨版本使用
- 仅为制作时刻的快照，可能不包含最新的更新和操作系统安全补丁。
- 离线安装包通常约 1GB 左右，而在线安装则是按需下载，更节省空间。
离线软件包是为特定的 Linux 操作系统小版本制作的
当操作系统小版本不匹配时，有概率能用，也有概率失败，我们建议你不要冒险尝试。
请务必注意，上表 `v4.4.0` 历史制品中的 EL9/EL10 安装包基于 9.7 / 10.1 制作，Debian 安装包基于 12.14 / 13.6 制作，Ubuntu 安装包基于 22.04.5 / 24.04.4 / 26.04.0 制作。
跨操作系统小版本可能因 OpenSSL 或系统库版本变化导致安装失败。您需要在安装相同操作系统的环境中执行在线安装后制作离线安装包，或联系我们定制离线软件包。
demo/install-offline.cast
> [!WARNING]
> 如果你在离线安装时遇到 "No package nginx available" 之类的错误，通常说明之前有过失败的安装尝试。删除 `/www/pigsty` 目录后重新执行部署即可。
如果您想要在自己的配置中，使用已经解包配置好的离线软件包，请修改并确保以下配置项：
- [**`repo_enabled`**](/docs/infra/param#repo_enabled)：将此参数打开，设置为 **`true`**，则会构建本地软件源（在大部份配置中被显式关闭）
- [**`node_repo_modules`**](/docs/node/param#node_repo_modules)：将此参数设置为 **`local`**，则环境中所有节点都从本地软件仓库安装
- 在大部份模板中，此参数被显式配置为：`node,infra,pgsql`，即直接从这些上游软件仓库安装。
- 将其设置为 `local`，则会使用本地软件仓库安装所有软件包，速度最快，没有其他仓库的变数干扰。
- 如果你想同时使用本地软件仓库和上游软件仓库，可以将其设置为 `local,node,infra,pgsql`
第一个参数如果打开，Pigsty 会创建 **本地软件仓库**，第二个参数如果包含 `local`，则环境中的所有节点会使用这个本地软件仓库。
如果只包含 `local`，那么它会成为所有节点的唯一软件源，如果你还想要从其他上游软件仓库继续安装其他软件包，可以将其他仓库模块名称也添加进去，例如 `local,node,infra,pgsql`。
**混合安装模式**
如果您的环境有互联网访问，那么有一种混合方法可以融合离线安装与在线安装的优点。
您可以使用离线软件包作为基础，并在线补足不匹配的增量软件包。
以 `v4.4.0` 历史制品为例，假设您使用的是 RockyLinux 9.6，但该离线软件包是为 RockyLinux 9.7 制作的。
您可以使用 `el9` 离线软件包（虽然是针对 9.7 制作的），然后在执行正式安装前，执行 `make repo-build` 重新下载 9.6 对应的缺失软件包，
Pigsty 将从上游仓库重新下载所需的 **增量**。
-------
## 制作离线软件包
如果您选择的操作系统不在默认列表中，您可以使用内置的 [**`cache.yml`**](https://github.com/pgsty/pigsty/blob/main/cache.yml) 剧本制作自己的离线软件包：
1. 找到一台运行完全相同操作系统版本，且可以访问互联网的节点
2. 使用 [**`rich`**](/docs/conf/rich) 配置模板执行 [**在线安装**](/docs/setup/install/)（`./configure -c rich`），并确认目标 Infra 节点的 `/www/pigsty` 本地仓库已经生成；若尚未生成，可先对该节点执行 `./infra.yml -t repo`
3. `cd ~/pigsty; ./cache.yml -l `：明确选择一个已经具备本地仓库的 Infra 节点，制作并取回离线软件包
4. 默认制品位于 `~/pigsty/dist/${version}/pigsty-pkg-${version}.${os}.${arch}.tgz`；将它复制到离线环境（ftp、scp、usb 等），再通过 `bootstrap` 解包使用
`cache.yml` 的当前默认值如下，可使用额外变量覆盖：
| 参数 | 默认值 | 说明 |
|:-----------------|:------------------------------------------|:-----------------------|
| `cache_pkg_name` | `pigsty-pkg-${version}.${os}.${arch}.tgz` | 离线包文件名模板 |
| `cache_pkg_dir` | `dist/${version}` | 管理节点上的输出目录 |
| `cache_repo` | `pigsty` | 从目标节点打包的本地仓库；多个仓库用逗号分隔 |
我们提供 [**付费服务**](/docs/about/service/)，提供经过测试的预制 Linux 主版本。次版本制作离线软件包（**¥200**）。
----------------
## Bootstrap
Pigsty 依赖 ansible 执行剧本，这个脚本负责用各种方式来确保 ansible 正确安装。
```bash
./bootstrap # 确保 ansible 正确安装（如果有离线包，优先使用离线安装并解包使用）
```
通常在两种情况下，你需要运行这个脚本：
- 你不是通过 [**安装脚本**](/docs/setup/install#安装) 来安装 Pigsty 的，而是通过下载，`git clone` 源码包的方式安装的，因此没有安装 ansible。
- 你准备通过离线软件包来安装 Pigsty，需要使用这个脚本来从离线软件包中安装 ansible。
`bootstrap` 脚本将自动检测离线软件包是否存在（`-p` 指定，默认为 `/tmp/pkg.tgz`）。
如果存在则解压使用它，然后从里面安装 ansible。
如果离线包不存在，它会尝试从互联网安装 ansible。如果还是不行，那你就要自己想办法了！
我的 yum/apt 仓库文件跑到哪里去了？
引导程序默认会 **移走** 现有软件源配置，以确保只有所需的仓库被启用。
您可以在 `/etc/yum.repos.d/backup` (EL) 或 `/etc/apt/backup` (Debian / Ubuntu) 中找回它们。
如果您想在 `bootstrap` 过程中保留现有软件源配置，请使用 `-k|--keep` 参数。
```bash
./bootstrap -k # 或 --keep
```