企业官网建设流程全解析

• 后端
• 数据库
• 文档数据库

FerretDB 是开源 MongoDB 替代方案，其 v2.x 版本以「PostgreSQL + DocumentDB 扩展」作为存储引擎。本文以 v2.5 官方安装文档为主线，讲解如何在 Kubernetes 集群中通过 StatefulSet 部署带 DocumentDB 扩展的 PostgreSQL 实例，并通过 Service 暴露 5432 端口，为后续 FerretDB 容器提供数据库连接。读完本文，你将掌握postgres.yaml的完整清单结构、关键环境变量的作用、部署验证方法，以及如何衔接 FerretDB 的 Kubernetes 部署完成整条链路的连通。

前置条件与架构概述

在 Kubernetes 上运行 FerretDB 需要两个核心组件：

1. PostgreSQL + DocumentDB 扩展：作为数据库引擎，负责数据存储、认证与查询执行；
2. FerretDB 本身：作为 MongoDB Wire Protocol 的入口，将 MongoDB 请求翻译为 PostgreSQL 查询。

本文聚焦第一个组件——DocumentDB PostgreSQL 的 Kubernetes 部署。官方文档强调，在开始安装之前，请确保你已经有一个运行中的 Kubernetes 集群（本指南不包含集群本身的搭建步骤）。

整个数据链路可以概括为：

MongoDB 客户端 (mongosh) │ 27017 MongoDB Wire Protocol ▼ FerretDB Pod │ postgres://user:pass@postgres: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），以保证跨环境部署的一致性。这个标签的语义为：

镜像标签与 FerretDB 版本必须匹配。具体的「最佳镜像版本」组合需要查看对应的 DocumentDB release notes 进行确认，切勿混用不匹配的版本组合。

提示：生产镜像不包含 FerretDB 本体，因此你需要分别部署 FerretDB（见下文「连接 FerretDB」小节）。

创建 postgres.yaml：StatefulSet + Service 清单详解

官方文档提供了一份可直接使用的postgres.yaml清单，其中包含两个 Kubernetes 资源，用---分隔：

1. StatefulSet：声明式管理 PostgreSQL Pod

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.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会为每个副本自动创建 PVC（PersistentVolumeClaim），accessModes: ['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: 5432

Service 名为postgres，通过selector匹配标签app: postgres的 Pod，将集群内流量转发到 Pod 的 5432 端口。这样 FerretDB 容器就可以用主机名postgres访问数据库，而无需关心 Pod IP 的变化。

部署并验证 PostgreSQL 实例

创建清单文件后，执行应用命令：

kubectl apply -f postgres.yaml

该命令会同时创建 StatefulSet 与 Service。随后官方建议通过以下命令检查实例状态：

kubectl get pods -l app=postgres kubectl get svc -l app=postgres

• kubectl 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>:<password>@postgres:5432/postgres

连接字符串解读：

• postgres://：PostgreSQL 协议连接 URL；
• <username>:<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_name=FerretDB与timezone=UTC。

从源码实现看，嵌入式实现入口 的Config结构将PostgreSQLURL标记为必需字段（Required），进一步印证了数据库连接在 FerretDB 启动流程中的核心地位。

本地验证连通性

FerretDB 部署完成后，可通过端口转发从本机连接：

kubectl port-forward svc/ferretdb 27017:27017

然后在另一个终端用mongosh连接（若已安装）：

mongosh mongodb://<username>:<password>@127.0.0.1:27017/

若认证失败，请检查：PostgreSQL 中是否已存在对应用户、POSTGRES_DB是否为postgres，以及 FerretDB 连接串中的凭据是否一致。FerretDB 目前仅支持客户端侧SCRAM-SHA-256认证机制，详细认证流程见 认证文档。

生产化与运维要点

基于官方文档与仓库配置信息，以下实践建议值得在生产环境中采纳：

1. 固定镜像标签：始终使用完整标签（如17-0.106.0-ferretdb-2.5.0），避免latest类标签带来的不可控漂移；
2. 存储容量规划：volumeClaimTemplates中的storage: 1Gi仅为最小示例，应根据数据增长预期调整，并考虑使用带备份能力的存储类；
3. 凭据管理：YAML 中的明文<password>适合快速上手，生产环境应改用 Kubernetes Secret 或外部密钥管理；
4. 健康检查：FerretDB 提供/debug/livez（存活探针）与/debug/readyz（就绪探针）两个 HTTP 端点，其中readyz会实际执行ping命令验证 PostgreSQL 连接与 DocumentDB 安装是否正确，可直接接入 Kubernetes liveness/readinessProbe，详见 observability.md；
5. 升级顺序：官方升级指南（见 Docker 版更新章节）强调，升级 FerretDB 前必须先升级匹配的 DocumentDB 镜像，并执行ALTER EXTENSION documentdb UPDATE;，切勿颠倒顺序。

总结

本文完整复现了 FerretDB v2.5 官方 Kubernetes 部署文档的核心流程：通过postgres.yaml（StatefulSet + Service）在集群中拉起带 DocumentDB 扩展的 PostgreSQL，将POSTGRES_DB固定为postgres以满足扩展初始化要求，随后用kubectl apply应用清单并验证 Pod 与 Service 状态，最后通过FERRETDB_POSTGRESQL_URL将 FerretDB 指向postgres:5432完成整条链路。这套清单既是官方推荐的生产部署基线，也是理解 FerretDB「MongoDB 协议翻译层 + PostgreSQL 存储引擎」架构的绝佳入口。

• 后端
• 数据库
• 文档数据库