Refly项目开发环境搭建与贡献指南

🎯 前言：为什么选择贡献Refly？

还在为AI原生创作工具的复杂性而头疼？想要参与一个真正开源的AI协作工作空间项目？Refly作为开源AI原生创作引擎，提供了直观的自由画布界面，集成了多线程对话、知识库RAG集成、上下文记忆和智能搜索等强大功能。本文将为你提供完整的开发环境搭建指南和贡献流程，助你快速融入这个充满活力的开源社区。

读完本文，你将获得：

• ✅ 完整的Refly开发环境配置方案
• ✅ 多应用（Web、API、桌面端）开发调试技巧
• ✅ 代码结构深度解析与贡献最佳实践
• ✅ 提交PR和参与社区协作的完整流程
• ✅ 常见问题排查与性能优化建议

📋 环境要求与前置准备

系统要求

组件	最低要求	推荐配置
CPU	1核心	4核心以上
内存	2GB	8GB以上
操作系统	Linux/macOS/Windows	Linux/macOS
Docker	20.10.0+	最新稳定版
Node.js	20.19.0 (LTS)	20.19.0+
pnpm	9.15.9	9.15.9+

必备工具安装

1. Docker安装

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker.io docker-compose
sudo systemctl enable docker
sudo systemctl start docker

# macOS (使用Homebrew)
brew install docker
open /Applications/Docker.app

# Windows
# 从Docker官网下载Docker Desktop安装包

2. Node.js版本管理

强烈推荐使用nvm管理Node.js版本：

# 安装nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash

# 重新加载shell配置
source ~/.bashrc  # 如果使用zsh: source ~/.zshrc

# 安装指定Node.js版本
nvm install 20.19.0
nvm use 20.19.0

3. pnpm包管理器

# 启用corepack（Node.js内置）
corepack enable

# 或者全局安装pnpm
npm install -g pnpm@9.15.9

# 验证安装
pnpm -v  # 应该输出 9.15.9

🚀 开发环境搭建实战

步骤1：获取项目代码

# 1. Fork项目到自己的GitHub账户
# 访问项目代码仓库点击Fork

# 2. 克隆fork后的仓库
git clone [e-mail]:<你的用户名>/refly.git
cd refly

# 3. 添加上游仓库（可选但推荐）
git remote add upstream https://gitcode.com/gh_mirrors/re/refly.git

步骤2：启动中间件服务

Refly依赖多个中间件服务，使用Docker Compose一键启动：

# 进入docker部署目录
cd deploy/docker

# 启动所有中间件服务
docker compose -f docker-compose.middleware.yml -p refly up -d

# 检查服务状态
docker ps | grep refly_

# 预期输出应该包含以下服务：
# refly_redis, refly_elasticsearch, refly_qdrant, refly_minio等

如果遇到容器健康检查失败，可以查看日志排查：

# 查看特定容器日志
docker logs refly_redis
docker logs refly_elasticsearch

# 重启问题容器
docker restart refly_redis

步骤3：安装依赖和构建

# 回到项目根目录
cd ../..

# 安装所有workspace依赖
pnpm install

# 复制开发环境配置
pnpm copy-env:develop

# 首次构建所有包
pnpm build

步骤4：启动开发服务器

方案A：统一启动（推荐）

# 同时启动API和Web应用
pnpm dev

方案B：分别启动

# 终端1 - 启动Web前端
cd apps/web
pnpm dev

# 终端2 - 启动API后端  
cd apps/api
pnpm dev

访问 http://localhost:5173 即可开始开发。

步骤5：桌面应用开发（可选）

# 启动Electron桌面应用
pnpm dev:electron

# 或者分别启动
cd apps/web && pnpm dev:electron    # 终端1
cd apps/desktop && pnpm dev:electron # 终端2

🏗️ 项目架构深度解析

整体架构图

graph TB
    subgraph Frontend Applications
        Web[Web App - React/TypeScript]
        Desktop[Desktop App - Electron]
        Extension[Browser Extension]
    end

    subgraph Backend Services
        API[API Server - NestJS]
        DB[(Database - PostgreSQL)]
        Redis[Redis - Cache & Session]
        Elastic[Elasticsearch - Search]
        Qdrant[Qdrant - Vector Store]
    end

    subgraph AI Components
        Providers[AI Providers - OpenAI/Anthropic/etc]
        RAG[RAG Pipeline - Knowledge Retrieval]
        Canvas[Canvas Engine - Real-time Collaboration]
    end

    Web --> API
    Desktop --> API
    Extension --> API
    
    API --> DB
    API --> Redis
    API --> Elastic
    API --> Qdrant
    
    API --> Providers
    API --> RAG
    API --> Canvas

代码组织结构

refly/
├── apps/                 # 应用层
│   ├── api/             # NestJS后端API
│   ├── web/             # React前端Web应用
│   ├── desktop/         # Electron桌面应用
│   └── extension/       # 浏览器扩展
├── packages/            # 共享包
│   ├── providers/       # AI提供商抽象
│   ├── common-types/    # 共享TypeScript类型
│   ├── ai-workspace-common/ # AI工作区通用组件
│   ├── utils/           # 工具函数
│   └── ...             # 其他共享包
├── deploy/              # 部署配置
└── docs/               # 文档

关键技术栈对比

