0.2 安装单节点 Pigsty 沙箱

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

0.2.1 获取与核对版本

前置身份

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 运行。对照当前支持矩阵确认发行版 minor 与架构。

固定 release

官方 bootstrap 方式：

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

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

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

{
  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 配置、部署与幂等重跑

生成，再评审

在 Pigsty source directory：

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

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

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：

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

再在 L1 执行：

./install.yml

保留：

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 重跑部署；幂等意味着系统应收敛到声明状态，不意味着：

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

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

失败与复位

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、连接池与观察组件状态

四层健康

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：

pig status
postgres --version
psql --version

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

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

检查 PostgreSQL readiness：

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，确认：

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 暴露到公网。

上一节：选择实验环境 · 返回本章目录 · 下一节：完成首次连通 · 查看全书目录 · 查看索引中心