# 离线安装
> 如何在没有互联网访问的环境中安装 Pigsty？以及如何制作离线软件安装包。
---
Pigsty 的 [**标准安装**](/zh/docs/setup/install) 流程需要访问互联网，然而生产环境的数据库服务器通常是与互联网隔离的。
因此 Pigsty 提供了离线安装的功能，允许您在没有互联网访问的环境中，同样完成安装与部署。
如果您有互联网访问，提前下载好预制的 [**离线软件包**](#离线软件包) 也可以帮助您加速安装的过程，并增强安装过程的确定性与可靠性。
----------------
## 简短版本
在执行 [**标准安装**](/zh/docs/setup/install#安装) 前，首先下载好 Pigsty 软件包与 [**离线软件包**](#离线软件包) 。
| 软件包下载地址 | CDN（中国大陆） | GitHub Release |
|--------------------|:------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------|
| Pigsty 源码包 | [pigsty-v2.7.0.tgz](https://get.pigsty.cc/v2.7.0/pigsty-v2.7.0.tgz) | [pigsty-v2.7.0.tgz](https://github.com/Vonng/pigsty/releases/download/v2.7.0/pigsty-v2.7.0.tgz) |
| EL8 兼容 离线软件包 | [pigsty-pkg-v2.7.0.el8.x86_64.tgz](https://get.pigsty.cc/v2.7.0/pigsty-pkg-v2.7.0.el8.x86_64.tgz) | [pigsty-pkg-v2.7.0.el8.x86_64.tgz](https://github.com/Vonng/pigsty/releases/download/v2.7.0/pigsty-pkg-v2.7.0.el8.x86_64.tgz) |
| Debian 12 离线软件包 | [pigsty-pkg-v2.7.0.debian12.x86_64.tgz](https://get.pigsty.cc/v2.7.0/pigsty-pkg-v2.7.0.debian12.x86_64.tgz) | [pigsty-pkg-v2.7.0.debian12.x86_64.tgz](https://github.com/Vonng/pigsty/releases/download/v2.7.0/pigsty-pkg-v2.7.0.debian12.x86_64.tgz) |
| Ubuntu 22.04 离线软件包 | [pigsty-pkg-v2.7.0.ubuntu22.x86_64.tgz](https://get.pigsty.cc/v2.7.0/pigsty-pkg-v2.7.0.ubuntu22.x86_64.tgz) | [pigsty-pkg-v2.7.0.ubuntu22.x86_64.tgz](https://github.com/Vonng/pigsty/releases/download/v2.7.0/pigsty-pkg-v2.7.0.ubuntu22.x86_64.tgz) |
您也可以使用 `curl` 通过命令行下载：
```bash
VERSION=v2.7.0 # Pigsty 版本号
DISTRO=el8 # 离线包系统版本可选值：el8, debian12, ubuntu22
curl "https://get.pigsty.cc/${VERSION}/pigsty-${VERSION}.tgz" -o ~/pigsty.tgz # 软件包，通常放置于 ~/pigsty.tgz
curl "https://get.pigsty.cc/${VERSION}/pigsty-pkg-${VERSION}.${DISTRO}.x86_64.tgz" -o /tmp/pkg.tgz # 离线包，默认放置于 /tmp/pkg.tgz
```
上传 Pigsty 软件包与离线软件包至管理节点，将离线包放置于 `/tmp/pkg.tgz`，然后通过 [**`bootstrap`**](#bootstrap) 过程启用。
```bash
./bootstrap # 变体：如果本机有互联网访问，使用 ./bootstrap -y 可自动下载对应系统的离线软件包
# 继续后面的配置与安装任务
./configure # 执行环境检测，并生成相应的推荐配置文件，如果你知道如何配置 Pigsty 可以跳过
./install.yml # 根据生成的配置文件开始在当前节点上执行安装，使用离线安装包大概需要10分钟完成
```
提示：如果您的节点带有互联网访问， [**`bootstrap`**](#bootstrap) 的过程中会询问是否下载离线软件包，回复 `y` 即可自动下载。
----------------
## 离线安装基本原理
Pigsty 会在安装过程中从互联网上游的 yum/apt 软件仓库，下载所需的 rpm/deb 包并构建一个本地软件源（默认位于 `/www/pigsty`）。
本地软件源由 Nginx 对外提供服务，后续无论是本机还是其他节点，都默认会使用本地软件源进行安装，而不再需要访问互联网。
使用本地软件源有三个主要好处：
1. 本地软件源可以避免重复的下载请求与流量消耗，显著加速安装速度并提高安装过程的可靠性。
2. 构建本地软件源会对当前可用软件版本取快照，确保部署环境内节点所安装软件版本的一致性。
3. 构建好的本地软件源可以整体打包，复制到安装有相同操作系统的隔离环境中用于**离线安装**。
离线安装的原理是：首先在一台具有相同操作系统，且有互联网访问的节点上，完成 [**标准安装**](/zh/docs/setup/install) 流程。
然后对构建好的本地软件源（默认位于 `/www/pigsty` ）取快照并打包，[**制作**](#制作离线软件包) 成为 [**离线软件包**](#离线软件包)，供安装有同样操作系统的生产环境网络隔离节点使用。
当 Pigsty 执行 [**安装**](/zh/docs/setup/install/#安装) 时，如果发现本地软件源已经存在，就会进入离线安装模式。
在此模式下，Pigsty 将跳过从互联网下载并构建本地软件源的过程，使用本地软件源完成整个安装过程，期间无需互联网访问。
**进入离线安装模式的判定标准**
判定本地软件源存在的标准是：默认位于 `/www/pigsty/repo_complete` 的标记文件存在。
这个标记文件会在标准安装过程中，下载完成后自动生成，说明这是一个可用的本地软件源。
删除本地软件源的 `repo_complete` 标记文件后，安装时将重新从上游下载 **缺失的** 软件包。
----------------
## 离线软件包
离线软件包是一个使用 `gzip` 与 `tar` 制作的标准 Tarball，以 `.tgz` 后缀结尾。通常放置于 `/tmp/pkg.tgz` 路径，并解压至 `/www/pigsty` 使用。
Pigsty 为 [**首要支持**](/zh/docs/reference/compatibility) 的三大操作系统发行版提供了预制离线软件包。如果您使用相同的操作系统版本，可以开箱即用。
**离线软件包**
**GitHub下载地址**
https://github.com/Vonng/pigsty/releases/download/v2.7.0/pigsty-pkg-v2.7.0.el8.x86_64.tgz # EL 8.9 (Green Obsidian)
https://github.com/Vonng/pigsty/releases/download/v2.7.0/pigsty-pkg-v2.7.0.debian12.x86_64.tgz # Debian 12 (bookworm)
https://github.com/Vonng/pigsty/releases/download/v2.7.0/pigsty-pkg-v2.7.0.ubuntu22.x86_64.tgz # Ubuntu 22.04 (jammy)
**中国大陆下载地址**
https://get.pigsty.cc/v2.7.0/pigsty-pkg-v2.7.0.el8.x86_64.tgz # EL 8.9 (Green Obsidian)
https://get.pigsty.cc/v2.7.0/pigsty-pkg-v2.7.0.debian12.x86_64.tgz # Debian 12 (bookworm)
https://get.pigsty.cc/v2.7.0/pigsty-pkg-v2.7.0.ubuntu22.x86_64.tgz # Ubuntu 22.04 (jammy)
**离线软件包的适用系统版本**
使用离线软件包安装时，请务必确保 OS 大版本精确匹配，尽可能确保系统小版本一致或尽可能接近。
OS 小版本不匹配的情况下通常也可以成功进行离线安装，但有概率出现部分软件包 **依赖缺失或冲突**。
这种情况请使用安装了相同小版本的系统预先 [**制作离线软件包**](#制作离线软件包) 进行离线安装，或参考 [**常见问题**](/zh/docs/setup/faq/) 解决。
----------------
## Bootstrap
Ansible 是 Pigsty 的核心依赖，离线安装首先需要解决如何在没有互联网访问或本地源的情况下，离线安装 Ansible 的问题。
Pigsty 的离线软件包中默认已经包含了 `ansible` 及其依赖，从离线软件包中提取并安装 `ansible` 的这一过程，称为 **Bootstrap**。
首先将离线软件包拷贝至生产环境管理节点上，并放置于 `/tmp/pkg.tgz` 路径下备用，然后执行 `bootstrap` 命令即可：
```bash
./bootstrap # 解压 /tmp/pkg.tgz，创建并启用本地软件源，然后从中安装 Ansible
```
[**`bootstrap`**](#bootstrap) 脚本会帮助您自动解压位于 `/tmp/pkg.tgz` 的离线软件包，向节点添加并启用本地源，并安装 Ansible 及其依赖。
如果您的环境有互联网访问，并且当前操作系统有可用的离线软件包。那么 `bootstrap` 还会在离线软件包不存在时，询问你是否要下载。
Bootstrap 过程的逻辑
1. 检查安装的前提条件是否满足（操作系统，芯片架构，内核）
2. 检查本地离线安装包（`/tmp/pkg.tgz`）是否存在？
* 是 -> 解压到 `/www/pigsty` 并配置本地FS软件源启用它。
* 否 -> 进一步决定是否从互联网下载离线软件包？（前提是对应操作系统的离线软件包存在！）
* 是 -> 从 GitHub 或 CDN 下载离线软件包并解压
* 否 -> 是否添加操作系统基础的上游源地址以供从互联网下载 ?
* 是 -> 根据地区与操作系统版本写入对应的上游源：`/etc/yum.repos.d/` 或 `/etc/apt/source.list.d`
* 否 -> 用户自己搞定，或者当前系统的默认配置就带有 Ansible
* 现在，我们有了一个可用的本地软件源，可用来安装 Pigsty 所需的软件包，特别是 Ansible。
* 优先级顺序: 本地的 `pkg.tgz` > 下载的 `pkg.tgz` > 原始上游 > 默认配置
3. 从上一步配置的软件源中，安装一些基本的重要软件，不同版本的软件略有不同：
* EL 8/9: `ansible python3-jmespath python3.11-jmespath python3-cryptography createrepo_c unzip wget dnf-utils sshpass modulemd-tools`
* ubuntu/debian: `ansible python3-jmespath dpkg-dev unzip wget sshpass acl`
4. 检查 `ansible` 是否成功安装。
例：有互联网访问，在 Bootstrap 过程中下载离线软件包（EL8）
在一台安装了 RockyLinux 8.9 ，有互联网访问的节点上，因为该操作系统（Rocky 8.9）提供了官方的离线软件包，所以在 ./bootstrap 过程中，
如果没有检测到可用的 `/www/pigsty` 本地软件源，或 `/tmp/pkg.tgz` 离线软件包，就会询问用户是否下载离线软件包，回复 `y` 即可。
当然您也可以直接使用 `bootstrap -y` 直接默认回复 “yes”。
```bash
[vagrant@build-el8 pigsty]$ ./bootstrap
bootstrap pigsty v2.7.0 begin
[ OK ] region = china
[ OK ] kernel = Linux
[ OK ] machine = x86_64
[ OK ] package = rpm,dnf
[ OK ] vendor = rocky (Rocky Linux)
[ OK ] version = 8 (8.9)
[ OK ] sudo = vagrant ok
[ OK ] EL 8.9 has pre-packed offline package available:
https://get.pigsty.cc/v2.7.0/pigsty-pkg-v2.7.0.el8.x86_64.tgz
[ IN ] offline package not exist on /tmp/pkg.tgz, download? (y/n):
=> y
[ OK ] $ curl https://get.pigsty.cc/v2.7.0/pigsty-pkg-v2.7.0.el8.x86_64.tgz -o /tmp/pkg.tgz
... (下载进度提示)
[ OK ] repo = extract from /tmp/pkg.tgz
[ OK ] repo file = use /etc/yum.repos.d/pigsty-local.repo
[WARN] rpm cache = updating, make take a while
[ OK ] repo cache = created
[ OK ] install el8 utils
...(yum install output)
Installed:
createrepo_c-0.17.7-6.el8.x86_64 createrepo_c-libs-0.17.7-6.el8.x86_64 drpm-0.4.1-3.el8.x86_64 modulemd-tools-0.7-8.el8.noarch python3-createrepo_c-0.17.7-6.el8.x86_64 python3-libmodulemd-2.13.0-1.el8.x86_64
python3-pyyaml-3.12-12.el8.x86_64 sshpass-1.09-4.el8.x86_64 unzip-6.0-46.el8.x86_64
...(yum install output) 18/18
Installed:
ansible-8.3.0-1.el8.noarch ansible-core-2.15.3-1.el8.x86_64 git-core-2.39.3-1.el8_8.x86_64 mpdecimal-2.5.1-3.el8.x86_64
python3-cffi-1.11.5-6.el8.x86_64 python3-cryptography-3.2.1-7.el8_9.x86_64 python3-jmespath-0.9.0-11.el8.noarch python3-pycparser-2.14-14.el8.noarch
python3.11-3.11.5-1.el8_9.x86_64 python3.11-cffi-1.15.1-1.el8.x86_64 python3.11-cryptography-37.0.2-5.el8.x86_64 python3.11-jmespath-1.0.1-1.el8.noarch
python3.11-libs-3.11.5-1.el8_9.x86_64 python3.11-pip-wheel-22.3.1-4.el8_9.1.noarch python3.11-ply-3.11-1.el8.noarch python3.11-pycparser-2.20-1.el8.noarch
python3.11-pyyaml-6.0-1.el8.x86_64 python3.11-setuptools-wheel-65.5.1-2.el8.noarch
Complete!
[ OK ] ansible = ansible [core 2.15.3]
[ OK ] boostrap pigsty complete
proceed with ./configure
```
例：无互联网访问，下载好离线包并从本地 bootstrap （Debian 12）
在一台互联网隔离的 Debian 12 节点上，用户已经提前下载好离线软件包，并上传至该节点的指定路径下。
如果离线软件包存在于 `/tmp/pkg.tgz`， bootstrap 会直接使用它，输出结果为：
```bash
vagrant@debian12:~/pigsty$ ./bootstrap
bootstrap pigsty v2.7.0 begin
[ OK ] region = china
[ OK ] kernel = Linux
[ OK ] machine = x86_64
[ OK ] package = deb,apt
[ OK ] vendor = debian (Debian GNU/Linux)
[ OK ] version = 12 (12)
[ OK ] sudo = vagrant ok
[ OK ] cache = /tmp/pkg.tgz exists
[ OK ] repo = extract from /tmp/pkg.tgz
[ OK ] repo file = use /etc/apt/sources.list.d/pigsty-local.list
[WARN] apt cache = updating, make take a while
...(apt install 输出)
[ OK ] ansible = ansible [core 2.14.3]
[ OK ] boostrap pigsty complete
proceed with ./configure
```
例：有互联网访问，但没离线包，直接从互联网 Bootstrap （Ubuntu 20.04）
在一台有互联网访问的 Ubuntu 20.04 节点上，因为 Pigsty 官方没有提供离线软件包，因此选择在线安装。在这种情况下，Bootstrap 会使用可用的源，使用 yum/apt 安装 `ansible` 与依赖：
```bash
vagrant@ubuntu20:~/pigsty$ ./bootstrap
bootstrap pigsty v2.7.0 begin
[ OK ] region = china
[ OK ] kernel = Linux
[ OK ] machine = x86_64
[ OK ] package = deb,apt
[ OK ] vendor = ubuntu (Ubuntu)
[ OK ] version = 20 (20.04)
[ OK ] sudo = vagrant ok
[WARN] ubuntu 20 focal does not have corresponding offline package, use online install
[WARN] cache = missing and skip download
[WARN] repo = skip (/tmp/pkg.tgz not exists)
[ OK ] repo file = add ubuntu focal china upstream
[WARN] apt cache = updating, make take a while
...(apt update/install 输出)
[ OK ] ansible = ansible 2.9.6
[ OK ] boostrap pigsty complete
proceed with ./configure
```
----------------
## 制作离线软件包
Pigsty 提供了制作离线软件包的脚本 [**`bin/cache`**](https://github.com/Vonng/pigsty/blob/v2.7.0/bin/cache) 。默认会将 `/www/pigsty` 目录压缩打包，放置于 `/tmp/pkg.tgz` 下。
```bash
bin/cache [version=v2.7.0]
[pkg_path=/tmp/pkg.tgz]
[repo_dir=/www/pigsty]
```
制作完成后，将其拷贝至生产环境管理节点，参考 [**`bootstrap`**](#bootstrap) 过程使用即可，您也可以手工完成这一过程：
```bash
sudo rm -rf /www/pigsty # 谨慎清理先前遗留软件
sudo tar -xf /tmp/pkg.tgz -C /www # 解压离线软件包至目录
```
制作离线软件安装包的样例输出
例如，在标准安装完成后的 Ubuntu 22.04 系统上执行 `bin/cache` 脚本，即可创建离线软件包（`/tmp/pkg.tgz`）。
```bash
vagrant@ubuntu22:~/pigsty$ bin/cache
[ OK ] create offline package on ubuntu22
[ OK ] pkg type = deb
[ OK ] repo dir = /www/pigsty
[ OK ] copy /www/pigsty to /tmp/pigsty-build/pigsty
[ OK ] grafana plugins = found, overwrite /tmp/pigsty-build/pigsty/plugins.tgz
knightss27-weathermap-panel marcusolsson-dynamictext-panel marcusolsson-json-datasource marcusolsson-treemap-panel volkovlabs-form-panel volkovlabs-image-panel
marcusolsson-calendar-panel marcusolsson-hourly-heatmap-panel marcusolsson-static-datasource volkovlabs-echarts-panel volkovlabs-grapi-datasource volkovlabs-variable-panel
[ OK ] ubuntu 22 = no packages needs to be cleansed
[ OK ] package = making pigsty-pkg-v2.7.0.ubuntu22.x86_64.tgz
pigsty/
pigsty/liblua5.2-0_5.2.4-2_amd64.deb
.................. # 许多软件包
pigsty/distro-info-data_0.52ubuntu0.6_all.deb
[ OK ] package = finish pigsty-pkg-v2.7.0.ubuntu22.x86_64.tgz 5b071c2a651e8d1e68fc02e7e922f2b3
-rw-rw-r-- 1 vagrant vagrant 1.2G /tmp/pkg.tgz
scp ubuntu22:/tmp/pkg.tgz v2.7.0/pigsty-pkg-v2.7.0.ubuntu22.x86_64.tgz
```