AIclinicalresearch/docs/05-部署文档/12-Node.js后端-SAE部署操作手册.md

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

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

---

📋 前置检查

开始之前，请确认：

• Docker镜像已推送到ACR：backend-service:v1.0
• RDS PostgreSQL已部署并迁移数据
• Python微服务已部署（内网地址：http://172.17.173.66:8000）
• 环境变量配置清单已准备（见 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. 填写基本信息：

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

3. 点击【下一步】

---

🐳 第二步：配置容器镜像

2.1 选择镜像来源

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

2.2 配置镜像仓库认证

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

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

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

应用实例数: 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. 复制以下内容粘贴：

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. 在【启动命令】中填写：

node dist/server.js

说明：

• ✅ 不需要 npm start（镜像已经编译好）
• ✅ 不需要 prisma migrate（数据已导入）
• ✅ 不需要 prisma generate（镜像构建时已生成）

3.5 健康检查配置

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

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

为什么初始延迟设置30秒？

• Node.js应用启动需要10-15秒
• Prisma Client初始化需要5-10秒
• 数据库连接池建立需要5秒
• 留有余量，避免首次健康检查失败

3. 点击【下一步】

---

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

4.1 检查配置摘要

在确认页面，仔细检查：

• 镜像地址正确：backend-service:v1.0
• 资源配置正确：1核2GB
• 环境变量数量：21个（可以点击查看详情）
• 健康检查路径：/health
• 启动命令：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】中执行：

# 测试健康检查
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 测试数据库连接

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

# 或测试其他已知API端点

---

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

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

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

排查步骤：

1. 检查日志中的错误信息：

   # 在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. 验证数据库连接：

   # 在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中查看环境变量：

   env | grep DATABASE_URL
   env | grep JWT_SECRET
   

问题4：内存不足（OOM）

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

解决方案：

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

---

📊 第七步：性能监控

7.1 查看监控指标

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

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

7.2 设置告警

建议配置以下告警：

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

---

📝 第八步：更新部署文档

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

8.1 更新部署进度总览

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

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

8.2 记录内网地址

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

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

---

🎯 后续步骤

Node.js后端部署成功后：

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

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

# 前端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
维护人员：运维团队

---

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