FlowTask
一个全面的任务管理平台,具有GitHub/Slack集成、通过MCP的AI代理功能和公共共享视图。采用Bun制造,性能超快。
特性
- 用看板图.具有可自定义状态的拖放任务管理。
- 智能视图.创建具有复杂查询条件的筛选视图。
- 公共共享。使用可选密码保护公开共享视图。
- GitHub集成.从GitHub issues/PR到FlowTask任务的单向同步。
- Slack集成。任务更新时从FlowTask到Slack频道的单向通知。
- AI代理.MCP服务器,配备AI驱动的任务管理工具。
- 实时更新原生Bun WebSocket+Redis发布/订阅,用于即时同步。
- 多工作空间.使用RBAC跨多个工作区组织项目。
技术栈
| 层 | 技术 |
|---|---|
| 运行时间 | 包子 |
| 前端 | React+TypeScript+Vite+顺风CSS |
| 后端 | Hono(在Bun上运行) |
| 数据库 | PostgreSQL+Drizzle ORM |
| 缓存/队列 | Redis |
| 身份验证 | 更好的身份验证 |
| 实时 | Bun WebSockets+Redis发布/订阅 |
先决条件
- 包子 1.1+ (https://bun.sh)
- 码头工人 和 Docker Compose (用于数据库)
- Git
开发设置
macOS/Linux
- 安装Bun (如果未安装)```bash
curl -fsSL https://bun.sh/install | bash
1. **克隆存储库**```bash
git clone https://github.com/flowful-ai/tasksflow.git
cd tasksflow
- 安装依赖项```bash
bun install
1. **设置环境变量**```bash
cp .env.example .env
编辑 .env 并配置:```env
Database
DATABASE_URL=postgresql://flowtask:flowtask@localhost:5432/flowtask
Redis
REDIS_URL=redis://localhost:6379
Auth
BETTER_AUTH_SECRET=your-secret-key-min-32-chars
BETTER_AUTH_URL=http://localhost:3001
Optional: OAuth providers
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=
Optional: Integrations
GITHUB_APP_ID=
GITHUB_APP_PRIVATE_KEY=
GITHUB_WEBHOOK_SECRET=
SLACK_BOT_TOKEN=
SLACK_SIGNING_SECRET=
Optional: AI
OPENROUTER_API_KEY=
ENCRYPTION_KEY=your-32-byte-encryption-key
1. **启动基础设施服务**```bash
docker-compose up -d
这将启动PostgreSQL、Redis和MinIO(S3兼容存储)。
- 运行数据库迁移```bash
bun run db:generate
bun run db:migrate
1. **启动开发服务器**```bash
bun run dev
- API服务器:http://localhost:3001
- WebSocket服务器:ws://localhost:3002/ws
- Web应用程序:http://localhost:5173
视窗
- 安装Bun```powershell
powershell -c "irm bun.sh/install.ps1 | iex"
或者使用WSL2(建议使用以获得最佳兼容性):```bash
# In WSL2
curl -fsSL https://bun.sh/install | bash
- 安装Docker桌面
- 下载自https://www.docker.com/products/docker-desktop/
- 在Docker桌面设置中启用WSL2后端
- 克隆和设置```powershell
git clone https://github.com/flowful-ai/tasksflow.git
cd tasksflow
bun install
1. **设置环境变量**```powershell
copy .env.example .env
编辑 .env 使用您喜欢的文本编辑器(与macOS/Linux相同的变量)。
- 启动基础设施服务```powershell
docker-compose up -d
1. **运行数据库迁移**```powershell
bun run db:generate
bun run db:migrate
- 启动开发服务器```powershell
bun run dev
### 有用的开发命令```bash
# Start all services in dev mode
bun run dev
# Start only the API
bun run --filter @flowtask/api dev
# Start only the web app
bun run --filter @flowtask/web dev
# Build all packages
bun run build
# Run type checking
bun run typecheck
# Run linting
bun run lint
# Generate new migration after schema changes
bun run db:generate
# Apply migrations
bun run db:migrate
# Open Drizzle Studio (database GUI)
bun run db:studio
# View logs from Docker services
docker-compose logs -f
直接数据库访问
为了调试或运行即席查询,您可以直接对PostgreSQL容器执行SQL:```bash
Run a single SQL query
docker exec -i flowtask-postgres psql -U flowtask -d flowtask -c "SELECT * FROM users;"
Run multiple queries
docker exec -i flowtask-postgres psql -U flowtask -d flowtask -c "
SELECT u.email,
CASE WHEN a.id IS NOT NULL THEN 'Yes' ELSE 'No' END as has_account
FROM users u
LEFT JOIN accounts a ON u.id = a.user_id;
"
Open an interactive PostgreSQL shell
docker exec -it flowtask-postgres psql -U flowtask -d flowtask
Execute SQL from a file
docker exec -i flowtask-postgres psql -U flowtask -d flowtask < script.sql
常见调试查询:```bash
# List all tables
docker exec -i flowtask-postgres psql -U flowtask -d flowtask -c "\dt"
# Describe a table structure
docker exec -i flowtask-postgres psql -U flowtask -d flowtask -c "\d users"
# Check users and their accounts
docker exec -i flowtask-postgres psql -U flowtask -d flowtask -c "
SELECT u.id, u.email, u.name, a.provider_id
FROM users u
LEFT JOIN accounts a ON u.id = a.user_id;
"
对于Redis访问:```bash
Open Redis CLI
docker exec -it flowtask-redis redis-cli
Check Redis keys
docker exec -i flowtask-redis redis-cli KEYS "*"
Monitor Redis in real-time
docker exec -it flowtask-redis redis-cli MONITOR
______________________________________________________________________
## 生产部署
### 使用Docker Compose
1. **克隆和配置**```bash
git clone https://github.com/flowful-ai/tasksflow.git
cd tasksflow
cp .env.example .env
- 编辑
.env用于生产```env
NODE_ENV=production
Use strong secrets
DATABASE_URL=postgresql://flowtask:STRONG_PASSWORD@db:5432/flowtask
REDIS_URL=redis://redis:6379
BETTER_AUTH_SECRET=generate-a-strong-64-char-secret
BETTER_AUTH_URL=https://your-domain.com
Configure your domain
CORS_ORIGIN=https://your-domain.com
1. **构建并启动**```bash
docker-compose -f docker-compose.prod.yml up -d --build
- 运行迁移```bash
docker-compose -f docker-compose.prod.yml exec api bun run db:migrate
1. **访问应用程序**
- Web应用程序:http://localhost:3000
- APIhttp://localhost:3001
- Websocket:WS://localhost:3002/WS
### 手动部署
1. **构建所有包**```bash
bun install --frozen-lockfile
bun run build
- 部署API```bash
cd apps/api
bun run dist/index.js
1. **部署Web应用程序**
web应用程序构建为静态文件 `apps/web/dist/`.部署到任何静态主机:
- **Nginx**:复制 `dist/` 到 `/usr/share/nginx/html/`
- **Vercel/Netlify**:指向 `apps/web` 目录
- **S3+云前端**:上传 `dist/` 到S3存储桶
1. **配置反向代理**
Nginx配置示例:```nginx
server {
listen 80;
server_name your-domain.com;
# Frontend
location / {
root /var/www/flowtask;
try_files $uri $uri/ /index.html;
}
# API proxy
location /api {
proxy_pass http://localhost:3001;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection 'upgrade';
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
}
# WebSocket proxy
location /ws {
proxy_pass http://localhost:3002;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "Upgrade";
proxy_set_header Host $host;
}
}
环境变量参考
变量 · 必填 · 描述
DATABASE_URL · 是 · PostgreSQL连接字符串
REDIS_URL · 是 · Redis连接字符串
BETTER_AUTH_SECRET · 是 · 签名身份验证令牌的秘密(最少32个字符)
BETTER_AUTH_URL · 是 · 身份验证回调的基本URL
API_PORT · 没有 · API服务器端口(默认值:3001)
WS_PORT · 否 · WebSocket服务器端口(默认:3002)
CORS_ORIGIN · 否 · 允许的CORS源(默认值:localhost:5173)
GITHUB_CLIENT_ID · 否 · GitHub OAuth应用程序客户端ID
GITHUB_CLIENT_SECRET · 否 · GitHub OAuth应用程序客户端机密
GOOGLE_CLIENT_ID · 否 · 谷歌OAuth客户端ID
GOOGLE_CLIENT_SECRET · 否 · 谷歌OAuth客户端机密
GITHUB_APP_ID · 否 · 用于集成的GitHub应用程序ID
GITHUB_APP_PRIVATE_KEY · 否 · GitHub应用程序私钥(base64编码)
GITHUB_WEBHOOK_SECRET · 否 · 验证GitHub webhooks的秘密
SLACK_BOT_TOKEN · 否 · Slack bot OAuth令牌
SLACK_SIGNING_SECRET · 否 · 验证Slack请求的秘密
OPENROUTER_API_KEY · 否 · 用于AI功能的OpenRouter API密钥
ENCRYPTION_KEY · 没有用于加密存储的API密钥的32字节密钥
MINIO_ENDPOINT · 文件存储没有 · S3/MinIO端点
MINIO_ACCESS_KEY · 否 · S3/MinIO访问密钥
MINIO_SECRET_KEY · 否 · S3/MinIO密钥
项目结构```
flowtask/
├── apps/
│ ├── api/ # Hono API server (Bun runtime)
│ │ ├── src/
│ │ │ ├── index.ts # Server entry point
│ │ │ ├── routes/ # API route handlers
│ │ │ └── websocket/ # Bun WebSocket handler
│ │ └── Dockerfile
│ │
│ └── web/ # React frontend
│ ├── src/
│ │ ├── components/ # UI components
│ │ ├── routes/ # Page components
│ │ ├── stores/ # Zustand state stores
│ │ └── api/ # API client
│ ├── nginx.conf
│ └── Dockerfile
│
├── packages/
│ ├── shared/ # Shared types and utilities
│ ├── database/ # Drizzle schema and client
│ ├── auth/ # Better Auth configuration
│ ├── domain/ # Business logic services
│ └── integrations/ # External service clients
│
├── docker-compose.yml # Development infrastructure
├── docker-compose.prod.yml # Production deployment
├── turbo.json # Turborepo configuration
└── package.json # Root package (Bun workspaces)
```
为什么是Bun?
FlowTask使用Bun作为其主要运行时有几个原因:
- 速度.Bun在启动服务器和运行TypeScript方面比Node.js快得多。
- 原生TypeScript无需进行转译步骤。Bun直接运行TypeScript。
- 内置WebSockets原生WebSocket支持,无需额外软件包。
- 一体化包管理器、打包器、测试运行器和运行时在一个工具中。
- 兼容Node.js大多数npm包都是开箱即用的。
集成设置
GitHub集成
- 创建GitHub应用程序https://github.com/settings/apps/new
- 配置权限:
- 问题:读写
- 拉取请求:读取
- Webhooks:接收事件 - 将webhook URL设置为
https://your-domain.com/api/webhooks/github - 生成并下载私钥
- 将凭据添加到
.env
Slack集成
FlowTask在任务更新时向Slack发布单向通知。它不会从Slack接收事件或创建任务。
- 创建Slack应用程序https://api.slack.com/apps
- 添加
chat:writeBot令牌范围 OAuth和权限 - 将应用程序安装到您的工作区并复制Bot用户OAuth令牌
- 邀请机器人加入目标频道
- 集
SLACK_BOT_TOKEN和SLACK_SIGNING_SECRET在.env
人工智能代理(MCP)
FlowTask MCP现在使用OAuth 2.1(授权码+PKCE)进行动态客户端注册。
- 使用以下命令在ChatGPT或Claude中添加MCP服务器
https://your-domain.com/api/mcp/sse.
- 传输模式:流式HTTP、无状态、,POST请求:
-GET/DELETE上/api/mcp/sse不支持。
- 传统拆分SSE端点(/api/mcp/sse/stream,/api/mcp/sse/message)已弃用/禁用。 - 客户端从以下位置发现OAuth元数据:
-https://your-domain.com/.well-known/oauth-protected-resource/api/mcp/sse
-https://your-domain.com/api/mcp/.well-known/oauth-authorization-server - 登录并批准一个工作区范围的同意(
mcp:workspace:)加上工具范围(mcp:tool:create_task,mcp:tool:add_comment等等)。 - 仅限工作区
owner和admin角色可以批准MCP OAuth访问。 - MCP工具通过以下方式发现
tools/list(不是通过list_resources).
贡献
- 分叉存储库
- 创建要素分支:
git checkout -b feature/my-feature - 进行更改
- 运行测试:
bun test - 承诺:
git commit -m "Add my feature" - 推:
git push origin feature/my-feature - 打开拉取请求
许可证
MIT许可证。看 许可证 了解详情。
