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

SAE环境变量配置指南

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

---

📋 配置说明

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

操作步骤

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

---

🔑 必填环境变量

基础配置

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

数据库配置

# 格式：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存储配置

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

# 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！

安全配置

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

# CORS配置
CORS_ORIGIN=*

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

---

⚙️ 推荐配置

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

CACHE_TYPE=memory
QUEUE_TYPE=memory

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

未来需要Redis时，改为：

CACHE_TYPE=redis
REDIS_HOST=r-bp1xxxx.redis.rds.aliyuncs.com
REDIS_PORT=6379
REDIS_PASSWORD=你的Redis密码
REDIS_DB=0

Dify配置（可选）

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

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

Python微服务配置

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

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

文件上传配置

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：

curl https://api.deepseek.com/v1/models \
  -H "Authorization: Bearer sk-你的密钥"

---

📝 配置示例（脱敏版）

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

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

---

📊 配置完成验证

自动验证

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

// 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

手动验证

# 访问健康检查接口
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部署完全指南