WeKan 部署 FerretDB 2 + PostgreSQL（DocumentDB 扩展）完整实战指南

WeKan 部署 FerretDB 2 PostgreSQLDocumentDB 扩展完整实战指南【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan本文以 WeKan 官方文档 docs/Databases/FerretDB/2/README.md 及其配套的 PostgreSQL.md 为主体讲解如何在 WeKan 中接入上游 FerretDB 2将数据持久化到 PostgreSQL 17 DocumentDB 扩展之上。读完本文你将掌握 FerretDB 2 与 v1 的本质差异、官方 Docker Compose 编排的完整用法以及源码编译 WeKan → 安装 PostgreSQL 17 DocumentDB → 安装 FerretDB 2 → 初始化数据库 → 前台或 systemd 启动 WeKan的全流程实操并理解为什么 v2 场景下的MONGO_URL不再需要directConnectiontrue。FerretDB 2 是什么上游版本与唯一后端FerretDB 是一个讲 MongoDB 线协议、把数据存到别处的中间层——WeKan 只通过 MongoDB 驱动与它对话完全不关心它背后是什么。FerretDB 2 是上游upstream官方发布的第二代版本它与 v1 最大的区别是与 v1 一样对外讲 MongoDB wire protocol数据只存储到 PostgreSQL需安装 DocumentDB 扩展v1 时代的其他后端SQLite、MySQL、MariaDB、SAP HANA在 v2 中被全部移除。这一点在仓库总览 docs/Databases/FerretDB/README.md 中有明确的版本对照表目录版本存储后端1FerretDB v1即 wekan/FerretDB 分支——WeKan 的默认数据库SQLite内嵌、PostgreSQL、MySQL、MariaDB、SAP HANA2FerretDB 2上游版本仅 PostgreSQL DocumentDB 扩展为什么 WeKan 仍保留 v1 分支因为 v1 的内嵌 SQLite 后端让 WeKan 可以完全自包含部署连数据库服务器都不用装同时也是 MongoDB 没有服务器构建的 ppc64le、s390x、riscv64 平台上唯一可用的默认数据库。如果你希望在生产环境中把数据真正放进 PostgreSQL那么 FerretDB 2 DocumentDB 就是官方推荐的组合。v2 与 v1 的容器差异原文档特别指出FerretDB 2 的编排运行两个容器——ghcr.io/ferretdb/postgres-documentdb内置 DocumentDB 扩展的 PostgreSQL 17和ghcr.io/ferretdb/ferretdb:2FerretDB 2 本体而 FerretDB v1 只运行一个容器或者在使用独立 SQL 服务器时运行两个。也就是说 v2 的 PostgreSQL 是强制的、不可替换的组成部分。快速开始官方 Docker Compose 编排仓库根目录提供了现成的编排文件 docker-compose-ferretdb-v2-postgresql.yml。原文档给出的启动命令只有一行docker compose -f docker-compose-ferretdb-v2-postgresql.yml up -d停止时使用docker compose -f docker-compose-ferretdb-v2-postgresql.yml stop该编排基于 docs/Databases/FerretDB/2/PostgreSQL.md 整理而成支持所有可运行 Node.js 22 的平台linux/amd64、linux/arm64、linux/arm/v7、linux/ppc64le、linux/s390x。三个服务逐一拆解整个栈由三个服务构成位于同一个wekan-tierbridge 网络内服务镜像作用postgres-documentdbghcr.io/ferretdb/postgres-documentdb:17PostgreSQL 17 DocumentDB 扩展FerretDB 2 的唯一存储后端ferretdbghcr.io/ferretdb/ferretdb:2MongoDB 兼容协议层对外监听:27017wekanghcr.io/wekan/wekan:latest可用版本号标签替代WeKan 应用本体1. postgres-documentdb 服务postgres-documentdb: image: ghcr.io/ferretdb/postgres-documentdb:17 container_name: wekan-postgres restart: always environment: POSTGRES_USER: ferretdb POSTGRES_PASSWORD: ${FERRETDB_POSTGRES_PASSWORD:-ferretdb_secret} POSTGRES_DB: ferretdb volumes: - postgres-data:/var/lib/postgresql/data networks: - wekan-tier关键点数据库用户名默认ferretdb密码通过环境变量FERRETDB_POSTGRES_PASSWORD注入缺省值为ferretdb_secret。生产部署务必通过.env文件或 shell 环境变量覆盖默认密码。2. ferretdb 服务ferretdb: image: ghcr.io/ferretdb/ferretdb:2 container_name: wekan-ferretdb restart: always environment: FERRETDB_POSTGRESQL_URL: postgres://ferretdb:${FERRETDB_POSTGRES_PASSWORD:-ferretdb_secret}postgres-documentdb/ferretdb depends_on: - postgres-documentdb networks: - wekan-tier ports: - 127.0.0.1:27017:27017注意两点FERRETDB_POSTGRESQL_URL是 FerretDB 2 连接 PostgreSQL 的唯一配置项账号密码与上面的POSTGRES_USER/POSTGRES_PASSWORD保持一致端口127.0.0.1:27017:27017默认只绑定到宿主机 localhost编排注释说明移除绑定可让它仅保留在内部网络这是出于安全考虑的默认做法。3. wekan 服务的关键环境变量编排注释里给出了镜像选择的完整示例GitHub Container Registry / Quay / Docker Hub 的latest与版本号标签并强烈建议升级时使用具体版本标签如ghcr.io/wekan/wekan:v6.89而非latest。与 FerretDB 2 强相关的三个环境变量是- METEOR_REACTIVITY_ORDERpolling - DDP_TRANSPORTsockjs - MONGO_URLmongodb://ferretdb:${FERRETDB_POSTGRES_PASSWORD:-ferretdb_secret}ferretdb:27017/wekan?authMechanismPLAINMETEOR_REACTIVITY_ORDERpollingFerretDB 两个版本都没有 MongoDB Change Streams 与副本集 oplog这一点在 docs/Databases/FerretDB/1/README.md 的 The OpLog 一节明确说明因此 WeKan 必须使用轮询polling而不是 oplog tailing。测试 tests/chartsFerretdb.test.cjs 也断言了METEOR_REACTIVITY_ORDER与DEFAULT_METEOR_REACTIVITY_ORDER均为polling。注释中的MONGO_OPLOG_URL被刻意保持未设置状态。DDP_TRANSPORTsockjsWeKan 只随包携带 sockjs 传输bundle 与镜像中均没有 uWebSockets.jsDDP_TRANSPORTuws会在启动时被强制改写为 sockjs。MONGO_URLauthMechanismPLAIN是 FerretDB 2 场景下的认证方式密码与FERRETDB_POSTGRES_PASSWORD联动。其余变量WRITABLE_PATH/data、ROOT_URL、MAIL_URL、WITH_APItrue、BROWSER_POLICY_ENABLEDtrue、LDAP/OAuth2 等与 WeKan 其他部署方式完全一致编排文件内有逐项注释可当作一份可读的配置字典。为什么 FerretDB 2 的 MONGO_URL 不需要 directConnectiontruev1 场景下所有 compose 文件的连接串都是mongodb://ferretdb:27017/wekan?directConnectiontrue这个参数不是装饰而是必需FerretDB v1 以--repl-set-namers0启动hello握手时会把监听地址0.0.0.0:27017填入hosts/me/primaryMongoDB 驱动在非直连模式下会丢弃用户给的种子地址、去做副本集发现结果把连接指向0.0.0.0:27017——在容器里就是应用容器自身什么都不在监听于是首次启动即报ECONNREFUSED对应 issue #6582。而 FerretDB 2不以--repl-set-name启动握手不会宣告副本集因此不会触发发现逻辑也就不需要directConnectiontrue。这一点有测试 tests/ferretdbDirectConnection.test.cjs 明确守护该测试扫描全部 compose 文件凡是以--repl-set-name运行 FerretDB 的文件其MONGO_URL必须带directConnectiontrue同时对 v2 编排做了反向断言——v2 没有--repl-set-name因此被固定为不需要该参数防止未来有人误加--repl-set-name却没有同步补上directConnection。同一测试还守护了 MongoDB 编排真实副本集的成员名可解析绝不能加directConnection否则会把 Meteor 钉死在副本集单个节点上。从源码编译安装 WeKan如果你的目标是绕过 Docker、直接在本机运行 FerretDB 2 PostgreSQL 组合原文档给出了从源码构建的完整步骤。也可以直接使用仓库根目录的 v2 compose 文件默认的 docker-compose.yml 使用的是 FerretDB v1 内嵌 SQLite。git clone --branch main --depth 1 https://github.com/wekan/wekan.git cd wekan sudo apt update sudo apt install -y build-essential gcc g make git curl wget \ p7zip-full zip unzip unp npm sudo npm install -g n export N_NODE_MIRRORhttps://github.com/wekan/node-v14-esm/releases/download sudo -E n 14.21.4 sudo npm -g install mapbox/node-pre-gyp sudo npm -g install meteor2.16 --unsafe-perm export PATH$PATH:$HOME/.meteor meteor npm install production meteor build .build --directory --platformsweb.browser要点说明通过n安装 WeKan 构建所固定的 Node.js14.21.4镜像源指向 wekan 官方的 node-v14-esm 发布目录全局安装 Meteor2.16meteor npm install production只安装生产依赖meteor build .build --directory --platformsweb.browser产出可部署目录.buildsystemd 一节中的WorkingDirectory即指向该目录下的 bundle。安装 PostgreSQL 17 DocumentDB 扩展FerretDB 2 的数据最终落在 PostgreSQL 17 DocumentDB 扩展上。原文档使用 Pigsty 仓库来安装sudo bash -c curl -fsSL https://repo.pigsty.io/pig | bash pig repo add pgsql -u pig ext install pg17 pig ext install documentdb然后编辑/etc/postgresql/17/main/postgresql.conf配置共享预加载库pg_cron与两个 DocumentDB 库shared_preload_libraries pg_cron, pg_documentdb, pg_documentdb_core编辑/etc/postgresql/17/main/pg_hba.conf将127.0.0.1/32与::1/128两条 host 行的认证方式从scram-sha-256替换为trust本地开发场景下简化认证生产环境请按你的安全策略调整。最后重启sudo service postgresql restart安装并配置 FerretDB 2原文档以v2.7.0的 Debian 包为例。下载curl -L \ https://github.com/FerretDB/FerretDB/releases/download/v2.7.0/ferretdb-amd64-linux.deb \ -o /tmp/ferretdb-amd64-linux.deb安装sudo apt -y install /tmp/ferretdb-amd64-linux.deb编辑/etc/systemd/system/ferretdb.service把连接 PostgreSQL 的用户名/密码填入下面这行EnvironmentFERRETDB_POSTGRESQL_URLpostgres://ferret:DB_PASSWORD_GOES_HERE127.0.0.1:5432/postgresFERRETDB_POSTGRESQL_URL与 Docker 编排中同名变量含义一致ferret是下一步要创建的数据库角色名DB_PASSWORD_GOES_HERE换成真实密码端口指向本机 PostgreSQL 5432。然后启用并启动sudo systemctl enable ferretdb.service sudo service ferretdb start初始化数据库FerretDB 2 需要 PostgreSQL 中预先存在可用的角色、数据库与 DocumentDB 扩展。以 postgres 超级用户进入 psql 执行su - su - postgres psql CREATE ROLE ferret WITH PASSWORD DB_PASSWORD_GOES_HERE; CREATE DATABASE ferretdb; GRANT ALL PRIVILEGES ON DATABASE ferretdb TO ferret; ALTER ROLE ferret WITH LOGIN; CREATE EXTENSION documentdb CASCADE; GRANT USAGE ON SCHEMA documentdb_api to ferret; GRANT USAGE ON SCHEMA documentdb_core to ferret; GRANT USAGE ON SCHEMA documentdb_api_internal to ferret; GRANT USAGE ON SCHEMA documentdb_api_catalog to ferret; GRANT INSERT ON TABLE documentdb_api_catalog.collections to ferret; GRANT ALL ON SCHEMA documentdb_data to ferret; GRANT documentdb_admin_role to ferret;说明先建角色ferret注意密码要与FERRETDB_POSTGRESQL_URL中的一致再建数据库ferretdbCREATE EXTENSION documentdb CASCADE是核心步骤它把 DocumentDB 的整套 schema 装入该数据库随后的一系列GRANT是 FerretDB 2 运行所必需的权限documentdb_api*系列 schema 的 USAGE、collections表的 INSERT、documentdb_dataschema 的全部权限以及documentdb_admin_role角色授权。启动 WeKan两种方式原文档提供了两种启动方式这里完整保留。a) 前台屏幕运行开发调试export PATH$HOME/.meteor cd ~/wekan MONGO_URLmongodb://ferret:DB_PASSWORD_GOES_HERE127.0.0.1:27017/wekan \ WRITABLE_PATH.. WITH_APItrue RICHER_CARD_COMMENT_EDITORfalse \ ROOT_URLhttps://wekan.example.com meteor run \ --exclude-archs web.browser.legacy,web.cordova \ --port 8080 21 | tee ../wekan-log.date %s.txt注意MONGO_URL指向 FerretDB 2 监听的127.0.0.1:27017数据库名wekanWeKan 会自行建库--exclude-archs跳过旧浏览器与 Cordova 构建以加快启动日志通过tee落盘。b) systemd 服务生产部署先创建/etc/default/wekan环境文件完整内容如下NODE_ENVproduction MAIL_FROMWeKan kanban boardsexample.com MAIL_URLsmtp://username:passwordemail-smtp.eu-west-1.amazonaws.com:587?tls{ciphers:SSLv3}secureConnectionfalse OAUTH2_AUTH_ENDPOINThttps://accounts.google.com/o/oauth2/v2/auth OAUTH2_CLIENT_IDexample.apps.googleusercontent.com OAUTH2_EMAIL_MAPemail OAUTH2_ENABLEDtrue OAUTH2_FULLNAME_MAPname OAUTH2_ID_MAPsub OAUTH2_REQUEST_PERMISSIONSopenid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email OAUTH2_SECRETtopsecret OAUTH2_TOKEN_ENDPOINThttps://oauth2.googleapis.com/token OAUTH2_USERINFO_ENDPOINThttps://openidconnect.googleapis.com/v1/userinfo OAUTH2_USERNAME_MAPemail MONGO_LOG_DESTINATIONmongodb-log.txt MONGODB_PORT27017 ROOT_URLhttps://boards.example.com WRITABLE_PATH../files MONGO_URLmongodb://ferret:DB_PASSWORD_GOES_HERE127.0.0.1:27017/wekan WITH_APItrue RICHER_CARD_COMMENT_EDITORfalse CARD_OPENED_WEBHOOK_ENABLEDfalse BIGEVENTS_PATTERNNONE BROWSER_POLICY_ENABLEDtrue TRUSTED_URL WEBHOOKS_ATTRIBUTES LDAP_BACKGROUND_SYNC_INTERVAL再创建/etc/systemd/system/wekan.service以普通用户boards运行先用sudo adduser boards建用户拷贝文件后sudo chown boards:boards /home/boards -R[Unit] DescriptionThe Wekan Service Aftersyslog.target network.target [Service] EnvironmentFile/etc/default/wekan Userboards Groupboards WorkingDirectory/home/boards/repos/bundle ExecStart/usr/local/bin/node main.js Restarton-failure SuccessExitStatus143 StandardOutputfile:/home/boards/repos/wekan-output-log.txt StandardErrorfile:/home/boards/repos/wekan-error-log.txt [Install] WantedBymulti-user.target其中WorkingDirectory指向前面meteor build产出的 bundle 目录ExecStart直接以 Node.js 运行main.js。最后启用并启动sudo systemctl enable wekan sudo systemctl start wekan对于 SSL/TLS原文档作者使用 Caddy 作为 Node.js 前面的反向代理详见 Caddy。同主题的周边文档还包括 Raspberry Pi 部署 Raspberry Pi 与 Windows 离线 bundle Offline。硬件要求与注意事项原文档在 Notes 一节给出两条非常实际的硬件经验务必提前评估机器至少 3 GB 内存在 384 MB 内存的机器上npm install meteor会直接崩溃机器至少 4 GB 内存3 GB 内存时meteor build阶段会崩溃。此外文档提醒如果你真的想在生产跑通这套组合需要准备好阅读 releases/build.sh 等构建脚本例如处理n/Meteor 版本、bundle 产物路径等细节按实际环境调整上述步骤。与 FerretDB v1、MongoDB 的关系若希望默认、自包含的部署内嵌 SQLite无需任何数据库服务器使用 FerretDB v1见 docs/Databases/FerretDB/1/README.md若偏爱 MongoDB 本身参考 docs/Databases/MongoDB若需要在 FerretDB 场景下理解 Meteor 的实时同步机制v1 的 OpLog 模拟、两版本都没有 Change Streams 的事实阅读 Oplog-Configuration.md 与 v1 文档的 The OpLog 一节。决策建议FerretDB 2 适合数据必须落在 PostgreSQL、愿意多维护一个 PostgreSQL 17 DocumentDB 实例的生产场景追求零数据库依赖的轻量部署则继续使用默认的 FerretDB v1 SQLite。两者对外都只暴露 MongoDB wire protocolWeKan 应用本身无需任何代码改动。【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考