Wekan 与 PostgreSQL：ToroDB 只读镜像方案的历史部署指南与 FerretDB 替代路线-创锋一号

Wekan 与 PostgreSQL：ToroDB 只读镜像方案的历史部署指南与 FerretDB 替代路线

【免费下载链接】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/ToroDB/PostgreSQL/README.md 为骨架，完整讲解其历史上的 Docker 一键部署方案：借助 ToroDB 把 Wekan 写入 MongoDB 的数据实时镜像为 PostgreSQL 只读副本，从而让 LibreOffice、报表系统等任何支持 PostgreSQL 的工具直接读取看板数据。读完本文，你将掌握这套 compose 的四个服务与关键环境变量、只读镜像的正确连接与使用边界、MongoDB 数据备份恢复流程，以及 ToroDB 停更后官方推荐的 FerretDB 替代路线。

ToroDB 是什么，为什么它已经停更

ToroDB 是一个用 Java 编写的 MongoDB 代理层，其思路是"替换底层存储"：Wekan 依旧通过 MongoDB 协议读写，而 ToroDB 在背后把数据实际存进 PostgreSQL 或 MySQL。项目代号 Stampede，在 CHANGELOG 中可以看到它从 v0.1（2017-02-13，MongoDB 3.2）一路演进到 v0.9（2018-12-22）的完整历史。

现状必须明确：ToroDB 已经不再开发。docs/Databases/ToroDB/README.md 与 docs/Databases/README.md 均明确指出：Wekan 并不运行在 ToroDB 之上，仓库中保留的仅是历史部署材料与替代方案说明。因此本文内容属于"历史方案复盘"性质：它解释了 Wekan 生态中曾经存在的一条 PostgreSQL 集成路径，也解释了为何今天应改用 FerretDB。

替代路线：FerretDB 与 SQL 后端的现状

原文档在同一页给出了明确的"Try FerretDB instead"指引，要点如下：

FerretDB用 Go 编写，与 ToroDB 是同一思路——在 SQL 数据库之上实现 MongoDB 线协议（wire protocol），让 Wekan 这类 Meteor 应用无需修改即可换用 PostgreSQL 后端；项目官方还引入 Microsoft DocumentDB 以补充额外的兼容能力。
FerretDB/SQLite 旧分支：FerretDB 的main-v1分支保留着 SQLite 后端，社区可以自行维护，但 FerretDB 官方当前不再开发它。
C89 SQLite 的固有问题：原文档指出 C89 版 SQLite 存在并发与数据损坏方面的问题。
Turso 的 Rust SQLite 计划：原文档介绍了 Turso（libsql 的继承者，后迁至 tursodatabase 组织下的 turso 仓库）用 Rust 重写 SQLite 的路线，并借助 TigerBeetle 这类模拟器验证并修复并发、损坏等缺陷；一旦重写完成，Rust 版 SQLite 可作为 C89 版的高并发、防损坏的"drop-in"替代品，语法不变。

在 Wekan 当前仓库中，PostgreSQL 后端的主力方案已是 FerretDB，详见 docs/Databases/FerretDB 与 docs/Databases/README.md（默认部署是 FerretDB v1 内嵌 SQLite，无需独立数据库服务器）。下文回到历史方案本身，讲解 ToroDB/PostgreSQL 只读镜像的部署细节。

架构：Wekan → MongoDB → ToroDB → PostgreSQL 只读镜像

这套方案的链路清晰，来自 README 的原始描述：

Wekan (Meteor/Node.js) ──写入──▶ MongoDB ──同步──▶ ToroDB ──写入──▶ PostgreSQL（只读镜像） ▲ LibreOffice / 报表工具 / 任意 SQL 客户端

核心规则是单向只读：

Wekan 正常读写 MongoDB（数据唯一事实来源）；
ToroDB 订阅 MongoDB 变更，把数据镜像到 PostgreSQL；
任何 SQL 侧工具（LibreOffice、BI 报表、脚本）只允许读 PostgreSQL，绝不能写——写操作应在 Wekan/MongoDB 中完成，再由镜像同步到 PostgreSQL。

这套设计的价值在于：让不具备 MongoDB 技能栈的团队，也能用标准 SQL 生态（Office 套件、报表、任意编程语言的 PostgreSQL 驱动）来查询看板数据。下面的截图展示了当年实测环境中的完整工作流——Wekan 看板界面、LibreOffice Base 连接postgresql://127.0.0.1:15432/wekan并查看wekan.cards表数据、终端执行安装与连接命令：

Docker 部署：完整操作步骤

原 README 给出 10 步部署流程，下面完整保留并补充关键说明。先决条件是宿主机已安装 docker-compose。

第 1~2 步：准备 compose 文件

历史上该方案是作为独立示例仓库维护的（git clone后进入torodb-postgresql目录）。在当前 Wekan 仓库中，该 compose 文件归档于 docs/Databases/ToroDB/PostgreSQL/docker-compose.yml，部署时请先把它复制到一个独立目录（例如mkdir torodb-postgresql && cp docs/Databases/ToroDB/PostgreSQL/docker-compose.yml torodb-postgresql/），再在该目录内执行后续命令。

