在 Debian/Ubuntu 上通过 DEB 包安装 DocumentDB 扩展并部署 FerretDB-平芜编程栈

后端
数据库
文档数据库

【免费下载链接】FerretDB

A truly Open Source MongoDB alternative

项目地址：https://gitcode.com/gh_mirrors/fe/FerretDB

本指南以 FerretDB 官方 v2.5 文档 website/versioned_docs/version-v2.5/installation/documentdb/deb.md 为核心，完整讲解如何基于 Debian、Ubuntu 等.deb发行版，使用dpkg安装 Microsoft DocumentDB 扩展，完成 PostgreSQL 的预加载配置与扩展创建，并配合 FerretDB 的 DEB 包完成整套部署与版本升级。读完本文，你将掌握生产包与调试包的选择依据、postgresql.conf中每一行 DocumentDB 参数的用途、CREATE EXTENSION的正确用法，以及保证升级不出错的 DocumentDB → FerretDB 更新顺序。

为什么需要 DocumentDB 扩展

FerretDB 是一款开源 MongoDB 替代方案，其 v2 系列以 PostgreSQL 作为数据存储引擎，而 MongoDB 文档模型、BSON 类型与查询语义则完全由 Microsoft 开源的DocumentDB 扩展在 PostgreSQL 中实现。也就是说，一个可用的 FerretDB 部署 = PostgreSQL + DocumentDB 扩展 + FerretDB 本体三部分，缺一不可。

FerretDB 官方在 release page 与 website/docs/installation/documentdb/kubernetes.md）。

选择正确的 DEB 包

官方发布页提供两类.deb包，务必按用途选择：

包类型	命名示例	适用场景
生产包	`documentdb.deb`	绝大多数生产部署，性能经过优化
开发包	`documentdb-dev.deb`/`documentdb-dbgsym.deb`	调试问题（`-dev`为开发构建，`-dbgsym`为调试符号包）

开发包内置了大量调试特性，会显著拖慢性能，官方明确不建议在生产环境使用。这一“生产/开发”双轨策略与 FerretDB 自身的包发布策略一致——FerretDB DEB 安装指南中同样提供了ferretdb.deb与带-dev后缀的调试包。

安装步骤

整体安装流程分为四步：下载包 → 安装 PostgreSQL 及依赖 → 安装扩展并配置postgresql.conf→ 创建扩展。

第一步：下载并安装依赖

从 DocumentDB 发布页下载与你目标 FerretDB 版本匹配的.deb包。在安装扩展本身之前，需要先安装 PostgreSQL 以及 DocumentDB 扩展所依赖的其他系统包（如编译运行库、pg_cron依赖等）。官方 DEB 包在安装时会对依赖进行检查，依赖缺失会直接导致dpkg -i报错。

第二步：使用 dpkg 安装扩展

以生产包为例，执行：

sudo dpkg -i /path/to/documentdb.deb

将/path/to/documentdb.deb替换为实际下载路径与文件名。若安装过程中因依赖缺失而失败，可先执行sudo apt-get install -f补齐依赖后重新安装。

第三步：配置 postgresql.conf

安装完成后，需要让 PostgreSQL 在启动时把扩展的动态库预加载进默认的postgres数据库。编辑postgresql.conf（通常位于/etc/postgresql/<版本>/main/postgresql.conf，或由pg_config --sysconfdir定位），加入以下配置：

shared_preload_libraries = 'pg_cron,pg_documentdb_core,pg_documentdb' cron.database_name = 'postgres' documentdb.enableCompact = true documentdb.enableLetAndCollationForQueryMatch = true documentdb.enableNowSystemVariable = true documentdb.enableSortbyIdPushDownToPrimaryKey = true documentdb.enableSchemaValidation = true documentdb.enableBypassDocumentValidation = true documentdb.enableUserCrud = true documentdb.maxUserLimit = 100

这些参数的含义与作用如下：

shared_preload_libraries：指定 PostgreSQL 启动时预加载的动态库。pg_cron提供定时任务能力（FerretDB 依赖它清理过期索引等后台作业），pg_documentdb_core与pg_documentdb是 DocumentDB 扩展的两个核心组件，顺序不能颠倒。
cron.database_name：pg_cron后台调度数据库，固定指向默认的postgres库。
documentdb.enableCompact：启用文档存储压缩，显著降低磁盘占用。
documentdb.enableLetAndCollationForQueryMatch：在查询匹配阶段启用$let表达式与排序规则（collation）支持，属于 MongoDB 兼容性开关。
documentdb.enableNowSystemVariable：启用聚合管道中的$$NOW系统变量。
documentdb.enableSortbyIdPushDownToPrimaryKey：允许把按_id排序下推到 PostgreSQL 主键索引，是查询性能优化项。
documentdb.enableSchemaValidation/documentdb.enableBypassDocumentValidation：控制文档模式校验及其绕过开关，用于支持 MongoDB 的validator与bypassDocumentValidation语义。
documentdb.enableUserCrud与documentdb.maxUserLimit：启用 FerretDB 的用户管理（createUser/dropUser/usersInfo等命令）并限定最大用户数（默认上限 100）。

配置完成后必须重启 PostgreSQL才能生效：

