AIclinicalresearch/开发环境配置指南.md

# 开发环境配置指南

## 🎯 核心建议：先本地开发，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**