第 3 步：修改 ROOT_URL（重要）

compose 中 Wekan 默认配置为：

- ROOT_URL=http://localhost

如需在局域网内使用，必须把http://localhost改为真实地址，例如http://192.168.10.100或http://example.com。ROOT_URL直接决定 Wekan 生成的页面链接与登录回调地址，配错会导致页面跳转和登录异常。

第 4 步（可选）：修改 PostgreSQL 凭据

默认数据库名、用户名、密码均为wekan。生产环境建议全部改掉，需同时修改 compose 中postgres服务与torodb-stampede服务两处的对应变量（见下文服务详解）。

第 5~6 步：启动与访问

docker-compose up -d

Wekan 访问地址为http://IPADDRESS或http://example.com（映射到容器内 8080 端口，宿主机 80 端口对外）。
首次启动时 MongoDB 容器会自动初始化名为rs1的副本集（ToroDB 依赖 MongoDB 副本集同步机制），Wekan 的depends_on仅指向mongodb。

第 7 步：连接 PostgreSQL 只读镜像

README 给出的 LibreOffice 连接信息：

dbname=wekan hostaddr=127.0.0.1 port=15432 user=wekan password=wekan

其他应用可使用 URL 形式：

postgresql://127.0.0.1:15432/wekan

用户名wekan、密码wekan（若在第 4 步修改过请保持一致）。注意：这里 README 记载的15432是历史版本端口；当前仓库的 docker-compose.yml 中postgres服务实际映射为"5432:5432"，因此实际端口请以你使用的 compose 文件为准（修改ports映射即可自定义对外端口）。使用原则：

只读：不要向 PostgreSQL 写入任何数据，它只是镜像；
需要修改数据时，回到 Wekan 操作，等待 ToroDB 同步；
若宿主机开放了对应端口（README 原文为 15432），局域网内其他机器也能远程连接该只读库。

第 8~9 步：MongoDB 与其他容器端口

MongoDB 在 README 中记录为127.0.0.1:28017（同样为历史端口，当前 compose 中为"27017:27017"）。
README 同时提醒：Wekan 与数据库均绑定0.0.0.0，因此可能被局域网其他计算机访问到（原作者注明未实测，属于风险提示，生产环境请配合防火墙使用）。

第 10 步：恢复 MongoDB 数据

部署前如需导入既有数据，按导出/恢复 Docker 中 MongoDB 数据操作。该文档的核心流程为：

停止 Wekan：docker stop wekan-app；
进入 MongoDB 容器：docker exec -it wekan-db bash（容器名以你的 compose 为准，本方案中为mongodb）；
备份：容器内执行mongodump -o /dump/，退出后用docker cp wekan-db:/dump .拷出；
恢复：把 dump 拷入容器后执行mongorestore --drop --db wekan /data/dump/wekan/；若遇索引冲突，改用mongorestore --drop --noIndexRestore --db wekan /data/dump/wekan/；
重新启动 Wekan。

docker-compose.yml 服务详解

当前仓库归档的 compose 定义了一个 bridge 网络wekan-tier与四个服务，下面逐一拆解。

mongodb（数据源）

mongodb: image: mongo:3.2 ports: - "27017:27017" entrypoint: - /bin/bash - "-c" - mongo --nodb --eval ' var db; while (!db) { try { db = new Mongo("mongodb:27017").getDB("local"); } catch(ex) {} sleep(3000); }; rs.initiate({_id:"rs1",members:[{_id:0,host:"mongodb:27017"}]}); ' 1>/dev/null 2>&1 & mongod --replSet rs1

固定使用 MongoDB 3.2，因为这是 ToroDB 兼容的版本（见 CHANGELOG v0.2）；
入口脚本先等待自身就绪，再初始化副本集rs1，最后以--replSet rs1启动mongod——副本集是 ToroDB 增量同步的前提；
数据持久化在命名卷mongodb:/data/db，另有mongodb-dump:/dump用于备份。

torodb-stampede（镜像核心）

torodb-stampede: image: quay.io/wekan/torodb-stampede:1.0.0 networks: [wekan-tier] links: [postgres, mongodb] environment: - POSTGRES_PASSWORD=wekan - TORODB_SETUP=true - TORODB_SYNC_SOURCE=mongodb:27017 - TORODB_BACKEND_HOST=postgres - TORODB_BACKEND_PORT=5432 - TORODB_BACKEND_DATABASE=wekan - TORODB_BACKEND_USER=wekan - TORODB_BACKEND_PASSWORD=wekan - DEBUG

