一个可以代替Trello的开源看板工具Kan，从零开始保姆级部署教程

原创

v3n0m
v3n0m

v3n0m

2026年8月22日 22:00
天津

在小说阅读器读本章

去阅读

今天给大家推荐一个开源的看板式项目管理工具Kan，它的定位为Trello的自托管替代品。它支持看板协作、标签筛选、Trello 数据导入、模板复用，并且内置了 MCP Server可以让主流的ai agent直接用自然语言操作你的看板。

这篇文章带你从零开始，在自己的服务器上部署一个完整可用的Kan实例，并配置好 MCP，让AI能帮你管理任务。

全文分为七步：准备环境 → Docker Compose 部署 → 环境变量配置 → 本地开发搭建 → MCP AI接入 → 日常运维 → 常见问题排查。

每一步都有可直接复制的命令和配置。

01 部署前准备

正式部署之前，先确认以下条件。

硬件要求：Kan 本身是轻量的 Next.js 应用，加上 PostgreSQL 数据库，最低 1 核 2G 内存即可跑起来。生产环境建议 2 核 4G 起步，尤其是团队人数较多时。

软件依赖：服务器上需要安装 Docker 和 Docker Compose。Kan 官方提供的镜像托管在 GitHub Container Registry（ghcr.io），确保服务器能访问 ghcr.io。

网络与域名：如果只是内网试用，直接用IP + 端口访问即可。如果要对外提供服务，建议准备一个域名，并用 Nginx / Caddy 做反向代理和 HTTPS。Kan 默认监听3000端口。

数据备份：所有看板数据存在 PostgreSQL 中，附件存在S3兼容存储里。部署前想清楚数据备份策略——这是自托管最容易被忽略但最关键的一步。

02 Docker Compose 一键部署

这是官方推荐的部署方式，一条命令拉起数据库、自动迁移和 Web 服务三个容器。

第一步：创建项目目录和 .env 文件。

在服务器上新建一个目录，比如 /opt/kan，然后在里面创建 .env 文件。以下是最小可用配置：

POSTGRES_PASSWORD=替换成一个强密码NEXT_PUBLIC_BASE_URL=http://你的服务器IP:3000BETTER_AUTH_SECRET=替换成至少32位随机字符串WEB_PORT=3000BETTER_AUTH_SECRET 用于加密认证会话，可以用 openssl rand -hex 32 生成。NEXT_PUBLIC_BASE_URL 必须和实际访问地址一致，否则 OAuth 回调和登录会出问题。

第二步：创建 docker-compose.yml。

官方仓库提供了完整的 docker-compose.yml，核心包含三个服务：

• postgres：PostgreSQL 15 数据库，数据通过 volume 持久化到 kan_postgres_data。
• migrate：一次性运行数据库迁移，完成后自动退出，web 服务依赖它成功启动。
• web：Kan 主应用，监听 3000 端口，restart: unless-stopped 保证异常自动重启。

你可以直接从项目仓库复制 docker-compose.yml，也可以用以下精简版：

services:  postgres:    image: postgres:15    environment:      POSTGRES_DB: kan_db      POSTGRES_USER: kan      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}    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  migrate:    image: ghcr.io/kanbn/kan-migrate:latest    environment:      - POSTGRES_URL=postgres://kan:${POSTGRES_PASSWORD}@postgres:5432/kan_db    depends_on:      postgres:        condition: service_healthy    restart: \"no\"  web:    image: ghcr.io/kanbn/kan:latest    ports:      - \"${WEB_PORT:-3000}:3000\"    env_file:      - .env    environment:      - POSTGRES_URL=postgres://kan:${POSTGRES_PASSWORD}@postgres:5432/kan_db      - NEXT_PUBLIC_ALLOW_CREDENTIALS=true    depends_on:      migrate:        condition: service_completed_successfully    restart: unless-stoppedvolumes:  kan_postgres_data:

第三步：启动服务。

docker compose up -d

启动顺序是：postgres 先启动并通过健康检查 → migrate 运行数据库迁移 → web 服务启动。整个过程大约 1-2 分钟。

第四步：验证。

浏览器访问 http://你的服务器IP:3000，看到注册页面就说明部署成功了。注册第一个账号，开始使用。

常用运维命令：

查看日志：docker compose logs -f web停止服务：docker compose down重启服务：docker compose restart

03 环境变量完整指南

最小部署只需要四个变量，但要让 Kan 真正好用，还需要配置认证、邮件、文件存储等。以下按功能分组说明。

必填项（不填无法启动或登录异常）

