使用 Vagrant 与 VirtualBox 快速搭建 Wekan 看板测试环境Snap 版部署全指南【免费下载链接】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本文介绍如何基于 Vagrant 与 VirtualBox在本地虚拟机中快速拉起一套 Wekan 看板Kanban测试环境从初始化ubuntu/xenial64虚拟机、编写Vagrantfile与bootstrap.sh自动执行snap install wekan到访问localhost:8080完成首次使用再到备份数据与一键销毁环境。读完本文你将掌握一套可复现、可销毁、零残留的 Wekan 本地评估流程并理解 Snap 版 Wekan 的核心配置项root-url、port、mail-url等及其底层实现。方案总览为什么用 Vagrant Snap 组合Wekan 是使用 Meteor 构建的开源看板应用仓库根目录README.md即说明 The Open Source kanban, built with Meteor。部署方式有很多种——Docker、源码编译、Snap、VirtualBox 预置镜像等。本方案选择Vagrant VirtualBox Snap的组合理由是Vagrant负责声明式地管理虚拟机生命周期一条vagrant up建机、装软件、配置端口一条vagrant destroy彻底清除环境非常适合快速测试与反复实验Snap是 Linux 上即装即用、自动更新的打包格式snap install wekan一条命令即可得到包含 Wekan 应用与内置数据库的完整服务无需手工配置 Node.js / MongoDB 依赖二者结合后整个部署过程只依赖两个文本文件Vagrantfile与bootstrap.sh可提交到版本库、随时重建符合基础设施即代码的实践。需要说明的是本文参考文档撰写于 Ubuntu 16.04 (Xenial) 时期而 Ubuntu 16.04 官方支持早已结束EOL。在实际操作中建议改用仍在维护期的 LTS 版本 box如ubuntu/jammy64或ubuntu/noble64只要宿主机安装有新版 snapd下面bootstrap.sh中的 Snap 命令在新版 Ubuntu 上同样适用。仓库中 Snap 安装文档 列出的支持范围也印证了 Snap 方案面向Linux 服务器或笔记本自动更新独立 Wekan的场景。第一步下载并安装 Vagrant 与 VirtualBox在开始之前需要宿主机上准备好两个基础工具Vagrant负责虚拟机的创建、配置与销毁官网 vagrantup.com 下载对应平台的安装包VirtualBoxVagrant 默认使用的虚拟化 Provider官网 virtualbox.org 下载建议使用较新版本参考仓库中 VirtualBox 文档 对版本兼容性的说明——旧版 VirtualBox 与新版 box 镜像可能不兼容。安装完成后在命令行CMD 或 BASH验证工具可用vagrant --version VBoxManage --version第二步初始化 Vagrant 项目目录打开终端创建并进入一个专门的工作目录本文以wekan_vagrant为例mkdir wekan_vagrant cd wekan_vagrant然后让 Vagrant 自动生成一个最小化的Vagrantfile骨架并指定基础镜像box为 Ubuntu 16.04 64 位vagrant init -m ubuntu/xenial64-m--minimal参数会生成一个只包含必要配置的精简Vagrantfile。ubuntu/xenial64是 HashiCorp 维护的官方 Ubuntu 16.04 x86_64 box 名称。若改用其他 LTS 版本只需替换为对应的官方 box 名例如ubuntu/jammy64。第三步编写 Vagrantfile用文本编辑器打开刚生成的Vagrantfile将以下内容整体替换进去Vagrant.configure(2) do |config| config.vm.box ubuntu/xenial64 config.vm.provision :shell, path: bootstrap.sh config.vm.network forwarded_port, guest: 8080, host: 8080 config.vm.provider virtualbox do |v| v.memory 2048 v.cpus 2 end end逐项解读这份配置配置行作用说明config.vm.box ubuntu/xenial64指定虚拟机基础镜像为 Ubuntu 16.04 64 位config.vm.provision :shell, path: bootstrap.sh指定 shell 预置脚本虚拟机首次启动时自动执行即下面的初始化脚本config.vm.network forwarded_port, guest: 8080, host: 8080把虚拟机内部的 8080 端口Wekan 默认监听端口转发到宿主机的 8080 端口这样宿主机浏览器可直接访问localhost:8080。Vagrant 默认网络模式是 NATforwarded_port正是基于 NAT 的端口转发v.memory 2048分配 2 GB 内存给虚拟机v.cpus 2分配 2 个 CPU 核心给虚拟机提示Wekan Snap 默认监听8080端口仓库中 Supported-settings-keys.md 记录port的默认值为8080root-url默认值为http://127.0.0.1。如果你的宿主机 8080 端口已被占用可把host: 8080改成其他端口如host: 18080访问时对应改为localhost:18080。第四步编写 bootstrap.sh 初始化脚本在同一个目录下新建一个文本文件bootstrap.sh写入以下内容#!/usr/bin/env bash sudo apt-get update sudo snap install wekan sudo snap set wekan root-urlhttp://localhost:8080 sudo systemctl restart snap.wekan.wekan脚本执行逻辑sudo apt-get update刷新 APT 软件源Ubuntu 16.04 及绝大多数现代 Ubuntu 已内置 snapd无需额外安装其他发行版需参照 Snap 安装文档 先装 snapdsudo snap install wekan从 Snap Store 下载并安装 Wekan 稳定版安装后自动注册两个 systemd 服务——snap.wekan.wekanWekan 应用与snap.wekan.mongodb内置 MongoDB 数据库详见 Snap 故障排查文档sudo snap set wekan root-urlhttp://localhost:8080设置 Wekan 的对外根 URL。这一步非常关键仓库 Snap 安装文档 明确强调必须正确设置 URL否则打开卡片等页面跳转会不正确sudo systemctl restart snap.wekan.wekan重启 Wekan 服务使配置生效。关于root-url的取值从 Supported-settings-keys.md 可以看出它支持多种形态# 仅在指定端口提供本地访问 root-urlhttp://localhost:5000 # 局域网内通过 IP 访问 root-urlhttp://192.168.10.100:5000 # 通过 Nginx/Caddy 反向代理对外提供服务 root-urlhttps://example.com root-urlhttps://example.com/wekan # 子路径部署Vagrant 默认端口转发场景下虚拟机内 Wekan 对宿主机而言就是localhost:8080因此 bootstrap 脚本里的http://localhost:8080是正确取值。第五步启动虚拟机并访问 Wekan一切就绪后在wekan_vagrant目录执行vagrant upVagrant 会自动完成以下动作下载ubuntu/xenial64box首次较慢→ 创建 VirtualBox 虚拟机 → 执行bootstrap.sh预置脚本含 Snap 安装 Wekan同样需要一些时间→ 建立端口转发。看到 default: Running provisioner: shell...及脚本执行日志输出即表示流程正常。等预置脚本跑完、命令返回后打开宿主机浏览器访问localhost:8080看到 Wekan 登录/注册界面即部署成功。若要进入虚拟机内部操作使用vagrant ssh进入后可用sudo systemctl status snap.wekan.wekan查看服务状态、用sudo journalctl -u snap.wekan.wekan.service查看应用日志详见 Snap 故障排查文档。第六步常用运维命令与进阶配置服务管理Wekan Snap 内含多个 systemd 服务单元在虚拟机内可用 systemd 常规命令管理sudo systemctl status snap.wekan.wekan # Wekan 应用服务 sudo systemctl status snap.wekan.mongodb # 内置 MongoDB 服务 sudo systemctl restart snap.wekan.wekan # 修改配置后重启生效查看与设置配置项Snap 版 Wekan 的所有配置都通过snap set完成修改后服务会自动重启生效由 snap/hooks/configure 钩子实现脚本注释写明 settings were altered by user, safest way to get them applied is to restart service。sudo snap get wekan # 查看当前所有配置值 wekan.help # 查看全部支持的配置键说明 sudo snap set wekan port3001 # 修改 Wekan 监听端口常用配置键速查以下配置键摘自 Supported-settings-keys.md均为 Snap 版 Wekan 原生支持的设置配置键说明默认值root-urlWekan 对外根 URL如http://127.0.0.1、https://wekan.example.comhttp://127.0.0.1portWekan 监听端口8080mail-urlSMTP 服务器连接串如smtps://user:passmailserver.example.com:453smtp://user:passmailserver.example.com:25/mail-from邮件发件人名称与地址如Wekan Boards supportexample.comwekan-adminexample.commongodb-port内置 MongoDB 端口27019disable-mongodb是否禁用内置数据库使用外部数据库时设truefalsecaddy-enabled是否启用内置 Caddy 反向代理/HTTPS 服务falsecaddy-bind-portCaddy 反代后端端口3001with-api是否开启 Wekan API关闭后无法导出 JSONtruebrowser-policy-enabled是否启用浏览器安全策略truetrusted-url允许以 iframe 嵌入 Wekan 的可信 URLwebhooks-attributes出站 Webhook 携带的字段cardId,listId,oldListId,boardId,comment,user,card,commentId邮件配置示例对应 Snap 安装文档 第 6 步sudo snap set wekan mail-urlsmtps://user:passmailserver.example.com:453 sudo snap set wekan mail-fromWekan Boards supportexample.comLDAP 配置示例来自 Supported-settings-keys.md 的 LDAP 小节sudo snap set wekan ldap-enabletrue sudo snap set wekan default-authentication-methodldap sudo snap set wekan ldap-fullname-fieldCN数据存放位置从 Snap 故障排查文档 可知 Snap 版 Wekan 的目录布局/var/snap/wekan/current当前版本的可写数据目录/var/snap/wekan/common/数据库与配置等长期数据跨版本升级保留/snap/wekan/currentSnap 镜像的只读挂载点squashfs。第七步数据备份与恢复测试环境中产生数据后建议在销毁前备份。Snap 版 Wekan 提供开箱即用的备份命令详见 Backup-and-restore.md# 在虚拟机内以普通用户执行创建备份到 /var/snap/wekan/common/db-backups wekan.database-backup # 列出已有备份 wekan.database-list-backups # 恢复指定备份 wekan.database-restore FULL-PATH-TO-BACKUP-FILENAME更可靠的方案是用 MongoDB 客户端工具直接 dump注意 Snap 内置 MongoDB 端口是 27019sudo snap stop wekan.wekan # 先停止 Wekan保证数据一致性 mongodump --port 27019 # 导出数据到 dump 目录 sudo snap start wekan.wekan # 重新启动恢复时同样先停服务再用mongorestoresudo snap stop wekan.wekan mongorestore -d wekan --drop --port 27019 sudo snap start wekan.wekan注意wekan.database-*这类 Snap 内嵌备份方式与 Snap 生命周期绑定snap remove wekan时可能随之丢失长期保存请使用基于mongodump的导出方案。第八步销毁测试环境测试结束后返回宿主机命令行执行vagrant destroy该命令会关闭并删除整个虚拟机彻底清除测试环境的一切痕迹之后如需重新测试再次执行vagrant up即可基于同一份Vagrantfile与bootstrap.sh从零重建。⚠️ 重要提醒vagrant destroy会一并删除虚拟机内的全部数据——包括 Wekan 中的看板、卡片、成员、附件以及内置 MongoDB 中的所有内容。Vagrantfile注释与文档均明确强调这一点。如果数据需要保留务必先按第七步完成备份或者改用vagrant halt暂停虚拟机保留磁盘数据待需要时再vagrant up恢复运行。常见问题排查vagrant up卡在 box 下载首次下载ubuntu/xenial64需要网络访问 HashiCorp box 仓库可提前用vagrant box add ubuntu/xenial64预下载。访问localhost:8080无响应先确认vagrant up已完成 provisionbootstrap.sh执行完毕再在虚拟机内执行sudo systemctl status snap.wekan.wekan检查服务状态并用sudo journalctl -u snap.wekan.wekan.service查看日志端口冲突时修改Vagrantfile的host: 8080。Ubuntu 16.04 已停止维护xenial 已 EOLSnap 与 APT 软件源在新环境下可能不可用。建议改用仍在维护期的 LTS box如ubuntu/jammy64bootstrap.sh无需改动。修改 Snap 配置后不生效snap set wekan ...会由 configure 钩子 自动重启相关服务若未生效手动执行sudo systemctl restart snap.wekan.wekan。总结本文基于仓库 Vagrant 部署文档完整复现了Vagrant VirtualBox Wekan Snap的测试环境搭建链路两个文本文件定义全部基础设施、一条命令启动、一条命令销毁配合 Snap 系列文档 中的配置键体系可以快速验证 Wekan 功能、测试 LDAP/邮件/反向代理等生产特性且对环境零残留。对于希望在生产环境长期运行的读者建议进一步参考仓库中的 Snap 安装与配置文档、Nginx/Caddy 反向代理配置 与 备份恢复文档。【免费下载链接】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），仅供参考