AIclinicalresearch/docs/07-运维文档/01-环境配置指南.md

# 环境配置指南

> **文档版本：** v1.0  
> **创建日期：** 2025-11-09  
> **维护者：** 技术团队  
> **最后更新：** 2025-11-09

---

## 📋 文档说明

本文档记录系统运行所需的全部环境变量配置，包括：
- 数据库连接信息
- LLM API密钥配置
- 第三方服务配置
- 安全相关配置

---

## 🗄️ 数据库配置

### PostgreSQL连接信息

**当前配置：**
```env
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ai_clinical_research
```

**连接参数说明：**
| 参数 | 当前值 | 说明 |
|------|--------|------|
| 用户名 | postgres | PostgreSQL默认用户 |
| 密码 | postgres | 本地开发密码 |
| 主机 | localhost | 本地数据库 |
| 端口 | 5432 | PostgreSQL默认端口 |
| 数据库名 | ai_clinical_research | 项目数据库 |

**Schema信息：**
- **当前Schema：** `public`（所有13个表）
- **计划Schema：** 10个隔离Schema（Week 1实施）
  - platform_schema
  - common_schema
  - asl_schema
  - aia_schema
  - pkb_schema
  - dc_schema
  - rvw_schema
  - admin_schema
  - ssa_schema
  - st_schema

---

## 🤖 LLM API配置

### 1. DeepSeek API

**用途：** 主力大模型（推理、对话、批处理）

**配置：**
```env
DEEPSEEK_API_KEY=sk-your-deepseek-key
```

**获取方式：**
1. 访问：https://platform.deepseek.com
2. 注册/登录账号
3. 进入API Keys页面
4. 创建新的API Key

**使用场景：**
- AI智能问答（选题评价、PICO梳理等）
- 批处理任务
- 标题摘要初筛
- 全文复筛

**定价：**
- DeepSeek-V3: ¥1/M tokens（输入），¥2/M tokens（输出）

---

### 2. 通义千问（Qwen）API

**用途：** 备用模型、特定场景优化

**配置：**
```env
DASHSCOPE_API_KEY=sk-your-qwen-key
```

**获取方式：**
1. 访问：https://dashscope.console.aliyun.com
2. 开通DashScope服务
3. 创建API Key

**使用场景：**
- 长文本处理（Qwen-Long）
- 特定领域任务
- 模型对比筛选

**定价：**
- Qwen-Max: ¥0.04/1K tokens
- Qwen-Long: ¥0.005/1K tokens

---

### 3. CloseAI配置（代理OpenAI和Claude）⭐⭐⭐

**用途：** 通过代理平台稳定访问OpenAI和Claude API

**为什么使用CloseAI？**
- ✅ 国内稳定访问，无需科学上网
- ✅ 一个账号同时使用OpenAI和Claude
- ✅ 兼容OpenAI SDK标准接口
- ✅ 最新模型支持：GPT-5-Pro、Claude-Sonnet-4.5

**配置：**
```env
# CloseAI统一API Key
CLOSEAI_API_KEY=sk-cu0iepbXYGGx2jc7BqP6ogtSWmP6fk918qV3RUdtGC3Edlpo

# OpenAI端点（通过CloseAI代理）
CLOSEAI_OPENAI_BASE_URL=https://api.openai-proxy.org/v1

# Claude端点（通过CloseAI代理）
CLOSEAI_CLAUDE_BASE_URL=https://api.openai-proxy.org/anthropic
```

**支持的模型：**

| 模型系列 | 最新模型 | 说明 |
|---------|---------|------|
| **OpenAI** | `gpt-5-pro` | 最新GPT-5模型 ⭐ |
| OpenAI | `gpt-4-turbo-preview` | GPT-4高性能版本 |
| OpenAI | `gpt-3.5-turbo` | 快速经济版本 |
| **Claude** | `claude-sonnet-4-5-20250929` | 最新Claude-4.5 ⭐ |
| Claude | `claude-3-5-sonnet-20241022` | Claude-3.5稳定版 |
| Claude | `claude-3-opus-20240229` | Claude-3最强版本 |

