AIclinicalresearch/docs/07-运维文档/03-SAE环境变量配置指南.md

# SAE环境变量配置指南

> **文档版本：** v1.0  
> **创建日期：** 2025-12-11  
> **适用场景：** 阿里云SAE部署环境变量配置  
> **使用方法：** 在SAE控制台逐行配置

---

## 📋 配置说明

在阿里云SAE控制台配置环境变量时，按照以下顺序逐行添加：

### 操作步骤

1. 登录阿里云控制台
2. 进入 Serverless应用引擎SAE
3. 选择应用 → 配置管理 → 环境变量
4. 点击「添加环境变量」
5. 逐行复制以下内容（替换所有"你的XXX"）

---

## 🔑 必填环境变量

### 基础配置

```bash
NODE_ENV=development
PORT=3001
SERVICE_NAME=aiclinical-backend-dev
LOG_LEVEL=debug
```

### 数据库配置

```bash
# 格式：postgresql://用户名:密码@地址:端口/数据库名
# 示例：postgresql://aiclinical:MyPass123@rm-bp1xxxx.mysql.rds.aliyuncs.com:5432/aiclinical_dev
DATABASE_URL=postgresql://aiclinical:你的密码@你的RDS内网地址:5432/aiclinical_dev

# Serverless连接池优化
DB_MAX_CONNECTIONS=400
MAX_INSTANCES=10
```

**获取RDS地址：**
1. RDS控制台 → 实例列表 → 点击实例ID
2. 基本信息 → 内网地址（复制）
3. 示例：`rm-bp1abcd1234.mysql.rds.aliyuncs.com`

### OSS存储配置

```bash
STORAGE_TYPE=oss
OSS_REGION=oss-cn-hangzhou
OSS_BUCKET=aiclinical-dev
OSS_ACCESS_KEY_ID=你的AccessKeyId
OSS_ACCESS_KEY_SECRET=你的AccessKeySecret
```

**获取OSS密钥：**
1. 访问控制RAM → 用户 → `aiclinical-oss`
2. 如果忘记密钥，需要重新创建AccessKey
3. **重要：** 密钥只显示一次，立即保存！

### LLM API配置

```bash
# DeepSeek（推荐）
DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com

# 通义千问（阿里云）
DASHSCOPE_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# CloseAI代理（可选）
CLOSEAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
CLOSEAI_OPENAI_BASE_URL=https://api.openai-proxy.org/v1
CLOSEAI_CLAUDE_BASE_URL=https://api.openai-proxy.org/anthropic
```

**至少配置一个LLM API Key！**

### 安全配置

```bash
# JWT密钥（必须修改！）
# 生成工具：https://www.random.org/strings/
JWT_SECRET=请改为32位以上随机字符串abcdefg123456
JWT_EXPIRES_IN=7d

# CORS配置
CORS_ORIGIN=*
```

**⚠️ JWT_SECRET 绝对不能使用默认值！**

---

## ⚙️ 推荐配置

### 缓存配置（初期不使用Redis）

```bash
CACHE_TYPE=memory
QUEUE_TYPE=memory
```

**说明：** 初期用户量小，使用内存缓存足够

**未来需要Redis时，改为：**
```bash
CACHE_TYPE=redis
REDIS_HOST=r-bp1xxxx.redis.rds.aliyuncs.com
REDIS_PORT=6379
REDIS_PASSWORD=你的Redis密码
REDIS_DB=0
```

### Dify配置（可选）

```bash
DIFY_API_KEY=app-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DIFY_API_URL=https://api.dify.ai/v1
```

**说明：** 如果使用Dify提供RAG服务，需要配置

### Python微服务配置

```bash
# 临时方案：先用公网地址
EXTRACTION_SERVICE_URL=http://你的临时地址:8000

# 正式方案：部署Python到SAE后使用内网地址
# EXTRACTION_SERVICE_URL=http://aiclinical-python-dev.default:8000
```

### 文件上传配置

```bash
UPLOAD_MAX_SIZE=104857600
```

**说明：** 100MB = 104857600 bytes

---

## ✅ 配置检查清单

### 第一步：复制粘贴检查

- [ ] 所有环境变量已添加到SAE
- [ ] 所有"你的XXX"已替换为真实值
- [ ] 没有遗漏任何必填项

### 第二步：格式检查

- [ ] DATABASE_URL 格式正确
  ```
  postgresql://用户名:密码@地址:端口/数据库
  ✅ 正确：postgresql://aiclinical:MyPass@rm-xxx.com:5432/db
  ❌ 错误：postgresql://aiclinical@rm-xxx.com:5432/db（缺少密码）
  ```

- [ ] 密码中没有特殊字符（`@ # $ % & 空格`）
  ```
  ✅ 推荐：MyPassword123
  ❌ 避免：My@Pass#123（包含@和#）
  ```

