PostgREST 安装完全指南预编译二进制、系统包管理器、Docker 容器与源码编译全攻略【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrestPostgREST 是一个把 PostgreSQL 数据库直接转换为 RESTful API 的 Web 服务器安装是使用它的第一步。本文以仓库文档 docs/explanations/install.rst 与 docs/shared/installation.rst 为主体骨架完整覆盖 macOS、FreeBSD、Linux、Windows 各平台的安装命令深入讲解预编译二进制运行、Docker 容器化部署以及 Stack/Nix 源码构建三种路径并结合当前仓库的源码、Nix 构建脚本与测试配置给出可验证的实操细节。读完本文你将能够根据自身环境选择最合适的安装方式并完成 PostgREST 的首次启动、配置与验证。安装方式总览PostgREST 提供以下四种主要安装途径你可以按场景选择方式适用场景特点预编译二进制快速上手、生产部署Linux 二进制为静态可执行文件可在任何 Linux 发行版运行系统包管理器习惯使用平台原生包管理由各发行版维护升级随系统走Docker 容器容器化部署、避免环境污染官方镜像配合 docker-compose 可一键拉起从源码编译无预编译包、需定制或参与开发需要 Haskell 工具链构建耗时较长官方发布页为 macOS、Windows、Linux 和 FreeBSD 提供预编译二进制其中 Linux 二进制是静态可执行文件不依赖系统动态库可以运行在任意 Linux 发行版上。此外也可以使用操作系统自带的包管理器安装详见下文各平台说明。使用系统包管理器安装以下命令均来自 docs/shared/installation.rst是各平台官方推荐的安装方式。macOSHomebrewmacOS 用户可以从 Homebrew 官方仓库安装brew install postgrestFreeBSDpkgFreeBSD 用户可以从官方 ports 安装pkg install hs-postgrestLinuxLinux 下根据发行版和包管理器不同有若干选择Arch Linuxcommunity 仓库pacman -S postgrestNix via nixpkgs使用 Nix 包管理器安装nix-env -i postgrestNix via flake使用 Nix flake 引入 PostgREST 作为构建输入适合在自定义 Nix 项目或可复现的开发环境中引用{ inputs.postgrest.url github:postgrest/postgrest; # ... }flake 声明了packages.default普通构建、packages.static静态构建若目标平台可用以及默认 app 入口具体见仓库根目录 flake.nix。WindowsChocolatey 或 ScoopWindows 用户可使用 Chocolatey 或 Scoop 两个包管理器choco install postgrest scoop install postgrest支持的 PostgreSQL 版本PostgREST 支持PostgreSQL 14即与 PostgreSQL 官方仍在维护支持的所有版本保持兼容。这意味着在规划数据库版本时只要使用官方仍在支持的 PostgreSQL 版本即可获得 PostgREST 的完整支持。下载预编译二进制并首次运行从发布页下载对应平台的压缩包后首先解压得到可执行文件# UNIX 平台 tar Jxf postgrest-[version]-[platform].tar.xz # Windows 平台应直接解压 zip 文件解压后即可运行。--help参数会打印完整的用法说明# 直接运行下载的二进制 ./postgrest --help # 通过包管理器安装后二进制已在 PATH 中 postgrest --help理解命令行选项从 docs/references/cli.rst 可以查看完整 CLI 定义Usage: postgrest [-v|--version] [-e|--example] [--dump-config | --dump-schema | --ready] [FILENAME] Available options: -h,--help Show this help text -v,--version Show the version information -e,--example Show an example configuration file --dump-config Dump loaded configuration and exit --dump-schema Dump loaded schema as JSON and exit (for debugging, output structure is unstable) --ready Checks the health of PostgREST by doing a request on the admin server /ready endpoint FILENAME Path to configuration file其中几个选项在安装后验证环节很有用postgrest --version打印版本号确认二进制可用postgrest --example输出一份完整的示例配置文件是快速起步的捷径postgrest --dump-config将实际加载的配置合并配置文件、环境变量与库内配置后打印出来并退出用于排查配置问题postgrest --dump-schema以 JSON 形式导出 schema 缓存输出结构不稳定仅供调试postgrest --ready对管理服务器的/ready端点发起健康检查成功退出码为 0失败为 1适合容器与编排系统的就绪探针注意server-host配置为特殊主机名时该参数不可用建议改为localhost。通过配置文件启动服务器PostgREST 服务器只接受一个参数配置文件的路径postgrest /path/to/postgrest.conf也可以先生成一份示例配置再编辑postgrest -e postgrest.conf # 你需要编辑该文件删掉 usage 部分后 postgrest 才能正常读取一份最小可用的配置文件包含以下关键项参见 docs/references/configuration.rst# postgrest.conf # 标准连接 URI 格式详见 PostgreSQL libpq 文档 db-uri postgres://user:passhost:5432/dbname # 客户端未提供认证时使用的数据库角色应与 authenticator 不同 db-anon-role anon # 用于校验 JWT 的密钥长度必须至少 32 字符 jwt-secret reallyreallyreallyreallyverysafe jwt-secret-is-base64 false # postgrest 进程监听 HTTP 请求的端口 server-port 3000配置的三个来源与优先级PostgREST 的配置参数可通过三种途径提供优先级从低到高为配置文件file_config即上面传入的postgrest.conf环境变量env_variables_config覆盖配置文件中的同名参数。环境变量全部大写、带PGRST_前缀、使用下划线例如PGRST_DB_URI对应db-uri、PGRST_APP_SETTINGS_*对应app.settings.*库内配置in_db_config通过db-pre-config指定的 SQL 函数用set_config设置pgrst.*参数覆盖前两者。注意库内配置参数使用下划线而非短横线例如pgrst.db_schemas、pgrst.jwt_secret。服务器可以在不重启的情况下通过信号或数据库通知重载配置但环境变量对运行中的进程不可更改因此 Docker 容器的配置无法热重载此时可改用库内配置或重启进程。db-uri还支持多种写法URI 格式特殊字符需百分号编码可用?sslmoderequire强制 SSL、keyword/value 格式host... port... user...、libpq 环境变量PGHOST、PGPORT、PGUSER等以及filename外部文件引用格式。Windows 常见问题pg_config 不在 PATH 中在 Windows 上启动时如果弹出类似下图的错误对话框通常是pg_config程序不在系统 PATH 中pg_config通常位于C:\Program Files\PostgreSQL\version\bin将其加入系统 PATH 即可。在命令行直接运行pg_config能看到输出路径列表说明 PATH 配置正确。使用 Docker 部署官方 Docker 镜像可以这样拉取# 拉取最新版本 docker pull postgrest/postgrest # 拉取指定版本版本号见 Docker Hub 的 tags 列表 docker pull postgrest/postgrest:version容器使用环境变量PGRST_*完成配置。有两种典型部署方式。方式一连接宿主机的原生 PostgreSQL将容器直接连到宿主上已运行的 PostgreSQLdocker run --rm --nethost \ -e PGRST_DB_URIpostgres://app_user:passwordlocalhost/postgres \ postgrest/postgrest上述连接串只是示例请按实际情况调整角色与密码并可能需要修改 PostgreSQL 的pg_hba.conf授予该用户本地登录权限。macOS 注意Docker for Mac 不支持--nethost。替代方案是为宿主机创建 IP 别名容器内解析该 IP 失败时会回退到宿主解析sudo ifconfig lo0 10.0.0.10 alias然后在连接串中使用10.0.0.10作为主机并记得在postgresql.conf的listen_addresses中包含该 IPlisten_addresses localhost,10.0.0.10还可能需要向pg_hba.conf添加一条 IPv4 本地连接规则host all all 10.0.0.10/32 trust最终命令变为docker run --rm -p 3000:3000 \ -e PGRST_DB_URIpostgres://app_user:password10.0.0.10/postgres \ postgrest/postgrest方式二PostgREST 与数据库全部容器化docker-compose如果不想在本机安装数据库可以让 PostgREST 与 PostgreSQL 都运行在容器中用 docker-compose 串联# docker-compose.yml version: 3 services: server: image: postgrest/postgrest ports: - 3000:3000 environment: PGRST_SERVER_HOST: 0.0.0.0 # 使 postgrest --ready 生效所必需 PGRST_DB_URI: postgres://app_user:passworddb:5432/app_db PGRST_OPENAPI_SERVER_PROXY_URI: http://127.0.0.1:3000 depends_on: - db db: image: postgres ports: - 5432:5432 environment: POSTGRES_DB: app_db POSTGRES_USER: app_user POSTGRES_PASSWORD: password # 如需持久化数据取消注释 # volumes: # - ./pgdata:/var/lib/postgresql/data在该文件所在目录执行docker-compose up会同时看到数据库与 PostgREST 的日志API 服务监听在 3000 端口。如果想在浏览器里直观查看 API可在services:下追加 swagger-ui 服务swagger: image: swaggerapi/swagger-ui ports: - 8080:8080 expose: - 8080 environment: API_URL: http://localhost:3000/之后浏览器访问 8080 端口即可看到 Swagger UI。Docker CPU 资源限制PostgREST 不支持 Docker 的--cpus约束选项。变通方案是使用 GHC RTS 的-N选项例如限制为 2 个 CPU 核心docker run --rm -p 3000:3000 \ -e PGRST_DB_URIpostgres://app_user:password10.0.0.10/postgres \ -e GHCRTS-N2 \ postgrest/postgrest仓库内的 Nix 构建 Docker 镜像当前仓库还提供了用 Nix 构建的极致精简 Docker 镜像详见 nix/tools/docker/README.md。它从scratch基础镜像出发只包含静态 PostgREST 二进制约 14 MB等价于一个仅有如下内容的 DockerfileFROM scratch ADD /absolute/path/to/postgrest /bin/postgrest EXPOSE 3000 USER 1000 CMD [ /bin/postgrest ]构建并加载镜像# 在仓库根目录执行构建 docker 属性结果软链接到 result nix-build -A docker # 运行加载脚本把镜像载入本地 Docker底层执行 docker load -i image file result/bin/postgrest-docker-load该镜像加载后名称固定为postgrest:latest。由于没有 bash、ls 等常用工具可以用docker save postgrest:latest image.tar查看 tar 内容或借助 Dive 分析层。若需要在此精简镜像之上派生更完整的镜像FROM alpine:latest COPY --frompostgrest/postgrest /bin/postgrest /bin # 追加你自己的其他内容从源码构建当目标系统没有预编译二进制时可以从源码构建。官方推荐使用StackHaskell 工具链它会自动安装所需的 Haskell 依赖。1. 安装 Stack按官方文档为你的平台安装 Stack。2. 安装系统库依赖不同操作系统需要的原生依赖如下操作系统依赖Ubuntu/Debianlibpq-dev, libgmp-dev, zlib1g-devCentOS/Fedora/Red Hatpostgresql-devel, zlib-devel, gmp-develBSDpostgresql12-clientmacOSlibpq, gmp3. 构建并安装二进制git clone https://gitcode.com/GitHub_Trending/po/postgrest cd postgrest # local-bin-path 可按需调整 stack build --install-ghc --copy-bins --local-bin-path /usr/local/bin注意事项如果构建失败且系统内存不足 1GB尝试添加 swap 文件--install-ghc仅在首次构建时需要后续构建可省略。构建完成后用postgrest --help验证安装是否成功。使用 Nix 构建与开发仓库实践当前仓库围绕 Nix 建立了完整的构建与开发体系详见 nix/README.md比通用源码构建更进一步。从本地仓库检出构建 PostgRESTnix-build --attr postgrestPackage构建结果在result/bin/postgrest。也可以构建静态链接二进制nix-build --attr postgrestStatic # 验证确为静态可执行文件 ldd result/bin/postgrest # not a dynamic executable静态构建基于pkgsStatic见 nix/static.nix。仓库在 flake 中已经声明了对postgrest.cachix.org二进制缓存的信任见 flake.nix建议启用该缓存否则机器需要从源码重建全部基于 Musl 的依赖耗时极长nix-env -iA cachix -f https://cachix.org/api/v1/install cachix use postgrest开发环境用nix-shell进入其中所有 PostgREST 工具脚本都以postgrest-前缀命名例如postgrest-build、postgrest-run、postgrest-test-spec等可用 tab 补全查看全部列表。这些脚本从仓库根目录解析路径即使当前目录在src下配置路径也须从仓库根目录写起例如postgrest-run test/io/configs/simple.conf。仓库内test/io/configs/目录存放了各类测试配置如 test/io/configs/defaults.config可作为配置书写的参考样例。安装后的验证与排障完成安装后可以按以下顺序验证postgrest --version确认版本生成并编辑配置postgrest -e postgrest.conf启动postgrest /path/to/postgrest.conf若配置了server-host为普通地址用postgrest --ready检查健康状态返回OK: http://localhost:3001/ready即正常使用postgrest --dump-config核对实际生效的配置项。常见问题排查要点Windows 上pg_config不在 PATH见前文Docker for Mac 不支持--nethost改用 IP 别名方案内存不足导致源码构建失败加 swap容器配置无法热重载改用库内配置或重启。至此无论你偏好二进制、包管理器、Docker 还是源码构建都能依据本文在当前仓库对应的文档与脚本指导下完成 PostgREST 的安装与首次运行。【免费下载链接】postgrestREST API for any Postgres database项目地址: https://gitcode.com/GitHub_Trending/po/postgrest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考