**获取方式：**
1. 访问：https://platform.openai-proxy.org
2. 注册账号并充值
3. 在控制台获取API Key
4. 一个API Key可同时调用OpenAI和Claude

**代码示例（TypeScript）：**
```typescript
import OpenAI from 'openai';

// OpenAI (通过CloseAI)
const openaiClient = new OpenAI({
  apiKey: process.env.CLOSEAI_API_KEY,
  baseURL: 'https://api.openai-proxy.org/v1',
});

const gptResponse = await openaiClient.chat.completions.create({
  model: 'gpt-5-pro',
  messages: [{ role: 'user', content: '你好' }],
});

// Claude (通过CloseAI)
const claudeClient = new OpenAI({
  apiKey: process.env.CLOSEAI_API_KEY,
  baseURL: 'https://api.openai-proxy.org/anthropic',
});

const claudeResponse = await claudeClient.chat.completions.create({
  model: 'claude-sonnet-4-5-20250929',
  messages: [{ role: 'user', content: '你好' }],
});
```

**使用场景（AI智能文献 ⭐）：**
- **GPT-5-Pro：** 文献精准筛选、质量控制
- **Claude-4.5：** 第三方仲裁、结构化输出
- **双模型对比：** DeepSeek + GPT-5-Pro 快速+高质量
- **三模型共识：** 冲突时启用Claude仲裁

**定价（参考）：**
- GPT-5-Pro: ~¥0.10/1K tokens（输入），~¥0.20/1K tokens（输出）
- Claude-4.5-Sonnet: ~¥0.021/1K tokens（输入），~¥0.105/1K tokens（输出）

**注意事项：**
- ⚠️ API Key包含敏感信息，不要提交到Git
- ⚠️ 建议定期更换API Key
- ⚠️ 生产环境使用独立的API Key

---

## 🔧 Dify配置（RAG引擎）

**用途：** 知识库向量检索、RAG问答

**配置：**
```env
DIFY_API_KEY=app-your-dify-key
DIFY_API_URL=http://localhost/v1
```

**部署信息：**
- **本地部署：** Docker Compose
- **访问地址：** http://localhost
- **管理后台：** http://localhost/install
- **向量数据库：** Qdrant（内置）

**获取API Key：**
1. 访问 Dify 管理后台
2. 进入"应用"页面
3. 创建"知识库应用"
4. 复制API Key

**使用场景：**
- 个人知识库文档上传
- @知识库问答
- 智能引用功能

---

## 🔐 安全配置

### JWT密钥

**配置：**
```env
JWT_SECRET=your-secret-key-change-in-production
JWT_EXPIRES_IN=7d
```

**说明：**
- 用于用户认证Token签名
- 建议使用32位以上随机字符串
- 过期时间：7天

**生成强密钥（可选）：**
```bash
# Node.js生成
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# OpenSSL生成
openssl rand -hex 32
```

---

## 🌐 服务配置

### 后端服务

**配置：**
```env
PORT=3001
HOST=0.0.0.0
NODE_ENV=development
LOG_LEVEL=info
```

**说明：**
| 参数 | 值 | 说明 |
|------|-----|------|
| PORT | 3001 | 后端服务端口 |
| HOST | 0.0.0.0 | 监听所有网卡 |
| NODE_ENV | development | 开发环境 |
| LOG_LEVEL | info | 日志级别 |

---

### CORS配置

**配置：**
```env
CORS_ORIGIN=http://localhost:5173
```

**说明：**
- 允许前端跨域访问
- 前端开发服务器：http://localhost:5173

---

### Redis配置（可选）

**配置：**
```env
REDIS_URL=redis://localhost:6379
```

**说明：**
- 用于缓存和会话管理
- 当前未强制要求

---

## 📁 文件上传配置

**配置：**
```env
UPLOAD_MAX_SIZE=10485760
UPLOAD_DIR=./uploads
```

**说明：**
| 参数 | 值 | 说明 |
|------|-----|------|
| UPLOAD_MAX_SIZE | 10485760 | 10MB（字节） |
| UPLOAD_DIR | ./uploads | 上传文件存储目录 |

