企业官网建设流程全解析

Wekan MongoDB Oplog 启用实战指南：从本地开发到生产部署的实时性能调优

【免费下载链接】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 仓库中的 OpLog-Enablement.md 为核心脉络，系统讲解 MongoDB Oplog（以及 Meteor 3 的 Change Streams）在 Wekan 各部署形态中的启用状态、配置方法与验证手段。读完本文，你将掌握在本地脚本、Docker Compose、Snap 与生产集群中正确开启实时订阅通道，并学会用可复现的命令验证 Oplog 生效、观测 CPU 与延迟的改善效果。

为什么 Oplog 对 Wekan 如此关键

Wekan 基于 Meteor 构建，所有看板、卡片、列表的实时更新都依赖 Meteor 的 pub/sub 机制与浏览器端 DDP 协议。Meteor 有两种数据变更发现方式：

• Oplog 驱动（推荐）：Meteor 在 MongoDB 副本集的local.oplog.rs上维持一个 tailable cursor，订阅所有数据库写入，把变化实时推送给已订阅的客户端，避免昂贵的轮询与全量 diff。
• Polling 驱动（默认降级）：Meteor 每隔若干毫秒轮询查询，并对比整个结果集。这会导致 CPU 占用升高、网络流量持续、更新延迟放大到秒级。

从源码结构可以确认，Wekan 在启动脚本中显式控制响应式驱动顺序。在 start-wekan.sh 中，当检测到本地 MongoDB 副本集已就绪时，会设置：

export METEOR_REACTIVITY_ORDER=changeStreams,oplog,polling export DDP_TRANSPORT=sockjs

否则回退为：

export METEOR_REACTIVITY_ORDER=polling

这里的changeStreams,oplog,polling表示 Meteor 依次尝试 Change Streams、Oplog、Polling 三种观测器，优先级从高到低。DDP_TRANSPORT=sockjs则是因为当前 Wekan 构建产物只携带 sockjs 传输层。仓库中 docker-compose-mongodb-v7.yml 是启用 MongoDB 副本集的标准 Compose 模板，而默认的 docker-compose.yml 使用 FerretDB v1，其部署是 polling-only 的。

启用前后性能对比

OpLog-Enablement.md 给出了同一批 UI 优化在两种模式下的表现差异：

这些数字同时被仓库中的生产部署文档佐证：AWS.md 记录了一个实际案例——多实例 Wekan 在设置MONGO_OPLOG_URL后，"所有 Wekan 实例的 CPU 使用率降至平均 10% 以下，仅偶发峰值"。

各部署平台的启用配置

1. 本地开发（start-wekan.sh / start-wekan.bat）

仓库根目录的 start-wekan.sh 与 start-wekan.bat 已内置完整的副本集初始化逻辑：它们通过snap-src/bin/db-eval.mjs（Node.js + 内置mongodb驱动，无需安装 mongosh）检查127.0.0.1:27017上的副本集状态，未初始化则自动执行rs-initiate，初始化成功后将USE_CHANGE_STREAMS=true并导出：

export MONGO_OPLOG_URL=mongodb://127.0.0.1:27017/local?replicaSet=rs0

对应的 Windows 批处理语法为：

SET MONGO_OPLOG_URL=mongodb://127.0.0.1:27017/local?replicaSet=rs0

脚本头部还给出了本地mongod的推荐启动参数，其中--oplogSize 20480表示将 Oplog 大小设为 20GB（约 20480MB），--replSet rs0开启单节点副本集：

mongod --storageEngine wiredTiger --wiredTigerCacheSizeGB 32 \ --timeZoneInfo /usr/share/zoneinfo \ --setParameter logicalSessionRefreshMillis=900000 \ --setParameter localLogicalSessionTimeoutMinutes=45 \ --oplogSize 20480 --replSet rs0 --bind_ip 127.0.0.1 --port 27017

手动初始化副本集（若使用旧版 MongoDB 或跳过脚本自动初始化）的步骤：

mongosh > rs.initiate() > rs.status()

2. Docker Compose

官方 MongoDB 7 模板 docker-compose-mongodb-v7.yml 中的 MongoDB 服务以--replSet rs0启动，并使用--oplogSize 20480预留 Oplog 空间：

mongodb: image: mongo:7 command: mongod --storageEngine wiredTiger --wiredTigerCacheSizeGB 32 --timeZoneInfo /usr/share/zoneinfo --setParameter logicalSessionRefreshMillis=900000 --setParameter localLogicalSessionTimeoutMinutes=45 --oplogSize 20480 --replSet rs0 --bind_ip_all --quiet &

Wekan 服务侧需要同时配置两个变量：

environment: - MONGO_URL=mongodb://wekandb:27017/wekan?replicaSet=rs0 - MONGO_OPLOG_URL=mongodb://wekandb:27017/local?replicaSet=rs0

注意MONGO_URL中也带上了replicaSet=rs0，驱动会据此发现副本集拓扑；MONGO_OPLOG_URL指向local数据库并同样携带副本集名。修改后执行：

docker compose -f docker-compose-mongodb-v7.yml up -d

3. Docker 单容器

Dockerfile 已在镜像环境变量中声明了MONGO_OPLOG_URL=""，运行时通过-e注入即可：

docker run \ -e MONGO_URL=mongodb://mongodb:27017/wekan \ -e MONGO_OPLOG_URL=mongodb://mongodb:27017/local?replicaSet=rs0 \ wekan:latest

前提是所连接的 MongoDB 必须以副本集模式运行，例如容器内command: mongod --replSet rs0。

4. Snap 安装