技术领域	主要技术	替代方案	选择理由
前端框架	React + TypeScript	Vue, Svelte	生态丰富，类型安全
后端框架	NestJS	Express, Fastify	企业级架构，TypeScript原生
状态管理	Zustand	Redux, MobX	简单轻量，性能优异
样式方案	Tailwind CSS	Styled-components, CSS Modules	开发效率高，设计一致
数据库ORM	Prisma	TypeORM, Sequelize	类型安全，开发体验好
实时协作	Yjs + HocusPocus	Socket.io, Colyseus	CRDT基础，无冲突合并

💻 开发工作流与最佳实践

1. 代码规范与质量保障

# 代码格式化
pnpm format

# 代码检查
pnpm lint

# 类型检查
pnpm check

# 运行测试
pnpm test

# 提交前自动格式化（通过husky钩子）
git add .
git commit -m "feat: add new feature"  # 自动触发lint-staged

2. 提交信息规范

Refly使用Conventional Commits规范：

# 示例提交信息
feat(canvas): add multi-select functionality
fix(api): resolve memory leak in RAG pipeline
docs: update development setup guide
chore: update dependencies to latest versions

3. 调试技巧

API调试

# 启用调试模式
cd apps/api
pnpm dev:debug

# 然后使用Chrome DevTools访问 chrome://inspect

前端调试

# 在浏览器中直接调试React组件
# 安装React Developer Tools扩展

🎯 贡献流程详解

1. 选择贡献方向

根据你的技能和兴趣选择合适的方向：

贡献领域	技术需求	优先级	适合人群
Canvas & AI功能	React, Canvas API, AI集成	高	前端工程师，AI工程师
知识库RAG	向量数据库，语义搜索	中	后端工程师，搜索专家
前端体验	React, TypeScript, CSS	中	前端工程师，UI/UX设计师
开发者体验	API设计，SDK开发	中	全栈工程师
核心架构	系统设计，性能优化	高	资深工程师

2. 寻找合适的Issue

# 查看开放的Issue
# 访问项目Issue页面，筛选"good first issue"标签

# 或者创建新Issue前先搜索是否已有类似建议

3. 开发流程

sequenceDiagram
    participant Developer
    participant LocalEnv
    participant GitHub

    Developer->>LocalEnv: git checkout -b feature-branch
    Developer->>LocalEnv: 开发功能并测试
    Developer->>LocalEnv: pnpm test && pnpm lint
    Developer->>GitHub: git push origin feature-branch
    Developer->>GitHub: 创建Pull Request
    GitHub->>Developer: CI/CD自动检查
    Note right of GitHub: 代码审查、测试通过
    GitHub->>GitHub: 合并到main分支

4. PR提交 checklist

• [ ] 代码遵循项目规范
• [ ] 添加或更新了相关测试
• [ ] 更新了文档（如需要）
• [ ] 提交信息符合Conventional Commits
• [ ] 所有CI检查通过
• [ ] 代码经过自测

🔧 常见问题排查

1. Docker容器启动失败

问题: docker compose up 报错或容器不断重启

解决方案:

# 检查Docker资源分配
docker system df  # 查看磁盘使用
docker stats     # 查看资源使用

# 清理无用资源
docker system prune -a

# 增加Docker资源限制（Docker Desktop）
# 设置 → Resources → 增加内存和CPU限制

2. Node.js版本不兼容

问题: pnpm install 失败或运行时错误

解决方案:

# 确认Node.js版本
node -v  # 应该是 20.19.0

# 使用nvm切换版本
nvm install 20.19.0
nvm use 20.19.0

# 清除npm缓存
npm cache clean --force

3. 中间件连接问题

问题: API无法连接Redis/Elasticsearch

解决方案:

# 检查中间件服务状态
docker ps -a

# 查看容器日志
docker logs refly_redis

# 重启特定服务
docker compose -f deploy/docker/docker-compose.middleware.yml restart redis

# 检查网络连接
docker network ls
docker network inspect refly_default

4. 构建错误

问题: pnpm build 失败

解决方案:

# 清理缓存重新安装
rm -rf node_modules
pnpm install

# 清除Turbo构建缓存
pnpm turbo clean

# 单独构建问题包
cd apps/api && pnpm build

🚀 性能优化建议

开发环境优化

# 使用快速构建模式（开发时）
cd apps/api && pnpm build:fast

# 禁用不必要的中间件（开发时）
# 在.env.development中设置：
ENABLE_ELASTICSEARCH=false
ENABLE_QDRANT=false

内存优化

// 在Node.js启动时增加内存限制
// package.json scripts中：
"dev": "NODE_OPTIONS='--max-old-space-size=4096' nodemon"

🌟 下一步学习路径

初级贡献者

1. 修复文档错别字或翻译问题
2. 解决带有"good first issue"标签的bug
3. 添加单元测试覆盖

中级贡献者

1. 实现小型功能特性
2. 优化现有代码性能
3. 参与代码审查

高级贡献者

1. 设计并实现核心功能模块
2. 领导技术方案设计
3. 指导新人贡献者

📞 获取帮助与社区参与

• 社区频道: 加入实时技术讨论
• 项目讨论区: 提出问题和建议
• 项目文档: 查阅详细API和使用指南
• Issue跟踪: 报告bug和功能请求

记住：每个贡献都很重要，无论大小。Refly社区欢迎所有类型的贡献，包括代码、文档、测试、设计反馈等。

---

准备好了吗？ 现在就开始你的Refly贡献之旅吧！选择一个小任务开始，逐步深入这个激动人心的AI原生创作引擎项目。遇到问题时，社区随时为你提供帮助。🚀

✨ 如果本文对你有帮助，请给项目点个Star支持我们的开源工作！