---

## 🚀 配置步骤

### 1. 检查环境变量文件

**位置：** `backend/.env`

如果文件不存在，参考以下模板创建：

```env
# ==================== 服务器配置 ====================
PORT=3001
HOST=0.0.0.0
NODE_ENV=development
LOG_LEVEL=info

# ==================== 数据库配置 ====================
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ai_clinical_research

# ==================== Redis配置 ====================
REDIS_URL=redis://localhost:6379

# ==================== JWT配置 ====================
JWT_SECRET=your-secret-key-change-in-production
JWT_EXPIRES_IN=7d

# ==================== LLM API配置 ====================
# DeepSeek
DEEPSEEK_API_KEY=sk-your-deepseek-key

# 通义千问（阿里云DashScope）
DASHSCOPE_API_KEY=sk-your-qwen-key

# Gemini（可选）
GEMINI_API_KEY=your-gemini-key

# ==================== Dify配置 ====================
DIFY_API_KEY=app-your-dify-key
DIFY_API_URL=http://localhost/v1

# ==================== 文件上传配置 ====================
UPLOAD_MAX_SIZE=10485760
UPLOAD_DIR=./uploads

# ==================== CORS配置 ====================
CORS_ORIGIN=http://localhost:5173
```

---

### 2. 验证配置

**启动后端服务：**
```bash
cd backend
npm run dev
```

**检查启动日志：**
```
✓ Prisma schema loaded
✓ Environment variables loaded from .env
✓ Datasource "db": PostgreSQL database "ai_clinical_research"
✓ Server running on http://0.0.0.0:3001
```

**验证数据库连接：**
```bash
cd backend
npx prisma migrate status
```

**预期输出：**
```
Environment variables loaded from .env
Datasource "db": PostgreSQL database "ai_clinical_research", schema "public" at "localhost:5432"
Database schema is up to date!
```

---

### 3. 常见问题排查

#### 问题1：数据库连接失败

**错误信息：**
```
Error: Can't reach database server at localhost:5432
```

**解决方案：**
1. 检查PostgreSQL是否启动
2. 验证端口5432是否被占用
3. 确认用户名密码是否正确

**检查PostgreSQL状态（Windows）：**
```bash
# 查看服务状态
Get-Service postgresql*

# 启动服务
Start-Service postgresql-x64-15
```

---

#### 问题2：LLM API调用失败

**错误信息：**
```
Error: Invalid API key
```

**解决方案：**
1. 检查API Key是否正确复制
2. 确认API Key是否已激活
3. 检查账户余额是否充足

---

#### 问题3：Dify连接失败

**错误信息：**
```
Error: connect ECONNREFUSED 127.0.0.1:80
```

**解决方案：**
1. 检查Dify是否启动：`docker-compose ps`
2. 启动Dify：`docker-compose up -d`
3. 验证访问：浏览器打开 http://localhost

---

## 🌟 平台基础设施配置（2025-11-16 新增）

> **⭐ 重要更新**：为支持云原生部署，新增平台基础设施环境变量  
> **详细文档**：[平台基础设施规划](../09-架构实施/04-平台基础设施规划.md)

---

### 1. 存储服务配置

#### **本地开发环境**

```bash
# backend/.env.development
STORAGE_TYPE=local
BASE_URL=http://localhost:3001
```

#### **生产环境（阿里云OSS）**

```bash
# SAE控制台 -> 环境变量配置
STORAGE_TYPE=oss
OSS_REGION=oss-cn-hangzhou
OSS_BUCKET=aiclinical-prod
OSS_ACCESS_KEY_ID=LTAI5t***
OSS_ACCESS_KEY_SECRET=***
OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com
```

#### **配置说明**

| 变量名 | 必需 | 默认值 | 说明 |
|--------|------|--------|------|
| `STORAGE_TYPE` | ✅ | `local` | 存储类型：`local` 或 `oss` |
| `BASE_URL` | 本地 | `http://localhost:3001` | 本地存储访问URL |
| `OSS_REGION` | 生产 | - | OSS区域（如：oss-cn-hangzhou） |
| `OSS_BUCKET` | 生产 | - | OSS Bucket名称 |
| `OSS_ACCESS_KEY_ID` | 生产 | - | 阿里云AccessKey ID |
| `OSS_ACCESS_KEY_SECRET` | 生产 | - | 阿里云AccessKey Secret |

