Wekan 看板数据持久化架构重构指南泳道高度与列表宽度的 Per-Board 与 Per-User 分离实践【免费下载链接】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/wekanWekan 是一个基于 Meteor 构建的开源看板应用。2025-12-23 的数据持久化审计带来了一项关键架构决策泳道swimlane高度与列表list宽度从每个用户各自保存改为每个看板共享保存而折叠状态、标签显隐等个人偏好则继续保留在用户维度。本文以 docs/Security/PerUserDataAudit2025-12-23/IMPLEMENTATION_GUIDE.md 为骨架结合 models/swimlanes.js、models/lists.js、models/users.js 等仓库源码完整讲解 Schema 变更、用户模型重构、客户端存储层改造、数据迁移脚本、测试清单与回滚方案。读完你将对共享数据与私有数据如何分层设计有可直接落地的完整认识。一、为什么必须区分 Per-Board 与 Per-User看板上有两类性质完全不同的数据看板级Per-Board共享数据泳道高度、列表宽度、卡片/清单/清单项的排序位置、所有标题、颜色、描述等。这些数据描述的是看板本身长什么样所有用户应当看到完全一致的视图。用户级Per-User私有数据泳道/列表/卡片的折叠状态、迷你卡片标签文字的显隐等。这些是个人偏好User A 的折叠不能影响 User B 的视野。在本次重构之前泳道高度profile.swimlaneHeights和列表宽度profile.listWidths被错误地存放在user.profile中属于用户私有数据。这带来的直接问题是同一看板上不同用户看到的泳道高度、列表宽度可能不一致甚至未登录的访客与登录成员看到的尺寸都不同。完整的分类矩阵与存储位置定义见 DATA_PERSISTENCE_ARCHITECTURE.md其数据流章节明确给出了两种数据各自的写入与读取链路。二、Schema 变更把共享数据搬进业务文档2.1 Swimlanes新增height字段在 models/swimlanes.js 中泳道集合新增了height字段源码实现与文档完全一致height: { /** * The height of the swimlane in pixels. * -1 auto-height (default) * 50-2000 fixed height in pixels */ type: Number, optional: true, defaultValue: -1, custom() { const h this.value; if (h ! -1 (h 50 || h 2000)) { return heightOutOfRange; } }, },关键语义取值含义-1自动高度默认值不写该字段时自动生效50~2000固定高度像素其他被custom()校验拒绝返回heightOutOfRange模式文件底部models/swimlanes.js专门用注释明确了边界折叠状态是 per-user 数据只存于profile.collapsedSwimlanes与未登录用户的 localStorage而height是 per-board 共享数据存在swimlanes.height。2.2 Lists新增width字段models/lists.js 中列表集合新增width字段width: { /** * The width of the list in pixels (100-1000). * #6465: default width is 220 pixels (was 272) so more lists fit on * screen; kept in sync with DEFAULT_LIST_WIDTH in models/lib/listWidth.js. */ type: Number, optional: true, defaultValue: 220, custom() { const w this.value; if (w 100 || w 1000) { return widthOutOfRange; } }, },需要注意一个仓库实际状态与文档存在差异的点文档编写时默认宽度是272但当前仓库已按 issue #6465 将默认宽度收窄为220像素让更多列表能显示在屏幕上。这一默认值的单一来源被抽取到了 models/lib/listWidth.js其中定义了DEFAULT_LIST_WIDTH 220所有未定制列表渲染的统一默认宽度MIN_LIST_WIDTH 200定制列表允许的最小宽度低于 Schema 校验上限100两者不一致是历史演进的结果isValidListWidth/normalizeListWidth/resolveListWidth宽度校验、归一化与解析函数。resolveListWidth的解析优先级见 models/lib/listWidth.js非常值得关注用户开启所有列表同宽模式fixedEnabled时直接使用单一fixedWidth否则取lists.width这个看板级共享宽度sharedWidth只有当看板开启个人列表宽度personalMode对应board.allowsPersonalListWidth时才回落到用户自己的personalWidth登录用户存 profile匿名用户存 localStorage。也就是说当前仓库的宽度体系已经比审计文档更进一步共享的lists.width只是默认来源个人宽度变成显式开关后的可选覆盖。这恰好印证了文档共享数据默认一致、私有数据按需隔离的设计思想。2.3 无需变更的部分以下实体在重构前就已经使用看板级sort字段存储排序位置本就属于 per-board 数据无需任何改动实体排序字段位置Cardscard.sortdecimalmodels/cards.jsChecklistschecklist.sortmodels/checklists.jsChecklistItemschecklistItem.sortmodels/checklistItems.js以泳道排序为例models/swimlanes.js 的copy助手在插入新泳道时会计算相邻两个 sort 值的平均数作为新 sort正是decimal 小数排序策略的落地实现。三、用户模型重构从 profile 搬走共享数据3.1 现状问题仓库当前仍保留旧实现审计文档描述了要修改的四个用户方法当前 models/users.js 中仍能看到重构前的实现可作为迁移前状态的参照getListWidths()models/users.js直接读取this.profile.listWidthsgetListWidth(boardId, listId)models/users.js优先查profile.listWidths[boardId][listId]否则回退到DEFAULT_LIST_WIDTHgetSwimlaneHeights()/getSwimlaneHeight()models/users.js同理读取profile.swimlaneHeightssetListWidth(boardId, listId, width)models/users.js与setSwimlaneHeight(boardId, swimlaneId, height)models/users.js把值写回profile.listWidths/profile.swimlaneHeights。与此同时Schema 中profile.listWidthsmodels/users.js与profile.swimlaneHeightsmodels/users.js两个 blackbox 对象字段正是文档第 2 节要求删除的字段。3.2 Option A新建持久化助手模块推荐文档推荐新建models/lib/persistenceHelpers.js把读写逻辑收敛到业务文档上// Get swimlane height from swimlane document (per-board storage) export const getSwimlaneHeight (swimlaneId) { const swimlane Swimlanes.findOne(swimlaneId); return swimlane swimlane.height ! undefined ? swimlane.height : -1; }; // Get list width from list document (per-board storage) export const getListWidth (listId) { const list Lists.findOne(listId); return list list.width ! undefined ? list.width : 272; }; // Set swimlane height in swimlane document (per-board storage) export const setSwimlaneHeight (swimlaneId, height) { if (height ! -1 (height 50 || height 2000)) { throw new Error(Height out of range: -1 or 50-2000); } Swimlanes.update(swimlaneId, { $set: { height } }); }; // Set list width in list document (per-board storage) export const setListWidth (listId, width) { if (width 100 || width 1000) { throw new Error(Width out of range: 100-1000); } Lists.update(listId, { $set: { width } }); };3.3 Option B直接修改用户方法文档给出了四个方法的改造前后对照核心是把查 profile → 回退默认值替换为查业务文档 → 回退默认值并移除boardId参数// 改造后从 list 文档读取共享宽度 getListWidth(listId) { const list ReactiveCache.getList({ _id: listId }); return list list.width ? list.width : 272; }, // 改造后从 swimlane 文档读取共享高度 getSwimlaneHeight(swimlaneId) { const swimlane ReactiveCache.getSwimlane(swimlaneId); return swimlane swimlane.height ? swimlane.height : -1; }, // 改造后写入 list 文档 setListWidth(listId, width) { Lists.update(listId, { $set: { width } }); }, // 改造后写入 swimlane 文档 setSwimlaneHeight(swimlaneId, height) { Swimlanes.update(swimlaneId, { $set: { height } }); },这里引入的ReactiveCache是 Wekan 的响应式缓存层imports/reactiveCache.js它的getList/getSwimlane能减少对 MongoDB 的直接查询并保持响应式更新客户端与服务端共用。这也是为何当前仓库的宽度解析模块被刻意设计成 Meteor-free 的纯 Node 模块models/lib/listWidth.js以便在纯 Node 环境下做单元测试参见tests/listWidthDefaults.test.cjs。3.4 必须保留的 Per-User 存储方法折叠状态与标签显隐继续留在用户 profile这些方法原样保留// 折叠泳道per-user getCollapsedSwimlanes() { const { collapsedSwimlanes {} } this.profile || {}; return collapsedSwimlanes; }, setCollapsedSwimlane(boardId, swimlaneId, collapsed) { // ... update user.profile.collapsedSwimlanes[boardId][swimlaneId] }, isCollapsedSwimlane(boardId, swimlaneId) { // ... check user.profile.collapsedSwimlanes }, // 折叠列表per-user getCollapsedLists() { /* ... */ }, setCollapsedList(boardId, listId, collapsed) { /* ... */ }, isCollapsedList(boardId, listId) { /* ... */ }, // 隐藏迷你卡片标签文字per-user getHideMiniCardLabelText(boardId) { /* ... */ }, setHideMiniCardLabelText(boardId, hidden) { /* ... */ },仓库中的实际实现印证了这一设计。models/users.js 的setCollapsedList/setCollapsedSwimlane都在写profile.collapsedLists/profile.collapsedSwimlanes且写入时用!!collapsed强制布尔化对应的服务端方法setListCollapsedState、setSwimlaneCollapsedStateserver/models/users.js先校验参数与登录态再写入当前用户的 profile。Schema 侧profile.collapsedListsmodels/users.js、profile.collapsedSwimlanesmodels/users.js以及profile.hideMiniCardLabelText均为 per-user 的 blackbox 对象这些不在删除范围。3.5 从用户 Schema 删除的字段// REMOVE from schema: profile.listWidths: { ... }, // Now stored in list.width profile.swimlaneHeights: { ... }, // Now stored in swimlane.height四、客户端存储访问层改造4.1 读写路径替换UI 层获取/设置宽度高度的方式从走用户 profile改为直接操作业务文档// OLD废弃从用户 profile 读取 const width Meteor.user().getListWidth(boardId, listId); // NEW从 list 文档读取 const width Lists.findOne(listId)?.width || 272; // OLD废弃通过 Meteor 方法写用户 profile Meteor.call(setListWidth, boardId, listId, 300); // NEW直接更新 list 文档 Lists.update(listId, { $set: { width: 300 } });对应地文档要求删除setListWidth、setSwimlaneHeight这两个更新用户 profile 的 Meteor 方法docs/Security/PerUserDataAudit2025-12-23/IMPLEMENTATION_GUIDE.md 有完整示意。需要提醒的是当前 server/models/users.js 仍存在applySwimlaneHeight、applySwimlaneHeightToStorage、applyListWidthToStorage等旧方法它们内部仍调用user.setSwimlaneHeight/setSwimlaneHeightToStorage/setListWidthToStorage——这些属于文档标注的TODO待重构部分重构时应一并清理避免新旧两条写入路径并存导致数据不一致。4.2 未登录用户的客户端存储架构文档 DATA_PERSISTENCE_ARCHITECTURE.md 明确了未登录用户的 per-user 状态保存位置数据存储介质Key折叠泳道Cookiewekan-collapsed-swimlanes折叠列表Cookiewekan-collapsed-lists卡片详情折叠Cookiewekan-card-collapsed隐藏迷你卡片标签localStoragewekan-hide-minicard-label-{boardId}折叠类数据走 Cookie 而非 localStorage是因为未登录用户看公共看板时服务端渲染也需要读取该状态。五、数据迁移脚本5.1 脚本骨架文档提供了完整可运行的迁移脚本核心逻辑放在Meteor.startup中、用migrations集合防重const MIGRATION_NAME migrate-to-per-board-height-width-storage; Migrations new Mongo.Collection(migrations); Meteor.startup(() { const existingMigration Migrations.findOne({ name: MIGRATION_NAME }); if (!existingMigration) { try { // Migrate swimlane heights from user.profile to swimlane.height Meteor.users.find().forEach(user { const swimlaneHeights user.profile?.swimlaneHeights || {}; Object.keys(swimlaneHeights).forEach(boardId { Object.keys(swimlaneHeights[boardId]).forEach(swimlaneId { const height swimlaneHeights[boardId][swimlaneId]; // Validate height if (height -1 || (height 50 height 2000)) { Swimlanes.update( { _id: swimlaneId, boardId }, { $set: { height } }, { multi: false } ); } }); }); }); // Migrate list widths from user.profile to list.width Meteor.users.find().forEach(user { const listWidths user.profile?.listWidths || {}; Object.keys(listWidths).forEach(boardId { Object.keys(listWidths[boardId]).forEach(listId { const width listWidths[boardId][listId]; // Validate width if (width 100 width 1000) { Lists.update( { _id: listId, boardId }, { $set: { width } }, { multi: false } ); } }); }); }); // Record successful migration Migrations.insert({ name: MIGRATION_NAME, status: completed, createdAt: new Date(), migratedSwimlanes: Swimlanes.find({ height: { $exists: true, $ne: -1 } }).count(), migratedLists: Lists.find({ width: { $exists: true, $ne: 272 } }).count(), }); console.log(✅ Migration to per-board height/width storage completed); } catch (error) { console.error(❌ Migration failed:, error); Migrations.insert({ name: MIGRATION_NAME, status: failed, error: error.message, createdAt: new Date(), }); } } });几个值得注意的实现要点按{ _id, boardId }联合条件更新Swimlanes.update({ _id: swimlaneId, boardId }, ...)防止把 A 看板的值错写进 B 看板同名文档写入前校验高度只迁移-1或50~2000范围内的值宽度只迁移100~1000范围内的值越界数据直接丢弃符合清理损坏数据的迁移策略见 DATA_PERSISTENCE_ARCHITECTURE.md记录迁移结果成功/失败都会写入migrations集合且记录迁移数量便于审计。5.2 与仓库现有迁移模式的对应仓库server/migrations/目录中已有成熟的迁移范式可参考。以 server/migrations/ensureValidSwimlaneIds.js 为例使用MIGRATION_NAME常量第 28 行、用Migrations.findOne检查是否已执行第 32 行、完成后写入{ name, status: completed, migratedAt }记录第 306-309 行、异常时记录失败原因第 330 行。迁移脚本应遵循这一模式避免每次启动重复执行。六、测试清单文档提供了完整的四组测试项可直接作为 PR 验收依据Schema 校验测试泳道height -1允许插入height 100允许插入泳道height 25拒绝 50height 3000拒绝 2000列表width 272当前仓库为 220允许插入width 50拒绝 100width 2000拒绝 1000数据持久化测试调整泳道高度 → 写入 swimlane 文档刷新页面高度保持不同用户加载同一看板 → 看到相同高度调整列表宽度 → 写入 list 文档刷新保持不同用户看到相同宽度Per-User 隔离测试User A 折叠泳道 → User B 仍看到展开状态User A 隐藏标签 → User B 仍看到标签同一用户刷新 → 个人偏好恢复切换账号 → 看不到上一个用户的偏好迁移测试在含旧 per-user 数据的库上运行迁移所有泳道高度迁移到 swimlane 文档、所有列表宽度迁移到 list 文档确认后可安全删除user.profile.swimlaneHeights与user.profile.listWidths这些测试项与 DATA_PERSISTENCE_ARCHITECTURE.md 中的测试清单相互呼应后者还额外覆盖了损坏的 localStorage/profile 数据在启动时被清理的场景。七、回滚方案如果迁移后出现问题按以下顺序回退1. 迁移前先备份 MongoDBmongodump -d wekan -o backup-wekan-before-migration2. 需要时从备份恢复mongorestore -d wekan backup-wekan-before-migration/wekan3. 回退代码恢复旧版的 models/swimlanes.js、models/lists.js、[models/users.js]。回滚的核心是备份先行因为迁移脚本只搬运数据、不清除旧 profile 字段所以备份恢复后不会丢失任何旧数据。八、涉及文件汇总文件变更状态models/swimlanes.js新增height字段✅ 已完成见第 125-140 行models/lists.js新增width字段✅ 已完成见第 267-282 行默认值已按 #6465 调整为 220models/lib/listWidth.js宽度默认值/校验/解析单一来源✅ 已完成models/users.js重构高度/宽度读写方法、删除profile.listWidths/profile.swimlaneHeights⏳ TODO当前仍保留旧实现server/migrations/migrateToPerBoardStorage.js迁移脚本⏳ TODODATA_PERSISTENCE_ARCHITECTURE.md架构文档✅ 已完成九、Per-Board 与 Per-User 数据总览✅ Per-Board 数据所有用户看到相同值泳道高度swimlanes.height-1 或 50~2000列表宽度lists.width100~1000卡片位置card.sort清单位置checklist.sort清单项位置checklistItem.sort所有标题、颜色、描述 Per-User 数据仅本人可见折叠状态泳道、列表、卡片迷你卡片标签文字显隐存储于user.profile或 Cookie/localStorage十、总结与后续工作本次重构确立了清晰的职责边界描述看板长什么样的数据进业务文档共享给所有人描述用户怎么看的数据留在 profile/Cookie 私有给个人。仓库现状表明 Schema 与架构层已完成泳道height、列表width字段已就位宽度解析逻辑已收敛到 models/lib/listWidth.js而用户方法的去 profile 化重构与数据迁移脚本仍是 TODO——下一步是依据本文第 3、5 节完成models/users.js的改造、按第 6 节清单测试并参照 server/migrations/ensureValidSwimlaneIds.js 的既有范式落地迁移脚本最后按第 7 节做好备份再上线。【免费下载链接】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），仅供参考