4ga Boards 3.3.13 Docker Compose 部署指南

目标：用 Docker Compose 一键部署 4ga Boards v3.3.13 官方三服务栈（应用 + PostgreSQL 18 + Redis 8），完成编排文件配置、启动、初始账号登录验证、数据持久化与官方备份/恢复脚本实测，并给出镜像选型、环境变量、等价 docker run、日常运维与常见问题。全部命令与回显均在 Docker 29.8.1 + Compose v5.5.1 环境实测采集（2026-10-22），组件背景见《4ga Boards 3.3.13 介绍与选型指南》。

一、环境信息

本文所有命令在以下环境实测：

宿主系统：Ubuntu 22.04（x86_64）
Docker：29.8.1（docker --version → Docker version 29.8.1, build 4a63305）
Docker Compose：v5.5.1（docker compose version → Docker Compose version v5.5.1）
栈组成与镜像：ghcr.io/rargames/4gaboards:3.3.13 + postgres:18-alpine + redis:8-alpine（与官方 docker-compose.yml 一致）
部署目录：/opt/4gaboards-compose/4ga-boards-3.3.13-stack/（Compose 项目名 4ga-boards-3.3.13-stack，实际生成的容器/资源前缀为去点号后的 4ga-boards-3313-stack）
对外端口：宿主机 8132 → 应用容器 1337
初始管理员：admin / q1w2e3r4（通过 DEFAULT_ADMIN_USERNAME/DEFAULT_ADMIN_PASSWORD 首启覆盖，见第四章）

💡 说明：Compose 项目名中的点号会被规范化去除（3.3.13 → 3313），生成的卷名/网络名/容器名均带 3313 前缀，属正常现象。官方编排默认映射 3000:1337，本文实测改用 8132 作为宿主端口示例，读者可按端口空闲情况自行调整左侧宿主端口。

二、镜像选型说明

镜像	本文所用 tag	角色	选型依据
`ghcr.io/rargames/4gaboards`	`3.3.13`	4ga Boards 应用（Node.js 24 alpine，内置前端构建产物）	官方发布镜像，tag 与 GitHub Releases 版本号一一对应（`3.3.13` 拉取成功，实测）
`postgres`	`18-alpine`	业务数据库	官方 docker-compose.yml 指定版本
`redis`	`8-alpine`	上传限流计数器共享存储	官方 docker-compose.yml 指定版本

选型要点：

应用镜像锁定版本 tag（如 3.3.13）而非 latest，升级时显式改 tag 后 docker compose pull && docker compose up -d，版本可追溯、可回滚；
Redis 是可选组件：仅用于 UPLOAD_RATE_LIMIT_STORE=redis 的多实例限流共享，单实例部署可改用内存存储并去掉 redis 服务——官方仓库提供 docker-compose-no-redis.yml 变体（来源：v3.3.13 源码仓库根目录，2026-10-22 实查）；
需要自建镜像时，源码根目录提供多阶段 Dockerfile（构建 client → 组装 server + 生产依赖），执行 docker:build 脚本即可，一般场景直接用官方镜像即可。

三、前置条件

已安装 Docker 29.x 与 Docker Compose v2+ 插件（验证命令：docker --version、docker compose version）；
宿主机端口未占用（本文用 8132；被占用会报 Bind for ... failed: port is already allocated，见 FAQ Q2）；
服务器可访问 GitHub Container Registry（ghcr.io）拉取应用镜像、可访问 Docker Hub 拉取 postgres/redis 镜像；网络受限时先在能联网的机器 docker pull 后 docker save/docker load 迁移；
磁盘余量建议 ≥5 GB（三支镜像约 600 MB，加上数据库与附件数据量增长）。

四、部署步骤

4.1 建目录并准备编排文件

mkdir -p /opt/4gaboards-compose/4ga-boards-3.3.13-stack
cd /opt/4gaboards-compose/4ga-boards-3.3.13-stack
curl -L https://raw.githubusercontent.com/RARgames/4gaBoards/main/docker-compose.yml -o docker-compose.yml

