forked from DevOps/deploy.stack
dfb150f77e
add complete readme document for postgres deployment with docker compose, including env config, deployment commands, connection info and upgrade notes
115 lines
3.3 KiB
Markdown
115 lines
3.3 KiB
Markdown
# 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` 或逻辑备份恢复
|