Wekan 12.64 Docker Compose 部署指南

目标：用 Docker Compose 一键部署 Wekan v12.64 + MongoDB 7（副本集 rs0）双服务栈，完成编排文件配置、副本集一次性初始化、启动验证、REST API 建板功能实测、数据持久化与日常运维，并给出镜像选型、环境变量、等价 docker run 与常见问题；篇末附 Kubernetes（Helm）部署形态说明。全部命令与回显均实测采集（2026-10-25），组件背景见《Wekan 介绍与选型指南》，裸机安装见《Ubuntu 22.04 安装 Wekan 12.64 指南》。

一、环境信息

本文所有命令在以下环境实测：

宿主系统：Ubuntu 22.04（x86_64）
Docker 与 Compose：Docker Engine + Compose v2 插件（docker compose version 可查询）
栈组成与镜像：quay.io/wekan/wekan:v12.64（应用）+ mongo:7（数据库，实测 7.0.x）
Compose 项目名：wekan-12.64-stack（容器名固定为 wekan-12.64-app / wekan-12.64-db）
部署目录：/opt/wekan-compose/（编排文件与 MongoDB 数据目录均在其下）
对外端口：宿主机 8136 → 应用容器 8080
容器网络：wekan-net（10.89.65.0/24，external 方式先建后用）
演示账号：admin / q1w2e3r4（部署后通过 REST API 注册创建，见 4.4 节）

💡 说明：q1w2e3r4 为本文演示用的固定测试口令，生产环境请务必换成高强度随机口令；宿主端口 8136 可按空闲情况自行调整（本文实测时 8135 被占用，故用 8136，见 FAQ Q2）。

二、镜像选型说明

镜像	本文所用 tag	角色	选型依据
`quay.io/wekan/wekan`	`v12.64`	Wekan 应用（Meteor/Node.js，镜像内置 Node 运行环境）	官方发布镜像，tag 与 GitHub Releases 版本号对应；同一版本同时推送到 `ghcr.io/wekan/wekan:v12.64`（Helm chart 默认用 ghcr）
`mongo`	`7`	业务数据库（副本集模式运行）	官方 `docker-compose-mongodb-v7.yml` 模板指定 MongoDB 7 路线

选型要点：

应用镜像锁定版本 tag（如 v12.64）而非 latest，升级时显式改 tag 后 docker compose pull && docker compose up -d，版本可追溯、可回滚；
数据库路线的取舍：Wekan 官方默认编排模板（docker-compose.yml）已切换为 FerretDB v1 + SQLite（MongoDB 协议兼容层，零外部数据库）；本文采用官方同时维护的 MongoDB 7 模板（docker-compose-mongodb-v7.yml）路线——MongoDB 副本集支持 change streams，实时推送延迟最低，适合生产；FerretDB 路线需以 METEOR_REACTIVITY_ORDER=polling 轮询兜底实时性（差异说明见《Wekan 12.64 配置参数详解》）；
镜像内置默认环境（实查 quay.io/wekan/wekan:v12.64 镜像元数据）：WITH_API=true、WRITABLE_PATH=/data、PORT=8080、DDP_TRANSPORT=sockjs、PASSWORD_LOGIN_ENABLED=true，容器内以非 root 的 wekan 用户运行，入口为 wekan-entrypoint.sh——编排时只需覆盖 MONGO_URL/ROOT_URL 等少数变量。

三、前置条件

已安装 Docker Engine 与 Compose v2 插件（验证命令：docker --version、docker compose version）；
宿主机端口未占用（本文用 8136；被占用会报 Bind for ... failed: port is already allocated，见 FAQ Q2）；
服务器可访问 quay.io 与 Docker Hub 拉取镜像；网络受限时先在能联网的机器 docker pull 后 docker save/docker load 迁移；
磁盘余量建议 ≥10 GB（两支镜像约 1 GB，余量为 MongoDB 数据与附件增长）。

四、部署步骤

4.1 建目录、网络与编排文件

mkdir -p /opt/wekan-compose
cd /opt/wekan-compose
docker network create --subnet 10.89.65.0/24 wekan-net