sudo systemctl restart postgresql

值得注意的是，这组配置与 Docker 部署路径中通过ALTER SYSTEM SET ...写入的 GUC 参数完全一致（参见 website/docs/installation/documentdb/docker.md），只是 DEB 裸机部署直接编辑postgresql.conf。此外，文档中还以注释形式给出了与 FerretDB 打包脚本ferretdb_packaging/10-preload.sh保持同步的约束，说明这份参数清单是官方打包与测试所验证过的标准配置。

第四步：创建扩展

重启后在postgres数据库中执行：

CREATE EXTENSION documentdb CASCADE;

CASCADE会一并创建documentdb依赖的附属扩展（如documentdb_core、documentdb_api等），这是必须的。执行成功后，可以在psql中通过\dx确认扩展已安装。

第五步：安装并连接 FerretDB

扩展就绪后，即可按 FerretDB DEB 安装指南继续部署 FerretDB：

sudo dpkg -i ferretdb.deb ferretdb --version

FerretDB 的 DEB 包会随附 systemd unit，使服务开机自启（配置方法见 systemd 配置指南）。FerretDB 连接 PostgreSQL 的默认 URL 为postgres://127.0.0.1:5432/postgres（可通过--postgresql-url参数或FERRETDB_POSTGRESQL_URL环境变量覆盖，见 cmd/ferretdb/main.go）。连接前需保证 PostgreSQL 中已初始化postgres数据库并准备好用户凭据，详见 PostgreSQL 连接设置。

升级到新版本

DocumentDB 与 FerretDB 的版本是一一绑定的：升级 FerretDB 之前，必须先升级到与之匹配的 DocumentDB 版本，顺序颠倒会导致扩展与 FerretDB 之间的 API 不兼容。

升级 DocumentDB

从发布页下载与目标 FerretDB 版本匹配的新.deb包；

用dpkg覆盖安装：

sudo dpkg -i /path/to/<new-documentdb-package.deb>

在postgres数据库中升级扩展本身：

sudo -u postgres psql -d postgres -c 'ALTER EXTENSION documentdb UPDATE;'

核对postgresql.conf中的预加载配置是否与上文“安装步骤”中列出的内容一致（新版本可能新增或调整 GUC 参数）；
重启 PostgreSQL 使改动生效。

再升级 FerretDB

DocumentDB 升级完成后，再按 FerretDB Docker 更新说明（DEB 路径同理）中的流程下载新ferretdb.deb并执行sudo dpkg -i，最后用ferretdb --version验证版本。

源码中的印证：连接建立时的版本与参数校验

以上配置并非只停留在文档层面。FerretDB 在建立到 PostgreSQL 的连接池时会执行一次连接健康检查，相关实现位于 internal/documentdb/pool_new.go：

每次新连接建立后，会查询version()与documentdb_api.binary_extended_version()，将 PostgreSQL 版本与 DocumentDB 版本写入状态，并与当前 FerretDB 构建期望的 DocumentDB 版本比对；若不匹配，会输出 "Unexpected DocumentDB version" 警告日志，这正是官方文档强调“升级前先装匹配的 DocumentDB 包”的底层原因。
连接建立后还会执行SHOW ALL，并对documentdb.enableUserCrud、documentdb.maxUserLimit等 GUC 参数的实际取值做日志记录，便于排查用户管理功能是否按预期启用。代码注释中亦有被暂缓执行的SET documentdb.enableUserCrud TO true逻辑，进一步印证这两个参数与 FerretDB 用户管理功能（internal/handler/msg_createuser.go、internal/handler/msg_dropuser.go）的强关联。
同时，docker-compose.yml 中开发环境的 PostgreSQL/YugabyteDB 服务也显式传入了documentdb.enableUserCrud = true与documentdb.maxUserLimit = 100，与本文postgresql.conf配置完全对应，可作为参数取值的交叉验证。

常见问题排查

dpkg -i报依赖错误：先sudo apt-get install -f补齐 PostgreSQL 与扩展依赖。
CREATE EXTENSION失败或报shared_preload_libraries相关错误：确认pg_documentdb_core与pg_documentdb已加入预加载列表，并已重启 PostgreSQL；预加载库顺序错误通常表现为启动即报错。
FerretDB 启动后日志出现 "Unexpected DocumentDB version"：说明 DocumentDB 扩展版本与 FerretDB 构建不匹配，需按本文升级流程先对齐 DocumentDB 版本。
无法创建用户或usersInfo为空：检查documentdb.enableUserCrud是否为true、documentdb.maxUserLimit是否够用（默认 100），并确认postgresql.conf修改后已重启生效。

小结

通过 DEB 包部署 DocumentDB 扩展是 FerretDB 在 Debian/Ubuntu 生态中最直接的安装路径：选对生产/开发包、正确预加载扩展库、配置 GUC 参数、CREATE EXTENSION documentdb CASCADE建库，即可完成底层引擎初始化；升级时则严格遵循“先 DocumentDB、后 FerretDB”的顺序，配合ALTER EXTENSION documentdb UPDATE平滑迁移。这套流程与 FerretDB 源码中的连接自检逻辑相互印证，是保证生产环境稳定运行的关键。