Kaneo | 开源自托管的项目管理与看板工具

Kaneo 是一个开源、自托管的项目管理与看板工具，目标是让团队在工作区中管理项目、任务、标签和协作，而不是被复杂的流程面板牵着走。它提供 Board、List、Backlog 三种工作视图，支持 GitHub 双向同步，并为 Claude、Cursor 等 MCP 客户端提供官方接入方式。仓库采用 MIT 许可证；自托管意味着数据库、密钥、备份、域名和升级由部署者负责。

截至 2026 年 9 月 3 日核对，usekaneo/kaneo 的默认分支是 main，最新 Release 为 v2.22.0（2026 年 8 月 21 日发布），GitHub 页面显示约 8,920 个 stars 和 748 个 forks；仓库主要语言为 TypeScript，官网为 https://kaneo.app/。版本、统计数量和镜像标签会继续变化，正式部署前应以官方仓库、文档和 Release 页面为准。

Kaneo 的组成：Web、API 与 PostgreSQL

官方文档把 Kaneo 拆成三个核心组件：用 Hono 和 TypeScript 编写的 API、用 React 与 Tailwind CSS 编写的 Web 前端，以及保存业务数据的 PostgreSQL。官方 Compose 示例把 API 和 Web 合并到 ghcr.io/usekaneo/kaneo:latest 容器中，再用 postgres:16-alpine 提供数据库服务；postgres_data 卷负责保存数据库文件。

组件	主要职责	部署时要留意
Web	工作区、项目、Board/List/Backlog 和设置界面	`KANEO_CLIENT_URL` 要与浏览器访问地址一致
API	任务、项目、成员、标签、评论、集成和 MCP 请求	反向代理、CORS、认证密钥和 API 地址必须匹配
PostgreSQL	持久化工作区、项目、任务和权限等业务数据	设置强密码、持久化卷、备份和恢复演练

这套拆分解释了 Kaneo 的自托管边界：容器负责应用运行，数据库卷负责状态持久化，域名和 HTTPS 由部署平台或反向代理处理。删除容器并不一定会删除命名卷，但没有卷、备份或明确恢复流程时，升级和迁移仍然可能造成数据风险。

从工作区到项目：Board、List、Backlog 三种视图

第一次使用时，先创建一个工作区，再在工作区内建立项目。每个项目可以按执行场景切换视图：Board 适合把任务拖过不同状态列，List 适合密集扫描、排序和查找，Backlog 适合规划和梳理尚未进入执行流的工作。任务可以设置描述、负责人、优先级、截止日期和标签；Board 与 List 工具栏可按状态、优先级、负责人、截止日期和标签过滤。

官方功能指南建议先统一状态流、优先级和标签命名，再邀请团队成员。这样做的价值不在于增加流程，而是让同一项目中的“待办、进行中、已完成”等状态有稳定含义；如果团队更重视批量检查，也可以在 List 视图中快速发现逾期、未分配或描述不完整的任务。

Kaneo 官方看板项目管理界面 — Kaneo 官方仓库展示的看板界面，包含状态列、任务卡片、过滤条件和项目导航；这是产品界面截图，不是本文生成的示意图。来源：https://github.com/usekaneo/kaneo/blob/main/apps/site/public/images/hero.png

GitHub 双向同步和 MCP：把任务接到开发工具

GitHub App 负责仓库与任务同步

Kaneo 的 GitHub 集成不是简单粘贴一个个人访问令牌，而是通过 GitHub App 提供细粒度权限。它可以从 Kaneo 任务创建 GitHub issue，在 issue 编辑、关闭或打标签时同步任务，也能把 pull request 与任务关联。官方文档列出的自动状态转换包括：分支 push 将任务移到 in-progress，PR 打开移到 in-review，PR 合并移到 done。

创建 GitHub App 时，官方建议至少为 Issues 授予读写权限，为 Pull Requests、Metadata 和 Contents 授予读取权限，并订阅 Issues、Issue comments、Pull requests、Push 四类 webhook 事件。仓库权限、Webhook URL 和私钥都属于部署凭据，应该放进密钥管理或环境变量中，不能提交到代码库或公开日志。

MCP 提供两种传输方式

每个 Kaneo 实例都内置 HTTP MCP 端点 /api/mcp，客户端可以指向 https://your-kaneo-instance.com/api/mcp，首次连接时跳转到 Kaneo 登录并明确批准客户端。文档说明该端点使用 OAuth 2.1 + PKCE；现代请求支持无状态模式，较早客户端仍可使用有状态的初始化流程。

