项目管理后端前端协同办公【免费下载链接】kanThe open source Trello alternative.项目地址https://gitcode.com/gh_mirrors/kan5/kan点击查看免费下载本文以 Kan 开源仓库一个基于 Next.js 与 tRPC 构建的开源 Trello 替代品的官方 README 为主线系统讲解如何用 Docker Compose 在自有服务器上完整部署 Kan逐项解读全部环境变量的作用与取值并演示如何通过内置 MCP Server 让 AI 客户端直接读写看板数据。读完本文你将掌握从零搭建生产环境、按需裁剪邮件 / S3 / 社交登录等可选能力以及用npx一行启动 AI 控制能力的完整实战路径。项目速览Kan 是一个开源的看板式项目管理工具定位为 Trello 的开源替代方案。它采用看板Board—列表List—卡片Card三层模型组织工作流支持工作区Workspace协作、成员邀请、标签过滤、评论与活动日志等功能。整个项目以 pnpm Turborepo 管理是一个包含 Web 应用、API 包、数据库层、邮件模板、MCP 服务器等多包仓库的 monorepo。核心功能特性README 明确列出的功能包括Board Visibility看板可见性控制谁能查看和编辑你的看板支持公开/私有等粒度配置Workspace Members工作区成员邀请成员加入工作区围绕团队协作管理项目Trello ImportsTrello 导入一键导入已有的 Trello 看板降低迁移成本Labels Filters标签与过滤器通过标签组织和快速筛选卡片Comments评论在卡片上讨论并与团队协作Activity Log活动日志记录所有卡片的变更历史提供详细的操作审计Templates模板通过可复用的自定义看板模板节省搭建时间Integrations集成即将推出计划连接更多常用工具。从源码结构看这些功能都有对应的实现支撑例如标签能力位于 packages/api/src/routers/label.ts导入能力位于 packages/api/src/routers/import.ts活动日志依赖数据库层的 packages/db/src/repository/cardActivity.repo.tsTrello 导入的认证逻辑位于 packages/api/src/utils/trello.ts。下图是 Kan 看板界面的实际截图仓库文档目录中的 hero 图技术栈Made With项目官方声明使用以下技术构建均为当前仓库 apps/web/package.json 中可验证的实际依赖技术用途Next.jsWeb 应用框架当前仓库锁定 Next.js 15.5.9tRPC端到端类型安全的 API 层Better Auth认证体系邮箱密码 OAuth/OIDCTailwind CSS样式与 UI 设计系统Drizzle ORMPostgreSQL 数据库访问与迁移React Email邮件模板渲染用 Docker Compose 自托管README 推荐的自托管方式是 Docker Compose它会一次性搭好 PostgreSQL 数据库并在 Web 服务启动前自动执行数据库迁移。仓库根目录提供了开箱即用的完整配置 docker-compose.yml该文件定义了migrate、web、postgres三个服务并支持通过CONTAINER_NAME、WEB_PORT等变量覆盖容器名与端口。第一步准备 .env 文件先创建.env文件并填入环境变量完整清单见下文“环境变量详解”模板可直接参考仓库根目录的 .env.examplecp .env.example .env至少需要配置以下三个必填项NEXT_PUBLIC_BASE_URLhttp://localhost:3000 BETTER_AUTH_SECRET随机 32 位以上字符串 POSTGRES_PASSWORD数据库密码其中BETTER_AUTH_SECRET可用如下命令生成随机值openssl rand -base64 26 | tr -dc a-zA-Z0-9 | head -c 32POSTGRES_PASSWORD仅在使用仓库提供的 compose 部署时需要因为 compose 中的 postgres 服务会用它初始化数据库账号kan。第二步使用 compose 配置可以直接使用仓库根目录的 docker-compose.yml核心结构如下完整版见仓库文件services: migrate: image: ghcr.io/kanbn/kan-migrate:latest container_name: ${CONTAINER_NAME:-kan-migrate} networks: - kan-network environment: - POSTGRES_URL${POSTGRES_URL} depends_on: postgres: condition: service_healthy restart: no web: image: ghcr.io/kanbn/kan:latest container_name: ${CONTAINER_NAME:-kan-web} ports: - ${WEB_PORT:-3000}:3000 networks: - kan-network env_file: - .env environment: - NEXT_PUBLIC_BASE_URL${NEXT_PUBLIC_BASE_URL} - BETTER_AUTH_SECRET${BETTER_AUTH_SECRET} - POSTGRES_URL${POSTGRES_URL} - NEXT_PUBLIC_ALLOW_CREDENTIALStrue depends_on: migrate: condition: service_completed_successfully restart: unless-stopped postgres: image: postgres:15 container_name: kan-db environment: - POSTGRES_DBkan_db - POSTGRES_USERkan - POSTGRES_PASSWORD${POSTGRES_PASSWORD} ports: - 5432:5432 volumes: - kan_postgres_data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U kan -d kan_db] interval: 5s timeout: 5s retries: 10 restart: unless-stopped networks: - kan-network networks: kan-network: volumes: kan_postgres_data:几个关键点值得注意迁移服务migrate只运行一次restart: no其 CMD 是npx drizzle-kit migrate由 apps/web/Dockerfile 中的migrate构建阶段封装迁移镜像只包含 packages/db/drizzle.config.ts、migrations 目录以及drizzle-kit、drizzle-orm、pg三个依赖web依赖migrate的成功退出condition: service_completed_successfully确保应用启动前数据库 schema 已就绪postgres 服务通过 healthcheck 门控pg_isready -U kan -d kan_db迁移服务会等待数据库真正可用仓库的完整 compose 还包含可选的build段落可直接docker compose build从源码构建镜像、S3_*、SMTP_*、OAuth 等全部可选环境变量的透传以及LOG_LEVEL、KAN_ADMIN_API_KEY等运维配置。第三步启动在项目根目录执行docker compose up -dmigrate服务会自动先执行数据库迁移然后web服务启动。应用默认运行在 http://localhost:3000可用WEB_PORT环境变量修改宿主端口。容器日常管理命令停止所有容器docker compose down查看全部日志docker compose logs -f查看指定服务日志docker compose logs -f web或docker compose logs -f migrate重启容器docker compose restart代码变更后重建并重启docker compose up -d --build环境变量详解README 提供了完整的官方环境变量表。结合 .env.example 与 docker-compose.yml下表按类别整理并补充了默认值、可选性说明变量说明是否必需示例POSTGRES_URLPostgreSQL 连接 URL使用外部数据库时必需postgres://user:passlocalhost:5432/dbREDIS_URLRedis 连接 URL使用限流时为可选redis://localhost:6379或redis://redis:6379DockerEMAIL_FROM发件人邮箱地址使用邮件功能时Kan hellomail.kan.bnSMTP_HOSTSMTP 服务器主机名使用邮件功能时smtp.resend.comSMTP_PORTSMTP 服务器端口使用邮件功能时465SMTP_USERSMTP 用户名/邮箱否resendSMTP_PASSWORDSMTP 密码/令牌否re_xxxxSMTP_SECURE是否使用安全 SMTP 连接未设置时默认为 true使用邮件功能时trueSMTP_REJECT_UNAUTHORIZED是否拒绝无效证书未设置时默认为 true使用邮件功能时falseNEXT_PUBLIC_DISABLE_EMAIL禁用全部邮件功能使用邮件功能时trueNEXT_PUBLIC_BASE_URL安装实例的基准 URL是http://localhost:3000NEXT_API_BODY_SIZE_LIMITAPI 请求体大小上限默认为 1mb否50mbBETTER_AUTH_ALLOWED_DOMAINSOIDC 登录允许的域名列表逗号分隔使用 OIDC/社交登录时example.com,subsidiary.comBETTER_AUTH_SECRET认证加密密钥是随机 32 字符字符串BETTER_AUTH_TRUSTED_ORIGINS允许的回调来源否http://localhost:3000,http://localhost:3001GOOGLE_CLIENT_IDGoogle OAuth 客户端 ID使用 Google 登录时xxx.apps.googleusercontent.comGOOGLE_CLIENT_SECRETGoogle OAuth 客户端密钥使用 Google 登录时xxxDISCORD_CLIENT_IDDiscord OAuth 客户端 ID使用 Discord 登录时xxxDISCORD_CLIENT_SECRETDiscord OAuth 客户端密钥使用 Discord 登录时xxxGITHUB_CLIENT_IDGitHub OAuth 客户端 ID使用 GitHub 登录时xxxGITHUB_CLIENT_SECRETGitHub OAuth 客户端密钥使用 GitHub 登录时xxxOIDC_CLIENT_ID通用 OIDC 客户端 ID使用 OIDC 登录时xxxOIDC_CLIENT_SECRET通用 OIDC 客户端密钥使用 OIDC 登录时xxxOIDC_DISCOVERY_URLOIDC discovery URL使用 OIDC 登录时https://auth.example.com/.well-known/openid-configurationTRELLO_APP_API_KEYTrello 应用 API Key使用 Trello 导入时xxxTRELLO_APP_API_SECRETTrello 应用 API 密钥使用 Trello 导入时xxxS3_REGIONS3 存储区域使用文件上传时WEURS3_ENDPOINTS3 端点 URL使用文件上传时https://xxx.r2.cloudflarestorage.comS3_ACCESS_KEY_IDS3 访问密钥使用文件上传时使用 IRSA 时可选xxxS3_SECRET_ACCESS_KEYS3 秘密密钥使用文件上传时使用 IRSA 时可选xxxS3_FORCE_PATH_STYLE对 S3 使用路径风格 URL使用文件上传时trueS3_AVATAR_UPLOAD_LIMIT头像最大字节数使用文件上传时20971522MBNEXT_PUBLIC_STORAGE_URL存储服务 URL使用文件上传时https://storage.kanbn.comNEXT_PUBLIC_STORAGE_DOMAIN存储域名使用文件上传时kanbn.comNEXT_PUBLIC_USE_VIRTUAL_HOSTED_URLS使用虚拟主机风格 URLbucket.domain.com使用文件上传时可选trueNEXT_PUBLIC_AVATAR_BUCKET_NAME头像 S3 桶名使用文件上传时avatarsNEXT_PUBLIC_ATTACHMENTS_BUCKET_NAME附件 S3 桶名使用文件上传时attachmentsNEXT_PUBLIC_ALLOW_CREDENTIALS允许邮箱密码登录使用认证时trueNEXT_PUBLIC_DISABLE_SIGN_UP禁用注册使用认证时falseNEXT_PUBLIC_WHITE_LABEL_HIDE_POWERED_BY在公开看板上隐藏“Powered by kan.bn”自托管白标白标场景trueKAN_ADMIN_API_KEY管理 API 密钥用于统计与管理端点使用管理/监控时your-secret-admin-keyLOG_LEVEL日志详细程度debug、info、warn、error开发环境默认 debug生产环境默认 info否info环境变量的源码级校验环境变量的合法性并非运行时才检查而是在应用启动阶段通过 apps/web/src/env.ts 使用t3-oss/env-nextjs与 zod 做 schema 校验服务端变量如BETTER_AUTH_SECRET被声明为z.string()必填缺失会导致应用拒绝启动BETTER_AUTH_TRUSTED_ORIGINS会被拆分成逗号分隔列表并逐个用z.string().url()校验非法 URL 会直接报错NEXT_PUBLIC_USE_VIRTUAL_HOSTED_URLS、NEXT_PUBLIC_ALLOW_CREDENTIALS、NEXT_PUBLIC_DISABLE_SIGN_UP、NEXT_PUBLIC_WHITE_LABEL_HIDE_POWERED_BY等布尔型变量会校验其值为true/falsePOSTGRES_URL与REDIS_URL为 URL 格式校验且允许为空字符串。几个容易踩坑的细节邮件端口与加密.env.example注释提示若 SMTP 端口为 587应将SMTP_SECURE显式设为falseSMTP_REJECT_UNAUTHORIZEDfalse可允许自签名证书S3 区域.env.example注明S3_REGION是 AWS S3 必需项如us-east-1多数 S3 兼容服务MinIO、Cloudflare R2、DigitalOcean Spaces会忽略它未设置时默认us-east-1Redis 缺省行为REDIS_URL未配置时限流功能会退化为进程内内存存储见 .env.example 注释Trello 变量命名README 表格写的是TRELLO_APP_API_SECRET而.env.example与 compose 中使用的是TRELLO_APP_SECRET配置时以.env.example为准容器外数据库如果使用外部 PostgreSQL则POSTGRES_PASSWORD不再需要只需正确配置POSTGRES_URL。本地开发环境要求根 package.json 声明了运行时要求Node.js 20.18.1pnpm 9.14.2项目使用 pnpm 9.14.2。步骤克隆仓库或 fork 后克隆自己的副本git clone https://gitcode.com/gh_mirrors/kan5/kan.git安装依赖pnpm install将.env.example复制为.env并配置环境变量cp .env.example .env执行数据库迁移pnpm db:migrate该命令实际执行cd packages/db pnpm migratepackage.json底层调用drizzle-kit migrate见 packages/db/package.json 的migrate脚本并借助dotenv -e ../../.env读取根目录的.env。启动开发服务器pnpm dev该命令通过turbo watch dev --continue以监视模式并行启动整个 monorepo 中所有包的开发任务。开发服务器启动前会自动先构建 MCP 包见 apps/web/package.json 中dev脚本先执行pnpm --filter kan/mcp build。常用开发命令命令用途pnpm dev启动全量开发环境监视模式pnpm dev:next只启动kan/web及其依赖的开发服务pnpm build构建整个 monorepopnpm lint/pnpm lint:fixESLint 检查 / 自动修复pnpm typecheck全仓库 TypeScript 类型检查pnpm test运行单元测试跳过 e2e 包pnpm test:e2e运行 Playwright 端到端测试pnpm db:studio打开 Drizzle Studio 可视化浏览数据库pnpm db:push直接将 schema 变更推送到数据库开发期用端到端测试在 packages/e2e 中按cloud与self-hosted两组组织覆盖看板生命周期、卡片详情、清单项、成员邀请、Trello 导入、Webhook、权限设置等大量场景可用于验证自托管实例的完整功能。MCP ServerAI 控制Kan 内置了一个遵循 Model Context Protocol 的 MCP 服务器任何兼容 MCP 的 AI 客户端Claude Desktop、Codex、Cursor、GitHub Copilot 等都可以用自然语言读取和控制你的 Kan 实例。一行启动无需安装MCP 服务器已发布为 npm 包无需克隆仓库或全局安装直接运行npx -y kan/mcp配置两个环境变量变量说明KAN_BASE_URL你的 Kan 实例地址KAN_API_TOKENAPI 令牌在Settings → API Keys页面生成然后在你的 AI 客户端的 MCP 配置中将该命令指向npx -y kan/mcp即可。按客户端Claude Desktop、Codex 等细分的具体配置方法以及示例提示词、完整工具参考与故障排查见官方 MCP Server 文档 apps/docs/integrations/mcp-server.mdx。源码实现原理从源码可以完整还原它的工作方式入口packages/mcp/src/index.ts 通过configFromEnv()读取KAN_BASE_URL与KAN_API_TOKEN创建客户端并连接StdioServerTransport标准输入输出传输这正是npx一行运行的原因配置校验packages/mcp/src/client.ts 中configFromEnv()在两个变量缺失时直接抛出异常并要求请求走{baseUrl}/api/v1{path}路径携带Authorization: Bearer {token}请求头工具注册packages/mcp/src/server.ts 注册了七大类工具——Workspace工作区、Board看板、List列表、Card卡片、Checklist清单、Label标签、Member成员每类工具的实现分别在 packages/mcp/src/tools/ 目录下并配有对应的 Vitest 测试如 packages/mcp/src/tools/board.test.ts、packages/mcp/src/tools/card.test.ts后端对接这些工具最终调用的是 Kan 自带的 OpenAPI REST 端点/api/v1/*由 apps/web/src/pages/api/v1/[...trpc].ts 承载——它基于trpc-to-openapi把 packages/api/src/root.ts 中定义的全部 tRPC 路由board、card、checklist、label、list、member、workspace 等自动转换成 REST 接口令牌鉴权REST 层的令牌校验位于 packages/api/src/utils/apiToken.ts同时支持Authorization: Bearer token与x-api-key请求头两种形式。API 令牌的管理页面Web 端的 API 令牌管理入口是Settings → API Keys对应页面实现位于 apps/web/src/pages/settings/api.tsx内部渲染 apps/web/src/views/settings/ApiSettings.tsx。运维与监控端点除了 MCP 之外自托管实例还可以直接通过 REST 端点做健康检查与统计健康检查GET /api/v1/health公开。实现见 packages/api/src/routers/health.ts会依次探测 PostgreSQL 连通性SELECT 1以及 S3 存储未配置 S3 时返回not_configured整体状态仅在数据库健康且存储可用或未配置时才返回ok实例统计GET /api/v1/stats管理端点。返回用户、工作区、看板、列表、卡片、评论、附件、活动日志、标签、清单等全量计数。它由adminProtectedProcedure保护要求请求头携带x-admin-api-key: KAN_ADMIN_API_KEY见 packages/api/src/trpc.ts 中的enforceUserIsAdmin中间件——这就是环境变量表中KAN_ADMIN_API_KEY的用途。REST 接口遵循 OpenAPI 规范完整的接口文档描述由 packages/api/src/openapi.ts 基于 tRPC 路由自动生成。参与贡献与许可证欢迎为项目提交贡献提交 Pull Request 前请先阅读 CONTRIBUTING.md。Kan 使用 AGPLv3 许可证全文见 LICENSE。这意味着你可以自由地自托管、修改和分发在遵守相应开源义务的前提下。结语从仓库 README 出发本文完整覆盖了 Kan 自托管的四条主线compose 三服务一键部署迁移先行 健康检查门控、43 项环境变量的逐项解读并借助 apps/web/src/env.ts 的 zod schema 说明启动期校验逻辑、本地开发工作流pnpm Turborepo Drizzle以及MCP 服务器让 AI 直接读写看板的能力。按本文步骤操作你可以在自有服务器上得到一套与官方一致的、可裁剪邮件与存储、可接入社交登录、可被 AI 客户端控制的完整看板系统。赞分享项目管理后端前端协同办公【免费下载链接】kanThe open source Trello alternative.项目地址https://gitcode.com/gh_mirrors/kan5/kan点击查看免费下载相关推荐NocoDB 自托管部署实战Docker、二进制与 Docker Compose 全解析附源码级环境变量剖析NocoDB 自托管部署实战Docker、二进制与 Docker Compose 全解析附源码级环境变量剖析 本文基于 NocoDB 仓库中的官方多语言数据库低代码后端前端如何把 Claude Code 的会话、代理与花费搬进桌面 GUIopcode 完整指南如何把 Claude Code 的会话、代理与花费搬进桌面 GUIopcode 完整指南 opcode 是一款开源的 Claude Code GUI 桌面应用桌面应用AI 应用AI AgentSparkyFitness 自托管健身数据平台Docker Compose 部署、环境变量与全家桶功能解析SparkyFitness 自托管健身数据平台Docker Compose 部署、环境变量与全家桶功能解析 SparkyFitness 是一个 自托管sel后端前端移动开发上一篇在 Google Antigravity 中安装与配置 Wren AI 的完整实战指南下一篇SpacetimeDB 查询构建器语法不一致性全解析与跨语言标准化方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
