Kanban - 企业级任务看板系统

一个现代化的任务管理看板系统，支持团队协作、权限管理、富文本编辑等功能。

功能特性 • 快速开始 • 开发指南 • API 文档

功能特性

核心功能

• 🎯 看板管理 - 创建、编辑、删除看板，支持多种视图模式
• 📋 任务管理 - 完整的任务生命周期管理，支持拖拽排序
• ✅ 子任务 - 任务分解，支持拖拽排序和进度追踪
• 👥 团队协作 - 团队创建、成员管理、角色分配
• 🔐 权限控制 - 基于 Casbin 的细粒度权限管理
• 📝 富文本编辑 - 基于 TipTap 的富文本编辑器，支持 Markdown
• 💬 评论系统 - 任务评论、@提及、富文本支持
• 📎 文件管理 - 图片上传、附件管理
• 📊 任务日志 - 完整的任务变更历史追踪
• 🗑️ 回收站 - 看板和团队的软删除与恢复
• 📜 系统审计 - 完整的操作日志记录
• 🔍 多视图模式 - 全局视图、用户视图、特权视图（管理员）

技术特性

• ⚡ 高性能 - 异步 I/O，支持并发处理
• 🐳 容器化 - Docker 一键部署
• 🔒 安全性 - JWT 认证、密码加密、XSS 防护
• 📱 响应式 - 适配桌面端和移动端
• 🧪 测试覆盖 - 完善的后端测试用例

技术栈

后端

• 框架: FastAPI 0.115+
• ORM: Tortoise ORM 0.22+
• 数据库: SQLite (支持其他关系型数据库)
• 认证: JWT + bcrypt
• 权限: Casbin
• Python: 3.13+

前端

• 框架: Vue 3.5 + TypeScript
• UI 库: Naive UI
• 状态管理: Pinia
• 路由: Vue Router 4
• 富文本: TipTap 2
• 拖拽: vuedraggable
• 构建工具: Vite 7

预览

系统激活

首次启动时需要激活系统，设置管理员账号和密码

看板视图

拖拽式任务管理，支持多列表和任务卡片

任务详情

完整的任务信息，包括描述、子任务、评论、附件和日志

富文本编辑器

功能强大的富文本编辑器，支持 Markdown、代码高亮、表格等

团队管理

团队创建、成员管理和权限分配

回收站

已删除的看板和团队可以恢复或永久删除

系统日志

完整的系统操作审计日志

快速开始

使用 Docker（推荐）

1. 克隆仓库

git clone https://github.com/donnel666/kanban.git
cd kanban

2. 构建 Docker 镜像

docker build -t kanban:latest .

3. 配置环境变量

# 生成随机密钥
export SECRET_KEY=$(openssl rand -hex 32)

4. 启动服务

docker-compose up -d

5. 访问应用 打开浏览器访问 http://localhost:8088

手动部署

后端

1. 安装依赖

cd backend
pip install uv
uv sync

2. 配置环境变量

cp .env.example .env
# 编辑 .env 文件，设置 SECRET_KEY 等配置

3. 启动服务

uv run uvicorn app.main:app --host 0.0.0.0 --port 8000

前端

1. 安装依赖

cd frontend
npm install
# 或使用 pnpm
pnpm install

2. 开发模式

npm run dev

3. 生产构建

npm run build

开发指南

项目结构

kanban/
├── backend/              # 后端服务
│   ├── app/
│   │   ├── api/         # API 路由
│   │   ├── core/        # 核心配置
│   │   ├── models/      # 数据模型
│   │   ├── schemas/     # Pydantic 模式
│   │   └── services/    # 业务逻辑
│   ├── tests/           # 测试用例
│   └── pyproject.toml   # 项目配置
├── frontend/            # 前端应用
│   ├── src/
│   │   ├── api/        # API 客户端
│   │   ├── components/ # 组件
│   │   ├── composables/# 组合式函数
│   │   ├── stores/     # 状态管理
│   │   ├── views/      # 页面
│   │   └── router/     # 路由配置
│   └── package.json
├── docker-compose.yml   # Docker 编排
└── Dockerfile          # Docker 镜像

运行测试

后端测试

cd backend
uv run pytest
# 带覆盖率
uv run pytest --cov=app --cov-report=html

前端测试

cd frontend
npm run test
# 带覆盖率
npm run test:coverage

构建 Docker 镜像

# 构建镜像
docker build -t kanban:latest .

# 导出镜像
docker save kanban:latest -o kanban.docker.tar

# 导入镜像
docker load -i kanban.docker.tar

API 文档

启动服务后，访问以下地址查看 API 文档：

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

主要 API 端点

• /api/auth/* - 认证相关
• /api/users/* - 用户管理
• /api/teams/* - 团队管理
• /api/boards/* - 看板管理
• /api/tasks/* - 任务管理
• /api/comments/* - 评论管理
• /api/trash/* - 回收站
• /api/system/* - 系统管理

配置说明

环境变量

变量名	说明	默认值
ENV	运行环境	development
DEBUG	调试模式	true
SECRET_KEY	JWT 密钥	必填
HOST	监听地址	0.0.0.0
PORT	监听端口	8000
DATABASE_URL	数据库连接	sqlite://data/kanban.db
CORS_ORIGINS	允许的跨域源	["*"]

系统初始化

系统首次启动时需要激活：

1. 访问系统后会自动跳转到激活页面
2. 设置管理员账号信息：
   • 用户名（登录名）
   • 显示名称
   • 密码（至少 6 位）
3. 点击"激活系统"完成初始化

激活后即可使用设置的账号登录系统。

贡献指南

欢迎贡献！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'feat: Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

提交规范

使用 Conventional Commits 规范：

• feat: 新功能
• fix: 修复 bug
• docs: 文档更新
• style: 代码格式调整
• refactor: 代码重构
• test: 测试相关
• chore: 构建/工具链相关

许可证

本项目采用 MIT License 开源协议。

联系方式

• Issues: GitHub Issues
• 讨论: GitHub Discussions

致谢

感谢以下开源项目：

• FastAPI
• Vue.js
• Naive UI
• TipTap
• Tortoise ORM
• Casbin

---

Made with ❤️ by the Kanban Team