本文实测使用的完整 docker-compose.yml（MongoDB 7 副本集路线，与官方 docker-compose-mongodb-v7.yml 同路线；差异：显式项目名、镜像锁 v12.64、healthcheck 探测副本集状态、端口映射 8136、external 网络）：

name: wekan-12.64-stack

services:
  wekandb:
    image: mongo:7
    container_name: wekan-12.64-db
    restart: always
    command: mongod --replSet rs0 --bind_ip_all
    volumes:
      - /opt/wekan-compose/mongo-data:/data/db
    networks:
      - wekan-net
    healthcheck:
      test: ["CMD", "mongosh", "--quiet", "--eval", "try { quit(rs.status().ok === 1 ? 0 : 1) } catch (e) { quit(1) }"]
      interval: 5s
      timeout: 5s
      retries: 12

  wekan:
    image: quay.io/wekan/wekan:v12.64
    container_name: wekan-12.64-app
    restart: always
    depends_on:
      wekandb:
        condition: service_healthy
    environment:
      MONGO_URL: mongodb://wekandb:27017/wekan?replicaSet=rs0
      ROOT_URL: http://localhost:8136
      PORT: 8080
      WITH_API: "true"
      WRITABLE_PATH: /data
    ports:
      - "8136:8080"
    networks:
      - wekan-net

networks:
  wekan-net:
    external: true

关键项解读（逐项）：

配置项	实测值	说明
`command: mongod --replSet rs0`	—	必需：以副本集模式启动 mongod（Wekan 依赖副本集 change streams，裸 `mongo:7` 默认无副本集）
healthcheck `rs.status().ok`	—	探测副本集就绪；`depends_on: service_healthy` 让应用等数据库就绪后再启动
`MONGO_URL`	`mongodb://wekandb:27017/wekan?replicaSet=rs0`	主机名 `wekandb` 为 Compose 服务名；必须带 `?replicaSet=rs0`，与 `command` 中副本集名一致；库名 `wekan` 首启自动创建
`ROOT_URL`	`http://localhost:8136`	对外访问地址，邮件/通知内链接由此拼接；改端口需同步修改
`ports: "8136:8080"`	—	宿主机 8136 → 容器 8080（镜像默认 PORT=8080，故 `PORT` 变量可省，此处显式写出便于阅读）
`WITH_API`	`"true"`	REST API 总开关；镜像默认已为 true，显式声明防止被覆盖丢失
`WRITABLE_PATH`	`/data`	附件等可写数据目录（镜像默认值；持久化建议见第五章）
`mongo-data` bind mount	`/opt/wekan-compose/mongo-data`	MongoDB 数据落宿主机目录，便于备份

4.2 首次启动与副本集一次性初始化（关键排障实录）

首次直接 docker compose up -d 会失败——全新数据目录下 MongoDB 副本集尚未初始化，healthcheck 的 rs.status() 探测不通过：

dependency failed to start: container wekan-12.64-db is unhealthy

这是 MongoDB 7 路线的必经一步（官方模板注释同样要求先初始化副本集）。处理方式：先单独起数据库，执行一次性 rs.initiate()：

docker compose up -d wekandb
docker exec wekan-12.64-db mongosh --quiet --eval 'rs.initiate()'

实测回显（节选关键行）：

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

然后再整体启动：

docker compose up -d

实测回显（输出节选）：

 Container wekan-12.64-db  Healthy
 Container wekan-12.64-app  Started

⚠️ 注意：rs.initiate() 只需在首次部署（数据目录为空）时执行一次；之后数据目录里已有副本集配置，重启/升级均无需再执行。

4.3 启动状态确认

docker compose ps

实测回显：

NAME              IMAGE                        STATUS                   PORTS
wekan-12.64-app   quay.io/wekan/wekan:v12.64   Up                       0.0.0.0:8136->8080/tcp
wekan-12.64-db    mongo:7                      Up (healthy)             27017/tcp

数据库副本集主节点核验：

docker exec wekan-12.64-db mongosh --quiet --eval 'db.runCommand({hello:1}).isWritablePrimary'

实测回显：

true

HTTP 可用性核验：

curl -sI http://localhost:8136/

实测回显：

HTTP/1.1 200 OK
Content-Security-Policy: frame-ancestors 'self'
X-Frame-Options: SAMEORIGIN

