企业官网建设流程全解析

Wekan 虚拟化部署指南：在 VirtualBox 中安装、配置与维护 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

本篇指南围绕 Wekan 官方发布的 VirtualBox 虚拟设备（Virtual Appliance）展开，讲解如何在 Oracle VirtualBox 中导入.ova镜像、通过桥接或 NAT 网络访问运行在虚拟机内的 Wekan 服务、配置ROOT_URL与邮件参数、以及使用构建脚本把已有虚拟设备升级到最新版本。读完本文，你将掌握从下载镜像到局域网访问、再到源码级定制与磁盘扩容的完整操作链路。

一、Wekan 的 VirtualBox 虚拟设备方案概览

Wekan 是一个基于 Meteor 构建的开源看板应用（Kanban）。除了 Docker、Snap、源码构建等部署方式外，官方还提供开箱即用的 VirtualBox 虚拟设备（Virtual Appliance），适合希望在隔离的 Linux 虚拟机中快速体验或长期运行 Wekan 的用户。

虚拟设备的核心设计目标有三点：

1. 开箱即用：下载.ova文件后直接在 VirtualBox 中导入即可，虚拟机内已预装 Wekan 及其运行依赖；
2. 网络可达：虚拟设备默认使用桥接（Bridged）网络模式，虚拟机拥有独立 IP 地址，局域网内的其他电脑可直接通过浏览器访问，也可以通过 SSH（22 端口）登录虚拟机；
3. 可升级可定制：仓库的 releases/virtualbox 目录内置了完整的运维脚本，用于启动、停止、查询 IP、放开 80 端口权限，以及把镜像内的 Wekan 源码重建到最新版本。

官方要求使用 VirtualBox 5.2.22 或更新版本（注：原文档指向外部站点，实际以你安装的 VirtualBox 版本为准），旧版本 VirtualBox 与镜像不兼容。

两种官方虚拟设备：普通用户版与开发者版

两种镜像统一使用以下登录凭据：

• 用户名：wekan
• 密码：wekan

开发者版镜像额外预装了 Snap、Docker、Firefox、Chrome、带 Meteor.js 扩展的 Visual Studio Code、GHex 十六进制编辑器等工具，是进行 Wekan / Sandstorm 开发的一站式环境。两份.ova文件都托管在 https://releases.wekan.team（下载地址以该站点实际提供的版本为准）。

二、下载与导入虚拟设备

1. 下载.ova文件

根据你的使用场景在 https://releases.wekan.team 下载对应的.ova文件：

• 普通使用：wekan-VERSION.ova
• 开发使用：wekan-sandstorm-VERSION.ova

2. 解压

.ova文件本身是一个打包容器，建议先使用压缩工具解压：

• Windows：使用 7-Zip
• Linux 等：使用 p7zip

解压后可得到虚拟硬盘文件（通常是.vmdk），这为后面的高级用法（如转换为 Qubes OS 使用的 raw 镜像）留出了空间。

3. 导入虚拟设备

在 VirtualBox 中通过「管理 → 导入虚拟电脑（Import Appliance）」导入.ova文件即可。导入后可以看到虚拟设备默认的虚拟机配置：内存 2GB，硬盘镜像当前占用约 16GB、最大可扩展至 500GB。

4. 可选：将虚拟设备转换为其他虚拟化格式

如果需要在 Qubes OS 中运行，可以把.ova解包出的.vmdk作为虚拟硬盘使用，或转换为 raw.img格式供 Qubes OS 的 HVM 虚拟机加载。这一转换流程在 Qubes OS 官方文档中有详细说明，本文不再展开。

三、VirtualBox 网络模式与端口转发设置

虚拟设备在导入后，需要根据你的访问方式设置网络。VirtualBox 支持多种网络模式，官方推荐两种典型方案：

方案 A：桥接模式（Bridged Adapter）——局域网直接访问

选择「桥接网卡」，并在「名称」中选择宿主机实际使用的物理网卡，例如：

• 有线网络：eth0、enp9s0等
• 无线网络：wlan等

在这种模式下，虚拟机将获得与宿主机同网段的独立 IP 地址。局域网内任何电脑都可以通过http://<虚拟机IP>直接访问 Wekan，同时也可以用 SSH（端口 22）登录虚拟机。

方案 B：NAT 模式 + 端口转发——与宿主机共享地址

选择「网络地址转换（NAT）」，虚拟机会复用宿主机的 IP 地址对外通信。此时需要配置端口转发规则，将宿主机端口转发到 Wekan 虚拟机的 8080 端口（即 Wekan Node.js 服务监听端口），实现宿主机访问。

关于端口 80 的说明

官方虚拟设备的 Wekan 运行在 80 端口，且由/etc/rc.local在开机时自动启动。为什么普通进程能绑定 80 这样的特权端口？关键在于node-allow-port-80.sh脚本：

sudo setcap cap_net_bind_service=+ep /usr/local/bin/node

