企业官网建设流程全解析

Focalboard Personal Edition 部署实战指南：桌面端、Ubuntu 服务器与 Docker 全流程解析

【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboard

Focalboard 是一个开源、可自托管的项目管理与协作平台（仓库描述为 "an open source, self-hosted alternative to Trello, Notion, and Asana"）。本指南以官方文档 Personal Edition 为核心，系统讲解其个人版（Personal Edition）的三条落地路径：Personal Desktop 桌面端、基于 Ubuntu 的 Personal Server、以及 Docker 一键部署，并结合仓库内的 Dockerfile、config.json、server/services/config/config.go 等源码与配置，深入剖析服务端参数含义、数据库选型（SQLite / PostgreSQL / MySQL）与 NGINX 反向代理细节。读完本文，你将能够独立完成 Focalboard 个人版的安装、配置、数据库切换、TLS 加固、systemd 服务化以及版本升级。

Personal Edition 概览：三种运行形态怎么选

官方文档 Personal Edition 索引页 将个人版划分为三种形态，适用场景各不相同：

三种形态的取舍原则很清晰：

• 如果你是 Focalboard 新手，官方文档明确建议：Personal Desktop 是尝试它的最快方式（"Personal Desktop is the fastest way to try it out"）。
• 如果需要在团队中使用，则应转向 Mattermost Boards（参见 Mattermost Boards 文档），并支持将 Personal Desktop 中的看板导入到 Mattermost Boards。
• 如果需要独立运行一个开发或自用服务器，则在 Ubuntu 或 Docker 上搭建 Personal Server。

从仓库结构可以印证这三条路径的存在：mac/（macOS 原生壳）、win-wpf/（Windows WPF 壳）、linux/与webapp/（Web 前端）对应桌面/客户端形态；server/目录（Go 语言实现的 API、存储、认证等）对应服务端形态；docker/目录则提供了完整的多阶段构建镜像方案。

Personal Desktop：单用户自包含桌面应用

Personal Desktop 是官方文档定义的"fully contained, standalone app meant for a single user"，即完全自包含、面向单用户的独立应用，特点是安装快、无需服务器与数据库。

官方文档给出的安装途径：

• macOS：从 Mac App Store 下载 Focalboard。
• Windows：从 Microsoft App Store 下载，或从最新 release 中下载focalboard-win.zip。
• Linux Desktop：
  1. 从最新 release 下载focalboard-linux.tar.gz；
  2. 解压该 tar.gz 归档；
  3. 打开focalboard-app文件夹内的focalboard-app可执行文件即可运行。

从仓库源码看，桌面端本质上是"Web 前端 + 本地壳"的架构：mac/Focalboard/ViewController.swift与CustomWKWebView.swift说明 macOS 端通过 WKWebView 承载 Web 应用，并配套PortUtils.swift（本地端口分配）与AutoSaveWindowController.swift（自动保存）；win-wpf/Focalboard/MainWindow.xaml.cs与Webview2Installer.cs则表明 Windows 端基于 WPF + WebView2。也就是说，桌面版复用的是 webapp/src 同一套 React/TypeScript 前端代码，只是打包载体不同——这解释了为何它可以做到"完全自包含、单机即用"。

Personal Server（Ubuntu）：从零搭建独立服务端

Personal Server 是官方文档定位的"standalone server for development and personal use"。下面是 ubuntu.md 的完整落地流程，按阶段拆解并补充底层原理。

准备一台 Ubuntu Server

文档以Ubuntu Server 18.04为例（仓库年代对应的 LTS 版本），常见托管选项包括 Digital Ocean、Amazon EC2、Linode，均可按各自平台指引完成初始服务器配置。如果你要升级已有安装，请直接参考升级指南。

安装 Focalboard 服务端

从 GitHub release 页下载 Ubuntu 归档包（文档示例使用v0.15.0，实际请以 release 列表中的最新版为准）：

wget https://github.com/mattermost/focalboard/releases/download/v0.15.0/focalboard-server-linux-amd64.tar.gz tar -xvzf focalboard-server-linux-amd64.tar.gz sudo mv focalboard /opt

解压后，服务端二进制位于/opt/focalboard/bin/focalboard-server，Web 静态资源位于/opt/focalboard/pack，配置文件为/opt/focalboard/config.json。这与仓库内 config.json 中的"webpath": "./webapp/pack"以及 Dockerfile 中COPY --from=nodebuild ... /webapp/pack pack/的目录约定一致。

