FlowFuse Docker Compose 部署文档

1. 镜像概述和主要用途

FlowFuse Docker Compose 是一个用于运行 FlowFuse 平台的 Docker Compose 示例项目。其主要用途是通过 Docker Compose 工具安装和管理 FlowFuse 所需的全部组件，实现 FlowFuse 平台的便捷部署、运行与维护。FlowFuse 是一个用于管理 Node-RED 项目、团队协作及资源分配的平台，本项目通过容器化方式简化其部署流程。

2. 核心功能和特性

2.1 核心容器组件

• flowfuse/forge-docker：包含 FlowFuse 应用主体及 Docker 驱动，负责平台核心功能与容器管理。
• flowfuse/node-red：基础 Node-RED 镜像，集成 FlowFuse 启动器及与 FlowFuse 平台通信所需的 Node-RED 插件，支持用户自定义部署需求。
• flowfuse/file-server：提供对象存储服务，用于支持运行在 Docker 上的项目实现持久化文件存储。

2.2 主要特性

• 通过 Docker Compose 统一管理多组件依赖（应用、数据库、存储等）。
• 支持项目数据持久化存储，通过独立文件服务器容器实现。
• 可自定义 Node-RED 镜像，满足特定部署场景需求。
• 集成 PostgreSQL 数据库，存储项目实例、用户信息等核心数据。
• 支持团队协作与用户管理，通过邮件邀请功能实现用户加入。

3. 使用场景和适用范围

3.1 适用场景

• 需要快速部署 FlowFuse 平台进行功能验证或原型开发。
• 通过 Docker 环境标准化 FlowFuse 部署流程，确保环境一致性。
• 管理多个 Node-RED 项目，实现团队协作与资源隔离。
• 开发环境中需要频繁调整 FlowFuse 配置或源码，进行功能迭代。

3.2 环境要求

• Linux 或 macOS 系统（Docker 运行环境）。
• 支持 Docker Compose v2+ 的 Docker 环境。
• 具备通配符 DNS 解析能力的网络环境。

4. 前提条件

4.1 Docker Compose 安装

FlowFuse 依赖 Docker Compose 管理组件，需确保系统已安装 Docker Compose v2 及以上版本。安装指南参考：
[***]

4.2 DNS 配置

需配置通配符 DNS 记录，将域名解析至运行 Docker 的主机 IP，以访问创建的项目。

• 示例：若 Docker 主机 IP 为 192.168.0.8，需配置 *.example.com 的 A 记录指向该 IP，使所有 example.com 子域名均解析至主机。
• 注意：本地测试时不可使用回环地址 127.0.0.1（如 /etc/hosts 文件中），否则会解析至容器内部网络栈。

5. 安装与部署

5.1 构建容器

执行以下命令构建所需容器镜像：

./build-containers.sh

该脚本会构建并标记以下镜像：

• flowfuse/forge-docker：包含 FlowFuse 应用及 Docker 驱动。
• flowfuse/node-red：集成 FlowFuse 启动器及必要插件的 Node-RED 镜像，支持用户自定义。
• flowfuse/file-server：提供对象存储服务，用于项目持久化文件存储。

5.2 配置文件修改

5.2.1 etc/flowforge.yml 配置

该文件映射至 flowfuse/forge-docker 容器，需修改以下关键配置：

• domain：设置为与 DNS 配置一致的域名（如 example.com）。
• base_url：设置平台基础 URL（如 [***]）。
• email 部分：配置本地 SMTP 服务器信息，用于发送用户邀请邮件（如 smtp.host、smtp.port、smtp.auth 等）。

5.2.2 docker-compose.yml 配置

• VIRTUAL_HOST：设置为与 etc/flowforge.yml 中 domain 一致的域名。

5.3 启动 FlowFuse 实例

容器构建及配置完成后，执行以下命令启动 FlowFuse：

docker-compose -p flowforge up -d

该命令会自动创建 db 目录，用于存储 PostgreSQL 数据库文件（项目实例、用户信息等数据）。

6. 升级步骤

从 1.2.0 版本之前升级时，需手动创建持久化上下文存储的数据库。启动实例后，执行以下命令：

docker exec -it flowforge_postgres_1 /docker-entrypoint-initdb.d/setup-context-db.sh

7. 开发模式（实验性）

适用于 FlowFuse 开发场景，通过本地挂载源码树运行 Docker 驱动。步骤如下：

1. 源码准备：将所有 FlowFuse 源码仓库（含本项目）检出至同一目录。
2. 依赖安装：在每个含 package.json 的源码仓库中执行 npm install。
3. 开发环境配置：在 flowforge 仓库中执行 npm run dev:local，建立仓库间的开发符号链接。
4. DNS 配置：按 4.2 节配置通配符 DNS。
5. 驱动配置：修改 flowforge 仓库中的 etc/flowforge.yml，启用 Docker 驱动：

   port: 3000
   host: 0.0.0.0
   domain: example.com
   base_url: [***]
   api_url: [***]
   
   driver:
     type: docker
     options:
       socket: /tmp/docker.sock
   

6. 依赖重建（首次运行）：若本地开发环境与 Docker 环境依赖不一致（如 bcrypt 二进制依赖），需修改 flowforge/package.json 中的 serve 脚本：

   "serve": "npm uninstall bcrypt && npm install bcrypt && npm-run-all --parallel build-watch start-watch"
   

   （注：返回本地运行时需重新安装该依赖）。
7. 启动开发环境：

   docker-compose -f docker-compose-local-dev.yml up --build
   

   该命令会启动标准环境，同时将本地源码树挂载至 forge 容器，通过 npm run serve 启动服务，支持源码变更时自动重建/重启。