这是用户在 2024-7-21 10:58 为 https://github.com/docker-library/docs/blob/master/postgres/README.md 保存的双语快照页面,由 沉浸式翻译 提供双语支持。了解如何保存?
Skip to content

Files

Latest commit

c23bb7f · Jul 9, 2024

History

History
416 lines (256 loc) · 30.3 KB

README.md

File metadata and controls

416 lines (256 loc) · 30.3 KB

Quick reference 快速参考

Supported tags and respective Dockerfile links
支持的标签和相应的 Dockerfile 链接

Quick reference (cont.)

What is PostgreSQL? 什么是PostgreSQL?

PostgreSQL, often simply "Postgres", is an object-relational database management system (ORDBMS) with an emphasis on extensibility and standards-compliance. As a database server, its primary function is to store data, securely and supporting best practices, and retrieve it later, as requested by other software applications, be it those on the same computer or those running on another computer across a network (including the Internet). It can handle workloads ranging from small single-machine applications to large Internet-facing applications with many concurrent users. Recent versions also provide replication of the database itself for security and scalability.
PostgreSQL,通常简称为“Postgres”,是一个对象关系数据库管理系统(RDBMS),强调可扩展性和标准兼容性。作为数据库服务器,其主要功能是安全地存储数据并支持最佳实践,然后根据其他软件应用程序的请求检索数据,无论是同一台计算机上的应用程序还是跨网络(包括Internet)在另一台计算机上运行的应用程序。它可以处理从小型单机应用程序到具有许多并发用户的大型面向Internet的应用程序的工作负载。最新版本还提供了数据库本身的复制,以确保安全性和可伸缩性。

PostgreSQL implements the majority of the SQL:2011 standard, is ACID-compliant and transactional (including most DDL statements) avoiding locking issues using multiversion concurrency control (MVCC), provides immunity to dirty reads and full serializability; handles complex SQL queries using many indexing methods that are not available in other databases; has updateable views and materialized views, triggers, foreign keys; supports functions and stored procedures, and other expandability, and has a large number of extensions written by third parties. In addition to the possibility of working with the major proprietary and open source databases, PostgreSQL supports migration from them, by its extensive standard SQL support and available migration tools. And if proprietary extensions had been used, by its extensibility that can emulate many through some built-in and third-party open source compatibility extensions, such as for Oracle.
PostgreSQL实现了大多数SQL:2011标准,是ACID兼容的和事务性的(包括大多数SQL语句)使用多版本并发控制(MVCC)避免锁定问题,提供对脏读和完全可串行化的免疫力;使用许多其他数据库中不可用的索引方法处理复杂的SQL查询;具有可更新的视图和物化视图,触发器,外键;支持函数和存储过程以及其他可扩展性,并具有大量由第三方编写的扩展。除了可以使用主要的专有和开源数据库外,PostgreSQL还通过其广泛的标准SQL支持和可用的迁移工具支持从它们迁移。而如果已经使用了专有扩展,通过它的扩展性,可以通过一些内置的和第三方开源兼容的扩展来模仿很多,比如针对Oracle。

wikipedia.org/wiki/PostgreSQL

logo

How to use this image
如何使用此图像

start a postgres instance
启动一个postgres实例

$ docker run --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword -d postgres

The default postgres user and database are created in the entrypoint with initdb.
默认的 postgres 用户和数据库在入口点中使用 initdb 创建。

The postgres database is a default database meant for use by users, utilities and third party applications.
postgres数据库是一个默认的数据库,供用户、实用程序和第三方应用程序使用。

postgresql.org/docs

... or via psql ...或通过 psql

$ docker run -it --rm --network some-network postgres psql -h some-postgres -U postgres
psql (14.3)
Type "help" for help.

postgres=# SELECT 1;
 ?column? 
----------
        1
(1 row)

... via docker-compose or docker stack deploy
...通过 docker-composedocker stack deploy

Example docker-compose.yml for postgres:
示例 docker-compose.yml 用于 postgres

# Use postgres/example user/password credentials
version: '3.9'