💡 说明：官方 docker-compose.yml 默认映射 3000:1337、镜像为 latest、口令为占位值。以下按本文实测的配置逐项修改。

本文实测使用的完整 docker-compose.yml（与官方模板的差异：顶部显式声明项目名、镜像锁版本 tag、口令与密钥落为实测值、端口映射 8132、新增初始管理员覆盖变量、自定义网络子网）：

# https://docs.4gaboards.com/docs/dev/install/docker-vars
name: 4ga-boards-3.3.13-stack
services:
  db:
    image: postgres:18-alpine
    restart: always
    networks:
      - boards-network
    volumes:
      - db-data-18:/var/lib/postgresql
    environment:
      POSTGRES_DB: 4gaBoards
      POSTGRES_PASSWORD: q1w2e3r4
      POSTGRES_INITDB_ARGS: '-A scram-sha-256'
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres -d 4gaBoards']
      interval: 5s
      timeout: 5s
      retries: 20
  redis:
    image: redis:8-alpine
    restart: always
    networks:
      - boards-network
    volumes:
      - redis-data-8:/data
    command: ['redis-server', '--appendonly', 'yes', '--requirepass', 'q1w2e3r4']
    healthcheck:
      test: ['CMD-SHELL', 'redis-cli -a "q1w2e3r4" ping | grep PONG']
      interval: 5s
      timeout: 5s
      retries: 20
  4gaBoards:
    image: ghcr.io/rargames/4gaboards:3.3.13
    restart: always
    networks:
      - boards-network
    volumes:
      - user-avatars:/app/public/user-avatars
      - project-background-images:/app/public/project-background-images
      - attachments:/app/private/attachments
    ports:
      - 8132:1337
    environment:
      BASE_URL: http://localhost:8132
      SECRET_KEY: 7f3a9c1d52e84b06a1f4c8d27e93b5a60d41c7e28f93a5b04c6d18e27f93a5b04c6d18e27f93a5b04c6d18e27f9a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e4
      DATABASE_URL: postgresql://postgres:q1w2e3r4@db/4gaBoards
      NODE_ENV: production
      UPLOAD_RATE_LIMIT_STORE: redis
      UPLOAD_RATE_LIMIT_REDIS_URL: redis://:q1w2e3r4@redis:6379/0
      DEFAULT_ADMIN_USERNAME: admin
      DEFAULT_ADMIN_PASSWORD: q1w2e3r4
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_healthy
volumes:
  user-avatars:
  project-background-images:
  attachments:
  db-data-18:
  redis-data-8:
networks:
  boards-network:
    driver: bridge
    ipam:
      config:
        - subnet: 10.89.72.0/24

关键项解读（逐项）：

配置项	实测值	说明
`name`	`4ga-boards-3.3.13-stack`	Compose 项目名，建议显式声明，避免多套栈同名互相覆盖
`POSTGRES_PASSWORD` / `DATABASE_URL` 口令段	`q1w2e3r4`	两处必须是同一个口令（应用以该口令连库）
`POSTGRES_INITDB_ARGS`	`-A scram-sha-256`	首次初始化数据库时启用 scram-sha-256 认证
redis `--requirepass` / `UPLOAD_RATE_LIMIT_REDIS_URL` 口令段	`q1w2e3r4`	两处一致，应用经 URL 连 Redis
`SECRET_KEY`	实测生成的 hex 串	会话签名密钥，务必用 `openssl rand -hex 64` 重新生成，不能沿用本文值
`BASE_URL`	`http://localhost:8132`	对外访问地址，同时决定 WebSocket 合法 origin（与《Ubuntu 22.04 安装 4ga Boards 3.3.13 指南》FAQ Q5 同理）
`DEFAULT_ADMIN_USERNAME/PASSWORD`	`admin` / `q1w2e3r4`	首次启动创建的初始管理员，替代默认 `demo/demo`
`ports: 8132:1337`	—	宿主机 8132 → 应用 1337；左侧按需调整
`subnet: 10.89.72.0/24`	—	显式指定栈内网段，避免与宿主机上其他网络冲突（见 FAQ Q1）；不需要时删除 `ipam` 段由 Docker 自动分配

