Kaneo 2.48.0 介绍与选型指南

Kaneo 是一个用 TypeScript 写成的轻量级开源项目管理工具，界面与交互走的是 Linear 那一类"快、干净、少层级"的路线，同时保留了看板、列表、日历、甘特图和 backlog 等成熟团队需要的视图。它由 usekaneo 团队维护，采用 MIT 许可证，既可以自托管，也可以直接使用官方云服务。本文基于 Kaneo v2.48.0（2026-10-26 发布）的源码、官方文档与 GitHub 元数据整理，重点回答三个问题：它到底是什么、和同类工具差在哪、什么团队适合上它。

💡 技术拓展：开源项目管理工具大致可分三族——重型企业套件（OpenProject、Redmine，模块齐全但部署与学习成本高）、敏捷专用工具（Taiga，Scrum/看板流程固化）、轻量任务协作工具（Kaneo、Vikunja、Leantime，强调上手速度与界面体验）。Kaneo 属于第三族，但通过自定义字段、自定义角色、GitHub 集成和 MCP 往上补了半档能力，定位介于"个人待办"与"企业套件"之间。

一、项目概况与版本事实

先把几个容易以讹传讹的基础事实钉死。以下数据均来自 GitHub API 与仓库内 package.json 的实查结果，不是二手资料。

一个值得注意的细节：任务的线索里写的是 kaneo-app/kaneo，但该路径现在返回 404，仓库实际归属 usekaneo/kaneo 组织。这说明项目改过组织名，按旧路径拉代码或查 API 都会失败，排障时不要被 404 误导。

版本节奏方面，Kaneo 发版非常密集：仅 2026-10-12 到 10-26 两周内就有 v2.46.1、v2.46.2、v2.47.0、v2.47.1、v2.48.0 五个版本。其中 v2.47.1 是安全版本，修复了作用域 API Key 与自定义工作区角色的权限校验、特权邀请链接、MCP 授权码与会话绑定等问题。生产环境自托管时，建议锁定具体小版本而不是长期跟 latest，升级前先看 Release Notes 是否含 "security release" 字样。

1.1 名称与商标

Kaneo 的拼写容易与 Kanban（看板）、Kanboard（另一款 PHP 看板工具）混淆。三者没有关系：Kanboard 是 PHP 单体的老牌看板，Kaneo 是 TypeScript 全栈的新项目。专栏内后续命令、容器名、目录名统一使用 kaneo 小写。

二、架构与技术栈

Kaneo 是一个 pnpm workspace 单仓库（monorepo），根 package.json 里 "packageManager": "pnpm@10.32.1"，"version": "2.48.0"。仓库顶层分为 apps/ 与 packages/ 两大部分。

apps/
├── api/        # 后端 API（Hono + Node.js）
├── web/        # 前端（React + Vite）
├── mobile/     # Android 客户端（Expo / React Native）
├── docs/       # Mintlify 文档站
└── site/       # 官网
packages/
├── cli/        # 命令行客户端
├── mcp/        # MCP Server
├── email/      # 邮件模板与发送
├── importers/  # Trello / PLANKA / Plane / Kaneo 导入器
├── permissions/# 权限模型
├── libs/       # 共享库
└── typescript-config/

2.1 后端框架：Hono，不是 NestJS

这是选型时最容易踩错的一点。任务线索里猜测后端是 NestJS，实际 apps/api/package.json 的依赖清单是：

"dependencies": {
  "@hono/node-server": "^2.1.3",
  "@hono/node-ws": "^1.3.1",
  "@hono/zod-openapi": "^1.6.3",
  "hono": "^4.13.14",
  "better-auth": "1.6.26",
  "@better-auth/api-key": "1.6.26",
  "drizzle-orm": "^0.45.3",
  "pg": "^8.23.1",
  "ioredis": "^6.0.0"
}

所以正确的技术栈描述是：Hono 4.13 提供 HTTP 路由与 WebSocket，better-auth 负责认证与会话，Drizzle ORM 负责数据访问与迁移，node-postgres 连接 PostgreSQL。没有任何 NestJS、Express、Prisma 依赖。Hono 基于 Web 标准 Request/Response，启动快、内存占用低，适合容器化和边缘部署，这也解释了为什么 Kaneo 的镜像可以做得比较小。

💡 技术拓展：Node.js 后端框架目前主流有五类——Express（生态最老、中间件最多，但类型支持弱）、Fastify（性能好、插件体系完善）、NestJS（Angular 风格，依赖注入 + 装饰器，企业级但样板代码多）、Koa（洋葱模型，轻量）、Hono（Web 标准 API，跨运行时，可跑 Node/Bun/Deno/Workers）。Kaneo 选 Hono，走的是"轻量 + 跨运行时 + 自带 OpenAPI"的路线，与它的产品定位一致。