services:

  db:
    image: postgres
    restart: always
    # set shared memory limit when using docker-compose
    shm_size: 128mb
    # or set shared memory limit when deploy via swarm stack
    #volumes:
    #  - type: tmpfs
    #    target: /dev/shm
    #    tmpfs:
    #      size: 134217728 # 128*2^20 bytes = 128Mb
    environment:
      POSTGRES_PASSWORD: example

  adminer:
    image: adminer
    restart: always
    ports:
      - 8080:8080

Try in PWD

Run docker stack deploy -c stack.yml postgres (or docker-compose -f stack.yml up), wait for it to initialize completely, and visit http://swarm-ip:8080, http://localhost:8080, or http://host-ip:8080 (as appropriate).
运行 docker stack deploy -c stack.yml postgres (或 docker-compose -f stack.yml up ),等待其完全初始化,然后访问 http://swarm-ip:8080http://localhost:8080http://host-ip:8080 (视情况而定)。

How to extend this image
如何延伸这一形象

There are many ways to extend the postgres image. Without trying to support every possible use case, here are just a few that we have found useful.
有很多方法可以扩展 postgres 图像。在不试图支持每一个可能的用例的情况下,这里只是我们发现有用的几个。

Environment Variables 环境变量

The PostgreSQL image uses several environment variables which are easy to miss. The only variable required is POSTGRES_PASSWORD, the rest are optional.
PostgreSQL镜像使用了几个容易被忽略的环境变量。唯一需要的变量是 POSTGRES_PASSWORD ,其余都是可选的。

Warning: the Docker specific variables will only have an effect if you start the container with a data directory that is empty; any pre-existing database will be left untouched on container startup.
警告:Docker特定的变量只有在你用空的数据目录启动容器时才有效;任何预先存在的数据库在容器启动时都不会被触及。

POSTGRES_PASSWORD

This environment variable is required for you to use the PostgreSQL image. It must not be empty or undefined. This environment variable sets the superuser password for PostgreSQL. The default superuser is defined by the POSTGRES_USER environment variable.
这个环境变量是使用PostgreSQL镜像所必需的。它不能为空或未定义。这个环境变量设置PostgreSQL的超级用户密码。默认的超级用户由 POSTGRES_USER 环境变量定义。

Note 1: The PostgreSQL image sets up trust authentication locally so you may notice a password is not required when connecting from localhost (inside the same container). However, a password will be required if connecting from a different host/container.
注一:PostgreSQL镜像在本地设置了 trust 身份验证,所以你可能会注意到从 localhost (在同一个容器内)连接时不需要密码。但是,如果从不同的主机/容器连接,则需要密码。

Note 2: This variable defines the superuser password in the PostgreSQL instance, as set by the initdb script during initial container startup. It has no effect on the PGPASSWORD environment variable that may be used by the psql client at runtime, as described at https://www.postgresql.org/docs/14/libpq-envars.html. PGPASSWORD, if used, will be specified as a separate environment variable.
注2:此变量定义PostgreSQL实例中的超级用户密码,由初始容器启动期间的 initdb 脚本设置。它对运行时可能由 psql 客户端使用的 PGPASSWORD 环境变量没有影响,如https://www.postgresql.org/docs/14/libpq-envars.html所述。 PGPASSWORD ,如果使用,将被指定为一个单独的环境变量。

POSTGRES_USER

This optional environment variable is used in conjunction with POSTGRES_PASSWORD to set a user and its password. This variable will create the specified user with superuser power and a database with the same name. If it is not specified, then the default user of postgres will be used.
这个可选的环境变量与 POSTGRES_PASSWORD 一起使用来设置用户及其密码。此变量将创建具有超级用户权限的指定用户和具有相同名称的数据库。如果未指定,则将使用默认用户 postgres

Be aware that if this parameter is specified, PostgreSQL will still show The files belonging to this database system will be owned by user "postgres" during initialization. This refers to the Linux system user (from /etc/passwd in the image) that the postgres daemon runs as, and as such is unrelated to the POSTGRES_USER option. See the section titled "Arbitrary --user Notes" for more details.
请注意,如果指定了此参数,PostgreSQL在初始化期间仍将显示 The files belonging to this database system will be owned by user "postgres" 。这是指运行 postgres 守护程序的Linux系统用户(来自映像中的 /etc/passwd ),因此与 POSTGRES_USER 选项无关。有关详细信息,请参阅标题为“任意 --user 注释”的部分。