---

### 2. 缓存服务配置

#### **本地开发环境**

```bash
# backend/.env.development
CACHE_TYPE=memory
```

#### **生产环境（阿里云Redis）**

```bash
# SAE控制台 -> 环境变量配置
CACHE_TYPE=redis
REDIS_HOST=r-***.redis.aliyuncs.com
REDIS_PORT=6379
REDIS_PASSWORD=***
REDIS_DB=0
```

#### **配置说明**

| 变量名 | 必需 | 默认值 | 说明 |
|--------|------|--------|------|
| `CACHE_TYPE` | ✅ | `memory` | 缓存类型：`memory` 或 `redis` |
| `REDIS_HOST` | Redis | - | Redis主机地址 |
| `REDIS_PORT` | Redis | `6379` | Redis端口 |
| `REDIS_PASSWORD` | Redis | - | Redis密码 |
| `REDIS_DB` | Redis | `0` | Redis数据库编号 |

---

### 3. 数据库连接池配置

#### **本地开发环境**

```bash
# backend/.env.development
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ai_clinical_research

# 本地开发无需配置连接池
```

#### **生产环境（阿里云RDS）**

```bash
# SAE控制台 -> 环境变量配置
DATABASE_URL=postgresql://user:password@rm-xxx.aliyuncs.com:5432/prod_db
DB_MAX_CONNECTIONS=400        # RDS最大连接数
MAX_INSTANCES=20              # SAE最大实例数
```

#### **配置说明**

| 变量名 | 必需 | 默认值 | 说明 |
|--------|------|--------|------|
| `DATABASE_URL` | ✅ | - | PostgreSQL连接字符串 |
| `DB_MAX_CONNECTIONS` | 生产 | `400` | RDS最大连接数 |
| `MAX_INSTANCES` | 生产 | `20` | SAE最大实例数 |

**连接数计算**：
```
每实例连接数 = DB_MAX_CONNECTIONS / MAX_INSTANCES
示例：400 / 20 = 20连接/实例
```

---

### 4. 日志配置

```bash
# 通用配置
LOG_LEVEL=info                # debug | info | warn | error
NODE_ENV=development          # development | production | test
```

#### **配置说明**

| 变量名 | 必需 | 默认值 | 说明 |
|--------|------|--------|------|
| `LOG_LEVEL` | ✅ | `info` | 日志级别 |
| `NODE_ENV` | ✅ | `development` | 运行环境 |

---

### 5. 功能开关配置

```bash
# 启用的业务模块（逗号分隔）
ENABLED_MODULES=ASL,AIA,PKB,DC,SSA,ST

# 或启用全部
ENABLED_MODULES=*
```

#### **配置说明**

| 模块代码 | 模块名称 | 状态 |
|---------|---------|------|
| `ASL` | AI智能文献 | 开发中 |
| `AIA` | AI智能问答 | 已完成 |
| `PKB` | 个人知识库 | 已完成 |
| `DC` | 数据清洗 | 计划中 |
| `SSA` | 智能统计分析 | 计划中 |
| `ST` | 统计工具 | 计划中 |

---

### 6. 应用配置

```bash
# 应用基础配置
PORT=3001                     # 应用端口
BASE_URL=http://localhost:3001

# JWT配置
JWT_SECRET=your-secret-key-here
JWT_EXPIRES_IN=7d

# CORS配置
CORS_ORIGIN=http://localhost:5173
```

---

## 📋 完整环境变量模板

### **backend/.env.development（本地开发）**

