1. 项目简介

1.1 什么是 Refly

Refly 是一款开源的 AI 原生创作引擎，通过直观的自由画布界面，帮助用户将创意轻松转化为高质量内容。无论你使用的是 macOS、Windows 还是 Linux，都可以通过 Docker 快速启动完整的开发或生产环境。

目前相关镜像主机已经存入vLLM-Omni自动生成项目中了，可以直接使用，内嵌入OLLMA QWEN3模型，同时你也可以自定义其他任意模型。

2. 系统要求

2.1 硬件要求

配置项	最低要求	推荐配置
CPU	2 核	4 核及以上
内存	4 GB	8 GB 及以上
磁盘	20 GB	50 GB SSD

2.2 软件要求

软件	版本要求	用途
Docker	≥ 20.10.0	容器化运行环境
Docker Compose	≥ 2.0.0	容器编排工具
Node.js	≥ 20.19.0	JavaScript 运行时
pnpm	≥ 9.15.9	包管理器
Git	最新版本	代码版本管理

2.3 端口占用

请确保以下端口未被占用：

端口	服务	说明
5173	Web 前端	开发环境访问入口
3000	API 服务	后端 API
5432	PostgreSQL	数据库
6379	Redis	缓存服务
6333	Qdrant	向量数据库
9200	Elasticsearch	全文搜索

---

3. 基础环境安装

3.1 安装 Docker

Docker 是一个开源的容器化平台，允许你将应用及其依赖打包到一个轻量级的容器中运行。对于 Ubuntu 20.04 及更高版本，Docker 提供了官方的仓库和安装工具。

安装方式说明：

• 官方仓库安装（推荐）：使用 Docker 官方仓库，能获得最新版本和及时的安全更新
• Snap 安装：更简单但可能不是最新版本
• 便携式二进制：适合特殊场景

本指南采用官方仓库安装方式。

步骤 1：更新系统包

首先更新系统的包管理器索引，确保能够获取最新的软件：

# 更新包管理器的索引
sudo apt-get update

# 升级已安装的包（可选）
sudo apt-get upgrade -y

步骤 2：安装依赖工具

Docker 安装需要以下依赖工具：

• ca-certificates - SSL/TLS 证书支持
• curl - 下载工具
• gnupg - GPG 密钥管理
• lsb-release - 发行版本识别

sudo apt-get install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

步骤 3：添加 Docker 官方 GPG 密钥

GPG 密钥用于验证 Docker 官方仓库的完整性和真实性，防止中间人攻击：

# 创建密钥存储目录
sudo mkdir -p /etc/apt/keyrings

# 下载 Docker GPG 密钥并转换为二进制格式
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
    sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 设置正确的文件权限（使系统能读取）
sudo chmod a+r /etc/apt/keyrings/docker.gpg

参数说明：

• -fsSL：静默模式下载，显示进度条
• --dearmor：将 ASCII 格式的密钥转换为二进制格式

步骤 4：添加 Docker 官方仓库

将 Docker 官方仓库添加到系统的 apt 源列表中：

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

参数说明：

• $(dpkg --print-architecture)：自动检测系统架构（amd64/arm64）
• $(lsb_release -cs)：自动检测 Ubuntu 代号（focal/jammy 等）
• stable：使用稳定版本（也可用 test 或 nightly）

步骤 5：更新包索引并安装 Docker

添加仓库后，需要更新包索引以获取 Docker 包信息，然后进行安装：

# 更新包索引以包含 Docker 官方仓库的包信息
sudo apt-get update

# 安装 Docker 及相关工具
sudo apt-get install -y \
    docker-ce \
    docker-ce-cli \
    containerd.io \
    docker-buildx-plugin \
    docker-compose-plugin

各组件说明：

• docker-ce：Docker 引擎（核心）
• docker-ce-cli：Docker 命令行工具
• containerd.io：容器运行时（Docker 底层依赖）
• docker-buildx-plugin：多平台镜像构建工具（可选）
• docker-compose-plugin：Docker Compose v2（容器编排）

步骤 6：配置 Docker 用户组（可选但推荐）

默认情况下，Docker 命令需要 sudo 权限。为了避免每次都输入 sudo，可以将当前用户添加到 docker 用户组：

# 创建 docker 用户组（通常已存在）
sudo groupadd docker

# 将当前用户添加到 docker 用户组
sudo usermod -aG docker $USER

