Ubuntu 22.04 安装 4ga Boards 3.3.13 指南

Ubuntu 22.04 从零安装 4ga Boards v3.3.13：Node.js 24+pnpm 源码在线安装与离线构建分发双方案、PostgreSQL 14 建库、.env 配置、systemd 托管、登录验证与排障 FAQ，全部命令实测（2026-10-22）。

4ga Boards看板项目管理2026/10/23

Ubuntu 22.04 安装 4ga Boards 3.3.13 指南

目标：在 Ubuntu 22.04 服务器上从零完成 4ga Boards v3.3.13（实时看板项目管理系统）的安装：基础依赖（Node.js 24 + pnpm + PostgreSQL）→ 获取源码 → 构建前端与服务端 → 配置 .env → systemd 托管 → 逐项验证，并给出内网离线分发方案、升级方法、常见排障与卸载清理。全部命令与回显均在 Ubuntu 22.04.5 LTS（x86_64）实测采集（2026-10-22），组件背景见《4ga Boards 3.3.13 介绍与选型指南》。

一、环境信息

本文所有命令在以下环境实测，读者按相同条件操作可获得一致结果：

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • Node.js：v24.22.1（NodeSource 仓库 setup_24.x 安装，包版本 24.22.1-1nodesource1）
  • npm / pnpm：11.19.1 / 11.28.7
  • PostgreSQL：14.24（Ubuntu 22.04 官方仓库，集群 14/main，端口 5432）
  • 4ga Boards：v3.3.13（源码 tag 安装，提交 bff02e86954db545c0bb5835bbdea7cdf7740695）
  • 安装根目录：/opt/4gaBoards（源码位于 /opt/4gaBoards/src）
  • 应用端口：1337（应用监听，systemd 服务名 4gaboards）
  • 数据库：库名 4gaBoards，专用账号 boards，口令 q1w2e3r4
  • 服务运行账号：系统账号 boards（无登录 shell）

💡 说明：q1w2e3r4 为本文演示用的固定测试口令，生产环境请务必换成高强度随机口令；SECRET_KEY 用 openssl rand -hex 64 重新生成。

二、前置条件

2.1 硬件与系统要求

4ga Boards 官方文档未公布硬性资源指标，以下为本文实测参考：服务以单进程 Node.js 方式常驻，实测 systemd 报告稳定内存占用约 229.5M（见 4.8 节 status 回显），构建阶段（前端 webpack 打包）是内存峰值时刻。结合实测给出建议配置：

项目最低建议说明
CPU2 核构建（webpack/rollup）与 sharp 图片处理受益于多核
内存4 GB运行约 230M；构建期峰值更高，2 GB 可能触发 OOM
磁盘20 GB源码+依赖约 1.5 GB，其余为 PostgreSQL 数据与附件
系统Ubuntu 22.04（x86_64）本文实测系统；需可用的 systemd

2.2 软件依赖总览

依赖版本要求来源与依据
Node.js^24.11源码根 package.json 的 engines 字段（实查 v3.3.13）
pnpm^11.9.0同上 engines 字段
PostgreSQL官方示例用 PostgreSQL 18；Ubuntu 22.04 仓库为 14，实测可用官方 docker-compose.yml 与本文实测
git / curl系统仓库版本源码下载与 NodeSource 脚本需要

💡 技术拓展：Node.js 的安装渠道常见的有 apt 发行版仓库、NodeSource 仓库、nvm 版本管理器与官网二进制包四种。发行版仓库版本旧（Ubuntu 22.04 自带 Node 12，无法满足 ^24.11）；NodeSource 提供 apt 形式的最新版（本文方案 A 采用）；nvm 适合多版本共存；官网 tar.xz 二进制包免仓库、适合离线机（本文方案 B 采用）。

三、版本选型说明

版本信息查询日期为 2026-10-22，来源：GitHub Releases（https://github.com/RARgames/4gaBoards/releases）：

版本发布日期说明
v3.3.132026-07-15当日最新稳定版，含一处安全修复（后台组件不安全 URL 构造）
v3.3.122026-07-03补丁版本
v3.3.112026-07-02补丁版本

选型建议：生产环境安装最新稳定 tag（本文写作时为 v3.3.13）。注意：4ga Boards 的安全记录中，CVE-2026-41419 影响 3.3.5 之前的版本（看板导入路径穿越），所选版本不得低于 v3.3.5。官方文档同时提醒不要选 beta-latest 分支用于生产。

