Ubuntu 22.04 安装 Wekan 12.64 指南

目标：在 Ubuntu 22.04 服务器上从零完成 Wekan v12.64（开源自托管看板平台）的安装：MongoDB 7.0 副本集 → 官方发行 bundle 解压部署 → 环境变量配置 → systemd 托管 → HTTP 与 REST API 建板逐项验证，并给出 Snap 备选方案、升级降级方法、mongodump 备份与常见排障 FAQ。全部命令与回显均在 Ubuntu 22.04.5 LTS（x86_64）实测采集（2026-10-25），组件背景与选型对比见《Wekan 介绍与选型指南》。

一、环境信息

本文所有命令在以下环境实测，读者按相同条件操作可获得一致结果：

• 操作系统：Ubuntu 22.04.5 LTS（x86_64），主机名 wekan-server
• MongoDB：7.0.45（MongoDB 官方 apt 仓库 mongodb-org，副本集名 rs0，端口 27017）
• Wekan：v12.64（官方发行 bundle wekan-12.64-amd64.zip，258,730,521 字节）
• Node.js：bundle 自带 v26.12.1（位于 /opt/wekan/bundle/node，随包附 node-runtime 运行库）
• 安装根目录：/opt/wekan（bundle 解压于 /opt/wekan/bundle）
• 应用端口：8081（systemd 服务名 wekan）
• 数据目录：/var/lib/wekan（附件等可写数据，WRITABLE_PATH 指向）
• 服务运行账号：系统账号 wekan（uid=999，无登录 shell）
• 演示账号：admin / q1w2e3r4（REST API 注册创建，见 4.9 节）

💡 说明：q1w2e3r4 为本文演示用的固定测试口令，生产环境请务必换成高强度随机口令。

二、前置条件

2.1 硬件与系统要求

Wekan 官方未公布硬性资源指标，以下为本文实测参考：服务以单进程 Node.js（Meteor）方式常驻，附件读写与 MongoDB 同机部署是主要磁盘消耗点。结合实测给出建议配置：

2.2 软件依赖总览

💡 技术拓展：Wekan 的数据库后端有两条路线——MongoDB 副本集（官方推荐生产路线，支持 change streams，实时推送延迟最低）与 FerretDB（MongoDB 协议兼容层，底层用 SQLite/PostgreSQL 存储，适合轻量场景；FerretDB 无 change streams，需用 METEOR_REACTIVITY_ORDER=polling 轮询兜底实时性）。本文裸机安装采用 MongoDB 7.0 副本集，理由是生产场景下实时性与生态兼容性最好；FerretDB 路线见《Wekan 12.64 配置参数详解》。

三、版本选型说明

版本信息查询日期为 2026-10-25，来源：GitHub Releases（https://github.com/wekan/wekan/releases）：

Wekan 发行渠道与资产对照：

选型建议：生产裸机安装选最新稳定版 bundle（本文写作时为 v12.64）。bundle 自带匹配版本的 Node.js 与运行库，避免了「Node 版本与 Meteor 构建不匹配」这类最常见的部署事故。

四、方案 A：官方发行 bundle 安装（推荐）

4.1 方案说明

官方 bundle 路线：在服务器上安装 MongoDB 7.0 并初始化为单节点副本集 → 下载解压官方 wekan-12.64-amd64.zip → 创建专用系统账号与数据目录 → 编写 systemd 单元（注入 MONGO_URL/ROOT_URL/WITH_API 等环境变量）→ 启动并验证。bundle 内自带 Node.js v26.12.1、node-runtime 运行库（含 libatomic.so.1）、mongo-tools 全套工具与预置好的 node_modules，目标机无需 npm 构建。本节全程命令与回显均实测。

4.2 安装基础工具

apt-get update
apt-get install -y curl wget gnupg unzip ca-certificates xz-utils

4.3 安装 MongoDB 7.0（官方仓库）

导入 MongoDB 官方 GPG 密钥并添加 7.0 仓库（Ubuntu 22.04 代号 jammy）：

curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | gpg --dearmor -o /usr/share/keyrings/mongodb-server-7.0.gpg
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse' > /etc/apt/sources.list.d/mongodb-org-7.0.list
apt-get update

确认候选版本后安装：

apt-cache policy mongodb-org

实测回显（关键行）：

mongodb-org:
  Installed: (none)
  Candidate: 7.0.45

apt-get install -y mongodb-org
mongod --version

实测回显（mongod --version 输出较长，节选关键行）：

Setting up mongodb-org (7.0.45) ...
db version v7.0.45