这条命令通过 Linuxsetcap机制，把cap_net_bind_service能力授予 Node.js 可执行文件，使其无需以 root 身份运行即可绑定 1024 以下的特权端口。仓库中的 releases/virtualbox/etc-rc.local.txt 展示了完整的开机自启逻辑：

#!/bin/sh -e # node-allow-port-80.sh sudo setcap cap_net_bind_service=+ep /usr/local/bin/node # Start Wekan at boot at Ubuntu 14.04 sudo -H -u wekan bash -c '/home/wekan/repos/wekan/releases/virtualbox/start-wekan.sh' exit 0

从源码结构看，开机时先授予 Node.js 绑定特权端口的权限，再以wekan普通用户身份启动 Wekan，避免了以 root 直接运行应用的安全风险。

四、首次启动与访问 Wekan

启动虚拟机

在 VirtualBox 中选中导入的虚拟设备并点击「启动」。系统启动后，Wekan 会由/etc/rc.local自动拉起。

登录虚拟机

通过 SSH 或虚拟机的图形桌面登录：

username: wekan password: wekan

查看虚拟机 IP

仓库提供了 releases/virtualbox/ipaddress.sh 用于查询当前 IP：

# ifdata -pa eth0 ip address

配置 ROOT_URL（关键步骤）

要让局域网内的其他电脑能够访问 Wekan，必须把ROOT_URL配置为虚拟机的实际 IP 地址。配置位于虚拟机内的/home/wekan/repos/start-wekan.sh：

cd repos ./stop-wekan.sh nano start-wekan.sh

stop-wekan.sh的实现非常简单直接——它通过pkill -f "node main.js"终止正在运行的 Wekan Node.js 进程（见 releases/virtualbox/stop-wekan.sh）。

在start-wekan.sh中修改环境变量，例如：

export ROOT_URL=http://192.168.1.200 export MAIL_URL=smtp://user:pass@mailserver.example.com:25/ export MAIL_FROM='Example Wekan Support <support@example.com>'

保存方法：按Ctrl+O回车保存，再按Ctrl+X退出 nano 编辑器。

为什么 ROOT_URL 必须正确？仓库根目录的 start-wekan.sh 中对这一变量有明确注释：

# If port is 80, must change ROOT_URL to: http://YOUR-WEKAN-SERVER-IPv4-ADDRESS , like http://192.168.0.100 # If port is not 80, must change ROOT_URL to: http://YOUR-WEKAN-SERVER-IPv4-ADDRESS:YOUR-PORT-NUMBER , like http://192.168.0.100:2000 # If ROOT_URL is not correct, these do not work: translations, uploading attachments. export ROOT_URL=${ROOT_URL:-http://localhost:2000}

也就是说，ROOT_URL 配置错误会导致翻译、附件上传等功能失效，这是虚拟化部署中最常见的坑之一。脚本默认值为http://localhost:2000，在虚拟机内部访问可以工作，但局域网外部访问必须改为虚拟机的 IP。

放开端口 80 并启动

./node-allow-port-80.sh ./start-wekan.sh

node-allow-port-80.sh即上文介绍的setcap授权脚本。启动后，在局域网内的任何电脑浏览器访问http://<虚拟机IP>即可使用 Wekan。

五、虚拟设备维护：升级到最新 Wekan

获取最新构建脚本

从 https://github.com/wekan/wekan-maintainer/tree/master/virtualbox 下载最新的虚拟机构建脚本（该仓库同时包含如何在普通 Ubuntu 14.04 64bit / Debian 9+ 原生或虚拟机环境中使用这些脚本的方法，以及让 Node.js 运行在 80 端口的脚本）。

说明：当前 Wekan 仓库的 releases/virtualbox 目录维护着一套同源脚本（README.txt、ipaddress.sh、node-allow-port-80.sh、start-wekan.sh、stop-wekan.sh），并在构建系统 build.sh 中注册了对应的命令行入口，例如「Server and VM | Show the VirtualBox VM's IP address」「Start WeKan in the VirtualBox VM」「Stop WeKan in the VirtualBox VM」等。

升级步骤

在虚拟机内依次执行：

# 1. 先执行一次 sudo 命令，以便输入 sudo 密码（密码：wekan） sudo ls # 2. 以普通用户运行构建脚本 ./build-meteor-1.6.sh

脚本交互式运行时：

• 第一次先选择选项 1，安装编译依赖；
• 依赖就绪后选择选项 3，重建 Wekan 源码到最新版本。

升级系统补丁

定期更新虚拟机内的 Ubuntu 系统：

sudo apt-get update

sudo apt-get -y dist-upgrade

注意：执行 sudo 命令时提示输入密码，即登录密码wekan。

更新后的参考材料

虚拟机的 Ubuntu 桌面上保留了丰富的参考资料：

