# Node.js 后端 - SAE部署操作手册

> **创建时间**：2025-12-24
> **操作对象**：Node.js 后端服务
> **部署目标**：阿里云 SAE（Serverless应用引擎）
> **预计时间**：30-40分钟

---

## 📋 前置检查

开始之前，请确认：

- [x] Docker镜像已推送到ACR：`backend-service:v1.0`
- [x] RDS PostgreSQL已部署并迁移数据
- [x] Python微服务已部署（内网地址：`http://172.17.173.66:8000`）
- [x] 环境变量配置清单已准备（见 `11-Node.js后端-SAE部署配置清单.md`）

---

## 🚀 第一步：登录SAE控制台并创建应用

### 1.1 进入SAE控制台

1. 打开浏览器，访问：https://sae.console.aliyun.com/
2. 选择地域：**华北2（北京）**
3. 选择命名空间：**cn-beijing:test-airesearch**

### 1.2 创建新应用

1. 点击【创建应用】按钮
2. 填写基本信息：

```yaml
应用名称: nodejs-backend-test
部署方式: 容器镜像
```

3. 点击【下一步】

---

## 🐳 第二步：配置容器镜像

### 2.1 选择镜像来源

1. 镜像类型：选择 **容器镜像服务（ACR）**
2. 选择实例：**个人版**
3. 选择地域：**华北2（北京）**

### 2.2 配置镜像仓库认证

⚠️ **重要**：必须先配置认证，否则无法拉取私有镜像

1. 点击【配置镜像仓库】
2. 填写认证信息：

```yaml
Registry地址: crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com
用户名: gofeng117@163.com
密码: fengzhibo117
```

3. 点击【确定】
4. 点击【验证认证】，确保认证成功

### 2.3 选择镜像

1. 选择命名空间：**ai-clinical**
2. 选择镜像：**backend-service**
3. 选择镜像版本：**v1.0**

完整镜像地址应显示为：
```
crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0
```

4. 点击【下一步】

---

## ⚙️ 第三步：配置应用参数

### 3.1 基础配置

```yaml
应用实例数: 1
CPU: 1核
内存: 2048 MB（2GB）
应用类型: Web应用
```

### 3.2 网络配置

1. **VPC配置**：
   - VPC ID：`vpc-2ze055cptkew9c38w4r06`
   - 安全组：`sg-2zedk6fi8sgmmcwdu7tu`
   - 勾选【自动分配公网SLB】：❌ 不勾选（仅内网访问）

2. **端口配置**：
   - 容器端口：`3001`
   - 协议：`TCP`

### 3.3 环境变量配置

⚠️ **关键步骤**：复制 `11-Node.js后端-SAE部署配置清单.md` 中的环境变量

**方式A：批量导入（推荐）**

1. 点击【批量导入】
2. 复制以下内容粘贴：

```env
DATABASE_URL=postgresql://airesearch:Xibahe%40fengzhibo117@pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432/ai_clinical_research?connection_limit=18&pool_timeout=10
JWT_SECRET=146c2fd064a69aa026496ee60e20483d07e951eae8323a501126469583433415
JWT_EXPIRES_IN=7d
DEEPSEEK_API_KEY=sk-7f8cc37a79fa4799860b38fc7ba2e150
DASHSCOPE_API_KEY=sk-75b4ff29a14a49e79667a331034f3298
CLOSEAI_API_KEY=sk-cu0ienbXYGGx2jc7BqP6ogtSWmP6fk918qV3RUdtGC3Ed1po
CLOSEAI_OPENAI_BASE_URL=https://api.openai-proxy.org/v1
CLOSEAI_CLAUDE_BASE_URL=https://api.openai-proxy.org/anthropic
DIFY_API_URL=http://localhost/v1
DIFY_API_KEY=dataset-mfvdiKvQ2l3NvxWm7RoYMN3c
PORT=3001
NODE_ENV=production
QUEUE_TYPE=pgboss
CACHE_TYPE=postgres
OSS_REGION=oss-cn-beijing
OSS_BUCKET=ai-clinical-research
OSS_ACCESS_KEY_ID=LTAI5tB2Dt3NdvBL3G7nYGv7
OSS_ACCESS_KEY_SECRET=1iSN9k39RkApP93QjUhC1DcPIeMG4V
OSS_ENDPOINT=oss-cn-beijing-internal.aliyuncs.com
PYTHON_SERVICE_URL=http://172.17.173.66:8000
LOG_LEVEL=info
```

3. 点击【确定】

**方式B：逐个添加**（如果批量导入不可用）

