docs: complete documentation system (250+ files)
- System architecture and design documentation - Business module docs (ASL/AIA/PKB/RVW/DC/SSA/ST) - ASL module complete design (quality assurance, tech selection) - Platform layer and common capabilities docs - Development standards and API specifications - Deployment and operations guides - Project management and milestone tracking - Architecture implementation reports - Documentation templates and guides
This commit is contained in:
478
docs/07-运维文档/01-环境配置指南.md
Normal file
478
docs/07-运维文档/01-环境配置指南.md
Normal file
@@ -0,0 +1,478 @@
|
||||
# 环境配置指南
|
||||
|
||||
> **文档版本：** 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
|
||||
|
||||
---
|
||||
|
||||
## 📊 配置检查清单
|
||||
|
||||
使用以下清单验证配置完整性：
|
||||
|
||||
- [ ] ✅ 数据库连接成功（`npx prisma migrate status`）
|
||||
- [ ] ✅ DeepSeek API Key配置且可用
|
||||
- [ ] ✅ Qwen API Key配置且可用
|
||||
- [ ] ✅ Dify服务运行中（`docker-compose ps`）
|
||||
- [ ] ✅ Dify API Key已配置
|
||||
- [ ] ✅ JWT密钥已配置
|
||||
- [ ] ✅ 后端服务启动成功（端口3001）
|
||||
- [ ] ✅ 前端服务启动成功（端口5173）
|
||||
- [ ] ✅ CORS配置正确（前端可访问后端API）
|
||||
|
||||
---
|
||||
|
||||
## 🔄 配置更新记录
|
||||
|
||||
| 日期 | 更新内容 | 更新人 |
|
||||
|------|---------|--------|
|
||||
| 2025-11-09 | 初始配置文档创建 | 技术团队 |
|
||||
| - | 待记录 | - |
|
||||
|
||||
---
|
||||
|
||||
## 📚 相关文档
|
||||
|
||||
- [数据库连接配置](../09-架构实施/02-数据库连接配置.md)
|
||||
- [部署架构设计](../05-部署文档/01-部署架构设计.md)
|
||||
- [系统架构总览](../00-项目概述/技术架构总览.md)
|
||||
|
||||
---
|
||||
|
||||
**文档版本：** v1.0
|
||||
**最后更新：** 2025-11-09
|
||||
**维护者：** 技术团队
|
||||
|
||||
Reference in New Issue
Block a user