- [ ] JWT_SECRET 已修改（不是默认值）
- [ ] OSS_REGION 格式正确（带 `oss-` 前缀）
  ```
  ✅ 正确：oss-cn-hangzhou
  ❌ 错误：cn-hangzhou
  ```

### 第三步：密钥有效性检查

- [ ] RDS密码正确（可以用数据库客户端测试连接）
- [ ] OSS AccessKey有效（在RAM控制台确认）
- [ ] LLM API Key有效（可以用curl测试）

**测试LLM API Key：**
```bash
curl https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer sk-你的密钥"
```

---

## 📝 配置示例（脱敏版）

```bash
NODE_ENV=development
PORT=3001
SERVICE_NAME=aiclinical-backend-dev
LOG_LEVEL=debug

DATABASE_URL=postgresql://aiclinical:MySecurePass123@rm-bp1abc123.mysql.rds.aliyuncs.com:5432/aiclinical_dev
DB_MAX_CONNECTIONS=400
MAX_INSTANCES=10

STORAGE_TYPE=oss
OSS_REGION=oss-cn-hangzhou
OSS_BUCKET=aiclinical-dev
OSS_ACCESS_KEY_ID=LTAI5t12345678901234
OSS_ACCESS_KEY_SECRET=abcdefghijk1234567890123456789012

CACHE_TYPE=memory
QUEUE_TYPE=memory

DEEPSEEK_API_KEY=sk-1234567890abcdef1234567890abcdef
DEEPSEEK_BASE_URL=https://api.deepseek.com

DASHSCOPE_API_KEY=sk-abcdef1234567890abcdef1234567890

JWT_SECRET=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
JWT_EXPIRES_IN=7d
CORS_ORIGIN=*

EXTRACTION_SERVICE_URL=http://123.456.789.0:8000

UPLOAD_MAX_SIZE=104857600
```

---

## 🔐 安全最佳实践

### 密钥管理

1. **不要将密钥提交到Git**
   - ❌ 不要创建 `.env.production` 文件
   - ❌ 不要在代码中硬编码密钥
   - ✅ 只在SAE控制台配置

2. **定期更换密钥**
   - 每3-6个月更换一次
   - 发现泄露立即更换

3. **使用密码管理器**
   - 推荐：1Password、LastPass、Bitwarden
   - 保存所有密钥和配置信息

### 环境隔离

```
开发环境：
  - Bucket: aiclinical-dev
  - Database: aiclinical_dev
  - JWT_SECRET: 独立的密钥

生产环境：
  - Bucket: aiclinical-prod
  - Database: aiclinical_prod
  - JWT_SECRET: 不同的密钥
```

**永远不要在生产环境使用开发环境的密钥！**

---

## 🆘 常见问题

### Q1: 忘记了RDS密码怎么办？

**解决方法：**
1. RDS控制台 → 账号管理
2. 找到用户 `aiclinical`
3. 点击「重置密码」
4. 设置新密码
5. 更新SAE环境变量中的 `DATABASE_URL`

### Q2: OSS AccessKey泄露了怎么办？

**解决方法：**
1. RAM控制台 → 用户 → `aiclinical-oss`
2. 禁用或删除泄露的AccessKey
3. 创建新的AccessKey
4. 更新SAE环境变量

### Q3: 如何验证环境变量配置正确？

**解决方法：**
1. 部署应用后，查看实时日志
2. 看到以下日志表示配置正确：
   ```
   ✅ [Config] Environment validation passed
   ✅ [Database] 数据库连接成功
   📦 [Storage] 使用阿里云 OSS 存储
   ```

### Q4: DATABASE_URL中密码包含特殊字符怎么办？

**解决方法：**
如果密码包含 `@ # $ % & 空格` 等特殊字符，需要URL编码：

```
原密码：My@Pass#123
编码后：My%40Pass%23123

完整URL：
postgresql://aiclinical:My%40Pass%23123@rm-xxx.com:5432/aiclinical_dev
```

**编码对照表：**
```
@ → %40
# → %23
$ → %24
% → %25
& → %26
空格 → %20
```

**推荐：** 重新设置不包含特殊字符的密码更简单

---

## 📊 配置完成验证

### 自动验证

部署后，应用会自动验证环境变量：

```typescript
// backend/src/config/env.ts
// 会自动检查所有必填项
```

**日志输出示例：**
```
✅ [Config] Environment validation passed
[Config] Application configuration:
  - Environment: development
  - Port: 3001
  - Storage: oss
  - Cache: memory
  - Queue: memory
  - Log Level: debug
```

### 手动验证

```bash
# 访问健康检查接口
curl http://你的SAE地址:3001/health

# 预期返回
{
  "status": "ok",
  "database": "connected",
  "storage": "oss",
  "cache": "memory",
  "timestamp": "2025-12-11T10:30:00.000Z"
}
```

---

**文档版本：** v1.0  
**最后更新：** 2025-12-11  
**维护者：** 技术架构师  
**相关文档：** [SAE部署完全指南](../05-部署文档/02-SAE部署完全指南(产品经理版).md)