在环境变量表格中逐个添加，参考 `11-Node.js后端-SAE部署配置清单.md` 中的表格。

### 3.4 启动命令配置

1. 在【启动命令】中填写：

```bash
node dist/server.js
```

**说明**：
- ✅ 不需要 `npm start`（镜像已经编译好）
- ✅ 不需要 `prisma migrate`（数据已导入）
- ✅ 不需要 `prisma generate`（镜像构建时已生成）

### 3.5 健康检查配置

1. 勾选【启用健康检查】
2. 配置参数：

```yaml
检查方式: HTTP请求
请求路径: /health
端口: 3001
初始延迟: 30秒
检查间隔: 10秒
超时时间: 3秒
不健康阈值: 3次
健康阈值: 2次
```

**为什么初始延迟设置30秒？**
- Node.js应用启动需要10-15秒
- Prisma Client初始化需要5-10秒
- 数据库连接池建立需要5秒
- 留有余量，避免首次健康检查失败

3. 点击【下一步】

---

## 📝 第四步：确认配置并部署

### 4.1 检查配置摘要

在确认页面，仔细检查：

- [x] 镜像地址正确：`backend-service:v1.0`
- [x] 资源配置正确：1核2GB
- [x] 环境变量数量：21个（可以点击查看详情）
- [x] 健康检查路径：`/health`
- [x] 启动命令：`node dist/server.js`

### 4.2 开始部署

1. 点击【创建应用】
2. 等待部署（约3-5分钟）

**部署过程**：
```
1. 拉取镜像（2分钟）
2. 创建容器实例（1分钟）
3. 启动应用（30秒）
4. 执行健康检查（30秒）
```

---

## ✅ 第五步：部署验证

### 5.1 检查应用状态

1. 在SAE应用列表中，找到 `nodejs-backend-test`
2. 查看状态：
   - ✅ 实例状态：**运行中**（绿色）
   - ✅ 健康检查：**通过**（绿色）
   - ❌ 如果显示"异常"或"未通过"，进入第六步排查

### 5.2 查看实时日志

1. 点击应用名称，进入应用详情
2. 点击【日志】→【实时日志】
3. 查找以下关键信息：

**✅ 成功的日志示例**：
```
============================================================
🚀 AI临床研究平台 - 后端服务器启动成功！
============================================================
📍 服务地址: http://0.0.0.0:3001
🔍 健康检查: http://0.0.0.0:3001/health
📡 API入口: http://0.0.0.0:3001/api/v1
🌍 运行环境: production
============================================================

[INFO] Server listening at http://0.0.0.0:3001
[INFO] Database connected: ai_clinical_research
[INFO] Health check endpoint available: /health
```

**❌ 失败的日志示例**：
```
[ERROR] Database connection failed: connect ETIMEDOUT
[ERROR] Prisma Client initialization failed
[ERROR] Application startup failed
```

如果看到错误，进入第六步排查。

### 5.3 获取内网地址

1. 在应用详情页，找到【基本信息】
2. 复制内网地址，格式类似：`http://172.17.x.x:3001`
3. 记录到部署文档中

**示例内网地址**：
```
http://172.17.173.88:3001
```

### 5.4 测试健康检查

在SAE的【Webshell】中执行：

```bash
# 测试健康检查
curl http://172.17.173.88:3001/health

# 期望返回（HTTP 200）：
{
  "status": "ok",
  "timestamp": "2025-12-24T12:00:00.000Z",
  "database": "connected",
  "uptime": 123,
  "environment": "production"
}
```

### 5.5 测试数据库连接

```bash
# 测试用户API（如果有数据）
curl http://172.17.173.88:3001/api/v1/users \
  -H "Authorization: Bearer test-token"

# 或测试其他已知API端点
```

---

## 🔧 第六步：故障排查（可选）

### 问题1：健康检查一直失败

**症状**：应用状态显示"异常"，实例频繁重启

**排查步骤**：

1. **检查日志中的错误信息**：
   ```bash
   # 在SAE实时日志中查找关键错误
   [ERROR] ...
   ```

2. **常见原因及解决方案**：

| 错误信息 | 原因 | 解决方案 |
|---------|------|---------|
| `connect ETIMEDOUT` | 数据库连接超时 | 检查RDS白名单、VPC配置 |
| `authentication failed` | 数据库密码错误 | 检查DATABASE_URL中的密码编码 |
| `ENOENT: no such file or directory` | 启动命令错误 | 确认启动命令为 `node dist/server.js` |
| `Cannot find module 'prisma'` | Prisma Client未生成 | 重新构建镜像 |
| `Port 3001 already in use` | 端口冲突 | 检查容器端口配置 |