• 桌面上的README.txt；
• ~/repos目录下的各运维脚本；
• /home/wekan/.bash_history记录了该虚拟设备当初的完整安装过程（包括其中的笔误），可作为排查问题的历史依据。

六、虚拟设备磁盘扩容与瘦身

虚拟硬盘规格

虚拟设备携带的硬盘镜像当前占用约 16GB，最大可增长至 500GB（动态扩展）。

扩容方法

使用VBoxManage命令扩大虚拟硬盘容量，例如：

VBoxManage modifymedium disk <path-to-vmdk> --resize <size-in-MB>

扩容后需要用 LiveCD 启动虚拟机，删除原有的逻辑交换分区（logical swap）和扩展分区（extended），重新创建更大尺寸的扩展分区并在其内部重建逻辑交换分区，使扩展的空间被文件系统真正利用。

压缩体积

官方镜像的尺寸经过专门瘦身处理（利用磁盘清零与压缩技术减小.vmdk的物理体积），用户在自行复制或归档虚拟机时同样可以参考这一思路：先在虚拟机内对空闲空间清零，再通过 VirtualBox 的克隆/压缩功能生成瘦身后的镜像。

七、深入源码：虚拟设备中的 Wekan 启动脚本解读

仓库根目录的 start-wekan.sh 是目前 Wekan 源码部署的标准启动模板，虚拟设备内的启动脚本是其简化/适配版本（见 releases/virtualbox/start-wekan.sh）。两者的核心环境变量保持一致：

在虚拟设备版本中，cd ~/repos/wekan/.build/bundle进入 Meteor 打包产物目录，最终以node main.js & >> ~/repos/wekan.log启动并把日志写入~/repos/wekan.log。脚本中保留了while true循环的注释结构，若希望崩溃后自动重启，可以取消注释让 Wekan 常驻运行。

现代版启动脚本（start-wekan.sh）则加入了更多生产环境逻辑，包括：

• 副本集（Replica Set）自动初始化：通过snap-src/bin/db-eval.mjs检查并初始化rs0副本集，为 MongoDB Change Streams 提供基础；
• Change Streams / polling 自动选择：根据是否具备node与db-eval，自动设置METEOR_REACTIVITY_ORDER=changeStreams,oplog,polling或polling；
• MongoDB 就绪等待：启动前轮询 MongoDB 主节点，超时（默认 120 秒）后打印数据库升级与迁移指引（mongodump/mongorestore备份恢复流程、WRITABLE_PATH下附件/头像的磁盘目录迁移提示等）；
• Node 堆内存自动适配：根据宿主机内存（含 cgroup 限制）自动计算--max-old-space-size，并默认以ulimit -s 65500; exec node main.js提升栈空间后启动。

这些机制解释了为什么虚拟设备/源码部署会强调 MongoDB 必须以副本集方式运行——现代 Wekan 默认依赖 Change Streams 实现实时数据同步。

八、第三方面向社区的虚拟设备：anselal 构建版

除了官方镜像，社区成员 anselal 也发布了一套 Wekan 虚拟设备，可从其仓库的 releases 页面下载：

• 登录凭据同样为：用户名wekan/密码wekan；
• 更多信息（包括用于生成该虚拟设备的脚本）见其仓库说明。

如果你在虚拟设备使用过程中遇到问题或希望提出功能需求，可以到 Wekan 官方仓库提交 issue。

九、常见问题与排查清单

1. 局域网内无法访问 Wekan？

按顺序检查：

1. 虚拟设备是否使用桥接模式并选择了正确的物理网卡；
2. start-wekan.sh中的ROOT_URL是否已改为虚拟机 IP；
3. node-allow-port-80.sh是否已执行（确认 Node.js 能绑定 80 端口）；
4. 虚拟机防火墙是否放行 80 / 22 端口。

2. 附件上传或翻译不生效？

优先检查ROOT_URL是否与浏览器地址栏中的实际访问地址完全一致（含端口号），详见 start-wekan.sh 中的注释说明。

3. 修改配置后需要重启 Wekan？

cd ~/repos ./stop-wekan.sh ./start-wekan.sh

4. 磁盘空间不足？

参考第六节使用VBoxManage扩容，或使用「清零 + 压缩」流程瘦身镜像。

十、总结

Wekan 的 VirtualBox 虚拟设备提供了从下载到上线的极简路径：导入.ova→ 启动 → 配置ROOT_URL→ 局域网访问，全程无需手动安装 MongoDB、Node.js 或编译 Meteor 应用。对于开发者，wekan-sandstorm镜像则直接内置了完整的交叉编译工具链。虚拟设备背后的运维脚本（node-allow-port-80.sh、start-wekan.sh、stop-wekan.sh、ipaddress.sh、etc-rc.local.txt）均可在本仓库的 releases/virtualbox 目录中查看，现代版启动模板 start-wekan.sh 中的 Change Streams、副本集自动初始化与内存自适应逻辑，则为迁移到生产环境提供了更完善的参考。

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