2.2 数据与存储

Kaneo 的主存储只有 PostgreSQL。官方 compose.yml 使用 postgres:16-alpine 镜像，说明官方验证基线是 PostgreSQL 16。数据库连接有两种给法：

• 显式 DATABASE_URL：postgresql://user:password@host:5432/db，优先级最高；
• 派生模式：由 POSTGRES_DB、POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_HOST、POSTGRES_PORT 拼出连接串，官方 Compose 走的就是这条路。

README 与 .env.sample 都强调：只设 POSTGRES_DB 和 POSTGRES_USER 不会触发派生模式，必须有 POSTGRES_PASSWORD，或者显式给 host/port。这是很多自托管部署"连不上库"的第一号原因。

除 PostgreSQL 外，Kaneo 还有三类可选依赖：

2.3 前端与呈现

前端是 React + Vite 的单页应用。开发模式下前端跑在 5173，后端跑在 1337，两者分离；生产镜像则把 web 与 api 打进同一个镜像，由内置的 loopback nginx 对外只暴露 5173，/api 反代到后端。这个设计对自托管很友好：只需要暴露一个端口、配一个域名，不用额外维护前端容器和反向代理规则。

不过它也有一个副作用：前端在构建期把 KANEO_API_URL、KANEO_CLIENT_URL、KANEO_TURNSTILE_SITE_KEY 烧进了静态资源，容器启动脚本再做文本替换。因此改这些变量后必须重建/重启容器，光改运行中的环境变量不生效；而且只有这三个变量会被替换，其他 KANEO_* 变量不会进前端。这是配置排障时的高频坑。

2.4 请求链路总览

一次典型请求的链路是：浏览器 → 生产镜像内 nginx（5173）→ API（Hono，容器内 1337）→ Drizzle ORM → PostgreSQL。实时更新走 WebSocket：单实例用内存广播，多实例需要 Redis Pub/Sub 才能跨进程转发。附件走"API 签发预签名 URL → 浏览器直传 S3 → 浏览器再直读"的路径，所以文档特别强调 S3 端点必须同时能被 API 和浏览器访问到，只给容器内部可达的地址会导致上传按钮无限转圈。

三、核心特性

以下特性均来自 v2.48.0 的 README、官方文档目录和源码包结构，未做功能想象的扩写。

3.1 视图与工作方式

看板的列（column）是项目级可自定义的，不是写死的"待办/进行中/完成"三列。这一点对流程不标准的团队很关键：可以直接按"需求评审 → 开发 → 测试 → 预发 → 上线"建列。

3.2 任务与协作

任务（task）是 Kaneo 的核心对象，围绕它有一整套上下文能力：

• 富文本描述、附件、子任务、任务依赖；
• 标签（label）、优先级、截止日期、负责人；
• 评论与活动记录（activity）；
• 时间跟踪（time tracking）；
• 自定义字段（custom fields），含单选/多选的选项退役机制（v2.48.0 新增"隐藏已退役选项"）；
• 重复任务：任务完成后按规则重新生成（v2.48.0 新特性）。

工作区（workspace）是最高一级组织单位，下面是多个项目（project）。一个工作区可以邀请成员、分配自定义角色；项目可以设置公开视图（public project views），把看板以只读形式分享给外部。

3.3 权限模型

Kaneo 的权限分三层：实例级、工作区级、项目级。源码里有独立的 packages/permissions 包，说明权限判断被抽成了可测试的模块，而不是散落在路由里。v2.47.1 专门修复了"作用域 API Key 与自定义工作区角色"的校验漏洞，说明 API Key 是带作用域（scope）的，可以限制到具体能力而不是全权令牌。

3.4 通知与集成

• 站内通知；
• 邮件通知（需 SMTP）；
• ntfy、Gotify 推送；
• 个人 Webhook；
• 项目 Webhook（含提醒调度器 scheduler/project-webhook-reminders.ts）；
• GitHub / Gitea 集成：仓库活动可触发任务状态流转（"rules that move tasks when repository activity changes"）；
• 聊天工具集成（README 未点名具体产品，文档站内有对应章节）。

⚠️ 安全默认值：面向私网的 Webhook、ntfy、Gotify、自建 Gitea/GitLab 以及导入源，默认被 SSRF 防护拦截，需要显式设置 KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS=true 才放行。只在可信内网开启，别在公网实例上顺手打开。

3.5 开放接口：REST、CLI、MCP