4.2 启动并确认状态

docker compose up -d

实测回显（输出节选）：

 Container 4ga-boards-3313-stack-redis-1 Waiting
 Container 4ga-boards-3313-stack-db-1 Waiting
 Container 4ga-boards-3313-stack-redis-1 Healthy
 Container 4ga-boards-3313-stack-db-1 Healthy
 Container 4ga-boards-3313-stack-4gaBoards-1 Starting
 Container 4ga-boards-3313-stack-4gaBoards-1 Started

可见依赖顺序生效：应用服务等待 db 与 redis 通过 healthcheck 后才启动。确认三个服务状态：

docker compose ps

实测回显：

NAME                                IMAGE                               COMMAND                   SERVICE     CREATED          STATUS                    PORTS
4ga-boards-3313-stack-4gaBoards-1   ghcr.io/rargames/4gaboards:3.3.13   "docker-entrypoint.s…"   4gaBoards   36 seconds ago   Up 30 seconds (healthy)   0.0.0.0:8132->1337/tcp, [::]:8132->1337/tcp
4ga-boards-3313-stack-db-1          postgres:18-alpine                  "docker-entrypoint.s…"   4gaBoards   37 seconds ago   Up 35 seconds (healthy)   5432/tcp
4ga-boards-3313-stack-redis-1       redis:8-alpine                      "docker-entrypoint.s…"   4gaBoards   37 seconds ago   Up 36 seconds (healthy)   6379/tcp

三个服务均 (healthy) 即部署完成（应用镜像自带 HEALTHCHECK 探测 http://localhost:1337，实测约 30 秒内转绿）。

4.3 登录验证（初始管理员）

浏览器访问 http://<服务器IP>:8132，用初始管理员 admin / q1w2e3r4 登录。命令行等价验证：

curl -sI http://localhost:8132 | head -3
curl -s -X POST http://localhost:8132/api/access-tokens -H 'Content-Type: application/json' -d '{"emailOrUsername":"admin","password":"q1w2e3r4"}'

实测回显：