4.4 初始化单节点副本集（必需）

⚠️ 注意：此步不可省略。Wekan 基于 Meteor 框架，依赖 MongoDB 副本集的 change streams/oplog 实现实时推送；未初始化为副本集的 mongod 会让 Wekan 启动报错或功能异常。即使只有一台 MongoDB，也必须执行副本集初始化。

编辑 /etc/mongod.conf，找到 #replication: 一行，改为：

replication:
  replSetName: "rs0"

启动 MongoDB 并设置开机自启：

systemctl enable mongod
systemctl start mongod
systemctl is-active mongod

实测回显：

Created symlink /etc/systemd/system/multi-user.target.wants/mongod.service → /lib/systemd/system/mongod.service.
active

执行副本集初始化并验证：

mongosh --quiet --eval 'rs.initiate()'

实测回显：

{
  info2: 'no configuration specified. Using a default configuration for the set',
  me: '127.0.0.1:27017',
  ok: 1
}

mongosh --quiet --eval 'rs.status().ok'

实测回显：

1

4.5 下载并解压 Wekan bundle

从 GitHub Releases 下载 v12.64 的 amd64 bundle（文件较大，约 247 MiB，耐心等待）：

cd /root
wget https://github.com/wekan/wekan/releases/download/v12.64/wekan-12.64-amd64.zip
ls -l wekan-12.64-amd64.zip

实测回显：

-rw-r--r-- 1 root root 258730521 Oct 25 09:52 wekan-12.64-amd64.zip

解压到 /opt/wekan：

mkdir -p /opt/wekan
cd /opt/wekan
unzip -q /root/wekan-12.64-amd64.zip
ls /opt/wekan/bundle

实测回显：

README  bsondump  cpu-exec  ferretdb  main.js  mongo-tools  mongodump  mongoexport  mongofiles  mongoimport  mongorestore  mongostat  mongotop  node  node-runtime  programs  qemu-x86_64  server  star.json  start-wekan.sh

验证 bundle 自带 Node.js 版本（LD_LIBRARY_PATH 指向自带运行库目录，原因见本节末尾 ⚠️ 说明）：

LD_LIBRARY_PATH=/opt/wekan/bundle/node-runtime /opt/wekan/bundle/node --version
ls /opt/wekan/bundle/programs/server/node_modules | wc -l

实测回显：

v26.12.1
35

确认服务端依赖已随包预置（35 项），无需再执行 npm install。

⚠️ 注意（排障实录）：直接执行 /opt/wekan/bundle/node --version 可能报错：

node: error while loading shared libraries: libatomic.so.1: cannot open shared object file: No such file or directory

原因是 Node 26 在 x86_64 上链接了 libatomic.so.1。两种解法任选其一：

1. 推荐（本文采用）：利用 bundle 自带的 node-runtime 目录（内含 libatomic.so.1），所有调用处加 LD_LIBRARY_PATH=/opt/wekan/bundle/node-runtime，systemd 单元中以 Environment=LD_LIBRARY_PATH=/opt/wekan/bundle/node-runtime 注入（见 4.7 节）；
2. 系统级安装运行库：apt-get install -y libatomic1（实测安装后系统 Node 26.10.0 亦可正常运行，node --version 输出 v26.10.0）。

本文实测曾独立安装官方 Node.js v26.10.0（tar.xz 解压至 /opt/node）并配合 libatomic1 跑通 Wekan bundle，作为备用路径可行；但既然 bundle 自带匹配版本 Node，方案 A 主线直接用自带 Node，少一层外部依赖。

4.6 创建运行账号与数据目录

创建无登录权限的系统账号 wekan，规划 /var/lib/wekan 为数据目录（WRITABLE_PATH，存放上传的附件等），并移交属主：

useradd -r -m -d /var/lib/wekan -s /usr/sbin/nologin wekan
mkdir -p /var/lib/wekan/files
chown -R wekan:wekan /var/lib/wekan /opt/wekan
id wekan

实测回显：

uid=999(wekan) gid=999(wekan) groups=999(wekan)

4.7 编写 systemd 单元并托管

创建服务单元 /etc/systemd/system/wekan.service（内容如下）：

[Unit]
Description=Wekan Kanban Server
After=network.target mongod.service
Requires=mongod.service

[Service]
Type=simple
User=wekan
Group=wekan
Environment=MONGO_URL=mongodb://127.0.0.1:27017/wekan?replicaSet=rs0
Environment=ROOT_URL=http://localhost:8081
Environment=PORT=8081
Environment=WITH_API=true
Environment=WRITABLE_PATH=/var/lib/wekan
Environment=LD_LIBRARY_PATH=/opt/wekan/bundle/node-runtime
ExecStart=/opt/wekan/bundle/node /opt/wekan/bundle/main.js
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

