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：

# 下载并安装 Docker Desktop
# https://www.docker.com/products/docker-desktop/

# 启动后验证
docker --version
docker-compose --version

macOS：

# 使用 Homebrew
brew install --cask docker

# 或下载安装包
# https://www.docker.com/products/docker-desktop/

2. 创建项目目录

mkdir ai-clinical-research
cd ai-clinical-research

3. 创建 docker-compose.yml

# 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. 启动所有服务

# 启动所有容器
docker-compose up -d

# 查看运行状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 停止所有容器
docker-compose down

# 停止并删除数据
docker-compose down -v

5. 验证服务

# 检查 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：

# 下载安装包
# 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：

brew install postgresql@15
brew services start postgresql@15

# 创建数据库
createdb ai_clinical_research

2. 安装 Redis

Windows：

# 使用 Memurai（Redis for Windows）
# https://www.memurai.com/get-memurai

# 或使用 WSL2 + Docker
wsl --install
# 然后在 WSL2 中运行 Docker

macOS：

brew install redis
brew services start redis

3. 安装 Node.js

# Windows 和 macOS
# 下载 LTS 版本
# https://nodejs.org/

# 验证安装
node --version  # v18.x 或更高
npm --version

4. 安装 Dify（本地方式）

# 克隆 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）

{
  "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）

# 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）

# 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:

#!/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:

@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

检查端口占用：

# Windows
netstat -ano | findstr :3000

# macOS/Linux
lsof -i :3000

3. 数据备份

定期备份数据库：

# 备份
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个月+： 生产环境（正式服务器）

现在就可以开始：

# 1. 安装 Docker Desktop
# 2. 创建项目目录
# 3. 复制上面的 docker-compose.yml
# 4. 启动开发环境
docker-compose up -d

节省成本：约¥350-400（开发阶段）

---

文档版本：v1.0
更新时间：2025-10-10