在 Ubuntu 上安装 FerretDB:PostgreSQL / SQLite 后端部署完整指南

原创2026-09-23 10:03:081,457 阅读
文章标签:数据库文档数据库MCP 服务后端可观测性

在 Ubuntu 上安装 FerretDB:PostgreSQL / SQLite 后端部署完整指南

FerretDB 是一款开源的文档数据库,它让 MongoDB 的语法与生态在 PostgreSQL(或 SQLite)之上得以延续:你既可以使用 mongosh、MongoDB 驱动与既有习惯去读写数据,又可以把数据真正掌握在自己手里。本篇指南以 FerretDB v1.12.1(Ubuntu 22.04 arm64)为基线,完整走一遍在 Ubuntu 上安装 PostgreSQL 后端、配置数据库与账号、通过 .deb 包安装 FerretDB、用 systemd 托管服务、经 mongosh 连接并验证数据落库的每一步;文末还额外演示 SQLite 后端的使用方式,并结合当前仓库源码讲解全部配置标志与常见安全加固点。读完你将能够在自己的 Ubuntu 服务器上独立完成一套可运行的 FerretDB 环境搭建。

前置条件

  • Ubuntu 系统:本教程基于 Ubuntu 22.04(arm64)验证,amd64 的安装步骤一致,仅在下载包架构上有所区分。
  • 非 root 用户:建议提前准备好一个拥有 sudo 权限的非 root 账号,后续所有系统级操作(安装包、配置 systemd)都经由 sudo 完成。
  • mongosh:MongoDB Shell,用于连接与操作 FerretDB 实例,需提前安装到本机。

安装开始前,先确保系统与软件包索引是最新的:

sudo apt update
sudo apt upgrade

Step 1:安装并初始化 PostgreSQL 后端

本指南主要演示 PostgreSQL 后端。如果系统尚未安装 PostgreSQL,先通过包管理器安装:

sudo apt install postgresql

安装完成后可用 psql --version 确认版本。教程验证环境中输出为 psql (14.9 (Ubuntu 14.9-0ubuntu0.22.04.1)),版本号随发行版仓库略有不同,不影响后续操作。

FerretDB 连接 PostgreSQL 时要求:数据库中已存在一个名为 ferretdb 的库,并配好对应的认证凭据。为此,先以 PostgreSQL 超级用户身份进入默认实例:

sudo -u postgres psql

进入后你将看到类似下面的交互提示:

~$ sudo -u postgres psql
psql (14.9 (Ubuntu 14.9-0ubuntu0.22.04.1))
Type "help" for help.

postgres=#

在 postgres=# 提示符下依次执行三条 SQL(请把 <username>、<password> 替换成你自己的账号与密码):

CREATE ROLE <username> WITH PASSWORD '<password>';
CREATE DATABASE ferretdb;
GRANT ALL PRIVILEGES ON DATABASE ferretdb TO <username>;

第一条创建数据库角色(即后续 FerretDB 与 mongosh 使用的登录账号),第二条创建名为 ferretdb 的数据库,第三条把该库的全部权限授予该角色。至此 PostgreSQL 后端就绪。

用 \q 退出 psql,再用新账号连回 ferretdb 库做一次连通性验证:

psql -h localhost -U <username> -d ferretdb

成功连接后输出大致如下:

psql (14.9 (Ubuntu 14.9-0ubuntu0.22.04.1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, bits: 256, compression: off)
Type "help" for help.

ferretdb=>

版本提示:教程基于 v1.12.1,FerretDB 直接把 MongoDB 文档映射为 PostgreSQL 中的表(以 _jsonb 字段存储 BSON 文档);而当前仓库主线已演进到 v2,改为依赖 PostgreSQL 的 DocumentDB 扩展(见 website/docs/installation/ferretdb/deb.md 中的说明),但它同样需要先准备 PostgreSQL 与数据库凭据,本节初始化流程依然适用。

Step 2:下载并安装 FerretDB

FerretDB 官方 releases 页面提供 amd64 与 arm64 两种架构的 .deb 包,请根据 Ubuntu 的 CPU 架构选择。本教程使用 FerretDB v1.12.1 的 arm64 deb 包,用 wget 或 curl 下载均可:

wget <FerretDB 官方 releases 页面中对应版本的下载地址>

或者用 curl(-L 跟随重定向,-J 使用服务器文件名,-O 写为本地文件):

curl -LJO <FerretDB 官方 releases 页面中对应版本的下载地址>

在 ferretdb-arm64.deb 所在目录执行安装:

sudo apt install ./ferretdb-arm64.deb

安装完成后用 ferretdb --version 验证:

ferretdb --version
version: v1.12.1
commit: d1486f2b5d86eadfa6d148752b14fdde49cb5db9
branch: unknown
dirty: true
package: deb
debugBuild: false

输出中的 version、commit、package 等字段来自编译期注入的构建信息。运行 ferretdb --help 可以查看全部配置标志——FerretDB 的所有运行时行为几乎都由这些标志控制。v1.12.1 的完整输出如下:

~$ ferretdb --help
Usage: ferretdb

Flags:
  -h, --help                             Show context-sensitive help.
      --version                          Print version to stdout and exit.
      --handler="pg"                     Backend handler: 'pg', 'sqlite' ($FERRETDB_HANDLER).
      --mode="normal"                    Operation mode: 'normal', 'proxy', 'diff-normal',
                                         'diff-proxy' ($FERRETDB_MODE).
      --state-dir="."                    Process state directory ($FERRETDB_STATE_DIR).
      --listen-addr="127.0.0.1:27017"    Listen TCP address ($FERRETDB_LISTEN_ADDR).
      --listen-unix=""                   Listen Unix domain socket path ($FERRETDB_LISTEN_UNIX).
      --listen-tls=""                    Listen TLS address ($FERRETDB_LISTEN_TLS).
      --listen-tls-cert-file=""          TLS cert file path ($FERRETDB_LISTEN_TLS_CERT_FILE).
      --listen-tls-key-file=""           TLS key file path ($FERRETDB_LISTEN_TLS_KEY_FILE).
      --listen-tls-ca-file=""            TLS CA file path ($FERRETDB_LISTEN_TLS_CA_FILE).
      --proxy-addr=""                    Proxy address ($FERRETDB_PROXY_ADDR).
      --debug-addr="127.0.0.1:8088"      Listen address for HTTP handlers for metrics, pprof,
                                         etc ($FERRETDB_DEBUG_ADDR).
      --postgresql-url="postgres://127.0.0.1:5432/ferretdb"
                                         PostgreSQL URL for 'pg' handler ($FERRETDB_POSTGRESQL_URL).
      --postgresql-new                   Use new PostgreSQL backend ($FERRETDB_POSTGRESQL_NEW).
      --sqlite-url="file:data/"          SQLite URI (directory) for 'sqlite' handler
                                         ($FERRETDB_SQLITE_URL).
      --log-level="info"                 Log level: 'debug', 'info', 'warn', 'error'
                                         ($FERRETDB_LOG_LEVEL).
      --[no-]log-uuid                    Add instance UUID to all log messages ($FERRETDB_LOG_UUID).
      --[no-]metrics-uuid                Add instance UUID to all metrics ($FERRETDB_METRICS_UUID).
      --telemetry=undecided              Enable or disable basic telemetry. See
                                         https://beacon.ferretdb.io ($FERRETDB_TELEMETRY).
      --test-records-dir=""              Testing: directory for record files
                                         ($FERRETDB_TEST_RECORDS_DIR).
      --test-disable-filter-pushdown     Experimental: disable filter pushdown
                                         ($FERRETDB_TEST_DISABLE_FILTER_PUSHDOWN).
      --test-enable-sort-pushdown        Experimental: enable sort pushdown
                                         ($FERRETDB_TEST_ENABLE_SORT_PUSHDOWN).
      --test-telemetry-url="https://beacon.ferretdb.io/"
                                         Telemetry: reporting URL ($FERRETDB_TEST_TELEMETRY_URL).
      --test-telemetry-undecided-delay=1h
                                         Telemetry: delay for undecided state
                                         ($FERRETDB_TEST_TELEMETRY_UNDECIDED_DELAY).
      --test-telemetry-report-interval=24h
                                         Telemetry: report interval
                                         ($FERRETDB_TEST_TELEMETRY_REPORT_INTERVAL).
      --test-telemetry-report-timeout=5s
                                         Telemetry: report timeout
                                         ($FERRETDB_TEST_TELEMETRY_REPORT_TIMEOUT).
      --test-telemetry-package=""        Telemetry: custom package type
                                         ($FERRETDB_TEST_TELEMETRY_PACKAGE).

配置标志速查表

上述标志中日常部署最常用的是以下几组(以当前仓库文档 website/docs/configuration/flags.md 为准,标志与环境变量一一对应):

标志 说明 环境变量 默认值
--postgresql-url PostgreSQL 连接 URL FERRETDB_POSTGRESQL_URL postgres://127.0.0.1:5432/postgres
--listen-addr MongoDB 协议 TCP 监听地址(设为空或 - 可关闭) FERRETDB_LISTEN_ADDR 127.0.0.1:27017
--listen-unix MongoDB 协议 Unix 套接字路径 FERRETDB_LISTEN_UNIX 空
--listen-tls / --listen-tls-cert-file / --listen-tls-key-file / --listen-tls-ca-file TLS 监听地址与证书、密钥、CA 文件 FERRETDB_LISTEN_TLS_* 空
--debug-addr 指标、pprof 等 HTTP 调试服务监听地址 FERRETDB_DEBUG_ADDR 127.0.0.1:8088
--mode 运行模式(normal / proxy / diff-normal / diff-proxy) FERRETDB_MODE normal
--state-dir 状态目录(存放 UUID、telemetry 等状态文件) FERRETDB_STATE_DIR .
--auth(可否定) 是否启用认证 FERRETDB_AUTH 启用
--log-level 日志级别:debug / info / warn / error FERRETDB_LOG_LEVEL info
--telemetry 是否上报基础遥测数据 FERRETDB_TELEMETRY undecided

关键设计:FerretDB 没有配置文件,一切配置都来自命令行标志,同时每个标志都有等价的 FERRETDB_* 环境变量(见 cmd/ferretdb/main.go 中 kong.DefaultEnvars("FERRETDB") 的注册逻辑),这让它在容器、systemd、云原生编排场景下可以非常自然地用环境变量注入配置。

版本差异:--handler(选择 pg / sqlite 后端)与 --sqlite-url 是 v1.12.1 时代的标志;从当前仓库 cmd/ferretdb/main.go 的 CLI 结构看,主线版本已移除这两个标志,改用固定的 PostgreSQL(DocumentDB)后端,并新增了 --postgresql-url-file、--listen-data-api-addr、--listen-mcp-addr、--otel-* 等标志。因此 --handler、--sqlite-url 仅对 v1.12.1 有效,升级到 v2 后请使用 --postgresql-url 系列配置。

Step 3:启动 FerretDB

下面分别演示两种启动方式:终端直启与 systemd 托管。

方式一:终端直接启动

在创建 systemd 服务前,先在终端用显式标志试跑一次。--postgresql-url 中的用户名、密码要替换成 Step 1 中创建的凭据:

ferretdb --postgresql-url="postgres://username:password@localhost/ferretdb"

其余必要标志使用默认值:--mode="normal"、--listen-addr="127.0.0.1:27017"。启动日志大致如下:

~$ ferretdb --postgresql-url="postgres://username:password@localhost/ferretdb"
2023-10-19T12:48:23.202+0100    INFO    ferretdb/main.go:253    Starting FerretDB v1.12.1...    {"version": "v1.12.1", "commit": "d1486f2b5d86eadfa6d148752b14fdde49cb5db9", "branch": "unknown", "dirty": true, "package": "deb", "debugBuild": false, "buildEnvironment": {"-buildmode":"exe","-compiler":"gc","CGO_ENABLED":"0","GOARCH":"arm64","GOOS":"linux","go.version":"go1.21.2","vcs":"git","vcs.time":"2023-10-10T12:15:18Z"}, "uuid": "d66f7807-aec3-406a-9779-2b5ec190e65a"}
2023-10-19T12:48:23.214+0100    INFO    telemetry   telemetry/reporter.go:148   The telemetry state is undecided; the first report will be sent in 1h0m0s. Read more about FerretDB telemetry and how to opt out at https://beacon.ferretdb.io.
2023-10-19T12:48:23.217+0100    INFO    debug   debug/debug.go:86   Starting debug server on http://127.0.0.1:8088/
2023-10-19T12:48:23.217+0100    INFO    listener    clientconn/listener.go:97   Listening on TCP 127.0.0.1:27017 ...

日志中的关键信息与源码逐一对应:Starting FerretDB ... 一行由 cmd/ferretdb/main.go 的启动流程输出,包含版本、commit、构建环境与实例 UUID;debug server 对应 --debug-addr 的 HTTP 调试服务;Listening on TCP 127.0.0.1:27017 则由监听器打印——在 internal/clientconn/listener.go 中,Listen 会按配置分别创建 TCP / Unix / TLS 三类监听器并逐一打印监听地址。若启动失败(例如连不上 PostgreSQL 或凭据错误),进程会直接报错退出,此时先回头检查 Step 1 的账号、库名与权限。

方式二:使用 systemd 托管

把 FerretDB 交给 systemd 管理后,可以实现开机自启、崩溃自动重启、统一日志等能力。

:::caution 请确保存在一个带 sudo 权限的非 root 用户来运行服务。如果还没有,可以这样创建:

sudo adduser ferret
sudo usermod -aG sudo ferret
su - ferret

:::

在 /etc/systemd/system 目录下新建服务文件(User= 应设为你的非 root 用户):

sudo nano /etc/systemd/system/ferretdb.service

内容如下:

[Unit]
Description=FerretDB service
After=network-online.target
Wants=network-online.target

[Service]
User=ferret
ExecStart=/usr/bin/ferretdb --postgresql-url="postgres://username:password@127.0.0.1:5432/ferretdb"
Restart=always

[Install]
WantedBy=multi-user.target

说明:

  • [Unit] 段声明服务依赖网络就绪(network-online.target),避免开机时因网络未就绪而启动失败;
  • [Service] 段指定以 ferret 用户运行(安全最小权限原则),ExecStart 传入后端连接串,Restart=always 保证进程异常退出后自动拉起;
  • [Install] 段将服务挂到 multi-user.target,配合下面的 enable 实现开机自启。

随后依次执行:

sudo systemctl daemon-reload
sudo systemctl enable ferretdb
sudo systemctl start ferretdb

daemon-reload 让 systemd 重新读取新增的服务文件,enable 注册开机自启,start 立即启动。查看运行状态与实时日志:

sudo systemctl status ferretdb
sudo journalctl -u ferretdb -f

更优实践:当前仓库的 .deb/.rpm 包其实已自带 systemd 单元(见 website/docs/installation/ferretdb/deb.md),单元内通过 Environment="FERRETDB_POSTGRESQL_URL=..." 这类变量给出示例配置。官方推荐用 sudo systemctl edit ferretdb 生成 override 配置,而不是直接修改单元文件,这样升级时不会被覆盖——例如要改用 Unix 套接字监听,可在 override 中写 Environment="FERRETDB_LISTEN_UNIX=/var/lib/ferretdb/ferretdb.sock"(见 website/docs/installation/ferretdb/systemd.md)。由于每个标志都有环境变量等价物,systemd 场景下优先用 Environment= 传递 FERRETDB_* 变量,比在 ExecStart 里拼长串参数更易维护。

Step 4:通过 mongosh 连接 FerretDB

FerretDB 运行起来后,另开一个终端,用与 Step 1 相同的用户名和密码,通过 MongoDB 连接串连接:

mongosh "mongodb://username:password@localhost:27017/ferretdb?authMechanism=PLAIN"

成功连接后 mongosh 会显示如下信息:

~$ mongosh "mongodb://username:password@localhost:27017/ferretdb?authMechanism=PLAIN"
Current Mongosh Log ID: 65304b6bb7bd5de804c5e34e
Connecting to:      mongodb://<credentials>@localhost:27017/ferretdb?authMechanism=PLAIN&directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.0.2
Using MongoDB:      6.0.42
Using Mongosh:      2.0.2

For mongosh info see: https://docs.mongodb.com/mongodb-shell/

------
   The server generated these startup warnings when booting
   2023-10-18T21:17:31.774Z: Powered by FerretDB v1.12.1 and PostgreSQL 14.9.
   2023-10-18T21:17:31.774Z: Please star us on GitHub: https://github.com/FerretDB/FerretDB.
   2023-10-18T21:17:31.774Z: The telemetry state is undecided.
   2023-10-18T21:17:31.774Z: Read more about FerretDB telemetry and how to opt out at https://beacon.ferretdb.io.
------

ferretdb>

提示符变为 ferretdb> 即表示连接成功。关于认证机制需要说明两点:

  • v1.12.1 教程演示的连接串使用了 authMechanism=PLAIN;
  • 从当前仓库 website/docs/security/authentication.md 看,FerretDB 本身不存储用户凭据,而是把认证完全委托给 PostgreSQL——客户端连接时提供的用户名/密码必须是 PostgreSQL 中真实存在的角色;客户端侧支持的认证机制为 SCRAM-SHA-256,连接串中通常无需显式指定,mongosh 会自动协商。--no-auth / FERRETDB_AUTH=false 可以关闭认证,但那样任何连接者都能访问数据,不建议在生产环境使用。

Step 5:插入文档并在 PostgreSQL 侧验证

FerretDB 兼容 MongoDB 命令与查询,可以放心执行你熟悉的 MongoDB 操作。通过 mongosh 插入一条文档:

ferretdb> db.playerstats.insertOne({"futbin_id" : 7,"player_name" : "Vieri", "player_extended_name" : "Christian Vieri", "quality" : "Gold - Rare", "revision" : "Icon", "overall" : 88 })
{
  acknowledged: true,
  insertedId: ObjectId("65305ac1b116d06ab74d6a33")
}
ferretdb> db.playerstats.find()
[
  {
    _id: ObjectId("65305ac1b116d06ab74d6a33"),
    futbin_id: 7,
    player_name: 'Vieri',
    player_extended_name: 'Christian Vieri',
    quality: 'Gold - Rare',
    revision: 'Icon',
    overall: 88
  }
]
ferretdb>

insertOne 返回的 insertedId 由 FerretDB 自动生成 ObjectId,find() 能按 MongoDB 语义完整读回文档。

回到 PostgreSQL 侧,看看这条文档在数据库里长什么样。用 Step 1 的账号连接 ferretdb 库并切换 schema:

ferretdb=> set search_path to ferretdb;
SET
ferretdb=> \dt
                     List of relations
  Schema  |            Name             | Type  |  Owner
----------+-----------------------------+-------+----------
 ferretdb | _ferretdb_database_metadata | table | username
 ferretdb | playerstats_0f3be573        | table | username
 ferretdb | test_afd071e5               | table | username
(3 rows)

ferretdb=> SELECT * from playerstats_0f3be573;

可以看到 FerretDB 为 playerstats 集合创建了对应的 PostgreSQL 表(表名带哈希后缀以避免命名冲突),文档被完整存入 _jsonb 列:

                                                                                                                                                                                                                                                         _jsonb
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 {"$s": {"p": {"_id": {"t": "objectId"}, "overall": {"t": "int"}, "quality": {"t": "string"}, "revision": {"t": "string"}, "futbin_id": {"t": "int"}, "player_name": {"t": "string"}, "player_extended_name": {"t": "string"}}, "$k": ["_id", "futbin_id", "player_name", "player_extended_name", "quality", "revision", "overall"]}, "_id": "65305ac1b116d06ab74d6a33", "overall": 88, "quality": "Gold - Rare", "revision": "Icon", "futbin_id": 7, "player_name": "Vieri", "player_extended_name": "Christian Vieri"}
(1 row)

值得留意的是存储格式:$s 字段(schema)记录了每个字段的类型标签(objectId、int、string),$k 记录字段顺序,正文则是实际数据。FerretDB 通过这种带类型信息的 BSON 表示,在 PostgreSQL 的关系模型中保住了文档数据库的类型语义与字段顺序,这也是它能以「MongoDB 协议 + PostgreSQL 存储」方式工作的核心设计之一。

Bonus:在 Ubuntu 上用 SQLite 后端运行 FerretDB

除了 PostgreSQL,v1.12.1 还支持 SQLite 后端。与 PostgreSQL 不同,SQLite 是无服务端(serverless)的——不需要单独的数据库服务进程,数据直接落盘为文件。

启动时只需切换 --handler:

ferretdb --handler="sqlite"

如果 data 目录尚不存在,请先创建(默认 SQLite 数据目录由 --sqlite-url="file:data/" 控制):

mkdir data

随后用不带认证参数、也更简单的连接串连接:

mongodb://localhost:27017/ferretdb

连接后同样会得到 ferretdb> 提示符,Step 5 中的插入、查询操作完全通用:

~$ mongosh "mongodb://username:password@localhost:27017/ferretdb?authMechanism=PLAIN"
Current Mongosh Log ID: 65304b6bb7bd5de804c5e34e
Connecting to:      mongodb://<credentials>@localhost:27017/ferretdb?authMechanism=PLAIN&directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.0.2
Using MongoDB:      6.0.42
Using Mongosh:      2.0.2
------
   The server generated these startup warnings when booting
   2023-10-18T21:17:31.774Z: Powered by FerretDB v1.12.1 and PostgreSQL 14.9.
   2023-10-18T21:17:31.774Z: Please star us on GitHub: https://github.com/FerretDB/FerretDB.
   2023-10-18T21:17:31.774Z: The telemetry state is undecided.
   2023-10-18T21:17:31.774Z: Read more about FerretDB telemetry and how to opt out at https://beacon.ferretdb.io.
------

ferretdb>

v1.12.1 时期 SQLite 后端尚不支持认证(用户名密码不会生效),这一点在选择后端做多用户生产部署时需要留意;SQLite 更适合单机、轻量、评估性场景。同样地,该能力属于 v1.12.1 的 --handler 体系,当前仓库主线已不再提供 --handler/--sqlite-url 标志(参见上文「版本差异」说明)。

生产化建议:日志、遥测与安全加固

  • 遥测(Telemetry):FerretDB 默认上报匿名基础使用数据,帮助项目改进兼容性。--telemetry 有三种状态:enabled、disabled、undecided(默认)。undecided 下首条报告会延迟 1 小时发送,给你留出决定时间;关闭方式包括 --telemetry=disable、环境变量 FERRETDB_TELEMETRY=disable、DO_NOT_TRACK=true,或运行时执行 db.disableFreeMonitoring()(详见 website/docs/telemetry.md)。
  • TLS 加密:若客户端与服务端之间走公网或不可信网络,应通过 --listen-tls、--listen-tls-cert-file、--listen-tls-key-file 启用 TLS 监听;--listen-tls-ca-file 还可开启客户端证书校验(对应实现见 internal/clientconn/listener.go 中的 tlsConfig)。systemd 服务里同样用 Environment="FERRETDB_LISTEN_TLS=..." 注入。
  • 监控与调试:默认 127.0.0.1:8088 的 debug 服务提供 Prometheus 指标与 pprof 性能采样,生产环境请勿将其暴露到公网。
  • 连接池参数:当前版本在连接 PostgreSQL 时,若未显式设置,pool_min_conns 默认为 10、pool_max_conns 默认为 50,application_name 固定为 FerretDB,timezone 固定为 UTC(见 website/docs/configuration/flags.md),这些细节对长连接较多的高并发场景有一定参考价值。

结语

至此,你已经在 Ubuntu 上完整走通了 FerretDB 的部署链路:安装并初始化 PostgreSQL(创建 ferretdb 库与专用账号)→ 下载安装对应架构的 .deb 包 → 通过命令行标志或 systemd 服务启动 → 用 mongosh 连接并写入文档 → 在 PostgreSQL 侧确认数据落库。如果只想快速做本地评估,SQLite 后端一条命令即可跑起来。

部署完成只是开始:FerretDB 作为一个开源项目,欢迎你在此基础上继续探索其配置标志的完整组合(TLS、认证、日志级别、遥测开关),并参阅仓库内的 配置文档 与 安装文档 深化理解;当遇到问题时,源码中的 启动入口、组件装配逻辑 与 监听器实现 是定位问题的最佳线索。

登录后查看全文
FerretDB