feat(platform): Complete Postgres-Only architecture refactoring (Phase 1-7)
Major Changes: - Implement Platform-Only architecture pattern (unified task management) - Add PostgresCacheAdapter for unified caching (platform_schema.app_cache) - Add PgBossQueue for job queue management (platform_schema.job) - Implement CheckpointService using job.data (generic for all modules) - Add intelligent threshold-based dual-mode processing (THRESHOLD=50) - Add task splitting mechanism (auto chunk size recommendation) - Refactor ASL screening service with smart mode selection - Refactor DC extraction service with smart mode selection - Register workers for ASL and DC modules Technical Highlights: - All task management data stored in platform_schema.job.data (JSONB) - Business tables remain clean (no task management fields) - CheckpointService is generic (shared by all modules) - Zero code duplication (DRY principle) - Follows 3-layer architecture principle - Zero additional cost (no Redis needed, save 8400 CNY/year) Code Statistics: - New code: ~1750 lines - Modified code: ~500 lines - Test code: ~1800 lines - Documentation: ~3000 lines Testing: - Unit tests: 8/8 passed - Integration tests: 2/2 passed - Architecture validation: passed - Linter errors: 0 Files: - Platform layer: PostgresCacheAdapter, PgBossQueue, CheckpointService, utils - ASL module: screeningService, screeningWorker - DC module: ExtractionController, extractionWorker - Tests: 11 test files - Docs: Updated 4 key documents Status: Phase 1-7 completed, Phase 8-9 pending
This commit is contained in:
371
docs/07-运维文档/03-SAE环境变量配置指南.md
Normal file
371
docs/07-运维文档/03-SAE环境变量配置指南.md
Normal file
@@ -0,0 +1,371 @@
|
||||
# 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)
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user