在 Debian/Ubuntu 上通过 DEB 包安装 DocumentDB 扩展并部署 FerretDB

后端数据库文档数据库【免费下载链接】FerretDBA 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_namepg_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 安装指南 继续部署 FerretDBsudo dpkg -i ferretdb.deb ferretdb --versionFerretDB 的 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 使改动生效。再升级 FerretDBDocumentDB 升级完成后再按 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 源码中的连接自检逻辑相互印证是保证生产环境稳定运行的关键。赞分享后端数据库文档数据库【免费下载链接】FerretDBA truly Open Source MongoDB alternative项目地址https://gitcode.com/gh_mirrors/fe/FerretDB点击查看免费下载相关推荐openwork Den Worker Runtime 深度解析云端工作节点的 OpenCode 预置与启动机制openwork Den Worker Runtime 深度解析云端工作节点的 OpenCode 预置与启动机制 openwork 的云工作节点Worker后端数据库文档数据库Compose Multiplatform 组件库指南Resources 资源库的跨平台加载、Demo 运行与测试体系Compose Multiplatform 组件库指南Resources 资源库的跨平台加载、Demo 运行与测试体系 导读 本文以 components/后端数据库文档数据库oh-my-pi eval 工具实战指南在持久化语言内核中逐格执行代码oh my pi eval 工具实战指南在持久化语言内核中逐格执行代码 导读 eval 是 oh my pi 编码代理提供的「一格调用 一个代码单元」的执后端数据库文档数据库上一篇OpenCore Legacy Patcher 终极指南4步让老Mac焕发新生的完整教程 下一篇告别类型混乱ReactRedux项目中interface与type的终极选择指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考