在 Kubernetes 上部署 FerretDB 的 DocumentDB 后端：PostgreSQL 安装、验证与连接实战指南

后端数据库文档数据库【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址https://gitcode.com/gh_mirrors/fe/FerretDB点击查看免费下载FerretDB 是一个开源 MongoDB 替代品其 v2 版本以 PostgreSQL 搭配 DocumentDB 扩展作为数据库引擎。本指南围绕官方 Kubernetes 安装文档完整讲解如何在 Kubernetes 集群中通过StatefulSet部署带 DocumentDB 扩展的 PostgreSQL 实例、校验其运行状态并通过FERRETDB_POSTGRESQL_URL将其接入 FerretDB最终使用mongosh完成端到端连接验证。读完本文你将掌握一套可复制、可运维的 FerretDB DocumentDB 后端 Kubernetes 部署方案。一、前置条件与整体架构在开始部署前请确认以下前提一个运行中的 Kubernetes 集群本地kind/minikube或云厂商托管集群均可并配置好kubectl具备在该集群中创建StatefulSet、Service与PersistentVolumeClaim的权限准备好用于访问 PostgreSQL 的用户名与密码。从架构上看FerretDB 并不直接存储数据而是作为 MongoDB Wire Protocol 协议层将客户端请求翻译为 SQL 后转发给 PostgreSQLmongosh / MongoDB 驱动 │ MongoDB 协议 (:27017) ▼ FerretDB 容器 │ PostgreSQL 协议 (:5432, FERRETDB_POSTGRESQL_URL) ▼ PostgreSQL DocumentDB 扩展StatefulSet数据卷持久化其中 PostgreSQL 需要安装并初始化DocumentDB 扩展FerretDB 才能正常工作。这正是本文要部署的核心组件。二、选择正确的镜像与版本号FerretDB 为「带 DocumentDB 扩展的 PostgreSQL」提供了专门的官方镜像仓库根目录的 docker-compose.yml 中同样可以看到基于build/deps构建该镜像的开发环境用法。生产环境推荐使用ghcr.io/ferretdb/postgres-documentdb:17-0.107.0-ferretdb-2.7.0该镜像标签采用PG主版本-DocumentDB版本-ferretdb版本三段式结构含义如下标签片段含义本例取值17PostgreSQL 主版本PostgreSQL 170.107.0DocumentDB 扩展版本0.107.0ferretdb-2.7.0配套 FerretDB 版本2.7.0:::tip 官方强烈建议始终指定完整镜像标签例如17-0.107.0-ferretdb-2.7.0避免使用latest之类的浮动标签导致不同环境间镜像不一致。具体每个 FerretDB 版本应搭配哪个 DocumentDB 版本请以对应版本的 DocumentDB 发布说明为准。 :::关于镜像的更多选择生产镜像 vs 调试用开发镜像可参考 DocumentDB Docker 安装文档。三、编写 postgres.yamlStatefulSet Service 完整清单由于 PostgreSQL 是有状态服务官方清单使用StatefulSet配合volumeClaimTemplates实现数据持久化并配套一个名为postgres的Service供 FerretDB 通过集群内 DNS 解析访问。创建postgres.yaml内容如下apiVersion: 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.107.0-ferretdb-2.7.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 --- apiVersion: v1 kind: Service metadata: name: postgres labels: app: postgres spec: selector: app: postgres ports: - port: 5432 targetPort: 54323.1 关键字段逐项解读serviceName: postgresStatefulSet必须关联一个 headlessService名称用于为每个 Pod 提供稳定的网络标识postgres-0.postgres。replicas: 1官方默认单副本。DocumentDB 扩展基于单写主实例工作生产环境如需高可用应在此基础上结合 PostgreSQL 主从/备份策略自行规划而不是简单扩副本。POSTGRES_USER/POSTGRES_PASSWORD部署前务必替换username与password为你的实际凭据。FerretDB 依赖 PostgreSQL 完成认证因此这两个值也是后续 FerretDB 连接串中使用的凭据。POSTGRES_DB: postgres必须保持为postgres。这是 DocumentDB 扩展正确初始化的硬性要求——FerretDB 要求postgres数据库已存在并完成扩展初始化才能建立连接详见 认证文档 - Set up PostgreSQL connection。volumeMounts挂载/var/lib/postgresql/dataPostgreSQL 的数据目录通过volumeClaimTemplates为每个副本动态申请 PVC。accessModes: [ReadWriteOnce]单节点读写符合单副本 PostgreSQL 的访问模式。storage: 1Gi示例最小存储申请生产环境请根据数据量评估后调整例如扩至数十或数百 GiB并考虑使用 SSD 存储类。Service端口映射port: 5432对外暴露targetPort: 5432指向容器端口selector: app: postgres与StatefulSet的 Pod 标签一致。四、应用清单并验证 PostgreSQL 实例4.1 应用清单kubectl apply -f postgres.yaml该命令会创建名为postgres的StatefulSet含 PVC、以及名为postgres的Service。FerretDB 后续可通过postgres:5432这个集群内地址连接该实例。4.2 验证运行状态kubectl get pods -l apppostgres kubectl get svc -l apppostgres第一条命令查看 Pod 是否进入Running且READY 1/1第二条命令确认Service已创建且CLUSTER-IP分配正常。如果 Pod 一直处于Pending常见原因是 PVC 无法绑定存储类不支持ReadWriteOnce或配额不足可用kubectl describe pod进一步排查。五、接入 FerretDB创建 ferretdb.yaml 并验证端到端连接PostgreSQL 就绪后即可部署 FerretDB 本体。FerretDB 通过FERRETDB_POSTGRESQL_URL环境变量或等价命令行参数--postgresql-url指向刚创建的postgres服务完整的连接流程见 FerretDB Kubernetes 安装文档。创建ferretdb.yamlapiVersion: apps/v1 kind: Deployment metadata: name: ferretdb spec: replicas: 1 selector: matchLabels: app: ferretdb template: metadata: labels: app: ferretdb spec: containers: - name: ferretdb image: ghcr.io/ferretdb/ferretdb:2.7.0 ports: - containerPort: 27017 env: - name: FERRETDB_POSTGRESQL_URL value: postgres://username:passwordpostgres:5432/postgres --- apiVersion: v1 kind: Service metadata: name: ferretdb labels: app: ferretdb spec: selector: app: ferretdb ports: - port: 27017 targetPort: 27017同样替换username与password为第 3 节设置的 PostgreSQL 凭据然后应用并检查状态kubectl apply -f ferretdb.yaml kubectl get pods -l appferretdb kubectl get svc -l appferretdb从本机访问集群内的 FerretDB使用端口转发kubectl port-forward svc/ferretdb 27017:27017在另一个终端用mongosh连接mongosh mongodb://username:password127.0.0.1:27017/连接成功即代表「FerretDB → PostgreSQL DocumentDB」整条链路已打通。注意连接串中的用户名/密码是PostgreSQL 用户凭据因为 FerretDB 的认证完全建立在 PostgreSQL 用户体系之上认证细节参见 认证文档。六、源码视角FerretDB 如何与 DocumentDB 后端交互结合本仓库源码可以更深入地理解为什么这套部署是 FerretDB v2 的必经之路。1. DocumentDB 是核心依赖而非可选组件。在 internal/documentdb/documentdb.go 中包注释明确了 FerretDB 只使用 DocumentDB 扩展提供的若干 schemadocumentdb_api主数据操作、documentdb_api_catalogexplain命令、documentdb_api_internal索引与认证、documentdb_core用于跟踪变更并通过go:generate生成对应调用代码。这些 schema 正是镜像初始化时在postgres数据库中安装好的这也是POSTGRES_DB必须为postgres的原因。2. PostgreSQL URL 是唯一必需的运行时配置。在 cmd/ferretdb/main.go 中可以看到 CLI 定义--postgresql-url的默认值是postgres://127.0.0.1:5432/postgres环境变量等价形式即FERRETDB_POSTGRESQL_URL。Kubernetes 部署中把它指向postgres:5432正是覆盖了这个默认值。完整参数表见 配置文档 - flags。3. 连接池行为有默认调优。根据 配置文档FerretDB 基于 pgx v5 连接 PostgreSQL并对默认值做了覆盖pool_min_conns未设置时为 10、pool_max_conns未设置时为 50同时始终设置application_nameFerretDB、timezoneUTC。这意味着在生产集群中如果 PostgreSQL 侧max_connections配置过小可能出现连接被拒的情况规划资源时应把这一连接池行为考虑进去。4. 认证与用户管理由 DocumentDB 扩展承接。仓库根目录的 docker-compose.yml开发环境以及 DocumentDB Docker 安装文档 中可以看到一组 DocumentDB 扩展配置例如documentdb.enableUserCrud true与documentdb.maxUserLimit 100默认限制 100 个用户这些设置决定了 FerretDB 的createUser等用户管理命令如何在 PostgreSQL 侧落地。七、生产实践建议凭据不要硬编码示例中username/password直接写在 YAML 中仅用于演示。生产环境建议改为 KubernetesSecret通过envFrom或secretKeyRef注入并配合外部密钥管理如 Vault轮换。版本固定与升级顺序务必固定完整镜像标签。升级时必须先升级 DocumentDB 扩展镜像在postgres数据库中执行ALTER EXTENSION documentdb UPDATE;并核对shared_preload_libraries、cron.database_name等配置再升级 FerretDB 本体具体步骤参见 DocumentDB Docker 安装文档的升级章节。存储规划1Gi只是最小演示值。请按业务数据量与备份策略合理设置 PVC 容量并对 PostgreSQL 数据卷配置定期备份ReadWriteOnce意味着同一卷同一时刻只能被一个节点挂载。本地开发对照如果不使用 Kubernetes也可以直接参考 docker-compose.yml 中的postgres服务定义用 Docker 快速拉起一个带 DocumentDB 扩展的 PostgreSQL 用于联调。通过本文的清单与验证步骤你可以在任意 Kubernetes 集群上稳定复现 FerretDB 的 DocumentDB 后端部署并为后续的 FerretDB 本体部署、认证配置与版本升级打下可靠基础。赞分享后端数据库文档数据库【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址https://gitcode.com/gh_mirrors/fe/FerretDB点击查看免费下载相关推荐FerretDB 在 Kubernetes 上部署 DocumentDB PostgreSQL从 StatefulSet 到集群连接完整指南FerretDB 在 Kubernetes 上部署 DocumentDB PostgreSQL从 StatefulSet 到集群连接完整指南 FerretDB后端数据库文档数据库FerretDB 在 Kubernetes 上部署 PostgreSQL with DocumentDB 扩展StatefulSet 实践指南FerretDB 在 Kubernetes 上部署 PostgreSQL with DocumentDB 扩展StatefulSet 实践指南 本文围绕 Fe后端数据库文档数据库使用 CloudNativePG 在 Kubernetes 上部署 FerretDB 与 PostgreSQL DocumentDB 扩展的完整指南使用 CloudNativePG 在 Kubernetes 上部署 FerretDB 与 PostgreSQL DocumentDB 扩展的完整指南 本篇技术指后端数据库文档数据库上一篇shelljs开源贡献者访谈核心开发者讲述项目故事下一篇Tmuxinator 故障排除常见问题诊断和修复指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考