# PostgreSQL

**Repository Path**: jianmu-library/postgres

## Basic Information

- **Project Name**: PostgreSQL
- **Description**: PostgreSQL 17/18 基础镜像源码；使用建木 Hub 基础镜像和国内软件源，保留数据库初始化接口。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-08
- **Last Updated**: 2026-10-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PostgreSQL

建木镜像库的 PostgreSQL 基础镜像源码。数据库从 PostgreSQL 官方源码编译，基础系统来自 `docker.jianmuhub.com/library/alpine`，初始化入口基于 Docker Library PostgreSQL 的 MIT 许可源码。

## 版本和数据目录

| PostgreSQL | 镜像目标标签 | PGDATA | 持久卷挂载位置 |
|---|---|---|---|
| 17.11 | `docker.jianmuhub.com/library/postgres:17.11-alpine3.20` | `/var/lib/postgresql/data` | `/var/lib/postgresql/data` |
| 18.6 | `docker.jianmuhub.com/library/postgres:18.6-alpine3.20` | `/var/lib/postgresql/18/docker` | `/var/lib/postgresql` |

当前构建入口使用 `linux/amd64`。具体源码 URL、SHA256、基础镜像 digest 和编译选项记录在 [versions.json](versions.json)。镜像标签表示本仓库的构建目标；公开拉取以建木 Hub 的实际发布结果为准。

PostgreSQL 18 提供 `uuidv7()`；两个版本均包含 `pg_trgm`。保留 OpenSSL、ICU、readline、zlib，以及按当前编译选项构建的 contrib 扩展。当前未启用 LLVM/JIT、PLPerl/Python/Tcl、GSSAPI、LDAP、XML、uuid-ossp、LZ4、数据库后端 Zstandard，以及 PostgreSQL 18 的 libcurl/liburing 可选功能。

## 软件源与构建

Dockerfile 在安装任何包之前显式设置清华 HTTPS Alpine `v3.20/main` 和 `v3.20/community` 软件源，并升级基础系统包。可以通过 `--apk-mirror` 更换国内镜像。包下载遇到临时错误时最多尝试三次，仍失败则停止构建；HTTPS 和包签名校验始终开启。整个构建不依赖 Docker Hub 镜像，也不声明需要另行下载的 Dockerfile frontend 镜像。

在 Linux amd64 且已安装 Docker、Python 3.11+ 的机器运行：

```sh
python3 scripts/fetch-source.py
python3 scripts/build.py 17
python3 scripts/build.py 18
```

下载器校验固定 SHA256，已缓存且校验通过的源码不会重复下载。源码包保存在 `sources/`，不提交到 Git。Dockerfile 在编译前再次核对 SHA256。受限网络中也可以将已核验的同名官方源码包放到该目录。

```sh
python3 scripts/build.py 18 --apk-mirror https://mirrors.ustc.edu.cn/alpine --jobs 4
```

构建只产生本地镜像。发布前应先运行下面的验证，并使用建木 Hub 的现有发布流程；仓库不保存 registry 凭据，也不在提交源码时自动推送镜像。

Hub 自动构建使用仓库根目录作为 context，Dockerfile 路径分别为 `17/Dockerfile`、`18/Dockerfile`，目标平台为 `linux/amd64`。直接克隆后不需要预下载归档：Dockerfile 缓存未命中时会下载官方 HTTPS 源码并核验固定 SHA256。`PG_SOURCE_MIRROR` 可以指定采用相同目录结构的 HTTPS 镜像；传输失败时回退官方源，哈希不符则停止。操作系统包使用国内源，PostgreSQL 源码默认使用已验证可下载的官方源。

```sh
docker build --pull=false --platform linux/amd64 --build-arg BUILD_JOBS=4 -f 18/Dockerfile -t docker.jianmuhub.com/library/postgres:18.6-alpine3.20 .
```

本地脚本的 `--source-mirror` 同时传给下载器和 Dockerfile；`--download-in-build` 跳过预下载，交由 Dockerfile 使用缓存或下载源码。

## 初始化与运行

兼容 `POSTGRES_USER`、`POSTGRES_DB`、`POSTGRES_PASSWORD`、`POSTGRES_PASSWORD_FILE`、`POSTGRES_INITDB_ARGS`、`POSTGRES_HOST_AUTH_METHOD`、`PGDATA` 和 `/docker-entrypoint-initdb.d`。默认要求提供初始化密码，入口将数据库进程降为 postgres 用户。密码或凭证文件由部署环境提供，不放入仓库。

初始化脚本仅在数据目录为空时运行；已有数据库启动时不会再次执行。两个主版本的数据目录不可互换，升级应使用 PostgreSQL 支持的备份恢复或 `pg_upgrade` 流程。

## 验证

```sh
python3 tests/smoke.py --image docker.jianmuhub.com/library/postgres:17.11-alpine3.20 --major 17 --output evidence/17.json
python3 tests/smoke.py --image docker.jianmuhub.com/library/postgres:18.6-alpine3.20 --major 18 --output evidence/18.json
```

验证使用已经构建的镜像，禁止自动拉取，不映射宿主端口，并禁用容器外部网络。它检查版本、非 root 数据库进程、UTF-8 数据、初始化脚本、SCRAM 认证、`pg_trgm`、PostgreSQL 18 的 `uuidv7()`，以及重启后的持久数据和初始化脚本执行次数。临时容器、卷和密码文件只属于本次验证，结束后自动清理。

[2026-10-08 实际验证记录](docs/verification-2026-10-08.md)包含两个版本的构建和运行结果。

这些检查验证基础镜像能力。陆吾或建木的完整 Schema、服务运行与业务验收由各产品部署单独验证。

## 来源与许可

源自 [PostgreSQL](https://www.postgresql.org/) 和 [Docker Library PostgreSQL](https://github.com/docker-library/postgres)。入口脚本固定在 `d588a44673ea9d123c1acb1a6924de10a27fc315`；本仓库仅将其中的降权工具从 `gosu` 改为 Alpine 的 `su-exec`，其他初始化逻辑保留。许可及修改说明见 [LICENSE](LICENSE) 和 [NOTICE](NOTICE)。