POSTGRES_DB

This optional environment variable can be used to define a different name for the default database that is created when the image is first started. If it is not specified, then the value of POSTGRES_USER will be used.
此可选环境变量可用于为首次启动映像时创建的默认数据库定义不同的名称。如果未指定,则将使用 POSTGRES_USER 的值。

POSTGRES_INITDB_ARGS

This optional environment variable can be used to send arguments to postgres initdb. The value is a space separated string of arguments as postgres initdb would expect them. This is useful for adding functionality like data page checksums: -e POSTGRES_INITDB_ARGS="--data-checksums".
这个可选的环境变量可以用来向 postgres initdb 发送参数。该值是一个空格分隔的参数字符串,正如 postgres initdb 所期望的那样。这对于添加数据页校验和等功能很有用: -e POSTGRES_INITDB_ARGS="--data-checksums"

POSTGRES_INITDB_WALDIR

This optional environment variable can be used to define another location for the Postgres transaction log. By default the transaction log is stored in a subdirectory of the main Postgres data folder (PGDATA). Sometimes it can be desireable to store the transaction log in a different directory which may be backed by storage with different performance or reliability characteristics.
这个可选的环境变量可用于为Postgres事务日志定义另一个位置。默认情况下,事务日志存储在主Postgres数据文件夹的目录中( PGDATA )。有时可能需要将事务日志存储在不同的目录中,该目录可能由具有不同性能或可靠性特征的存储支持。

Note: on PostgreSQL 9.x, this variable is POSTGRES_INITDB_XLOGDIR (reflecting the changed name of the --xlogdir flag to --waldir in PostgreSQL 10+).
注意:在PostgreSQL 9.x上,这个变量是 POSTGRES_INITDB_XLOGDIR (反映了在PostgreSQL 10+中 --xlogdir 标志的名称更改为 --waldir )。

POSTGRES_HOST_AUTH_METHOD

This optional variable can be used to control the auth-method for host connections for all databases, all users, and all addresses. If unspecified then scram-sha-256 password authentication is used (in 14+; md5 in older releases). On an uninitialized database, this will populate pg_hba.conf via this approximate line:
此可选变量可用于控制 all 数据库、 all 用户和 all 地址的 auth-method for host 连接。如果未指定,则使用 scram-sha-256 密码身份验证(在14+中;在旧版本中为 md5 )。在一个未初始化的数据库上,这将通过以下近似行填充 pg_hba.conf

echo "host all all all $POSTGRES_HOST_AUTH_METHOD" >> pg_hba.conf

See the PostgreSQL documentation on pg_hba.conf for more information about possible values and their meanings.
有关可能的值及其含义的更多信息,请参阅 pg_hba.conf 上的PostgreSQL文档。

Note 1: It is not recommended to use trust since it allows anyone to connect without a password, even if one is set (like via POSTGRES_PASSWORD). For more information see the PostgreSQL documentation on Trust Authentication.
注1:不建议使用 trust ,因为它允许任何人在没有密码的情况下连接,即使设置了密码(如通过 POSTGRES_PASSWORD )。有关更多信息,请参阅PostgreSQL文档信任身份验证。

Note 2: If you set POSTGRES_HOST_AUTH_METHOD to trust, then POSTGRES_PASSWORD is not required.
注2:如果您将 POSTGRES_HOST_AUTH_METHOD 设置为 trust ,则不需要 POSTGRES_PASSWORD

Note 3: If you set this to an alternative value (such as scram-sha-256), you might need additional POSTGRES_INITDB_ARGS for the database to initialize correctly (such as POSTGRES_INITDB_ARGS=--auth-host=scram-sha-256).
注3:如果您将其设置为其他值(例如 scram-sha-256 ),则可能需要额外的 POSTGRES_INITDB_ARGS 才能正确初始化数据库(例如 POSTGRES_INITDB_ARGS=--auth-host=scram-sha-256 )。

PGDATA

Important Note: when mounting a volume to /var/lib/postgresql, the /var/lib/postgresql/data path is a local volume from the container runtime, thus data is not persisted on the mounted volume.
重要提示:当将卷挂载到 /var/lib/postgresql 时, /var/lib/postgresql/data 路径是来自容器运行时的本地卷,因此数据不会持久存储在挂载的卷上。

