Kaneo 开发环境搭建与配置指南环境变量、Redis/SMTP 选项与常见故障排查【免费下载链接】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本文是 Kaneo 开源项目管理平台的开发环境搭建指南覆盖从零启动pnpm dev开发服务器、配置统一.env环境变量文件、按需启用 Redis/SMTP/SSO/云模式防护等全部关键环节并给出 CORS、数据库连接、认证、网络等高频问题的排查方案。读完本文你将掌握一套可直接复制运行的本机开发配置并理解这些配置在 apps/api 与 apps/web 源码中的实际生效机制为本地二次开发或自托管部署打下基础。快速开始两条命令跑起前后端Kaneo 使用 pnpm workspace Turborepo 管理多包仓库根 package.json 中pnpm dev即执行turbo devAPI 与 Web 应用在同一个开发命令下并行启动。环境要求为 Node.js 24.0.0、pnpm 10见根 package.json 的engines与packageManager字段。完整步骤如下安装依赖pnpm install创建根目录.env文件填入必需的环境变量下文详述。启动开发服务器pnpm dev该命令会同时启动两个服务API监听http://localhost:1337Web 应用监听http://localhost:5173两者均支持热重载hot reload修改源码后即时生效。TipWeb 应用默认会自动连接http://localhost:1337上的 API无需额外配置代理浏览器直接访问 http://localhost:5173 即可开始开发。apps/api/Dockerfile与apps/web/Dockerfile分别定义了 API 与 Web 的容器化构建方式本地若要按容器方式联调可参考 compose.local.yml包含 postgres、api、web 三个服务Postgres 通过 healthcheck 就绪后 API 才启动。统一环境变量文件一个.env管所有Kaneo 的环境变量采用单一.env文件策略文件位于仓库根目录由 API 和 Web 服务共享。根 package.json 中的dotenv-mono依赖负责加载这一份配置apps/api/src/utils/get-settings.ts 顶部调用config()完成加载后再按需读取各项变量。根目录 .gitignore 已把.env、.env.local、.env.development.local、.env.production.local等本地环境文件加入忽略列表因此配置不会被提交进仓库仓库根目录提供的 .env.sample 是官方配置模板包含每个变量的注释说明可直接复制为.env使用。必需环境变量开发模式下至少需要配置以下变量变量说明开发环境示例KANEO_CLIENT_URLWeb 应用的访问地址http://localhost:5173KANEO_API_URLAPI 服务的访问地址http://localhost:1337AUTH_SECRETJWT 令牌生成的密钥长度必须不少于 32 字符openssl rand -hex 32的输出DATABASE_URLPostgreSQL 连接字符串postgresql://kaneo:kaneolocalhost:5432/kaneoPOSTGRES_DBPostgreSQL 数据库名kaneoPOSTGRES_USERPostgreSQL 用户名kaneoPOSTGRES_PASSWORDPostgreSQL 密码自定义强密码DEVICE_AUTH_CLIENT_IDS设备流 OAuth 客户端白名单可选DEVICE_AUTH_CLIENT_IDS是可选变量用于声明允许通过设备授权流程device flow访问/api/auth/device/code的 OAuth 客户端 ID 列表多个 ID 用逗号分隔。未设置时Kaneo 隐式允许kaneo-cli与kaneo-mcp两个默认客户端因此使用官方 CLI 或 MCP 服务无需任何额外配置需要覆盖时当你需要额外信任其他客户端例如桌面应用时必须把默认 ID 一并写全例如kaneo-cli,kaneo-mcp,my-desktop-app。该变量的典型场景是引入 MCP/CLI 之外的第三方设备客户端时避免其请求被认证层拒绝。开发专用变量本地开发时Web 应用还支持以下两个变量VITE_API_URL—— 开发环境的 API 地址未设置时默认http://localhost:1337。这是 Vite 在构建/开发阶段读取的变量与生产镜像的运行时占位符替换机制不同见下文VITE_APP_URL—— 用于生成分享链接的应用地址可选。这两个变量按 Vite 的约定写在apps/web/.env中即可在pnpm dev时生效。可选变量总览Kaneo 支持大量可选配置涵盖认证、集成、通知、监控等多个维度SSO 登录提供商GitHub OAuthGITHUB_OAUTH_CLIENT_ID/GITHUB_OAUTH_CLIENT_SECRET旧版回退变量GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET、GoogleGOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET、DiscordDISCORD_CLIENT_ID/DISCORD_CLIENT_SECRET、Custom OAuth/OIDCCUSTOM_OAUTH_CLIENT_ID/CUSTOM_OAUTH_CLIENT_SECRET等。这些变量的启用与否会直接反映在 apps/api/src/utils/get-settings.ts 返回的公开配置中登录页据此决定渲染哪些登录方式GitHub 仓库集成GitHub App用于仓库同步与 Webhook与 GitHub SSO 相互独立GITHUB_APP_ID、GITHUB_PRIVATE_KEY、GITHUB_WEBHOOK_SECRET、可选GITHUB_APP_NAMESMTP 邮件服务见下文专节访问控制设置例如DISABLE_REGISTRATION、DISABLE_PASSWORD_REGISTRATION、DISABLE_WORKSPACE_CREATION、DISABLE_GUEST_ACCESS、DISABLE_LOGIN_FORM、DEMO_MODE等见 apps/api/src/utils/get-settings.tsCORS 配置CORS_ORIGINS见故障排查一节Redis用于 WebSocket 水平扩展见下文专节私有网络通知接收端KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONStrue允许 ntfy/Gotify/Webhook 等通知目标解析到私有地址默认关闭以防 SSRF 攻击内置 HTTP MCP 端点KANEO_INTERNAL_API_URL仅用于服务端向内置 HTTP MCP 端点发起的请求默认http://127.0.0.1:1337仅当 API 进程自身无法访问该地址时才需要覆盖。Redis 配置三种部署模式Kaneo 使用 Redis 实现 WebSocket 的 Pub/Sub 广播。任何 Redis 模式配置后多实例间的实时更新将通过 Redis Pub/Sub 中继全部不配置时则回退到进程内内存适配器仅限单实例参见 apps/api/src/ws/in-memory-broadcast-adapter.ts 与 apps/api/src/ws/redis-broadcast-adapter.ts。底层实现在 apps/api/src/redis/index.ts它依据变量解析出三种模式之一并创建 ioredis 客户端。模式一Standalone单机REDIS_URLredis://localhost:6379适合开发环境或单节点部署直接使用连接串。模式二Sentinel高可用自动故障转移REDIS_SENTINELSsentinel-1:26379,sentinel-2:26379,sentinel-3:26379 REDIS_SENTINEL_MASTER_NAMEmymaster # 默认 mymaster REDIS_SENTINEL_PASSWORD # Sentinel 节点密码与数据节点密码不同时可单独设置 REDIS_SENTINEL_TLSfalse # 是否对 Sentinel 连接启用 TLS默认 false模式三Cluster水平分片REDIS_CLUSTER_NODESnode-1:6379,node-2:6379,node-3:6379共享变量REDIS_PASSWORDREDIS_PASSWORD被 Sentinel 与 Cluster 两种模式共用用于数据节点的认证它不是 Sentinel 自身的认证密码后者应使用REDIS_SENTINEL_PASSWORD。优先级规则Note同一时间只能配置一种模式。若同时配置多个优先级为Cluster Sentinel Standalone。该优先级顺序与源码一致apps/api/src/redis/index.ts 中的resolveRedisMode()先检查REDIS_CLUSTER_NODES再检查REDIS_SENTINELS最后才回退到REDIS_URL若三者均未设置则抛出异常由上层回退到内存适配器。节点列表的解析由parseNodeList()完成支持host:port、IPv6 括号写法如[::1]:6379以及缺省端口Sentinel 默认 26379、Cluster 默认 6379并有对应单元测试 tests/api/redis/redis-config.test.ts 与 tests/api/redis/redis-priority.test.ts 覆盖。SMTP 配置邮件发送SMTP 用于发送工作区邀请、魔法链接magic link等邮件涉及变量变量说明默认值SMTP_HOSTSMTP 服务器主机名—SMTP_PORTSMTP 服务器端口—SMTP_USERSMTP 用户名—SMTP_PASSWORDSMTP 密码—SMTP_FROM发件人地址—SMTP_SECURE使用 TLStrue设为false关闭SMTP_REQUIRE_TLS要求 TLSfalse设为true开启SMTP_IGNORE_TLS忽略 TLS 证书错误false自签名证书时设trueNote若 SMTP 服务器使用自签名或无效 TLS 证书设置SMTP_IGNORE_TLStrue可跳过证书校验。SMTP 是否配置成功会通过isSmtpConfigured()见 apps/api/src/utils/get-settings.ts暴露到公开配置中登录页据此决定是否展示邮箱验证码登录。配置 SMTP 后登录默认使用邮箱验证码如需改回邮箱/密码登录设置DISABLE_EMAIL_OTP_SIGN_INtrue工作区邀请邮件仍走 SMTP。云模式滥用防护Cloud-mode abuse mitigations该组配置面向托管的多租户实例自托管实例可保持不设置KANEO_CLOUDtrue启用云专属保护拦截一次性邮箱注册、强制执行 Cloudflare Turnstile 人机验证、禁止访客账号发送工作区邀请并收紧/sign-up/email与/organization/invite-member的限流TURNSTILE_SECRET_KEY—— Cloudflare Turnstile 密钥部署在API 容器用于服务端校验不设置则跳过验证KANEO_TURNSTILE_SITE_KEY—— Turnstile 站点密钥部署在web 容器。生产 Web 镜像会把字面占位符KANEO_TURNSTILE_SITE_KEY烧进 bundle容器启动时由 apps/web/env.sh 用运行时值替换VITE_TURNSTILE_SITE_KEY——仅本地开发用写在apps/web/.env中由 Vite 在构建/开发时读取不用于生产镜像。运行时的占位符替换机制值得展开说明生产 Web 镜像的 JS/CSS 产物中预置了KANEO_*字面量占位符容器启动时 apps/web/env.sh 会遍历/usr/share/nginx/html下包含该字面量的文件并用实际环境变量值替换同时顺带生成 MCP OAuth 的发现配置/.well-known下的resource与authorization_serversJSON。若KANEO_TURNSTILE_SITE_KEY未设置脚本还会把残留的引号占位符清空为空字符串避免前端把它当成真值而破坏自托管注册流程。Sentry错误监控全部可选Sentry 集成为完全可选不设置任何相关变量即为零遥测SENTRY_DSN—— API 的 Sentry DSN不设置则 Sentry SDK 永不初始化SENTRY_ENVIRONMENT—— API 事件的环境标签默认取NODE_ENVSENTRY_TRACES_SAMPLE_RATE—— API 性能追踪采样率取值0–1默认0关闭追踪KANEO_SENTRY_DSN——web 容器的 Sentry DSN浏览器错误、追踪、会话回放与KANEO_TURNSTILE_SITE_KEY一样走运行时占位符替换机制VITE_SENTRY_DSN——仅本地开发写在apps/web/.env中。完整的环境变量清单与更细的配置说明可在仓库文档 docs/core/installation/environment-variables.mdx 中查阅。常见问题排查CORS 错误症状浏览器控制台报 Failed to fetchAPI 请求出现网络错误提示 Access to fetch at ... from origin ... has been blocked by CORS policy解决方案核对 URL 配置确保KANEO_API_URL与 API 服务地址一致、KANEO_CLIENT_URL与 Web 应用地址一致开发环境还可在.env中设置VITE_API_URL。配置 CORS 来源在.env中把前端地址加入CORS_ORIGINSCORS_ORIGINShttp://localhost:5173,https://yourdomain.com开发环境可将CORS_ORIGINS留空以允许所有来源。注意CORS_ORIGINS应与KANEO_CLIENT_URL保持一致否则可能影响认证流程。检查协议一致性前端与 API 应使用相同协议http/https开发环境不要混用。验证服务可达用curl http://localhost:1337/config测试 API 是否可访问该端点即 apps/api/src/config/index.ts 公开的实例配置接口并确认服务监听端口正确。数据库连接问题症状报 Database connection failedAPI 服务无法启动解决方案检查 PostgreSQL确认服务在运行、数据库存在、凭据正确可用psql $DATABASE_URL直接测试连接。修正DATABASE_URL检查连接字符串格式以及用户名、密码、主机、端口、数据库名。主机名要与 API 运行位置匹配API 容器与 Postgres 服务在同一个 Docker Compose 网络内时用postgresAPI 直接跑在宿主机上时用localhost若看到getaddrinfo EAI_AGAIN postgres说明 API 在错误的网络上下文里解析 Compose 主机名。使用正确的配置模式宿主原生开发优先显式配置DATABASE_URL若用POSTGRES_*派生连接串API 跑在宿主机时应设POSTGRES_HOSTlocalhost仅设置POSTGRES_DB和POSTGRES_USER不会切换到派生连接模式。源码层面的依据apps/api/src/database/resolve-database-url.ts 的解析顺序是优先DATABASE_URL否则当POSTGRES_PASSWORD、POSTGRES_HOST或POSTGRES_PORT任一存在即getDerivationSignal()为真时从POSTGRES_*拼接连接串默认用户名kaneo、主机postgres、端口5432、库名kaneo且派生模式下POSTGRES_PASSWORD必填两者都缺失时回退到本地兜底串postgresql://localhost:5432/kaneo。对应的单元测试见 tests/api/database/resolve-database-url.test.ts。认证问题症状报 Authentication failed用户无法登录解决方案检查认证配置确认.env中已设置AUTH_SECRET生产环境务必使用强随机密钥可用openssl rand -hex 32生成。注意若AUTH_SECRET未设置API 启动时会随机生成一个临时密钥重启后所有会话失效见 .env.sample 注释。核对KANEO_CLIENT_URL与KANEO_API_URL是否正确配置。清理浏览器数据清除 Cookie 与 localStorage或改用无痕/隐私模式重试。网络错误症状出现 Network errorAPI 请求超时解决方案检查服务状态确认 API 服务在运行并查看服务日志中的错误。检查防火墙/代理确保端口未被屏蔽确认代理设置未干扰请求。核对 URL用 curl 或浏览器逐一验证所有 URL 可访问。开发环境 vs 生产环境维度开发环境生产环境协议前后端均用http://localhost前后端均用 HTTPSCORS_ORIGINS留空允许所有来源或与本机 URL 一致必须显式设置且应与KANEO_CLIENT_URL匹配AUTH_SECRET可用简单密钥必须使用强唯一随机密钥数据库本地 PostgreSQL配置正式的数据库凭据关键 URLWeb 使用VITE_API_URL默认http://localhost:1337KANEO_CLIENT_URL与KANEO_API_URL设为生产地址获取进一步帮助如果问题仍未解决可按以下顺序自查查看浏览器控制台的详细报错信息审查 API 服务日志逐一核对所有环境变量是否设置正确确认 PostgreSQL、API、前端等所有服务均在运行查阅仓库内更完整的安装与部署文档docs/core/installation含 环境变量说明、Docker Compose 安装、服务启动以及 部署指南。环境变量与配置以仓库实际代码和 .env.sample 模板为准在升级版本或迁移部署环境后建议重新核对一遍变量清单尤其是新增的可选能力Redis、SMTP、Turnstile、Sentry 等所依赖的变量是否齐备。【免费下载链接】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），仅供参考