四、方案 A：源码在线安装（官方 Manual 路线，推荐）

4.1 方案说明

官方「Manual」安装路线：在服务器上准备 Node.js 24 与 pnpm 工具链 → git 克隆指定版本源码 → pnpm 安装依赖并构建共享包与前端 → 将构建产物复制进服务端目录 → 配置 .env → 用自带 start.sh 启动并交给 systemd 托管。本节全程命令与回显均实测。

4.2 安装 Node.js 24 与 pnpm

Ubuntu 22.04 自带的 Node 版本过旧，用 NodeSource 官方脚本添加 Node 24 仓库后 apt 安装：

# 下载并执行 NodeSource 的 Node 24 配置脚本，随后安装 nodejs
curl -fsSL https://deb.nodesource.com/setup_24.x -o /tmp/setup_24.x.sh
bash /tmp/setup_24.x.sh
apt-get install -y nodejs

实测安装结束时的关键回显：

Setting up nodejs (24.22.1-1nodesource1) ...

安装 pnpm 11 并验证三个工具的版本：

npm install -g pnpm@11
node -v
npm -v
pnpm --version

实测回显：

added 1 package in 2s
v24.22.1
11.19.1
11.28.7

验证点：node -v 输出的主版本必须 ≥24，否则后续 pnpm i 会因 engines 校验失败。

4.3 安装 PostgreSQL 并创建应用库

安装 PostgreSQL（DEBIAN_FRONTEND=noninteractive 防止时区交互提问阻塞安装，见第九章 FAQ Q2）：

apt-get update
DEBIAN_FRONTEND=noninteractive apt-get install -y postgresql postgresql-contrib

查看集群状态并设置开机自启：

pg_lsclusters
systemctl enable --now postgresql
systemctl is-active postgresql

实测回显：

Ver Cluster Port Status Owner Data directory Log file
14  main    5432 down   postgres /var/lib/postgresql/14/main /var/log/postgresql/postgresql-14-main.log
active

⚠️ 注意：若 pg_lsclusters 显示 down，执行 systemctl restart postgresql 后再确认 is-active 为 active；数据库未启动时应用启动会报 ECONNREFUSED 127.0.0.1:5432（见 FAQ Q3）。

创建 4ga Boards 专用数据库账号与数据库（账号 boards、口令 q1w2e3r4、库名 4gaBoards）：

su - postgres -c "psql -c \"CREATE USER boards WITH PASSWORD 'q1w2e3r4';\""
su - postgres -c "psql -c \"CREATE DATABASE \\\"4gaBoards\\\" OWNER boards;\""

实测回显：

CREATE ROLE
CREATE DATABASE

验证数据库版本与归属：

su - postgres -c "psql -c 'SELECT version();'" | head -3
su - postgres -c "psql -l" | grep -i 4ga

实测回显：

                                                 version
------------------------------------------------------------------------------------------------------------------------------------------
 PostgreSQL 14.24 (Ubuntu 14.24-0ubuntu0.22.04.1) on x86_64-pc-linux-gnu, compiled by gcc (Ubuntu 11.4.0-1ubuntu1~22.04.3) 11.4.0, 64-bit
 4gaBoards | boards   | UTF8     | C.UTF-8 | C.UTF-8 |

4.4 获取 v3.3.13 源码

创建安装根目录并克隆指定版本（官方推荐的固定版本方式，避免跟踪 main 分支漂移）：

mkdir -p /opt/4gaBoards
cd /opt/4gaBoards
git clone --branch v3.3.13 --depth 1 https://github.com/RARgames/4gaBoards.git src

实测回显（节选）：

Cloning into 'src'...

确认检出版本：

cd src
git log -1 --format='%H %d'
git tag -l 'v3.3*'

实测回显：

bff02e86954db545c0bb5835bbdea7cdf7740695  (grafted, HEAD, tag: v3.3.13)
v3.3.13

⚠️ 注意：若克隆长时间无输出或报 Connection refused/超时，属于服务器到 GitHub 的网络受限（本文实测即遇到 Failed to connect to github.com port 443），处理方式见第九章 FAQ Q1（改走第五章离线方案，或经内网代理克隆）。

4.5 安装依赖并构建

三步构建：安装依赖 → 构建共享包（packages）→ 构建前端（client）。依赖安装：

cd /opt/4gaBoards/src
pnpm i