NEXT_PUBLIC_BASE_URL：你的 Kan 访问地址，如 https://kan.yourdomain.com。必须和实际访问地址完全一致，包括 http/https 和端口。BETTER_AUTH_SECRET：认证加密密钥，至少 32 位随机字符串。POSTGRES_URL 或 POSTGRES_PASSWORD：数据库连接。Docker Compose 部署时在 compose 文件里配置 URL 即可。

认证配置

NEXT_PUBLIC_ALLOW_CREDENTIALS=true：允许邮箱密码注册登录。如果只想用 OAuth 登录，设为 false。NEXT_PUBLIC_DISABLE_SIGN_UP=false：是否禁止新用户注册。生产环境如果只给内部团队用，可以设为 true 关闭公开注册。Google 登录：GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRETGitHub 登录：GITHUB_CLIENT_ID + GITHUB_CLIENT_SECRETDiscord 登录：DISCORD_CLIENT_ID + DISCORD_CLIENT_SECRET企业 OIDC：OIDC_CLIENT_ID + OIDC_CLIENT_SECRET + OIDC_DISCOVERY_URL，可对接公司内部身份系统。BETTER_AUTH_ALLOWED_DOMAINS：限制 OIDC 登录的邮箱域名，比如只允许 yourcompany.com。

邮件配置

邮件用于注册验证、密码重置和通知。需要配置 SMTP：

EMAIL_FROM：发件人地址，如 \"Kan <[email protected]>\"SMTP_HOST、SMTP_PORT、SMTP_USER、SMTP_PASSWORD：SMTP 服务器信息。SMTP_SECURE=true：是否使用 TLS，465 端口通常设为 true，587 端口设为 false。NEXT_PUBLIC_DISABLE_EMAIL=true：如果暂时不想配邮件，可以用这个变量禁用所有邮件功能，但密码重置会不可用。

文件存储（附件和头像）

Kan 使用 S3 兼容存储保存附件。如果不配，文件上传功能不可用。可以用 AWS S3、Cloudflare R2、MinIO 等：

S3_REGION、S3_ENDPOINT、S3_ACCESS_KEY_ID、S3_SECRET_ACCESS_KEY：S3 连接信息。S3_FORCE_PATH_STYLE=true：MinIO 等自建存储需要设为 true。NEXT_PUBLIC_AVATAR_BUCKET_NAME、NEXT_PUBLIC_ATTACHMENTS_BUCKET_NAME：头像和附件的 bucket 名称。NEXT_PUBLIC_STORAGE_URL：存储服务的访问 URL

Trello 导入

要使用 Trello 看板一键导入，需要在 Trello 开发者平台创建应用，然后配置：

TRELLO_APP_API_KEY + TRELLO_APP_API_SECRET

白标与管理

NEXT_PUBLIC_WHITE_LABEL_HIDE_POWERED_BY=true：隐藏公开看板上的 \"Powered by kan.bn\" 标识。KAN_ADMIN_API_KEY：管理员 API 密钥，用于统计和管理端点。LOG_LEVEL=info：日志级别，生产环境建议 info，调试时用 debug。

04 本地开发环境搭建

如果你想参与开发、调试功能或做二次定制，需要搭建本地开发环境。

前置依赖：Node.js 18+、pnpm、PostgreSQL 15（本地安装或用 Docker 跑一个）。

步骤一：克隆仓库。

git clone https://github.com/kanbn/kan.gitcd kan

步骤二：安装依赖。

pnpm install

项目是 Turborepo 管理的 monorepo，pnpm 会自动安装所有 workspace 的依赖。

步骤三：配置环境变量。

cp .env.example .env然后编辑 .env，至少配置 POSTGRES_URL、NEXT_PUBLIC_BASE_URL=http://localhost:3000、BETTER_AUTH_SECRET

步骤四：运行数据库迁移。

pnpm db:migrate

这会在你的 PostgreSQL 中创建 Kan 需要的所有表。

步骤五：启动开发服务器。

pnpm dev

默认在 http://localhost:3000 启动，支持热重载。

项目结构速览：

apps/：主应用代码（Next.js Web 应用）packages/：共享包，包括 logger、UI 组件等cloud/：云版本相关代码（通知、定价等）tooling/：工程化工具配置

05 配置 MCP Server：让 AI 操作你的 Kan

这是 Kan 区别于其他看板工具的核心功能。配置完成后，你可以在 AI 编程工具里直接说\"帮我创建一个卡片\"，AI 会自动在 Kan 里完成操作。

