# PostgreSQL 部署配置

基于 Docker Compose 的 PostgreSQL 数据库部署方案，提供生产环境和测试环境两套配置。

## 目录结构

```
postgres/
├── env.cfg            # 环境变量配置（镜像版本、密码、认证方式）
├── prod.stack.yml     # 生产环境部署配置
├── test.stack.yml     # 测试环境部署配置
└── readme.md          # 本文件
```

## 环境变量说明 (`env.cfg`)

| 变量名 | 说明 | 示例值 |
|--------|------|--------|
| `IMAGE_TAG` | 测试环境使用的 PostgreSQL 镜像（≤16 版本） | `postgres:16.10` |
| `IMAGE_TAG_V15` | PostgreSQL 15 镜像标签 | `postgres:15.14` |
| `IMAGE_TAG_V17` | PostgreSQL 17 镜像标签 | `postgres:17.6` |
| `IMAGE_TAG_V18` | 生产环境使用的 PostgreSQL 18 镜像标签 | `postgres:18.0` |
| `POSTGRES_PASSWORD` | 数据库超级用户密码 | `AGC4eGx2aq8rSiZXBP` |
| `POSTGRES_HOST_AUTH_METHOD` | 主机认证方式 | `scram-sha-256` |

> ⚠️ **安全提示**：部署前请务必修改 `POSTGRES_PASSWORD` 为你自己的强密码，不要使用默认密码。

## 环境差异对比

| 配置项 | 生产环境 (`prod.stack.yml`) | 测试环境 (`test.stack.yml`) |
|--------|---------------------------|---------------------------|
| 项目名称 | `prod-dbs` | `test-dbs` |
| 容器名称 | `prod-postgres` | `test-postgres` |
| 镜像版本 | `IMAGE_TAG_V18`（PostgreSQL 18） | `IMAGE_TAG`（PostgreSQL 16） |
| 共享内存 | `256mb` | `128mb` |
| 数据卷路径 | `/var/lib/postgresql`（≥17 版本） | `/var/lib/postgresql/data`（≤16 版本） |

> 📌 **注意**：PostgreSQL ≥17 版本的数据目录变更为 `/var/lib/postgresql`，≤16 版本为 `/var/lib/postgresql/data`，请根据版本正确挂载。

## 部署前准备

创建数据卷目录：

```bash
mkdir -pv /data/volumes/postgres/data
```

## 部署命令

### 拉取镜像

**生产环境：**
```bash
docker compose --env-file ./dbSer/postgres/env.cfg -f ./dbSer/postgres/prod.stack.yml pull
```

**测试环境：**
```bash
docker compose --env-file ./dbSer/postgres/env.cfg -f ./dbSer/postgres/test.stack.yml pull
```

### 启动服务

**生产环境：**
```bash
docker compose -p prod-dbs --env-file ./dbSer/postgres/env.cfg -f ./dbSer/postgres/prod.stack.yml up -d
```

**测试环境：**
```bash
docker compose -p test-dbs --env-file ./dbSer/postgres/env.cfg -f ./dbSer/postgres/test.stack.yml up -d
```

## 连接信息

| 参数 | 值 |
|------|----|
| 主机 | `localhost` 或服务器 IP |
| 端口 | `5432` |
| 用户名 | `postgres` |
| 密码 | `env.cfg` 中 `POSTGRES_PASSWORD` 的值 |
| 认证方式 | `scram-sha-256` |

连接示例：

```bash
psql -h localhost -p 5432 -U postgres
```

## 数据持久化

数据库数据挂载在宿主机 `/data/volumes/postgres/data` 目录下，容器重建后数据不会丢失。

## 常用管理命令

```bash
# 查看运行状态
docker compose -p prod-dbs ps

# 查看日志
docker compose -p prod-dbs logs -f postgres

# 停止服务
docker compose -p prod-dbs down

# 重启服务
docker compose -p prod-dbs restart
```

## 版本升级注意事项

- 从 PostgreSQL ≤16 升级到 ≥17 时，数据目录路径发生变化，需要迁移数据
- 升级前请务必备份数据：`pg_dumpall -U postgres > backup.sql`
- 不支持跨大版本直接替换数据目录，需使用 `pg_upgrade` 或逻辑备份恢复