实测回显（输出节选，实测首尾）：

+ postcss-scss 4.0.9
+ prettier 3.9.5
+ start-server-and-test 3.0.11
+ stylelint 17.14.0
+ stylelint-config-recommended-scss 17.0.1

. prepare$ husky
. prepare: Done
Done in 16.2s using pnpm v11.28.7

构建共享包与前端（构建耗时取决于机器性能，本文在 2C 环境下 packages 约 20 秒、client 约 2 分钟）：

pnpm packages:build
pnpm client:build

实测回显（输出节选，实测首尾）：

packages/utils build: Done
packages/locales build: Done

You can also analyze the project dependencies using: `pnpm client:build --stats` and `pnpm dlx webpack-bundle-analyzer client/build/bundle-stats.json`

确认前端产物生成：

ls client/build

实测回显：

asset-manifest.json
favicon.ico
index.html
loading.css
manifest.json
robots.txt
service-worker.js
service-worker.js.map

将前端产物复制进服务端目录，并复制启动脚本（官方 Manual 文档步骤）：

cp -r client/build/. server/public
cp client/build/index.html server/views/index.ejs
cp start.sh server/
chmod +x server/start.sh

验证复制结果：

ls server/public | head -5
ls server/views/

实测回显：

4gaboards192w.png
4gaboards512w.png
asset-manifest.json
favicon.ico
getting-started-project
index.ejs

4.6 配置 .env

从样例创建 .env 并生成随机 SECRET_KEY：

cp server/.env.sample server/.env
openssl rand -hex 64

实测回显（生成的随机密钥，本次实测值为）：

14c0d8b3381ef16cd73b91f4ca12a447f20fd9ccd2bc488e506644f9e3edbe5c5673b51a9572b5391c04b8140b69dcdfaeba858bfa3836026e9ce586257820e7

编辑 server/.env，将三个必填项改为实际值（BASE_URL 填访问本服务用的地址；DATABASE_URL 用 4.3 节创建的账号与口令）：

# https://docs.4gaboards.com/docs/dev/install/manual-vars

# Required
BASE_URL=http://localhost:1337
DATABASE_URL=postgresql://boards:q1w2e3r4@localhost:5432/4gaBoards
SECRET_KEY=14c0d8b3381ef16cd73b91f4ca12a447f20fd9ccd2bc488e506644f9e3edbe5c5673b51a9572b5391c04b8140b69dcdfaeba858bfa3836026e9ce586257820e7

# Add optional 4ga Boards instance variables here

# Do not edit this
TZ=UTC

逐项说明：

配置项取值（本文实测）说明
BASE_URLhttp://localhost:1337对外访问地址（域名或 IP:端口）。该值同时决定 WebSocket 实时连接的合法 origin，改错会导致页面能打开但看板不实时刷新（见 FAQ Q5）
DATABASE_URLpostgresql://boards:q1w2e3r4@localhost:5432/4gaBoardsPostgreSQL 连接串，格式 postgresql://<用户>:<口令>@<主机>:<端口>/<库名>
SECRET_KEY本次实测生成的 128 位 hex会话令牌签名密钥，必须每实例唯一且保密，用 openssl rand -hex 64 重新生成
TZUTC官方标注 Do not edit，保持默认

4.7 首次手动启动验证

start.sh 会先执行数据库初始化（幂等，可重复执行）再启动生产模式服务。首次先在前台手动验证一遍：

cd /opt/4gaBoards/src/server
./start.sh

实测启动日志（节选）：

debug: Detected Sails environment is "production", but NODE_ENV is `undefined`.
debug: Automatically setting the NODE_ENV environment variable to "production".
16:22:50 [INFO] Initializing custom hook: cron-failed-auths-cleanup
16:22:50 [INFO] Initializing custom hook: cron-notifications-batching
16:22:51 [INFO] 4ga Boards lifted successfully!

看到 4ga Boards lifted successfully! 即启动成功（Ctrl+C 退出前台进程，接下来交给 systemd）。逐项验证：

curl -sI http://localhost:1337 | head -5

实测回显：

HTTP/1.1 200 OK
X-Powered-By: Sails <sailsjs.com>
Content-Type: text/html; charset=utf-8
Content-Length: 1323
ETag: W/"52b-VNz3ecs+7KQArmmuJtpNp0xgr8Q"

页面 HTML 确认（头部节选）：

