在 Ubuntu 上安装 FerretDB:PostgreSQL / SQLite 后端部署完整指南
在 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、认证、日志级别、遥测开关),并参阅仓库内的 配置文档 与 安装文档 深化理解;当遇到问题时,源码中的 启动入口、组件装配逻辑 与 监听器实现 是定位问题的最佳线索。