This optional variable can be used to define another location - like a subdirectory - for the database files. The default is /var/lib/postgresql/data. If the data volume you're using is a filesystem mountpoint (like with GCE persistent disks), or remote folder that cannot be chowned to the postgres user (like some NFS mounts), or contains folders/files (e.g. lost+found), Postgres initdb requires a subdirectory to be created within the mountpoint to contain the data.
这个可选变量可用于为数据库文件定义另一个位置(如目录)。默认值为 /var/lib/postgresql/data 。如果你使用的数据卷是一个文件系统挂载点(比如GCE持久化磁盘),或者是一个不能由 postgres 用户拥有的远程文件夹(比如一些NFS挂载),或者包含文件夹/文件(比如 lost+found ),那么Postgres initdb 需要在挂载点中创建一个目录来包含数据。

For example: 举例来说:

$ docker run -d \
	--name some-postgres \
	-e POSTGRES_PASSWORD=mysecretpassword \
	-e PGDATA=/var/lib/postgresql/data/pgdata \
	-v /custom/mount:/var/lib/postgresql/data \
	postgres

This is an environment variable that is not Docker specific. Because the variable is used by the postgres server binary (see the PostgreSQL docs), the entrypoint script takes it into account.
这是一个非Docker特定的环境变量。由于该变量由 postgres 服务器二进制文件使用(参见PostgreSQL文档),因此入口点脚本会将其考虑在内。

Docker Secrets

As an alternative to passing sensitive information via environment variables, _FILE may be appended to some of the previously listed environment variables, causing the initialization script to load the values for those variables from files present in the container. In particular, this can be used to load passwords from Docker secrets stored in /run/secrets/<secret_name> files. For example:
作为通过环境变量传递敏感信息的替代方案, _FILE 可以附加到前面列出的一些环境变量中,导致初始化脚本从容器中存在的文件加载这些变量的值。特别是,这可以用于从存储在 /run/secrets/<secret_name> 文件中的Docker secret加载密码。举例来说:

$ docker run --name some-postgres -e POSTGRES_PASSWORD_FILE=/run/secrets/postgres-passwd -d postgres

Currently, this is only supported for POSTGRES_INITDB_ARGS, POSTGRES_PASSWORD, POSTGRES_USER, and POSTGRES_DB.
目前仅支持 POSTGRES_INITDB_ARGSPOSTGRES_PASSWORDPOSTGRES_USERPOSTGRES_DB

Initialization scripts 初始化脚本

If you would like to do additional initialization in an image derived from this one, add one or more *.sql, *.sql.gz, or *.sh scripts under /docker-entrypoint-initdb.d (creating the directory if necessary). After the entrypoint calls initdb to create the default postgres user and database, it will run any *.sql files, run any executable *.sh scripts, and source any non-executable *.sh scripts found in that directory to do further initialization before starting the service.
如果您希望在从该映像派生的映像中执行其他初始化,请在 /docker-entrypoint-initdb.d 下添加一个或多个 *.sql*.sql.gz*.sh 脚本(如有必要,请创建目录)。在入口点调用 initdb 以创建默认的 postgres 用户和数据库之后,它将运行任何 *.sql 文件,运行任何可执行的 *.sh 脚本,并在启动服务之前获取在该目录中找到的任何不可执行的 *.sh 脚本以进行进一步的初始化。

Warning: scripts in /docker-entrypoint-initdb.d are only run if you start the container with a data directory that is empty; any pre-existing database will be left untouched on container startup. One common problem is that if one of your /docker-entrypoint-initdb.d scripts fails (which will cause the entrypoint script to exit) and your orchestrator restarts the container with the already initialized data directory, it will not continue on with your scripts.
警告:只有当你用空的数据目录启动容器时, /docker-entrypoint-initdb.d 中的脚本才会运行;任何预先存在的数据库在容器启动时都不会被触及。一个常见问题是,如果您的 /docker-entrypoint-initdb.d 脚本之一失败(这将导致入口点脚本退出)并且您的编排器使用已初始化的数据目录重新启动容器,则它将不会继续使用您的脚本。

