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

环境配置指南

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

---

📋 文档说明

本文档记录系统运行所需的全部环境变量配置，包括：

• 数据库连接信息
• LLM API密钥配置
• 第三方服务配置
• 安全相关配置

---

🗄️ 数据库配置

PostgreSQL连接信息

当前配置：

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

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

配置：

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

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

配置：

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

配置：

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

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问答

配置：

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密钥

配置：

JWT_SECRET=your-secret-key-change-in-production
JWT_EXPIRES_IN=7d

说明：

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

生成强密钥（可选）：

# Node.js生成
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# OpenSSL生成
openssl rand -hex 32

---

🌐 服务配置

后端服务

配置：

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配置

配置：

CORS_ORIGIN=http://localhost:5173

说明：

• 允许前端跨域访问
• 前端开发服务器：http://localhost:5173

---

Redis配置（可选）

配置：

REDIS_URL=redis://localhost:6379

说明：

• 用于缓存和会话管理
• 当前未强制要求

---

📁 文件上传配置

配置：

UPLOAD_MAX_SIZE=10485760
UPLOAD_DIR=./uploads

说明：

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

---

🚀 配置步骤

1. 检查环境变量文件

位置： backend/.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. 验证配置

启动后端服务：

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

验证数据库连接：

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

# 查看服务状态
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 新增）

⭐ 重要更新：为支持云原生部署，新增平台基础设施环境变量
详细文档：平台基础设施规划

---

1. 存储服务配置

本地开发环境

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

生产环境（阿里云OSS）

# 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. 缓存服务配置

本地开发环境

# backend/.env.development
CACHE_TYPE=memory

生产环境（阿里云Redis）

# 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. 数据库连接池配置

本地开发环境

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

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

生产环境（阿里云RDS）

# 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. 日志配置

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

配置说明

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

---

5. 功能开关配置

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

# 或启用全部
ENABLED_MODULES=*

配置说明

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

---

6. 应用配置

# 应用基础配置
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（本地开发）

# ==================== 应用配置 ====================
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（生产环境）

# ==================== 应用配置 ====================
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	新增平台基础设施配置章节	技术团队

---

📚 相关文档

• 数据库连接配置
• 部署架构设计
• 系统架构总览

---

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