# 安装单节点 Pigsty 沙箱

LLMS 索引： [llms.txt](/llms.txt)

---

本节以全新、可销毁 Linux 节点为前提，冻结 Pigsty `v4.5.0`，使用默认单节点 `meta`
模板和 PostgreSQL 18。官方命令与模板会继续演进；复现本书时固定 release，不追随
`main` 或“latest”漂移。

## 0.2.1 获取与核对版本 {#item-0-2-1}

### 前置身份

```bash
id
hostnamectl
cat /etc/os-release
uname -m
sudo -n true
ssh localhost sudo -n true
```

Pigsty 需要 Linux、SSH 和 sudo。`sudo -n`/localhost SSH 失败时先修管理前置，不要把
脚本改成长期 root 运行。对照[当前支持矩阵](https://pigsty.io/docs/ref/linux/)确认
发行版 minor 与架构。

### 固定 release

官方 bootstrap 方式：

```bash
curl -fsSL https://repo.pigsty.io/get | bash -s v4.5.0
cd ~/pigsty
```

若组织禁止 pipe-to-shell，先下载、记录 SHA-256、人工/安全工具审查，再执行；或：

```bash
git clone https://github.com/pgsty/pigsty.git
cd pigsty
git checkout v4.5.0
git status --short
git rev-parse HEAD
./bootstrap
```

tag 提供版本选择，不自动证明供应链可信。高要求环境应按组织规则验证 release
artifact、来源、签名/摘要、package repository 与代理。offline package 必须匹配
OS minor/architecture，并核对对应 release 页面摘要。

### 保存不含 secret 的 acquisition manifest

```bash
{
  date -Is
  git describe --tags --always --dirty 2>/dev/null || true
  git rev-parse HEAD 2>/dev/null || true
  uname -a
  cat /etc/os-release
} > pg36-acquisition.txt
```

不要把 shell environment、完整 inventory 或 credential 写入该文件。

## 0.2.2 配置、部署与幂等重跑 {#item-0-2-2}

### 生成，再评审

在 Pigsty source directory：

```bash
./configure -g -v 18
chmod 0600 pigsty.yml
```

`-g` 生成随机密码；默认 `meta` 是单节点模板。执行前评审：

```text
inventory host/IP is this L1
pg_cluster and instance identity are expected
PostgreSQL major is 18
package/repository source is accepted
data/config/log/backup paths fit the disk
listen/access rules do not expose public networks
generated passwords are not defaults
modules and apps are actually needed
```

`pigsty.yml` 含访问和密码信息，不提交本书仓库、不粘贴到公开 issue。`files/pki/ca/ca.key`
生成后同样限制权限并备份到受控位置。

### 执行部署

先确认 target：

```bash
./install.yml --list-hosts
./install.yml --list-tags
```

再在 L1 执行：

```bash
./install.yml
```

保留：

```text
start/end time
Pigsty revision
redacted inventory digest
Ansible exit code
failed task and host
package versions
```

不要把“play recap 全 green”当数据库验收；下一目从 service、component 和 SQL 三侧
验证。

### 幂等的正确含义

修复临时网络/package 前置后，可以对同一 desired state 重跑部署；幂等意味着系统应
收敛到声明状态，不意味着：

```text
每次没有任何 changed
任何删除 playbook 都安全
运行中手改不会被覆盖
失败后可以删除 PGDATA 再试
```

若重跑持续出现 unexpected changes，比较 inventory、rendered file 与 runtime，
定位 non-idempotent task 或 drift。不要为“全绿”关闭安全控制。

### 失败与复位

```text
package/download failed -> 修 repo/DNS/TLS，保留失败输出后重跑
inventory/host wrong    -> 停止；不要在错误目标继续
disk/memory exhausted   -> 扩容或重建 L1，不清理未知 PG/WAL 文件
partial database state  -> 先取证和确认是否已有数据，再决定恢复/重建
```

对全新、确认无数据的 disposable VM，回到安装前 snapshot 往往比手工拆半套服务可靠。
已有数据的机器不属于本节重建授权。

## 0.2.3 检查 PostgreSQL、连接池与观察组件状态 {#item-0-2-3}

### 四层健康

```text
process
  service active / no crash loop

endpoint
  port accepts and route selects expected backend

protocol
  PostgreSQL authentication and SQL work

semantic
  exact cluster/database/role/version and expected read-write state
```

检查环境/package：

```bash
pig status
postgres --version
psql --version
```

检查本机 unit（模板禁用某组件时，inactive 不自动等于失败）：

```bash
systemctl is-active patroni
systemctl is-active pgbouncer
systemctl is-active haproxy
systemctl --failed
```

检查 PostgreSQL readiness：

```bash
pg_isready -h 127.0.0.1 -p 5432
```

`pg_isready` 不验证业务角色、数据库、查询或正确 backend，只是 protocol-level
availability。

### 分清端口

默认 Pigsty service 通常包括：

| 端口 | 入口 | 教学语义 |
|---:|---|---|
| 5432 | PostgreSQL instance | 本实例直连 |
| 6432 | PgBouncer | 本实例 pool |
| 5433 | HAProxy primary service | 读写，经 pool |
| 5434 | HAProxy replica service | 只读目标，经 pool |
| 5436 | HAProxy default service | primary 直连 |
| 5438 | HAProxy offline service | offline/分析直连 |

以本地 `pigsty.yml` 与 rendered HAProxy config 为准。单节点仍可暴露 replica/offline
service 名称，但没有第二故障域，不应宣称 HA。

### 观察系统

从受限网络访问 Web UI，确认：

```text
PostgreSQL target discovered
host target discovered
Patroni/etcd/PgBouncer/HAProxy as configured
metrics have recent timestamps
logs and alert evaluation available
```

dashboard 可见不证明采集语义正确；记录 target identity 和 timestamp。不要公开默认
UI 密码或将管理 UI 暴露到公网。

---

[上一节：选择实验环境](../01/) · [返回本章目录](../) ·
[下一节：完成首次连通](../03/) ·
[查看全书目录](/toc/) · [查看索引中心](/indexes/)