企业官网建设流程全解析

• 项目仓库: 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-ban

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:latestcontainer_name:kanbanrestart:unless-stoppedenvironment:# 初始管理员，只在库中还没有用户时使用KANBAN_ADMIN_USERNAME:adminKANBAN_ADMIN_PASSWORD:change-me-pleasevolumes:-./data:/dataports:-"3000:3000"

dockercompose up-d

容器启动时会依次做这几件事：

1. data/config.yaml不存在时，自动生成一份默认配置；
2. 执行migrate，创建或升级表结构；库中还没有用户时，按环境变量创建初始管理员；
3. 启动服务。

数据库文件、附件和配置都在data目录中，备份时备份这个目录即可。打开http://localhost:3000，用上面的管理员账号登录。

初始管理员

• 第一次启动时必须提供KANBAN_ADMIN_USERNAME和KANBAN_ADMIN_PASSWORD。库中没有用户又没有提供这两个变量时，migrate会报错，容器无法启动。
• 用户名 1 到 32 个字符，不能包含空白字符；密码至少 8 个字符。
• 管理员创建完成后，这两个变量就不再起作用，可以从配置中删掉。其他账号由管理员在「用户管理」中创建。

Docker Compose（PostgreSQL）

使用 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:3000"depends_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_USERNAME=adminKANBAN_ADMIN_PASSWORD=change-me-please\./kanban migrate-c./data/config.yaml ./kanban server-c./data/config.yaml

也可以从源码构建，需要 Go 1.26 和 Node.js 24：

gitclone https://github.com/Akvicor/kanban.gitcdkanbanmakebuild# 产出 build/kanban，前端已嵌入

升级

使用 Docker 时，拉取新镜像后重新创建容器即可，容器每次启动都会先执行migrate：

dockercompose pulldockercompose up-d

使用二进制时，替换文件后务必先执行kanban migrate再启动服务。服务启动时不会自动升级表结构，跳过这一步会在使用新功能时出错。

配置

配置文件为 YAML，分为四段：

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 或单个 IP）trusted-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（服务端上限 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 天内没有任何请求或同步连接时，登录会失效，需要重新登录。