Kanboard 看板部署：从克隆仓库到打开登录页的完整流程

【免费下载链接】kanboardKanban project management software项目地址: https://gitcode.com/gh_mirrors/ka/kanboard

Kanboard 是一款轻量级的看板项目管理工具，用"列 + 卡片"的看板组织任务进度。这篇走源码部署路线：从克隆仓库到浏览器里看到登录页，一共 5 个实操步骤，其中数据库配置和目录权限是两处最容易踩坑的环节。不想动环境的话，可以直接跳到 Docker 一键启动小节。

场景与适用判断

Kanboard 是自托管的看板项目管理软件：建项目、把任务卡片在列间拖动代表进度，附带自动化规则、子任务、时间跟踪和邮件通知。按 README.md 的说明，项目目前处于维护模式，功能稳定但不再新增大特性，选型时要有这个预期。

适合个人和小团队自建内网看板、不想依赖 SaaS 的场景，也适合手里已有 Linux 服务器、熟悉 Apache/Nginx 的开发者。不适合需要甘特图、多级审批流的团队——Kanboard 的功能边界刻意收敛在看板方法论内。

后端是 PHP 写的，依赖用 Composer 管理，这就是为什么下面要装 Composer；数据库默认 SQLite，可换 MySQL 或 PostgreSQL；仓库同时提供了 Docker 镜像方案。

环境自检清单

逐条跑下面的命令确认依赖，一行出结果：

走 Docker 方案的话，只需docker -v确认容器环境可用即可。

部署实操

拿到代码

把源码放到服务器上，以下示例以/var/www/kanboard为根目录：

git clone https://gitcode.com/gh_mirrors/ka/kanboard cd kanboard

注意：Kanboard 的 Web 入口是仓库根目录的index.php，不存在独立的 public 目录，这一点直接影响后面 Web 服务器的写法。

装依赖

因为后端是 PHP，依赖必须经 Composer 安装，vendor/目录会被 index.php 间接加载：

composer install --no-dev

本仓库已自带vendor/目录，确认文件完整可以跳过这步；缺失的话配好 Composer 镜像源再执行。

写数据库配置

默认驱动是 SQLite，数据库文件自动落在data/db.sqlite，这一档什么都不用改。要换 MySQL 的话，把 config.default.php 复制为data/config.php（app/common.php 优先加载该文件），只改数据库这几行：

define('DB_DRIVER', 'mysql'); define('DB_HOSTNAME', 'localhost'); define('DB_USERNAME', 'kanboard'); define('DB_PASSWORD', '你的密码'); define('DB_NAME', 'kanboard');

别直接改config.default.php，官方约定是整份复制再修改。PHP 侧对应的 pdo_mysql 或 pdo_pgsql 扩展也要提前开启，否则app/check_setup.php会直接报错。

让 Web 服务指向它

站点根目录指向仓库根目录，由.htaccess把所有请求重写到index.php，data/.htaccess 负责屏蔽数据目录的直接访问。Apache 最小配置：

<VirtualHost *:80> ServerName kanboard.local DocumentRoot /var/www/kanboard <Directory /var/www/kanboard> AllowOverride All Require all granted </Directory> </VirtualHost>

Nginx 用户则手写等价规则。AllowOverride All必须给，否则.htaccess不生效，页面会 403 或 404，这一步容易踩坑：

server { listen 80; root /var/www/kanboard; index index.php; location / { try_files $uri $uri/ /index.php$is_args$args; } location ~ ^/(data|app|libs|vendor)/ { return 404; } location ~ \.php$ { include fastcgi_params; fastcgi_pass unix:/run/php/php8.1-fpm.sock; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; } }

其中return 404那行不能省，它保证源码和数据库文件不会被浏览器直接下载。

放开目录权限

数据库、缓存和上传文件全部落在 data/ 目录，Web 服务用户必须可写：

chown -R www-data:www-data /var/www/kanboard/data chmod -R 755 /var/www/kanboard/data

www-data换成你系统的实际 Web 用户，Nginx 环境下常见的还有nginx。

Docker 一键启动（备选）

仓库根目录自带现成的 docker-compose.sqlite.yml，一条命令拉起：

docker compose -f docker-compose.sqlite.yml up -d

数据落在命名卷里不会丢，docker logs kanboard可看运行日志；换 MySQL 部署就把文件换成docker-compose.mysql.yml。

跑通验证与排错

成功的样子：浏览器打开http://kanboard.local/，首次访问出现管理员账号创建页，填完用户名和密码提交，即可进入项目列表，整个链路跑通。命令行也可以借仓库里的健康检查接口确认：

curl http://kanboard.local/healthcheck.php

返回{"status":200,"message":"Database connection is OK"}即数据库连通正常。

高频报错与对策：

• 403 Forbidden：Apache 没给AllowOverride All，或data/目录权限没放开，检查虚拟主机配置并补跑 chown 命令。
• 500 或提示 "PHP extension required"：缺 pdo_sqlite、gd、mbstring 等扩展，用php -m核对清单，装齐后重启 PHP-FPM 和 Web 服务。
• 数据库连接失败（用 MySQL 时）：data/config.php里的DB_*与实际不符，或 pdo_mysql 未启用，逐项核对账号密码。
• 后台任务不执行：定时任务没有挂 cron，给 crontab 加一行每分钟执行php /var/www/kanboard/cli cronjob。

下一步

• 登录后先建第一个项目，Kanboard 会初始化"待办 / 进行中 / 完成"三列默认看板。
• 往列里添加任务卡片、指派成员，拖列即改状态，活动时间线自动记录。
• 项目的"自动化"配置里可以设"卡片移入某列后自动分配成员"之类的规则。
• 更多功能细节以仓库 README.md 指向的官方文档为准。

【免费下载链接】kanboardKanban project management software项目地址: https://gitcode.com/gh_mirrors/ka/kanboard