# 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=请改�?2位以上随机字符串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. **定期更换密钥**
   - �?-6个月更换一�?
   - 发现泄露立即更换

3. **使用密码管理�?*
   - 推荐�?Password、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)