Kaneo 自托管部署与实践指南从 Docker Compose、Coolify 到 Kubernetes 的完整安装、配置与开发流程【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/appKaneo 是一个开源的轻量级项目管理平台主打“更少即是更多”的设计理念界面简洁、聚焦任务本身支持自托管与宽松的 MIT 开源许可。本文基于仓库 README.md 及配套源码、配置文件系统讲解 Kaneo 的多种部署方式drim 一键部署、Docker Compose、Coolify、Helm/Kubernetes、环境变量配置原理、开发环境搭建、内置 MCP Server 能力与常见故障排查帮助你根据自己的基础设施选型并顺利落地一套可长期运行的自托管项目管理系统。Kaneo 项目概览理念与仓库结构Kaneo 诞生的出发点很直接市面上的项目管理工具并非功能不够而是功能过剩——过多的通知、多余的按钮、复杂的流程反而把团队从“打造好产品”这件事上拉开。Kaneo 坚持“工具应当隐形”其核心差异点如下见 README.md简洁界面聚焦你的工作本身而不是工具本身可自托管数据始终掌握在自己手中注重性能对运行效率有明确追求开放源码采用宽松的 MIT 许可证见 LICENSE。从仓库结构看这是一个基于 pnpm workspace 的 monorepopnpm-workspace.yaml、package.json主要模块包括目录作用apps/api后端 API 服务Hono Drizzle ORM PostgreSQL监听 1337 端口apps/webWeb 前端Vite React监听 5173 端口packages/email邮件模板与 SMTP 发送封装packages/permissions权限模型与判断逻辑packages/libs共享工具库Hono 封装、API URL 解析等packages/mcp官方 MCP Server 客户端封装charts/kaneoKubernetes Helm Chartcompose.yml/compose.local.yml/compose.coolify.yml三种场景的 Docker Compose 编排根目录的 package.json 通过 turbo 统一管理构建与测试pnpm build、pnpm dev、pnpm test、pnpm typecheck等命令会递归执行到各个子包。部署路径总览三种主流方式怎么选Kaneo 提供了从“零配置”到“完全掌控”的多条部署路径均以仓库 README.md 为准drim 一键部署适合追求省心、想要自动 HTTPS 与数据库初始化的场景Docker Compose 快速启动适合大多数自托管场景一条命令拉起单容器 Kaneo PostgreSQLCoolify 平台部署适合已经使用 Coolify 作为 PaaS 的用户Helm Chart 部署到 Kubernetes适合已有 K8s 集群、需要生产级配置Ingress/Gateway API、HPA、Secret 管理的团队源码开发模式面向想要二次开发或贡献代码的开发者。方式一使用 drim 一键部署对于希望“开箱即用”的部署官方提供 drim CLI 工具自动完成 HTTPS、数据库初始化与全部服务配置curl -fsSL https://assets.kaneo.app/install.sh | sh drim setup执行完上述两条命令后Kaneo 实例即可运行。该方式尤其适合快速上线或需要“开箱即用”的生产环境。方式二Docker Compose 快速启动推荐自托管首选Docker Compose 是最快的试用与常规自托管方式。仓库 README.md 给出的编排将 Kaneo 与 PostgreSQL 组合在一起Kaneo 使用一个整合镜像ghcr.io/usekaneo/kaneo:latestAPI Web 前端 nginx 反向代理打包于同一容器services: postgres: image: postgres:16-alpine env_file: - .env ports: - 5432:5432 volumes: - postgres_data:/var/lib/postgresql/data restart: unless-stopped healthcheck: test: [CMD-SHELL, pg_isready -U kaneo -d kaneo] interval: 10s timeout: 5s retries: 5 kaneo: image: ghcr.io/usekaneo/kaneo:latest ports: - 5173:5173 env_file: - .env depends_on: postgres: condition: service_healthy restart: unless-stopped volumes: postgres_data:启动步骤将上述内容保存为compose.yml复制.env.sample为.env仓库根目录已提供 .env.sample编辑.env取消注释KANEO_CLIENT_URLhttp://localhost:5173并设置POSTGRES_PASSWORD你的密码AUTH_SECRETopenssl rand -hex 32 的输出执行docker compose up -d然后访问 http://localhost:5173。注意在 Docker Compose 网络内Kaneo 容器通过服务名postgres访问数据库如果 API 跑在宿主机而非 Compose 网络内则应使用localhost或显式设置DATABASE_URL。整合镜像内部的启动逻辑源码级解析理解整合镜像的行为对排查问题很有帮助其启动入口为 deploy/kaneo-entrypoint.sh自动派生KANEO_API_URL若未显式设置KANEO_API_URL则从KANEO_CLIENT_URL推导为${KANEO_CLIENT_URL}/api自动派生DATABASE_URL若未显式设置DATABASE_URL则要求必须提供POSTGRES_PASSWORD并用POSTGRES_USER、POSTGRES_HOST默认postgres、POSTGRES_PORT默认5432、POSTGRES_DB默认kaneo拼接连接串用户名与密码会做 URL 编码若DATABASE_URL和POSTGRES_PASSWORD都未设置则直接报错退出fail-fast自动生成AUTH_SECRET若未设置会为本次会话随机生成一个 32 字节 hex 密钥并打印警告——注意这会导致重启后会话失效生产环境务必显式设置并持久化依次启动 API 进程监听 1337与 nginx监听 5173并通过http://127.0.0.1:1337/api/health健康检查等待 API 就绪镜像内同时内置了 Dockerfile.kaneo 声明的容器级 HEALTHCHECK同样探测/api/health。与之对应仓库源码层面还有一套数据库连接解析逻辑 apps/api/src/database/resolve-database-url.ts解析优先级为DATABASE_URL显式连接串 由POSTGRES_PASSWORD/POSTGRES_HOST/POSTGRES_PORT触发的派生模式 兜底的postgresql://localhost:5432/kaneo。这里有一个关键细节仅设置POSTGRES_DB和POSTGRES_USER不会开启派生模式.env.sample 中也有同样说明必须存在密码或显式 host/port 才会触发派生。启动阶段还会经过 apps/api/src/database/prepare-database-startup.ts 完成“配置解析 → 等待数据库就绪 → 执行启动迁移drizzle 迁移”三步流程任一环节失败都会给出包含 host/port/database 来源的明确报错。方式三在 Coolify 上部署仓库自带针对 Coolify 优化过的编排文件 compose.coolify.yml。在 Coolify 中的配置要点如下创建Public Repository资源指向https://github.com/usekaneo/kaneo选择Docker Compose构建包Base Directory 为/Compose Location 为compose.coolify.yml给kaneo服务分配域名格式为https://your-domain.com:5173端口仅用于让 Coolify 知道流量路由到哪个容器端口访问者仍使用正常 HTTPS 域名设置KANEO_CLIENT_URL你的公网地址不带:5173AUTH_SECRET与数据库密码由 Coolify 的 magic variables 自动生成无需手工填写不要设置KANEO_API_URL入口脚本会从KANEO_CLIENT_URL自动推导公网地址 /api若误设成localhost会导致浏览器端 API 调用失败如需固定版本可通过KANEO_IMAGE_TAG指定发布 tag镜像默认跟随 latest。从 compose.coolify.yml 可以看到postgres服务通过SERVICE_PASSWORD_POSTGRES接收自动生成的密码kaneo服务则通过SERVICE_HEX_64_KANEO接收 64 位 hex 的AUTH_SECRET并共享同一个POSTGRES_PASSWORDkaneo服务的健康检查使用wget ... http://127.0.0.1:5173/api/health并预留了 60 秒的start_period数据库迁移可能在启动阶段耗时。方式四Kubernetes 部署Helm Chart对于 K8s 集群仓库在 charts/kaneo/README.md 提供了完整 Helm Chart 文档部署 Kaneo 的 API、Web 前端与 PostgreSQL可选并支持 Ingress 或 Gateway API。快速安装helm install kaneo oci://ghcr.io/usekaneo/charts/kaneo \ --namespace kaneo \ --create-namespace # 本地访问 kubectl port-forward svc/kaneo-kaneo 5173:5173 -n kaneo生产环境 Ingresshelm install kaneo oci://ghcr.io/usekaneo/charts/kaneo \ --namespace kaneo \ --create-namespace \ --set ingress.enabledtrue \ --set ingress.classNamenginx \ --set ingress.hosts[0].hostpm.yourcompany.com生产环境 Gateway API若集群已部署 Gateway API CRD 并配置好Gatewayhelm install kaneo oci://ghcr.io/usekaneo/charts/kaneo \ --namespace kaneo \ --create-namespace \ --set gateway.enabledtrue \ --set gateway.parentRefs[0].namemain-gateway \ --set gateway.parentRefs[0].namespacegateway-system \ --set gateway.parentRefs[0].sectionNamehttps \ --set gateway.hostnames[0]pm.yourcompany.comChart 关键参数速查参数默认值说明kaneo.image.repositoryghcr.io/usekaneo/kaneoKaneo 镜像仓库kaneo.service.port5173Kaneo 服务端口kaneo.env.clientUrl实例公网地址对应KANEO_CLIENT_URL。任何非 localhost 部署都必须设置否则登录会出现 “invalid origin” 错误注意键名大小写敏感clientUrl不是clientURLkaneo.env.authSecretBetter Auth 密钥最短 32 字符existingSecret启用时忽略kaneo.env.disableRegistrationfalse禁用新用户注册postgresql.enabledtrue是否随 Chart 部署 PostgreSQLpostgresql.persistence.size8GiPostgreSQL 数据卷大小autoscaling.enabledfalse是否启用 HPA启用后建议设置 CPU request否则无法计算 CPU 利用率ingress.enabledfalse是否创建 Ingressgateway.enabledfalse是否创建 Gateway API HTTPRouteHelm 部署的生产建议与常见坑外部数据库生产环境建议postgresql.enabledfalse改用托管 PostgreSQL配置kaneo.env.database.external.*若使用既有 Secret 存放连接串注意密码中的特殊字符需要百分号编码“invalid origin”登录失败通常是clientUrl未设置或拼写错误clientURL会被静默忽略Pod 崩溃循环CrashLoopBackOff多为外部数据库连接串错误密码错误、特殊字符未编码、host/port/库名不对可用kubectl get secret ... -o jsonpath{.data.postgres_uri} | base64 -d检查实际使用的连接串Pod Security Admission受限命名空间下需要设置podSecurityContext.runAsNonRoot: true、seccompProfile.type: RuntimeDefault以及securityContext.allowPrivilegeEscalation: false、capabilities.drop: [ALL]数据库备份可参考kubectl exec -it deployment/release-postgresql -- pg_dump -U kaneo_user kaneo backup.sql的方式定期备份。环境变量配置详解Kaneo 使用根目录单一.env文件API 与 Web 服务共享ENVIRONMENT_SETUP.md。完整变量清单见仓库根目录 .env.sample。必填变量变量说明KANEO_CLIENT_URLWeb 应用地址如http://localhost:5173KANEO_API_URLAPI 地址如http://localhost:1337整合镜像未设置时由KANEO_CLIENT_URL推导AUTH_SECRETJWT 签名密钥至少 32 字符生产环境用长随机串openssl rand -hex 32生成DATABASE_URLPostgreSQL 连接串显式模式也可改用POSTGRES_DB/POSTGRES_USER/POSTGRES_PASSWORD派生模式POSTGRES_DB/POSTGRES_USER/POSTGRES_PASSWORD数据库名、用户名、密码开发环境专属变量VITE_API_URL开发时 API 地址默认http://localhost:1337VITE_APP_URL用于生成链接的应用地址可选。设备流Device FlowOAuthDEVICE_AUTH_CLIENT_IDS可选。逗号分隔的允许设备流 OAuth 客户端 ID 列表。未设置时默认隐式允许kaneo-cli与kaneo-mcp因此 CLI 与 MCP 无需额外配置只有需要追加受信客户端如kaneo-cli,kaneo-mcp,my-desktop-app时才需要覆盖为完整列表且要包含仍需保留的默认 ID。Redis 配置WebSocket 水平扩展当配置了任一 Redis 模式时WebSocket 广播改用 Redis Pub/Sub支持多 API 实例实时同步未配置时回退到内存适配器仅限单实例。同一时间只能配置一种模式优先级为 Cluster Sentinel StandaloneENVIRONMENT_SETUP.mdStandaloneREDIS_URL如redis://localhost:6379SentinelREDIS_SENTINELS逗号分隔的 Sentinel 节点、REDIS_SENTINEL_MASTER_NAME默认mymaster、REDIS_SENTINEL_PASSWORD、REDIS_SENTINEL_TLS默认falseClusterREDIS_CLUSTER_NODES逗号分隔的种子节点共享REDIS_PASSWORD数据节点密码Sentinel 与 Cluster 模式共用源码层面apps/api/src/redis/index.ts 提供isRedisConfigured()判断WebSocket 适配器初始化逻辑在 apps/api/src/ws/index.ts 中根据该判断选择InMemoryBroadcastAdapter或RedisBroadcastAdapter并输出 WebSockets Initialized using: ...日志便于确认当前模式。SMTP 配置用于工作区邀请、验证码登录等邮件发送SMTP_HOST/SMTP_PORT服务器地址与端口SMTP_USER/SMTP_PASSWORD认证信息SMTP_FROM发件地址SMTP_SECURE使用 TLS默认trueSMTP_REQUIRE_TLS强制 TLS默认falseSMTP_IGNORE_TLS忽略 TLS 证书错误默认false自签名证书场景设为true当 SMTP 配置后默认使用邮箱验证码登录设置DISABLE_EMAIL_OTP_SIGN_INtrue可切换为邮箱密码登录工作区邀请邮件仍走 SMTP。认证与 SSOGitHub SSOGITHUB_OAUTH_CLIENT_ID/GITHUB_OAUTH_CLIENT_SECRET旧版兼容变量GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRETGitHub 仓库集成与 SSO 独立GitHub App 模式GITHUB_APP_ID、GITHUB_PRIVATE_KEY、GITHUB_WEBHOOK_SECRET、可选GITHUB_APP_NAME还支持 Google、Discord、Custom OAuth/OIDC详见官方文档。云模式与反滥用仅托管多租户实例KANEO_CLOUDtrue开启一次性邮箱注册拦截、Turnstile 验证码强制、访客账号邀请限制、注册与邀请接口的收紧限流。自托管实例无需设置TURNSTILE_SECRET_KEYCloudflare Turnstile 服务端校验密钥API 容器未设置时跳过验证码KANEO_TURNSTILE_SITE_KEYTurnstile 站点密钥用于web 容器。生产镜像会把字面量占位符KANEO_TURNSTILE_SITE_KEY烘焙进前端产物容器启动时由 apps/web/env.sh 替换为运行时值若留空env.sh 会把占位符清空为避免自托管注册流程被误判开启验证码对应仓库 issue #1304 的修复VITE_TURNSTILE_SITE_KEY仅本地开发使用写入apps/web/.envVite 在构建/开发时读取。Sentry 错误监控全部可选SENTRY_DSNAPI 的 DSN未设置则 SDK 完全不初始化SENTRY_ENVIRONMENT环境标签默认取NODE_ENVSENTRY_TRACES_SAMPLE_RATE请求链路采样率0–1默认0关闭KANEO_SENTRY_DSNweb 容器 DSN浏览器错误、链路、会话回放与 Turnstile 同样的运行时占位符替换机制VITE_SENTRY_DSN本地开发用。Web 容器运行时替换机制整合镜像的前端部署在 nginx 中配置见 apps/web/nginx.kaneo.conf监听 5173将/api/反向代理到 1337并为 MCP OAuth 提供/.well-known/端点。由于是纯静态构建产物运行时变量依赖 apps/web/env.sh 在容器启动时对 JS/CSS 文件做字符串替换KANEO_API_URL、KANEO_CLIENT_URL及其余KANEO_前缀变量同时生成 MCP OAuth 的资源服务器与授权服务器发现 JSON。这也解释了为什么在 Coolify 上误把KANEO_API_URL设为localhost会直接破坏浏览器端 API 调用。开发环境搭建仓库提供了面向开发者的 ENVIRONMENT_SETUP.md核心流程如下# 克隆并安装依赖 git clone https://github.com/usekaneo/kaneo.git cd kaneo pnpm install # 在根目录创建 .env参考 .env.sample必填项见上文 # 详情见 ENVIRONMENT_SETUP.md # 启动开发服务器API 1337 Web 5173 pnpm dev开发模式要点API1337与 Web5173都会热重载Web 会自动连接http://localhost:1337本地开发数据库可直接用 Docker Compose 的postgres服务compose.local.yml 提供了 api/web/docs 三服务编排其中 docs 服务基于 mintlify 运行文档站点常用工程命令根 package.jsonpnpm buildturbo 构建、pnpm test、pnpm test:integration、pnpm lint、pnpm typecheckAPI 侧还提供db:generate、db:migrate、db:studio等 Drizzle 数据库脚本apps/api/package.json。内置 MCP Server让 AI 工具直接管理任务Kaneo 提供官方 MCPModel Context Protocol支持AI 工具如 Claude、Cursor 等 MCP 客户端可以直接操作任务、项目与标签每个实例内置 HTTP MCP 端点位于/api/mcp源码实现在 apps/api/src/mcp/index.ts同时提供 OAuth 授权端点/api/mcp/authorize、/api/mcp/token、/api/mcp/register并对外暴露/.well-known/oauth-protected-resource/api/mcp与/.well-known/oauth-authorization-server/api发现文档stdio 客户端使用 npm 上的官方包kaneo/mcp直接执行npx -y kaneo/mcp即可若 API 自身进程访问不到http://127.0.0.1:1337可通过KANEO_INTERNAL_API_URL覆盖内置 MCP 端点服务端请求所使用的 API 源默认http://127.0.0.1:1337。常见问题排查CORS 错误典型症状为浏览器控制台出现 “Failed to fetch” 或被 CORS 策略拦截。排查顺序ENVIRONMENT_SETUP.md核对KANEO_API_URL与 API 实际地址、KANEO_CLIENT_URL与前端地址一致设置CORS_ORIGINS逗号分隔如http://localhost:5173,https://yourdomain.com开发时可留空以允许所有来源。注意CORS_ORIGINS应与KANEO_CLIENT_URL保持一致以保证认证正常前后端协议保持一致不要混用 http/https验证 API 可达curl http://localhost:1337/config。数据库连接问题确认 PostgreSQL 运行中、库与凭据正确psql $DATABASE_URL注意连接串格式用户名、密码、host、端口、库名host 要与 API 运行位置匹配API 容器与 Postgres 在同一 Compose 网络内用postgresAPI 直接跑在宿主机上用localhost。若出现getaddrinfo EAI_AGAIN postgres说明 API 在错误的网络上下文解析 Compose 主机名宿主机原生开发优先使用显式DATABASE_URL若用POSTGRES_*派生宿主机上要设POSTGRES_HOSTlocalhost仅设POSTGRES_DB与POSTGRES_USER不会开启派生模式对应 apps/api/src/database/resolve-database-url.ts 的getDerivationSignal()逻辑。认证问题确认AUTH_SECRET已设置且生产环境足够强核对KANEO_CLIENT_URL与KANEO_API_URL清除浏览器 Cookie 与本地存储或尝试无痕模式。生产环境最佳实践综合 ENVIRONMENT_SETUP.md 与 charts/kaneo/README.md 的建议前后端一律启用 HTTPSCORS_ORIGINS显式配置并与KANEO_CLIENT_URL一致AUTH_SECRET使用强随机值并妥善保管K8s 中建议放入 Secret或使用kaneo.env.existingSecret引用既有 Secret数据库使用独立、安全的凭据K8s 场景建议外接托管 PostgreSQL 并定期备份为容器设置资源请求与限制防止资源耗尽若需限制注册设置kaneo.env.disableRegistration: true登录页将隐藏注册入口已有用户仍可登录多实例水平扩展时配置 Redis优先 Cluster其次 Sentinel最后 Standalone保持镜像与数据库定期更新。参与贡献与许可Kaneo 欢迎各类形式的贡献报告 Bug、提出功能建议、改进文档、提交代码等详见 CONTRIBUTING.md。项目采用 MIT 许可证LICENSE可自由使用与二次开发。总结Kaneo 以“少即是多”的产品哲学切入项目管理领域在部署层面则保持了充分的灵活性与工程化程度从 drim 一键部署、Docker Compose 单容器编排到 Coolify 平台与 Kubernetes Helm Chart 均有开箱即用的支持根目录统一的.env配置模型、镜像启动时的自动派生逻辑、Redis 多模式 WebSocket 扩展以及内置的 MCP Server使其既适合个人快速试用也具备生产级自托管的完整性。无论你选择哪条路径本文给出的配置参数、源码级原理与排查清单都能帮你少走弯路快速跑通并稳定运行自己的 Kaneo 实例。【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考