docs(platform): Add database documentation system and restructure deployment docs
Completed: - Add 6 core database documents (docs/01-平台基础层/07-数据库/) Architecture overview, migration history, environment comparison, tech debt tracking, seed data management, PostgreSQL extensions - Restructure deployment docs: archive 20 legacy files to _archive-2025/ - Create unified daily operations manual (01-日常更新操作手册.md) - Add pending deployment change tracker (03-待部署变更清单.md) - Update database development standard to v3.0 (three iron rules) - Fix Prisma schema type drift: align @db.* annotations with actual DB IIT: UUID/Timestamptz(6), SSA: Timestamp(6)/VarChar(20/50/100) - Add migration: 20260227_align_schema_with_db_types (idempotent ALTER) - Add Cursor Rule for auto-reminding deployment change documentation - Update system status guide v6.4 with deployment and DB doc references - Add architecture consultation docs (Prisma guide, SAE deployment guide) Technical details: - Manual migration due to shadow DB limitation (TD-001 in tech debt) - Deployment docs reduced from 20+ scattered files to 3 core documents - Cursor Rule triggers on schema.prisma, package.json, Dockerfile changes Made-with: Cursor
This commit is contained in:
539
docs/05-部署文档/_archive-2025首次部署/12-Node.js后端-SAE部署操作手册.md
Normal file
539
docs/05-部署文档/_archive-2025首次部署/12-Node.js后端-SAE部署操作手册.md
Normal file
@@ -0,0 +1,539 @@
|
||||
# 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
|
||||
**维护人员**：运维团队
|
||||
|
||||
---
|
||||
|
||||
🎉 **祝部署顺利！如有问题，请参考故障排查章节或联系技术支持。**
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user