逐项说明：

加载并启动服务：

systemctl daemon-reload
systemctl enable wekan
systemctl start wekan

实测回显（enable 一步）：

Created symlink /etc/systemd/system/multi-user.target.wants/wekan.service → /etc/systemd/system/wekan.service.

4.8 启动验证

查看运行状态：

systemctl is-active wekan

实测回显：

active

查看启动日志关键行：

journalctl -u wekan --no-pager | tail -20

实测关键日志行（节选）：

ROOT_URL is http://localhost:8081. Every link WeKan sends by email is built from it...
Avatar server routes initialized
SwimlaneId validation hooks installed

确认 HTTP 可用：

curl -sI http://localhost:8081/

实测回显：

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

浏览器访问 http://<服务器IP>:8081/ 即可看到 Wekan 注册/登录页（生产环境建议前置 Nginx 反代与 TLS，见 FAQ Q5 说明）。

4.9 REST API 功能验证（注册 → 登录 → 建板 → 建列 → 建卡）

Wekan 自带 REST API（v12.64 实测可用），此处以 API 走通一条完整业务链路作为安装成功的最终验证。API 详细端点清单见《Wekan 12.64 API 使用详解》。

⚠️ 注意（排障实录）：若 systemd 单元未设置 WITH_API=true，调用任意 /api/* 端点会返回纯文本：

WeKan API is disabled, so this address answers nothing. ... Set the environment variable WITH_API=true and restart WeKan.

解决：在单元中加入 Environment=WITH_API=true，执行 systemctl daemon-reload && systemctl restart wekan 后恢复正常（本文实测复现并修复）。

第 1 步：注册管理员账号（首个注册的用户自动成为管理员）：

curl -s -X POST http://localhost:8081/users/register \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","email":"admin@example.com","password":"q1w2e3r4"}'

实测回显：

{"token":"k0nXK2HQvPnXtZYQjqt_-Xph6m4oSxYts2I2-bPuEh-","tokenExpires":"2027-01-23T01:58:49.677Z","id":"6dik2xfRpdrDmRK39"}

第 2 步：登录获取令牌：

curl -s -X POST http://localhost:8081/users/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"q1w2e3r4"}'

实测回显：

{"id":"6dik2xfRpdrDmRK39","token":"tdfw8ug5R0jyPiHY-ErOFNxDVD28d9G01O80VqyPtY-","tokenExpires":"2027-01-23T01:58:56.501Z"}

第 3 步：创建看板（owner 填上一步返回的用户 id，令牌放入 Authorization: Bearer）：

curl -s -X POST http://localhost:8081/api/boards \
  -H 'Authorization: Bearer tdfw8ug5R0jyPiHY-ErOFNxDVD28d9G01O80VqyPtY-' \
  -H 'Content-Type: application/json' \
  -d '{"title":"S9 演示看板","owner":"6dik2xfRpdrDmRK39","permission":"private"}'

实测回显：

{"_id":"tuPWkXeK9cLFMH6fi","defaultSwimlaneId":"YnpLEN2vm25Go5PsL"}

第 4 步：查看当前用户的看板列表：

⚠️ 注意：GET /api/boards 实测返回空数组 []（该端点不列出当前用户看板），需用用户维度端点：

curl -s http://localhost:8081/api/users/6dik2xfRpdrDmRK39/boards \
  -H 'Authorization: Bearer tdfw8ug5R0jyPiHY-ErOFNxDVD28d9G01O80VqyPtY-'

实测回显：

[{"_id":"tuPWkXeK9cLFMH6fi","title":"S9 演示看板"}]

第 5 步：创建列表（List）：

curl -s -X POST http://localhost:8081/api/boards/tuPWkXeK9cLFMH6fi/lists \
  -H 'Authorization: Bearer tdfw8ug5R0jyPiHY-ErOFNxDVD28d9G01O80VqyPtY-' \
  -H 'Content-Type: application/json' \
  -d '{"title":"待办"}'

实测回显：

{"_id":"kcgRds4kDvXFLAgKj"}

第 6 步：在列表中创建卡片（authorId 填用户 id，swimlaneId 填建板时返回的默认泳道 id）：

curl -s -X POST http://localhost:8081/api/boards/tuPWkXeK9cLFMH6fi/lists/kcgRds4kDvXFLAgKj/cards \
  -H 'Authorization: Bearer tdfw8ug5R0jyPiHY-ErOFNxDVD28d9G01O80VqyPtY-' \
  -H 'Content-Type: application/json' \
  -d '{"title":"撰写季度报告","description":"汇总 Q3 数据并出图","authorId":"6dik2xfRpdrDmRK39","swimlaneId":"YnpLEN2vm25Go5PsL"}'

实测回显：

{"_id":"vWzFp9QjeeSPzqdRH"}

第 7 步：列出卡片确认：

curl -s http://localhost:8081/api/boards/tuPWkXeK9cLFMH6fi/lists/kcgRds4kDvXFLAgKj/cards \
  -H 'Authorization: Bearer tdfw8ug5R0jyPiHY-ErOFNxDVD28d9G01O80VqyPtY-'

实测回显：

[{"_id":"vWzFp9QjeeSPzqdRH","title":"撰写季度报告","description":"汇总 Q3 数据并出图","swimlaneId":"YnpLEN2vm25Go5PsL","assignees":[],"sort":0}]

至此，HTTP 页面访问与 REST API 全链路（注册/登录/建板/建列/建卡/查询）均验证通过，安装完成。

五、方案 B：Snap 安装（备选）

5.1 方案说明

Wekan 在 Snap 商店有官方维护的包（wekan），snapd 会自动处理 Node/MongoDB 依赖并以 systemd 服务托管，适合 Ubuntu 系服务器快速试用。

⚠️ 注意：Snap 方案要求宿主机是带 systemd 的 Linux 真机且已安装 snapd（Ubuntu Server/Desktop 默认自带）；在精简系统或无 systemd 环境（如部分 LXC、WSL1）上 snapd 无法正常工作，请改用方案 A。

5.2 安装命令

snap install wekan

安装后用 snap set 注入关键配置（键名与方案 A 环境变量对应，官方文档键名清单见「十、参考链接」第 4 条）：

snap set wekan root-url="http://localhost:8081"
snap set wekan port="8081"
snap set wekan with-api="true"

预期输出（形式如下，以实际版本为准）：

wekan (…) 12.x from Lauri Ojansivu (xet7) installed

5.3 验证与数据位置

snap services wekan

预期输出中 wekan 与内置 wekan.mongodb 均为 enabled/active。Snap 包内置 MongoDB，数据与配置位于 /var/snap/wekan/ 下；日常启停用 snap start wekan / snap stop wekan。

六、方案对比与选择建议

选择建议：生产环境选方案 A——MongoDB 独立部署便于备份、监控与性能调优，参数与目录布局完全透明；方案 B 适合几分钟内在 Ubuntu 真机上拉起一个试用实例。

七、配置说明

7.1 核心环境变量

Wekan 通过环境变量配置（方案 A 写在 systemd 单元，方案 B 用 snap set）。核心变量速查：

完整参数清单（LDAP/OIDC/SAML、附件限制、邮件通知、Matomo 统计等约 185 项）见《Wekan 12.64 配置参数详解》。

7.2 升级、降级与多版本

升级：停服 → 备份（见 7.3）→ 下载新版本 bundle 解压到新目录（如 /opt/wekan-new）→ 移交属主 → 修改 systemd 单元路径（或把 /opt/wekan 整体替换）→ systemctl daemon-reload && systemctl start wekan：

systemctl stop wekan
cd /opt
wget https://github.com/wekan/wekan/releases/download/v12.65/wekan-12.65-amd64.zip   # 版本号以 GitHub Releases 最新为准
mkdir wekan-new && cd wekan-new && unzip -q ../wekan-12.65-amd64.zip
chown -R wekan:wekan /opt/wekan-new
# 切换：mv /opt/wekan /opt/wekan-old && mv /opt/wekan-new /opt/wekan
systemctl start wekan
systemctl is-active wekan

降级：反向操作，恢复旧版本目录即可。降级前先恢复对应时间点的数据库备份，避免新版本写过的数据结构在旧版本上异常。

多版本并存：不同版本解压到不同目录，复制 systemd 单元改服务名、PORT、ROOT_URL 与路径，各自使用独立的 MongoDB 库名（修改 MONGO_URL 末尾库名，如 wekan-test）即可互不影响。

7.3 数据备份（mongodump 实测）

Wekan 的业务数据全部在 MongoDB 库 wekan 中，附件文件在 WRITABLE_PATH 目录。备份需两者兼顾。bundle 自带 mongodump 工具，直接可用：

/opt/wekan/bundle/mongodump --uri="mongodb://127.0.0.1:27017/wekan?replicaSet=rs0" --out=/var/lib/wekan/backup-2026-10-25

实测回显（逐集合导出，节选首尾）：

... writing `wekan.<coll>` to `/var/lib/wekan/backup-2026-10-25/wekan/<coll>.bson` ...
... done dumping wekan.<coll> ... documents

备份完成后 /var/lib/wekan/ 下新增 backup-2026-10-25 目录。再打包附件目录：

tar -czf /var/lib/wekan/backup-files-2026-10-25.tar.gz -C /var/lib/wekan files

恢复用配套的 /opt/wekan/bundle/mongorestore --uri="mongodb://127.0.0.1:27017/wekan?replicaSet=rs0" --dir=<备份目录>/wekan。

八、常见问题（FAQ）

Q1：启动后 /opt/wekan/bundle/node 报 libatomic.so.1: cannot open shared object file？ 见 4.5 节 ⚠️：systemd 单元中补 Environment=LD_LIBRARY_PATH=/opt/wekan/bundle/node-runtime 后 daemon-reload 并重启；或 apt-get install -y libatomic1 系统级解决。

Q2：调用 /api/boards 返回纯文本 WeKan API is disabled...？ WITH_API 未开启（默认 false）。systemd 单元加 Environment=WITH_API=true，执行 systemctl daemon-reload && systemctl restart wekan（本文实测复现与修复过程见 4.9 节 ⚠️）。

Q3：Wekan 启动失败，日志提示副本集/oplog 相关错误？ MongoDB 未初始化为副本集。按 4.4 节在 /etc/mongod.conf 配置 replication.replSetName: "rs0" 并重启 mongod，执行 rs.initiate()，确认 rs.status().ok 返回 1，同时核对 MONGO_URL 带 ?replicaSet=rs0。

Q4：GET /api/boards 返回空数组 []，但明明已创建看板？ 这是 v12.64 实测行为：GET /api/boards 不列出当前用户看板，改用用户维度端点 GET /api/users/<用户id>/boards（实测返回 [{"_id":"tuPWkXeK9cLFMH6fi","title":"S9 演示看板"}]），详见《Wekan 12.64 API 使用详解》。

Q5：ROOT_URL 填错有什么影响？ Wekan 邮件邀请链接、通知内卡片链接均以 ROOT_URL 拼接；填错会导致邮件内链接不可达。生产环境应填最终对外地址（含反代域名与 https），改后 systemctl restart wekan。前置 Nginx 反代时按 ROOT_URL=https://kanban.example.com、PORT=8081 监听回环地址即可。

Q6：端口 8081 被占，启动失败？ 改 systemd 单元的 PORT 与 ROOT_URL 为新端口（如 8082），daemon-reload 后重启；用 ss -ltnp | grep 8081 确认端口占用方。

九、卸载与清理

按以下顺序完整卸载（先停服务，再删单元与文件，最后按需清理数据库）：

systemctl disable --now wekan
rm /etc/systemd/system/wekan.service
systemctl daemon-reload
rm -rf /opt/wekan /var/lib/wekan
userdel wekan

数据库侧（确认不再需要数据后执行）：

mongosh --quiet --eval 'use wekan; db.dropDatabase()'

可选：连同 MongoDB 一起卸载（不影响系统其他组件时再执行）：

systemctl disable --now mongod
apt-get purge -y mongodb-org mongodb-org-server mongodb-org-shell mongodb-org-mongos mongodb-org-tools
rm -rf /var/lib/mongodb /var/log/mongodb /etc/mongod.conf

⚠️ 注意：db.dropDatabase() 与 rm -rf /var/lib/mongodb 均不可恢复，执行前确认已有有效备份（备份方法见 7.3 节）。

十、参考链接

1. Wekan GitHub Releases（bundle 下载）：https://github.com/wekan/wekan/releases
2. Wekan 官方 Wiki（安装与配置专题）：https://github.com/wekan/wekan/wiki
3. MongoDB 7.0 Ubuntu 安装官方文档：https://www.mongodb.com/docs/v7.0/tutorial/install-mongodb-on-ubuntu/
4. Snap 商店 Wekan 页（snap set 键名清单）：https://snapcraft.io/wekan
5. Wekan REST API 文档：https://github.com/wekan/wekan/wiki/REST-API
6. 本专栏相关篇目：《Wekan 介绍与选型指南》、《Wekan 12.64 Docker Compose 部署指南》、《Wekan 12.64 配置参数详解》、《Wekan 12.64 API 使用详解》