聊到看板工具，很多团队第一反应是Trello、Notion或者国内的Worktile一类SaaS。用起来确实省事，但有个绕不开的问题：你的项目数据全在别人服务器上，免费版的功能被砍得七七八八，稍微上规模的团队就得按人头订阅。我自己一直有自托管习惯，找了一圈开源看板项目，最后选中了4ga Boards。它是个用ASP.NET Core + Angular写的开源看板工具，有看板、清单、标签、截止日期、附件、评论、活动记录这些核心功能，操作手感很像Trello。最关键的是，官方提供了Docker镜像，一条命令就能在自己服务器上跑起来，数据完全自己掌控。今天这篇就完整记录我用Docker部署4ga Boards的思路和踩坑过程，给想自托管看板工具的朋友一份可以直接照着做的参考。
1. 为什么最终选了4ga Boards：自托管看板工具的选型复盘
1.1 自托管看板到底解决了什么问题
先别急着上手部署，说清楚需求再选型，后面才不会白折腾。我当时的使用场景是一个五六人的小项目组，需要管理迭代任务、Bug流转和需求池，对实时协作的要求不算高，但有三条硬性条件：数据不能出内网、不想按人头订阅付费、希望有清爽的看板交互而不是一堆自定义字段搞得比Excel还复杂。
满足"自托管"三个字的开源看板其实不少，我前后试过WeKan、Focalboard、Planka，最后才定下4ga Boards。WeKan是老牌，功能确实全，但界面停留在十年前，成员权限颗粒度细到反而难配置；Focalboard是Notion收购的产物，界面漂亮，但更新节奏不稳定，插件体系也比较封闭，想二次开发不太方便；Planka的交互不错，可依赖的组件比较多，单容器部署体验一般，升级时容易遇到前端资源对不上的情况。
4ga Boards能胜出，本质上是赢在三件事上：
- 部署足够简单。官方Docker镜像已经把ASP.NET Core运行时和Angular前端静态文件全部打进去了，容器内一个进程搞定，不用自己折腾Nginx托管静态资源，也不用装Node环境去编译前端。
- 数据层灵活。默认SQLite开箱即用，需要上规模时随时可以切到PostgreSQL或MySQL，不需要改代码，改环境变量就行。
- 交互自然。拖拽卡片、层级列表、成员头像、标签筛选这些高频操作都做得很顺，团队成员从Trello迁移过来几乎零学习成本。
1.2 核心功能与适用规模
4ga Boards的功能定位很清晰：做团队任务看板，而不是万能项目管理平台。它没有甘特图、没有工时统计、没有复杂的权限矩阵，但看板该有的都有：多看板管理、列表与卡片拖拽、标签颜色自定义、成员分配、检查清单、截止日期、附件上传、评论讨论、操作活动日志。对做迭代研发、内容排期、个人任务管理这三个场景，这些功能完全够用。
从实际资源占用来看，默认SQLite模式下，单容器内存占用大概两三百兆，CPU平时几乎可以忽略。这个体量放在一台2核4G的小服务器上绰绰有余，甚至树莓派跑起来也没压力。我自己的体验是：十人以内团队、每天几百次操作，SQLite完全不会成为瓶颈；如果团队超过二十人，或需要多人高频并发写同一个看板，再考虑切PostgreSQL。
1.3 几张选型对比表，省得你再趟一遍
我选型时列过一个对照表，整理如下，不一定绝对客观，但都是我实际部署用过之后的感受：
| 项目 | 部署复杂度 | 界面交互 | 数据存储 | 社区活跃度 | 我的评价 |
|---|---|---|---|---|---|
| 4ga Boards | 极简，单容器 | 接近Trello | SQLite/PostgreSQL/MySQL等 | 中上 | 综合体验最均衡 |
| WeKan | 中等，依赖较多 | 较老旧 | MongoDB | 老牌稳定 | 功能重但颜值劝退 |
| Focalboard | 简单 | 很现代 | SQLite/PostgreSQL | 更新不稳 | 用起来像半成品 |
| Planka | 中等 | 现代 | PostgreSQL | 一般 | 单容器方案不够省心 |
如果你只是自己用、两个人用，选哪个其实无所谓，看界面喜好就行。但如果是要给团队长期用、还要考虑升级维护成本，我的建议很直接：优先考虑4ga Boards这种"一个容器一个服务"的方案，运维负担越小，工具的生命力越长。
2. 部署前必须搞清楚的三个底层细节：数据目录、环境变量与镜像验证
2.1 数据存储：SQLite文件落在哪里
动手敲命令之前，我强烈建议你先搞清楚一件事：这个工具的数据到底写在哪里。很多Docker部署翻车，都是因为只做了端口映射，没做数据挂载，容器一删数据全没。
4ga Boards默认使用SQLite数据库，镜像里有一个数据目录专门存放SQLite数据库文件，官方镜像的标准路径是/data。当然，不同版本对这个目录的处理会有细节差异，所以我的习惯是先拉镜像，然后立刻用docker inspect确认一下：
docker pull 4ga/boards:latest docker inspect 4ga/boards:latest | grep -A1 VOLUME镜像声明的Volume信息会直接告诉你官方推荐挂哪里，照着做就不会错。把宿主机的目录或Docker命名卷挂到这个路径，数据库文件持久化就算搞定了。
另外还要提醒一下：4ga Boards上传的附件文件也是存在这个数据目录下的，不是只存路径。所以这个目录同时承担了数据库和附件存储两个职责，备份时一定都得带上。
2.2 环境变量：连接串和JWT密钥
4ga Boards是ASP.NET Core应用，熟悉.NET的人都知道它的配置体系是分层的：环境变量里用双层下划线__表示配置层级冒号，比如SECRETS__JWTTOKEN对应的就是配置项SECRETS:JWTTOKEN。
部署时需要关注的环境变量主要有两个：
| 环境变量名 | 作用 | 说明 |
|---|---|---|
CONNECTIONSTRINGS__CONNECTION | 数据库连接串 | 不设置时默认用SQLite并写入/data目录 |
SECRETS__JWTTOKEN | 登录令牌签名密钥 | 生产环境务必显式设置成长随机串 |
JWT密钥这个我多说一句。很多人觉得"反正有默认值，不设也能跑"，确实能跑，但如果你不设置，它在容器重启时可能使用固定的默认签名，或者产生我们没法预期的行为。更安全的做法是：第一次部署时就生成一个64位以上的随机字符串，写进compose文件里，以后别随便改。因为一旦改了，所有已登录用户的令牌会立即失效，大家得重新登录一次，虽然不致命，但会影响使用体验。
2.3 架构确认：为什么这个镜像只有一个端口
第一次用这个镜像的人可能会疑惑：前端后端不分离吗？怎么只有一个80端口？
4ga Boards镜像的做法是：ASP.NET Core的后端服务同时托管Angular编译后的静态文件。也就是说，页面路由和/api接口走的都是同一个HTTP服务。容器里只跑一个进程，对外只暴露一个80端口。
这个架构带来的好处是部署简单，坏处是如果你习惯把静态资源单独扔给Nginx托管，反而容易出问题。我后面讲反代会细说，这里你只需要记住：默认情况下一整个请求路径都转发给容器即可，不需要做静态/动态拆分。
3. 两条部署路线：从一条命令跑通到compose正式落地
3.1 第一条路：docker run快速体验
如果你只是想先看看这个工具长什么样，一条命令就够了：
docker run -d \ --name boards \ -p 8080:80 \ -v boards-data:/data \ --restart unless-stopped \ 4ga/boards:latest解释一下这几个参数，省得你复制完不知道什么意思：
-d：后台运行。--name boards：给容器起个名字，后续管理方便。-p 8080:80：把容器内80端口映射到宿主机8080端口。你宿主机上如果80被占了，换一个就行。-v boards-data:/data：创建一个名为boards-data的Docker命名卷，挂到容器的/data目录。这一步直接决定了你的数据能不能持久化，千万别省。--restart unless-stopped：容器异常退出时自动重启，服务器重启后也会跟着起来。适合长时间运行的Web服务。
跑起来之后，浏览器访问http://宿主机IP:8080就能看到登录页。先注册一个账号，4ga Boards的规则是：第一个注册成功的用户自动获得管理员权限，之后可以到用户管理里把注册开关关掉，避免陌生人来注册。
想确认容器状态和日志，用这两条命令：
docker ps docker logs -f boards3.2 第二条路：docker compose按生产标准落地
docker run适合临时验证，正式给团队用，我建议直接用compose。compose的好处是把配置固化成文件，以后升级、迁移、重建都只要一条命令，不用背一长串docker run参数。
下面是我实际在用的docker-compose.yml，你复制以后需要改的就是密码串：
services: boards: image: 4ga/boards:latest container_name: boards restart: unless-stopped ports: - "8080:80" volumes: - boards-data:/data environment: SECRETS__JWTTOKEN: "please_change_this_to_a_long_random_string_at_least_32_chars" volumes: boards-data:启动命令：
docker compose up -d这里我不建议在环境变量里设置CONNECTIONSTRINGS__CONNECTION，除非你确定要换数据库。保持默认SQLite反而是最稳的起步方式，后面需要再改，不用推倒重来。
3.3 初始化验证：确认数据确实写进了卷
部署完别急着走，我习惯做三步验证：
- 访问登录页，确认页面正常渲染，注册第一个账号并登录。
- 创建一个测试看板，加两张卡片，确认拖拽正常。
- 进入容器确认数据文件已经生成：
docker exec -it boards sh ls -la /data看到/data目录下有数据库文件和附件上传目录，就说明数据持久化链路是通的。这一步做完，你再怎么docker compose down、up都不会丢东西。
4. 数据持久化进阶：从SQLite换到PostgreSQL，以及备份恢复
4.1 SQLite的边界在哪里
默认SQLite模式下，整个数据库就一个文件，备份极其简单，这也是我推荐小团队起步用SQLite的原因。但你要留意它的边界：SQLite适合低并发写入，如果团队人数增多、多个成员同时在看板上高频操作，可能会出现数据库锁等待，表现为操作偶尔卡顿。
什么时候该换PostgreSQL？我的经验判断标准是：活跃用户超过十五人，或者看板卡片总数超过几千张且附件很多，或者你本身就是搞运维的，希望用熟悉的PostgreSQL生态统一管理。这时候换数据库收益很明显。
4.2 compose里加入PostgreSQL服务的完整方案
切换PostgreSQL不需要改任何应用代码，只需要给compose增加一个数据库服务，再给boards服务设置连接串环境变量。我的生产compose长这样：
services: db: image: postgres:16-alpine container_name: boards-db restart: unless-stopped environment: POSTGRES_USER: boards POSTGRES_PASSWORD: "choose_a_strong_db_password" POSTGRES_DB: boards volumes: - db-data:/var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U boards -d boards"] interval: 5s timeout: 5s retries: 12 boards: image: 4ga/boards:latest container_name: boards restart: unless-stopped ports: - "8080:80" volumes: - boards-data:/data environment: CONNECTIONSTRINGS__CONNECTION: "Host=db;Port=5432;Database=boards;Username=boards;Password=choose_a_strong_db_password" SECRETS__JWTTOKEN: "please_change_this_to_a_long_random_string_at_least_32_chars" depends_on: db: condition: service_healthy volumes: boards-data: db-data:有几个细节我要特意说明：
- 连接串的格式是Npgsql风格，分号分隔，写成
Host=数据库主机名;Port=端口;Database=库名;Username=用户名;Password=密码。这里的Host=db指compose里数据库服务的服务名，不是"填写某个IP"。 depends_on加condition: service_healthy很重要。没有这一步，boards可能先启动，此时PostgreSQL还没就绪，连接失败后容器直接退出；加了健康检查，数据库就绪前boards不会启动，避免凭运气启动。- 即使改用PostgreSQL，
/data卷也还是保留挂载，因为附件文件仍然存储在应用的数据目录里，别试图省掉这个卷。
MySQL同样支持，连接串改成Server=db;Port=3306;Database=boards;Uid=boards;Pwd=密码即可。但个人建议优先PostgreSQL，生态和稳定性都更好。
4.3 备份与恢复的实操命令
备份这件事，我建议从一开始就做，别等数据丢了再后悔。分两种场景：
SQLite模式备份
SQLite虽然可以热备份，但直接在运行中复制db文件有极小概率复制到写入中的坏数据。稳妥做法是先停容器再复制：
docker stop boards docker cp boards:/data/boards.db ./boards-$(date +%F).db docker start boardsPostgreSQL模式备份
用pg_dump，不停库也能安全备份：
docker exec boards-db pg_dump -U boards -d boards > boards-$(date +%F).sql恢复时反过来：
docker exec -i boards-db psql -U boards -d boards < boards-2025-01-01.sql最后一定要把备份文件从服务器上拷贝走，否则服务器硬盘挂了，备份和原数据一起没了。我在部署时顺手把备份命令写成了一个cron脚本，每天凌晨执行，意外恢复时才知道这个习惯多值钱。
5. 让团队真正用起来：局域网访问、反向代理与日常维护
5.1 端口映射与局域网访问
容器跑起来之后，首先解决"别人怎么访问"的问题。如果你们在同一局域网，防火墙放行宿主机8080端口即可：
sudo ufw allow 8080/tcp然后团队成员直接用http://内网IP:8080访问。这里有个易错点：尽量别用localhost分发给同事，他们会访问自己的电脑。要填服务器在局域网里的IP，用ip addr查一下就行。
如果服务器在云上，则要在云控制台的安全组里放行对应端口。Windows用户如果用的是Docker Desktop而不是Linux服务器，注意Docker Desktop的端口映射默认绑定在宿主机上，局域网能不能访问取决于Windows防火墙是否放行，这一层和容器本身无关，排查时不要搞混。
5.2 Nginx反向代理与HTTPS部署
内网直连只适合测试，正式用建议在前面加一层Nginx反代，好处是：统一入口、可以上HTTPS证书、以后想换端口或加访问控制都方便。
我的Nginx配置片段如下：
server { listen 80; server_name kanban.example.com; client_max_body_size 50m; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } }几个关键点解释一下：
client_max_body_size 50m：4ga Boards支持上传附件，默认Nginx上传大小限制是1m，不调这个的话附件稍微大点就报413。Upgrade和Connection "upgrade"：这是给实时同步类长连接用的。你在看板上操作，其他成员希望页面自动更新，如果反代把这几个头丢了，实时刷新就会失效，只能手动刷新页面。- 一整段都转发给后端，不要单独拆静态资源。原因在第二章说过，这个镜像的前端本来就是后端托管的，拆开反而添乱。
配置好后重载Nginx：
sudo nginx -t sudo systemctl reload nginxHTTPS直接用certbot上证书，两步搞定：
sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d kanban.example.com证书会自动续期，之后访问https://kanban.example.com就是加密连接了。
5.3 日常维护：镜像更新与数据迁移
自托管工具最怕的就是"装完就不管了"，我一般每月做一次例行维护，流程很固定：
- 先备份数据，方法见第四章。
- 拉取新镜像：
docker compose pull - 重启服务：
docker compose up -d - 打开页面做一遍冒烟测试：登录、看板操作、附件上传。
4ga Boards在启动时会自动执行数据迁移逻辑，所以升级版本一般不用手动改数据库结构。但升级前还是强烈建议看一眼官方更新说明，如果版本跨度大，先备份再升，给自己留条后路。
6. 排错记录：我在部署中遇到的四个真实问题
6.1 Docker Desktop虚拟化没开导致"容器还没跑就输了"
这条严格说不算4ga Boards的问题，但很多Windows用户第一次部署Docker项目就卡在这一步，我见过太多了。现象是启动Docker Desktop直接弹错：Docker Desktop failed to start because virtualization support is not detected。
原因基本都是CPU虚拟化没开或Windows虚拟化功能没启用。排查顺序是：
- 重启进BIOS/UEFI，确认Intel VT-x（或AMD-V）处于开启状态。
- 控制面板里启用"适用于Windows的虚拟机监控程序平台"和"Hyper-V"（新版Docker Desktop用WSL2则确保启用Windows Subsystem for Linux）。
- 执行
systeminfo看底部"Hyper-V要求"一栏，确认四项都显示"是"。
这几个步骤看起来简单，但网上大多数"启动Docker失败"的求助都绕在这条路上。如果你是Linux服务器，就不会遇到这问题，直接跳过。
6.2 挂载目录权限不对导致容器反复重启
用过bind mount的人应该有印象：把宿主机的某个目录挂进去，数据库文件死活写不进去，容器一直restarting。看日志会看到类似unable to open database file的报错。
原因很直接：容器内的进程没有目标目录的写权限。如果用的是Docker命名卷，Docker会自动初始化权限，一般不会遇到；但你一旦图省事在compose里写成./data:/data这种相对路径的bind mount，宿主机目录的属主和容器内进程的UID对不上，就会踩坑。
我的建议是：刚开始用阶段直接上命名卷，别纠结bind mount。如果项目要求数据目录在宿主机上可见，那就根据镜像内进程的UID把目录属主改对再启动。排查指令docker logs boards永远是你第一个想到的命令，日志会给足线索。
6.3 连接串写错导致数据库连不上
换PostgreSQL时报错的原因，我遇到过两类最典型：
第一类是环境变量名拼写不对。ASP.NET Core的配置读取是严格的，CONNECTIONSTRINGS__CONNECTION中间是两个下划线，写成单下划线或者大小写不对，应用可能根本读不到你的连接串，然后它又默默回退到SQLite。你看着好像数据库服务都正常，但数据其实还在SQLite里，让人非常迷惑。
第二类是连接串里的主机名。我见过有人把Host=db改成Host=127.0.0.1的，这是在宿主机上连自己的数据库，当然连不上。在compose网络里，服务名就是主机名，db指的就是数据库服务，不需要填IP。
6.4 反代之后实时刷新失效或页面刷新404
这两个问题会一起出现，原因也在第二章埋下了。如果你把静态资源拆分给Nginx托管、只把/api转发给容器，那么访问根路径时Nginx找自己的静态目录，刷新某个看板详情页时Nginx按路径匹配找文件，找不到就404，同时实时长连接也没法正确建立。
我自己的解决方式很简单：整站都转发，不拆分。页面路由和API统一走后端，SPA的路由由后端正确兜底返回首页，刷新自然不会404。如果配置没问题还是404，检查一下Nginx里location是否误加了对后缀文件的处理规则，比如try_files写得不合适。
7. 用了两个月之后的一些真实体会
两个月用下来，这个工具在我这边的定位已经固定成"团队默认任务协作入口"。印象最深的几点：一个是它足够轻，扔在内网的一台小机器上完全没存在感，不像某些大平台光内存就吃掉几个G；另一个是团队成员迁移几乎无感，用Trello的人过来第一天就能上手。
如果非要说槽点，我觉得它的移动端体验比较朴素，适合应急查看，不适合长时间在手机上操作看板。另外中文界面覆盖得比较全，但个别事项描述还是英文，对完全不懂英文的人有一点点门槛，好在不影响使用。
如果你也想搭一套自己的看板系统，我的建议是先从默认SQLite跑起来，数据卷一定挂好，JWT密钥一定设好，这两件事做了，后面所有调整都是平滑的。等真有需要，再按我第四章的方案切PostgreSQL，整个过程不用停机太久，成本并不高。能把自己团队的任务数据彻底攥在自己手里，这个换来的安心感，值得折腾这一次。