# 方式一：注销并重新登录（最安全）
# 直接在菜单中选择"注销"，然后重新登录

# 方式二：激活新的用户组成员资格（推荐）
newgrp docker

# 方式三：验证权限配置是否成功
docker run hello-world

重要安全说明：
docker 用户组拥有等同于 root 的权限。只将信任的用户添加到此组。

步骤 7：启动 Docker 服务

安装完成后，启动 Docker 守护进程并设置开机自启：

# 启动 Docker 守护进程（后台服务）
sudo systemctl start docker

# 设置 Docker 开机自启
sudo systemctl enable docker

# 验证 Docker 是否正常运行
sudo systemctl status docker

预期输出应该显示：active (running)

步骤 8：验证 Docker 安装

运行 Docker 官方测试镜像来验证安装是否成功：

# 运行 hello-world 测试镜像
docker run hello-world

如果看到以下输出，说明 Docker 安装成功：

Hello from Docker!
This message shows that your installation appears to be working correctly.

常见错误及解决方案：

错误	原因	解决方案
Got permission denied	用户没有 docker 权限	运行 sudo usermod -aG docker $USER 并重新登录
Cannot connect to Docker daemon	Docker 服务未启动	运行 sudo systemctl start docker
Unable to locate package docker-ce	仓库添加失败	检查网络和重复步骤 4
curl: Failed to resolve host	网络连接问题	检查网络连接或更换 DNS

3.2 安装 Docker Compose

Docker Compose 是 Docker 官方提供的容器编排工具，用于定义和运行多容器 Docker 应用。它使用 YAML 文件（通常是 docker-compose.yml）来配置应用的服务，然后通过一条命令启动所有服务。

Docker Compose 的作用：

• 声明式配置：用 YAML 文件定义容器的配置、网络、卷等
• 一键启动：docker-compose up 即可启动整个应用栈
• 依赖管理：自动管理容器间的依赖顺序
• 网络隔离：为容器创建独立的网络环境
• 卷管理：简化数据持久化配置

验证 Docker Compose 安装

在 Ubuntu 上安装 docker-compose-plugin 时，Docker Compose v2 已自动包含。验证安装：

# 检查 Docker Compose 版本
docker compose version

# 预期输出应该显示 v2.x.x

如果需要独立安装 Docker Compose v2

如果以上命令无法找到 docker compose，可以手动安装：

# 1. 确定系统架构
DOCKER_CONFIG=${DOCKER_CONFIG:-$HOME/.docker}
mkdir -p $DOCKER_CONFIG/cli-plugins

# 2. 下载最新版本的 Docker Compose
# 注：这里使用 v2.20.0 作为示例，可替换为最新版本
curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" \
    -o $DOCKER_CONFIG/cli-plugins/docker-compose

# 3. 如果系统是 arm64 架构，使用 aarch64 版本
# curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-aarch64" \
#     -o $DOCKER_CONFIG/cli-plugins/docker-compose

# 4. 给予执行权限
chmod +x $DOCKER_CONFIG/cli-plugins/docker-compose

# 5. 验证安装
docker compose version

或使用系统包管理器安装：

# 如果已有 pip（Python 包管理器）
sudo pip3 install docker-compose

# 或使用 apt（如果 docker-compose-plugin 尚未安装）
sudo apt-get install -y docker-compose-plugin

Docker Compose 常用命令

# 启动所有服务（后台运行）
docker compose up -d

# 查看所有运行的容器
docker compose ps

# 查看日志
docker compose logs -f

# 查看特定服务的日志
docker compose logs -f postgres

# 停止所有服务
docker compose down

# 停止并删除卷（数据会被清除）
docker compose down -v

# 重启服务
docker compose restart

# 重新构建镜像
docker compose build

3.3 安装 Node.js 和 pnpm

Node.js 是一个 JavaScript 运行时环境，允许在服务器端执行 JavaScript 代码。pnpm 是一个高效的 npm 包管理器，相比 npm 和 yarn 占用更少的磁盘空间。Refly 项目使用 pnpm 管理依赖。

方法 1：使用 NodeSource 仓库（推荐 - 更简单）

NodeSource 提供了预编译的 Node.js 二进制包，安装更快且更新及时：

