强曰为道
与天地相似,故不违。知周乎万物,而道济天下,故不过。旁行而不流,乐天知命,故不忧.
文档目录

PostgreSQL 完全指南 / 02 - 安装部署

第 02 章 · 安装部署

2.1 安装方式概览

方式适用场景优点缺点
包管理器(apt/yum)开发/测试环境简单快捷版本可能较旧
官方 APT/YUM 仓库生产环境最新稳定版需配置仓库
源码编译定制需求完全可控编译耗时、依赖多
Docker快速启动/开发零配置、秒级启动持久化需额外配置
二进制包无 root 权限不需要编译需手动配置

2.2 Ubuntu / Debian 安装

使用官方仓库安装(推荐)

# 1. 安装依赖
sudo apt update
sudo apt install -y wget gnupg2 lsb-release

# 2. 添加 PostgreSQL 官方 APT 仓库
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt \
$(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

# 3. 导入仓库签名密钥
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | \
  sudo apt-key add -

# 4. 更新包索引并安装
sudo apt update
sudo apt install -y postgresql-17

# 5. 验证安装
sudo systemctl status postgresql
psql --version

安装完成后,PostgreSQL 会自动:

  • 创建 postgres 系统用户
  • 初始化数据目录(通常在 /var/lib/postgresql/17/main/
  • 启动服务并设置开机自启
  • 监听 localhost:5432

安装常用扩展

sudo apt install -y postgresql-17-contrib postgresql-17-postgis-3

2.3 CentOS / RHEL / Fedora 安装

# 1. 安装官方仓库 RPM
sudo yum install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm

# 2. 禁用内置 PostgreSQL 模块(RHEL 8+/CentOS 8+)
sudo dnf -qy module disable postgresql

# 3. 安装 PostgreSQL 17
sudo yum install -y postgresql17-server postgresql17

# 4. 初始化数据库
sudo /usr/pgsql-17/bin/postgresql-17-setup initdb

# 5. 启动并设置开机自启
sudo systemctl start postgresql-17
sudo systemctl enable postgresql-17

# 6. 验证
sudo systemctl status postgresql-17
/usr/pgsql-17/bin/psql --version

2.4 macOS 安装

使用 Homebrew

# 安装
brew install postgresql@17

# 启动服务
brew services start postgresql@17

# 验证
psql --version

# 首次连接(macOS 默认使用当前系统用户)
psql postgres

使用 Postgres.app(图形化)

  1. 下载 https://postgresapp.com/
  2. 拖入 Applications
  3. 启动后自动初始化并运行
  4. 点击 “Open psql” 即可连接

2.5 Windows 安装

  1. 访问 https://www.postgresql.org/download/windows/
  2. 下载 EDB 安装程序(Interactive Installer by EDB)
  3. 运行安装程序:
    • 选择安装目录
    • 选择组件(PostgreSQL Server, pgAdmin, Stack Builder, Command Line Tools)
    • 设置数据目录
    • 设置 postgres 用户密码
    • 设置端口(默认 5432)
    • 选择语言区域
  4. 完成安装后,通过 Start Menu 打开 pgAdmin 或 SQL Shell (psql)

2.6 源码编译安装

适用于需要自定义编译选项的场景:

# 1. 安装编译依赖
sudo apt install -y build-essential libreadline-dev zlib1g-dev \
  libssl-dev libxml2-dev libxslt-dev libsystemd-dev \
  libicu-dev pkg-config

# 2. 下载源码
wget https://ftp.postgresql.org/pub/source/v17.0/postgresql-17.0.tar.gz
tar xzf postgresql-17.0.tar.gz
cd postgresql-17.0

# 3. 配置编译选项
./configure --prefix=/usr/local/pgsql \
  --with-openssl \
  --with-systemd \
  --with-icu \
  --with-libxml

# 4. 编译并安装
make -j$(nproc)
sudo make install

# 5. 安装 contrib 扩展
cd contrib
make -j$(nproc)
sudo make install

# 6. 创建用户和数据目录
sudo useradd -m -s /bin/bash postgres
sudo mkdir -p /var/lib/postgresql/data
sudo chown postgres:postgres /var/lib/postgresql/data

# 7. 初始化数据库
sudo -u postgres /usr/local/pgsql/bin/initdb \
  -D /var/lib/postgresql/data \
  --encoding=UTF8 \
  --locale=en_US.UTF-8

# 8. 启动
sudo -u postgres /usr/local/pgsql/bin/pg_ctl \
  -D /var/lib/postgresql/data \
  -l logfile start

⚠️ 注意事项:源码编译安装后,需要手动配置 PATHLD_LIBRARY_PATH,或创建 systemd service 文件。


2.7 Docker 快速部署

最简启动

docker run -d \
  --name postgres \
  -e POSTGRES_PASSWORD=yourpassword \
  -p 5432:5432 \
  postgres:17

生产级配置

docker run -d \
  --name postgres \
  --restart=always \
  -e POSTGRES_USER=myapp \
  -e POSTGRES_PASSWORD=strongpassword \
  -e POSTGRES_DB=mydb \
  -p 5432:5432 \
  -v pgdata:/var/lib/postgresql/data \
  -v ./init.sql:/docker-entrypoint-initdb.d/init.sql \
  --shm-size=256m \
  postgres:17 \
    -c shared_buffers=512MB \
    -c effective_cache_size=1536MB \
    -c max_connections=200 \
    -c work_mem=16MB \
    -c maintenance_work_mem=128MB \
    -c wal_buffers=16MB \
    -c random_page_cost=1.1

Docker Compose 配置

version: "3.8"

services:
  postgres:
    image: postgres:17
    container_name: pg-main
    restart: always
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: securepassword
      POSTGRES_DB: appdb
      PGDATA: /var/lib/postgresql/data/pgdata
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./config/postgresql.conf:/etc/postgresql/postgresql.conf
      - ./config/pg_hba.conf:/etc/postgresql/pg_hba.conf
    command: postgres -c config_file=/etc/postgresql/postgresql.conf
    shm_size: 256m
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  pgdata:
    driver: local

2.8 核心配置文件

PostgreSQL 的配置主要涉及以下文件(通常位于数据目录中):

文件作用说明
postgresql.conf主配置文件内存、连接、WAL、日志等
pg_hba.conf客户端认证控制谁能连、怎么认证
pg_ident.conf用户名映射OS 用户 → PG 用户映射
postgresql.auto.confALTER SYSTEM 存储不要手动编辑

pg_hba.conf 详解

pg_hba.conf(Host-Based Authentication)控制客户端连接的认证方式。格式:

# TYPE    DATABASE  USER      ADDRESS         METHOD
  local   all       postgres                  peer
  local   all       all                       scram-sha-256
  host    all       all       127.0.0.1/32    scram-sha-256
  host    all       all       ::1/128         scram-sha-256
  host    mydb      appuser   10.0.0.0/8      scram-sha-256
  host    all       all       0.0.0.0/0       reject
字段含义
TYPElocal(Unix Socket)、host(TCP/IP)、hostssl(仅 SSL)
DATABASE数据库名,all = 所有,多个用逗号分隔
USER用户名,all = 所有
ADDRESS客户端 IP/CIDR,local 类型不需要
METHOD认证方法

常见认证方法:

方法安全性说明
trust❌ 极低无需密码,绝不要在生产使用
peer✅ 高仅本地 Socket,要求 OS 用户名 = PG 用户名
scram-sha-256✅ 高密码认证(PG 10+推荐)
md5⚠️ 中密码认证(旧方式,建议升级到 scram-sha-256)
cert✅ 高SSL 客户端证书认证
reject拒绝连接

⚠️ 注意事项pg_hba.conf 是从上往下匹配的,第一个匹配的规则生效。更具体的规则应放在前面。


2.9 初始化后的基础配置

安装完成后,建议立即修改 postgresql.conf 中的以下关键参数:

-- 查看当前配置
SHOW shared_buffers;
SHOW work_mem;
SHOW max_connections;

-- 或者查看所有配置
SELECT name, setting, unit, context
FROM pg_settings
WHERE name IN (
    'shared_buffers', 'effective_cache_size', 'work_mem',
    'maintenance_work_mem', 'max_connections', 'wal_buffers',
    'random_page_cost', 'log_min_duration_statement'
);

推荐初始配置(4GB 内存服务器)

postgresql.conf 中修改:

# 内存相关
shared_buffers = 1GB              # 总内存的 25%
effective_cache_size = 3GB        # 总内存的 75%
work_mem = 8MB                    # 每个排序/哈希操作的内存
maintenance_work_mem = 256MB      # VACUUM/CREATE INDEX 的内存
wal_buffers = 64MB                # WAL 缓冲区

# 连接相关
max_connections = 200             # 最大连接数
superuser_reserved_connections = 3 # 为超级用户保留的连接

# WAL 相关
wal_level = replica               # 支持复制和 PITR
max_wal_size = 2GB
min_wal_size = 512MB

# 日志
log_min_duration_statement = 1000 # 记录超过 1 秒的慢查询
log_checkpoints = on
log_connections = on
log_disconnections = on
log_lock_waits = on

# 随机读代价(SSD 环境)
random_page_cost = 1.1            # SSD 使用 1.1,HDD 使用 4.0

修改后重启或重载配置:

# 方式 1:在 psql 中重载(大部分参数支持)
SELECT pg_reload_conf();

# 方式 2:系统命令重启
sudo systemctl restart postgresql

# 方式 3:使用 ALTER SYSTEM(推荐,不需要编辑文件)
ALTER SYSTEM SET shared_buffers = '1GB';
ALTER SYSTEM SET work_mem = '8MB';
-- 修改后需要重启才能生效的参数
SELECT pg_reload_conf();

💡 技巧:使用 ALTER SYSTEM SET 修改的参数会写入 postgresql.auto.conf,优先级高于 postgresql.conf。用 ALTER SYSTEM RESET param_name 可以恢复默认值。


2.10 常用管理命令

# 服务管理(systemd)
sudo systemctl start postgresql     # 启动
sudo systemctl stop postgresql      # 停止
sudo systemctl restart postgresql   # 重启
sudo systemctl reload postgresql    # 重载配置
sudo systemctl status postgresql    # 查看状态

# 使用 pg_ctl 管理(适合非 systemd 环境)
pg_ctl -D /var/lib/postgresql/data start
pg_ctl -D /var/lib/postgresql/data stop
pg_ctl -D /var/lib/postgresql/data reload

# 查看数据目录
sudo -u postgres psql -c "SHOW data_directory;"
sudo -u postgres psql -c "SHOW config_file;"
sudo -u postgres psql -c "SHOW hba_file;"

业务场景

场景推荐安装方式理由
本地开发Docker 或 Homebrew秒级启动,不影响系统
CI/CD 测试Docker Compose可重复、隔离、自动化
生产单机官方仓库 + 手动调优稳定、可控、易维护
生产容器化Docker / K8s + CloudNativePG弹性伸缩、声明式管理

扩展阅读