316 lines
8.7 KiB
Markdown
316 lines
8.7 KiB
Markdown
# Kan
|
||
|
||
Kan 是一个开源的看板式项目管理工具，可作为 Trello 的自托管替代方案。它支持工作区、看板、列表、卡片、标签、成员、评论、检查清单和活动记录。
|
||
|
||
Kan 使用 AGPLv3 协议发布。
|
||
|
||
- [项目主页](https://kan.bn)
|
||
- [在线文档](https://docs.kan.bn)
|
||
- [路线图](https://kan.bn/kan/roadmap)
|
||
- [Discord 社区](https://discord.gg/e6ejRb6CmT)
|
||
|
||
|
||
|
||
## 功能
|
||
|
||
- 看板可见性控制
|
||
- 工作区成员和协作
|
||
- Trello 看板导入
|
||
- 卡片标签和筛选
|
||
- 评论、活动记录和检查清单
|
||
- 可复用的看板模板
|
||
- 卡片截止日期、成员和附件
|
||
- 内置 REST API 和 MCP 服务
|
||
|
||
## 使用 Docker Compose 自托管
|
||
|
||
### 环境要求
|
||
|
||
- Docker Engine
|
||
- Docker Compose v2
|
||
|
||
### 启动
|
||
|
||
在仓库根目录执行：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env`，至少设置以下变量：
|
||
|
||
```dotenv
|
||
NEXT_PUBLIC_BASE_URL=http://localhost:3000
|
||
POSTGRES_PASSWORD=请填写数据库密码
|
||
POSTGRES_URL=postgresql://kan:请填写数据库密码@postgres:5432/kan_db
|
||
BETTER_AUTH_SECRET=请填写一个随机的 32 位以上密钥
|
||
```
|
||
|
||
构建本地镜像并启动：
|
||
|
||
```bash
|
||
docker compose up -d --build
|
||
```
|
||
|
||
仓库自带的 `docker-compose.yml` 使用本地镜像标签：
|
||
|
||
```yaml
|
||
services:
|
||
migrate:
|
||
image: kan-migrate:local
|
||
build:
|
||
context: .
|
||
dockerfile: ./apps/web/Dockerfile
|
||
target: migrate
|
||
web:
|
||
image: kan:local
|
||
build:
|
||
context: .
|
||
dockerfile: ./apps/web/Dockerfile
|
||
target: web
|
||
```
|
||
|
||
不会拉取远端 Web 镜像。数据库迁移会在 Web 服务启动前自动执行。启动完成后访问 <http://localhost:3000>。如修改端口，请同步修改 `WEB_PORT` 和 `NEXT_PUBLIC_BASE_URL`。
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
# 查看状态
|
||
docker compose ps
|
||
|
||
# 查看 Web 日志
|
||
docker compose logs -f web
|
||
|
||
# 查看迁移日志
|
||
docker compose logs -f migrate
|
||
|
||
# 停止服务
|
||
docker compose down
|
||
|
||
# 停止服务并删除数据库卷（会删除本地数据）
|
||
docker compose down -v
|
||
```
|
||
|
||
检查 API 健康状态：
|
||
|
||
```bash
|
||
curl http://localhost:3000/api/v1/health
|
||
```
|
||
|
||
预期返回：
|
||
|
||
```json
|
||
{ "status": "ok", "database": "ok", "storage": "not_configured" }
|
||
```
|
||
|
||
默认文件存储状态为 `not_configured`。如需上传头像和附件，请按照 `.env.example` 配置 S3 兼容存储。
|
||
|
||
## 本地开发
|
||
|
||
项目是 pnpm monorepo，需要 Node.js 20.18.1 或更高版本，以及 pnpm 9.14.2。
|
||
|
||
```bash
|
||
git clone https://github.com/kanbn/kan.git
|
||
cd kan
|
||
pnpm install
|
||
cp .env.example .env
|
||
pnpm db:migrate
|
||
pnpm dev
|
||
```
|
||
|
||
开发服务器默认地址为 <http://localhost:3000>。常用检查命令：
|
||
|
||
```bash
|
||
pnpm typecheck
|
||
pnpm lint
|
||
pnpm format
|
||
```
|
||
|
||
## 环境变量
|
||
|
||
完整变量列表见 [`.env.example`](.env.example)。
|
||
|
||
| 变量 | 用途 | 示例 |
|
||
| ------------------------------- | ---------------------------------- | -------------------------------------------- |
|
||
| `NEXT_PUBLIC_BASE_URL` | 当前 Kan 实例的访问地址 | `http://localhost:3000` |
|
||
| `POSTGRES_URL` | PostgreSQL 连接地址 | `postgresql://kan:密码@postgres:5432/kan_db` |
|
||
| `POSTGRES_PASSWORD` | Compose 创建 PostgreSQL 使用的密码 | `change-me` |
|
||
| `BETTER_AUTH_SECRET` | 登录会话加密密钥 | 随机 32 位以上字符串 |
|
||
| `WEB_PORT` | 宿主机映射端口 | `3000` |
|
||
| `REDIS_URL` | 可选的限流 Redis 地址 | `redis://redis:6379` |
|
||
| `NEXT_PUBLIC_ALLOW_CREDENTIALS` | 是否允许账号密码登录 | `true` |
|
||
| `NEXT_PUBLIC_DISABLE_SIGN_UP` | 是否关闭注册 | `false` |
|
||
| `KAN_ADMIN_API_KEY` | 管理和监控接口密钥 | 自定义密钥 |
|
||
|
||
## MCP 服务
|
||
|
||
Kan 仓库内置了基于 Model Context Protocol 的 MCP 服务。连接后，Claude Desktop、Cursor、VS Code、Codex 等 MCP 客户端可以通过自然语言读取和管理 Kan 数据。
|
||
|
||
### 先看这里
|
||
|
||
MCP 源码位于 `packages/mcp`，目前是仓库内的工作区包，并未发布为 npm 公共包。因此以下命令不能使用：
|
||
|
||
```bash
|
||
npx -y @kan/mcp
|
||
bunx kan-mcp
|
||
```
|
||
|
||
请从当前仓库构建 MCP 服务，再让客户端启动生成的文件。
|
||
|
||
### 获取 API 密钥
|
||
|
||
1. 登录 Kan。
|
||
2. 打开设置中的 API 密钥页面，地址通常为 `/settings/api`。
|
||
3. 创建一个 API 密钥并立即保存。密钥只会完整显示一次。
|
||
|
||
MCP 使用用户 API 密钥，不是 `KAN_ADMIN_API_KEY`。请求会以 Bearer Token 方式访问 `${KAN_BASE_URL}/api/v1`。
|
||
|
||
### 构建
|
||
|
||
在仓库根目录执行：
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm --filter @kan/mcp build
|
||
```
|
||
|
||
构建产物为 `packages/mcp/dist/index.js`。MCP 服务使用 stdio 通信，应由 MCP 客户端启动，不需要单独暴露 HTTP 端口。
|
||
|
||
### 环境变量
|
||
|
||
| 变量 | 说明 |
|
||
| --------------- | ---------------------------------- |
|
||
| `KAN_BASE_URL` | Kan 实例根地址，不要追加 `/api/v1` |
|
||
| `KAN_API_TOKEN` | Kan 设置中创建的用户 API 密钥 |
|
||
|
||
本地 Kan 使用 Docker Compose 时：
|
||
|
||
```text
|
||
KAN_BASE_URL=http://localhost:3000
|
||
KAN_API_TOKEN=kan_你的_api_key
|
||
```
|
||
|
||
### Claude Desktop 和 Cursor
|
||
|
||
Claude Desktop 使用 `claude_desktop_config.json`，Cursor 使用项目内的 `.cursor/mcp.json`。将 `args` 中的路径替换为本机仓库的绝对路径：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"kan": {
|
||
"command": "node",
|
||
"args": ["/绝对路径/kan/packages/mcp/dist/index.js"],
|
||
"env": {
|
||
"KAN_BASE_URL": "http://localhost:3000",
|
||
"KAN_API_TOKEN": "kan_你的_api_key"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
Windows 路径示例：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"kan": {
|
||
"command": "node",
|
||
"args": ["C:\\workspace\\kan\\packages\\mcp\\dist\\index.js"],
|
||
"env": {
|
||
"KAN_BASE_URL": "http://localhost:3000",
|
||
"KAN_API_TOKEN": "kan_你的_api_key"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
VS Code 的 `mcp.json` 使用 `servers` 作为顶层键，并增加 `type`：
|
||
|
||
```json
|
||
{
|
||
"servers": {
|
||
"kan": {
|
||
"type": "stdio",
|
||
"command": "node",
|
||
"args": ["/绝对路径/kan/packages/mcp/dist/index.js"],
|
||
"env": {
|
||
"KAN_BASE_URL": "http://localhost:3000",
|
||
"KAN_API_TOKEN": "kan_你的_api_key"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Codex
|
||
|
||
Codex 可通过命令添加 stdio MCP 服务。将脚本路径替换为本机绝对路径：
|
||
|
||
```bash
|
||
codex mcp add kan \
|
||
--env KAN_BASE_URL=http://localhost:3000 \
|
||
--env KAN_API_TOKEN=kan_你的_api_key \
|
||
-- node /绝对路径/kan/packages/mcp/dist/index.js
|
||
```
|
||
|
||
Windows PowerShell：
|
||
|
||
```powershell
|
||
codex mcp add kan `
|
||
--env KAN_BASE_URL=http://localhost:3000 `
|
||
--env KAN_API_TOKEN=kan_你的_api_key `
|
||
-- node C:\workspace\kan\packages\mcp\dist\index.js
|
||
```
|
||
|
||
使用 `codex mcp get kan` 检查配置。
|
||
|
||
### 手动启动和排错
|
||
|
||
Linux 或 macOS：
|
||
|
||
```bash
|
||
KAN_BASE_URL=http://localhost:3000 \
|
||
KAN_API_TOKEN=kan_你的_api_key \
|
||
node packages/mcp/dist/index.js
|
||
```
|
||
|
||
PowerShell：
|
||
|
||
```powershell
|
||
$env:KAN_BASE_URL = "http://localhost:3000"
|
||
$env:KAN_API_TOKEN = "kan_你的_api_key"
|
||
node .\packages\mcp\dist\index.js
|
||
```
|
||
|
||
如果出现 `Connection closed`，检查以下内容：
|
||
|
||
1. 已执行 `pnpm --filter @kan/mcp build`。
|
||
2. `args` 指向真实存在的 `packages/mcp/dist/index.js`。
|
||
3. `KAN_BASE_URL` 只填写实例根地址。
|
||
4. `KAN_API_TOKEN` 是 Kan 用户 API 密钥。
|
||
5. `http://localhost:3000/api/v1/health` 返回数据库正常。
|
||
|
||
### 工具范围
|
||
|
||
当前 MCP 服务提供 46 个工具，覆盖工作区、看板、列表、卡片、评论、标签、检查清单和成员管理。连接后可以直接提出以下请求：
|
||
|
||
- 列出我的工作区。
|
||
- 查看研发工作区中的所有看板。
|
||
- 创建一个包含待办、进行中、已完成列表的新看板。
|
||
- 将登录问题卡片移动到进行中列表。
|
||
- 给版本发布卡片添加检查清单和评论。
|
||
|
||
## 技术栈
|
||
|
||
Next.js、React、tRPC、Better Auth、Tailwind CSS、Drizzle ORM、PostgreSQL 和 Model Context Protocol SDK。
|
||
|
||
## 参与贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request。提交代码前请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)，并运行类型检查、Lint 和格式检查。
|
||
|
||
## 许可证与联系
|
||
|
||
项目使用 [AGPLv3](LICENSE) 协议。如需支持，请发送邮件至 [henry@kan.bn](mailto:henry@kan.bn)，或加入 [Discord 社区](https://discord.gg/e6ejRb6CmT)。
|