背景：

我想安装一个PostgreSQL进行学习，看视频是说使用12比较稳妥，
然后一般使用图像化界面操作，也就是pgAdmin 4，然后我想直接使用codex安装

本文章主要记录，可参考过程

1.codex输入指令，然后会询问你一些问题，按需求回复即可

我现在需要学习postgreSQL12,使用图形界面 postgre admin14来学习，
想使用docker来安装，但是我电脑上没有docker，请详细说明步骤，
生成md文档告诉我如何一步一步安装和配置，
顺便你帮我安装一下我说到的这些，生成的md放E:\study_file\技术文档总集这里

2.我之前下载过一个安装包

D:\docker_install这个下面有安装包，你看适合吗，可以安装在这个目录下面

3.生成计划

PostgreSQL 12 + pgAdmin 4 Docker 学习环境安装方案

## 摘要

- 现有 `Docker Desktop 4.70.0` 安装包数字签名有效，可以安装；但将按你的选择下载当前官方最新版，现有安装包保留备用。
- 电脑满足运行条件：Windows 11 家庭版 64 位、约 32 GB 内存、Hypervisor 已启用、D 盘剩余约 260 GB。
- 使用 Docker Desktop 的 WSL 2 后端，同时运行 PostgreSQL 12.22 和 pgAdmin 4。
- PostgreSQL 12 已于 2024-11-21结束维护，仅用于本机学习，不用于生产环境。[PostgreSQL 官方说明](https://www.postgresql.org/support/versioning/)
- 采用以下目录：

  - Docker 程序：`D:\docker_install\DockerDesktop`
  - Docker 虚拟磁盘：`D:\docker_install\data`
  - 安装包：`D:\docker_install\packages`
  - PostgreSQL 项目：`D:\docker_install\postgresql12-lab`
  - 教程文档：`E:\study\_file\技术文档总集\PostgreSQL12_Docker_pgAdmin4_安装配置与学习环境.md`

## 实施步骤

1. 安装前检查

   - 再次确认 TCP 端口 `5432`、`5050` 未被占用。
   - 从 [Docker 官方页面](https://docs.docker.com/desktop/setup/install/windows-install/)下载最新版 x86_64 安装包。
   - 验证 Docker Inc 数字签名和官方 SHA-256；保留原有 4.70.0 安装包，不覆盖、不删除。

2. 启用 WSL 2

   - 管理员权限执行 `wsl --install --no-distribution`，不额外安装 Ubuntu。
   - 在系统要求时重启电脑；你重新打开本任务后继续。
   - 重启后执行 `wsl --update`、`wsl --set-default-version 2`，确认 WSL 满足 Docker Desktop 要求。[微软 WSL 安装说明](https://learn.microsoft.com/windows/wsl/install)

3. 安装 Docker Desktop

   - 使用 WSL 2 后端和 Linux 容器模式。
   - 通过官方安装参数指定程序目录和 WSL 虚拟磁盘目录，禁用不适用于家庭版的 Windows 容器功能。
   - Docker 服务协议由你在首次启动界面中亲自确认，不自动代替你接受。
   - 验证 `docker version`、`docker compose version`、`docker info`，并确认 Docker 数据实际写入 D 盘。

4. 创建 PostgreSQL 学习项目

   在 `D:\docker_install\postgresql12-lab` 创建：

   - `compose.yaml`
   - `.env`
   - `.gitignore`
   - `servers.json`

   配置内容：

   - PostgreSQL 镜像固定为最终版本 `postgres:12.22-bookworm`。
   - pgAdmin 镜像固定为实施时的官方稳定版，不使用浮动的 `latest` 标签。
   - PostgreSQL 数据库：`study_db`
   - PostgreSQL 用户：`postgres`
   - PostgreSQL 密码：`123456`
   - pgAdmin 登录邮箱：`admin@example.com`
   - pgAdmin 密码：`123456`
   - PostgreSQL 和 pgAdmin 均使用持久化 Docker 卷。
   - 添加数据库健康检查和容器启动依赖。
   - 使用 `servers.json` 预先注册 PostgreSQL 服务，pgAdmin 内部连接地址使用容器服务名，而不是 `localhost`。

5. 启动与验证

   - 执行 `docker compose pull` 和 `docker compose up -d`。
   - pgAdmin 地址：`http://127.0.0.1:5050`
   - PostgreSQL 地址：`127.0.0.1:5432`
   - 登录 pgAdmin，连接 `study_db`，执行版本查询和建表、插入、查询示例。
   - 停止并重新启动容器，确认测试数据和 pgAdmin 配置仍然存在。
   - 所有端口只绑定 `127.0.0.1`，不会向局域网开放；`123456` 仅允许用于这个本机学习环境。

6. 生成详细 Markdown 教程

   文档将包含：

   - 本机环境检查结果
   - WSL 2 和 Docker Desktop 图形化、命令行两套安装步骤
   - 每次需要管理员权限或重启的位置
   - 完整 Compose 配置及逐项解释
   - pgAdmin 登录、注册服务器和执行 SQL 的图文式操作路径
   - 容器启动、停止、重启、查看日志和查看状态命令
   - 数据持久化、备份和恢复方法
   - 修改密码和端口的方法
   - WSL、虚拟化、镜像下载、端口冲突、连接失败等常见故障处理
   - 清空学习环境的命令，并对会删除数据的操作添加醒目警告
   - PostgreSQL 12 已停止维护的说明和未来升级建议
   - Docker、微软、PostgreSQL、pgAdmin 官方资料链接

## 验收测试

- `wsl --version` 和 `wsl --status` 正常，默认版本为 WSL 2。
- Docker Desktop 能启动，Docker Engine 为 Linux 模式。
- Docker 程序及虚拟磁盘位于指定的 D 盘子目录。
- 两个容器均为运行状态，PostgreSQL 健康检查通过。
- `SELECT version();` 返回 PostgreSQL `12.22`。
- pgAdmin 可通过 `127.0.0.1:5050` 登录并连接数据库。
- 能完成建表、插入、查询；容器重启后数据仍存在。
- 局域网地址不能直接访问 `5432` 或 `5050`。
- Markdown 文档成功写入指定 E 盘目录，并额外保留一份可在 Codex 中下载的副本。

## 假设与故障策略

- 此环境用于个人学习，符合 Docker Desktop 免费使用场景。
- 安装过程中你可以响应 UAC 管理员提示，并允许一次系统重启。
- 网络允许从 Docker 官方站和 Docker Hub 下载安装包及镜像。
- 如果最新版安装包下载或签名验证失败，将停止安装并报告原因，不会静默改用旧版本。
- 不删除或覆盖 `D:\docker_install\Docker Desktop Installer.exe`。
- 不启用远程数据库访问，不把弱密码用于生产环境。

4.什么是WSL，有什么用，如何安装打开使用

安装方式

运行方式

5.生成的md文档，以及使用教程

# PostgreSQL 12 + pgAdmin 4 + Docker Desktop 安装配置教程

> 适用电脑：Windows 11 家庭版中文版（64 位）  
> 本机学习环境：Docker Desktop 4.87.0 + WSL 2.7.12 + PostgreSQL 12.22 + pgAdmin 4 9.17  
> 文档生成日期：2026-08-24

## 1. 最终效果和目录

安装完成后，通过浏览器访问 pgAdmin：

- pgAdmin 地址：<http://127.0.0.1:5050>
- pgAdmin 登录邮箱：`admin@example.com`
- pgAdmin 登录密码：`123456`
- PostgreSQL 主机（Windows 软件连接时）：`127.0.0.1`
- PostgreSQL 主机（pgAdmin 容器连接时）：`postgres`
- PostgreSQL 端口：`5432`
- 数据库：`study_db`
- 用户：`postgres`
- 密码：`123456`

目录规划：

```text
C:\Users\30414\AppData\Local\Programs\DockerDesktop
└─ Docker Desktop.exe             # Docker Desktop 当前用户程序

D:\docker_install
├─ Docker Desktop Installer 4.87.0.exe
├─ data                           # Docker 的 WSL 虚拟磁盘、镜像和容器数据
└─ postgresql12-lab               # PostgreSQL 学习项目
   ├─ compose.yaml
   ├─ .env
   ├─ .gitignore
   ├─ servers.json
   └─ backup                      # SQL 备份目录
```

> 安全提醒：`123456` 是弱密码。本教程把端口严格绑定到 `127.0.0.1`，只适合这台电脑上的学习环境。不要把此密码用于生产、云服务器或局域网开放环境。

## 日常快速使用指南（以后主要看这一节）

下面把“图像工具”理解为“图形工具”。本环境有两个图形界面：

- **Docker Desktop**：负责启动和管理 Docker 引擎、容器、镜像和数据卷。
- **pgAdmin 4**：浏览器里的 PostgreSQL 图形管理工具，用于建库、建表、查询和查看数据。

### A. 每次开机后怎样启动

#### 方法一：使用开始菜单和 Docker Desktop 图形界面

1. 按 Windows 键，搜索并打开 **Docker Desktop**。
2. 等待右下角 Docker 鲸鱼图标出现，并确认 Docker Desktop 显示 Engine 正在运行。
3. 在 Docker Desktop 左侧打开 **Containers**。
4. 找到 `postgresql12-lab` 项目。如果两个容器没有运行，点击项目右侧的启动按钮。
5. 两个容器都显示绿色运行状态后，即可访问 pgAdmin。

两个容器的用途：

- `postgresql12-db`：PostgreSQL 12 数据库。
- `postgresql12-pgadmin`：pgAdmin 4 图形界面。

`compose.yaml` 已设置 `restart: unless-stopped`。只要 Docker Desktop 随 Windows 登录启动，容器通常也会自动恢复运行。可以在 Docker Desktop 的 **Settings > General** 中按需启用 **Start Docker Desktop when you sign in to your computer**。

#### 方法二：使用 PowerShell（推荐，最稳定）

打开一个新的 PowerShell 窗口，执行：

```powershell
$env:PATH="$env:LOCALAPPDATA\Programs\DockerDesktop\resources\bin;$env:PATH"
Set-Location 'D:\docker_install\postgresql12-lab'
docker compose up -d
docker compose ps
```

看到 `postgresql12-db` 和 `postgresql12-pgadmin` 的状态都是 `Up`，数据库就已经启动。`docker compose up -d` 可以反复执行：无论容器此前是停止状态、被删除状态还是已经运行，它都会把环境恢复到应有状态。

如果 PowerShell 提示找不到 `docker` 命令，先关闭并重新打开 PowerShell；仍然找不到时，保留上面第一行临时添加 PATH 的命令。

也可以用一组命令启动容器并直接打开 pgAdmin：

```powershell
$env:PATH="$env:LOCALAPPDATA\Programs\DockerDesktop\resources\bin;$env:PATH"
Set-Location 'D:\docker_install\postgresql12-lab'
docker compose up -d
Start-Process 'http://127.0.0.1:5050'
```

### B. 怎样访问 PostgreSQL 和 pgAdmin

#### 访问 pgAdmin 图形界面

在浏览器地址栏输入：

<http://127.0.0.1:5050>

登录信息：

- 邮箱：`admin@example.com`
- 密码：`123456`

登录后，在左侧依次展开：

```text
Servers
└─ PostgreSQL 12 学习库
```

第一次连接数据库时，pgAdmin 会询问 PostgreSQL 密码，输入 `123456`。个人学习电脑上可以勾选保存密码；如果电脑会被他人使用，则不要保存。

#### 其他 Windows 数据库软件的连接信息

以后使用 DBeaver、DataGrip、Navicat 或程序代码连接时填写：

| 配置项 | 值 |
|---|---|
| Host/主机 | `127.0.0.1` |
| Port/端口 | `5432` |
| Database/数据库 | `study_db` |
| Username/用户名 | `postgres` |
| Password/密码 | `123456` |

注意主机名的区别：

- Windows 浏览器、数据库客户端和本机程序使用 `127.0.0.1`。
- pgAdmin 运行在 Docker 容器中，因此它连接 PostgreSQL 时使用容器服务名 `postgres`。
- 当前端口只监听本机 `127.0.0.1`，局域网中的其他电脑无法访问，这是学习环境的安全设置。

### C. 怎样使用 pgAdmin 图形工具

#### 1. 认识左侧对象树

连接服务器后，依次展开：

```text
Servers
└─ PostgreSQL 12 学习库
   └─ Databases
      └─ study_db
         └─ Schemas
            └─ public
               └─ Tables
```

如果刚创建的数据库或表没有出现，右键上一级节点，选择 **Refresh**。

#### 2. 用图形界面新建数据库

1. 右键 **Databases**。
2. 选择 **Create > Database...**。
3. 在 **Database** 中输入数据库名，例如 `practice_db`。
4. **Owner** 选择 `postgres`。
5. 点击 **Save**。

日常练习可以直接使用已经创建好的 `study_db`，不必每次都新建数据库。

#### 3. 用图形界面新建表

以创建学生表为例：

1. 展开 **study_db > Schemas > public**。
2. 右键 **Tables**，选择 **Create > Table...**。
3. 在 **General** 页把 Name 填为 `students_gui`。
4. 打开 **Columns** 页，依次添加以下列：

| 列名 | 数据类型 | Not NULL | Primary key |
|---|---|---:|---:|
| `id` | `bigserial` | 是 | 是 |
| `name` | `character varying(50)` | 是 | 否 |
| `age` | `integer` | 否 | 否 |

5. 点击 **Save**。
6. 右键 **Tables** 并选择 **Refresh**，确认能看到 `students_gui`。

#### 4. 用表格直接添加和修改数据

1. 右键 `students_gui`。
2. 选择 **View/Edit Data > All Rows**。
3. 在结果表格最后的空白行中填写 `name` 和 `age`；`id` 是自动编号，可以留空。
4. 点击工具栏上的 **Save Data Changes** 保存按钮。
5. 修改已有单元格后也要点击保存；只关闭页面可能不会保存修改。

#### 5. 使用 Query Tool 执行 SQL

1. 右键左侧的 `study_db`。
2. 选择 **Query Tool**。
3. 在上方 SQL 编辑区粘贴下面的练习语句：

```sql
CREATE TABLE IF NOT EXISTS students_sql (
    id BIGSERIAL PRIMARY KEY,
    name VARCHAR(50) NOT NULL,
    age INTEGER CHECK (age >= 0)
);

INSERT INTO students_sql (name, age)
VALUES ('张三', 20), ('李四', 22);

SELECT *
FROM students_sql
ORDER BY id;
```

4. 点击工具栏上的执行按钮（闪电/播放图标），或按 `F5`。
5. 下方 **Data Output** 显示查询结果，**Messages** 显示执行信息或错误。

常用 SQL 操作：

```sql
-- 查询
SELECT * FROM students_sql;

-- 修改
UPDATE students_sql SET age = 21 WHERE name = '张三';

-- 删除一行
DELETE FROM students_sql WHERE name = '李四';
```

执行 `UPDATE` 或 `DELETE` 前，建议先用相同的 `WHERE` 条件执行一次 `SELECT`，确认将要影响哪些数据。

#### 6. 用 pgAdmin 图形界面备份与恢复

备份：

1. 右键 `study_db`，选择 **Backup...**。
2. Filename 选择 pgAdmin 存储区中的文件名，例如 `study_db.backup`。
3. Format 选择 **Custom**。
4. 点击 **Backup**。
5. 如需把文件保存到 Windows，可在 pgAdmin 的 **Tools > Storage Manager** 中找到该文件并下载。

恢复：

1. 最好先创建一个空数据库，例如 `study_restore_gui`。
2. 右键该数据库，选择 **Restore...**。
3. 选择已经上传到 pgAdmin 存储区的 `.backup` 文件。
4. 点击 **Restore**。

如果提示找不到 PostgreSQL 12 备份程序，按本文第 11 节把 PostgreSQL 12 Binary Path 设置为 `/usr/local/pgsql-12`。如果只是想把 `.sql` 文件直接保存在 `D:\docker_install\postgresql12-lab\backup`，使用本文第 10 节的 PowerShell 命令更方便。

### D. 怎样关闭，数据会不会丢

关闭浏览器页面只会关闭 pgAdmin 网页，不会停止数据库，也不会丢失数据。

日常停止容器：

```powershell
$env:PATH="$env:LOCALAPPDATA\Programs\DockerDesktop\resources\bin;$env:PATH"
Set-Location 'D:\docker_install\postgresql12-lab'
docker compose stop
```

也可以在 Docker Desktop 的 **Containers** 页面点击停止按钮。容器停止后，可以从 Windows 右下角托盘中的 Docker 图标选择 **Quit Docker Desktop**。

下次使用时仍执行：

```powershell
Set-Location 'D:\docker_install\postgresql12-lab'
docker compose up -d
```

数据库数据存放在 Docker 命名卷中，因此 `stop`、重启电脑，甚至执行 `docker compose down` 都不会删除数据。**不要执行 `docker compose down -v`，除非你明确要永久清空数据库和 pgAdmin 配置。**

### E. 页面打不开时的快速检查

依次执行：

```powershell
$env:PATH="$env:LOCALAPPDATA\Programs\DockerDesktop\resources\bin;$env:PATH"
Set-Location 'D:\docker_install\postgresql12-lab'
docker info
docker compose up -d
docker compose ps
docker compose logs --tail=100 pgadmin
```

- `docker info` 报错：Docker Desktop 尚未完全启动，先打开它并等待 Engine 正常。
- 容器不是 `Up`：查看最后一条日志中的错误。
- 容器正常但网页打不开：确认地址是 `http://127.0.0.1:5050`，不是 `https`。
- 能打开 pgAdmin 但数据库连接失败：主机应是 `postgres`，端口 `5432`，用户 `postgres`，密码 `123456`。

## 2. 已完成的安装前检查

本机检查结果：

- Windows 11 家庭版中文版，64 位，Build 26200
- CPU：13th Gen Intel Core i7-13650HX
- 内存：约 31.73 GB
- Windows 已检测到 Hypervisor，硬件虚拟化条件具备
- D 盘剩余空间约 260 GB
- TCP `5432` 和 `5050` 当前未被占用
- 当前没有安装 Docker、PostgreSQL 或 pgAdmin
- WSL 命令存在，但 WSL 功能尚未完成安装
- 原 Docker Desktop 4.70.0 安装包在 Windows Build 26200 上稳定返回退出码 `-5`，未能安装，现已按要求删除
- 最终安装包版本：Docker Desktop 4.87.0.236836
- 安装包数字签名：有效，签名者为 Docker Inc
- 最终安装包 SHA-256：`9AC03D4E900C0FDEE981D4BDE083A55FDFB28FFBA2CAE77726EFF2A437254822`

PostgreSQL 12.22 是 12 系列最终版本。PostgreSQL 12 已于 2024-11-21 停止官方维护，不再收到安全和缺陷修复，只建议用于旧项目兼容学习。参考：[PostgreSQL 版本支持策略](https://www.postgresql.org/support/versioning/)。

## 3. 第一步：启用 WSL 2

Docker Desktop 在 Windows 家庭版上使用 Linux 容器，需要 WSL 2。Docker Desktop 自己会管理内部 Linux 环境，因此本教程不额外安装 Ubuntu。

### 3.1 使用图形界面打开管理员 PowerShell

1. 按 Windows 键。
2. 输入 `PowerShell`。
3. 右键“Windows PowerShell”或“终端”，选择“以管理员身份运行”。
4. 在 UAC 窗口中选择“是”。

### 3.2 安装 WSL 基础组件

执行：

```powershell
wsl --install --no-distribution
```

在本机实际执行时，旧版内置 WSL 命令返回了退出码 `1`，没有完成快速安装。如果你以后在相似电脑上遇到相同情况，请继续在管理员 PowerShell 中执行微软支持的手动启用命令：

```powershell
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
```

本机通过这两条命令成功启用了所需功能，并返回 `3010`，含义是“操作成功，需要重新启动才能生效”。

如果系统提示需要重启，请保存其他工作并重启电脑。重启之后重新打开 PowerShell，执行：

```powershell
wsl --update
wsl --set-default-version 2
wsl --version
wsl --status
```

预期结果：能够看到 WSL 和内核版本，默认版本为 `2`。

如果下载长时间停在 `0.0%`，可尝试：

```powershell
wsl --update --web-download
```

参考：[微软 WSL 安装文档](https://learn.microsoft.com/windows/wsl/install)。

## 4. 第二步：安装 Docker Desktop 4.87.0

### 4.1 本机实际成功的安装方式

这台电脑的 Windows Build 26200 在“所有用户 + UAC + 自定义程序目录”模式下会让 Docker 安装器退出并返回 `-5`。最终采用 Docker 官方推荐的“当前用户安装”模式：程序位于当前用户的 `%LOCALAPPDATA%`，不需要 UAC；体积较大的 WSL 虚拟磁盘、镜像、容器和数据库数据仍然放在 D 盘。

在普通 PowerShell 中执行：

```powershell
$installer = 'D:\docker_install\Docker Desktop Installer 4.87.0.exe'

Start-Process -FilePath $installer -Wait -ArgumentList @(
  'install',
  '--user',
  '--backend=wsl-2',
  '--wsl-default-data-root=D:\docker_install\data',
  '--no-windows-containers'
)
```

这些参数的作用：

- `--user`：按当前用户安装，避开本机 UAC 重启兼容问题。
- `--backend=wsl-2`：使用 WSL 2 后端。
- `--wsl-default-data-root`：把虚拟磁盘、镜像和容器数据放到 D 盘。
- `--no-windows-containers`：只使用本教程需要的 Linux 容器，减少额外权限与组件。

最终程序目录为：

```text
C:\Users\30414\AppData\Local\Programs\DockerDesktop
```

参考：[Docker Desktop Windows 安装与参数说明](https://docs.docker.com/desktop/setup/install/windows-install/)。

### 4.2 首次启动

1. 从开始菜单打开 Docker Desktop；也可以执行：

   ```powershell
   Start-Process "$env:LOCALAPPDATA\Programs\DockerDesktop\Docker Desktop.exe"
   ```

2. 阅读 Docker Subscription Service Agreement，然后由你手动点击接受。
3. 等待左下角状态显示 Docker Engine 正在运行。
4. 如果提示登录 Docker Hub，个人学习可以选择跳过；拉取公开镜像不要求登录。
5. 确保处于 Linux containers 模式。

打开一个新的 PowerShell 验证：

```powershell
docker version
docker compose version
docker info
```

本机验证结果：Docker Desktop `4.87.0`、Docker Engine `29.7.2`、Docker Compose `5.4.0`，Engine 为 Linux/WSL 2 模式，内核为 `6.18.33.2-microsoft-standard-WSL2`。

如果提示找不到 `docker`，先关闭并重新打开 PowerShell；仍未解决时重启一次电脑。

## 5. 第三步：检查学习项目配置

进入项目目录：

```powershell
Set-Location 'D:\docker_install\postgresql12-lab'
Get-ChildItem -Force
docker compose config --quiet
```

应当能看到 `compose.yaml`、`.env`、`.gitignore`、`servers.json` 和 `backup`。

### 5.1 `compose.yaml` 的关键设计

- `postgres:12.22-bookworm`：固定 PostgreSQL 12 最终补丁版本，避免版本漂移。
- `dpage/pgadmin4:9.17`：固定 pgAdmin 版本，不使用浮动 `latest`。
- `postgres_data`：持久保存数据库文件。
- `pgadmin_data`：持久保存 pgAdmin 用户设置和服务器配置。
- `127.0.0.1:5432:5432`：数据库只接受本机访问。
- `127.0.0.1:5050:80`：pgAdmin 只接受本机浏览器访问。
- 健康检查：数据库真正可以连接后才启动 pgAdmin。
- `servers.json`：首次启动时自动注册名为“PostgreSQL 12 学习库”的连接。

### 5.2 密码为什么放在 `.env`

`.env` 内容为：

```dotenv
POSTGRES_PASSWORD=123456
PGADMIN_PASSWORD=123456
```

`.gitignore` 已排除 `.env`，避免以后误提交到 Git。即使如此，真实项目也必须改用强密码和专门的密钥管理方案。

## 6. 第四步：拉取镜像并启动

确保 Docker Desktop 已经运行，然后执行：

```powershell
Set-Location 'D:\docker_install\postgresql12-lab'
docker compose pull
docker compose up -d
docker compose ps
```

第一次下载可能需要几分钟。正常状态应为：

- `postgresql12-db`：`Up`、`healthy`
- `postgresql12-pgadmin`：`Up`

查看启动日志：

```powershell
docker compose logs --tail=100 postgres
docker compose logs --tail=100 pgadmin
```

持续跟踪日志可使用：

```powershell
docker compose logs -f
```

按 `Ctrl+C` 仅退出日志查看，不会停止容器。

## 7. 第五步：使用 pgAdmin 4

### 7.1 登录 pgAdmin

浏览器打开：<http://127.0.0.1:5050>

输入：

- Email：`admin@example.com`
- Password：`123456`

### 7.2 连接 PostgreSQL

左侧 Servers 中应出现“PostgreSQL 12 学习库”。首次连接时输入数据库密码 `123456`，可按需勾选保存密码。

如果没有自动出现，可手动注册：

1. 右键 Servers，选择 Register > Server。
2. General > Name：`PostgreSQL 12 学习库`。
3. Connection > Host name/address：`postgres`。
4. Port：`5432`。
5. Maintenance database：`study_db`。
6. Username：`postgres`。
7. Password：`123456`。
8. 点击 Save。

> 在 pgAdmin 容器内不能把数据库主机填写为 `localhost`。`localhost` 指向 pgAdmin 容器自己，正确主机名是 Compose 服务名 `postgres`。

### 7.3 执行第一段 SQL

依次展开 Servers > PostgreSQL 12 学习库 > Databases > study_db，右键 `study_db`，选择 Query Tool，执行：

```sql
SELECT version();
SHOW server_version;

CREATE TABLE students (
    id          BIGSERIAL PRIMARY KEY,
    name        VARCHAR(50) NOT NULL,
    age         INTEGER CHECK (age >= 0),
    created_at  TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
);

INSERT INTO students (name, age)
VALUES ('张三', 20), ('李四', 22);

SELECT *
FROM students
ORDER BY id;
```

`SELECT version()` 应显示 PostgreSQL `12.22`。

## 8. 常用管理命令

以下命令都在项目目录执行：

```powershell
Set-Location 'D:\docker_install\postgresql12-lab'
```

查看状态：

```powershell
docker compose ps
```

停止但不删除容器：

```powershell
docker compose stop
```

重新启动：

```powershell
docker compose start
```

重启：

```powershell
docker compose restart
```

停止并删除容器，但保留数据库卷：

```powershell
docker compose down
```

再次创建：

```powershell
docker compose up -d
```

进入 `psql`：

```powershell
docker compose exec postgres psql -U postgres -d study_db
```

退出 `psql`：

```text
\q
```

## 9. 验证数据持久化

先确认 `students` 表中有数据，然后执行：

```powershell
docker compose down
docker compose up -d
docker compose exec postgres psql -U postgres -d study_db -c "SELECT * FROM students ORDER BY id;"
```

重建容器后仍能看到数据，说明 `postgres_data` 持久化卷工作正常。

## 10. 备份与恢复

### 10.1 备份

项目的 `backup` 目录映射为数据库容器中的 `/backup`：

```powershell
docker compose exec postgres pg_dump -U postgres -d study_db -f /backup/study_db.sql
Get-Item '.\backup\study_db.sql'
```

### 10.2 恢复到当前数据库

恢复前应确认备份文件来源可靠：

```powershell
docker compose exec postgres psql -U postgres -d study_db -f /backup/study_db.sql
```

如果备份中包含已经存在的对象，可能出现“对象已存在”。练习完整恢复时，建议新建一个空数据库：

```powershell
docker compose exec postgres createdb -U postgres study_restore
docker compose exec postgres psql -U postgres -d study_restore -f /backup/study_db.sql
```

## 11. pgAdmin 备份工具路径

pgAdmin 容器包含 PostgreSQL 12 的备份工具。如果 pgAdmin 的 Backup/Restore 界面提示找不到工具：

1. 打开 File > Preferences。
2. 找到 Paths > Binary paths。
3. PostgreSQL 12 Binary Path 填写：`/usr/local/pgsql-12`。
4. 保存后重试。

参考：[pgAdmin 容器部署文档](https://www.pgadmin.org/docs/pgadmin4/latest/container_deployment.html)。

## 12. 修改密码时的重要规则

PostgreSQL 官方镜像的 `POSTGRES_PASSWORD` 只在数据库卷首次初始化时生效。已有数据卷时，只修改 `.env` 不会修改数据库里的密码。

保留数据并修改数据库密码，应在 pgAdmin Query Tool 执行：

```sql
ALTER USER postgres WITH PASSWORD '新的强密码';
```

然后同步修改 `.env`。pgAdmin 登录密码同样不会因为修改 `.env` 自动变化；已有 pgAdmin 卷时，应在 pgAdmin 用户界面修改。

## 13. 常见问题排查

### 13.1 Docker Desktop 提示 WSL 太旧

```powershell
wsl --update
wsl --shutdown
```

重新启动 Docker Desktop。

### 13.2 Docker Engine 未运行

先打开 Docker Desktop，等待状态正常，再执行：

```powershell
docker info
```

仍失败时查看 Docker Desktop 的 Troubleshoot 页面，或重启电脑。

### 13.3 镜像拉取失败或超时

先检查网络：

```powershell
docker pull hello-world
```

如果公司网络使用代理，在 Docker Desktop > Settings > Resources/Proxies 中按实际网络配置代理。不要随意添加来源不明的镜像加速地址。

### 13.4 端口被占用

检查端口：

```powershell
netstat -ano | Select-String ':5432\s|:5050\s'
```

如有 TCP 监听，可在 `compose.yaml` 左侧修改 Windows 端口，例如：

```yaml
ports:
  - "127.0.0.1:15432:5432"
```

pgAdmin 也可改成 `127.0.0.1:15050:80`，修改后执行：

```powershell
docker compose up -d
```

### 13.5 pgAdmin 无法连接数据库

依次检查：

```powershell
docker compose ps
docker compose logs --tail=100 postgres
docker compose exec postgres pg_isready -U postgres -d study_db
```

确认 pgAdmin 连接主机为 `postgres`、端口为 `5432`、用户为 `postgres`。

### 13.6 修改 `.env` 后密码没有变化

这是持久化卷的正常行为，参考第 12 节。不要为了修改密码直接删除数据卷。

## 14. 完全重置学习数据库

> **高风险操作：下面命令会永久删除 PostgreSQL 数据和 pgAdmin 配置。只有明确不需要现有学习数据时才执行。**

先备份，再执行：

```powershell
Set-Location 'D:\docker_install\postgresql12-lab'
docker compose down -v
docker compose up -d
```

因为卷已删除，新的数据库会重新读取 `.env` 中的初始化密码。

## 15. 推荐学习顺序

1. 数据库、Schema、表、行和列的概念。
2. `CREATE TABLE` 与常用数据类型。
3. `INSERT`、`SELECT`、`UPDATE`、`DELETE`。
4. `WHERE`、排序、分页和聚合。
5. 主键、唯一约束、外键和检查约束。
6. 多表 `JOIN`。
7. 索引与 `EXPLAIN`。
8. 视图、函数和事务。
9. 用户、角色和权限。
10. `pg_dump`、恢复及 PostgreSQL 大版本升级概念。

## 16. 官方资料

- [Docker Desktop Windows 安装](https://docs.docker.com/desktop/setup/install/windows-install/)
- [Docker Desktop WSL 2 后端](https://docs.docker.com/desktop/features/wsl/)
- [微软 WSL 安装](https://learn.microsoft.com/windows/wsl/install)
- [PostgreSQL 官方 Docker 镜像](https://hub.docker.com/_/postgres)
- [PostgreSQL 12.22 文档](https://www.postgresql.org/docs/12/)
- [PostgreSQL 12.22 发布说明](https://www.postgresql.org/docs/12/release-12-22.html)
- [pgAdmin 容器部署](https://www.pgadmin.org/docs/pgadmin4/latest/container_deployment.html)