项目仓库: https://github.com/Akvicor/kanban桌面客户端: https://github.com/Akvicor/kanban-app个人博客: https://www.ksyaki.com/archives/kanban-zi-tuo-guan-de-ge-ren-ji-hua-yu-dai-ban-kan-banDocker 镜像:ghcr.io/akvicor/kanbanKanban是一个自托管的个人看板后端 Go、前端 React使用 GPLv3 协议开源。功能五层结构文件夹 → 看板 → 面板标签页→ 列表 → 卡片。文件夹最多嵌套 16 层各层都可以拖动调整顺序。实时同步所有修改通过 WebSocket 立即推送到同一用户的其他设备。卡片内容Markdown 描述、多选标签、优先级、三层任务、附件、关联跳转、定时器和操作记录。图片、PDF、音视频和文本附件可以在线预览。列表规则卡片在列表中创建、移入、移出时可以自动调整标签和开始 / 完成时间每个列表可以单独设置排序。提醒与截止到点通过 gmsg 发送通知。服务停机期间错过的提醒恢复后补发发送失败自动重试。归档看板、面板、列表、卡片四级归档进入归档后可以查看和恢复。附件管理附件按 sha256 全局去重存储按引用计数管理同一用户重复上传同一个文件时秒传。搜索筛选面板内按标题、描述、标签、优先级、成员、日期筛选「只看今日」把非今日的卡片变灰。响应式与 PWA电脑、平板、手机三档布局可以添加到手机主屏全屏使用提供清爽、暗夜、纸感三套配色。中英双语在个人设置中切换界面语言或跟随系统通知内容使用相同语言。多用户管理员创建账号各用户数据互相隔离用户名、昵称、密码、时区、快捷键各自修改。界面看板目录侧栏卡片详情暗夜配色手机上的布局部署镜像ghcr.io/akvicor/kanban支持linux/amd64和linux/arm64。latest指向最新正式版也可以指定版本例如ghcr.io/akvicor/kanban:v0.1.9。Docker ComposeSQLiteSQLite 不需要额外的数据库服务是最简单的部署方式。新建一个目录写入docker-compose.ymlservices:kanban:image:ghcr.io/akvicor/kanban:latestcontainer_name:kanbanrestart:unless-stoppedenvironment:# 初始管理员只在库中还没有用户时使用KANBAN_ADMIN_USERNAME:adminKANBAN_ADMIN_PASSWORD:change-me-pleasevolumes:-./data:/dataports:-3000:3000dockercompose up-d容器启动时会依次做这几件事data/config.yaml不存在时自动生成一份默认配置执行migrate创建或升级表结构库中还没有用户时按环境变量创建初始管理员启动服务。数据库文件、附件和配置都在data目录中备份时备份这个目录即可。打开http://localhost:3000用上面的管理员账号登录。初始管理员第一次启动时必须提供KANBAN_ADMIN_USERNAME和KANBAN_ADMIN_PASSWORD。库中没有用户又没有提供这两个变量时migrate会报错容器无法启动。用户名 1 到 32 个字符不能包含空白字符密码至少 8 个字符。管理员创建完成后这两个变量就不再起作用可以从配置中删掉。其他账号由管理员在「用户管理」中创建。Docker ComposePostgreSQL使用 PostgreSQL 时需要先准备配置文件让 Kanban 知道数据库的连接方式mkdir-pdatacurl-fsSL-odata/config.yaml https://raw.githubusercontent.com/Akvicor/kanban/main/config.postgres.yaml.example# 修改 data/config.yaml 中 database.password与下面的 POSTGRES_PASSWORD 保持一致services:postgres:image:postgres:17.2restart:unless-stoppedenvironment:POSTGRES_DB:kanbanPOSTGRES_USER:kanbanPOSTGRES_PASSWORD:change-me-before-startvolumes:-postgres-data:/var/lib/postgresql/datahealthcheck:test:[CMD-SHELL,pg_isready -U kanban -d kanban]interval:5stimeout:5sretries:12kanban:image:ghcr.io/akvicor/kanban:latestcontainer_name:kanbanrestart:unless-stoppedenvironment:KANBAN_ADMIN_USERNAME:adminKANBAN_ADMIN_PASSWORD:change-me-pleasevolumes:-./data:/dataports:-3000:3000depends_on:postgres:condition:service_healthyvolumes:postgres-data:附件仍然保存在data目录中备份时需要同时备份data目录和 PostgreSQL 数据。二进制运行在 Releases 下载对应系统的kanban-系统-架构.tar.gz目前提供 Linux 和 macOS 的 amd64 / arm64 版本。checksums.txt中是各文件的 SHA-256 校验值。tar-xzfkanban-linux-amd64.tar.gzcdkanban-linux-amd64# 生成默认配置-p 指定数据目录mkdir-pdata ./kanban example-p./data/-c./data/config.yaml# 创建或升级表结构并创建初始管理员KANBAN_ADMIN_USERNAMEadminKANBAN_ADMIN_PASSWORDchange-me-please\./kanban migrate-c./data/config.yaml ./kanban server-c./data/config.yaml也可以从源码构建需要 Go 1.26 和 Node.js 24gitclone https://github.com/Akvicor/kanban.gitcdkanbanmakebuild# 产出 build/kanban前端已嵌入升级使用 Docker 时拉取新镜像后重新创建容器即可容器每次启动都会先执行migratedockercompose pulldockercompose up-d使用二进制时替换文件后务必先执行kanban migrate再启动服务。服务启动时不会自动升级表结构跳过这一步会在使用新功能时出错。配置配置文件为 YAML分为四段段说明server监听地址、端口、HTTPS 证书、受信任的反向代理databasesqlite或postgres以及对应的连接参数storage附件、缩略图和未完成上传的存放目录log日志文件开关、级别和输出标志SQLite 的完整示例app-name:Kanbandebug:falseserver:http-ip:0.0.0.0http-port:3000web-path:buildenable-https:falsecrt-file:/data/cert/example.com.crtkey-file:/data/cert/example.com.key# 受信任的反向代理地址CIDR 或单个 IPtrusted-proxies:[]database:type:sqlitefile:/data/kanban.dbstorage:path:/data/fileslog:enable-file:falsefile:/data/kanban.log反向代理一般会把 Kanban 放在 Nginx 后面由 Nginx 处理 HTTPS。需要注意三件事实时同步使用 WebSocket路径是/api/sync/ws需要转发Upgrade和Connection头。附件按分片上传每片 8MB服务端上限 16MBclient_max_body_size要调大否则上传会被 Nginx 拒绝。在配置的server.trusted-proxies中填写 Nginx 的地址。Kanban 只从这些地址转发的X-Forwarded-For中读取客户端 IP登录限流按这个 IP 计数不填时所有请求看起来都来自 Nginx。server { listen 443 ssl; server_name kanban.example.com; ssl_certificate /etc/nginx/cert/example.com.crt; ssl_certificate_key /etc/nginx/cert/example.com.key; client_max_body_size 32m; location /api/sync/ws { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_read_timeout 1h; } location / { proxy_pass http://127.0.0.1:3000; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }Nginx 和 Kanban 跑在同一台机器上、Kanban 在 Docker 中时容器看到的来源地址是 Docker 网桥的网关地址trusted-proxies要填这个地址例如172.17.0.1或对应网段。需要 HTTPS 的另一个原因是 PWA浏览器只允许在 HTTPS 下把网页添加为可以全屏使用的应用。通知提醒和截止通知通过 gmsg 发送。在「通知渠道」中添加渠道APIgmsg 服务的地址可以是内网地址不带?和#请求发往API/api/send。Token、Signgmsg 中对应的发送凭据。内容格式文本或 Markdown。渠道页可以发送测试消息确认能收到后再给卡片设置提醒。提醒和截止的正文模板支持占位符Markdown 渠道可以对插入的内容做转义避免卡片标题里的特殊字符破坏格式。服务停机期间到点的提醒会在恢复后补发发送失败会自动重试失败时记录 HTTP 状态码和 gmsg 返回的错误信息。桌面客户端除了浏览器和 PWA还可以使用桌面客户端 kanban-app。客户端是一个 Electron 外壳窗口直接加载你的 Kanban 服务器页面、接口和实时同步都由服务器提供服务器升级后界面随之更新客户端本身很少需要更新。在 Releases 下载对应系统的安装包系统安装包Linux.AppImage加执行权限后直接运行或.debamd64 / arm64Windows.exeamd64macOS.dmgApple 芯片选arm64Intel 芯片选amd64安装包没有使用开发者证书签名首次打开时系统会提示macOS在「系统设置 → 隐私与安全性」中点「仍要打开」或执行xattr -dr com.apple.quarantine /Applications/Kanban.app。Windows在「Windows 已保护你的电脑」提示中点「更多信息 → 仍要运行」。首次启动时输入服务器地址例如https://kanban.example.com客户端会通过健康检查接口确认这是 Kanban 服务器再打开。之后可以在菜单「更换服务器地址」中切换服务器各服务器的登录状态分别保存。Windows 和 Linux 上菜单栏默认隐藏按CtrlShiftM显示或隐藏。这是客户端唯一自带的快捷键其余按键都交给看板网页不会和 Kanban 的快捷键冲突。站外链接会在系统浏览器中打开。使用建议个人使用直接选 SQLite一个容器、一个data目录备份最省事。第一次启动一定要设置KANBAN_ADMIN_USERNAME和KANBAN_ADMIN_PASSWORD管理员创建完成后可以把它们删掉。对外提供访问时放在 HTTPS 反向代理后面并填写server.trusted-proxies。反向代理要转发 WebSocket并调大client_max_body_size。生产环境建议固定镜像版本确认更新内容后再升级。使用二进制部署时每次升级先执行kanban migrate。设备 90 天内没有任何请求或同步连接时登录会失效需要重新登录。