FerretDB Systemd 服务部署与配置实战指南：使用 systemctl 管理 MongoDB 兼容数据库服务

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

本指南围绕 FerretDB 随 DEB / RPM 安装包附带的 systemd unit 展开，讲解如何将 FerretDB 注册为开机自启的系统服务、通过systemctl edit覆盖环境变量，并结合仓库内真实的 unit 文件与命令行参数解析源码，说明每个配置项的实际作用。读完本文，你将能够在 Debian/Ubuntu 或 RHEL/CentOS 系列服务器上完整落地一个由 systemd 托管的 FerretDB 实例，并掌握从监听地址、Unix 域套接字到 PostgreSQL 连接串的进阶配置方法。

前置条件：先通过 DEB 或 RPM 安装 FerretDB

systemd unit 随安装包一起分发，因此在使用 systemd 之前，需要先完成二进制安装。FerretDB 官方提供生产包（如ferretdb.deb/ferretdb.rpm）与调试包（带-dev后缀，性能显著下降，不建议生产使用），对应安装方式参见 .deb 安装指南 与 .rpm 安装指南。

以.deb系（Debian、Ubuntu）为例：

sudo dpkg -i ferretdb.deb ferretdb --version

以.rpm系（RHEL、CentOS）为例：

sudo rpm -i ferretdb.rpm ferretdb --version

需要特别说明的是：FerretDB 安装包不会自动安装 PostgreSQL。由于 v2 系列以 PostgreSQL（配合 DocumentDB 扩展）作为后端，请提前确保 PostgreSQL 可用。.rpm包可通过sudo yum install -y postgresql安装；.deb包对应的 DocumentDB 扩展安装参见仓库中的 DocumentDB 安装文档。

随包附带的 unit 文件解析

安装完成后，systemd 会获得一个名为ferretdb的服务单元，用于在系统启动时自动拉起 FerretDB。仓库中真实打包的 unit 文件位于 build/ferretdb.service，内容如下：

[Unit] Description=FerretDB Database Documentation=https://docs.ferretdb.io/ Wants=network-online.target After=network-online.target [Service] ExecStart=/usr/bin/ferretdb Restart=on-failure # Configure the FerretDB service with `systemctl edit ferretdb`. # For more configuration options check https://docs.ferretdb.io/configuration/flags/ Environment="FERRETDB_POSTGRESQL_URL=postgres://127.0.0.1:5432/postgres" [Install] WantedBy=multi-user.target

几个值得注意的设计点：

• [Unit]段声明了Wants与After均为network-online.target，确保 FerretDB 在网络就绪后再启动，避免后端连接因网络未初始化而失败；
• [Service]段中ExecStart=/usr/bin/ferretdb直接启动主进程，Restart=on-failure让服务在非正常退出时自动拉起，这是实现"开机自启 + 崩溃自愈"的关键；
• 内置了一条示例环境变量FERRETDB_POSTGRESQL_URL=postgres://127.0.0.1:5432/postgres，即默认的 PostgreSQL 连接地址；
• [Install]段的WantedBy=multi-user.target表示服务会随多用户运行级别被启用。

安装完成后即可启动并设置开机自启：

sudo systemctl daemon-reload sudo systemctl enable --now ferretdb sudo systemctl status ferretdb

查看实时日志可使用：

journalctl -u ferretdb -f

配置方式：环境变量与命令行参数的等价关系

unit 文件中的环境变量并非固定写法，而是每个命令行 flag 都拥有等价的环境变量这一设计原则的体现。从 cmd/ferretdb/main.go 的源码可以看到，FerretDB 使用kong库解析参数，并通过kong.DefaultEnvars("FERRETDB")将--xxx-yyy形式的 flag 自动映射为FERRETDB_XXX_YYY形式的环境变量：

// cmd/ferretdb/main.go var cli struct { PostgreSQLURL string `name:"postgresql-url" default:"postgres://127.0.0.1:5432/postgres" ...` ... } kongOptions = []kong.Option{ ... kong.DefaultEnvars("FERRETDB"), }

这意味着"配置文件不存在，全部配置都通过 flag 或环境变量注入"，恰好与 systemd 的Environment=机制天然契合。官方文档的完整参数清单见 配置参数文档，下表中列出与 systemd 部署最相关的配置项：

