Skip to main content

Deploying with Docker

warning警告

This documentation has not yet been tested with PostGraphile V5. Please get in touch if you have used it!

本文档尚未在 PostGraphile V5 中经过完整实测。如果你已在实际项目中使用过相关方案,欢迎与我们联系反馈!

PostGraphile has an official Docker image which is suitable to use if you don't need custom plugins and are deploying PostGraphile as standalone:

如果你不需要自定义插件,且希望独立部署 PostGraphile,可以直接使用官方 Docker 镜像:

Our Docker images are versioned:

官方 Docker 镜像按以下规则进行版本标记:

  • graphile/postgraphile:5 will give you the latest stable in the "v5.x.x" line (no alphas, betas, rcs); this is the recommended version to use

    graphile/postgraphile:5 指向“v5.x.x”分支中最新的稳定版(不包含 alpha、beta、rc 版本);推荐优先使用该标签

  • Every new versioned git tag will be available using the exact same tag; e.g. v5.6.7-alpha.8 would become graphile/postgraphile:v5.6.7-alpha.8

    每个带版本号的新 git tag 都会对应生成一个同名镜像标签;例如 v5.6.7-alpha.8 会发布为 graphile/postgraphile:v5.6.7-alpha.8

  • Every new vX.Y.Z git tag (i.e. no alpha/beta/rc) will automatically release graphile/postgraphile:X-Y and graphile/postgraphile:X-Y-Z

    每个正式版 vX.Y.Z git tag(即不含 alpha/beta/rc 后缀)都会自动发布 graphile/postgraphile:X-Y 与 graphile/postgraphile:X-Y-Z 两个镜像标签

  • graphile/postgraphile:latest will give you the latest stable (but beware of major version bumps!)

    graphile/postgraphile:latest 指向最新的稳定版(但请注意,它可能会跨越主版本升级!)

  • graphile/postgraphile:next will give you the equivalent of what's on master right now (i.e. pre-release/bleeding edge/nightly)

    graphile/postgraphile:next 对应 master 分支的当前最新代码(即预发布 / 前沿构建 / nightly 版本)

From time to time graphile/postgraphile:5 may lag behind where it should be because it's the only manual step in the above. If this happens, give Benjie a poke over Discord and he'll push the latest v5.x.y tag to the v5 branch via git push origin v5.x.y:v5.

由于上述流程中只有 graphile/postgraphile:5 需要手动更新,它偶尔可能会稍微滞后于最新版本。如果遇到这种情况,可以在 Discord 上提醒 Benjie,他会通过 git push origin v5.x.y:v5 将最新的 v5.x.y 标签推送到 v5 分支。

A request was made for clarification on why there are Docker versions with dots and other Docker versions with dashes; hopefully this clears things up:

曾有用户询问为什么有些 Docker 标签使用点号(.)而另一些使用短横线(-),这里统一说明一下:

  • X and X-Y are the versions that you should use, they will be updated over time with compatible bug fixes.

    X 和 X-Y 是日常推荐使用的标签,它们会随着兼容的 Bug 修复持续更新。

  • X-Y-Z for completeness, and may include alpha/beta/etc versions of that specific release in future

    X-Y-Z 用于补全具体小版本标签,未来可能会包含该特定版本的 alpha/beta 等预发布构建

  • vX.Y.Z-foo.A or whatever are the explicit git tags which will only ever build once and will not be kept up to date as the project advances. Use these if you need to pin an explicit version... explicitly.

    vX.Y.Z-foo.A 等对应精确的 git tag,它们只会构建一次,之后不会随项目推进而更新。当你需要严格锁定到某个精确版本时,可以使用这类标签。

Custom Dockerfile自定义 Dockerfile​

Should you want to deploy a more custom app then a custom Dockerfile is likely in order. To reduce the size of your final image, we recommend using a multi-stage build.

如果你需要部署高度定制化的应用,通常需要编写自定义 Dockerfile。为了减小最终镜像体积,建议采用多阶段构建(multi-stage build)。

There's a few critical things to keep in mind:

有几个关键细节需要注意:

  • PostGraphile CLI listens, by default, on localhost; you may need to override this, e.g. with preset.grafserv.host = "0.0.0.0"

    PostGraphile CLI 默认仅监听 localhost;在容器环境中通常需要覆盖此配置,例如设置 preset.grafserv.host = "0.0.0.0"

  • PostGraphile needs to be able to connect to your database; ensure that Docker is networked such that this is possible

    PostGraphile 必须能够访问你的数据库;请确保 Docker 网络配置允许容器连接到数据库服务

To speed up builds, we recommend you pay attention to your .dockerignore file; here's an example to get you started:

