Refly 完整安装使用指南

1. 项目简介1.1 什么是 ReflyRefly 是一款开源的 AI 原生创作引擎通过直观的自由画布界面帮助用户将创意轻松转化为高质量内容。无论你使用的是 macOS、Windows 还是 Linux都可以通过 Docker 快速启动完整的开发或生产环境。目前相关镜像主机已经存入vLLM-Omni自动生成项目中了可以直接使用内嵌入OLLMA QWEN3模型同时你也可以自定义其他任意模型。2. 系统要求2.1 硬件要求配置项最低要求推荐配置CPU2 核4 核及以上内存4 GB8 GB 及以上磁盘20 GB50 GB SSD2.2 软件要求软件版本要求用途Docker≥ 20.10.0容器化运行环境Docker Compose≥ 2.0.0容器编排工具Node.js≥ 20.19.0JavaScript 运行时pnpm≥ 9.15.9包管理器Git最新版本代码版本管理2.3 端口占用请确保以下端口未被占用端口服务说明5173Web 前端开发环境访问入口3000API 服务后端 API5432PostgreSQL数据库6379Redis缓存服务6333Qdrant向量数据库9200Elasticsearch全文搜索3. 基础环境安装3.1 安装 DockerDocker 是一个开源的容器化平台允许你将应用及其依赖打包到一个轻量级的容器中运行。对于 Ubuntu 20.04 及更高版本Docker 提供了官方的仓库和安装工具。安装方式说明官方仓库安装推荐使用 Docker 官方仓库能获得最新版本和及时的安全更新Snap 安装更简单但可能不是最新版本便携式二进制适合特殊场景本指南采用官方仓库安装方式。步骤 1更新系统包首先更新系统的包管理器索引确保能够获取最新的软件# 更新包管理器的索引sudoapt-getupdate# 升级已安装的包可选sudoapt-getupgrade-y步骤 2安装依赖工具Docker 安装需要以下依赖工具ca-certificates- SSL/TLS 证书支持curl- 下载工具gnupg- GPG 密钥管理lsb-release- 发行版本识别sudoapt-getinstall-y\ca-certificates\curl\gnupg\lsb-release步骤 3添加 Docker 官方 GPG 密钥GPG 密钥用于验证 Docker 官方仓库的完整性和真实性防止中间人攻击# 创建密钥存储目录sudomkdir-p/etc/apt/keyrings# 下载 Docker GPG 密钥并转换为二进制格式curl-fsSLhttps://download.docker.com/linux/ubuntu/gpg|\sudogpg--dearmor-o/etc/apt/keyrings/docker.gpg# 设置正确的文件权限使系统能读取sudochmodar /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|\sudotee/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 官方仓库的包信息sudoapt-getupdate# 安装 Docker 及相关工具sudoapt-getinstall-y\docker-ce\docker-ce-cli\containerd.io\docker-buildx-plugin\docker-compose-plugin各组件说明docker-ceDocker 引擎核心docker-ce-cliDocker 命令行工具containerd.io容器运行时Docker 底层依赖docker-buildx-plugin多平台镜像构建工具可选docker-compose-pluginDocker Compose v2容器编排步骤 6配置 Docker 用户组可选但推荐默认情况下Docker 命令需要sudo权限。为了避免每次都输入sudo可以将当前用户添加到 docker 用户组# 创建 docker 用户组通常已存在sudogroupadddocker# 将当前用户添加到 docker 用户组sudousermod-aGdocker$USER# 方式一注销并重新登录最安全# 直接在菜单中选择注销然后重新登录# 方式二激活新的用户组成员资格推荐newgrpdocker# 方式三验证权限配置是否成功dockerrun hello-world重要安全说明docker 用户组拥有等同于 root 的权限。只将信任的用户添加到此组。步骤 7启动 Docker 服务安装完成后启动 Docker 守护进程并设置开机自启# 启动 Docker 守护进程后台服务sudosystemctl startdocker# 设置 Docker 开机自启sudosystemctlenabledocker# 验证 Docker 是否正常运行sudosystemctl statusdocker预期输出应该显示active (running)步骤 8验证 Docker 安装运行 Docker 官方测试镜像来验证安装是否成功# 运行 hello-world 测试镜像dockerrun 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 daemonDocker 服务未启动运行sudo systemctl start dockerUnable to locate package docker-ce仓库添加失败检查网络和重复步骤 4curl: Failed to resolve host网络连接问题检查网络连接或更换 DNS3.2 安装 Docker ComposeDocker Compose 是 Docker 官方提供的容器编排工具用于定义和运行多容器 Docker 应用。它使用 YAML 文件通常是 docker-compose.yml来配置应用的服务然后通过一条命令启动所有服务。Docker Compose 的作用声明式配置用 YAML 文件定义容器的配置、网络、卷等一键启动docker-compose up即可启动整个应用栈依赖管理自动管理容器间的依赖顺序网络隔离为容器创建独立的网络环境卷管理简化数据持久化配置验证 Docker Compose 安装在 Ubuntu 上安装docker-compose-plugin时Docker Compose v2 已自动包含。验证安装# 检查 Docker Compose 版本dockercompose 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-Lhttps://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. 给予执行权限chmodx$DOCKER_CONFIG/cli-plugins/docker-compose# 5. 验证安装dockercompose version或使用系统包管理器安装# 如果已有 pipPython 包管理器sudopip3installdocker-compose# 或使用 apt如果 docker-compose-plugin 尚未安装sudoapt-getinstall-ydocker-compose-pluginDocker Compose 常用命令# 启动所有服务后台运行dockercompose up-d# 查看所有运行的容器dockercomposeps# 查看日志dockercompose logs-f# 查看特定服务的日志dockercompose logs-fpostgres# 停止所有服务dockercompose down# 停止并删除卷数据会被清除dockercompose down-v# 重启服务dockercompose restart# 重新构建镜像dockercompose build3.3 安装 Node.js 和 pnpmNode.js 是一个 JavaScript 运行时环境允许在服务器端执行 JavaScript 代码。pnpm 是一个高效的 npm 包管理器相比 npm 和 yarn 占用更少的磁盘空间。Refly 项目使用 pnpm 管理依赖。方法 1使用 NodeSource 仓库推荐 - 更简单NodeSource 提供了预编译的 Node.js 二进制包安装更快且更新及时# 下载 NodeSource 设置脚本并运行# 该脚本会自动添加 NodeSource 仓库并配置 aptcurl-fsSLhttps://deb.nodesource.com/setup_20.x|sudo-Ebash-# 安装 Node.js 和 npmsudoapt-getinstall-ynodejs# 验证安装node-v# 应显示 v20.x.xnpm-v# 应显示对应的 npm 版本NodeSource 脚本说明setup_20.x指定安装 Node.js 20.x LTS 版本-E保留用户的环境变量脚本会自动配置 apt 仓库方法 2使用 NVMNode Version Manager - 更灵活NVM 允许在一台机器上安装和管理多个 Node.js 版本适合需要在不同项目间切换版本的开发者# 下载并安装 NVMcurl-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 版本nvminstall20.19.0# 将 20.19.0 设置为默认版本nvmaliasdefault20.19.0# 验证安装node-v# 应显示 v20.19.0npm-vNVM 其他常用命令# 列出已安装的 Node.js 版本nvm list# 列出可用的 Node.js 版本nvm list-remote# 切换到特定版本nvm use20.19.0# 安装特定版本nvminstall18.17.0# 卸载特定版本nvm uninstall18.17.0方法对比特性NodeSourceNVM安装难度简单中等版本管理单一版本多版本切换系统级安装是否用户级更新频率通过 apt 更新手动管理推荐场景单个项目多个项目3.4 安装 pnpm 包管理器pnpmPerformant npm是一个高效的 npm 替代品具有以下优势磁盘节省使用硬链接和符号链接共享依赖速度快安装速度比 npm 和 yarn 快严格更严格的依赖解析避免幽灵依赖安装 pnpm# 使用 npm 全局安装 pnpm 9.15.9 版本npminstall-gpnpm9.15.9# 验证安装pnpm-v# 应显示 9.15.9# 配置 pnpm设置 pnpm home 目录等pnpmsetup# 重新加载 shell 配置source~/.bashrcpnpm 常用命令# 安装项目依赖pnpminstall# 安装并添加新包pnpmaddpackage-name# 安装开发依赖pnpmadd-Ddev-package-name# 删除包pnpmremove package-name# 更新包pnpmupdate# 清空缓存pnpmstore prune为什么 Refly 使用 pnpmRefly 是一个 Monorepo 项目包含 2 个应用api 和 web和 24 个共享包。pnpm 的 Monorepo 支持自动解析包间的依赖关系符号链接共享代码避免重复更快的安装和更新速度防止幽灵依赖问题3.4 Ubuntu 快速安装脚本为了简化安装流程你可以使用以下一键安装脚本#!/bin/bashecho Refly 开发环境安装脚本Ubuntu/Debian # 更新系统echo1. 更新系统包...sudoapt-getupdatesudoapt-getupgrade-y# 安装 Dockerecho2. 安装 Docker...sudoapt-getinstall-yca-certificatescurlgnupg lsb-releasesudomkdir-p/etc/apt/keyringscurl-fsSLhttps://download.docker.com/linux/ubuntu/gpg|\sudogpg--dearmor-o/etc/apt/keyrings/docker.gpgechodeb [arch$(dpkg --print-architecture)signed-by/etc/apt/keyrings/docker.gpg] \ https://download.docker.com/linux/ubuntu$(lsb_release-cs)stable|\sudotee/etc/apt/sources.list.d/docker.list/dev/nullsudoapt-getupdatesudoapt-getinstall-ydocker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin# 配置 Docker 用户组echo3. 配置 Docker 用户组...sudousermod-aGdocker$USERnewgrpdocker# 启动 Dockerecho4. 启动 Docker 服务...sudosystemctl startdockersudosystemctlenabledocker# 安装 Node.jsecho5. 安装 Node.js...curl-fsSLhttps://deb.nodesource.com/setup_20.x|sudo-Ebash-sudoapt-getinstall-ynodejs# 安装 pnpmecho6. 安装 pnpm...npminstall-gpnpm9.15.9pnpmsetupecho 安装完成 echo验证环境echoDocker 版本docker--versionechoDocker Compose 版本dockercompose versionechoNode.js 版本node-vechopnpm 版本pnpm-v将上述脚本保存为install-refly.sh然后运行chmodx install-refly.sh ./install-refly.sh4、项目初始化4.1 克隆项目# 使用 HTTPS 克隆gitclone https://github.com/refly-ai/refly.git# 进入项目目录cdrefly4.2 安装依赖pnpminstall…详情请参照古月居