focalboard 是轻量开源看板工具，linux 一键部署需下载预编译 focalboard-server 二进制（勿用 npm），注意架构匹配、端口占用、config.json 路径、data 目录权限及反代时加 --no-https-redirect；nginx 需透传请求头；systemd 服务必须设好 workingdirectory、user 和 --no-https-redirect 参数。

focalboard 是开源的自托管看板工具，轻量、无数据库依赖（默认用 SQLite）、适合中小团队做项目管理。它不依赖复杂后端，但部署时容易卡在「启动失败」「访问 404」「端口不通」几个点上。

---

怎么安装 focalboard（Linux 一键部署）

官方提供预编译二进制包，**不要用 npm install -g focalboard** —— 那是旧版前端开发包，不是服务端可执行程序。

直接下载对应架构的 focalboard-server 二进制文件（推荐 amd64）：

curl -LO https://github.com/mattermost/focalboard/releases/download/vv1.12.0/focalboard-server-linux-amd64.tar.gz
tar -xzf focalboard-server-linux-amd64.tar.gz
chmod +x focalboard-server

验证能否运行：

./focalboard-server --help

如果报错 no such file or directory: ./focalboard-server，大概率是缺少 libc 或架构不匹配（比如在 ARM 服务器上硬跑 amd64 包），换用 focalboard-server-linux-arm64。

---

focalboard-server 启动失败常见原因

直接运行 ./focalboard-server 后没输出、进程秒退，通常有以下几种情况：

• 端口被占用：默认监听 :8000，用 lsof -i :8000 或 ss -tuln | grep 8000 检查；
• 配置文件路径错误：focalboard-server 默认找当前目录下的 config.json，若不存在会静默失败；
• SQLite 目录无写权限：默认数据存在 ./data，确保当前用户对 data/ 有读写权限；
• 没加 --no-https-redirect 却用了反向代理（如 Nginx）：此时服务会尝试跳转 HTTPS，导致前端白屏或 301 循环。

---

怎么配反向代理让外网能访问（Nginx + 域名）

别把 focalboard-server 暴露在公网端口上，必须套一层 Nginx。关键点不是“转发”，而是“透传请求头”和“关闭重定向”：

在 /etc/nginx/sites-available/focalboard 中写：

Linux installer

先解析安全源，运行本地CLI安装、启动、卸载Linux桌面应用。用户请求时使用。

下载

server {
    listen 80;
    server_name kb.example.com;
<pre class="brush:php;toolbar:false;">location / {
    proxy_pass http://127.0.0.1:8000;
    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_redirect off;
}

}

然后启动服务前，**必须加参数**：

./focalboard-server --no-https-redirect --config config.json

否则 Nginx 转发过来的 HTTP 请求会被服务端强行 301 到 HTTPS，前端加载 JS/CSS 404。

---

怎么用 systemd 管理服务（开机自启 + 日志追踪）

手动运行不靠谱，必须注册为系统服务。注意三点：工作目录、用户权限、环境变量。

新建 /etc/systemd/system/focalboard.service：

[Unit]
Description=FocalBoard Server
After=network.target
<p>[Service]
Type=simple
User=focalboard
Group=focalboard
WorkingDirectory=/opt/focalboard
ExecStart=/opt/focalboard/focalboard-server --config /opt/focalboard/config.json --no-https-redirect
Restart=on-failure
RestartSec=10
StandardOutput=journal
StandardError=journal</p><p>[Install]
WantedBy=multi-user.target</p>

操作步骤：

• 先创建专用用户：sudo useradd --system --no-create-home --shell /usr/sbin/nologin focalboard；
• 把 focalboard-server 和 config.json 放到 /opt/focalboard/，并 chown -R focalboard:focalboard /opt/focalboard；
• 启用服务：sudo systemctl daemon-reload && sudo systemctl enable --now focalboard；
• 查日志：sudo journalctl -u focalboard -f，比 tail -f 更可靠。

最容易被忽略的是 WorkingDirectory —— 缺失会导致 config.json 找不到、data/ 创建在根目录下、甚至 SQLite 文件权限混乱。