为了加快构建速度,建议合理配置 .dockerignore 文件,以下是一个基础示例:

# .dockerignore
.env
.git
.github
.next
.vscode
node_modules

*Dockerfile*
*docker-compose*

**/dist
**/__tests__

The content of your Dockerfile will vary greatly depending on your repository setup, but here's an example for inspiration, using Yarn v4:

Dockerfile 的具体写法会因仓库结构而异,下面给出一个基于 Yarn v4 的参考示例:

# Dockerfile

# Global args, set before the first FROM, shared by all stages
ARG NODE_ENV="production"
ARG GRAPHILE_ENV="production"

################################################################################
# Build stage 1 - `yarn build`

FROM node:24-alpine AS builder
# Import our shared args
ARG NODE_ENV
ARG GRAPHILE_ENV

# Cache node_modules for as long as possible
COPY .yarn/ /app/.yarn/
COPY .yarnrc.yml package.json yarn.lock tsconfig.json /app/
WORKDIR /app/
RUN ["corepack", "enable"]
RUN ["yarn", "install", "--immutable"]

# Copy over the server source code
COPY src/ /app/src/

# Finally run the build script
RUN ["yarn", "run", "build"]

################################################################################
# Build stage 2 - COPY the relevant things (multiple steps)

FROM node:24-alpine AS clean
# Import our shared args
ARG NODE_ENV
ARG GRAPHILE_ENV

# Copy over selectively just the tings we need, try and avoid the rest
COPY --from=builder /app/.yarnrc.yml /app/package.json /app/yarn.lock /app/
COPY --from=builder /app/.yarn/releases/ /app/.yarn/releases/
COPY --from=builder /app/dist/ /app/dist/

################################################################################
# Build stage FINAL - COPY everything, once, and then do a clean `yarn install`

FROM node:24-alpine
# Import our shared args
ARG NODE_ENV
ARG GRAPHILE_ENV

EXPOSE 5678
WORKDIR /app/
# Copy everything from stage 2, it's already been filtered
COPY --from=clean /app/ /app/

# Install yarn ASAP because it's the slowest
RUN ["corepack", "enable"]
RUN ["yarn", "workspaces", "focus", "-A", "--production"]

LABEL description="My PostGraphile-powered server"

ENV HOST="0.0.0.0"
ENV NODE_ENV=$NODE_ENV
ENV GRAPHILE_ENV=$GRAPHILE_ENV
ENTRYPOINT ["yarn", "start:production"]

Build via:

使用以下命令构建镜像:

docker build -t mypostgraphileproject .

This builds the Docker image from the Dockerfile in the current directory, and tags it as mypostgraphileproject.

该命令会基于当前目录中的 Dockerfile 构建镜像,并为其打上 mypostgraphileproject 标签。

Run via:

使用以下命令运行容器:

docker run \
--rm \
-it \
-p 5678:5678 \
-e DATABASE_URL="postgres://username:password@host:port/db" \
mypostgraphileproject
  • --rm removes the container automatically when it exits

    --rm:容器退出时自动清理删除

  • -it runs the container interactively with TTY attached, useful for logs and Ctrl-C

    -it:以交互式终端(TTY)模式运行容器,方便查看实时日志以及使用 Ctrl-C 中止

  • -p 5678:5678 publishes port 5678 from the container to port 5678 on the host

    -p 5678:5678:将容器内的 5678 端口映射到宿主机的 5678 端口

  • -e DATABASE_URL=… sets the database connection string at runtime

    -e DATABASE_URL=…:在运行时设置数据库连接字符串

  • mypostgraphileproject is the image to run (named via -t in the docker build command above

    mypostgraphileproject:指定要运行的镜像名称(即前面 docker build 命令中通过 -t 指定的名称)

See it working in benjie/ouch.

可在 benjie/ouch 中查看实际运行效果。

Connecting to database on host machine连接宿主机上的数据库

Use the docker argument --add-host=host.docker.internal:host-gateway and the connection string postgres://username:password@host.docker.internal/mydb to connect to the mydb db on the host machine. For this to work, you'll also need to ensure your listen_address is set correctly:

如果数据库运行在宿主机上,可在 Docker 中传入 --add-host=host.docker.internal:host-gateway 参数,并使用连接字符串 postgres://username:password@host.docker.internal/mydb 来连接宿主机的 mydb 数据库。此外,还需要确保 PostgreSQL 的 listen_address 配置正确:

postgresql.conf
# ...
listen_address = 'localhost,172.17.0.1'
port = 5432
# ...

And you may need to restart PostgreSQL after you've started the Docker daemon so that the port binds correctly.

同时,在启动 Docker 守护进程后,你可能需要重启一次 PostgreSQL,以确保监听端口正常绑定。