```bash
# ==================== 应用配置 ====================
NODE_ENV=development
PORT=3001
BASE_URL=http://localhost:3001

# ==================== 数据库配置 ====================
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/ai_clinical_research

# ==================== 存储服务 ====================
STORAGE_TYPE=local

# ==================== 缓存服务 ====================
CACHE_TYPE=memory

# ==================== 日志配置 ====================
LOG_LEVEL=debug

# ==================== LLM配置 ====================
DEEPSEEK_API_KEY=sk-***
QWEN_API_KEY=sk-***

# ==================== RAG配置 ====================
DIFY_API_BASE_URL=http://localhost/v1
DIFY_API_KEY=app-***

# ==================== JWT配置 ====================
JWT_SECRET=dev-secret-key-change-in-production
JWT_EXPIRES_IN=7d

# ==================== CORS配置 ====================
CORS_ORIGIN=http://localhost:5173

# ==================== 功能开关 ====================
ENABLED_MODULES=*
```

### **backend/.env.production（生产环境）**

```bash
# ==================== 应用配置 ====================
NODE_ENV=production
PORT=3001

# ==================== 数据库配置 ====================
DATABASE_URL=postgresql://user:password@rm-xxx.aliyuncs.com:5432/prod_db
DB_MAX_CONNECTIONS=400
MAX_INSTANCES=20

# ==================== 存储服务 ====================
STORAGE_TYPE=oss
OSS_REGION=oss-cn-hangzhou
OSS_BUCKET=aiclinical-prod
OSS_ACCESS_KEY_ID=LTAI5t***
OSS_ACCESS_KEY_SECRET=***

# ==================== 缓存服务 ====================
CACHE_TYPE=redis
REDIS_HOST=r-***.redis.aliyuncs.com
REDIS_PORT=6379
REDIS_PASSWORD=***
REDIS_DB=0

# ==================== 日志配置 ====================
LOG_LEVEL=info

# ==================== LLM配置 ====================
DEEPSEEK_API_KEY=sk-***
QWEN_API_KEY=sk-***

# ==================== RAG配置 ====================
DIFY_API_BASE_URL=https://api.dify.ai/v1
DIFY_API_KEY=app-***

# ==================== JWT配置 ====================
JWT_SECRET=<生产环境强密钥>
JWT_EXPIRES_IN=7d

# ==================== CORS配置 ====================
CORS_ORIGIN=https://app.yourdomain.com

# ==================== 功能开关 ====================
ENABLED_MODULES=ASL,AIA,PKB,DC,SSA,ST
```

---

## 📊 配置检查清单

使用以下清单验证配置完整性：

### **基础配置（必需）**
- [ ] ✅ 数据库连接成功（`npx prisma migrate status`）
- [ ] ✅ 存储类型已配置（`STORAGE_TYPE`）
- [ ] ✅ 日志级别已配置（`LOG_LEVEL`）
- [ ] ✅ JWT密钥已配置

### **LLM配置（必需）**
- [ ] ✅ DeepSeek API Key配置且可用
- [ ] ✅ Qwen API Key配置且可用
- [ ] ✅ Dify服务运行中（`docker-compose ps`）
- [ ] ✅ Dify API Key已配置

### **平台基础设施（云原生）**
- [ ] ✅ 存储服务配置正确（本地/OSS）
- [ ] ✅ 缓存服务配置正确（Memory/Redis）
- [ ] ✅ 连接池参数已配置（生产环境）
- [ ] ✅ 功能开关已配置（ENABLED_MODULES）

### **应用运行（必需）**
- [ ] ✅ 后端服务启动成功（端口3001）
- [ ] ✅ 前端服务启动成功（端口5173）
- [ ] ✅ CORS配置正确（前端可访问后端API）
- [ ] ✅ 可正常使用平台服务（storage/logger/cache等）

---

## 🔄 配置更新记录

| 日期 | 更新内容 | 更新人 |
|------|---------|--------|
| 2025-11-09 | 初始配置文档创建 | 技术团队 |
| 2025-11-16 | 新增平台基础设施配置章节 | 技术团队 |

---

## 📚 相关文档

- [数据库连接配置](../09-架构实施/02-数据库连接配置.md)
- [部署架构设计](../05-部署文档/01-部署架构设计.md)
- [系统架构总览](../00-项目概述/技术架构总览.md)

---

**文档版本：** v1.0  
**最后更新：** 2025-11-09  
**维护者：** 技术团队