For example, to add an additional user and database, add the following to /docker-entrypoint-initdb.d/init-user-db.sh:
例如,要添加其他用户和数据库,请将以下内容添加到 /docker-entrypoint-initdb.d/init-user-db.sh

#!/bin/bash
set -e

psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" --dbname "$POSTGRES_DB" <<-EOSQL
	CREATE USER docker;
	CREATE DATABASE docker;
	GRANT ALL PRIVILEGES ON DATABASE docker TO docker;
EOSQL

These initialization files will be executed in sorted name order as defined by the current locale, which defaults to en_US.utf8. Any *.sql files will be executed by POSTGRES_USER, which defaults to the postgres superuser. It is recommended that any psql commands that are run inside of a *.sh script be executed as POSTGRES_USER by using the --username "$POSTGRES_USER" flag. This user will be able to connect without a password due to the presence of trust authentication for Unix socket connections made inside the container.
这些初始化文件将按照当前区域设置(默认为 en_US.utf8 )定义的排序名称顺序执行。任何 *.sql 文件将由 POSTGRES_USER 执行,默认为 postgres 超级用户。建议在 *.sh 脚本中运行的任何 psql 命令都使用 --username "$POSTGRES_USER" 标志作为 POSTGRES_USER 执行。由于容器内存在Unix套接字连接的 trust 身份验证,因此该用户将能够在没有密码的情况下进行连接。

Additionally, as of docker-library/postgres#253, these initialization scripts are run as the postgres user (or as the "semi-arbitrary user" specified with the --user flag to docker run; see the section titled "Arbitrary --user Notes" for more details). Also, as of docker-library/postgres#440, the temporary daemon started for these initialization scripts listens only on the Unix socket, so any psql usage should drop the hostname portion (see docker-library/postgres#474 (comment) for example).
此外,从docker-library/postgres#253开始,这些初始化脚本将以 postgres 用户(或使用 --user 标记指定为 docker run 的“半任意用户”;有关更多详细信息,请参阅标题为“任意 --user 注释”的部分)运行。此外,从docker-library/postgres#440开始,为这些初始化脚本启动的临时守护进程只监听Unix套接字,因此任何 psql 用法都应该删除主机名部分(例如,请参阅docker-library/postgres#474(注释))。

Database Configuration 数据库配置

There are many ways to set PostgreSQL server configuration. For information on what is available to configure, see the PostgreSQL docs for the specific version of PostgreSQL that you are running. Here are a few options for setting configuration:
有很多方法可以设置PostgreSQL服务器配置。有关可配置内容的信息,请参阅您正在运行的特定PostgreSQL版本的PostgreSQL文档。以下是用于设置配置的几个选项:

  • Use a custom config file. Create a config file and get it into the container. If you need a starting place for your config file you can use the sample provided by PostgreSQL which is available in the container at /usr/share/postgresql/postgresql.conf.sample (/usr/local/share/postgresql/postgresql.conf.sample in Alpine variants).
    使用自定义配置文件。创建一个配置文件并将其放入容器中。如果你需要一个配置文件的起始位置,你可以使用PostgreSQL提供的示例,它可以在容器中找到,地址是 /usr/share/postgresql/postgresql.conf.sample (在Alpine变体中是 /usr/local/share/postgresql/postgresql.conf.sample )。

    • Important note: you must set listen_addresses = '*'so that other containers will be able to access postgres.
      重要提示:您必须设置 listen_addresses = '*' ,以便其他容器能够访问postgres。
    $ # get the default config
    $ docker run -i --rm postgres cat /usr/share/postgresql/postgresql.conf.sample > my-postgres.conf
    
    $ # customize the config
    
    $ # run postgres with custom config
    $ docker run -d --name some-postgres -v "$PWD/my-postgres.conf":/etc/postgresql/postgresql.conf -e POSTGRES_PASSWORD=mysecretpassword postgres -c 'config_file=/etc/postgresql/postgresql.conf'
  • Set options directly on the run line. The entrypoint script is made so that any options passed to the docker command will be passed along to the postgres server daemon. From the PostgreSQL docs we see that any option available in a .conf file can be set via -c.
    直接在管路上设置选项。创建入口点脚本,以便将传递给docker命令的任何选项都沿着传递给 postgres 服务器守护进程。从PostgreSQL文档中我们可以看到,任何在 .conf 文件中可用的选项都可以通过 -c 设置。

    $ docker run -d --name some-postgres -e POSTGRES_PASSWORD=mysecretpassword postgres -c shared_buffers=256MB -c max_connections=200