如果客户端需要 stdio 传输，可以使用官方 npm 包 @kaneo/mcp，运行 npx -y @kaneo/mcp 或调用其安装命令把服务注册到 Cursor、Claude Desktop 等客户端。stdio 路径要求 Node.js 24 或更新版本，并通过设备授权完成登录；HTTP 与 stdio 暴露的工具覆盖工作区、项目、任务、评论、标签、时间记录和搜索等对象。

部署路线：drim、Docker Compose、Coolify 与 Kubernetes

drim 一键部署

官方 README 将 drim 作为快速部署路径，它负责处理 HTTPS、数据库和服务配置：

curl -fsSL https://assets.kaneo.app/install.sh | sh && drim setup

这条命令会执行远程安装脚本。生产环境使用前应先审阅脚本来源、执行内容和目标服务器权限，并确认域名、备份和回滚策略。

Docker Compose 手动部署

想控制服务、端口和环境变量时，可以使用仓库中的 Compose 示例。最小配置包含 PostgreSQL 与 Kaneo 容器，数据库卷名为 postgres_data；启动命令为 docker compose up -d。

运行前先复制 .env.sample 为 .env，设置 KANEO_CLIENT_URL=http://localhost:5173、POSTGRES_DB=kaneo、POSTGRES_USER=kaneo、强密码形式的 POSTGRES_PASSWORD，并用 openssl rand -hex 32 生成至少 32 个字符的 AUTH_SECRET。启动后打开 http://localhost:5173；如果 API 运行在宿主机而不是 Compose 容器内，再按文档设置 DATABASE_URL 或数据库主机名。

Coolify 与 Kubernetes

仓库提供面向 Coolify 的 compose.coolify.yml，可从 Public Repository 创建 Docker Compose 资源，并为 Kaneo 服务绑定域名。Coolify 会生成数据库密码和 AUTH_SECRET；KANEO_API_URL 通常留空，让它从 KANEO_CLIENT_URL 推导。Kubernetes 用户可以使用仓库中的 Helm chart，并按照 chart 文档配置 TLS、持久化和生产参数。

文件上传、环境变量与安全边界

Kaneo 的任务描述和评论支持通过 S3 兼容对象存储上传私有文件。对象存储不是运行核心功能的必选项；不配置时，任务与评论中的上传功能不可用。官方文档推荐本地部署优先考虑 MinIO，也支持 AWS S3、Cloudflare R2 等兼容后端。API 会创建预签名上传 URL，文件桶不必公开暴露，反向代理和对象存储的 CORS 仍需按实际域名配置。

除了数据库和认证密钥，部署者还应根据实际需求决定是否启用 GitHub/Google/Discord SSO、SMTP、Redis、通知 Webhook 和访问控制开关。公开部署前至少应配置 HTTPS、强 AUTH_SECRET、强数据库密码、最小 GitHub App 权限和定期备份；不要把 GITHUB_PRIVATE_KEY、OAuth secret 或对象存储密钥写入前端代码、镜像层或截图。

v2.22.0 的维护信号

最新 Release v2.22.0 于 2026 年 8 月 21 日发布，变更记录包括站点博客与替代方案汇总、当标签不存在时 API 返回 404、CI 权限收紧以及发布流程文档更新。仓库在 2026 年 9 月初仍有新的提交活动，说明项目处于持续维护状态；但 ghcr.io/usekaneo/kaneo:latest 是浮动标签，需要可复现部署时应锁定明确版本或提交，并在升级前备份数据库、检查迁移和验证关键登录/集成功能。

MIT 许可与适用范围

Kaneo 根目录 LICENSE 使用 MIT License，允许在保留版权与许可证声明的前提下使用、修改和再分发。MIT 许可不替你取得 GitHub、邮件、对象存储或上游 OAuth 服务的使用权，也不保证自托管实例天然安全或高可用；第三方依赖和外部服务条款仍需单独核对。

Kaneo 适合希望掌握数据、需要轻量看板和列表工作流、或想把任务与 GitHub/MCP 接起来的小型团队和个人。它不适合被当作无需运维的 SaaS 替代品：你仍要负责 PostgreSQL 持久化、HTTPS、备份、升级、账号策略和 webhook 可达性。如果团队只需要临时个人待办，部署数据库和反向代理的成本可能超过工具本身带来的收益。