源码系统概览
文章正文
Kaneo 是一款 TypeScript 全栈开源项目管理工具,聚焦简洁协作与自部署。
项目以“少即是多”为设计理念,把项目、任务、看板、Backlog、Gantt、时间记录、GitHub 集成等能力整合到一个 monorepo 中。
整套源码采用 React + Hono + PostgreSQL 技术栈,前后端分离,提供完整 OpenAPI、Helm Chart 与 MCP 集成,适合二开做企业内网项目管理平台。
本资源为 gitcc 镜像,功能与 GitHub 原版 usekaneo/kaneo 保持一致,可直接本地构建或 Docker Compose 启动。
TL;DR:Kaneo 是一套面向小团队的开源项目管理源码,核心模块覆盖 Workspace / Project / Task / Column / Label / Time Entry / Notification,默认提供看板、Backlog、Gantt 视图,支持 GitHub Issue 同步、Webhook 自动化与 MCP 服务端,适合作为企业内部项目管理与任务协作系统的底座进行二次开发。
源码简介
Kaneo 源码遵循 MIT 协议,完整仓库在 GitHub usekaneo/kaneo 维护,当前 v2.9.x 主线以 TypeScript 重写,提供 API、Web、Site、Docs、Email、MCP、Permissions 等多个子包。
主应用为 apps/web(React 19 + Vite + TanStack Router + TipTap 富文本)与 apps/api(Hono + Drizzle ORM + better-auth + ioredis),数据库为 PostgreSQL 16,推荐使用 Docker Compose 或 Helm Chart 一键部署。
工程采用 pnpm workspace + turbo,代码量约 17M / 1349 个文件,数据库表 22 张,涵盖 activity、label、notification、project、session、task、time_entry、user、workspace、workspace_member、github_integration、account、verification、invitation、team_member、team、apikey、external_link、integration、column、workflow_rule 等。
仓库内还附带 Mintlify 文档站(apps/docs)、官方营销站(apps/site,Next.js 15)、本地 stdio MCP 服务(packages/mcp)、通用 Webhook 插件、GitHub App 集成、React Email 模板库,二开时可作为完整工程底座使用。
测试覆盖包括单元测试、单测、API 集成测试(用真实 PostgreSQL)与 Helm Chart 验证,默认开启 Biome 格式化、Husky commit hook、commitlint 规范,可直接作为企业研发模板。
适用场景
小团队敏捷协作:支持 5-30 人团队的项目立项、任务分配、看板流转与每日站会回顾。
个人任务管理:Workspace 模式让个人也可以独立组织多个项目,Backlog 视图用于需求池整理。
企业内部项目管理:支持自部署、角色权限、邀请审核、API Key 与 GitHub 集成,可作为研发团队任务协作平台。
产品 Demo 与教学:配套 Mintlify 文档站与 OpenAPI 接口文件,适合做项目管理类课程演示与原型。
功能亮点
Workspace / Project / Task 三级组织:每个 Workspace 包含多个 Project,Project 内通过 Column 自定义看板阶段。
看板 / Backlog / Gantt / 任务详情四视图:支持拖拽、过滤、排序、批量操作与富文本 TipTap 描述。
时间记录与活动流:Time Entry 统计工时,Activity 记录操作历史,Notification 推送实时提醒。
GitHub 集成与 Webhook:仓库绑定后可自动同步 Issue、PR 评论,Workflow Rule 触发看板列自动流转。
MCP 服务端:内置 /api/mcp HTTP 端点与 stdio CLI,可被 Claude Code、Cursor 等 AI 客户端调用,实现自然语言操作任务。
权限与角色:better-auth 鉴权 + Permissions 包,支持工作区角色、项目级 RBAC 与 API Key 速率限制。
技术架构与部署指南
技术栈与运行环境
前端:React 19 + Vite + TanStack Router + TanStack Query + Tailwind CSS v4 + Radix UI + dnd-kit + TipTap。
后端:Hono 4(Node 20+) + Drizzle ORM + better-auth + ioredis + croner + Sentry + hono-openapi。
数据库:PostgreSQL 16,使用 Drizzle Migration 管理 0000-0012 共 13 个 schema 变更文件。
辅助服务:Redis(会话与速率限制)、AWS S3(文件附件,通过 @aws-sdk/client-s3 预签名上传)、SMTP 邮件(React Email 模板)。
运行要求:Node.js 20.19+、pnpm 10.x、Docker 20.10+(生产推荐 Kubernetes 1.23+ 与 Helm 3.2+)。
同类方案对比
| 维度 | Kaneo | Leantime | OpenProject | Wekan |
|---|---|---|---|---|
| 技术栈 | React + Hono + PostgreSQL | PHP + Laravel | Ruby on Rails + Angular | Node.js + Meteor |
| 部署方式 | Docker / Helm | Docker | Docker / 自托管 | Docker / Snap |
| 看板 / Gantt | 原生支持 | 看板为主 | 完整支持 | 看板为主 |
| GitHub 集成 | 内置 | 插件 | 插件 | 无 |
| MCP / AI 接入 | 内置 MCP 端点 | 无 | 无 | 无 |
| 协议 | MIT | AGPL | GPL | MIT |
By the numbers:17M 源码体积 · 1349 个源文件 · 22 张数据表 · 13 次 schema 迁移 · 11 种 i18n 语言(en/de/el/es/fr/id/ko/mk/nl/zh-CN/ru)· v2.9.x 维护中。
安装与部署提示
推荐使用官方 Helm Chart 部署到 Kubernetes 集群,Chart 路径 charts/kaneo,支持 Ingress、Gateway API、HPA 与独立 PostgreSQL 子 Chart。
开发模式:克隆仓库后执行 pnpm install,复制 apps/api/.env.sample 与 apps/web/.env.sample,设置 DATABASE_URL、AUTH_SECRET、KANEO_CLIENT_URL,运行 pnpm dev 同时启动 API 与 Web。
Docker Compose 部署:从 compose.yml 启动 postgres + kaneo 容器,默认端口 5173,数据库 healthcheck 触发应用启动,生产环境务必修改 POSTGRES_PASSWORD 与 AUTH_SECRET。
数据库迁移:首次启动自动运行 drizzle-kit migrate,如需重置可手动删除 postgres_data 卷后重建,生产升级前请阅读 CHANGELOG.md 并备份。
截图与演示说明
以下截图来自 GitHub 原版 usekaneo/kaneo 仓库,均为无水印原图。
图为 Kaneo 看板主界面,顶部展示当前工作区与项目切换,Backlog 与 BOArd 两个 Tab 对应需求池与执行面板,右上角可在 Board 与 List 两种视图间切换。
图为亮色模式下的完整工作区,左侧栏显示 Overview、Projects、Members、Invitations 等导航,Projects 下可看到 Platform Core、Marketing Site、Docs Experience、GitHub Sync 等项目卡片,中央看板含 To Do、In Progress、In Review、Done 四列。
图为暗色模式,深色背景降低长时间盯屏幕的疲劳,左下角主题切换器可在亮/暗模式间一键切换,任务卡片支持拖拽、标签着色、优先级、负责人、截止日期。
图为 Dashboard 看板视图,顶部 Filter 提供 Priority / Assignee 等多条件过滤,看板列含任务计数、图标与展开操作,支持自定义列与工作流规则。
常见问题
问:Kaneo 与 GitHub 原版有何差异?
本资源为 gitcc 镜像,功能与 GitHub usekaneo/kaneo 主线一致,源码完整可构建,差异主要在仓库托管平台与同步时间。
问:是否支持中文界面?
i18n 包已包含 en-US / de-DE / el-GR / es-ES / fr-FR / id-ID / ko-KR / mk-MK / nl-NL 等多语种资源,中文翻译需要自行在 i18n/ 下补齐。
问:最低部署要求是什么?
2 核 4G 内存即可运行单实例 Demo,生产建议 4 核 8G 以上,PostgreSQL 16 与 Redis 建议独立部署并配置自动备份。
问:如何启用 GitHub 集成?
在 Project Settings → Integrations 中配置 GitHub App,填入 Installation ID,启用后 Issue / PR 评论会自动同步到任务详情,并可通过 Workflow Rule 触发看板列流转。
问:能否接入企业 SSO?
better-auth 支持 OAuth Provider,可在 apps/api/.env 中配置 IDP 客户端参数,Auth Secret 与回调地址需要在 Auth Provider 后台白名单登记。
安全风险提示
示例配置硬编码风险:charts/kaneo/README.md 中存在示例密码占位符,生产部署前必须替换为强随机字符串并通过 Secret 管理。
AUTH_SECRET 必须使用 openssl rand -hex 32 生成,不要复用示例值,否则会话签名可被预测。
API Key 启用速率限制:默认 24 小时 10 次调用,生产可根据负载调整,密钥泄露后立即在 Settings → API Keys 撤销。
MCP 端点风险:暴露 /api/mcp 时务必配置 DEVICE_AUTH_CLIENT_IDS 白名单,避免未授权客户端通过设备流获取 Token。
依赖升级:package.json pnpm overrides 已修复 esbuild / lodash / ws / next 等多个 CVE,升级前请保留 overrides 段,自行升级可能引入漏洞。
下载说明
本资源通过 gitcc 镜像分发,目录结构与 GitHub 原版 usekaneo/kaneo 一致,包含完整 apps / packages / charts / i18n 目录,可在本地直接 pnpm install 构建。
构建产物会输出到 apps/api/dist 与 apps/web/dist,部署到生产环境推荐使用预构建镜像 ghcr.io/usekaneo/kaneo:latest。
示例数据导入可执行 pnpm db:seed:user-data,需要提前配置 DATABASE_URL 与 POSTGRES_PASSWORD。
问题反馈与功能建议请前往 GitHub Issues 提交,中文用户可加入官方 Discord 社区获取帮助。
GitHub项目开源地址:https://github.com/usekaneo/kaneo