HTTP/1.1 200 OK
X-Powered-By: Sails <sailsjs.com>
Content-Type: text/html; charset=utf-8
{"item":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjQ5MzYwMTUyLTM5MDUtNDU4Mi1iNmU4LTc5ODczYWQ2Yjk1MCJ9.eyJpYXQiOjE3OT..."}

返回 JWT 令牌说明初始管理员创建成功、登录链路正常（DEFAULT_ADMIN_USERNAME/DEFAULT_ADMIN_PASSWORD 覆盖生效）。若这两个变量在首次启动后才添加，不会再生效——那时请在界面里改密或重建数据卷。

4.4 服务内进程核验（可选）

docker compose exec 4gaBoards node -e "console.log(process.version)"

实测回显：

v24.22.1

与源码 engines 要求（Node ^24.11）一致，镜像运行时无版本漂移。

五、数据持久化说明

5.1 命名卷清单

编排文件声明了 5 个命名卷，覆盖全部持久化数据：

卷名（生成后带项目前缀）	容器内路径	内容
`4ga-boards-3313-stack_db-data-18`	`/var/lib/postgresql`	PostgreSQL 全部业务数据
`4ga-boards-3313-stack_redis-data-8`	`/data`	Redis AOF 持久化（限流计数器）
`4ga-boards-3313-stack_attachments`	`/app/private/attachments`	卡片附件
`4ga-boards-3313-stack_user-avatars`	`/app/public/user-avatars`	用户头像
`4ga-boards-3313-stack_project-background-images`	`/app/public/project-background-images`	项目背景图

实机核对：

docker volume ls | grep 3313

实测回显：

local     4ga-boards-3313-stack_attachments
local     4ga-boards-3313-stack_db-data-18
local     4ga-boards-3313-stack_project-background-images
local     4ga-boards-3313-stack_redis-data-8
local     4ga-boards-3313-stack_user-avatars

5.2 重启后数据保持实测

docker compose restart 4gaBoards
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8132

实测回显：

重启后服务即恢复且数据保留（命名卷独立于容器生命周期）；docker compose down 不删除卷，只有加 -v 才会连卷一起删除。

5.3 备份与恢复（官方脚本实测）

官方在源码仓库根目录提供 boards-backup.sh / boards-restore.sh，专用于 Compose 部署形态：备份脚本按「Compose 目录名推导容器名」工作，因此部署目录名要与 Compose 项目名（去点号后）一致（本文目录名 4ga-boards-3313-stack，与实际容器前缀一致）。把两个脚本下载到部署目录并执行备份：

./boards-backup.sh

实测回显（输出节选）：

Checking 4ga-boards-3313-stack-db-1: if there is no message below, 4ga-boards-3313-stack-db-1 is not running
Exporting db...
Exporting attachments...
Exporting user-avatars...
Exporting project-background-images...
Compressing backup...
Backup created at 4gaBoards-backup-2026-10-23T00-37-27Z.tgz

ls -lh *.tgz

实测回显：

-rw-r--r-- 1 root root 11K 10月 23 00:37 4gaBoards-backup-2026-10-23T00-37-27Z.tgz

备份包内含 PostgreSQL 全量导出（pg_dumpall 生成的 postgres.sql）与附件、头像、背景图三个目录，单文件即可异地保存。恢复实测：

./boards-restore.sh 4gaBoards-backup-2026-10-23T00-37-27Z.tgz

实测回显（输出节选）：

Importing attachments ...
Importing user-avatars...
Importing project-background-images...
Cleaning up temp files...
Backup restored from 4gaBoards-backup-2026-10-23T00-37-27Z.tgz

恢复后立即验证登录（实测返回新 JWT，数据完好）：

curl -s -X POST http://localhost:8132/api/access-tokens -H 'Content-Type: application/json' -d '{"emailOrUsername":"admin","password":"q1w2e3r4"}' | head -c 60

⚠️ 注意（来自官方 README）：恢复时备份内数据库口令必须与当前 docker-compose.yml 的 POSTGRES_PASSWORD 一致；若已改口令，需先编辑备份包内 postgres.sql 的 ALTER ROLE postgres WITH SUPERUSER ... PASSWORD 'XXX' 行再恢复。

六、环境变量表

6.1 4ga Boards 应用服务变量（本文实测值）

变量	本文实测值	必填	说明
`BASE_URL`	`http://localhost:8132`	是	对外访问地址，决定 WebSocket 合法 origin
`SECRET_KEY`	`openssl rand -hex 64` 生成	是	会话令牌签名密钥
`DATABASE_URL`	`postgresql://postgres:q1w2e3r4@db/4gaBoards`	是	连接串，主机名 `db` 为 Compose 服务名
`NODE_ENV`	`production`	是（官方模板含）	生产模式
`UPLOAD_RATE_LIMIT_STORE`	`redis`	否	上传限流存储（默认 memory；多实例用 redis）
`UPLOAD_RATE_LIMIT_REDIS_URL`	`redis://:q1w2e3r4@redis:6379/0`	条件必填	`UPLOAD_RATE_LIMIT_STORE=redis` 时必填
`DEFAULT_ADMIN_USERNAME`	`admin`	否	首启初始管理员用户名（默认 demo）
`DEFAULT_ADMIN_PASSWORD`	`q1w2e3r4`	否	首启初始管理员口令（默认 demo）

完整可选变量（SSO、通知、附件上限、日志级别等约 50 项）见《4ga Boards 3.3.13 配置参数详解》与官方变量文档 https://docs.4gaboards.com/docs/dev/install/docker-vars/ 。

6.2 数据库与 Redis 服务变量

变量/参数	本文实测值	说明
`POSTGRES_DB`	`4gaBoards`	初始化创建的库名
`POSTGRES_PASSWORD`	`q1w2e3r4`	postgres 超级用户口令，须与 `DATABASE_URL` 一致
`POSTGRES_INITDB_ARGS`	`-A scram-sha-256`	初始化认证方式
redis `command`	`--appendonly yes --requirepass q1w2e3r4`	开启 AOF 持久化并设访问口令

七、配置参数说明

容器版没有 .env 文件：所有配置通过 compose 的 environment 注入，改配置即改 docker-compose.yml 后 docker compose up -d（会重建对应服务容器）；
参数体系与裸机 .env 完全一致（同一套变量名），差别只在注入方式；TZ 在容器版由官方镜像按 UTC 处理，一般无需设置；
常用改配置场景：换访问域名（BASE_URL）、扩展上传限额（UPLOAD_RATE_LIMIT_*、ATTACHMENT_MAX_BYTES）、接入 SSO（OIDC_*/GOOGLE_*/GITHUB_*/MICROSOFT_*）——逐项含义与实测见《4ga Boards 3.3.13 配置参数详解》。

八、配置文件挂载

官方镜像设计为「环境变量注入 + 命名卷持久化」，不需要挂载任何配置文件。两类常见扩展挂载：

附件/头像改宿主机目录（bind mount）：把对应命名卷换成宿主机路径即可，便于接外部备份体系：

    volumes:
      - /opt/4gaboards-data/attachments:/app/private/attachments
      - /opt/4gaboards-data/user-avatars:/app/public/user-avatars
      - /opt/4gaboards-data/project-background-images:/app/public/project-background-images

💡 说明：切换前先用 docker cp 把原卷内容拷出到新目录（或直接新建空目录重新开始），目录属主需与容器内运行用户一致（镜像内以 node 用户运行）。

数据库数据外移：同理可将 db-data-18 卷换成 bind mount；生产更推荐保持命名卷 + pg_dumpall 定期备份（见 5.3 节）。

九、等价 docker run

仅启动 4ga Boards 应用服务（不含数据库）的等价命令如下，用于理解 compose 配置到裸 docker 命令的映射（需先有可达的 PostgreSQL 与网络）：

docker run -d --name 4gaboards \
  -p 8132:1337 \
  -e BASE_URL=http://localhost:8132 \
  -e SECRET_KEY=7f3a9c1d52e84b06a1f4c8d27e93b5a60d41c7e28f93a5b04c6d18e27f93a5b04c6d18e27f93a5b04c6d18e27f9a3b5c7d9e1f2a4b6c8d0e2f4a6b8c0d2e4 \
  -e DATABASE_URL=postgresql://postgres:q1w2e3r4@db/4gaBoards \
  -e NODE_ENV=production \
  -e UPLOAD_RATE_LIMIT_STORE=redis \
  -e UPLOAD_RATE_LIMIT_REDIS_URL=redis://:q1w2e3r4@redis:6379/0 \
  -e DEFAULT_ADMIN_USERNAME=admin \
  -e DEFAULT_ADMIN_PASSWORD=q1w2e3r4 \
  -v user-avatars:/app/public/user-avatars \
  -v project-background-images:/app/public/project-background-images \
  -v attachments:/app/private/attachments \
  --restart always \
  ghcr.io/rargames/4gaboards:3.3.13

💡 说明：Compose 相对裸 docker run 的增值点是 depends_on 的健康检查编排（应用等待数据库就绪）、命名卷与网络的一键管理、以及 docker compose 系列运维命令；生产部署建议使用 Compose 或 Kubernetes（官方提供 helm-chart）。

十、常用运维命令

以下命令均在本文部署目录内实测（在 docker-compose.yml 所在目录执行）：

docker compose ps                     # 查看三服务状态与健康检查结果（回显见 4.2）
docker compose logs -f 4gaBoards      # 跟踪应用日志
docker compose logs --tail 50 db      # 查看数据库最近 50 行日志
docker compose restart 4gaBoards      # 重启应用服务（实测后 200，见 5.2）
docker compose stop                   # 停止全部服务（保留容器与卷）
docker compose start                  # 启动已停止的服务
docker compose down                   # 删除容器与网络（保留卷，数据不丢）
docker compose down -v                # 连同数据卷一起删除（危险，数据全丢）
docker compose pull && docker compose up -d   # 升级镜像并应用（改 tag 后执行）
docker compose exec db pg_isready -U postgres -d 4gaBoards   # 手动探活数据库
docker compose exec db psql -U postgres -d 4gaBoards -c '\dt' # 进入库内查表

镜像更新检查实测（docker compose pull 4gaBoards，tag 已是最新时回显）：

Image ghcr.io/rargames/4gaboards:3.3.13 Pulling
Image ghcr.io/rargames/4gaboards:3.3.13 Pulled

十一、常见问题（FAQ）

Q1：docker compose up 报 invalid pool request: Pool overlaps with other one on this address space？ 本文实测遇到（显式指定子网与宿主机已有网络冲突时）：

failed to create network 4ga-boards-3313-stack_boards-network: Error response from daemon: invalid pool request: Pool overlaps with other one on this address space

定位：compose 里 ipam 指定的子网（本文初版用 10.89.59.0/24）已被其他网络占用。解决：用 docker network ls + docker network inspect <网络名> --format '{{range .IPAM.Config}}{{.Subnet}}{{end}}' 查出已占网段，改用空闲网段（本文改为 10.89.72.0/24）后重新 docker compose up -d；不需要固定网段时直接删除 ipam 配置让 Docker 自动分配。

Q2：启动报 Bind for 0.0.0.0:xxxx failed: port is already allocated？ 定位：宿主机端口被其他进程或容器占用。解决：改 ports 左侧宿主端口（如 8132:1337 改为其他空闲端口），同时同步修改 BASE_URL 的端口后 docker compose up -d 重建。

Q3：docker compose ps 里 4gaBoards 一直 starting 或 unhealthy？ 定位：应用容器内健康检查探测 http://localhost:1337 失败，多数是数据库未就绪或 DATABASE_URL 口令与 POSTGRES_PASSWORD 不一致。排查顺序：docker compose logs db 看数据库是否正常接受连接 → 核对两个口令一致 → docker compose logs 4gaBoards 看连接错误详情。修改后 docker compose up -d 重建。

Q4：改了 POSTGRES_PASSWORD 后数据库认证失败？ 定位：postgres 镜像的 POSTGRES_PASSWORD 只在数据目录首次初始化时生效，之后改 compose 不会改库内口令。解决（二选一）：进库改口令——docker compose exec db psql -U postgres -c "ALTER USER postgres WITH PASSWORD 'q1w2e3r4';"；或开发环境可接受数据清空时 docker compose down -v 后重新 up -d 重新初始化。

Q5：boards-backup.sh 提示容器不存在？ 定位：脚本按「部署目录名小写」推导容器名（<目录名>-db-1）。若目录名与 Compose 项目名（去点号后）不一致就会找错。解决：把部署目录改名为与实际容器前缀一致（本文为 4ga-boards-3313-stack），或在目录内核对 docker ps 输出的实际容器名后再执行。

十二、参考链接

官方 Docker Compose 安装文档：https://docs.4gaboards.com/docs/dev/install/docker/
官方 Docker Compose 变量文档：https://docs.4gaboards.com/docs/dev/install/docker-vars/
官方 docker-compose.yml 模板：https://github.com/RARgames/4gaBoards/blob/main/docker-compose.yml
官方镜像：https://github.com/RARgames/4gaBoards/pkgs/container/4gaboards
官方备份/恢复脚本（源码仓库根目录）：https://github.com/RARgames/4gaBoards
本专栏相关篇目：《4ga Boards 3.3.13 介绍与选型指南》、《Ubuntu 22.04 安装 4ga Boards 3.3.13 指南》、《4ga Boards 3.3.13 配置参数详解》、《4ga Boards 3.3.13 常用 CLI 命令与工具详解》