前置条件：一个正在运行的 Kan 实例（自托管或云版本均可）、Node.js 18+、一个支持 MCP 的 AI 客户端。

第一步：在 Kan 中生成 API Key。

登录 Kan → 进入 Settings（设置）→ API Keys → Create key。生成后复制保存，这个 Key 只显示一次。

第二步：启动 MCP Server。

推荐用 npx 方式，不需要全局安装，自动使用最新版本：

npx -y @kan/mcp

也可以全局安装：

npm install -g @kan/mcpkan-mcp

MCP Server 通过两个环境变量配置：

KAN_API_URL：你的 Kan 实例地址，如 http://localhost:3000KAN_API_KEY：第一步生成的 API Key

第三步：在 AI 客户端中配置。

以 Cursor 为例：打开 Settings → MCP → 添加新的 MCP Server，配置命令为 npx，参数为 -y @kan/mcp，环境变量填入 KAN_API_URL 和 KAN_API_KEY。

Claude Desktop 的配置方式类似，在其 MCP 配置文件中添加对应的 command 和 env。

第四步：验证。

在 AI 对话框里输入：\"列出我所有的看板\"或\"在看板创建一个卡片，标题是测试任务\"。如果 AI 能正确读取或操作你的 Kan，说明配置成功。

安全提醒：API Key 等同于账号操作权限，不要提交到代码仓库，不要在公共环境暴露。生产环境建议通过环境变量或密钥管理工具注入。

06 日常运维与升级

查看日志：

web查看 Web 服务实时日志docker compose logs -f
查看数据库日志docker compose logs -f postgres

升级到最新版本：

Kan 的镜像 tag 是 latest，升级需要重新拉取镜像并重启：

docker compose pulldocker compose up -d

migrate 容器会在每次启动时自动运行新的数据库迁移，不需要手动操作。升级前建议先备份数据库。

数据备份：

PostgreSQL 数据存在 kan_postgres_data volume 中。备份命令：

docker compose exec postgres pg_dump -U kan kan_db > kan_backup_$(date +%Y%m%d).sql

建议设置定时任务（cron）每天自动备份，并保留最近 7-30 天的备份文件。附件如果存在 S3 中，由 S3 提供商负责耐久性，但也建议定期同步到异地存储。

性能调优：

团队人数较多时，给 PostgreSQL 分配更多内存。配置 REDIS_URL启用限流，防止 API 被滥用。用 Nginx 做反向代理时，注意配置 WebSocket 支持和合理的上传大小限制（对应 NEXT_API_BODY_SIZE_LIMIT）。

07 常见问题排查

Q：启动后访问 3000 端口显示连接拒绝？

先运行docker compose ps确认 web 容器是否在运行。如果一直在 restart，查看docker compose logs web找错误原因。常见原因是 BETTER_AUTH_SECRET 未设置或 POSTGRES_URL 连接失败。

Q：能打开页面但注册后登录失败？

检查NEXT_PUBLIC_BASE_URL是否和实际访问地址完全一致。如果用了反向代理和 HTTPS，这里必须写 https://开头的完整域名，不能写 IP 或带错端口。

Q：OAuth 登录回调报错？

确认 OAuth 应用的回调地址配置正确，并且BETTER_AUTH_TRUSTED_ORIGINS 包含了你的域名。如果用了 OIDC，检查 OIDC_DISCOVERY_URL 是否可访问。

Q：邮件发不出去？

检查 SMTP 配置。常见问题：端口和 SMTP_SECURE 不匹配（465 用 true，587 用 false）、SMTP 密码是授权码而非登录密码、服务器防火墙拦截了出站 SMTP 端口。可以先用 NEXT_PUBLIC_DISABLE_EMAIL=true 跳过邮件，确认其他功能正常后再排查。

Q：附件上传失败？

确认 S3 相关环境变量都配置了，bucket 已创建且访问密钥有读写权限。MinIO 等自建存储需要设置S3_FORCE_PATH_STYLE=true。

Q：Trello 导入按钮不可用？

需要配置TRELLO_APP_API_KEY 和 TRELLO_APP_API_SECRET，并且在 Trello 开发者后台设置正确的回调地址。

结尾

到这里，你应该已经有了一个完整运行的 Kan 实例：数据在自己的数据库里，团队成员可以注册协作，AI 能通过 MCP 直接操作看板。

自托管的价值不只是\"省钱\"，更重要的是数据主权和可定制性。而MCP的接入，让这个工具从\"需要人手动操作的软件\"变成了\"AI 工作流的一个节点\"这可能是项目管理工具下一个形态的雏形。