Wekan 12.64 API 使用详解

目标：从 0 到 1 讲清 Wekan v12.64 REST API 的启用、认证与各资源域（用户、看板、列表、卡片）的调用方式，所有请求与响应均来自真实运行的 v12.64 实例逐行照抄（2026-10-25 实测）。组件安装见《Ubuntu 22.04 安装 Wekan 12.64 指南》或《Wekan 12.64 Docker Compose 部署指南》；完整配置参数见《Wekan 12.64 配置参数详解》；组件背景见《Wekan 介绍与选型指南》。

一、环境信息

本文实测环境：

服务端：Wekan v12.64（官方 release bundle，自带 Node.js v26.12.1），MongoDB 7.0.45 副本集 rs0，监听 http://localhost:8081，systemd 托管。
关键配置：WITH_API=true（REST API 总开关，见第二章）。
客户端工具：curl（任意支持 HTTP 的工具均可，如 Postman、HTTPie、Python requests）。
演示账号：admin / q1w2e3r4（本文实测注册的账号）。

二、前置条件

2.1 确认 API 已启用

Wekan 的 REST API 由环境变量 WITH_API 控制，bundle 直跑时默认关闭（false），官方镜像默认开启（true）。未启用时，任何 /api/* 请求都会返回禁用提示。

未启用时的实测响应：

curl http://localhost:8081/api/boards

输出：

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

解决：在 systemd 单元 /etc/systemd/system/wekan.service 的 [Service] 段加入 Environment=WITH_API=true，然后：

systemctl daemon-reload
systemctl restart wekan
systemctl is-active wekan

输出：

active

验证 API 已启用：

curl -I http://localhost:8081/api/boards

输出：

HTTP/1.1 200 OK

⚠️ 注意：WITH_API=false 不仅关闭 REST API，还会同时禁用「导出看板」功能（导出依赖 API 通道）。

2.2 端点与认证方式

端点基准：ROOT_URL 决定的外部地址，本文实测为 http://localhost:8081。
认证方式：注册/登录接口返回 Bearer Token，后续请求在 Header 中携带 Authorization: Bearer <token>。
令牌有效期：默认 90 天（由 ACCOUNTS_COMMON_LOGIN_EXPIRATION_IN_DAYS 控制）。

三、API 总览

Wekan REST API 按资源域划分，核心端点如下：

资源域	端点	说明
用户	`POST /users/register`	注册新用户（直接返回 Token）
用户	`POST /users/login`	登录获取 Token
看板	`POST /api/boards`	创建看板
看板	`GET /api/boards/:boardId`	获取看板详情
看板	`GET /api/users/:userId/boards`	获取指定用户的看板列表
列表	`POST /api/boards/:boardId/lists`	在看板中创建列表
列表	`GET /api/boards/:boardId/lists`	获取看板全部列表
卡片	`POST /api/boards/:boardId/lists/:listId/cards`	在列表中创建卡片
卡片	`GET /api/boards/:boardId/lists/:listId/cards`	获取列表全部卡片

⚠️ 已知坑：GET /api/boards（无用户维度）在当前版本实测返回空数组 []，即使该用户已创建看板。获取看板列表必须使用用户维度端点 GET /api/users/:userId/boards（实测见第五章 5.2 节）。

四、认证与首次调用

4.1 注册新用户

注册接口直接返回登录 Token，无需二次登录：

curl -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"}

字段说明：

字段	说明
`token`	后续 API 调用的 Bearer Token
`tokenExpires`	Token 过期时间（ISO 8601，默认 90 天后）
`id`	用户 ID（后续创建看板、卡片时作为 `owner`/`authorId` 使用）

💡 说明：注册接口在「管理员未禁用公开注册」时可用；生产环境建议在 Admin Panel / People / Registration 中关闭公开注册后，由管理员在面板中创建账号，再通过登录接口获取 Token。

4.2 登录获取 Token

已有账号通过登录接口换取 Token：

curl -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"}

⚠️ 注意：同一账号每次登录都会签发新的 Token（旧 Token 在过期前依然有效）。脚本场景建议每次运行时重新登录取 Token，而不是硬编码长期 Token。

4.3 携带 Token 调用受保护接口

后续所有 /api/* 请求都需要在 Header 中携带 Token：

curl -H "Authorization: Bearer tdfw8ug5R0jyPiHY-ErOFNxDVD28d9G01O80VqyPtY-" \
  http://localhost:8081/api/boards/tuPWkXeK9cLFMH6fi

五、各 API 域详解

5.1 看板管理

创建看板

需要指定 owner（用户 ID）与 permission（private/public）：

curl -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"}

字段说明：

字段	说明
`_id`	新建看板的 ID，后续创建列表、查询详情时使用
`defaultSwimlaneId`	看板默认泳道 ID，创建卡片时可作为 `swimlaneId`

获取看板列表（用户维度）

⚠️ 重要坑位：GET /api/boards 实测返回空数组 []：

curl -H "Authorization: Bearer tdfw8ug5R0jyPiHY-ErOFNxDVD28d9G01O80VqyPtY-" \
  http://localhost:8081/api/boards

输出（实测）：

[]

必须使用用户维度端点才能拿到当前用户的看板列表：

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

输出（实测）：

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

获取看板详情

curl -H "Authorization: Bearer tdfw8ug5R0jyPiHY-ErOFNxDVD28d9G01O80VqyPtY-" \
  http://localhost:8081/api/boards/tuPWkXeK9cLFMH6fi

输出（实测，节选）：

{"_id":"tuPWkXeK9cLFMH6fi","title":"S9 演示看板","members":[{"userId":"6dik2xfRpdrDmRK39","isAdmin":true}],"permission":"private","color":"belize","slug":"s9-yan3-shi4-kan4-ban3","archived":false,"createdAt":"2026-10-25T01:59:48.187Z"}

字段说明：

字段	说明
`members`	看板成员列表，`isAdmin` 标识板管理员
`permission`	`private`（仅成员可见）或 `public`（公开）
`slug`	URL 友好标识（自动由标题拼音化生成）
`archived`	是否已归档

5.2 列表管理

创建列表

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

输出（实测）：

{"_id":"kcgRds4kDvXFLAgKj"}

获取看板全部列表

curl -H "Authorization: Bearer tdfw8ug5R0jyPiHY-ErOFNxDVD28d9G01O80VqyPtY-" \
  http://localhost:8081/api/boards/tuPWkXeK9cLFMH6fi/lists

输出（实测）：

[{"_id":"kcgRds4kDvXFLAgKj","title":"待办","modifiedAt":"2026-10-25T02:00:06.925Z","cardsModifiedAt":null}]

5.3 卡片管理

创建卡片

创建卡片必须指定 authorId（创建者用户 ID）与 swimlaneId（泳道 ID，取看板创建时返回的 defaultSwimlaneId）：

curl -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"}

获取列表全部卡片

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

输出（实测）：

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

字段说明：

字段	说明
`assignees`	负责人 ID 列表（空数组表示未分配）
`sort`	卡片在列表中的排序权重（越小越靠前）

六、分页、过滤与排序通用约定

Wekan v12.64 REST API 的列表端点直接返回完整 JSON 数组，实测未发现 ?limit=、?skip= 等分页查询参数生效的证据。当前版本的通用约定如下：

约定	说明
认证	所有 `/api/*` 端点必须携带 `Authorization: Bearer <token>`
请求体	`Content-Type: application/json`，字段为 camelCase
响应体	成功返回 JSON 对象或数组；未认证返回 `401`
排序	卡片按 `sort` 字段升序返回；看板/列表按创建顺序返回
过滤	通过路径参数过滤（如 `:userId`、`:boardId`、`:listId`），无查询字符串过滤语法

💡 说明：如果看板规模大到列表端点返回的数组过长（数千张卡片），建议在看板维度分多次获取（先取列表，再逐列表取卡片），或直接在 MongoDB 层做数据导出，而不是依赖 API 分页。

七、常见问题

7.1 调用 /api/boards 返回 "WeKan API is disabled"

现象：返回纯文本提示 API 被禁用。

原因：WITH_API 未设置（bundle 直跑默认 false）。

解决：systemd 单元加 Environment=WITH_API=true，daemon-reload + restart 后重试（实测过程见第二章 2.1 节）。

7.2 GET /api/boards 返回空数组 []

现象：用户明明创建了看板，但 GET /api/boards 返回 []。

原因：当前版本该端点不按 Token 用户过滤，实测返回空数组，属于已知行为。

解决：改用用户维度端点 GET /api/users/:userId/boards（实测可正确返回看板列表，见第五章 5.2 节）。

7.3 创建卡片时提示缺少 swimlaneId

现象：POST /api/boards/:boardId/lists/:listId/cards 报错或卡片不出现在任何泳道。

原因：Wekan 卡片必须挂在泳道下，swimlaneId 为必填。

解决：创建看板时响应中的 defaultSwimlaneId 即为默认泳道 ID；或通过看板详情端点获取泳道列表后选择目标泳道。

7.4 Token 过期后调用返回 401

现象：请求返回 401 Unauthorized。

原因：Token 超过 ACCOUNTS_COMMON_LOGIN_EXPIRATION_IN_DAYS（默认 90 天）有效期。

解决：重新调用 POST /users/login 获取新 Token（见第四章 4.2 节）。脚本场景建议捕获 401 后自动重登录，而不是让任务直接失败。

7.5 如何通过 API 导出看板

「导出看板」功能与 REST API 共用 WITH_API 开关。启用后可在 Web 界面看板菜单中导出 JSON，也可通过看板详情端点 + 列表端点 + 卡片端点逐级拉取后自行拼装导出数据（实测各端点返回字段见第五章）。

八、参考链接

Wekan REST API 官方文档：https://github.com/wekan/wekan/blob/main/docs/API/REST-API.md
Wekan GitHub 仓库：https://github.com/wekan/wekan
Meteor 账户体系（Token 机制）：https://docs.meteor.com/api/accounts-multi.html
站内关联文档：《Wekan 12.64 配置参数详解》（WITH_API 等参数详解）、《Ubuntu 22.04 安装 Wekan 12.64 指南》、《Wekan 12.64 Docker Compose 部署指南》、《Wekan 介绍与选型指南》