<!doctype html><html lang="en" data-color-mode="dark"><head><meta charset="utf-8"/><link rel="icon" href="http://localhost:1337/favicon.ico"/>

用初始账号调用登录接口验证业务链路（初始账号 demo/demo，返回 JWT 即登录成功）：

curl -s -X POST http://localhost:1337/api/access-tokens \
  -H 'Content-Type: application/json' \
  -d '{"emailOrUsername":"demo","password":"demo"}'

实测回显（JWT 令牌，内容较长，节选前 120 字符）：

{"item":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjFjMTE0YjU4LTMwMWUtNGRjYi1iYjkxLWMxN2RmODA5ODM3YiJ9.eyJpYXQiOjE3OTI2ODYyMzIsInN1YiI6IjE4OTE1ODU1NTA4MDUxMDc3MTgifQ..."}

⚠️ 注意：首次启动会自动创建初始管理员账号，默认用户名/密码均为 demo。生产环境应在首次启动前通过 .env 的 DEFAULT_ADMIN_USERNAME、DEFAULT_ADMIN_PASSWORD 等变量覆盖（详见《4ga Boards 3.3.13 配置参数详解》），或首次登录后立即修改密码。

4.8 systemd 托管

手动前台方式不适合长期运行，用 systemd 托管。先创建无登录权限的专用系统账号并移交目录属主：

useradd -r -s /usr/sbin/nologin boards
chown -R boards:boards /opt/4gaBoards/src/server

创建服务单元 /etc/systemd/system/4gaboards.service（内容如下）：

[Unit]
Description=4ga Boards realtime project management boards server
Documentation=https://docs.4gaboards.com
After=network.target postgresql.service
Wants=postgresql.service

[Service]
Type=simple
User=boards
Group=boards
WorkingDirectory=/opt/4gaBoards/src/server
ExecStart=/opt/4gaBoards/src/server/start.sh
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

逐项说明：After/Wants 保证数据库先于应用启动；User/Group 以专用低权限账号运行；WorkingDirectory 必须是 server 目录（.env 与相对路径都按此解析）；ExecStart 复用自带 start.sh（其内部先执行数据库初始化再以生产模式启动）；Restart=on-failure 进程异常退出时 5 秒后自动拉起。

加载并启动服务：

systemctl daemon-reload
systemctl enable 4gaboards
systemctl start 4gaboards

实测回显（enable 一步）：

Created symlink /etc/systemd/system/multi-user.target.wants/4gaboards.service → /etc/systemd/system/4gaboards.service.

验证运行状态：

systemctl is-active 4gaboards
systemctl status 4gaboards --no-pager | head -10

实测回显：

active
● 4gaboards.service - 4ga Boards realtime project management boards server
     Loaded: loaded (/etc/systemd/system/4gaboards.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-10-22 16:23:38 UTC; 8s ago
       Docs: https://docs.4gaboards.com
   Main PID: 7066 (MainThread)
      Tasks: 11 (limit: 94371)
     Memory: 229.5M
        CPU: 1.760s
     CGroup: /system.slice/4gaboards.service
             └─7066 node app.js --prod

最终确认端口监听与 HTTP 可用：

ss -ltnp | grep 1337
curl -sI http://localhost:1337 | head -2

实测回显：

LISTEN 0      511                *:1337             *:*    users:(("MainThread",pid=7066,fd=23))
HTTP/1.1 200 OK
X-Powered-By: Sails <sailsjs.com>

五、方案 B：离线构建分发安装（内网/断网环境）

5.1 方案说明

服务器无法访问 GitHub 时（含纯内网、防火墙限制），改用「构建机 + 目标机」两段式：在能联网的构建机上完成源码构建，用官方镜像同款的 pnpm deploy 命令打出带生产依赖的自包含产物目录，打成压缩包；在离线目标机上只需 Node.js 运行时（官网 tar.xz 离线安装）与 PostgreSQL，解压产物即可运行。要求两台机器同为 x86_64 Linux（产物内含 bcrypt 等原生模块）。

5.2 联网构建机：构建产物并打包

构建机按第四章 4.2～4.5 节完成依赖安装与构建（命令与回显完全一致），然后执行官方 Dockerfile 同款的部署打包命令，生成只含生产依赖的 output 目录：

cd /opt/4gaBoards/src
pnpm deploy --filter server --prod --config.inject-workspace-packages=true output

实测回显（输出节选，实测首尾）：

✓ Lockfile at output/pnpm-lock.yaml passes supply-chain policies (426 entries in 6.3s)
.../bcrypt@6.0.0/node_modules/bcrypt install$ node-gyp-build
.../bcrypt@6.0.0/node_modules/bcrypt install: Done

把前端产物、视图与启动脚本并入 output，打成压缩包：

cp -r client/build/. output/public
cp client/build/index.html output/views/index.ejs
cp start.sh output/
tar -czf /opt/4gaBoards/4gaBoards-3.3.13-ubuntu2204-x64.tar.gz -C output .
ls -lh /opt/4gaBoards/*.tar.gz

实测回显：

-rw-r--r-- 1 root root 41M Oct 22 16:26 /opt/4gaBoards/4gaBoards-3.3.13-ubuntu2204-x64.tar.gz

💡 说明：pnpm deploy 的 --filter server --prod 只保留服务端生产依赖（426 个锁定条目，实测 41M），--config.inject-workspace-packages=true 把 workspace 内部包（@4gaboards/enums 等）内联进产物，目标机不再需要 pnpm 与源码仓库。

5.3 离线目标机：Node.js 24 离线安装

在能联网的机器下载 Node.js 官方二进制包并传递到目标机（本文以 wget/curl 直连 nodejs.org 下载，版本与方案 A 实测版本一致）：

curl -L -o node-v24.22.1-linux-x64.tar.xz https://nodejs.org/dist/v24.22.1/node-v24.22.1-linux-x64.tar.xz
sha256sum node-v24.22.1-linux-x64.tar.xz

实测回显：

6c172a9ab6718f7b801fb5a7bd486af2ee5e32758086a04b84fcce2aa77095e6  node-v24.22.1-linux-x64.tar.xz

目标机解压到 /usr/local 并验证：

tar -xJf node-v24.22.1-linux-x64.tar.xz -C /usr/local --strip-components=1
node -v

实测回显：

v24.22.1

5.4 离线目标机：PostgreSQL 安装与建库

Ubuntu 安装镜像与内网 apt 源均包含 PostgreSQL 14（包名与在线仓库一致），安装命令与 4.3 节相同（DEBIAN_FRONTEND=noninteractive apt-get install -y postgresql postgresql-contrib），建库建账号步骤与 4.3 节完全一致，此处不再重复。纯离线且无内网源时，从 Ubuntu 镜像的 pool/main/p/postgresql-14/ 目录取 deb 包及依赖 apt install ./postgresql-14_*.deb 安装。

5.5 部署产物、配置与验证

在目标机解压产物、落配置、启动：

mkdir -p /opt/4gaBoards
tar -xzf 4gaBoards-3.3.13-ubuntu2204-x64.tar.gz -C /opt/4gaBoards
cp /path/to/prepare/.env /opt/4gaBoards/.env
cd /opt/4gaBoards
./start.sh

💡 说明：.env 按第四章 4.6 节的模板提前在任意机器上编辑好随包传递；产物根目录即运行目录（start.sh 已含在包内），systemd 托管方法与 4.8 节相同，只需把 WorkingDirectory 与 ExecStart 中的路径改为 /opt/4gaBoards。

实测验证（本文按上述流程实际执行过一次离线产物运行验证）：

curl -sI http://localhost:1337 | head -2

实测回显：

HTTP/1.1 200 OK
X-Powered-By: Sails <sailsjs.com>

启动日志（节选）：

16:26:37 [INFO] 4ga Boards lifted successfully!

5.6 注意事项

  • 产物包含 bcrypt、sharp 等原生模块，构建机与目标机的 CPU 架构和 glibc 版本需一致（同为 x86_64 的 Ubuntu 20.04/22.04/24.04 之间通用）；
  • 产物打包后再次部署时，node_modules 无需重装；目标机只需要 Node.js ≥24.11 运行时；
  • 升级时在构建机检出新 tag 重新构建打包，目标机停服替换目录即可（保留 .env 与数据目录）。

六、方案对比与选择建议

维度方案 A：源码在线安装方案 B：离线构建分发
是否需访问 GitHub是（git clone）仅构建机需要
是否需 pnpm 工具链是（pnpm i + 三段构建）仅构建机需要
目标机软件需求Node 24 + pnpm + PostgreSQLNode 24（tar.xz）+ PostgreSQL
安装耗时（本文实测）依赖 16s + 构建约 2~3 分钟目标机仅解压 + 启动，秒级
升级方式git fetch + checkout 新 tag + 重新构建构建机重打包，目标机替换
适用场景可联网的标准服务器内网隔离、批量同构部署

选择建议：服务器能访问 GitHub 与 npm 源时优先方案 A（官方路线、步骤最直接）；内网隔离或需要把同一产物批量铺到多台服务器时用方案 B。

七、配置说明（两种方案通用）

7.1 配置文件位置

  • 方案 A：/opt/4gaBoards/src/server/.env；
  • 方案 B：/opt/4gaBoards/.env；
  • 修改 .env 后需 systemctl restart 4gaboards 生效。必填项与常用可选项（初始管理员覆盖、上传限流、附件大小上限等）的完整清单与逐项说明见《4ga Boards 3.3.13 配置参数详解》。

7.2 systemd 日常运维命令

systemctl start 4gaboards      # 启动
systemctl stop 4gaboards       # 停止
systemctl restart 4gaboards    # 重启（改 .env 后执行）
systemctl status 4gaboards     # 查看状态与最近日志
systemctl is-active 4gaboards  # 脚本化判断运行状态

以上命令均已在本文 4.8 节流程中实际执行（status/is-active 回显见该节）。

7.3 数据持久化位置与备份要点

方案 A 的数据落点：业务数据在 PostgreSQL 库 4gaBoards；上传的附件、用户头像、项目背景图分别存于源码目录下 server/private/attachments、server/public/user-avatars、server/public/project-background-images（与官方容器版卷路径一致）。备份需同时覆盖数据库导出与这三个目录，具体命令与回显见《4ga Boards 3.3.13 常用 CLI 命令与工具详解》。

八、升级与版本切换

8.1 查看当前版本

cd /opt/4gaBoards/src
git log -1 --format='%d'
grep '"version"' package.json

实测回显：

 (grafted, HEAD, tag: v3.3.13)
  "version": "3.3.13",

8.2 升级到新版本

官方 Manual 文档给出的升级流程为：拉取新 tag → 检出 → 重新安装依赖与构建 → 重启服务：

cd /opt/4gaBoards/src
git fetch --tags
git checkout v3.3.14        # 以实际最新 tag 为准（查询 GitHub Releases）
pnpm i
pnpm packages:build
pnpm client:build
cp -r client/build/. server/public
cp client/build/index.html server/views/index.ejs
systemctl restart 4gaboards

💡 说明：git checkout 后重新执行构建与复制，命令与第四章 4.5 节完全一致（回显可对照）；start.sh 中的数据库初始化是幂等的，服务重启时会自动完成新版本的迁移。升级前务必先备份数据库与附件目录（见《4ga Boards 3.3.13 常用 CLI 命令与工具详解》）。

8.3 降级与多版本

同一目录 git checkout 旧 tag 后重复构建即可降级；需要长期并行两个版本时，把源码克隆到第二目录（如 /opt/4gaBoards-3.3.12）并复制 service 单元改服务名与路径。注意服务端包含数据库迁移，降级到旧版本前应确认数据库结构兼容，必要时用服务端自带的回滚脚本（db:rollback，见《4ga Boards 3.3.13 常用 CLI 命令与工具详解》）并优先以备份恢复方式回退。

九、常见问题（FAQ）

Q1：git clone 报 Failed to connect to github.com port 443 / 长时间卡住怎么办？ 本文实测环境出现过该报错：

fatal: unable to access 'https://github.com/RARgames/4gaBoards.git/': Failed to connect to github.com port 443 after 21050 ms: Connection refused

定位：服务器到 GitHub 的 443 出网受限。解决：改走第五章方案 B（联网机构建后离线分发）；若单位内网有 HTTP 代理，也可为 git 配置代理后重新克隆（代理地址与端口取自本单位网络配置，配置命令为 git config --global http.proxy <代理地址> 形式）。

Q2：apt-get install postgresql 停在 tzdata 配置不动？ 实测中安装过程在时区交互提问处挂起（进程表可见 debconf 的 tzdata.config configure 在等待输入）。解决：安装时加非交互变量，并对已中断的安装执行配置收尾：

DEBIAN_FRONTEND=noninteractive apt-get install -y postgresql postgresql-contrib
dpkg --configure -a

实测执行后 dpkg --configure -a 正常结束，pg_lsclusters 出现 14 main 集群记录。

Q3：启动报 connect ECONNREFUSED 127.0.0.1:5432？ 实测日志：

Acquire connection error: Error: connect ECONNREFUSED 127.0.0.1:5432
Error: connect ECONNREFUSED 127.0.0.1:5432
  code: 'ECONNREFUSED',

定位：PostgreSQL 服务未运行（本文实测为人为停止 postgresql 服务后启动应用复现）。解决：

systemctl start postgresql
systemctl is-active postgresql

实测 is-active 返回 active 后重启 4ga Boards 即恢复正常（实测恢复后 curl -sI 返回 200）。

Q4：应用日志报数据库认证失败 / psql: error: FATAL: password authentication failed for user "boards"？ 实测回显：

psql: error: connection to server at "localhost" (::1), port 5432 failed: FATAL:  password authentication failed for user "boards"

定位：DATABASE_URL 中的口令与数据库实际口令不一致（实测用错误口令 wrongpass 连接复现）。解决：核对 .env 的 DATABASE_URL 与 4.3 节建账号时设置的口令一致；忘记口令时可用 su - postgres -c "psql -c \"ALTER USER boards WITH PASSWORD 'q1w2e3r4';\"" 重置后重启应用。验证方法：

PGPASSWORD=q1w2e3r4 psql -h localhost -U boards -d 4gaBoards -c 'SELECT current_database();'

实测回显：

 current_database
------------------
 4gaBoards
(1 row)

Q5：页面能打开，但看板不实时刷新、别人改动看不到？ 定位：BASE_URL 与实际访问地址不一致。4ga Boards 生产模式下 WebSocket 的合法 origin 直接取自 BASE_URL（源码 server/config/env/production.js 中 onlyAllowOrigins: [new url.URL(process.env.BASE_URL).origin]，实查 v3.3.13），启动日志中也会出现 onlyAllowOrigins ... only includes references to the localhost origin 的提示。解决：把 BASE_URL 改成与浏览器地址栏一致的 http(s)://<域名或IP>:<端口>，systemctl restart 4gaboards 后刷新页面。

Q6：pnpm i 报 engines/node 版本不满足？ 源码 engines 要求 Node ^24.11、pnpm ^11.9.0（实查 v3.3.13 根 package.json）。验证与处理：

node -v    # 应输出 v24.x（本文实测 v24.22.1）

低于 24 时按 4.2 节重新安装 NodeSource 的 Node 24，或走方案 B 的 tar.xz 离线安装。

十、卸载与清理

按以下顺序完整卸载（先停服务，再删单元与文件，最后清理数据库）：

systemctl disable --now 4gaboards
rm /etc/systemd/system/4gaboards.service
systemctl daemon-reload
rm -rf /opt/4gaBoards

数据库侧（确认不再需要数据后执行）：

su - postgres -c "psql -c 'DROP DATABASE \"4gaBoards\";'"
su - postgres -c "psql -c 'DROP USER boards;'"

可选：连同依赖一起卸载（不影响系统其他组件时再执行）：

apt-get purge -y nodejs
apt-get purge -y postgresql postgresql-contrib

⚠️ 注意：DROP DATABASE 不可恢复，执行前确认已有有效备份；apt-get purge postgresql 会删除 /var/lib/postgresql 下的全部数据。

十一、参考链接

  1. 官方手动安装文档：https://docs.4gaboards.com/docs/dev/install/manual-install/
  2. 官方变量说明：https://docs.4gaboards.com/docs/dev/install/manual-vars/
  3. 官方 PostgreSQL 安装说明：https://docs.4gaboards.com/docs/dev/install/manual-postgres/
  4. 官方卸载说明：https://docs.4gaboards.com/docs/dev/install/manual-uninstall/
  5. 官方 Web 服务器（反向代理）配置：https://docs.4gaboards.com/docs/dev/web-server-config
  6. GitHub 仓库与 Releases：https://github.com/RARgames/4gaBoards
  7. Node.js 二进制下载（方案 B 离线包）：https://nodejs.org/dist/
  8. NodeSource 安装脚本说明：https://deb.nodesource.com/
  9. 本专栏相关篇目：《4ga Boards 3.3.13 介绍与选型指南》、《4ga Boards 3.3.13 Docker Compose 部署指南》、《4ga Boards 3.3.13 配置参数详解》、《4ga Boards 3.3.13 常用 CLI 命令与工具详解》