HaHafeng
6124c7abc6
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
317 lines
7.5 KiB
Markdown
317 lines
7.5 KiB
Markdown
# Node.js 后端 - SAE部署配置清单
|
||
|
||
> **创建时间**：2025-12-24
|
||
> **部署环境**：测试环境（Test）
|
||
> **应用名称**：nodejs-backend-test
|
||
> **目标规格**：1核2GB
|
||
|
||
---
|
||
|
||
## 🔐 生成的强JWT密钥
|
||
|
||
**⚠️ 重要：请妥善保管此密钥，不要泄露！**
|
||
|
||
```bash
|
||
JWT_SECRET=146c2fd064a69aa026496ee60e20483d07e951eae8323a501126469583433415
|
||
```
|
||
|
||
**密钥特性**：
|
||
- ✅ 64个十六进制字符（256位强度）
|
||
- ✅ 完全随机生成
|
||
- ✅ 符合生产环境安全标准
|
||
|
||
---
|
||
|
||
## 📋 完整环境变量配置
|
||
|
||
### 方式1：逐个配置（SAE控制台）
|
||
|
||
在SAE控制台 → 应用配置 → 环境变量中，逐个添加以下配置：
|
||
|
||
| 变量名 | 变量值 | 说明 |
|
||
|--------|--------|------|
|
||
| `DATABASE_URL` | `postgresql://airesearch:Xibahe%40fengzhibo117@pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432/ai_clinical_research?connection_limit=18&pool_timeout=10` | RDS数据库连接（注意@编码为%40） |
|
||
| `JWT_SECRET` | `146c2fd064a69aa026496ee60e20483d07e951eae8323a501126469583433415` | 🔐 新生成的强密钥 |
|
||
| `JWT_EXPIRES_IN` | `7d` | JWT过期时间 |
|
||
| `DEEPSEEK_API_KEY` | `sk-7f8cc37a79fa4799860b38fc7ba2e150` | DeepSeek API密钥 |
|
||
| `DASHSCOPE_API_KEY` | `sk-75b4ff29a14a49e79667a331034f3298` | 阿里千问API密钥 |
|
||
| `CLOSEAI_API_KEY` | `sk-cu0ienbXYGGx2jc7BqP6ogtSWmP6fk918qV3RUdtGC3Ed1po` | CloseAI代理密钥 |
|
||
| `CLOSEAI_OPENAI_BASE_URL` | `https://api.openai-proxy.org/v1` | OpenAI代理地址 |
|
||
| `CLOSEAI_CLAUDE_BASE_URL` | `https://api.openai-proxy.org/anthropic` | Claude代理地址 |
|
||
| `DIFY_API_URL` | `http://localhost/v1` | Dify服务地址（未部署） |
|
||
| `DIFY_API_KEY` | `dataset-mfvdiKvQ2l3NvxWm7RoYMN3c` | Dify API密钥 |
|
||
| `PORT` | `3001` | 服务端口 |
|
||
| `NODE_ENV` | `production` | 运行环境 |
|
||
| `QUEUE_TYPE` | `pgboss` | 队列类型 |
|
||
| `CACHE_TYPE` | `postgres` | 缓存类型 |
|
||
| `OSS_REGION` | `oss-cn-beijing` | OSS区域 |
|
||
| `OSS_BUCKET` | `ai-clinical-research` | OSS Bucket名称 |
|
||
| `OSS_ACCESS_KEY_ID` | `LTAI5tB2Dt3NdvBL3G7nYGv7` | OSS访问密钥ID |
|
||
| `OSS_ACCESS_KEY_SECRET` | `1iSN9k39RkApP93QjUhC1DcPIeMG4V` | OSS访问密钥Secret |
|
||
| `OSS_ENDPOINT` | `oss-cn-beijing-internal.aliyuncs.com` | OSS内网地址 |
|
||
| `PYTHON_SERVICE_URL` | `http://172.17.173.66:8000` | Python微服务地址 |
|
||
| `LOG_LEVEL` | `info` | 日志级别 |
|
||
|
||
---
|
||
|
||
### 方式2：批量导入（推荐）
|
||
|
||
将以下内容复制，在SAE控制台使用"批量导入"功能：
|
||
|
||
```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
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 SAE应用配置参数
|
||
|
||
### 基本信息
|
||
```yaml
|
||
应用名称: nodejs-backend-test
|
||
部署方式: 容器镜像
|
||
命名空间: cn-beijing:test-airesearch
|
||
地域: 华北2（北京）
|
||
```
|
||
|
||
### 镜像配置
|
||
```yaml
|
||
镜像类型: 私有镜像
|
||
镜像地址: crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0
|
||
镜像版本: v1.0
|
||
```
|
||
|
||
### ACR镜像仓库认证
|
||
```yaml
|
||
Registry地址: crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com
|
||
用户名: gofeng117@163.com
|
||
密码: fengzhibo117
|
||
```
|
||
|
||
### 资源配置
|
||
```yaml
|
||
CPU: 1核
|
||
内存: 2GB
|
||
实例数: 1个（固定）
|
||
```
|
||
|
||
### 网络配置
|
||
```yaml
|
||
VPC ID: vpc-2ze055cptkew9c38w4r06
|
||
安全组ID: sg-2zedk6fi8sgmmcwdu7tu
|
||
```
|
||
|
||
### 端口配置
|
||
```yaml
|
||
容器端口: 3001
|
||
协议: TCP
|
||
```
|
||
|
||
### 健康检查配置
|
||
```yaml
|
||
检查类型: HTTP
|
||
检查路径: /health
|
||
检查端口: 3001
|
||
初始延迟: 30秒
|
||
检查间隔: 10秒
|
||
超时时间: 3秒
|
||
不健康阈值: 3次
|
||
健康阈值: 2次
|
||
```
|
||
|
||
### 启动命令
|
||
```bash
|
||
node dist/server.js
|
||
```
|
||
|
||
**说明**：
|
||
- ✅ 不需要执行 `prisma migrate deploy`（数据已通过pg_dump导入）
|
||
- ✅ 不需要执行 `prisma generate`（镜像构建时已生成）
|
||
- ✅ 直接启动编译后的服务即可
|
||
|
||
---
|
||
|
||
## ✅ 部署后验证清单
|
||
|
||
部署成功后，需要验证以下项目：
|
||
|
||
### 1. 应用状态检查
|
||
- [ ] SAE控制台显示应用状态为"运行中"
|
||
- [ ] 健康检查显示为"通过"
|
||
- [ ] 无重启或崩溃记录
|
||
|
||
### 2. 日志检查
|
||
查看实时日志，应该看到类似以下输出：
|
||
```
|
||
============================================================
|
||
🚀 AI临床研究平台 - 后端服务器启动成功！
|
||
============================================================
|
||
📍 服务地址: http://0.0.0.0:3001
|
||
🔍 健康检查: http://0.0.0.0:3001/health
|
||
📡 API入口: http://0.0.0.0:3001/api/v1
|
||
🌍 运行环境: production
|
||
============================================================
|
||
```
|
||
|
||
### 3. 健康检查测试
|
||
获取应用的内网地址后，执行：
|
||
```bash
|
||
curl http://172.17.x.x:3001/health
|
||
```
|
||
|
||
期望返回：
|
||
```json
|
||
{
|
||
"status": "ok",
|
||
"timestamp": "2025-12-24T12:00:00.000Z",
|
||
"database": "connected",
|
||
"uptime": 123
|
||
}
|
||
```
|
||
|
||
### 4. 数据库连接测试
|
||
检查日志中是否有数据库连接成功的消息，无报错信息。
|
||
|
||
### 5. 记录内网地址
|
||
- [ ] 记录Node.js后端的内网地址（格式：`http://172.17.x.x:3001`）
|
||
- [ ] 更新到部署文档中
|
||
|
||
---
|
||
|
||
## 🎯 后续步骤
|
||
|
||
Node.js后端部署成功后：
|
||
|
||
1. **更新前端Nginx配置**
|
||
- 将Node.js后端的内网地址配置到前端Nginx
|
||
- 环境变量：`VITE_API_BASE_URL=http://172.17.x.x:3001`
|
||
|
||
2. **部署前端Nginx**
|
||
- 使用Node.js后端的内网地址
|
||
- 完成前端应用的SAE部署
|
||
|
||
3. **全链路测试**
|
||
- 前端 → Node.js后端 → Python微服务 → RDS
|
||
- 验证完整的业务流程
|
||
|
||
---
|
||
|
||
## 📞 故障排查
|
||
|
||
### 问题1：应用无法启动
|
||
**症状**：健康检查一直失败，应用显示"异常"
|
||
|
||
**排查步骤**：
|
||
1. 查看"实时日志"，检查启动错误
|
||
2. 常见原因：
|
||
- DATABASE_URL格式错误（@未编码）
|
||
- 端口配置不匹配
|
||
- 环境变量缺失
|
||
|
||
### 问题2：数据库连接失败
|
||
**症状**：日志显示数据库连接超时
|
||
|
||
**排查步骤**：
|
||
1. 检查RDS白名单是否包含VPC网段（172.17.0.0/16）
|
||
2. 检查DATABASE_URL中的密码是否正确编码（@编码为%40）
|
||
3. 在SAE的Webshell中测试：
|
||
```bash
|
||
curl -v telnet://pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432
|
||
```
|
||
|
||
### 问题3：健康检查路径404
|
||
**症状**：健康检查显示HTTP 404错误
|
||
|
||
**解决方案**：
|
||
- 确认健康检查路径为 `/health`（不是 `/api/health`）
|
||
- 确认健康检查端口为 `3001`
|
||
|
||
---
|
||
|
||
## 🔒 安全注意事项
|
||
|
||
1. **JWT密钥保护**：
|
||
- ✅ 已生成强随机密钥
|
||
- ⚠️ 不要将密钥提交到Git
|
||
- ⚠️ 不要在日志中打印密钥
|
||
|
||
2. **数据库密码保护**：
|
||
- ✅ 使用环境变量管理
|
||
- ⚠️ 注意URL编码（@编码为%40）
|
||
|
||
3. **API密钥保护**：
|
||
- ✅ 所有LLM API密钥已配置为环境变量
|
||
- ⚠️ 定期轮换密钥
|
||
|
||
---
|
||
|
||
**文档创建时间**：2025-12-24
|
||
**维护人员**：运维团队
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|