# 下载 NodeSource 设置脚本并运行
# 该脚本会自动添加 NodeSource 仓库并配置 apt
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# 安装 Node.js 和 npm
sudo apt-get install -y nodejs

# 验证安装
node -v    # 应显示 v20.x.x
npm -v     # 应显示对应的 npm 版本

NodeSource 脚本说明：

• setup_20.x：指定安装 Node.js 20.x LTS 版本
• -E：保留用户的环境变量
• 脚本会自动配置 apt 仓库

方法 2：使用 NVM（Node Version Manager - 更灵活）

NVM 允许在一台机器上安装和管理多个 Node.js 版本，适合需要在不同项目间切换版本的开发者：

# 下载并安装 NVM
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载 shell 配置（使 nvm 命令生效）
source ~/.bashrc
# 如果使用 zsh shell，运行
source ~/.zshrc

# 安装 Node.js 20.19.0 LTS 版本
nvm install 20.19.0

# 将 20.19.0 设置为默认版本
nvm alias default 20.19.0

# 验证安装
node -v    # 应显示 v20.19.0
npm -v

NVM 其他常用命令：

# 列出已安装的 Node.js 版本
nvm list

# 列出可用的 Node.js 版本
nvm list-remote

# 切换到特定版本
nvm use 20.19.0

# 安装特定版本
nvm install 18.17.0

# 卸载特定版本
nvm uninstall 18.17.0

方法对比：

特性	NodeSource	NVM
安装难度	简单	中等
版本管理	单一版本	多版本切换
系统级安装	是	否（用户级）
更新频率	通过 apt 更新	手动管理
推荐场景	单个项目	多个项目

3.4 安装 pnpm 包管理器

pnpm（Performant npm）是一个高效的 npm 替代品，具有以下优势：

• 磁盘节省：使用硬链接和符号链接共享依赖
• 速度快：安装速度比 npm 和 yarn 快
• 严格：更严格的依赖解析，避免幽灵依赖

安装 pnpm：

# 使用 npm 全局安装 pnpm 9.15.9 版本
npm install -g pnpm@9.15.9

# 验证安装
pnpm -v    # 应显示 9.15.9

# 配置 pnpm（设置 pnpm home 目录等）
pnpm setup

# 重新加载 shell 配置
source ~/.bashrc

pnpm 常用命令：

# 安装项目依赖
pnpm install

# 安装并添加新包
pnpm add package-name

# 安装开发依赖
pnpm add -D dev-package-name

# 删除包
pnpm remove package-name

# 更新包
pnpm update

# 清空缓存
pnpm store prune

为什么 Refly 使用 pnpm？

Refly 是一个 Monorepo 项目，包含 2 个应用（api 和 web）和 24 个共享包。pnpm 的 Monorepo 支持：

• 自动解析包间的依赖关系
• 符号链接共享代码，避免重复
• 更快的安装和更新速度
• 防止幽灵依赖问题

3.4 Ubuntu 快速安装脚本

为了简化安装流程，你可以使用以下一键安装脚本：

#!/bin/bash

echo "===== Refly 开发环境安装脚本（Ubuntu/Debian） ====="

# 更新系统
echo "1. 更新系统包..."
sudo apt-get update
sudo apt-get upgrade -y

# 安装 Docker
echo "2. 安装 Docker..."
sudo apt-get install -y ca-certificates curl gnupg lsb-release
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
    sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
    https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
    sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 配置 Docker 用户组
echo "3. 配置 Docker 用户组..."
sudo usermod -aG docker $USER
newgrp docker

# 启动 Docker
echo "4. 启动 Docker 服务..."
sudo systemctl start docker
sudo systemctl enable docker

# 安装 Node.js
echo "5. 安装 Node.js..."
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 pnpm
echo "6. 安装 pnpm..."
npm install -g pnpm@9.15.9
pnpm setup

echo "===== 安装完成 ====="
echo "验证环境："
echo "Docker 版本："
docker --version
echo "Docker Compose 版本："
docker compose version
echo "Node.js 版本："
node -v
echo "pnpm 版本："
pnpm -v

将上述脚本保存为 install-refly.sh，然后运行：

chmod +x install-refly.sh
./install-refly.sh

---

4、项目初始化

4.1 克隆项目

# 使用 HTTPS 克隆
git clone https://github.com/refly-ai/refly.git

# 进入项目目录
cd refly

4.2 安装依赖

pnpm install

…详情请参照古月居