Snap 部署通过snap set配置，并与wekan-control脚本联动。仓库中的 snap-src/bin/wekan-control 显示：非 FerretDB 数据库且未显式设置时，脚本会自动导出MONGO_OPLOG_URL；而 FerretDB 场景下则通过wekan-ferretdb-oplog开关决定是否使用 Oplog，关闭时会unset MONGO_OPLOG_URL并强制METEOR_REACTIVITY_ORDER=polling。手动配置命令为：

sudo snap set wekan MONGO_OPLOG_URL=mongodb://127.0.0.1:27017/local?replicaSet=rs0

查看当前配置：

sudo wekan.wekan-help | grep MONGO_OPLOG snap get wekan wekan-ferretdb-oplog # FerretDB 场景下应输出 false

5. 生产部署（Atlas / 自建副本集）

生产环境要求 MongoDB 运行在副本集模式下（即使是单节点也算副本集），并带认证信息：

MONGO_OPLOG_URL=mongodb://<username>:<password>@<host>/local?authSource=admin&replicaSet=rsName

以 MongoDB Atlas 为例：

MONGO_URL=mongodb+srv://user:password@cluster.mongodb.net/wekan?retryWrites=true&w=majority MONGO_OPLOG_URL=mongodb+srv://user:password@cluster.mongodb.net/local?authSource=admin&replicaSet=atlas-replica-set

local是 MongoDB 内部用于存放 Oplog 的系统库，authSource=admin指定认证库，replicaSet必须与集群实际副本集名一致。

6. 云平台与异构后端

• AWS：详见 AWS.md，其中给出了MONGO_OPLOG_URL=mongodb://<username>:<password>@<mongoDbURL>/local?authSource=admin&replicaSet=rsWekan的 Compose 写法；文中还提及可通过 Redis Oplog 进一步提升多实例扩展性（AWS ElastiCache 提供 Redis）。
• ToroDB/PostgreSQL：ToroDB 后端同样支持 Oplog，配置示例见 docker-compose.yml。
• LDAP 等登录模块：LDAP 与 Oplog 的组合配置见 LDAP.md。

验证 Oplog 是否生效

启用后按以下三步确认：

1. 检查 MongoDB 副本集状态：

mongosh > rs.status() # 应显示副本集成员列表，且存在一个 PRIMARY

2. 检查 Wekan 日志中的 Oplog 痕迹：

tail -f wekan.log | grep -i oplog

从 Migrations.md 可知，OpLog 尾随（tail）在运行时表现为 Meteor 在local.oplog.rs上持有 tailable cursor；日志中应出现 "oplog enabled" 之类的确认信息。反之，如果进入 polling 模式，wekan-control会主动清空MONGO_OPLOG_URL，此时日志不会出现 Oplog 尾随迹象。

3. 监控性能变化：

# CPU 应从 20-30% 降至 3-5% top -p $(pgrep node)

实施检查清单

以下清单可直接对照执行（源自 OpLog-Enablement.md）：

• 本地开发
  • 运行mongosh > rs.initiate()初始化副本集（或由start-wekan.sh/start-wekan.bat自动完成）
  • 在脚本中启用MONGO_OPLOG_URL（新版本脚本在副本集就绪时会自动导出）
  • 重启 Wekan
• Docker Compose
  • MongoDB 服务以mongod --replSet rs0启动
  • 在 Wekan 服务环境变量中加入MONGO_OPLOG_URL
  • 执行docker compose up --build
• Snap
  • 执行sudo snap set wekan MONGO_OPLOG_URL=...
  • 用sudo wekan.wekan-help验证
• 生产环境
  • 确认 MongoDB 副本集已正确配置
  • 在启动 Wekan 前设置环境变量
  • 监控 CPU 使用率（应明显下降）

关键注意事项与故障排查

注意事项：

• Oplog 强制要求 MongoDB 以副本集模式运行，即使只有一个节点也必须初始化副本集。
• 不启用 Oplog 时，所有 pub/sub 优化都会以降级性能运行：实时更新延迟约 2000ms，CPU 占用高出 4–10 倍。
• 建议在所有部署上启用 Oplog；繁忙部署至少保持2GB的 Oplog 大小，并持续监控 Oplog 窗口（window），防止 Oplog 被写满后旧变更被提前覆盖。

常见问题：

深入阅读

• Oplog-Configuration.md——完整的 Oplog 配置指南（为什么重要、全平台配置、验证、性能影响、故障排查）
• MongoDB README——Wekan 支持 MongoDB 3.0–8.0，并说明默认数据库为 FerretDB v1
• AWS.md——AWS 生产部署的 Oplog 配置与多实例扩展经验
• Migrations.md——Oplog 尾随与 polling 模式在迁移问题诊断中的表现
• docker-compose-mongodb-v7.yml——可直接使用的 MongoDB 7 + 副本集 Compose 模板
• start-wekan.sh / start-wekan.bat——本地启动脚本中的副本集自动初始化与METEOR_REACTIVITY_ORDER切换逻辑

结论

Oplog 是 Wekan 实时体验与多实例扩展性的性能地基。仓库已在本地脚本、Docker 模板、Snap 配置与生产文档四个层面完成了启用支持：本地开发甚至可以在不安装 mongosh 的情况下自动初始化副本集。对运维人员而言，核心动作只有三步——把 MongoDB 跑成副本集、正确设置MONGO_OPLOG_URL、按上文清单验证；完成后，迁移状态、Cron 跟踪、配置变更等实时优化即可从 2000ms 的轮询延迟跃升到 50ms 以内的事件驱动响应。

【免费下载链接】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