chore: project initialization - Day 4 environment setup
This commit is contained in:
AI Clinical Dev Team
704
开发环境配置指南.md
Normal file
704
开发环境配置指南.md
Normal file
@@ -0,0 +1,704 @@
|
||||
# 开发环境配置指南
|
||||
|
||||
## 🎯 核心建议：先本地开发，MVP完成后再上云
|
||||
|
||||
**理由：**
|
||||
- ✅ 节省成本（开发期2.5个月无需云服务器费用）
|
||||
- ✅ 调试方便（本地开发响应快）
|
||||
- ✅ 灵活性高（随时修改配置）
|
||||
- ✅ 降低风险（等功能稳定后再上云）
|
||||
|
||||
---
|
||||
|
||||
## 📅 分阶段部署策略
|
||||
|
||||
### 阶段1：本地开发（0-2个月）⭐ 当前阶段
|
||||
|
||||
**环境：** 开发人员本地电脑
|
||||
|
||||
**需要的硬件：**
|
||||
- CPU: 4核心以上
|
||||
- 内存: 16GB以上（推荐）
|
||||
- 硬盘: 50GB可用空间
|
||||
- 操作系统: Windows 10+、macOS、Linux
|
||||
|
||||
**需要安装：**
|
||||
- Docker Desktop（运行Dify）
|
||||
- Node.js 18+（后端开发）
|
||||
- PostgreSQL 15+（或用Docker）
|
||||
- Redis 7+（或用Docker）
|
||||
|
||||
**费用：** ¥0（使用现有设备）
|
||||
|
||||
**适用于：**
|
||||
- 搭建基础架构
|
||||
- 开发核心功能
|
||||
- 本地测试
|
||||
- MVP开发
|
||||
|
||||
---
|
||||
|
||||
### 阶段2：内测环境（2-2.5个月）
|
||||
|
||||
**环境：** 小型云服务器
|
||||
|
||||
**推荐配置：**
|
||||
- CPU: 2核心
|
||||
- 内存: 4GB
|
||||
- 硬盘: 40GB
|
||||
- 带宽: 1Mbps
|
||||
|
||||
**云厂商选择：**
|
||||
- 阿里云：轻量应用服务器 约¥60/月
|
||||
- 腾讯云：轻量应用服务器 约¥50/月
|
||||
|
||||
**费用：** ¥50-60/月
|
||||
|
||||
**适用于：**
|
||||
- 小范围内测（5-10人）
|
||||
- 功能验证
|
||||
- 性能初步测试
|
||||
|
||||
---
|
||||
|
||||
### 阶段3：正式上线（3个月后）
|
||||
|
||||
**环境：** 生产级云服务器
|
||||
|
||||
**推荐配置：**
|
||||
- CPU: 4核心
|
||||
- 内存: 8GB
|
||||
- 硬盘: 100GB SSD
|
||||
- 带宽: 5Mbps
|
||||
|
||||
**费用：** ¥200-300/月
|
||||
|
||||
**适用于：**
|
||||
- 正式对外服务
|
||||
- 100+用户规模
|
||||
|
||||
---
|
||||
|
||||
## 💻 本地开发环境配置（详细步骤）
|
||||
|
||||
### 方案A：全Docker方式（推荐 ⭐）
|
||||
|
||||
**优点：** 环境隔离、配置简单、一键启动
|
||||
|
||||
#### 1. 安装Docker Desktop
|
||||
|
||||
**Windows：**
|
||||
```bash
|
||||
# 下载并安装 Docker Desktop
|
||||
# https://www.docker.com/products/docker-desktop/
|
||||
|
||||
# 启动后验证
|
||||
docker --version
|
||||
docker-compose --version
|
||||
```
|
||||
|
||||
**macOS：**
|
||||
```bash
|
||||
# 使用 Homebrew
|
||||
brew install --cask docker
|
||||
|
||||
# 或下载安装包
|
||||
# https://www.docker.com/products/docker-desktop/
|
||||
```
|
||||
|
||||
#### 2. 创建项目目录
|
||||
|
||||
```bash
|
||||
mkdir ai-clinical-research
|
||||
cd ai-clinical-research
|
||||
```
|
||||
|
||||
#### 3. 创建 docker-compose.yml
|
||||
|
||||
```yaml
|
||||
# docker-compose.yml
|
||||
version: '3.8'
|
||||
|
||||
services:
|
||||
# PostgreSQL 数据库
|
||||
postgres:
|
||||
image: postgres:15-alpine
|
||||
container_name: acr-postgres
|
||||
environment:
|
||||
POSTGRES_DB: ai_clinical_research
|
||||
POSTGRES_USER: dev_user
|
||||
POSTGRES_PASSWORD: dev_password
|
||||
ports:
|
||||
- "5432:5432"
|
||||
volumes:
|
||||
- postgres_data:/var/lib/postgresql/data
|
||||
restart: unless-stopped
|
||||
|
||||
# Redis 缓存
|
||||
redis:
|
||||
image: redis:7-alpine
|
||||
container_name: acr-redis
|
||||
ports:
|
||||
- "6379:6379"
|
||||
volumes:
|
||||
- redis_data:/data
|
||||
restart: unless-stopped
|
||||
|
||||
# Dify（RAG系统）
|
||||
dify:
|
||||
image: langgenius/dify-api:latest
|
||||
container_name: acr-dify
|
||||
environment:
|
||||
- DB_USERNAME=dify
|
||||
- DB_PASSWORD=dify_password
|
||||
- DB_HOST=dify-postgres
|
||||
- DB_PORT=5432
|
||||
- DB_DATABASE=dify
|
||||
- REDIS_HOST=dify-redis
|
||||
- REDIS_PORT=6379
|
||||
- SECRET_KEY=your-secret-key-change-this
|
||||
ports:
|
||||
- "5001:5001"
|
||||
depends_on:
|
||||
- dify-postgres
|
||||
- dify-redis
|
||||
restart: unless-stopped
|
||||
|
||||
# Dify 专用 PostgreSQL
|
||||
dify-postgres:
|
||||
image: postgres:15-alpine
|
||||
container_name: acr-dify-postgres
|
||||
environment:
|
||||
POSTGRES_DB: dify
|
||||
POSTGRES_USER: dify
|
||||
POSTGRES_PASSWORD: dify_password
|
||||
volumes:
|
||||
- dify_postgres_data:/var/lib/postgresql/data
|
||||
restart: unless-stopped
|
||||
|
||||
# Dify 专用 Redis
|
||||
dify-redis:
|
||||
image: redis:7-alpine
|
||||
container_name: acr-dify-redis
|
||||
volumes:
|
||||
- dify_redis_data:/data
|
||||
restart: unless-stopped
|
||||
|
||||
# Dify Web界面（可选，开发调试用）
|
||||
dify-web:
|
||||
image: langgenius/dify-web:latest
|
||||
container_name: acr-dify-web
|
||||
environment:
|
||||
- CONSOLE_API_URL=http://localhost:5001
|
||||
ports:
|
||||
- "3000:3000"
|
||||
depends_on:
|
||||
- dify
|
||||
restart: unless-stopped
|
||||
|
||||
volumes:
|
||||
postgres_data:
|
||||
redis_data:
|
||||
dify_postgres_data:
|
||||
dify_redis_data:
|
||||
|
||||
networks:
|
||||
default:
|
||||
name: acr-network
|
||||
```
|
||||
|
||||
#### 4. 启动所有服务
|
||||
|
||||
```bash
|
||||
# 启动所有容器
|
||||
docker-compose up -d
|
||||
|
||||
# 查看运行状态
|
||||
docker-compose ps
|
||||
|
||||
# 查看日志
|
||||
docker-compose logs -f
|
||||
|
||||
# 停止所有容器
|
||||
docker-compose down
|
||||
|
||||
# 停止并删除数据
|
||||
docker-compose down -v
|
||||
```
|
||||
|
||||
#### 5. 验证服务
|
||||
|
||||
```bash
|
||||
# 检查 PostgreSQL
|
||||
docker exec -it acr-postgres psql -U dev_user -d ai_clinical_research -c "\dt"
|
||||
|
||||
# 检查 Redis
|
||||
docker exec -it acr-redis redis-cli ping
|
||||
# 应返回: PONG
|
||||
|
||||
# 检查 Dify
|
||||
curl http://localhost:5001/health
|
||||
# 或在浏览器访问 http://localhost:3000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 方案B：本地安装方式
|
||||
|
||||
**适用于：** 不想用Docker或机器配置较低
|
||||
|
||||
#### 1. 安装 PostgreSQL
|
||||
|
||||
**Windows：**
|
||||
```bash
|
||||
# 下载安装包
|
||||
# https://www.postgresql.org/download/windows/
|
||||
|
||||
# 安装后创建数据库
|
||||
psql -U postgres
|
||||
CREATE DATABASE ai_clinical_research;
|
||||
CREATE USER dev_user WITH PASSWORD 'dev_password';
|
||||
GRANT ALL PRIVILEGES ON DATABASE ai_clinical_research TO dev_user;
|
||||
```
|
||||
|
||||
**macOS：**
|
||||
```bash
|
||||
brew install postgresql@15
|
||||
brew services start postgresql@15
|
||||
|
||||
# 创建数据库
|
||||
createdb ai_clinical_research
|
||||
```
|
||||
|
||||
#### 2. 安装 Redis
|
||||
|
||||
**Windows：**
|
||||
```bash
|
||||
# 使用 Memurai（Redis for Windows）
|
||||
# https://www.memurai.com/get-memurai
|
||||
|
||||
# 或使用 WSL2 + Docker
|
||||
wsl --install
|
||||
# 然后在 WSL2 中运行 Docker
|
||||
```
|
||||
|
||||
**macOS：**
|
||||
```bash
|
||||
brew install redis
|
||||
brew services start redis
|
||||
```
|
||||
|
||||
#### 3. 安装 Node.js
|
||||
|
||||
```bash
|
||||
# Windows 和 macOS
|
||||
# 下载 LTS 版本
|
||||
# https://nodejs.org/
|
||||
|
||||
# 验证安装
|
||||
node --version # v18.x 或更高
|
||||
npm --version
|
||||
```
|
||||
|
||||
#### 4. 安装 Dify（本地方式）
|
||||
|
||||
```bash
|
||||
# 克隆 Dify
|
||||
git clone https://github.com/langgenius/dify.git
|
||||
cd dify/api
|
||||
|
||||
# 安装 Python 依赖
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 配置环境变量
|
||||
cp .env.example .env
|
||||
# 编辑 .env，填入数据库连接信息
|
||||
|
||||
# 运行数据库迁移
|
||||
flask db upgrade
|
||||
|
||||
# 启动 API
|
||||
flask run --host=0.0.0.0 --port=5001
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 开发工具推荐
|
||||
|
||||
### 必需工具
|
||||
|
||||
1. **代码编辑器**
|
||||
- VS Code（推荐）⭐
|
||||
- WebStorm
|
||||
- Cursor（AI辅助编程）
|
||||
|
||||
2. **API测试工具**
|
||||
- Postman（推荐）⭐
|
||||
- Insomnia
|
||||
- VS Code REST Client 插件
|
||||
|
||||
3. **数据库管理工具**
|
||||
- DBeaver（推荐，免费）⭐
|
||||
- TablePlus
|
||||
- pgAdmin
|
||||
|
||||
4. **Git客户端**
|
||||
- Git命令行
|
||||
- GitHub Desktop
|
||||
- SourceTree
|
||||
|
||||
### 推荐插件（VS Code）
|
||||
|
||||
```json
|
||||
{
|
||||
"recommendations": [
|
||||
"dbaeumer.vscode-eslint", // ESLint
|
||||
"esbenp.prettier-vscode", // 代码格式化
|
||||
"prisma.prisma", // Prisma ORM
|
||||
"ms-azuretools.vscode-docker", // Docker
|
||||
"humao.rest-client", // REST API 测试
|
||||
"bradlc.vscode-tailwindcss", // TailwindCSS
|
||||
"dsznajder.es7-react-js-snippets" // React 代码片段
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 本地开发配置文件
|
||||
|
||||
### 后端环境变量（.env）
|
||||
|
||||
```bash
|
||||
# backend/.env
|
||||
|
||||
# 数据库
|
||||
DATABASE_URL="postgresql://dev_user:dev_password@localhost:5432/ai_clinical_research"
|
||||
|
||||
# Redis
|
||||
REDIS_URL="redis://localhost:6379"
|
||||
|
||||
# JWT
|
||||
JWT_SECRET="your-jwt-secret-change-this-in-production"
|
||||
JWT_EXPIRES_IN="7d"
|
||||
|
||||
# LLM API Keys（本地开发可先不填，等需要测试时再填）
|
||||
DEEPSEEK_API_KEY=""
|
||||
DASHSCOPE_API_KEY=""
|
||||
GEMINI_API_KEY=""
|
||||
|
||||
# Dify
|
||||
DIFY_API_URL="http://localhost:5001"
|
||||
DIFY_API_KEY="" # 启动Dify后在管理界面获取
|
||||
|
||||
# 对象存储（本地开发可先不配置）
|
||||
OSS_ACCESS_KEY_ID=""
|
||||
OSS_ACCESS_KEY_SECRET=""
|
||||
OSS_BUCKET=""
|
||||
OSS_REGION=""
|
||||
|
||||
# 应用配置
|
||||
NODE_ENV="development"
|
||||
PORT=3001
|
||||
```
|
||||
|
||||
### 前端环境变量（.env.local）
|
||||
|
||||
```bash
|
||||
# frontend/.env.local
|
||||
|
||||
# API 地址
|
||||
VITE_API_URL="http://localhost:3001"
|
||||
|
||||
# 是否启用调试模式
|
||||
VITE_DEBUG=true
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 快速启动脚本
|
||||
|
||||
### 一键启动（适用于方案A：Docker）
|
||||
|
||||
创建 `start-dev.sh`（macOS/Linux）或 `start-dev.bat`（Windows）：
|
||||
|
||||
**start-dev.sh:**
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
echo "🚀 启动开发环境..."
|
||||
|
||||
# 启动 Docker 服务
|
||||
echo "📦 启动 Docker 容器..."
|
||||
docker-compose up -d
|
||||
|
||||
# 等待服务就绪
|
||||
echo "⏳ 等待服务启动..."
|
||||
sleep 10
|
||||
|
||||
# 启动后端
|
||||
echo "🔧 启动后端服务..."
|
||||
cd backend
|
||||
npm run dev &
|
||||
BACKEND_PID=$!
|
||||
|
||||
# 启动前端
|
||||
echo "🎨 启动前端服务..."
|
||||
cd ../frontend
|
||||
npm run dev &
|
||||
FRONTEND_PID=$!
|
||||
|
||||
echo "✅ 开发环境启动完成！"
|
||||
echo ""
|
||||
echo "📝 访问地址："
|
||||
echo " 前端: http://localhost:5173"
|
||||
echo " 后端: http://localhost:3001"
|
||||
echo " Dify: http://localhost:3000"
|
||||
echo ""
|
||||
echo "按 Ctrl+C 停止所有服务"
|
||||
|
||||
# 等待用户中断
|
||||
wait $BACKEND_PID $FRONTEND_PID
|
||||
```
|
||||
|
||||
**start-dev.bat:**
|
||||
```batch
|
||||
@echo off
|
||||
echo 🚀 启动开发环境...
|
||||
|
||||
echo 📦 启动 Docker 容器...
|
||||
docker-compose up -d
|
||||
|
||||
echo ⏳ 等待服务启动...
|
||||
timeout /t 10
|
||||
|
||||
echo 🔧 启动后端服务...
|
||||
start cmd /k "cd backend && npm run dev"
|
||||
|
||||
echo 🎨 启动前端服务...
|
||||
start cmd /k "cd frontend && npm run dev"
|
||||
|
||||
echo ✅ 开发环境启动完成！
|
||||
echo.
|
||||
echo 📝 访问地址：
|
||||
echo 前端: http://localhost:5173
|
||||
echo 后端: http://localhost:3001
|
||||
echo Dify: http://localhost:3000
|
||||
echo.
|
||||
pause
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💰 成本对比
|
||||
|
||||
### 本地开发（推荐用于开发阶段）
|
||||
|
||||
| 项目 | 成本 |
|
||||
|------|------|
|
||||
| 硬件 | ¥0（使用现有电脑） |
|
||||
| 软件 | ¥0（全部开源免费） |
|
||||
| LLM API | ¥10-50（少量测试） |
|
||||
| **总计** | **¥10-50/2.5个月** |
|
||||
|
||||
### 云服务器（开发环境）
|
||||
|
||||
| 项目 | 成本 |
|
||||
|------|------|
|
||||
| 服务器（2核4G） | ¥60/月 × 2.5 = ¥150 |
|
||||
| 数据库（小规格） | ¥50/月 × 2.5 = ¥125 |
|
||||
| 带宽 | ¥30/月 × 2.5 = ¥75 |
|
||||
| LLM API | ¥50 |
|
||||
| **总计** | **¥400/2.5个月** |
|
||||
|
||||
**节省：约¥350-390（开发阶段）**
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 本地开发注意事项
|
||||
|
||||
### 1. 资源限制
|
||||
|
||||
**Docker Desktop 默认限制：**
|
||||
- CPU: 2核心
|
||||
- 内存: 2GB
|
||||
|
||||
**建议调整：**
|
||||
```
|
||||
设置 → Resources → Advanced
|
||||
- CPUs: 4（如果机器允许）
|
||||
- Memory: 8GB（推荐）
|
||||
- Swap: 2GB
|
||||
```
|
||||
|
||||
### 2. 端口占用
|
||||
|
||||
**常用端口：**
|
||||
- 3000: Dify Web界面
|
||||
- 3001: 后端API
|
||||
- 5001: Dify API
|
||||
- 5173: 前端开发服务器
|
||||
- 5432: PostgreSQL
|
||||
- 6379: Redis
|
||||
|
||||
**检查端口占用：**
|
||||
```bash
|
||||
# Windows
|
||||
netstat -ano | findstr :3000
|
||||
|
||||
# macOS/Linux
|
||||
lsof -i :3000
|
||||
```
|
||||
|
||||
### 3. 数据备份
|
||||
|
||||
**定期备份数据库：**
|
||||
```bash
|
||||
# 备份
|
||||
docker exec acr-postgres pg_dump -U dev_user ai_clinical_research > backup.sql
|
||||
|
||||
# 恢复
|
||||
docker exec -i acr-postgres psql -U dev_user ai_clinical_research < backup.sql
|
||||
```
|
||||
|
||||
### 4. API Key 管理
|
||||
|
||||
**开发阶段策略：**
|
||||
- 使用个人API Key（不要提交到Git）
|
||||
- 设置低配额（避免误操作）
|
||||
- 使用便宜的模型测试（DeepSeek-V3）
|
||||
|
||||
---
|
||||
|
||||
## 🎯 什么时候需要购买云服务器？
|
||||
|
||||
### 场景1：需要团队协作
|
||||
|
||||
**时机：** 当第2名开发者加入时
|
||||
|
||||
**原因：**
|
||||
- 共享开发环境
|
||||
- 统一数据库
|
||||
- 方便联调
|
||||
|
||||
**推荐：** 购买小型云服务器（2核4G，¥60/月）
|
||||
|
||||
### 场景2：需要外部测试
|
||||
|
||||
**时机：** MVP完成，需要给用户试用
|
||||
|
||||
**原因：**
|
||||
- 外网访问
|
||||
- 稳定性测试
|
||||
- 收集反馈
|
||||
|
||||
**推荐：** 购买小型云服务器
|
||||
|
||||
### 场景3：准备正式上线
|
||||
|
||||
**时机：** 功能稳定，准备对外服务
|
||||
|
||||
**原因：**
|
||||
- 生产级稳定性
|
||||
- 性能优化
|
||||
- 数据安全
|
||||
|
||||
**推荐：** 购买生产级服务器（4核8G，¥250/月）
|
||||
|
||||
---
|
||||
|
||||
## 📋 分阶段采购清单
|
||||
|
||||
### 第0-8周：本地开发（当前阶段）⭐
|
||||
|
||||
**需要购买：**
|
||||
- [ ] ❌ 不需要任何云服务！
|
||||
|
||||
**需要准备：**
|
||||
- [ ] ✅ 本地安装 Docker Desktop
|
||||
- [ ] ✅ 申请 DeepSeek API Key（免费额度足够测试）
|
||||
- [ ] ✅ 申请 Qwen API Key（可选）
|
||||
|
||||
**费用：** ¥0-10
|
||||
|
||||
---
|
||||
|
||||
### 第9-10周：内测准备（如需要）
|
||||
|
||||
**需要购买：**
|
||||
- [ ] 🟡 轻量应用服务器（2核4G）¥60/月
|
||||
- [ ] 🟡 或使用阿里云/腾讯云免费试用（新用户）
|
||||
|
||||
**用途：**
|
||||
- 小范围内测
|
||||
- 团队联调
|
||||
|
||||
**费用：** ¥0-120
|
||||
|
||||
---
|
||||
|
||||
### 第11周+：正式上线
|
||||
|
||||
**需要购买：**
|
||||
- [ ] 🔴 云服务器（4核8G）¥250/月
|
||||
- [ ] 🔴 对象存储 OSS ¥50/月
|
||||
- [ ] 🔴 CDN加速 ¥50/月
|
||||
- [ ] 🔴 域名 ¥50/年
|
||||
- [ ] 🔴 SSL证书（可用免费的Let's Encrypt）
|
||||
|
||||
**费用：** ¥350/月起
|
||||
|
||||
---
|
||||
|
||||
## ✅ 推荐方案
|
||||
|
||||
### 第1-2个月（现在）：
|
||||
|
||||
**✅ 本地开发，不购买云服务器**
|
||||
|
||||
**理由：**
|
||||
1. 节省成本（¥0 vs ¥400）
|
||||
2. 调试方便（响应快）
|
||||
3. 灵活性高（随时修改）
|
||||
4. 功能还在开发中，不需要云环境
|
||||
|
||||
**需要做的：**
|
||||
1. 安装 Docker Desktop
|
||||
2. 按照本文档配置本地环境
|
||||
3. 申请 DeepSeek API Key（少量测试用）
|
||||
|
||||
### 第2.5个月：
|
||||
|
||||
**🟡 考虑购买小型云服务器（如需内测）**
|
||||
|
||||
### 第3个月+：
|
||||
|
||||
**🔴 购买生产级服务器（正式上线）**
|
||||
|
||||
---
|
||||
|
||||
## 🎉 总结
|
||||
|
||||
**回答您的问题：不需要现在购买云服务器！**
|
||||
|
||||
**建议：**
|
||||
1. ✅ **0-2个月：** 本地开发（Docker Desktop）
|
||||
2. 🟡 **2-2.5个月：** 内测环境（小型云服务器，可选）
|
||||
3. 🔴 **3个月+：** 生产环境（正式服务器）
|
||||
|
||||
**现在就可以开始：**
|
||||
```bash
|
||||
# 1. 安装 Docker Desktop
|
||||
# 2. 创建项目目录
|
||||
# 3. 复制上面的 docker-compose.yml
|
||||
# 4. 启动开发环境
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
**节省成本：约¥350-400（开发阶段）**
|
||||
|
||||
---
|
||||
|
||||
**文档版本：v1.0**
|
||||
**更新时间：2025-10-10**
|
||||
|
||||
Reference in New Issue
Block a user