应用日志核验（columnDatesScanned 等为启动时 schema 自检统计，出现即正常）：

docker compose logs --tail 6 wekan

实测回显（节选）：

wekan-12.64-app  | ... columnDatesScanned: 0 ...

4.4 功能验证（REST API 注册 → 登录 → 建板）

浏览器访问 http://<服务器IP>:8136 即可看到注册/登录页。命令行用 REST API 走通业务链路作为最终验证（首个注册的用户自动成为管理员）：

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

实测回显（tokenExpires 字段较长，节选）：

{"token":"9cO8Sii1obn0RTS641Clf058Iloge-8k-Umcg13mwS7","tokenExpires":"2027-01-23T...","id":"iZeyymEtNRT4J9PZr"}

登录换取令牌：

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

实测回显（tokenExpires 字段较长，节选）：

{"id":"iZeyymEtNRT4J9PZr","token":"-W94YKDMl97j9Fd8HY9WgXDK9KKBOOxOMa-V7y1oTxo","tokenExpires":"2027-01-23T..."}

创建看板（owner 填用户 id）：

curl -s -X POST http://localhost:8136/api/boards \
  -H 'Authorization: Bearer -W94YKDMl97j9Fd8HY9WgXDK9KKBOOxOMa-V7y1oTxo' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Compose 演示板","owner":"iZeyymEtNRT4J9PZr","permission":"private"}'

实测回显：

{"_id":"uekCxA98nutMb878c","defaultSwimlaneId":"KPC88LH7tGvjzvqkP"}

返回看板 id 即业务链路全部打通。建列表/建卡片/查卡片的完整 API 操作见《Wekan 12.64 API 使用详解》。

五、数据持久化说明

5.1 持久化落点清单

数据	位置（本文编排）	说明
MongoDB 业务数据（看板/卡片/用户等全部业务态）	bind mount：`/opt/wekan-compose/mongo-data` → 容器 `/data/db`	随编排文件同目录，便于打包备份
Wekan 附件/头像等可写文件	容器内 `/data`（`WRITABLE_PATH`）	本文实测栈未显式挂载，容器重建会丢失，生产建议按下节补挂

5.2 附件目录补挂（生产建议）

在 wekan 服务下追加一个命名卷挂载 /data，附件即独立于容器生命周期：

  wekan:
    volumes:
      - wekan-data:/data

volumes:
  wekan-data:

修改后执行 docker compose up -d 重建应用容器生效。

5.3 重启后数据保持实测

docker compose restart wekan
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8136/

实测回显：

重启后服务恢复且数据保留（MongoDB 数据在 bind mount 目录，独立于容器生命周期）；docker compose down 不删除宿主机 mongo-data 目录。

5.4 备份要点

备份需同时覆盖 MongoDB 数据与附件目录。MongoDB 侧可用 docker exec wekan-12.64-db mongodump --uri="mongodb://127.0.0.1:27017/wekan?replicaSet=rs0" --out=/data/db/dump 导出后从宿主机 mongo-data/dump 取走（官方 Wiki 备份专题即此思路）；更系统的备份恢复操作（mongodump/mongorestore 实测）见《Ubuntu 22.04 安装 Wekan 12.64 指南》第 7.3 节，命令在容器内外等价。

六、环境变量表

6.1 Wekan 应用服务变量（本文实测值）

变量	本文实测值	镜像默认	说明
`MONGO_URL`	`mongodb://wekandb:27017/wekan?replicaSet=rs0`	无（必填）	数据库连接串；主机名为 Compose 服务名，必须带 `replicaSet`
`ROOT_URL`	`http://localhost:8136`	无（必填）	对外访问根地址
`PORT`	`8080`	8080	容器内监听端口（与 ports 右侧一致即可）
`WITH_API`	`"true"`	true	REST API 总开关
`WRITABLE_PATH`	`/data`	/data	附件等可写数据目录
`DDP_TRANSPORT`	未设置（默认 sockjs）	sockjs	实时推送通道（另有 websocket 可选）
`PASSWORD_LOGIN_ENABLED`	未设置（默认 true）	true	是否允许用户名/密码登录