Kaneo 的接口形态是 REST + OpenAPI，不是 tRPC。README 直接写 "a REST API"，API 依赖里有 @hono/zod-openapi，apps/api/package.json 还提供 openapi:export 脚本（tsx scripts/export-openapi.ts），文档站有 /docs/api-reference/introduction。这意味着你可以用任意 HTTP 客户端、任意语言调用，也能直接导入 OpenAPI 规范生成 SDK。

在此基础上还有两个客户端形态：

• packages/cli：官方命令行客户端 kaneo-cli；
• packages/mcp：官方 MCP Server（npm 包 @kaneo/mcp，2026-10-25 发布 0.1.14），让 AI 助手能读写任务。

MCP 的设备授权默认放行 kaneo-cli 和 kaneo-mcp 两个 client ID，不需要额外配置；要接自研客户端才需要改 DEVICE_AUTH_CLIENT_IDS。

3.6 迁移导入

内置导入器支持 Trello、PLANKA、Plane 以及 Kaneo 自身（用于实例间搬迁）。Trello 导入需要 Power-Up API Key（TRELLO_API_KEY）才能显示一键授权按钮；不配也能用，但要手动贴 Key。从 Plane 迁过来这条路径对正在评估"Plane → Kaneo"的团队比较实用——同批已有 Plane 专栏，本文只做能力对比，不展开迁移步骤。

四、部署形态与资源基线

官方明确把 Docker Compose 作为自托管维护路径：仓库根目录有 compose.yml、compose.local.yml、compose.coolify.yml，另有 Helm Chart 目录 charts/。compose.yml 的结构很简单，两个服务：

注意官方 compose 没有 name: 字段，也没有给 Postgres 映射宿主端口，这是刻意的：默认不把数据库暴露到宿主网络。生产部署时建议自行加 name:、固定镜像 tag、把 Postgres 放到独立网络，并补齐备份。

资源基线方面，源码里没有官方最低配置表，但可以从构建与运行依赖推断，并在后续篇目实测：API 是单进程 Node 服务，前端是静态资源，PostgreSQL 16 是唯一重负载组件。对 10–50 人团队，2 vCPU / 4 GB 内存的云主机足够；百人以上或附件量大时，瓶颈通常先出现在 PostgreSQL 和对象存储，而不是 Node 进程。

4.1 与"裸机安装"的关系

Kaneo 支持裸机跑（pnpm install + pnpm dev），但那条路要求 Node.js 24.11+ 或 26+、pnpm 10.32.1、本地 PostgreSQL，且要分别启动 API（1337）与前端（5173），生产还要自己配反向代理和进程守护。对长期运维，官方镜像 + Compose 明显更省事；裸机路线适合内网离线环境或需要改源码的团队。两种路线在本专栏各有专篇。

4.2 版本与 Node 版本约束

根 package.json 的 engines 字段是硬约束：

"engines": {
  "node": "^24.11.0 || >=26.0.0"
}

也就是说，Node 20 或 22 无法满足 v2.48.0 的官方要求。这一点与"Node 20+ 即可"的常见印象不同，是本次实查纠正的关键事实之一。若用旧 Node 强行安装，pnpm 会在 engine-strict 开启时直接失败；即便绕过，TypeScript 7 + Vite 新版本的工具链也可能在运行期报语法/API 不兼容。裸机安装请直接上 Node 24 LTS 线。

五、与同类工具的对比

对比对象选同类的五款：Plane、OpenProject、Leantime、Vikunja、Taiga。数据取自各项目 GitHub 仓库 2026-10-27 的实查结果，能力维度取自各自 README 与官方文档，未做"谁更好"的主观排名。

5.1 逐项解读

对 Plane：Plane 是当前这个赛道体量最大的开源项目（61.5k star），功能覆盖任务、冲刺、文档、Triage，生态和社区都更成熟，代价是组件多、资源占用高、升级面更大。Kaneo 的优势是部署极简（两个容器、一个端口）和 MIT 许可（Plane 是 AGPL-3.0，商用二次分发时约束更强）。如果只需要看板和任务、不需要内置 Wiki 和冲刺报告，Kaneo 的运维成本明显更低。

对 OpenProject：OpenProject 是 GPL-3.0 的企业级套件，强在预算、成本、基线、会议、Wiki、甘特依赖，适合有 PMO 和正式流程的组织。它的 Ruby 栈与多容器部署对运维要求更高，上手也更重。Kaneo 不是它的替代品，而是"只要任务协作"时的轻量选择。