另外两点值得在生产环境注意的细节：

• 若设置了FERRETDB_POSTGRESQL_URL_FILE，源码中会在启动前用文件内容覆盖FERRETDB_POSTGRESQL_URL，适合把连接串放在权限受控的文件中（见 cmd/ferretdb/main.go 中if len(cli.PostgreSQLURLFile) > 0的处理）；
• checkFlags会把值为-的监听类 flag 归一化为空串，等价于"禁用该监听"，因此即使通过环境变量把值设为-也不会误启动监听。

用 systemctl edit 覆盖默认配置

unit 文件中的环境变量只是示例，应替换为符合你环境的真实配置。FerretDB 官方推荐的做法是使用 systemd 的 drop-in 机制，执行：

sudo systemctl edit ferretdb

该命令会打开编辑器并生成位于/etc/systemd/system/ferretdb.service.d/override.conf的覆盖文件。任何写在上方注释区与"Lines below this comment will be discarded"之间的内容，都会与原始 unit 合并，从而覆盖原有配置。

示例一：监听 Unix 域套接字

官方文档给出的典型场景是在本机部署时改用 Unix 域套接字，以省去 TCP 端口暴露。覆盖文件可写为：

### Editing /etc/systemd/system/ferretdb.service.d/override.conf ### Anything between here and the comment below will become the new contents of the file [Service] Environment="FERRETDB_LISTEN_UNIX=/var/lib/ferretdb/ferretdb.sock" ### Lines below this comment will be discarded ...

写入后执行sudo systemctl daemon-reload && sudo systemctl restart ferretdb即可生效。此时 MongoDB 客户端可通过mongodb:///var/lib/ferretdb/ferretdb.sock连接（注意：套接字所在目录/var/lib/ferretdb需确保存在且运行用户可写）。从 cmd/ferretdb/readyz.go 的实现可以看到，就绪探针会把cli.Listen.Unix自动转换为mongodb://<url-encoded-path>形式的连接串执行ping，因此该套接字路径同样会被用于健康检查，无需额外配置。

示例二：调整监听地址与连接串

若希望服务对外提供 MongoDB 协议（例如监听所有网卡），并指向远端 PostgreSQL，可在覆盖文件中同时设置多项：

[Service] Environment="FERRETDB_LISTEN_ADDR=0.0.0.0:27017" Environment="FERRETDB_POSTGRESQL_URL=postgres://ferret:secret@10.0.0.5:5432/ferretdb"

请权衡安全边界：监听0.0.0.0时建议同时启用认证（默认开启），或在前面叠加 TLS 监听（相关参数见 TLS 连接文档）。

验证服务可用性

配置完成后，除systemctl status ferretdb外，FerretDB 本身也提供了两种验证手段：

• 版本校验：ferretdb --version输出版本、commit、分支等构建信息；
• 就绪探测：FerretDB 内置ping子命令，它会按照当前配置的监听地址（TCP 或 Unix 套接字）实际发起 MongoDB wire 协议请求，只有ping返回ok: 1才判定就绪，可用于脚本化健康检查（实现见 cmd/ferretdb/readyz.go）。

因此，在 systemd 之外还可以配合ferretdb ping判断实例是否真正可服务，而不仅依赖进程存活状态。

注意事项与限制

• 实验性功能：随包分发 systemd unit 这一特性当前仍标记为实验性（原文档中的:::note提示），遇到问题可在社区反馈；
• 后端依赖：FerretDB 不负责安装 PostgreSQL 与 DocumentDB 扩展，请确保后端可用后再启动服务；升级时也需先升级匹配版本的 DocumentDB 包（见 .deb 更新指南）；
• 默认值差异：官方 Docker 镜像会对部分默认值进行覆盖（如监听地址、状态目录），而 systemd 部署直接使用二进制默认值，迁移时需留意二者差异，完整默认值以上述配置表格为准；
• 覆盖文件优先级：通过systemctl edit生成的 drop-in 文件会合并而非替换原 unit，如需彻底关闭某项监听，将对应环境变量置空或设为-即可。

至此，一个由 systemd 全权托管、支持崩溃自愈与开机自启、并可通过 drop-in 灵活调整监听方式与后端连接的 FerretDB 服务便部署完成，你可以在此基础上继续按需叠加 TLS、认证与监控能力。

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