完整变量体系（LDAP/OIDC/SAML、附件大小限制、邮件通知、登录锁定策略等约 185 项）见《Wekan 12.64 配置参数详解》。

6.2 MongoDB 服务关键配置

配置	本文实测值	说明
`command`	`mongod --replSet rs0 --bind_ip_all`	副本集模式启动；`--bind_ip_all` 使容器间可连
healthcheck	`mongosh --quiet --eval 'try { quit(rs.status().ok === 1 ? 0 : 1) } catch (e) { quit(1) }'`	副本集就绪探测；12 次 × 5s 覆盖冷启动耗时
数据卷	`./mongo-data:/data/db`	bind mount 到部署目录

七、配置参数说明

容器版没有独立配置文件：所有配置通过 compose 的 environment 注入，改配置即改 docker-compose.yml 后 docker compose up -d（会重建对应服务容器）；
参数体系与裸机 systemd Environment= 注入完全一致（同一套变量名），差别只在注入方式；
常用改配置场景：换访问域名（ROOT_URL）、限制附件大小（ATTACHMENTS_UPLOAD_MAX_SIZE/AVATARS_UPLOAD_MAX_SIZE）、登录锁定策略（ACCOUNTS_LOCKOUT_*）、接入 LDAP/OIDC——逐项含义见《Wekan 12.64 配置参数详解》。

八、配置文件挂载

官方镜像设计为「环境变量注入」，不需要挂载任何配置文件。常见扩展挂载只有两类：

附件目录外移：见 5.2 节，命名卷或宿主机目录挂载 /data；
MongoDB 数据外移：本文已用 bind mount（mongo-data）；需要换位置时改 volumes 左侧路径即可，迁移前先用 mongodump 备份。

九、等价 docker run

仅启动 Wekan 应用服务（不含数据库）的等价命令如下，用于理解 compose 配置到裸 docker 命令的映射（需先有以 --replSet rs0 启动并完成 rs.initiate() 的 MongoDB 容器，且二者在同一网络）：

docker run -d --name wekan-12.64-app \
  --network wekan-net \
  -p 8136:8080 \
  -e MONGO_URL="mongodb://wekandb:27017/wekan?replicaSet=rs0" \
  -e ROOT_URL="http://localhost:8136" \
  -e PORT=8080 \
  -e WITH_API=true \
  -e WRITABLE_PATH=/data \
  --restart always \
  quay.io/wekan/wekan:v12.64

💡 说明：Compose 相对裸 docker run 的增值点是 depends_on 健康检查编排（应用等数据库副本集就绪）、数据卷与网络的一键管理、以及 docker compose 系列运维命令；生产部署建议使用 Compose 或 Kubernetes（见第十二章）。

十、常用运维命令

以下命令均在本文部署目录（/opt/wekan-compose）内实测：

docker compose ps                      # 查看双服务状态与健康检查结果（回显见 4.3）
docker compose logs -f wekan           # 跟踪应用日志
docker compose logs --tail 50 wekandb  # 查看数据库最近 50 行日志
docker compose restart wekan           # 重启应用服务（实测后 200，见 5.3）
docker compose stop                    # 停止全部服务（保留容器与数据）
docker compose start                   # 启动已停止的服务
docker compose down                    # 删除容器（保留宿主机 mongo-data 数据目录）
docker compose pull && docker compose up -d   # 升级镜像并应用（改 tag 后执行）
docker exec wekan-12.64-db mongosh --quiet --eval 'rs.status().ok'              # 副本集状态探测
docker exec wekan-12.64-db mongosh --quiet --eval 'db.runCommand({hello:1}).isWritablePrimary'  # 主节点确认

升级操作（官方模板注释给出的流程）：docker compose stop → 修改编排文件中镜像 tag 为新版本（版本号查询 GitHub Releases）→ docker compose pull → docker compose up -d。只动 wekan 应用服务，不要删数据库容器与数据目录；跨大版本（如 MongoDB 3.x→4.x 时代）升级需先 mongodump 备份并用 --noIndexRestore 恢复，详见官方 Wiki 备份专题。

十一、常见问题（FAQ）

