Docker 镜像: ghcr.io/akvicor/kanban
Kanban 是一个自托管的个人看板，后端 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 Compose（SQLite）
SQLite 不需要额外的数据库服务，是最简单的部署方式。新建一个目录，写入 docker-compose.yml：
services:
kanban:
image: ghcr.io/akvicor/kanban:latest
container_name: kanban
restart: unless-stopped
environment:
# 初始管理员，只在库中还没有用户时使用
KANBAN_ADMIN_USERNAME: admin
KANBAN_ADMIN_PASSWORD: change-me-please
volumes:
- ./data:/data
ports:
- "3000:3000"启动
docker compose up -d容器启动时会依次做这几件事：
data/config.yaml不存在时，自动生成一份默认配置；执行
migrate，创建或升级表结构；库中还没有用户时，按环境变量创建初始管理员；启动服务。
数据库文件、附件和配置都在 data 目录中，备份时备份这个目录即可。打开 http://localhost:3000，用上面的管理员账号登录。
初始管理员
第一次启动时必须提供
KANBAN_ADMIN_USERNAME和KANBAN_ADMIN_PASSWORD。库中没有用户又没有提供这两个变量时，migrate会报错，容器无法启动。用户名 1 到 32 个字符，不能包含空白字符；密码至少 8 个字符。
管理员创建完成后，这两个变量就不再起作用，可以从配置中删掉。其他账号由管理员在「用户管理」中创建。
Docker Compose（PostgreSQL）
使用 PostgreSQL 时，需要先准备配置文件，让 Kanban 知道数据库的连接方式：
mkdir -p data
curl -fsSL -o data/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.2
restart: unless-stopped
environment:
POSTGRES_DB: kanban
POSTGRES_USER: kanban
POSTGRES_PASSWORD: change-me-before-start
volumes:
- postgres-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U kanban -d kanban"]
interval: 5s
timeout: 5s
retries: 12
kanban:
image: ghcr.io/akvicor/kanban:latest
container_name: kanban
restart: unless-stopped
environment:
KANBAN_ADMIN_USERNAME: admin
KANBAN_ADMIN_PASSWORD: change-me-please
volumes:
- ./data:/data
ports:
- "3000:3000"
depends_on:
postgres:
condition: service_healthy
volumes:
postgres-data:附件仍然保存在 data 目录中，备份时需要同时备份 data 目录和 PostgreSQL 数据。
二进制运行
在 Releases 下载对应系统的 kanban-<系统>-<架构>.tar.gz，目前提供 Linux 和 macOS 的 amd64 / arm64 版本。checksums.txt 中是各文件的 SHA-256 校验值。
tar -xzf kanban-linux-amd64.tar.gz
cd kanban-linux-amd64
# 生成默认配置，-p 指定数据目录
mkdir -p data
./kanban example -p ./data/ -c > ./data/config.yaml
# 创建或升级表结构，并创建初始管理员
KANBAN_ADMIN_USERNAME=admin KANBAN_ADMIN_PASSWORD=change-me-please \
./kanban migrate -c ./data/config.yaml
./kanban server -c ./data/config.yaml也可以从源码构建，需要 Go 1.26 和 Node.js 24：
git clone https://github.com/Akvicor/kanban.git
cd kanban
make build # 产出 build/kanban，前端已嵌入升级
使用 Docker 时，拉取新镜像后重新创建容器即可，容器每次启动都会先执行 migrate：
docker compose pull
docker compose up -d使用二进制时，替换文件后务必先执行 kanban migrate 再启动服务。服务启动时不会自动升级表结构，跳过这一步会在使用新功能时出错。
配置
SQLite 的完整示例：
app-name: Kanban
debug: false
server:
http-ip: 0.0.0.0
http-port: 3000
web-path: build
enable-https: false
crt-file: /data/cert/example.com.crt
key-file: /data/cert/example.com.key
# 受信任的反向代理地址（CIDR 或单个 IP）
trusted-proxies: []
database:
type: sqlite
file: /data/kanban.db
storage:
path: /data/files
log:
enable-file: false
file: /data/kanban.log反向代理
一般会把 Kanban 放在 Nginx 后面，由 Nginx 处理 HTTPS。需要注意三件事：
实时同步使用 WebSocket，路径是
/api/sync/ws，需要转发Upgrade和Connection头。附件按分片上传，每片 8MB（服务端上限 16MB），
client_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 发送。在「通知渠道」中添加渠道：
API：gmsg 服务的地址，可以是内网地址；不带
?和#，请求发往<API>/api/send。Token、Sign：gmsg 中对应的发送凭据。
内容格式：文本或 Markdown。
渠道页可以发送测试消息，确认能收到后再给卡片设置提醒。提醒和截止的正文模板支持占位符，Markdown 渠道可以对插入的内容做转义，避免卡片标题里的特殊字符破坏格式。
服务停机期间到点的提醒，会在恢复后补发；发送失败会自动重试，失败时记录 HTTP 状态码和 gmsg 返回的错误信息。
桌面客户端
除了浏览器和 PWA，还可以使用桌面客户端 kanban-app。客户端是一个 Electron 外壳：窗口直接加载你的 Kanban 服务器，页面、接口和实时同步都由服务器提供，服务器升级后界面随之更新，客户端本身很少需要更新。
在 Releases 下载对应系统的安装包：
安装包没有使用开发者证书签名，首次打开时系统会提示：
macOS：在「系统设置 → 隐私与安全性」中点「仍要打开」，或执行
xattr -dr com.apple.quarantine /Applications/Kanban.app。Windows：在「Windows 已保护你的电脑」提示中点「更多信息 → 仍要运行」。
首次启动时输入服务器地址，例如 https://kanban.example.com，客户端会通过健康检查接口确认这是 Kanban 服务器再打开。之后可以在菜单「更换服务器地址」中切换服务器，各服务器的登录状态分别保存。
Windows 和 Linux 上菜单栏默认隐藏，按 Ctrl+Shift+M 显示或隐藏。这是客户端唯一自带的快捷键，其余按键都交给看板网页，不会和 Kanban 的快捷键冲突。站外链接会在系统浏览器中打开。
使用建议
个人使用直接选 SQLite，一个容器、一个
data目录，备份最省事。第一次启动一定要设置
KANBAN_ADMIN_USERNAME和KANBAN_ADMIN_PASSWORD，管理员创建完成后可以把它们删掉。对外提供访问时放在 HTTPS 反向代理后面，并填写
server.trusted-proxies。反向代理要转发 WebSocket，并调大
client_max_body_size。生产环境建议固定镜像版本，确认更新内容后再升级。
使用二进制部署时，每次升级先执行
kanban migrate。设备 90 天内没有任何请求或同步连接时，登录会失效，需要重新登录。