FerretDB 在 Kubernetes 上部署 DocumentDB PostgreSQL：从 StatefulSet 到集群连接完整指南

后端数据库文档数据库【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址https://gitcode.com/gh_mirrors/fe/FerretDB点击查看免费下载FerretDB 是开源 MongoDB 替代方案其 v2.x 版本以「PostgreSQL DocumentDB 扩展」作为存储引擎。本文以 v2.5 官方安装文档为主线讲解如何在 Kubernetes 集群中通过 StatefulSet 部署带 DocumentDB 扩展的 PostgreSQL 实例并通过 Service 暴露 5432 端口为后续 FerretDB 容器提供数据库连接。读完本文你将掌握postgres.yaml的完整清单结构、关键环境变量的作用、部署验证方法以及如何衔接 FerretDB 的 Kubernetes 部署完成整条链路的连通。前置条件与架构概述在 Kubernetes 上运行 FerretDB 需要两个核心组件PostgreSQL DocumentDB 扩展作为数据库引擎负责数据存储、认证与查询执行FerretDB 本身作为 MongoDB Wire Protocol 的入口将 MongoDB 请求翻译为 PostgreSQL 查询。本文聚焦第一个组件——DocumentDB PostgreSQL 的 Kubernetes 部署。官方文档强调在开始安装之前请确保你已经有一个运行中的 Kubernetes 集群本指南不包含集群本身的搭建步骤。整个数据链路可以概括为MongoDB 客户端 (mongosh) │ 27017 MongoDB Wire Protocol ▼ FerretDB Pod │ postgres://user:passpostgres:5432/postgres ▼ PostgreSQL DocumentDB (StatefulSet, 端口 5432)选择正确的 DocumentDB 镜像与版本标签FerretDB 官方提供了预打包的 PostgreSQL with DocumentDB 扩展镜像可用于各种部署方式Docker、Kubernetes 等。在 Docker 安装文档 中可以看到官方镜像分为两类生产镜像ghcr.io/ferretdb/postgres-documentdb稳定、经过优化的正式部署镜像大多数场景推荐使用开发镜像ghcr.io/ferretdb/postgres-documentdb-dev包含额外调试特性但性能显著更慢不推荐用于生产。版本标签规范官方强烈建议始终指定完整的镜像标签如17-0.106.0-ferretdb-2.5.0以保证跨环境部署的一致性。这个标签的语义为标签片段含义17PostgreSQL 主版本号170.106.0DocumentDB 扩展版本ferretdb-2.5.0对应的 FerretDB 版本镜像标签与 FerretDB 版本必须匹配。具体的「最佳镜像版本」组合需要查看对应的 DocumentDB release notes 进行确认切勿混用不匹配的版本组合。提示生产镜像不包含 FerretDB 本体因此你需要分别部署 FerretDB见下文「连接 FerretDB」小节。创建 postgres.yamlStatefulSet Service 清单详解官方文档提供了一份可直接使用的postgres.yaml清单其中包含两个 Kubernetes 资源用---分隔1. StatefulSet声明式管理 PostgreSQL PodapiVersion: apps/v1 kind: StatefulSet metadata: name: postgres spec: serviceName: postgres replicas: 1 selector: matchLabels: app: postgres template: metadata: labels: app: postgres spec: containers: - name: postgres image: ghcr.io/ferretdb/postgres-documentdb:17-0.106.0-ferretdb-2.5.0 ports: - containerPort: 5432 env: - name: POSTGRES_USER value: username - name: POSTGRES_PASSWORD value: password - name: POSTGRES_DB value: postgres volumeMounts: - name: data mountPath: /var/lib/postgresql/data volumeClaimTemplates: - metadata: name: data spec: accessModes: [ReadWriteOnce] resources: requests: storage: 1Gi关键设计点说明StatefulSet volumeClaimTemplates选择 StatefulSet 而非 Deployment是为了给 PostgreSQL 提供稳定的持久化存储。volumeClaimTemplates会为每个副本自动创建 PVCPersistentVolumeClaimaccessModes: [ReadWriteOnce]表示卷只能被单个节点读写storage: 1Gi是初始存储请求可按实际数据量调整mountPath: /var/lib/postgresql/data这是 PostgreSQL 的数据目录将数据卷挂载到此处保证 Pod 重建后数据不丢失环境变量三件套POSTGRES_USER/POSTGRES_PASSWORD数据库超级用户凭据必须替换为你的实际值文档中的username、password是占位符POSTGRES_DB必须固定为postgres。这是正确初始化 DocumentDB 扩展的硬性要求——FerretDB 需要postgres数据库已初始化且存在才能建立连接。从仓库安全文档 authentication.md 可知FerretDB 自身不保存任何用户凭据认证完全依赖 PostgreSQL。因此这个 StatefulSet 中创建的超级用户正是后续 FerretDB 与 MongoDB 客户端认证所依赖的凭据来源。2. Service固定访问入口apiVersion: v1 kind: Service metadata: name: postgres labels: app: postgres spec: selector: app: postgres ports: - port: 5432 targetPort: 5432Service 名为postgres通过selector匹配标签app: postgres的 Pod将集群内流量转发到 Pod 的 5432 端口。这样 FerretDB 容器就可以用主机名postgres访问数据库而无需关心 Pod IP 的变化。部署并验证 PostgreSQL 实例创建清单文件后执行应用命令kubectl apply -f postgres.yaml该命令会同时创建 StatefulSet 与 Service。随后官方建议通过以下命令检查实例状态kubectl get pods -l apppostgres kubectl get svc -l apppostgreskubectl get pods查看 PostgreSQL Pod 是否进入Running/Ready状态kubectl get svc确认名为postgres的 Service 已创建且CLUSTER-IP与端口 5432 就绪。Pod 正常就绪后集群内即可通过postgres:5432解析到数据库服务。这也是下一节 FerretDB 连接字符串中主机名的来源。连接 FerretDB完成整条链路PostgreSQL 实例就绪后需要将 FerretDB 部署到同一集群中。完整步骤见 FerretDB Kubernetes 安装文档其核心连接配置如下# ferretdb.yaml节选 containers: - name: ferretdb image: ghcr.io/ferretdb/ferretdb:2.5.0 ports: - containerPort: 27017 env: - name: FERRETDB_POSTGRESQL_URL value: postgres://username:passwordpostgres:5432/postgres连接字符串解读postgres://PostgreSQL 协议连接 URLusername:password与 postgres.yaml 中POSTGRES_USER/POSTGRES_PASSWORD保持一致postgres:5432主机名postgres正是上文 Service 的名字集群内 DNS 会将其解析到对应 Pod/postgres必须连接postgres数据库因为 DocumentDB 扩展在该库中初始化。FERRETDB_POSTGRESQL_URL对应命令行参数--postgresql-url。根据 flags.md 的说明其默认值为postgres://127.0.0.1:5432/postgres在 Kubernetes 场景下必须显式指定为 Service 地址。FerretDB 使用 pgx v5 驱动连接 PostgreSQL并额外设置了连接池参数pool_min_conns默认 10、pool_max_conns默认 50、application_nameFerretDB与timezoneUTC。从源码实现看嵌入式实现入口 的Config结构将PostgreSQLURL标记为必需字段Required进一步印证了数据库连接在 FerretDB 启动流程中的核心地位。本地验证连通性FerretDB 部署完成后可通过端口转发从本机连接kubectl port-forward svc/ferretdb 27017:27017然后在另一个终端用mongosh连接若已安装mongosh mongodb://username:password127.0.0.1:27017/若认证失败请检查PostgreSQL 中是否已存在对应用户、POSTGRES_DB是否为postgres以及 FerretDB 连接串中的凭据是否一致。FerretDB 目前仅支持客户端侧SCRAM-SHA-256认证机制详细认证流程见 认证文档。生产化与运维要点基于官方文档与仓库配置信息以下实践建议值得在生产环境中采纳固定镜像标签始终使用完整标签如17-0.106.0-ferretdb-2.5.0避免latest类标签带来的不可控漂移存储容量规划volumeClaimTemplates中的storage: 1Gi仅为最小示例应根据数据增长预期调整并考虑使用带备份能力的存储类凭据管理YAML 中的明文password适合快速上手生产环境应改用 Kubernetes Secret 或外部密钥管理健康检查FerretDB 提供/debug/livez存活探针与/debug/readyz就绪探针两个 HTTP 端点其中readyz会实际执行ping命令验证 PostgreSQL 连接与 DocumentDB 安装是否正确可直接接入 Kubernetes liveness/readinessProbe详见 observability.md升级顺序官方升级指南见 Docker 版更新章节强调升级 FerretDB 前必须先升级匹配的 DocumentDB 镜像并执行ALTER EXTENSION documentdb UPDATE;切勿颠倒顺序。总结本文完整复现了 FerretDB v2.5 官方 Kubernetes 部署文档的核心流程通过postgres.yamlStatefulSet Service在集群中拉起带 DocumentDB 扩展的 PostgreSQL将POSTGRES_DB固定为postgres以满足扩展初始化要求随后用kubectl apply应用清单并验证 Pod 与 Service 状态最后通过FERRETDB_POSTGRESQL_URL将 FerretDB 指向postgres:5432完成整条链路。这套清单既是官方推荐的生产部署基线也是理解 FerretDB「MongoDB 协议翻译层 PostgreSQL 存储引擎」架构的绝佳入口。赞分享后端数据库文档数据库【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址https://gitcode.com/gh_mirrors/fe/FerretDB点击查看免费下载相关推荐JDK HotSpot 反汇编插件 hsdisCapstone、LLVM、binutils 三大后端的构建与使用实战指南JDK HotSpot 反汇编插件 hsdisCapstone、LLVM、binutils 三大后端的构建与使用实战指南 本文围绕 JDK 仓库中的 hsdi后端数据库文档数据库掌握 GitHub Copilot CLI 技能系统用 SKILL.md 打造可自动匹配的领域专家掌握 GitHub Copilot CLI 技能系统用 SKILL.md 打造可自动匹配的领域专家 本篇技术指南以 awesome copilot 仓库中 c后端数据库文档数据库Refine 中 MUI Material UI 与 X Data Grid 版本迁移指南从 v5/v4 升级到 v6/v7 的完整实操Refine 中 MUI Material UI 与 X Data Grid 版本迁移指南从 v5/v4 升级到 v6/v7 的完整实操 本文是 Refine后端数据库文档数据库上一篇如何让老Mac免费装上最新macOSOpenCore Legacy Patcher 完整指南下一篇将 Repomix 作为 Node.js 库集成从 runCli 到底层 API 的完整实践指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考