Q1：首次 docker compose up -d 报 dependency failed to start: container wekan-12.64-db is unhealthy？ 本文实测复现。定位：全新数据目录下副本集未初始化，healthcheck 的 rs.status() 探测失败，应用因 depends_on: service_healthy 被拒绝启动。解决：按 4.2 节先 docker compose up -d wekandb，docker exec wekan-12.64-db mongosh --quiet --eval 'rs.initiate()'（回显 ok: 1），再 docker compose up -d。该初始化只需首次执行一次。

Q2：启动报 Bind for 0.0.0.0:8135 failed: port is already allocated？ 本文实测遇到（8135 被其他进程占用）：

Bind for 0.0.0.0:8135 failed: port is already allocated

解决：改 ports 左侧宿主端口（本文改为 8136），同步修改 ROOT_URL 端口后 docker compose up -d 重建。

Q3：调用 /api/boards 返回空数组 []，或返回 WeKan API is disabled...？ 前者是 v12.64 实测行为——GET /api/boards 不列出当前用户看板，改用 GET /api/users/<用户id>/boards（详见《Wekan 12.64 API 使用详解》）；后者说明 WITH_API 被改为 false，恢复为 "true" 并 docker compose up -d 重建即可。

Q4：ROOT_URL 与实际访问地址不一致有什么影响？ 邮件邀请、通知内的卡片链接均以 ROOT_URL 拼接，填错会导致链接不可达；前置 Nginx 反代时把 ROOT_URL 改为最终对外地址（含 https 与域名）后 docker compose up -d 重建。

Q5：docker compose logs wekan 出现数据库连接错误？ 排查顺序：docker compose ps 看 wekan-12.64-db 是否 (healthy) → 不健康时按 Q1 检查副本集初始化 → 核对 MONGO_URL 的主机名（wekandb）、副本集名（rs0）与数据库服务 command 一致。

十二、Kubernetes 部署形态（Helm）

Wekan 官方在 Kubernetes 上的交付形态是 Helm Chart（来源：github.com/wekan/charts 仓库、wekan.fi/charts 文档站与 ArtifactHub，2026-10-25 查询）：

Chart 坐标：仓库 https://wekan.github.io/charts，chart 名 wekan，chart 版本 12.64.0、appVersion 12.64（与本文版本对应）；
数据库默认形态：chart 自带 FerretDB（templates/ferretdb-*.yaml）承担数据库角色；要外接 MongoDB（如本文的 MongoDB 7 副本集），设 externalDatabase.url 并关闭 ferretdb.enabled=false；
镜像：ghcr.io/wekan/wekan:v12.64（注意 k8s 路线默认用 ghcr，compose 模板用 quay，二者同源）；
关键 values：platform: kubernetes（OpenShift 时改为 openshift 以禁用 initContainer chown）；replicaCount: 1；FerretDB 路线下 METEOR_REACTIVITY_ORDER=polling（无 change streams），外接 MongoDB 7 时可用 changeStreams,oplog,polling；DDP_TRANSPORT=sockjs。

示例命令（helm 3）：

helm repo add wekan https://wekan.github.io/charts
helm repo update
helm install wekan wekan/wekan --version 12.64.0

⚠️ 注意：本节仅给出官方 chart 来源、关键 values 与示例命令，k8s 集群实测见后续 K1 批次专题文档。

十三、参考链接

Wekan 官方编排模板（含 FerretDB 默认版与 MongoDB 7 变体，注释含变量说明）：https://github.com/wekan/wekan（仓库根目录 docker-compose.yml 与 docker-compose-mongodb-v7.yml）
Wekan 官方 Wiki（备份/恢复、升级专题）：https://github.com/wekan/wekan/wiki
Wekan 镜像仓库（quay.io）：https://quay.io/repository/wekan/wekan
Wekan Helm Chart：https://github.com/wekan/charts 、https://wekan.fi/charts 、https://artifacthub.io/packages/helm/wekan/wekan
mongo:7 镜像：https://hub.docker.com/_/mongo
本专栏相关篇目：《Wekan 介绍与选型指南》、《Ubuntu 22.04 安装 Wekan 12.64 指南》、《Wekan 12.64 配置参数详解》、《Wekan 12.64 API 使用详解》