对 Leantime：Leantime 用 PHP，面向"非项目经理"的人群，理念是降低项目管理门槛，含目标、想法板、时间记录。两者定位接近（都强调易用），差别在技术栈与扩展性：Leantime 的 PHP 生态适合已有 LNMP 运维体系的团队，Kaneo 的 TypeScript 全栈更适合前端/Node 团队二次开发。

对 Vikunja：Vikunja 是 Go 单二进制，部署最轻，许可证 AGPL-3.0，擅长个人与小队任务清单，看板和甘特是近年补齐的能力。它有"单二进制"的天然优势，但在工作区/角色/自定义字段/集成这些"团队协作深度"上不如 Kaneo。要极致轻量选 Vikunja，要团队协作深度选 Kaneo。

对 Taiga：Taiga 是敏捷（Scrum/看板）专用工具，流程固化程度高，Python/Django 栈，社区活跃度低于巅峰期。它的优势是敏捷方法论贴合度高（用户故事、冲刺、Epic），劣势是流程不灵活、界面偏旧。Kaneo 更像"通用任务协作"，不自带冲刺燃尽图这类敏捷报表。

⚠️ 许可证提醒：Kaneo 是 MIT，可闭源分发、可商用改造；Plane、OpenProject、Leantime、Vikunja、Taiga 均为 AGPL/GPL 系，若你打算把修改版作为 SaaS 对外提供，需要先评估开源义务。这个差异在"自用"场景无所谓，在"产品化"场景是决定性的。

六、适用与不适用场景

6.1 适合

• 5–100 人的产品/研发团队：需要看板 + 任务上下文 + 权限，但不想维护一套 Jira 级别的系统；
• 已有 PostgreSQL 运维体系：Kaneo 只加一个 Node 容器，复用现有数据库即可；
• 需要自托管且在意许可：MIT 许可对二次开发和商业分发最友好；
• 想接 AI 助手：官方 MCP Server + REST API，能让 Claude/Cursor 之类直接读写任务；
• 内网/离线环境：单镜像 + 单数据库，离线导入镜像即可跑，不依赖外部 SaaS；
• 从 Trello / PLANKA / Plane 迁移：内置导入器，迁移路径现成。

6.2 不适合

• 需要正式项目组合管理（PPM）：预算、成本、资源池、基线、挣值分析——这些去 OpenProject；
• 需要内置文档/Wiki 作为主仓库：Kaneo 没有独立 Wiki/Pages，知识库要另配（如 Outline、Wiki.js）；
• 强敏捷方法论团队：需要用户故事、冲刺、燃尽图、Epic 层级——Taiga 更贴合；
• 只有 1–3 人的极简场景：Vikunja 单二进制更省事；
• 无 PostgreSQL 且不想引入：Kaneo 只支持 PostgreSQL，不接受 SQLite/MySQL；
• 需要成熟的中文社区与商业支持：Kaneo 文档以英文为主，商业支持依赖官方云与 Discord。

七、版本选择与升级建议

7.1 选哪个版本

• 生产环境：锁 v2.48.0（当前最新稳定版），或至少 v2.47.1（含安全修复）。不要用 latest 标签长期跑，Kaneo 两周五个版本的节奏会让"某天重启后界面变了"成为常态。
• 升级前：读 Release Notes，确认是否 "security release"；备份 PostgreSQL（pg_dump）与 .env；确认 AUTH_SECRET 不变（变了会导致所有会话失效）。
• 大版本跳跃：官方没有提供跨大版本自动迁移承诺，迁移由 API 启动时的 Drizzle 迁移执行；跨多个小版本升级建议逐个小版本走，先在看板/任务/附件三个路径做回归。

7.2 上手路径

对本专栏的读者，建议顺序是：先读本篇确认选型 → 按 Ubuntu 裸机篇理解各组件与目录 → 按 Compose 篇起一套可用的生产实例 → 用配置参数篇逐项调优（URL、认证、SMTP、S3）→ 最后用 REST API 篇做自动化和集成。

八、小结

Kaneo 2.48.0 是一个定位清晰的产品：用 TypeScript 全栈（Hono + React + Drizzle + PostgreSQL）把"看板 + 任务协作"做得足够快、足够轻，再用自定义字段、角色、REST API、CLI、MCP 把能力补到中型团队够用的程度。它不是 OpenProject 的替代品，也不是 Vikunja 的替代品，而是两者之间那个"部署不麻烦、功能不寒酸、许可证不设限"的选项。

选型判断可以浓缩成一句话：如果你要的是"一个能自己托管、运维成本低、还能被自动化和 AI 调用的任务看板"，Kaneo 值得进候选；如果你要的是预算/成本/敏捷报表这类正式项目管理能力，直接去看 OpenProject 或 Taiga，别在 Kaneo 上硬凑。