开源自托管看板工具：基于Preact+Hono+SQLite的零云依赖方案

1. 项目概述一个为自托管与AI协作而生的看板应用如果你正在寻找一个可以完全掌控在自己手里、没有订阅费用、又能无缝集成到你自己产品中的看板工具那么clawnify/open-kanban这个项目值得你花时间深入研究。它不是一个玩具而是一个生产就绪的、开源的 Trello 替代方案。我花了些时间把它部署起来并深入研究了其代码架构发现它的设计理念非常务实零云依赖、双模式界面、以及为现代开发流程量身定制的技术栈。简单来说这是一个基于Preact Hono SQLite构建的轻量级看板应用。你可以在本地一键运行数据就存在一个 SQLite 文件里彻底摆脱了对任何外部云服务的依赖。这尤其适合那些需要将项目管理功能嵌入到自己 SaaS 产品中的团队或者任何对数据隐私和成本控制有要求的个人开发者。最让我觉得巧妙的是它的“双模式UI”设计一个是我们熟悉的、为人类优化的拖拽交互界面另一个则是为 AI 智能体或浏览器自动化工具准备的“代理模式”界面元素更大、操作更显式。这种设计考虑到了未来人机协作的工作流颇具前瞻性。2. 核心设计思路与技术选型解析2.1 为什么是 Preact Hono SQLite 这个组合看到这个技术栈我的第一反应是“精悍”。这完全是一个为全栈JavaScript/TypeScript开发者打造的、追求极致简洁和高效的技术方案。Preact 作为前端框架相比完整的 ReactPreact 的核心优势在于其极小的体积约 3kB和相似的 API。对于一个看板应用这种交互密集但组件结构相对清晰的场景Preact 提供了足够的 React 生态能力如 Hooks、Context同时保证了极快的加载速度和运行时性能。这意味着你可以轻松地将这个看板组件嵌入到任何网页中而不用担心引入一个庞大的前端框架带来的负担。Hono 作为后端框架Hono 是一个为边缘计算和现代 JS 运行时如 Cloudflare Workers, Bun, Deno, Node.js设计的超快 Web 框架。它的 API 设计非常直观类似于 Express 但更轻量。在这个项目中Hono 完美地承担了提供 RESTful API 的角色。由于看板应用的后端逻辑主要是 CRUD增删改查Hono 的简洁性使得服务器端代码非常易于理解和维护。SQLite 作为数据库这是实现“零云依赖”和“自托管”承诺的关键。SQLite 是一个服务器端的数据库整个数据库就是一个.db文件。它无需安装和配置复杂的数据库服务如 PostgreSQL 或 MySQL非常适合嵌入式场景和桌面应用。使用better-sqlite3这个 Node.js 驱动可以直接进行同步的、高性能的数据库操作简化了异步处理逻辑。对于个人或小团队的项目管理工具来说SQLite 的性能和可靠性完全足够并且备份和迁移数据异常简单——直接复制一个文件即可。这个技术栈组合清晰地传达了一个信息开发者体验和部署简易性优先。你不需要成为 DevOps 专家就能让一个功能完整的看板系统跑起来。2.2 双模式UI兼顾人类直觉与机器可靠性的设计哲学这是该项目最独具匠心的特性。传统的看板工具如 Trello完全围绕人类的拖拽操作设计但这对于自动化脚本或 AI 智能体来说并不友好。如何让同一个应用既能让人用得顺手又能让机器可靠地操作项目给出的答案是通过 URL 参数?agenttrue动态切换界面模式。人类模式这是我们熟悉的体验。卡片可以通过拖拽在列表间移动列表标题和卡片内容支持双击或点击进行内联编辑更多的操作如删除、移动被隐藏在一个需要鼠标悬停才会出现的“...”菜单中。这种设计最大限度地利用了屏幕空间提供了流畅的视觉反馈。代理模式当检测到agenttrue参数时界面会发生关键变化拖拽被禁用取而代之的是每个卡片上都会显示一个显式的“移动到 [列表]”下拉选择框。所有表单始终可见。添加卡片的输入框不再需要点击“添加卡片”按钮才出现而是直接显示在列表底部。操作按钮显式化。列表标题旁边会出现明确的“重命名”按钮卡片上的操作按钮也固定显示不再依赖悬停。点击目标变大。所有可交互元素的面积被有意增大降低了自动化点击操作误触的风险。这种设计的意义在于它承认了两种不同的“用户”有着截然不同的交互需求。人类追求效率和流畅感而机器或通过机器操作的人类如使用浏览器自动化工具进行测试或批量操作追求的是确定性和可靠性。通过一个简单的开关将两者解耦是一个非常优雅的解决方案。3. 项目架构与核心模块深度剖析让我们深入代码仓库看看它是如何组织起来的。理解其架构对于你想进行二次开发或集成至关重要。3.1 前后端分离与数据流项目采用了经典的前后端分离架构但得益于全栈 JS 和 Vite开发体验是统一和高效的。src/ ├── server/ # 后端 (Hono SQLite) │ ├── schema.sql # 数据库表结构定义 │ ├── db.ts # 数据库连接、初始化及数据访问层 │ └── index.ts # Hono 应用定义所有 REST API 端点 └── client/ # 前端 (Preact) ├── app.tsx # 应用根组件检测 agent 模式 ├── context.tsx # Preact Context管理全局看板状态 ├── hooks/ # 自定义 Hooks │ ├── use-board.ts # 获取和更新看板数据 │ └── use-drag.ts # 封装 HTML5 拖拽逻辑 └── components/ # UI 组件库 ├── board.tsx ├── list.tsx ├── card.tsx └── ... (其他专用组件)数据流非常清晰前端组件如board.tsx通过use-board.ts这个自定义 Hook 发起 API 请求。use-board.ts调用后端的 REST API定义在server/index.ts。后端 API 通过db.ts中的函数与 SQLite 数据库交互。数据返回后更新到context.tsx提供的全局状态中。所有订阅了该状态的 UI 组件自动重新渲染。3.2 数据模型设计简洁而高效数据库只有两张表关系简单明了这正是其轻量化的体现。-- lists 表代表看板的列 CREATE TABLE lists ( id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL, position INTEGER NOT NULL, -- 用于排序 created_at DATETIME DEFAULT CURRENT_TIMESTAMP ); -- cards 表代表列中的卡片 CREATE TABLE cards ( id INTEGER PRIMARY KEY AUTOINCREMENT, list_id INTEGER NOT NULL, title TEXT NOT NULL, description TEXT, position INTEGER NOT NULL, -- 在同一个 list 内的排序 created_at DATETIME DEFAULT CURRENT_TIMESTAMP, updated_at DATETIME DEFAULT CURRENT_TIMESTAMP, FOREIGN KEY (list_id) REFERENCES lists (id) ON DELETE CASCADE );设计要点解析position字段这是实现手动排序的核心。无论是列表的水平排序还是卡片在列表内的垂直排序都依赖这个整数字段。当用户拖拽调整顺序后后端会重新计算并更新相关所有项的position值。这是一种常见且高效的排序策略。ON DELETE CASCADE这是数据库层面的一个关键设置。它意味着当删除一个列表 (list) 时数据库会自动删除该列表下所有的卡片 (card)。这保证了数据的一致性避免了“孤儿卡片”的出现也简化了后端删除逻辑。updated_at字段仅在cards表中存在。这很合理因为列表通常只涉及创建、重命名和排序而卡片的内容标题、描述则需要频繁更新。这个字段为未来实现“最近更新”之类的功能预留了空间。3.3 API 设计紧凑且完备后端 (server/index.ts) 提供了一组非常紧凑的 REST API完全覆盖了看板的所有操作方法端点描述关键逻辑GET/api/board获取整个看板数据通过 JOIN 查询一次性返回所有列表及其下属的卡片并按position排序。这是最高效的方式避免了前端多次请求。POST/api/lists创建新列表接收title自动计算最大的position值并加1使新列表出现在最右侧。PUT/api/lists/:id更新列表标题简单的UPDATE操作。DELETE/api/lists/:id删除列表得益于ON DELETE CASCADE只需删除列表行数据库会自动清理卡片。POST/api/cards在指定列表中创建卡片接收list_id和title在目标列表内计算新的最大position。PUT/api/cards/:id更新卡片内容更新title,description和updated_at时间戳。DELETE/api/cards/:id删除卡片直接删除。POST/api/cards/:id/move将卡片移动到另一列表这是最复杂的操作。它需要1. 从原列表的卡片序列中移除该卡片重排position。2. 将其list_id更新为目标列表ID。3. 插入到目标列表的指定位置重排目标列表的position。所有这些需要在一次数据库事务中完成以保证数据一致性。注意/api/cards/:id/move这个端点设计得非常通用。它不仅处理跨列表移动实际上也处理同一列表内的排序。前端在拖拽结束时无论是列表内移动还是跨列表移动都会调用这个接口并传递目标list_id和新的position索引。后端逻辑会统一处理。4. 从零开始本地部署与深度定制指南4.1 环境准备与首次运行假设你已经在本地开发环境按照官方 Quickstart 的步骤即可。但我想补充一些细节和可能遇到的问题。# 1. 克隆项目 git clone https://github.com/clawnify/open-kanban.git cd open-kanban # 2. 安装依赖 (确保你已安装 Node.js 20 和 pnpm) pnpm install # 3. 启动开发服务器 pnpm run dev实操心得与注意事项Node.js 版本项目要求 Node.js 20。如果你使用nvm管理多版本可以运行nvm use如果项目有.nvmrc文件或手动切换。低于此版本可能会在安装或运行better-sqlite3原生模块时遇到问题。包管理器项目推荐pnpm它速度更快且节省磁盘空间。如果你习惯用npm或yarn理论上也可以但建议先删除现有的node_modules和锁文件 (package-lock.json或yarn.lock)再用你选择的工具重新install以避免潜在的依赖解析冲突。首次运行执行pnpm run dev后Vite 会启动开发服务器。关键一步打开浏览器访问http://localhost:5173时后端 Hono 服务器也会被启动。此时你会注意到项目根目录下自动生成了一个data.db文件。这是因为server/db.ts中的初始化逻辑会在数据库文件不存在时自动执行schema.sql来建表并插入一个默认的看板通常包含“待办”、“进行中”、“完成”三个列表。这个过程是完全静默的是开箱即用体验的一部分。4.2 深入探索“代理模式”如前所述代理模式是特色功能。除了在浏览器中手动添加?agenttrue参数你还可以思考它的应用场景端到端测试如果你要为这个看板应用写自动化测试例如使用 Playwright 或 Cypress使用代理模式会让测试脚本更稳定。因为显式的按钮和固定的表单比寻找悬停元素和模拟拖拽要可靠得多。AI 智能体集成假设你正在构建一个 AI 助手它可以帮用户管理任务。你可以让 AI 助手在操作看板时始终使用代理模式的 URL。这样AI 通过解析页面 HTML 结构时能更清晰地识别出可操作的元素如“移动到”下拉框、大大的“添加卡片”按钮。无障碍访问虽然项目没有明确说明但这种大目标、显式控件的界面客观上对某些使用辅助技术的用户也更友好。你可以在client/app.tsx中看到模式检测的逻辑非常简单// 简化后的逻辑 const urlParams new URLSearchParams(window.location.search); const isAgentMode urlParams.has(agent);然后这个isAgentMode的布尔值会通过 Context 传递给所有子组件从而决定它们渲染的是“人类版”还是“代理版”。4.3 如何进行自定义与扩展作为一个开源项目其最大的价值在于可定制性。以下是一些常见的扩展方向修改默认样式项目使用了基础的 CSS。你可以在client目录下的组件中直接修改样式或者引入像Tailwind CSS这样的工具。要引入 Tailwind你需要安装依赖配置postcss.config.js和tailwind.config.js并在根样式文件中导入。增加卡片字段比如你想为卡片添加“优先级”、“截止日期”或“标签”。修改server/schema.sql在cards表中添加新字段如due_date DATETIME。更新server/db.ts中与卡片相关的 TypeScript 接口和数据库操作函数。在server/index.ts中更新创建卡片 (POST /api/cards) 和更新卡片 (PUT /api/cards/:id) 的接口使其能接收和处理新字段。在前端修改client/context.tsx中的状态类型并在card.tsx组件的编辑和展示视图中添加对应的 UI 控件。添加用户系统这是个大改动但思路清晰。你需要在数据库中添加users表并在cards表中添加assignee_id字段。实现用户认证如 JWT。修改所有 API 端点将其与用户权限关联例如用户只能修改自己创建的卡片。前端添加登录/注册页面并在请求头中携带认证令牌。更换数据库虽然 SQLite 是亮点但如果你需要多实例部署或更强的并发能力可以考虑换成 PostgreSQL。你需要更换better-sqlite3为pgPostgreSQL 客户端。重写server/db.ts中的所有查询语句因为 SQLite 和 PostgreSQL 的 SQL 方言有细微差别如AUTOINCREMENTvsSERIAL。修改连接逻辑从文件连接变为网络连接。5. 生产环境部署与运维实践开发环境跑起来很简单但要将其作为一个真正的服务部署出去还需要一些步骤。5.1 构建与部署项目使用 Vite 进行构建它同时处理了前端资源打包和后端代码的转译。# 构建生产版本 pnpm run build # 构建完成后你会看到新增的 dist/ 目录 # 然后可以启动生产服务器 pnpm run start部署选项传统服务器你可以将整个项目文件夹或仅dist/目录上传到一台有 Node.js 环境的云服务器如 AWS EC2、DigitalOcean Droplet、阿里云 ECS。使用pm2或systemd来守护pnpm start进程并配置 Nginx 作为反向代理将域名请求转发到应用运行的端口默认可能是 3000 或 5173。Docker 容器化这是更推荐的方式能保证环境一致性。你需要编写一个Dockerfile。# 示例 Dockerfile FROM node:20-alpine WORKDIR /app COPY package.json pnpm-lock.yaml ./ RUN corepack enable pnpm pnpm install --frozen-lockfile COPY . . RUN pnpm run build EXPOSE 3000 # 假设生产服务器运行在3000端口 CMD [pnpm, start]然后构建镜像并运行容器。别忘了通过 Docker 卷 (-v) 将宿主机目录挂载到容器内以持久化data.db文件否则容器重启后数据会丢失。Serverless/边缘平台由于使用了 Hono这个应用可以轻松部署到支持 Node.js 的 Serverless 平台如 Vercel、Netlify Functions 或 Cloudflare Workers。但需要注意SQLite 在无状态函数中运行时需要将数据库文件读写到持久化存储中如 Vercel 的 Blob Storage这比传统部署更复杂一些。对于看板这种有状态应用传统服务器或容器部署通常是更直接的选择。5.2 数据备份与迁移因为数据都在一个data.db文件里备份极其简单手动备份直接复制data.db文件即可。自动备份可以写一个简单的 cron 任务定期将data.db文件压缩并上传到云存储如 AWS S3、Backblaze B2。迁移如果你想从一台服务器迁移到另一台只需将data.db文件和应用程序一起复制过去。确保新环境的 Node.js 版本兼容即可。5.3 性能考量与优化建议对于中小规模团队的使用默认性能绰绰有余。但如果卡片数量变得非常庞大例如上万张可能需要考虑优化前端虚拟滚动当前card-list.tsx会渲染一个列表下的所有卡片。如果单个列表内有成百上千张卡片会导致 DOM 节点过多影响页面性能。可以引入虚拟滚动库如virtua来只渲染可视区域内的卡片。API 分页目前GET /api/board是一次性拉取所有数据。对于超大型看板可以考虑为卡片列表实现分页查询但要注意这会影响拖拽排序的体验因为你需要动态加载更多卡片。数据库索引确保在lists(position),cards(list_id, position)上建立索引可以大幅加快排序和查询速度。better-sqlite3在初始化时就可以创建索引。6. 常见问题排查与实战技巧在实际把玩和设想集成过程中我总结了一些可能会遇到的问题和技巧。6.1 开发与运行问题速查表问题现象可能原因解决方案pnpm install失败提示better-sqlite3编译错误Node.js 版本过低或缺少系统编译工具如python,make,g。1. 确保 Node.js 20。2. 在 macOS 上安装 Xcode Command Line Tools (xcode-select --install)。3. 在 Ubuntu/Debian 上安装build-essential(sudo apt-get install build-essential)。4. 在 Windows 上可能需要安装windows-build-tools(以管理员身份运行npm install --global windows-build-tools)。运行pnpm run dev后页面空白或报错端口冲突或前端资源构建失败。1. 检查终端输出看是否有错误信息。2. 默认端口是 5173尝试访问http://localhost:5173。3. 查看浏览器开发者控制台 (Console) 的具体报错。拖拽功能在移动端或某些浏览器上不工作HTML5 拖拽 API 在不同平台和浏览器上的支持度有差异。1. 这是该 API 的已知限制。对于需要广泛移动端支持的生产环境可以考虑引入第三方拖拽库如dnd-kit它提供了更一致和强大的跨平台拖拽体验。但这需要重写use-drag.ts和相关的组件逻辑。修改了schema.sql但数据库没更新schema.sql只在数据库文件首次创建时执行。1. 停止应用。2. 删除data.db文件。3. 重新启动应用它会用新的 schema 重建数据库。注意这会丢失所有数据对于生产环境你需要编写数据库迁移脚本如使用kysely等迁移工具。代理模式 (?agenttrue) 下某些操作无效前端组件可能没有正确接收到isAgentMode参数。1. 检查client/app.tsx中的 URL 参数解析逻辑。2. 确保context.tsx正确地将isAgentMode传递给了所有需要区分的组件如card.tsx,list-footer.tsx。6.2 集成与二次开发技巧作为 NPM 包嵌入如果你只想使用其看板 UI 组件可以尝试将client/目录下的逻辑打包成一个独立的库。但这需要较大的改造包括将后端 API 调用抽象为可配置的适配器。更简单的方式是直接 fork 项目将其作为你项目的一个子模块git submodule或直接复制源代码进行定制。样式隔离当你把这个看板嵌入到现有 SaaS 页面时可能会发生样式冲突。建议在项目的根组件或主要容器上添加一个特定的 CSS 类名如open-kanban-container并将所有看板相关的 CSS 规则都嵌套在这个类名下这样可以有效避免样式污染。状态管理项目使用了 Preact Context 进行简单的全局状态管理。对于更复杂的状态交互如撤销/重做、实时协作Context 可能力有不逮。届时可以考虑引入更专门的状态管理库如Zustand或Jotai它们与 Preact/React 集成得很好且概念简单。实现实时同步当前应用是“请求-响应”模式多个浏览器标签页之间不会自动同步更改。要实现 Trello 那样的实时体验你需要引入 WebSocket。可以在后端 Hono 应用中集成ws库每当看板数据有变更时广播给所有连接的客户端。前端则需要监听 WebSocket 消息并更新 Context 中的状态。这个项目提供了一个坚实、优雅的起点。它没有过度设计每一行代码都围绕着“实现一个可自托管的、好用的看板”这个核心目标。无论是直接使用还是作为你下一个项目管理工具的基石clawnify/open-kanban都展示了如何用现代且简洁的技术栈解决一个实际的问题。我最欣赏的是它对“双模式UI”的思考这提醒我们在设计工具时不仅要考虑人类用户也要为自动化伙伴留好接口。