Locale Customization 区域设置自定义

You can extend the Debian-based images with a simple Dockerfile to set a different locale. The following example will set the default locale to de_DE.utf8:
您可以使用简单的 Dockerfile 来扩展基于Debian的映像,以设置不同的区域设置。下面的示例将默认区域设置为 de_DE.utf8

FROM postgres:14.3
RUN localedef -i de_DE -c -f UTF-8 -A /usr/share/locale/locale.alias de_DE.UTF-8
ENV LANG de_DE.utf8

Since database initialization only happens on container startup, this allows us to set the language before it is created.
由于数据库初始化只发生在容器启动时,这允许我们在创建之前设置语言。

Also of note, Alpine-based variants starting with Postgres 15 support ICU locales. Previous Postgres versions based on alpine do not support locales; see "Character sets and locale" in the musl documentation for more details.
同样值得注意的是,从Postgres 15开始的基于Alpine的变体支持ICU语言环境。之前基于alpine的Postgres版本不支持语言环境;有关更多详细信息,请参阅musl文档中的“字符集和语言环境”。

You can set locales in the Alpine-based images with POSTGRES_INITDB_ARGS to set a different locale. The following example will set the default locale for a newly initialized database to de_DE.utf8:
您可以使用 POSTGRES_INITDB_ARGS 在基于Alpine的图像中设置区域设置,以设置不同的区域设置。下面的示例将新初始化的数据库的默认区域设置为 de_DE.utf8

$ docker run -d -e LANG=de_DE.utf8 -e POSTGRES_INITDB_ARGS="--locale-provider=icu --icu-locale=de-DE" -e POSTGRES_PASSWORD=mysecretpassword postgres:15-alpine 

Additional Extensions 附加扩展

When using the default (Debian-based) variants, installing additional extensions (such as PostGIS) should be as simple as installing the relevant packages (see github.com/postgis/docker-postgis for a concrete example).
当使用默认的(基于Debian的)变体时,安装附加的扩展(比如PostGIS)应该和安装相关的软件包一样简单(具体的例子请参见github.com/postgis/docker-postgis)。

When using the Alpine variants, any postgres extension not listed in postgres-contrib will need to be compiled in your own image (again, see github.com/postgis/docker-postgis for a concrete example).
当使用Alpine变体时,任何未在postgres-contrib中列出的postgres扩展都需要在您自己的镜像中编译(同样,请参阅github.com/postgis/docker-postgis以获取具体示例)。

Arbitrary --user Notes 任意 --user 注释

As of docker-library/postgres#253, this image supports running as a (mostly) arbitrary user via --user on docker run. As of docker-library/postgres#1018, this is also the case for the Alpine variants.
自docker-library/postgres#253起,此镜像支持以(大多数)任意用户身份通过 --user on docker run 运行。从docker-library/postgres#1018开始,Alpine变体也是如此。

The main caveat to note is that postgres doesn't care what UID it runs as (as long as the owner of /var/lib/postgresql/data matches), but initdb does care (and needs the user to exist in /etc/passwd):
需要注意的主要警告是, postgres 不关心它以什么UID运行(只要 /var/lib/postgresql/data 的所有者匹配),但 initdb 确实关心(并且需要用户存在于 /etc/passwd 中):

$ docker run -it --rm --user www-data -e POSTGRES_PASSWORD=mysecretpassword postgres
The files belonging to this database system will be owned by user "www-data".
...

$ docker run -it --rm --user 1000:1000 -e POSTGRES_PASSWORD=mysecretpassword postgres
initdb: could not look up effective user ID 1000: user does not exist