3. **验证数据库连接**：
   ```bash
   # 在SAE的Webshell中测试
   curl -v telnet://pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432
   ```

### 问题2：镜像拉取失败

**症状**：日志显示 `Failed to pull image`

**解决方案**：

1. 检查ACR认证配置：
   - Registry地址是否正确（VPC域名）
   - 用户名密码是否正确

2. 重新配置镜像仓库认证：
   - SAE应用详情 → 配置管理 → 镜像设置
   - 重新输入认证信息

### 问题3：环境变量未生效

**症状**：应用行为与预期不符

**排查步骤**：

1. 在SAE应用详情 → 环境变量中，确认所有变量已配置
2. 在Webshell中查看环境变量：
   ```bash
   env | grep DATABASE_URL
   env | grep JWT_SECRET
   ```

### 问题4：内存不足（OOM）

**症状**：应用频繁重启，日志中出现 `Out of Memory`

**解决方案**：

1. 在SAE应用详情 → 基本配置中，将内存调整为 **2核4GB**
2. 重新部署应用

---

## 📊 第七步：性能监控

### 7.1 查看监控指标

在SAE应用详情 → 监控中，关注以下指标：

```yaml
CPU使用率: 应 < 70%
内存使用率: 应 < 80%
实例健康状态: 应保持"健康"
请求响应时间: 应 < 1000ms
```

### 7.2 设置告警

建议配置以下告警：

```yaml
CPU使用率 > 80%: 发送告警
内存使用率 > 90%: 发送告警
实例不健康: 立即发送告警
```

---

## 📝 第八步：更新部署文档

部署成功后，更新以下文档：

### 8.1 更新部署进度总览

编辑 `00-部署进度总览.md`：

```markdown
| **Node.js后端** | ✅ 已完成 | v1.0 | SAE | 2025-12-24 | ... |
```

### 8.2 记录内网地址

在 `00-部署进度总览.md` 中添加：

```markdown
| nodejs-backend-test | ✅ 运行中 | 1核2GB | 1 | 3001 | http://172.17.173.88:3001 | 无（仅内网） |
```

---

## 🎯 后续步骤

Node.js后端部署成功后：

### 1. 部署前端Nginx（下一步）

前端Nginx需要配置Node.js后端的内网地址：

```bash
# 前端Nginx环境变量
VITE_API_BASE_URL=http://172.17.173.88:3001
```

参考文档：`07-前端Nginx-SAE部署操作手册.md`

### 2. 全链路测试

完整的请求链路：

```
用户浏览器
    ↓
前端Nginx (SAE)
    ↓
Node.js后端 (SAE)  ← http://172.17.173.88:3001
    ↓
├─→ Python微服务 (SAE)  ← http://172.17.173.66:8000
├─→ RDS PostgreSQL      ← pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432
└─→ 阿里云OSS           ← ai-clinical-research.oss-cn-beijing-internal.aliyuncs.com
```

### 3. 性能优化（可选）

如果测试环境运行稳定，可以考虑：

- **弹性伸缩**：配置自动扩缩容规则
- **资源调整**：根据监控数据调整CPU/内存
- **日志优化**：配置日志清理策略

---

## ✅ 部署完成检查清单

在完成部署后，请确认：

- [ ] SAE应用状态为"运行中"
- [ ] 健康检查显示"通过"
- [ ] 实时日志无ERROR级别错误
- [ ] 健康检查接口返回200
- [ ] 内网地址已记录
- [ ] 部署文档已更新
- [ ] Python微服务可以正常调用
- [ ] 数据库连接正常
- [ ] OSS文件上传/下载正常

---

## 📞 支持与帮助

### 常见问题

1. **Q: 如何重启应用？**
   - A: SAE应用详情 → 基本信息 → 点击【重启】

2. **Q: 如何查看完整日志？**
   - A: SAE应用详情 → 日志 → 历史日志（支持时间范围查询）

3. **Q: 如何回滚到之前的版本？**
   - A: SAE应用详情 → 版本管理 → 选择历史版本 → 回滚

4. **Q: 如何扩容实例？**
   - A: SAE应用详情 → 基本配置 → 修改实例数/规格 → 确认变更

### 联系方式

- **技术支持**：开发团队
- **阿里云工单**：https://workorder.console.aliyun.com/

---

**文档创建时间**：2025-12-24  
**最后更新**：2025-12-24  
**维护人员**：运维团队

---

🎉 **祝部署顺利！如有问题，请参考故障排查章节或联系技术支持。**