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

> **创建时间**�?025-12-24
> **操作对象**：Node.js 后端服务
> **部署目标**：阿里云 SAE（Serverless应用引擎�?
> **预计时间**�?0-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�?GB�?
应用类型: 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�?
```

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

3. 点击【下一步�?

---

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

### 4.1 检查配置摘�?

在确认页面，仔细检查：

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

### 4.2 开始部�?

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

**部署过程**�?
```
1. 拉取镜像�?分钟�?
2. 创建容器实例�?分钟�?
3. 启动应用�?0秒）
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�?GB**
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�?GB | 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级别错误
- [ ] 健康检查接口返�?00
- [ ] 内网地址已记�?
- [ ] 部署文档已更�?
- [ ] Python微服务可以正常调�?
- [ ] 数据库连接正�?
- [ ] OSS文件上传/下载正常

---

## 📞 支持与帮�?

### 常见问题

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

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

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

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

### 联系方式

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

---

**文档创建时间**�?025-12-24  
**最后更�?*�?025-12-24  
**维护人员**：运维团�?

---

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