环境变量	含义	本文件默认值
`TORODB_SETUP`	首次启动时自动初始化后端库表结构	`true`
`TORODB_SYNC_SOURCE`	同步源，即 MongoDB 地址	`mongodb:27017`
`TORODB_BACKEND_HOST`/`PORT`	后端 PostgreSQL 地址与端口	`postgres`/`5432`
`TORODB_BACKEND_DATABASE`	镜像目标数据库名	`wekan`
`TORODB_BACKEND_USER`/`PASSWORD`	后端数据库账号与密码	`wekan`/`wekan`
`DEBUG`	开启调试日志（未赋值即启用）	—

镜像被固定为quay.io/wekan/torodb-stampede:1.0.0。注意 CHANGELOG v0.4 记载过 ToroDB 因"不支持复合索引（compound indexes）"而退出的问题，该版本已修复——这也是选型时必须锁定版本、不要随意升级的原因之一。

postgres（只读镜像后端）

postgres: image: quay.io/wekan/postgres:9.6 environment: - POSTGRES_PASSWORD=wekan ports: - "5432:5432"

PostgreSQL 9.6 镜像同样由 Wekan 团队从 Docker Hub 迁移至 Quay 以避免拉取限流（compose 注释说明，2020-12-03）。对外端口5432:5432即 SQL 客户端（LibreOffice 等）的连接入口。

wekan（应用）

wekan: image: quay.io/wekan/wekan container_name: wekan-app restart: always ports: - 80:8080 environment: - WRITABLE_PATH=/data - MONGO_URL=mongodb://mongodb:27017/wekan - ROOT_URL=http://localhost - MAIL_URL=smtp://user:pass@mailserver.example.com:25/ - MAIL_FROM='Example Wekan Support <support@example.com>' - WITH_API=true - RICHER_CARD_COMMENT_EDITOR=false - CARD_OPENED_WEBHOOK_ENABLED=false - BIGEVENTS_PATTERN=NONE - BROWSER_POLICY_ENABLED=true - LDAP_BACKGROUND_SYNC_INTERVAL='' depends_on: [mongodb] volumes: - wekan-files:/data:rw

关键点：

MONGO_URL指向mongodb://mongodb:27017/wekan，Wekan 只与 MongoDB 通信，不直接接触 PostgreSQL——这正是 ToroDB 透明代理的意义；
WITH_API=true启用 REST API，也是"导出看板（Export Board）"功能的前置条件，关闭则导出不可用；
BROWSER_POLICY_ENABLED=true启用浏览器安全策略（见 server/policy.js），可配合TRUSTED_URL允许指定站点 iframe 嵌入 Wekan；文档注释明确不建议关闭；
BIGEVENTS_PATTERN=NONE默认关闭"所有成员强制通知"的大事件模式，可改为due或received|start|due|end等正则匹配活动类型；
其余可选变量（S3 附件存储、MONGO_OPLOG_URL、OAuth2/OIDC、LDAP、SAML、CAS、邮件服务等）在 compose 中以注释形式完整保留，可按需取消注释启用；注意 compose 顶部注释强调环境变量值不要加单引号（LDAP_BACKGROUND_SYNC_INTERVAL=''是官方刻意保留的空值写法）；
Wekan 未depends_onPostgreSQL/ToroDB，因为应用本身不依赖镜像链路，MongoDB 就绪即可启动；
wekan-files:/data:rw卷保存上传的附件，对应WRITABLE_PATH=/data。

历史版本演进（CHANGELOG 要点）

CHANGELOG.md 记录了这套 compose 的演进轨迹，可供追溯其行为差异：

v0.1（2017-02-13）：首个版本，实现 Wekan ⇄ MongoDB ⇄ ToroDB → PostgreSQL 只读镜像，支持任意具备 PostgreSQL 驱动的语言/Office 套件（当时为 LibreOffice 3.5+）；
v0.2（2017-04-06）：改用 Meteor 1.4 基础镜像；MongoDB 锁定 3.2 以保证 ToroDB 兼容；
v0.4（2017-08-18）：修复 ToroDB 因不支持复合索引而退出的问题；
v0.5（2018-08-01）：默认启用 Wekan API（保证导出看板可用），新增 Matomo 统计选项；
v0.6（2018-08-03）：wekan-app 容器内部端口统一为 8080；
v0.7 / v0.8（2018-08）：新增 browser-policy、trusted-url、webhooks 设置与 OAuth2；
v0.9（2018-12-22）：更新到当时最新的 Wekan 与 ToroDB 镜像，补齐环境变量文档。

总结：什么时候用这套方案

若你的环境仍然依赖 ToroDB/PostgreSQL 这套历史镜像，本文的 compose 解析与运维步骤（只读原则、凭据修改、备份恢复、端口说明）可直接对照使用；
若你正在规划新的 PostgreSQL 后端部署，仓库官方指引是改用 FerretDB：同样是把 MongoDB 数据落到 SQL 数据库，但它是活跃维护的 Go 实现，也是 Wekan 当前默认数据库后端（详见 docs/Databases/README.md），不要再基于已停更的 ToroDB 新建生产环境。

无论选择哪条路线，请牢记本方案的根本约束：PostgreSQL 只是只读镜像，一切数据变更都要回到 Wekan/MongoDB 一侧完成。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析