The three easiest ways to get around this:
三个最简单的方法来解决这个问题:

  1. allow the image to use the nss_wrapper library to "fake" /etc/passwd contents for you (see docker-library/postgres#448 for more details)
    允许图像使用 nss_wrapper 库为您“伪造” /etc/passwd 内容(有关更多详细信息,请参阅docker-library/postgres#448)

  2. bind-mount /etc/passwd read-only from the host (if the UID you desire is a valid user on your host):
    bind-mount /etc/passwd 从主机只读(如果您想要的UID是您主机上的有效用户):

    $ docker run -it --rm --user "$(id -u):$(id -g)" -v /etc/passwd:/etc/passwd:ro -e POSTGRES_PASSWORD=mysecretpassword postgres
    The files belonging to this database system will be owned by user "jsmith".
    ...
  3. initialize the target directory separately from the final runtime (with a chown in between):
    与最终运行时单独初始化目标目录(中间有 chown ):

    $ docker volume create pgdata
    $ docker run -it --rm -v pgdata:/var/lib/postgresql/data -e POSTGRES_PASSWORD=mysecretpassword postgres
    The files belonging to this database system will be owned by user "postgres".
    ...
    ( once it's finished initializing successfully and is waiting for connections, stop it )
    $ docker run -it --rm -v pgdata:/var/lib/postgresql/data bash chown -R 1000:1000 /var/lib/postgresql/data
    $ docker run -it --rm --user 1000:1000 -v pgdata:/var/lib/postgresql/data postgres
    LOG:  database system was shut down at 2017-01-20 00:03:23 UTC
    LOG:  MultiXact member wraparound protections are now enabled
    LOG:  autovacuum launcher started
    LOG:  database system is ready to accept connections

Caveats 警告

If there is no database when postgres starts in a container, then postgres will create the default database for you. While this is the expected behavior of postgres, this means that it will not accept incoming connections during that time. This may cause issues when using automation tools, such as docker-compose, that start several containers simultaneously.
如果在容器中启动 postgres 时没有数据库,则 postgres 将为您创建默认数据库。虽然这是 postgres 的预期行为,但这意味着它在此期间不会接受传入连接。当使用自动化工具(如 docker-compose )同时启动多个容器时,这可能会导致问题。

Also note that the default /dev/shm size for containers is 64MB. If the shared memory is exhausted you will encounter ERROR: could not resize shared memory segment . . . : No space left on device. You will want to pass --shm-size=256MB for example to docker run, or alternatively in docker-compose.
还请注意,容器的默认 /dev/shm 大小为64MB。如果共享内存耗尽,您将遇到 ERROR: could not resize shared memory segment . . . : No space left on device 。例如,您可能希望将 --shm-size=256MB 传递给 docker run ,或者在 docker-compose 中传递。

Where to Store Data 在何处存储数据

Important note: There are several ways to store data used by applications that run in Docker containers. We encourage users of the postgres images to familiarize themselves with the options available, including:
重要提示:有几种方法可以存储在Docker容器中运行的应用程序所使用的数据。我们鼓励 postgres 图像的用户熟悉可用的选项,包括:

  • Let Docker manage the storage of your database data by writing the database files to disk on the host system using its own internal volume management. This is the default and is easy and fairly transparent to the user. The downside is that the files may be hard to locate for tools and applications that run directly on the host system, i.e. outside containers.
    让Docker管理数据库数据的存储,方法是使用自己的内部卷管理将数据库文件写入主机系统上的磁盘。这是默认设置,对用户来说很容易且相当透明。缺点是,对于直接在主机系统上运行的工具和应用程序(即外部容器),这些文件可能很难找到。
  • Create a data directory on the host system (outside the container) and mount this to a directory visible from inside the container. This places the database files in a known location on the host system, and makes it easy for tools and applications on the host system to access the files. The downside is that the user needs to make sure that the directory exists, and that e.g. directory permissions and other security mechanisms on the host system are set up correctly.
    在主机系统上(容器外部)创建一个数据目录,并将其挂载到从容器内部可见的目录中。这将数据库文件放置在主机系统上的已知位置,并使主机系统上的工具和应用程序可以轻松访问这些文件。缺点是用户需要确保目录存在,并且在主机系统上正确设置了目录权限和其他安全机制。

The Docker documentation is a good starting point for understanding the different storage options and variations, and there are multiple blogs and forum postings that discuss and give advice in this area. We will simply show the basic procedure here for the latter option above:
Docker文档是了解不同存储选项和变体的良好起点,有多个博客和论坛帖子讨论并提供这方面的建议。我们将简单地展示上面后一个选项的基本过程:

  1. Create a data directory on a suitable volume on your host system, e.g. /my/own/datadir.
    在主机系统上的适当卷上创建数据目录,例如 /my/own/datadir

  2. Start your postgres container like this:
    像这样启动 postgres 容器:

    $ docker run --name some-postgres -v /my/own/datadir:/var/lib/postgresql/data -e POSTGRES_PASSWORD=mysecretpassword -d postgres:tag

The -v /my/own/datadir:/var/lib/postgresql/data part of the command mounts the /my/own/datadir directory from the underlying host system as /var/lib/postgresql/data inside the container, where PostgreSQL by default will write its data files.
命令的 -v /my/own/datadir:/var/lib/postgresql/data 部分将底层主机系统的 /my/own/datadir 目录挂载为容器内的 /var/lib/postgresql/data 目录,PostgreSQL默认将在其中写入其数据文件。

Image Variants 图像变量

The postgres images come in many flavors, each designed for a specific use case.
postgres 镜像有多种风格,每种都是针对特定用例设计的。

postgres:<version>

This is the defacto image. If you are unsure about what your needs are, you probably want to use this one. It is designed to be used both as a throw away container (mount your source code and start the container to start your app), as well as the base to build other images off of.
这是事实上的形象。如果你不确定你的需求是什么,你可能想使用这个。它被设计为既可以用作丢弃容器(挂载源代码并启动容器以启动应用程序),也可以用作构建其他镜像的基础。

Some of these tags may have names like bookworm or bullseye in them. These are the suite code names for releases of Debian and indicate which release the image is based on. If your image needs to install any additional packages beyond what comes with the image, you'll likely want to specify one of these explicitly to minimize breakage when there are new releases of Debian.
这些标签中的一些可能有像书呆子或靶心这样的名字。这些是Debian发行版的套件代号,表示映像基于哪个发行版。如果您的映像需要安装映像附带的软件包之外的任何其他软件包,您可能需要明确指定其中一个,以在有新的Debian发行版时最大限度地减少损坏。

postgres:<version>-alpine

This image is based on the popular Alpine Linux project, available in the alpine official image. Alpine Linux is much smaller than most distribution base images (~5MB), and thus leads to much slimmer images in general.
此映像基于流行的Alpine Linux项目,在 alpine 官方映像中提供。Alpine Linux比大多数发行版基础映像(~ 5 MB)小得多,因此通常会导致更苗条的映像。

This variant is useful when final image size being as small as possible is your primary concern. The main caveat to note is that it does use musl libc instead of glibc and friends, so software will often run into issues depending on the depth of their libc requirements/assumptions. See this Hacker News comment thread for more discussion of the issues that might arise and some pro/con comparisons of using Alpine-based images.
当您主要关心的是最终图像尺寸尽可能小时,此变体非常有用。需要注意的主要警告是,它确实使用musl libc而不是glibc和friends,因此软件经常会遇到问题,这取决于他们的libc需求/假设的深度。请参阅此Hacker News评论线程,以了解可能出现的问题的更多讨论以及使用基于Alpine的图像的一些利弊比较。

To minimize image size, it's uncommon for additional related tools (such as git or bash) to be included in Alpine-based images. Using this image as a base, add the things you need in your own Dockerfile (see the alpine image description for examples of how to install packages if you are unfamiliar).
为了最小化图像大小,在基于Alpine的图像中包含其他相关工具(例如 gitbash )是不常见的。使用这个镜像作为基础,在你自己的Dockerfile中添加你需要的东西(如果你不熟悉如何安装包,请参阅 alpine 镜像描述的示例)。

License 许可证

View license information for the software contained in this image.
查看此映像中包含的软件的许可证信息。

As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).
与所有Docker镜像一样,这些镜像也可能包含其他软件,这些软件可能在其他许可证下(例如来自基础发行版的Bash等,沿着所包含的主软件的任何直接或间接依赖项)。

Some additional license information which was able to be auto-detected might be found in the repo-info repository's postgres/ directory.
可以在 repo-info 存储库的 postgres/ 目录中找到一些能够自动检测的其他许可证信息。

As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.
对于任何预建映像的使用,映像用户有责任确保此映像的任何使用符合其中包含的所有软件的任何相关许可。