WeKan Snap 故障排查指南：服务状态检查、数据目录布局与 MongoDB 共享接口用法

WeKan Snap 故障排查指南服务状态检查、数据目录布局与 MongoDB 共享接口用法【免费下载链接】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 Snap 包的运维排障展开如何确认wekan、mongodb及ferretdb等服务的运行状态、在哪里查日志、可写数据与只读镜像分别存放在哪个目录以及mongodb-slot/mongodb-plug内容接口的正确接法。读完之后你能够独立完成一台 WeKan Snap 实例从安装、启停到数据库共享的完整诊断流程并在数据库无法启动时按源码内置的提示逐步定位根因。一、WeKan Snap 是什么一组 systemd 服务而不是一个可执行程序Snap 是面向 Linux 的打包格式/snap/wekan/current是一个只读挂载的 squashfs 镜像里面装着 WeKan 应用本体与所有依赖而所有可写内容都放在镜像之外。安装后的 WeKan 并不是一个你在终端里敲命令运行的程序而是一组由 snapd 托管、systemd 拉起的服务。从 snapcraft.yaml 的apps:定义可以看到当前版本包含的守护进程应用服务名启动脚本说明wekan./bin/wekan-controlWeKan 主进程Meteor 应用声明after: [mongodb, ferretdb]mongodb./bin/mongodb-control内置 MongoDB 7ferretdb./bin/ferretdb-control内置 FerretDB v1SQLite 后端新安装的默认数据库caddy./bin/caddy-control反向代理提供 Caddy 自动 HTTPS声明after: [mongodb]此外还有一批非守护的命令行工具daemon未声明help、open、database-backup、database-list-backups、database-compare、database-merge、database-restore、migrate、repair-attachments、maintenance、problems等均以snap run wekan.app调用。这里有两点值得说明官方早期文档中的表述是应该有两个服务mongodb和wekan在运行。从当前 snapcraft.yaml 看默认发行版又多了ferretdb与caddy两个常驻服务——排查时不要只盯两个服务ferretdb的状态同样重要。WeKan 是服务端应用所以除了help命令外没有任何面向普通用户的可执行命令安装后在桌面菜单看到入口、以及在终端使用wekan.help查看全部配置说明是它的常规交互方式。二、安装与启用/禁用先理解 enable/disable 的语义安装只需要一条命令$ snap install wekanSnap 支持对任意服务做enable/disable通常配合snap stop/snap start。对 WeKan 而言这个机制的用途是想临时停掉 WeKan 但不想卸载——因为卸载snap remove会连带删除全部用户数据。典型场景是维护期间停服务、保留数据$ sudo snap stop wekan.wekan # 停止主服务 $ sudo snap disable wekan.wekan # 禁止随系统自启 # ...维护... $ sudo snap enable wekan.wekan $ sudo snap start wekan.wekan这个语义与源码一致wekan-control 在启动时会用snapctl start --enable 实例名.ferretdb/snapctl start --enable 实例名.mongodb确保数据库服务处于启用且运行状态snapctl start --enable等价于snap enablesnap start以避免 WeKan 主服务无限等待一个被手动禁用掉的数据库服务。三、检查服务状态与翻日志排障的第一现场WeKan 是服务除了help之外没有别的用户可执行命令因此出问题时的第一反应应该是看服务状态。官方排障文档给出的标准动作是# 查看 wekan 相关的所有 systemd 服务状态 $ sudo systemctl status snap.wekan.*正常情况下应看到wekan与数据库服务mongodb或ferretdb处于active (running)任何一个显示failed或activating就是应该优先排查的对象。wekan.help的帮助输出中同样内置了这条提示见 wekan-help 中systemctl status snap.${SNAP_INSTANCE_NAME}.*一段。需要更详细的日志时用 journalctl# 一次看 wekan 所有服务的日志 $ sudo journalctl -u snap.wekan.* # 单独看某一个服务例如主服务 $ sudo journalctl -u snap.wekan.wekan.service # 或数据库服务原文档中该条命令省略了 journalctl 前缀完整写法如下 $ sudo journalctl -u snap.wekan.mongodb.service原文档第 4 条里sudo snap.wekan.mongodb.service这一行显然漏写了journalctl实际应以sudo journalctl -u snap.wekan.mongodb.service执行。等价地也可以直接用sudo snap logs wekan/sudo snap logs wekan.ferretdb查看——Snap 各启动脚本内置的诊断提示中反复引用的正是snap logs。先更新 snapd再谈排障。文档特别强调很多诡异问题源于机器上的 snapd 过旧第一步应当把系统包更新到最新并用下面命令确认版本$ snap version文档写于 snapd 2.26 年代原文Currently we are on 2.26现在只需确保snap version输出的 snapd/snapd-store/snapd-agent 均为当前发行渠道的最新版本即可。四、目录结构可写数据在哪里、只读镜像在哪里理解目录布局是排障与备份的基础。Snap 的三层目录职责如下路径性质存放内容/snap/wekan/current只读squashfs 挂载WeKan 应用镜像本体代码、Node.js、数据库二进制、Caddy 等随版本刷新而整体更换/var/snap/wekan/revision即$SNAP_DATA可写版本专属的可写数据/var/snap/wekan/common即$SNAP_COMMON可写跨版本共享数据库文件与其他共享设置升级/回滚都不受影响这三个路径在 snapcraft.yaml 的environment:中被显式定义为environment: SNAP_DATA: /var/snap/$SNAP_INSTANCE_NAME/$SNAP_REVISION SNAP_COMMON: /var/snap/$SNAP_INSTANCE_NAME/common SNAP: /snap/$SNAP_INSTANCE_NAME/$SNAP_REVISION原文档中共享文件夹创建在/var/snap/wekan/current下、可写数据在那里的表述对应的就是$SNAP_DATA这一修订号数据目录。需要特别注意两点工程含义均可在 wekan-control 的注释中印证$SNAP_COMMON不会被snap revert回滚——它跨修订号共享所以回滚旧版本时数据库文件依然保留。附件与头像在磁盘上不在数据库里。wekan-control 中WRITABLE_PATH默认为$SNAP_COMMON/files并预先创建attachments、avatars子目录诊断提示里也反复提醒迁移/换机时要把整个$SNAP_COMMON/files目录一并拷贝否则附件丢失。五、MongoDB 内容接口什么时候用 slot什么时候用 plugWeKan Snap 声明了一对content接口定义见 snapcraft.yamlplugs: mongodb-plug: interface: content target: $SNAP_DATA/shared slots: mongodb-slot: interface: content write: - $SNAP_DATA/share它们的用途仅限于两种复杂场景原文档第 5 条场景 a把 wekan 自带的 MongoDB 共享给其他 snap 使用—— 用wekan:mongodb-slot。做法是把对方 snap 的 plug 连接到wekan:mongodb-slot再让对方服务去使用共享目录里的 MongoDBunix socketsocket 文件名为mongodb-端口.sock端口取自MONGODB_PORT。具体操作细节见 Sharing-MongoDB。场景 b让 wekan 使用别处另一个 snap提供的 MongoDB—— 用wekan:mongodb-plug。做法是把wekan:mongodb-plug连到提供 MongoDB 的那个 snap 的 slot然后关闭 wekan 自带 MongoDB 并指向外部 socket$ snap set wekan disable-mongodbtrue $ snap set wekan mongodb-bind-unix-socketrun/mongodb-27017.sock注意mongodb-bind-unix-socket的值是相对共享目录的路径。源码侧的处理见 wekan-control设置了MONGODB_BIND_UNIX_SOCKET后它会拼出MONGO_URLmongodb://socket路径/wekan形式的 URI 供主进程连接。一个常见的错误接法在原文档里被明确点名把wekan:mongodb-plug连到wekan:mongodb-slot本身毫无意义自己连自己really makes no sense。slot 是我给别人用plug 是我用别人的方向不能反。六、源码内置的排障提示数据库起不来时Snap 自己会告诉你怎么办当前版本的 Snap 把大量排障知识直接写进了启动脚本 wekan-control读懂这些逻辑可以少走很多弯路。6.1 启动前先决定用哪个数据库脚本第一件实事是调用bin/database-role从数据本身判定运行在 FerretDB 还是 MongoDB 上是否有非空的 FerretDB SQLite 库、迁移是否完成而不是读一个可能与实际磁盘状态矛盾的配置文件。随后它确保恰有一个数据库服务在共享端口上运行snapctl start --enable选中项、snapctl stop --disable另一项。6.2 等待数据库就绪超过 120 秒会打印完整诊断清单WeKan 主进程不会在数据库应答之前打开 Web 端口。就绪探测使用内置的db-evalNode.js 24 mongodb驱动直连 wire 协议因此不再依赖 mongosh。若等待超过WEKAN_DB_WAIT_TIMEOUT默认 120 秒脚本会在日志里打印一次排障清单这正是官方推荐的检查顺序等待 FerretDB 时wekan-controlWeKan: FerretDB still not accepting connections on host:port. Check the FerretDB log for the real reason: snap logs 实例名.ferretdb Common causes after a snap update: - the bundled FerretDB binary cannot run on this CPU/architecture (exec format error in the log) - report your snap version and CPU architecture to WeKan. - a locked or corrupt SQLite database under: $SNAP_COMMON/files/db - FerretDB left disabled/stopped (a failed migration hand-off): snap start --enable 实例名.ferretdb To keep working on MongoDB instead while this is sorted out: snap set 实例名 databasemongodb Attachments and avatars are stored ON DISK under WRITABLE_PATH, NOT in the database ($SNAP_COMMON/files), so they are safe.等待 MongoDB 时wekan-control最典型的场景是用旧版 MongoDB 写出的数据库新版 mongod 打不开脚本给出的升级步骤是1. Start the OLD, previously-working MongoDB version. 2. Back up: mongodump --archivewekan.archive --gzip 3. Stop old MongoDB. Start the NEW MongoDB on an EMPTY data dir. 4. Restore: mongorestore --archivewekan.archive --gzip --drop 5. Start WeKan again.并要求同时检查snap logs 实例名.mongodb关注featureCompatibilityVersion不匹配、mongod 版本错误、或需要mongod --repair的非正常关闭。6.3 等待期间Web 端口会直接说人话仅把原因写进日志是不够的——站点宕机时管理员最后才会想到去看snap logs。因此脚本设置了WEKAN_DB_WAIT_PAGE_SECONDS默认 30 秒等待数据库超过该时间后会在 Web 端口上启动一个正在等待数据库的提示页由 wekan-maintenance-page.mjs 提供并在数据库就绪前一直持有该端口避免浏览器超时、代理缓存 503 等次生问题。类似的状态页还有两种触发条件维护模式$SNAP_COMMON/.wekan-maintenance文件存在时用snap run wekan.maintenance on|off切换直接对所有 URL 返回 HTTP 503 维护页供管理员手工操作数据库数据库文件过旧$SNAP_COMMON/.mongodb-data-too-old标记存在且实例并非运行在含数据的 FerretDB 上时返回数据库对此版本 Snap 来说太旧的解释页该标记由迁移控制逻辑在尝试了所有可用读取器之后写入。6.4 资源预算与内存启动脚本还会按可用内存读取/proc/meminfo与 cgroup 限额取较小者自动设置 Node 堆上限与 FerretDB 的 Go 内存上限见 wekan-control日志首行即可看到例如WeKan memory budget: Node 2457 MiB; FerretDB Go 512 MiB; available 4096 MiB.若遇到 Node 堆溢出可参考脚本内注释的NODE_OPTIONS--max_old_space_size4096或--stack-size调整方式。七、常用诊断与数据救援命令速查除systemctl/journalctl外Snap 提供了一组面向管理员的snap run命令帮助文本由 wekan-help 生成wekan.help可随时打印并列出全部配置键的当前值与默认值# 查看帮助含所有支持的 settings key 及当前值/默认值 $ wekan.help # 数据库备份 / 列出备份 / 恢复默认目录 $SNAP_COMMON/db-backups $ sudo snap run wekan.database-backup [backup file] $ sudo snap run wekan.database-list-backups $ sudo snap run wekan.database-restore path to backup # 迁移后实例有两份数据副本MongoDB 原件 FerretDB 副本 # 先看各自内容不改动再把缺失的文档合并过来只 INSERT不覆盖不删除 $ sudo snap run wekan.database-compare $ sudo snap run wekan.database-merge # 打印 Admin Panel Problems 状态概览migrations | login | broken-cards | cpu | help # 供只有服务器访问权限、无法登录管理面板的运维查看 $ sudo snap run wekan.problems # 增量修复附件/头像启动时也会自动在后台运行 $ sudo snap run wekan.repair-attachmentswekan.help输出还给出了常用配置方式例如snap set wekan debugtrue调试 OIDC 等、snap set wekan mongo-url...、snap set wekan mongo-log-destinationsnapcommon以及结尾的警示部分设置变更会导致部分或全部服务重启请谨慎操作。八、排障流程小结结合原文档与源码一条可复用的排查链路是snap version确认 snapd 不是旧版sudo systemctl status snap.wekan.*找出非active的服务当前版本应关注wekan、mongodb/ferretdb、caddysudo journalctl -u snap.wekan.服务或sudo snap logs wekan.服务读日志优先匹配脚本内置提示中的关键症状exec format error、SQLite 锁/损坏、featureCompatibilityVersion不兼容核对数据目录数据库在/var/snap/wekan/common$SNAP_COMMON附件在/var/snap/wekan/common/files/snap/wekan/current是只读镜像、改动它没有意义涉及跨 snap 共享数据库时确认 slot/plug 方向slot 给别人、plug 用别人的并通过 unix socketmongodb-端口.sockdisable-mongodb/mongodb-bind-unix-socket配置连通怀疑数据版本问题时用wekan.database-compare/wekan.database-merge/wekan.problems在不动数据的前提下取证。更多背景可继续参考仓库内的 Snap 安装说明、共享 MongoDB 操作 与 邮件排障文档。【免费下载链接】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），仅供参考