安装并配置 NGINX 反向代理

为什么需要 NGINX？官方文档说明：Focalboard 服务端默认监听8000 端口（由 config.json 的port指定），推荐用 NGINX 作为 Web 代理，把 80 端口的 http 与 websocket 请求转发到 8000。

sudo apt update sudo apt install nginx

创建站点配置：

sudo nano /etc/nginx/sites-available/focalboard

粘贴如下配置（完整继承自原文档，注意location ~ /ws/*块专门处理 WebSocket 升级）：

upstream focalboard { server localhost:8000; keepalive 32; } server { listen 80 default_server; server_name focalboard.example.com; location ~ /ws/* { proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; client_max_body_size 50M; proxy_set_header Host $http_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_set_header X-Frame-Options SAMEORIGIN; proxy_buffers 256 16k; proxy_buffer_size 16k; client_body_timeout 60; send_timeout 300; lingering_timeout 5; proxy_connect_timeout 1d; proxy_send_timeout 1d; proxy_read_timeout 1d; proxy_pass http://focalboard; } location / { client_max_body_size 50M; proxy_set_header Connection ""; proxy_set_header Host $http_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_set_header X-Frame-Options SAMEORIGIN; proxy_buffers 256 16k; proxy_buffer_size 16k; proxy_read_timeout 600s; proxy_cache_revalidate on; proxy_cache_min_uses 2; proxy_cache_use_stale timeout; proxy_cache_lock on; proxy_http_version 1.1; proxy_pass http://focalboard; } }

两个 location 块的分工值得注意：

• location ~ /ws/*：Focalboard 的实时协同依赖 WebSocket（仓库中 server/ws 目录实现了服务端 WebSocket 适配器）。这里通过Upgrade/Connection "upgrade"头完成协议升级，并将读写超时放宽到 1 天（proxy_connect_timeout 1d等），避免长连接被 Nginx 掐断。
• location /：普通 HTTP 请求，client_max_body_size 50M限制上传体积（对应文件上传场景），proxy_cache_revalidate on、proxy_cache_lock on等开启静态缓存优化。

如果存在默认站点，先删除再启用新站点并重载：

sudo rm /etc/nginx/sites-enabled/default sudo ln -s /etc/nginx/sites-available/focalboard /etc/nginx/sites-enabled/focalboard sudo nginx -t sudo /etc/init.d/nginx reload

配置 TLS 加密（生产必做）

官方文档明确警告：生产服务器必须配置 TLS，否则登录密码与数据在网络上裸露传输。推荐参考 NGINX 官方 TLS 终止指南与 Let's Encrypt Certbot 指南完成证书签发与配置。这一步是"文档原话级别的安全要求"，部署到公网时不可跳过。

数据库选型：SQLite / PostgreSQL / MySQL

Focalboard 默认使用SQLite存储数据，但官方文档明确推荐生产环境使用PostgreSQL（文档时代测试过的版本为 Postgres 10.15），MySQL 则作为替代方案。仓库中 docker-testing/ 目录同时提供了 MariaDB、MySQL、PostgreSQL 三套 compose 测试编排，印证三种数据库均为受支持后端。

方式一：PostgreSQL（推荐）

sudo apt install postgresql postgresql-contrib

以 postgres 用户进入 psql 创建库与用户（请把 user/password 替换成自己的值）：

sudo --login --user postgres psql

CREATE DATABASE boards; CREATE USER boardsuser WITH PASSWORD 'boardsuser-password'; \q

exit

编辑配置文件：

nano /opt/focalboard/config.json

将 db 相关配置改为：

"dbtype": "postgres", "dbconfig": "postgres://boardsuser:boardsuser-password@localhost/boards?sslmode=disable&connect_timeout=10"

这个 DSN 的组成：postgres://用户:密码@主机/库名?sslmode=disable&connect_timeout=10。connect_timeout=10限制建连超时，sslmode=disable表示本地连接不启用 TLS（公网场景应自行评估是否启用 SSL）。对照 docker/config.json 可以看到完全一致的连接串形态（postgres://boardsuser:boardsuser-password@focalboard-db/boards?...）。

方式二：MySQL（备选）

sudo apt-get install mysql-server sudo mysql

CREATE DATABASE boards; GRANT ALL on boards.* to 'boardsuser'@'localhost' identified by 'boardsuser-password';

exit

同样编辑/opt/focalboard/config.json：

"dbtype": "mysql", "dbconfig": "boardsuser:boardsuser-password@tcp(127.0.0.1:3306)/boards"

MySQL 特有的排序规则（collation）注意事项（原文档重点提示，务必保留）：

• 使用 MySQL 时，官方推荐使用 collation 而非 charset；
• 必须使用utf8mb4系列排序规则，例如未指定时默认使用utf8mb4_general_ci；
• 如果此前以 Mattermost Plugin 形式使用 Focalboard（0.9 版本之前），必须确保focalboard_前缀表的 collation 与 mattermost 表的 collation一致，否则可能出现字符集不一致导致的异常。

配置 systemd 服务：开机自启与崩溃重启

为了让服务器跨重启持续运行，创建 systemd unit：

sudo nano /lib/systemd/system/focalboard.service

[Unit] Description=Focalboard server [Service] Type=simple Restart=always RestartSec=5s ExecStart=/opt/focalboard/bin/focalboard-server WorkingDirectory=/opt/focalboard [Install] WantedBy=multi-user.target

关键点：Type=simple匹配 Go 服务端单进程直启的特性；Restart=always+RestartSec=5s实现崩溃后 5 秒自动拉起；WorkingDirectory=/opt/focalboard保证相对路径（./data/focalboard.db、./files等）解析正确。然后：

sudo systemctl daemon-reload sudo systemctl start focalboard.service sudo systemctl enable focalboard.service

验证服务是否正常

curl localhost:8000 curl localhost

• 第一条命令验证 Focalboard 服务端在默认 8000 端口运行；
• 第二条命令验证 NGINX 代理是否成功转发；
• 官方文档说明：两条命令应返回相同的 HTML 片段。

远程访问时，在浏览器打开服务器的 IP 或域名即可。后续的服务器初始化（创建管理员、配置团队等）请参考仓库官方 server setup 指南 完成。

Personal Server（Docker）：单行命令快速部署

官方 Docker 方案只需一条命令即可运行最新版 Personal Server：

docker run -it -p 80:8000 mattermost/focalboard

然后浏览器打开http://localhost。若 80 端口被占用，可显式指定端口：

docker run -it -p <port>:8000 mattermost/focalboard

这条命令的本质可以从 docker/Dockerfile 还原出来——官方镜像是一个三阶段构建产物：

1. Webapp 构建阶段：node:16.3.0环境中对 webapp 执行npm install && npm run pack，产出静态资源到pack/；
2. Go 构建阶段：golang:1.18.3环境中执行make server-docker，产出服务端二进制；
3. 最终镜像：基于debian:buster-slim，将静态资源与二进制复制到/opt/focalboard，以nobody用户运行，EXPOSE 8000/tcp（另暴露 9092 供 Prometheus 指标），声明VOLUME /opt/focalboard/data，入口为/opt/focalboard/bin/focalboard-server。

镜像内默认配置文件是 docker/server_config.json，其默认dbtype为sqlite3、dbconfig为./data/focalboard.db——即默认把 SQLite 数据落在挂载卷/opt/focalboard/data中，从而实现容器重建后数据不丢失。

需要手动定制（如切换数据库、改端口）时，官方文档建议：按 Ubuntu 手动搭建指南 的步骤自行配置。仓库同时提供了开箱即用的扩展编排文件：

• docker/docker-compose.yml：单服务 + 命名卷fbdata，将容器 8000 映射到宿主机 80；
• docker/docker-compose-db-nginx.yml：推荐的生产化组合——focalboard-db（PostgreSQL，库boards、用户/密码boardsuser/boardsuser-password）+jwilder/nginx-proxy反向代理 + Focalboard 应用，并通过./config.json:/opt/focalboard/config.json把宿主配置注入容器（该文件正是仓库根目录的 config.json，其dbtype为postgres，dbconfig指向focalboard-db主机名）。这与 Ubuntu 手动搭建中的"PostgreSQL + NGINX"架构完全对应。

服务端配置参数深度解析

无论哪种部署方式，最终都落到一份 JSON 配置。仓库根目录 config.json 是完整示例，其字段结构由 server/services/config/config.go 中的Configuration结构体定义（字段带json与mapstructure双标签，说明配置同时支持 JSON 文件与环境变量两种来源）。核心参数如下：

从源码结构可以推断（config.go 中FilesDriver与AmazonS3Config并存），文件存储支持"本地磁盘 + S3 兼容对象存储"两种后端；SessionExpireTime与SessionRefreshTime共同控制 Web 会话生命周期，30 天过期 + 5 小时刷新是一个典型的"长会话 + 滚动续期"组合。修改这些参数后需要重启focalboard.service（或重建容器）才能生效。

升级 Personal Server：保留数据的安全升级流程

官方 升级指南 针对此前按 Ubuntu 指南搭建的安装，给出了完整的升级步骤（示例版本为 v0.9.2，实际以 release 最新版为准）：

# 1. 下载新版本归档包 wget https://github.com/mattermost/focalboard/releases/download/v0.9.2/focalboard-server-linux-amd64.tar.gz tar -xvzf focalboard-server-linux-amd64.tar.gz # 2. 停止服务 sudo systemctl stop focalboard.service # 3. 备份旧版本 sudo mv /opt/focalboard /opt/focalboard-old sudo mv focalboard /opt # 4. 迁移数据与配置：上传文件目录 + 配置文件 sudo mv /opt/focalboard-old/files /opt/focalboard sudo cp /opt/focalboard-old/config.json /opt/focalboard # 5. 启动服务 sudo systemctl start focalboard.service # 6.（可选）验证无误后删除备份 sudo rm -rf /opt/focalboard-old

升级要点解读：

• 必须迁移两份关键数据：files（用户上传的附件）与config.json（数据库连接、端口等既有配置）。注意官方流程只迁移这两项，而 SQLite 数据库文件本身位于 WorkingDirectory 之外的数据目录，需确认你的安装实际存放位置后再行处置；
• 建议在干净目录中解压或先删除旧安装包，避免新旧文件混用；
• 升级完成后先验证服务正常，再删除/opt/focalboard-old备份。

常见问题与排障思路

1. curl localhost与curl localhost:8000返回不一致：说明 NGINX 代理链路有问题，检查/etc/nginx/sites-available/focalboard的proxy_pass http://focalboard;与 upstream 定义，并确认sudo nginx -t通过、已执行 reload。
2. WebSocket 无法实时同步：确认 NGINX 的/ws/*location 配置了Upgrade/Connection "upgrade"头；Focalboard 的实时功能依赖 server/ws 提供的 WebSocket 通道。
3. 切换数据库后服务启动失败：检查dbconfig连接串格式（Postgres 需postgres://前缀，MySQL 需user:pass@tcp(host:port)/db），确认数据库已创建、用户权限正确，并留意 MySQL 的utf8mb4collation 要求。
4. 容器数据丢失：docker run时未挂载/opt/focalboard/data卷，SQLite 数据随容器销毁。务必使用-v挂载或采用 docker-compose.yml 中的命名卷方案。
5. 生产环境未配置 TLS：登录密码与数据明文传输，属于官方文档明确警告的安全隐患，务必配置 Let's Encrypt 证书。

总结

围绕 Personal Edition，本文完整覆盖了官方文档的全部部署路径与配置要点：

• Personal Desktop：单用户、自包含桌面应用，是快速体验 Focalboard 的最短路径；
• Personal Server（Ubuntu）：服务端二进制 + NGINX 反向代理（含 WebSocket 转发）+ TLS + PostgreSQL/MySQL 数据库 + systemd 常驻，构成一套完整的自托管方案；
• Personal Server（Docker）：docker run -it -p 80:8000 mattermost/focalboard单行启动，docker-compose-db-nginx.yml 提供"PostgreSQL + Nginx 代理"的生产化参考；
• 配置与升级：以 config.json 和 config.go 为基准理解全部参数；升级时务必迁移files目录与config.json。

后续如需团队协作、私有看板与团队沟通能力，官方文档指向 Mattermost Boards（见 Mattermost 文档），并支持将 Personal Desktop 的看板导入其中——这为从"个人版"迈向"团队版"提供了平滑的升级通道。

【免费下载链接】focalboardFocalboard is an open source, self-hosted alternative to Trello, Notion, and Asana.项目地址: https://gitcode.com/GitHub_Trending/fo/focalboard