Wekan 看板部署到 Sandstorm 沙箱平台安装升级、MongoDB 到 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 官方维护的 Sandstorm 平台部署文档为骨架系统讲解如何在 Sandstorm 安全沙箱中安装、备份、升级 Wekan 看板应用重点剖析新版包将内嵌 MongoDB 3.0 迁移到 FerretDB v1SQLite的一次性迁移机制、迁移后的磁盘释放操作以及 CloudFlare Caddy 反代配置与 grain 数据救援方案。读完本文你将掌握 Sandstorm Wekan 从安装、日常维护到故障救援的完整闭环并能对照仓库源码理解迁移与磁盘管理在底层的实际执行逻辑。1. Sandstorm 平台与 Wekan 的定位Sandstorm 是一种面向单用户的容器式应用运行平台每个应用实例grain运行在独立的沙箱中用户通过平台统一管理登录、权限与数据。官方文档对 Sandstorm 的定位是适用于 Ubuntu 64bit 与 Debian 64bit 自建服务器安装后提供自动更新且更新在发布前经过测试通过其自带功能即可获得https://yourservername.sandcats.io域名下的免费 SSL平台本身经过安全审计官方文档建议将其用于公网或内网的安全关键场景平台与沙箱隔离机制完全开源。Sandstorm 曾经提供名为 Oasis 的按月付费 grain 托管服务但该托管服务已停止官方文档明确提醒如果你在 Oasis 上还有 grain应迁移到自托管。这与自建self-hosted相关的 sandcats.io、App Market、更新推送等能力不受影响。Wekan 以.spk包的形式发布到 Sandstorm App Market安装后每个用户每次打开即创建一个独立的 Wekan 看板 grain。与其他部署形态Docker、Snap、VirtualBox相比Sandstorm 版有明确的能力差异见下文功能支持矩阵例如不支持向外发送邮件、不支持 REST API因此在选型前需要先确认功能边界。2. 获取与安装 Wekan 的 Sandstorm 包2.1 官方正式版Wekan 的官方包发布在 Sandstorm App Market官方渠道安装时只应使用官方版本——文档特别警告实验Experimental版本是损坏的Only use official. Experimental versions are broken.不要在生产环境使用实验版。2.2 最新测试版通过 Test App Loader 安装如果你想提前体验尚未上架的最新构建文档给出的流程是先备份现有 grain见第 3 节。打开 Sandstorm Test App Loader 页面。从项目 GitHub releases 页面复制最新的wekan.spk文件 URL。在 Test App Loader 页面填写你的 Sandstorm 实例 URL。点击Install完成安装。之后该版本会陆续进入 App Market 的 Experimental 与 Official 渠道。2.3 CloudFlare 下的 100 MB 上传限制如果你的 Sandstorm 站点前面挂了 CloudFlare需要注意CloudFlare 对文件上传存在100 MB 大小限制会阻止你直接把wekan.spk作为文件上传到 Sandstorm。解决方式是改用上文提到的Sandstorm Test App Loader从 URL 直接安装从而绕过文件上传通道。2.4 演示与试玩项目文档为 Wekan 提供了 Sandstorm 上的在线演示demo入口你可以直接体验 grain 形态下的看板操作。下图展示了 Wekan 看板在 Sandstorm 沙箱界面中的实际运行效果3. 备份升级前的必要前提升级 Sandstorm Wekan 前文档反复强调必须先备份。官方给出的备份步骤是首先备份整个 Sandstorm 平台使用 Sandstorm 官方管理文档中的备份方法。然后在 Sandstorm 顶部菜单栏的向下箭头按钮中把所有 grain 逐个下载为.zip文件以防万一。保持备份习惯是长期建议持续下载并保留你的 Wekan grains。grain.zip文件本身就是一份可离线持有的数据副本配合第 7 节的救援流程可以在最坏情况下恢复数据。4. 升级从 MongoDB 3.0 到 FerretDB v1SQLite的迁移4.1 为什么需要迁移新版 Sandstorm Wekan 不再内嵌 MongoDB 服务器而是改用FerretDB v1SQLite 后端。FerretDB 是一个 MongoDB 协议的替代实现是 MongoDB 7 Server 的即插即用替代品drop-in replacement实现了 MongoDB 7 的服务器线协议wire protocol将 MongoDB 的 JavaScript 查询转换为 SQLite 的 SQL 查询数据保存在 SQLite 数据库中Wekan 维护的 FerretDB fork 额外补充了若干 MongoDB 特性并由维护者 xet7 持续维护。这一架构使稳定运行态下完全不再需要 MongoDB 服务器进程WekanNode.js 24直接与 FerretDB 通信。老旧的 mongod 3.0 只在迁移那一刻作为只读数据源被临时拉起。4.2 首次打开旧 grain 时的自动迁移如果你存在旧版 Wekan grain 的数据打开旧 grain 时会自动迁移附件从 MongoDBGridFS迁移到文件系统files/attachments目录文本数据从 MongoDB 迁移到 SQLitefiles/db/wekan.sqlite迁移与启动期间grain 会显示一个**please wait等待页**页面自动刷新一旦就绪便直接打开 Wekan。此前版本在迁移窗口期会因应用端口无人监听而报无法嵌入其他页面打开此页面This page can not be displayed embedded in another page的错误用户需要关闭 grain 再重新打开。现在的实现通过在应用端口上运行一个极小的桥接服务器sandstorm-src/migration-bridge.js由 grain 启动器在整个迁移与交接期间运行让 grain 始终保持在沙箱框架内该报错不再出现。4.3 迁移的内部结构源码级仓库中的sandstorm-src/start.js是 grain 启动器launcher的规范实现被.spk构建过程复制为meteor-spk.deps/start.js。它按 grain 已有数据的不同形态走不同路径grain 已有数据处理方式无数据全新安装直接以空 FerretDB 运行 WekanniscuMongoDB 2.x 时代先迁移 niscu → MongoDB 3.0保留的旧路径再迁移 MongoDB 3.0 → FerretDBMongoDB 3.0WiredTiger位于/var/wiredTigerDb迁移 MongoDB 3.0 → FerretDB已是 FerretDB检测到标记文件跳过迁移直接运行迁移是幂等的完成迁移后写入标记文件/var/.migration-to-ferretdb-done之后不再重复迁移旧数据永远不会被自动删除由管理员在管理面板中手动释放见第 5 节。关键端口grain 内部回环端口用途4000应用 HTTP 端口位于sandstorm-http-bridge之后即APP_PORT4001FerretDB v1 稳定运行端口MONGO_URLmongodb://127.0.0.1:4001/wekan4003迁移期间临时 mongod 3.0只读数据源4004迁移 niscu 2.x 时的 niscud 端口迁移分两个阶段Stage 1niscu → MongoDB 3.0对极老 grain先以 niscudMongoDB 2.x fork读出旧库用旧的 Node mongodb 驱动逐集合复制到 mongod 3.0WiredTiger生成/var/wiredTigerDb。注意此处 mongod 3.0 被显式指定--wiredTigerCacheSizeGB 1——因为 grain 沙箱内内存探测返回 0mongod 3.0 默认会算出cache_size0G而让 WiredTiger 直接断言失败崩溃Fatal Assertion 28561。Stage 2MongoDB 3.0 → FerretDB用旧版 CLImongoexport因为现代驱动无法与 3.x 服务器对话从 mongod 3.0 读出数据通过现代 Node 驱动写入 FerretDB 目标库CollectionFS/Meteor-Files 的 GridFS 附件与头像被抽取落盘到文件系统。迁移成功才写标记文件失败则保留旧数据下次启动重试。4.4 please wait 等待页的桥接实现sandstorm-src/migration-bridge.js是一个零依赖仅node:http的极简 HTTP 服务回答任何 URL 都返回一个带HTTP 503 Retry-After: 5meta http-equivrefresh content5的等待页页面文案默认为 WeKan is getting your data ready.可通过BRIDGE_MESSAGE环境变量覆盖。它作为子进程运行而非进程内服务器是因为start.js在迁移期间阻塞于spawnSync无法同时服务进程内 socket杀掉子进程即可确定性释放APP_PORT随后迁移进度面板或 Meteor 才能绑定该端口。启动器从进程一开始就拉起桥接WeKan is starting…迁移中显示正在迁移数据交接阶段显示Finishing up — starting WeKan…确保 grain 框架内始终有内容可显示。4.5 包体与环境变更对应sandstorm-pkgdef.capnp中的变更要点WRITABLE_PATH从/var/wekan-uploads改为/var/files附件、头像与 FerretDB SQLitedb/均位于其下不再在environ中设置MONGO_URL改由start.js在运行时指向 FerretDB 端口启动命令为argv [/sandstorm-http-bridge, 4000, --, ./start-memory.sh]其中start-memory.sh会根据 cgroup 内存上限自动计算 Node 堆大小--max-old-space-size默认取物理内存的 3/5上限 4096 MB再exec node start.jsSANDSTORM1与METEOR_SETTINGS{public:{sandstorm:true}}已就位前者驱动客户端基于 header 的自动登录后者驱动管理面板中isSandstorm为真的新功能DDP_TRANSPORTsockjs被显式钉住使.spk可以剪掉 121 MB 的 uWS 传输模块releases/bundle-trim.mjs负责裁剪这是包体满足 Sandstorm 1 GiB 上限的关键一环并由tests/bundleTrim.test.cjs约束二者不可漂移。完整的迁移设计细节目标架构、沙箱 seccomp 兼容性验证、meteor-spk.deps载荷清单、构建/CI 步骤与风险测试清单参见 Meteor3/Migration.md。5. 迁移后释放磁盘空间迁移完成后旧的 MongoDB 3.0 原始数据库文件仍躺在/var/wiredTigerDb下占用 grain 磁盘空间而数据已完整存在于 FerretDB 与文件系统中因此可以安全删除。操作路径看板右上角点击你的 Wekan 用户名注意是 Wekan 看板内不是 Sandstorm 黑色背景→Member Settings / 成员设置 → Admin Panel / 管理面板 → Attachments / 附件 → Sandstorm→Delete raw MongoDB database files / 删除原始 MongoDB 数据库文件。该功能由server/methods/sandstormMigration.js提供两个管理员方法sandstormMigrationStatus()返回迁移是否完成标记文件是否存在、迁移是否成功migration-status.json中success true、原始 MongoDB 文件与 FerretDB SQLite、附件、头像各占用多少字节sandstormDeleteRawMongo()仅在迁移确认成功标记文件存在且状态文件success:true且原始目录存在时才允许删除返回释放的字节数任何前置条件不满足都会抛出Meteor.Error如migration-not-done、migration-not-successful。删除是不可逆操作但迁移后数据已在 FerretDB 文件系统中删除仅回收冗余的 MongoDB 3.0 副本。客户端对应的 Sandstorm 标签页实现位于 client/components/settings/attachments.js渲染isSandstorm时为真的管理视图。6. 功能支持矩阵哪些可用、哪些不可用Sandstorm Wekan 与其他部署形态的功能差异在文档中非常明确可用WorksGoogle / GitHub / LDAP / SAML / Passwordless 邮件登录从 Wekan JSON 导入通过 sandcats.io 域名获得免费 SSL从 Sandstorm grain.zip文件中救援 MongoDB 数据到 Standalone Wekan。下图为 Sandstorm 管理面板的登录提供方配置页对应上述多种登录方式的启用入口不可用Does not work从 Trello 导入时不导入附件——因为 Wekan 沙箱对外部 HTTP 访问的兼容实现尚未完成卡片复制/移动到其他看板Copying/Moving card to another boardREST API出站 Webhook相关背景见 Outgoing-Webhook-to-Discord.md从 Wekan 发送邮件。以上限制有对应的 Sandstorm 目标标签Targets:Sandstorm开源 issue 列表新问题可以在 Wekan 仓库提交 bug report 或 feature request。7. 从 Sandstorm grain .zip 中救援数据文档提供了一条从 grain.zip文件把数据迁移到 Standalone Wekan 的完整救援路径适用于例如Board not found等异常场景详见 Export-from-Wekan-Sandstorm-grain-.zip-file.md要点如下安装zip unzip p7zip-full wget等工具并按需准备修复版 Meteor 工具链与 MongoDB 3.2 环境用 Sandstorm 顶部向下箭头按钮把 Wekan grain 下载为.zip并解压数据库文件位于解压目录的data/wiredTigerDb/若数据库无法打开用 mongod--dbpath grain/data/wiredTigerDb --repair修复将修复后的目录替换到本地 MongoDB 数据目录并启动服务用mongodump --db meteor导出 dump或用mongoexport逐集合导出 JSON 文本文件脚本示例见该文档附件位于cfs_gridfs.attachments.files集合可用 NoSQLBooster 等 GUI 逐一下载到本地。注意 Sandstorm grain 的数据库名是meteor而 StandaloneDocker/Snap的数据库名是wekan恢复时需要处理数据库名差异如mongorestore到不同数据库名。相关内容也可参考仓库的 Backup 文档。8. 把看板数据导出为 CSVPython 方案除数据库级救援外文档还提供了用 Python 把 Sandstorm Wekan 卡片导出为 CSV 的脚本化方案步骤详见 Wekan-Sandstorm-cards-to-CSV-using-Python.md适合需要把看板数据进一步做报表或分析的场景。9. Trello 导入附件的绕行方案Sandstorm 版无法直接导入 Trello 附件原因见第 6 节。文档给出的标准绕行流程先安装 Standalone 版 Wekan例如 Docker / Snap / VirtualBox可装在本地电脑在 Standalone 版中从 Trello 导入看板将看板导出为 Wekan 看板 JSON导出的 JSON 中包含 base64 编码的附件再把这个 JSON 导入 Sandstorm 版 Wekan。10. CloudFlare DNS 与 Caddy 反向代理配置文档记录了在 CloudFlare Caddy 环境下让 Sandstorm 正常工作的实测配置。前提要点Sandstorm 应配置为完整域名full domain配合 CloudFlare SSL/TLS 与 Caddy不支持子域名、不支持子路径sub-url也不支持 Lets Encrypt据文档说明其不支持通配符 SSL/TLS实测可用组合CloudFlare DNS 开启TLS Strict检查DNS 记录点亮橙色云朵图标启用 TLS 代理配合Origin 证书证书位于/etc/caddy/certs/example.com.pem包含私钥与证书。DNS 记录* A example.com ip-address A example.com ip-addressCaddyfile代理到运行 Debian Sandstorm 的 KVM 虚拟机# Full domain where Sandstorm login is. Not subdomain. Not sub-url. *.example.com example.com { tls { load /etc/caddy/certs alpn http/1.1 } # If KVM VM, its IP address: #reverse_proxy 123.123.123.123:80 # Localhost port 81, when not in KVM VM reverse_proxy 127.0.0.1:81 } blog.somecompany.com { tls { load /etc/caddy/certs alpn http/1.1 } # Blog hosted at Sandstorm WordPress reverse_proxy 127.0.0.1:81 } othercompany.com { tls { load /etc/caddy/certs alpn http/1.1 } # Website hosted at Sandstorm Hacker CMS reverse_proxy 127.0.0.1:81 }若 Sandstorm 运行在 KVM 虚拟机内还可参考 Snap 多实例在同一 LXC 上的说明Many-Snaps-on-LXC.md。Sandstorm 主配置文件位于/opt/sandstorm/sandstorm.conf其中配置登录域名、HTTP 端口等。文档给出的实测片段SERVER_USERsandstorm PORT81 MONGO_PORT6081 BIND_IP127.0.0.1 BASE_URLhttps://example.com WILDCARD_HOST*.example.com UPDATE_CHANNELdev ALLOW_DEV_ACCOUNTSfalse SMTP_LISTEN_PORT25 #SANDCATS_BASE_DOMAINsandcats.io #HTTPS_PORT443补充说明相关 Web 服务器配置背景可参考 Caddy Webserver Config文档提到需要等待 Origin 证书生效该方案只在 CloudFlare 下实测通过在 Namecheap 的 FreeDNS 下无效若使用动态 IP如电缆调制解调器不支持 CloudFlare DDNS需要编写脚本通过 CloudFlare API 在 IP 变化时修正 DNS 记录。11. 系统级注意事项Debian 与 UbuntuDebian amd64正常安装 Sandstorm 即可。Ubuntu 24.04 amd64启动时可能出现大量报错与Permission denied; name /proc/self/setgroups。以 root 执行以下命令可解决echo kernel.apparmor_restrict_unprivileged_userns 0 /etc/sysctl.d/99-userns.conf sysctl --system然后重启 Sandstorm 服务即可恢复正常。该问题根因与 Ubuntu 24.04 收紧非特权用户命名空间unprivileged user namespaces有关。12. 日常使用要点All Boards 页面与封面图All Boards 页面Wekan 启动后进入 All Boards 页面的Favorites收藏所有看板最初位于Remaining剩余直到你点击星标将其置入 Favorites还可以把看板从 Remaining 移动到个人 Workspaces 或 Sub-Workspaces 组织管理。封面图Cover image可在 右侧边栏Right Sidebar→ Board Settings → Card 中启用该设置表格左右两列并排展示卡片与迷你卡片的设置项Cover Image位于列表靠近底部的位置。13. 其他资源与反馈渠道构建 Wekan 的 Sandstorm 包.spk的维护者指引见 Building-Wekan-for-Sandstorm.md开发/调试 Sandstorm 版 Wekan 的说明见 Developing-Wekan-for-Sandstorm.mdWekan 与 Sandstorm 的平台定位对比见 Wekan-vs-Sandstorm.md已知问题与规划见 TODO.mdBug 报告与功能请求Wekan 相关提交到 Wekan 仓库 issues带Targets:Sandstorm标签跟踪Sandstorm 平台本身的问题提交到 Sandstorm 仓库 issues。14. 总结与建议综合文档与源码Sandstorm 版 Wekan 的核心运维要点可归纳为备份优先升级前先备份平台并下载全部 grain 为.zip只装官方版实验版损坏仅用于尝鲜理解迁移是一次性的首次打开旧 grain 会自动完成 MongoDB → FerretDB 附件落盘迁移窗口期由migration-bridge.js保持等待页可见迁移幂等且不自动删旧数据迁移后记得释放空间通过 Admin Panel / Attachments / Sandstorm 的安全删除按钮回收/var/wiredTigerDb注意功能边界Sandstorm 版不支持 REST API、出站 Webhook、邮件发送与 Trello 附件导入选型前务必对照支持矩阵网络层完整域名 CloudFlare Caddy 是文档实测可行的反代组合注意 100 MB 上传限制与 Ubuntu 24.04 的 userns 内核参数。遵循以上路径你可以在 Sandstorm 上稳定运行、升级并长期维护 Wekan 看板同时在极端情况下具备完整的备份与救援能力。【免费下载链接】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），仅供参考
Wekan 看板部署到 Sandstorm 沙箱平台：安装升级、MongoDB 到 FerretDB 迁移与数据救援实战指南
Wekan 看板部署到 Sandstorm 沙箱平台安装升级、MongoDB 到 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 官方维护的 Sandstorm 平台部署文档为骨架系统讲解如何在 Sandstorm 安全沙箱中安装、备份、升级 Wekan 看板应用重点剖析新版包将内嵌 MongoDB 3.0 迁移到 FerretDB v1SQLite的一次性迁移机制、迁移后的磁盘释放操作以及 CloudFlare Caddy 反代配置与 grain 数据救援方案。读完本文你将掌握 Sandstorm Wekan 从安装、日常维护到故障救援的完整闭环并能对照仓库源码理解迁移与磁盘管理在底层的实际执行逻辑。1. Sandstorm 平台与 Wekan 的定位Sandstorm 是一种面向单用户的容器式应用运行平台每个应用实例grain运行在独立的沙箱中用户通过平台统一管理登录、权限与数据。官方文档对 Sandstorm 的定位是适用于 Ubuntu 64bit 与 Debian 64bit 自建服务器安装后提供自动更新且更新在发布前经过测试通过其自带功能即可获得https://yourservername.sandcats.io域名下的免费 SSL平台本身经过安全审计官方文档建议将其用于公网或内网的安全关键场景平台与沙箱隔离机制完全开源。Sandstorm 曾经提供名为 Oasis 的按月付费 grain 托管服务但该托管服务已停止官方文档明确提醒如果你在 Oasis 上还有 grain应迁移到自托管。这与自建self-hosted相关的 sandcats.io、App Market、更新推送等能力不受影响。Wekan 以.spk包的形式发布到 Sandstorm App Market安装后每个用户每次打开即创建一个独立的 Wekan 看板 grain。与其他部署形态Docker、Snap、VirtualBox相比Sandstorm 版有明确的能力差异见下文功能支持矩阵例如不支持向外发送邮件、不支持 REST API因此在选型前需要先确认功能边界。2. 获取与安装 Wekan 的 Sandstorm 包2.1 官方正式版Wekan 的官方包发布在 Sandstorm App Market官方渠道安装时只应使用官方版本——文档特别警告实验Experimental版本是损坏的Only use official. Experimental versions are broken.不要在生产环境使用实验版。2.2 最新测试版通过 Test App Loader 安装如果你想提前体验尚未上架的最新构建文档给出的流程是先备份现有 grain见第 3 节。打开 Sandstorm Test App Loader 页面。从项目 GitHub releases 页面复制最新的wekan.spk文件 URL。在 Test App Loader 页面填写你的 Sandstorm 实例 URL。点击Install完成安装。之后该版本会陆续进入 App Market 的 Experimental 与 Official 渠道。2.3 CloudFlare 下的 100 MB 上传限制如果你的 Sandstorm 站点前面挂了 CloudFlare需要注意CloudFlare 对文件上传存在100 MB 大小限制会阻止你直接把wekan.spk作为文件上传到 Sandstorm。解决方式是改用上文提到的Sandstorm Test App Loader从 URL 直接安装从而绕过文件上传通道。2.4 演示与试玩项目文档为 Wekan 提供了 Sandstorm 上的在线演示demo入口你可以直接体验 grain 形态下的看板操作。下图展示了 Wekan 看板在 Sandstorm 沙箱界面中的实际运行效果3. 备份升级前的必要前提升级 Sandstorm Wekan 前文档反复强调必须先备份。官方给出的备份步骤是首先备份整个 Sandstorm 平台使用 Sandstorm 官方管理文档中的备份方法。然后在 Sandstorm 顶部菜单栏的向下箭头按钮中把所有 grain 逐个下载为.zip文件以防万一。保持备份习惯是长期建议持续下载并保留你的 Wekan grains。grain.zip文件本身就是一份可离线持有的数据副本配合第 7 节的救援流程可以在最坏情况下恢复数据。4. 升级从 MongoDB 3.0 到 FerretDB v1SQLite的迁移4.1 为什么需要迁移新版 Sandstorm Wekan 不再内嵌 MongoDB 服务器而是改用FerretDB v1SQLite 后端。FerretDB 是一个 MongoDB 协议的替代实现是 MongoDB 7 Server 的即插即用替代品drop-in replacement实现了 MongoDB 7 的服务器线协议wire protocol将 MongoDB 的 JavaScript 查询转换为 SQLite 的 SQL 查询数据保存在 SQLite 数据库中Wekan 维护的 FerretDB fork 额外补充了若干 MongoDB 特性并由维护者 xet7 持续维护。这一架构使稳定运行态下完全不再需要 MongoDB 服务器进程WekanNode.js 24直接与 FerretDB 通信。老旧的 mongod 3.0 只在迁移那一刻作为只读数据源被临时拉起。4.2 首次打开旧 grain 时的自动迁移如果你存在旧版 Wekan grain 的数据打开旧 grain 时会自动迁移附件从 MongoDBGridFS迁移到文件系统files/attachments目录文本数据从 MongoDB 迁移到 SQLitefiles/db/wekan.sqlite迁移与启动期间grain 会显示一个**please wait等待页**页面自动刷新一旦就绪便直接打开 Wekan。此前版本在迁移窗口期会因应用端口无人监听而报无法嵌入其他页面打开此页面This page can not be displayed embedded in another page的错误用户需要关闭 grain 再重新打开。现在的实现通过在应用端口上运行一个极小的桥接服务器sandstorm-src/migration-bridge.js由 grain 启动器在整个迁移与交接期间运行让 grain 始终保持在沙箱框架内该报错不再出现。4.3 迁移的内部结构源码级仓库中的sandstorm-src/start.js是 grain 启动器launcher的规范实现被.spk构建过程复制为meteor-spk.deps/start.js。它按 grain 已有数据的不同形态走不同路径grain 已有数据处理方式无数据全新安装直接以空 FerretDB 运行 WekanniscuMongoDB 2.x 时代先迁移 niscu → MongoDB 3.0保留的旧路径再迁移 MongoDB 3.0 → FerretDBMongoDB 3.0WiredTiger位于/var/wiredTigerDb迁移 MongoDB 3.0 → FerretDB已是 FerretDB检测到标记文件跳过迁移直接运行迁移是幂等的完成迁移后写入标记文件/var/.migration-to-ferretdb-done之后不再重复迁移旧数据永远不会被自动删除由管理员在管理面板中手动释放见第 5 节。关键端口grain 内部回环端口用途4000应用 HTTP 端口位于sandstorm-http-bridge之后即APP_PORT4001FerretDB v1 稳定运行端口MONGO_URLmongodb://127.0.0.1:4001/wekan4003迁移期间临时 mongod 3.0只读数据源4004迁移 niscu 2.x 时的 niscud 端口迁移分两个阶段Stage 1niscu → MongoDB 3.0对极老 grain先以 niscudMongoDB 2.x fork读出旧库用旧的 Node mongodb 驱动逐集合复制到 mongod 3.0WiredTiger生成/var/wiredTigerDb。注意此处 mongod 3.0 被显式指定--wiredTigerCacheSizeGB 1——因为 grain 沙箱内内存探测返回 0mongod 3.0 默认会算出cache_size0G而让 WiredTiger 直接断言失败崩溃Fatal Assertion 28561。Stage 2MongoDB 3.0 → FerretDB用旧版 CLImongoexport因为现代驱动无法与 3.x 服务器对话从 mongod 3.0 读出数据通过现代 Node 驱动写入 FerretDB 目标库CollectionFS/Meteor-Files 的 GridFS 附件与头像被抽取落盘到文件系统。迁移成功才写标记文件失败则保留旧数据下次启动重试。4.4 please wait 等待页的桥接实现sandstorm-src/migration-bridge.js是一个零依赖仅node:http的极简 HTTP 服务回答任何 URL 都返回一个带HTTP 503 Retry-After: 5meta http-equivrefresh content5的等待页页面文案默认为 WeKan is getting your data ready.可通过BRIDGE_MESSAGE环境变量覆盖。它作为子进程运行而非进程内服务器是因为start.js在迁移期间阻塞于spawnSync无法同时服务进程内 socket杀掉子进程即可确定性释放APP_PORT随后迁移进度面板或 Meteor 才能绑定该端口。启动器从进程一开始就拉起桥接WeKan is starting…迁移中显示正在迁移数据交接阶段显示Finishing up — starting WeKan…确保 grain 框架内始终有内容可显示。4.5 包体与环境变更对应sandstorm-pkgdef.capnp中的变更要点WRITABLE_PATH从/var/wekan-uploads改为/var/files附件、头像与 FerretDB SQLitedb/均位于其下不再在environ中设置MONGO_URL改由start.js在运行时指向 FerretDB 端口启动命令为argv [/sandstorm-http-bridge, 4000, --, ./start-memory.sh]其中start-memory.sh会根据 cgroup 内存上限自动计算 Node 堆大小--max-old-space-size默认取物理内存的 3/5上限 4096 MB再exec node start.jsSANDSTORM1与METEOR_SETTINGS{public:{sandstorm:true}}已就位前者驱动客户端基于 header 的自动登录后者驱动管理面板中isSandstorm为真的新功能DDP_TRANSPORTsockjs被显式钉住使.spk可以剪掉 121 MB 的 uWS 传输模块releases/bundle-trim.mjs负责裁剪这是包体满足 Sandstorm 1 GiB 上限的关键一环并由tests/bundleTrim.test.cjs约束二者不可漂移。完整的迁移设计细节目标架构、沙箱 seccomp 兼容性验证、meteor-spk.deps载荷清单、构建/CI 步骤与风险测试清单参见 Meteor3/Migration.md。5. 迁移后释放磁盘空间迁移完成后旧的 MongoDB 3.0 原始数据库文件仍躺在/var/wiredTigerDb下占用 grain 磁盘空间而数据已完整存在于 FerretDB 与文件系统中因此可以安全删除。操作路径看板右上角点击你的 Wekan 用户名注意是 Wekan 看板内不是 Sandstorm 黑色背景→Member Settings / 成员设置 → Admin Panel / 管理面板 → Attachments / 附件 → Sandstorm→Delete raw MongoDB database files / 删除原始 MongoDB 数据库文件。该功能由server/methods/sandstormMigration.js提供两个管理员方法sandstormMigrationStatus()返回迁移是否完成标记文件是否存在、迁移是否成功migration-status.json中success true、原始 MongoDB 文件与 FerretDB SQLite、附件、头像各占用多少字节sandstormDeleteRawMongo()仅在迁移确认成功标记文件存在且状态文件success:true且原始目录存在时才允许删除返回释放的字节数任何前置条件不满足都会抛出Meteor.Error如migration-not-done、migration-not-successful。删除是不可逆操作但迁移后数据已在 FerretDB 文件系统中删除仅回收冗余的 MongoDB 3.0 副本。客户端对应的 Sandstorm 标签页实现位于 client/components/settings/attachments.js渲染isSandstorm时为真的管理视图。6. 功能支持矩阵哪些可用、哪些不可用Sandstorm Wekan 与其他部署形态的功能差异在文档中非常明确可用WorksGoogle / GitHub / LDAP / SAML / Passwordless 邮件登录从 Wekan JSON 导入通过 sandcats.io 域名获得免费 SSL从 Sandstorm grain.zip文件中救援 MongoDB 数据到 Standalone Wekan。下图为 Sandstorm 管理面板的登录提供方配置页对应上述多种登录方式的启用入口不可用Does not work从 Trello 导入时不导入附件——因为 Wekan 沙箱对外部 HTTP 访问的兼容实现尚未完成卡片复制/移动到其他看板Copying/Moving card to another boardREST API出站 Webhook相关背景见 Outgoing-Webhook-to-Discord.md从 Wekan 发送邮件。以上限制有对应的 Sandstorm 目标标签Targets:Sandstorm开源 issue 列表新问题可以在 Wekan 仓库提交 bug report 或 feature request。7. 从 Sandstorm grain .zip 中救援数据文档提供了一条从 grain.zip文件把数据迁移到 Standalone Wekan 的完整救援路径适用于例如Board not found等异常场景详见 Export-from-Wekan-Sandstorm-grain-.zip-file.md要点如下安装zip unzip p7zip-full wget等工具并按需准备修复版 Meteor 工具链与 MongoDB 3.2 环境用 Sandstorm 顶部向下箭头按钮把 Wekan grain 下载为.zip并解压数据库文件位于解压目录的data/wiredTigerDb/若数据库无法打开用 mongod--dbpath grain/data/wiredTigerDb --repair修复将修复后的目录替换到本地 MongoDB 数据目录并启动服务用mongodump --db meteor导出 dump或用mongoexport逐集合导出 JSON 文本文件脚本示例见该文档附件位于cfs_gridfs.attachments.files集合可用 NoSQLBooster 等 GUI 逐一下载到本地。注意 Sandstorm grain 的数据库名是meteor而 StandaloneDocker/Snap的数据库名是wekan恢复时需要处理数据库名差异如mongorestore到不同数据库名。相关内容也可参考仓库的 Backup 文档。8. 把看板数据导出为 CSVPython 方案除数据库级救援外文档还提供了用 Python 把 Sandstorm Wekan 卡片导出为 CSV 的脚本化方案步骤详见 Wekan-Sandstorm-cards-to-CSV-using-Python.md适合需要把看板数据进一步做报表或分析的场景。9. Trello 导入附件的绕行方案Sandstorm 版无法直接导入 Trello 附件原因见第 6 节。文档给出的标准绕行流程先安装 Standalone 版 Wekan例如 Docker / Snap / VirtualBox可装在本地电脑在 Standalone 版中从 Trello 导入看板将看板导出为 Wekan 看板 JSON导出的 JSON 中包含 base64 编码的附件再把这个 JSON 导入 Sandstorm 版 Wekan。10. CloudFlare DNS 与 Caddy 反向代理配置文档记录了在 CloudFlare Caddy 环境下让 Sandstorm 正常工作的实测配置。前提要点Sandstorm 应配置为完整域名full domain配合 CloudFlare SSL/TLS 与 Caddy不支持子域名、不支持子路径sub-url也不支持 Lets Encrypt据文档说明其不支持通配符 SSL/TLS实测可用组合CloudFlare DNS 开启TLS Strict检查DNS 记录点亮橙色云朵图标启用 TLS 代理配合Origin 证书证书位于/etc/caddy/certs/example.com.pem包含私钥与证书。DNS 记录* A example.com ip-address A example.com ip-addressCaddyfile代理到运行 Debian Sandstorm 的 KVM 虚拟机# Full domain where Sandstorm login is. Not subdomain. Not sub-url. *.example.com example.com { tls { load /etc/caddy/certs alpn http/1.1 } # If KVM VM, its IP address: #reverse_proxy 123.123.123.123:80 # Localhost port 81, when not in KVM VM reverse_proxy 127.0.0.1:81 } blog.somecompany.com { tls { load /etc/caddy/certs alpn http/1.1 } # Blog hosted at Sandstorm WordPress reverse_proxy 127.0.0.1:81 } othercompany.com { tls { load /etc/caddy/certs alpn http/1.1 } # Website hosted at Sandstorm Hacker CMS reverse_proxy 127.0.0.1:81 }若 Sandstorm 运行在 KVM 虚拟机内还可参考 Snap 多实例在同一 LXC 上的说明Many-Snaps-on-LXC.md。Sandstorm 主配置文件位于/opt/sandstorm/sandstorm.conf其中配置登录域名、HTTP 端口等。文档给出的实测片段SERVER_USERsandstorm PORT81 MONGO_PORT6081 BIND_IP127.0.0.1 BASE_URLhttps://example.com WILDCARD_HOST*.example.com UPDATE_CHANNELdev ALLOW_DEV_ACCOUNTSfalse SMTP_LISTEN_PORT25 #SANDCATS_BASE_DOMAINsandcats.io #HTTPS_PORT443补充说明相关 Web 服务器配置背景可参考 Caddy Webserver Config文档提到需要等待 Origin 证书生效该方案只在 CloudFlare 下实测通过在 Namecheap 的 FreeDNS 下无效若使用动态 IP如电缆调制解调器不支持 CloudFlare DDNS需要编写脚本通过 CloudFlare API 在 IP 变化时修正 DNS 记录。11. 系统级注意事项Debian 与 UbuntuDebian amd64正常安装 Sandstorm 即可。Ubuntu 24.04 amd64启动时可能出现大量报错与Permission denied; name /proc/self/setgroups。以 root 执行以下命令可解决echo kernel.apparmor_restrict_unprivileged_userns 0 /etc/sysctl.d/99-userns.conf sysctl --system然后重启 Sandstorm 服务即可恢复正常。该问题根因与 Ubuntu 24.04 收紧非特权用户命名空间unprivileged user namespaces有关。12. 日常使用要点All Boards 页面与封面图All Boards 页面Wekan 启动后进入 All Boards 页面的Favorites收藏所有看板最初位于Remaining剩余直到你点击星标将其置入 Favorites还可以把看板从 Remaining 移动到个人 Workspaces 或 Sub-Workspaces 组织管理。封面图Cover image可在 右侧边栏Right Sidebar→ Board Settings → Card 中启用该设置表格左右两列并排展示卡片与迷你卡片的设置项Cover Image位于列表靠近底部的位置。13. 其他资源与反馈渠道构建 Wekan 的 Sandstorm 包.spk的维护者指引见 Building-Wekan-for-Sandstorm.md开发/调试 Sandstorm 版 Wekan 的说明见 Developing-Wekan-for-Sandstorm.mdWekan 与 Sandstorm 的平台定位对比见 Wekan-vs-Sandstorm.md已知问题与规划见 TODO.mdBug 报告与功能请求Wekan 相关提交到 Wekan 仓库 issues带Targets:Sandstorm标签跟踪Sandstorm 平台本身的问题提交到 Sandstorm 仓库 issues。14. 总结与建议综合文档与源码Sandstorm 版 Wekan 的核心运维要点可归纳为备份优先升级前先备份平台并下载全部 grain 为.zip只装官方版实验版损坏仅用于尝鲜理解迁移是一次性的首次打开旧 grain 会自动完成 MongoDB → FerretDB 附件落盘迁移窗口期由migration-bridge.js保持等待页可见迁移幂等且不自动删旧数据迁移后记得释放空间通过 Admin Panel / Attachments / Sandstorm 的安全删除按钮回收/var/wiredTigerDb注意功能边界Sandstorm 版不支持 REST API、出站 Webhook、邮件发送与 Trello 附件导入选型前务必对照支持矩阵网络层完整域名 CloudFlare Caddy 是文档实测可行的反代组合注意 100 MB 上传限制与 Ubuntu 24.04 的 userns 内核参数。遵循以上路径你可以在 Sandstorm 上稳定运行、升级并长期维护 Wekan 看板同时在极端情况下具备完整的备份与救援能力。【免费下载链接】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），仅供参考
