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
517 lines
11 KiB
Markdown
517 lines
11 KiB
Markdown
# 🎉 前端Nginx - 部署成功总结
|
||
|
||
> **部署完成时间**：2025-12-25 19:55
|
||
> **镜像版本**：v1.0
|
||
> **内网地址**：`http://172.17.173.72:80`
|
||
> **部署状态**：✅ 运行中
|
||
> **健康检查**：✅ 通过（HTTP 200）
|
||
|
||
---
|
||
|
||
## 📊 一、部署信息概览
|
||
|
||
### 应用配置
|
||
```yaml
|
||
应用名称: frontend-nginx-service
|
||
命名空间: cn-beijing:test-airesearch
|
||
地域: 华北2（北京）
|
||
部署方式: 容器镜像
|
||
```
|
||
|
||
### 实例规格
|
||
```yaml
|
||
CPU: 0.5核
|
||
内存: 1GB
|
||
实例数: 1个
|
||
规格选择理由:
|
||
- 前端只提供静态资源和代理转发
|
||
- 资源消耗极低
|
||
- 0.5核完全足够
|
||
- 对比：后端需要1核2GB，Python需要1核2GB
|
||
```
|
||
|
||
### 镜像信息
|
||
```yaml
|
||
镜像仓库: ai-clinical_frontend-nginx
|
||
镜像版本: v1.0
|
||
镜像大小: 91.9 MB
|
||
镜像地址: crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v1.0
|
||
构建时间: 2025-12-23
|
||
基础镜像: nginx:alpine
|
||
```
|
||
|
||
### 网络配置
|
||
```yaml
|
||
内网地址: http://172.17.173.72:80
|
||
VPC: vpc-2ze055cptkew9c38w4r06
|
||
安全组: sg-2zedk6fi8sgmmcwdu7tu
|
||
公网访问: 无（仅内网）
|
||
```
|
||
|
||
---
|
||
|
||
## 🚀 二、部署过程
|
||
|
||
### 部署时间线
|
||
|
||
| 时间 | 操作 | 结果 |
|
||
|------|------|------|
|
||
| 11:50 | 创建SAE应用 | ✅ |
|
||
| 11:52 | 配置容器镜像和实例规格 | ✅ |
|
||
| 11:53 | 配置环境变量（后端地址） | ✅ |
|
||
| 11:54 | 配置健康检查 | ✅ |
|
||
| 11:54 | 部署应用 | ✅ |
|
||
| 11:55 | 容器启动成功 | ✅ |
|
||
| 11:55 | 健康检查通过 | ✅ |
|
||
| 12:00 | 完整链路测试通过 | ✅ |
|
||
|
||
**总耗时**：约10分钟（一次成功，零问题）
|
||
|
||
---
|
||
|
||
## ✅ 三、部署验证
|
||
|
||
### 1. 启动日志验证
|
||
|
||
```bash
|
||
============================================
|
||
Starting Frontend Nginx Service
|
||
Backend Service: 172.17.173.71:3001
|
||
Container Timezone: Asia/Shanghai
|
||
Current Time: Thu Dec 25 11:54:56 CST 2025
|
||
============================================
|
||
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
|
||
nginx: configuration file /etc/nginx/nginx.conf test is successful
|
||
```
|
||
|
||
**验证结果**：✅ 所有配置正确，启动成功
|
||
|
||
### 2. 静态资源测试
|
||
|
||
**测试命令**：
|
||
```bash
|
||
curl -I http://172.17.173.72/
|
||
```
|
||
|
||
**测试结果**：
|
||
```http
|
||
HTTP/1.1 200 OK
|
||
Server: nginx
|
||
Content-Type: text/html; charset=utf-8
|
||
Content-Length: 458
|
||
Cache-Control: no-cache, no-store, must-revalidate
|
||
```
|
||
|
||
**验证结果**：✅ 静态资源正常提供
|
||
|
||
### 3. React应用验证
|
||
|
||
**测试命令**：
|
||
```bash
|
||
curl http://172.17.173.72/ | head -20
|
||
```
|
||
|
||
**测试结果**：
|
||
```html
|
||
<!doctype html>
|
||
<html lang="en">
|
||
<head>
|
||
<meta charset="UTF-8" />
|
||
<title>frontend-v2</title>
|
||
<script type="module" crossorigin src="/assets/index-DAkaorvh.js"></script>
|
||
<link rel="stylesheet" crossorigin href="/assets/index-BLOlkMiR.css">
|
||
</head>
|
||
<body>
|
||
<div id="root"></div>
|
||
</body>
|
||
</html>
|
||
```
|
||
|
||
**验证结果**：✅ React应用HTML正常，Vite构建产物完整
|
||
|
||
### 4. 前端→后端代理测试（关键！）
|
||
|
||
**测试命令**：
|
||
```bash
|
||
curl http://172.17.173.72/health
|
||
```
|
||
|
||
**测试结果**：
|
||
```
|
||
healthy
|
||
```
|
||
|
||
**验证结果**：✅ 前端到后端的代理完全正常工作！
|
||
|
||
### 5. 健康检查日志
|
||
|
||
```bash
|
||
127.0.0.1 - - [25/Dec/2025:11:55:01 +0800] "GET / HTTP/1.1" 200 304
|
||
127.0.0.1 - - [25/Dec/2025:11:55:06 +0800] "GET / HTTP/1.1" 200 304
|
||
127.0.0.1 - - [25/Dec/2025:11:55:11 +0800] "GET / HTTP/1.1" 200 304
|
||
```
|
||
|
||
**验证结果**：✅ SAE健康检查正常，每5秒检查一次
|
||
|
||
---
|
||
|
||
## 🎯 四、关键配置
|
||
|
||
### 环境变量配置
|
||
|
||
```bash
|
||
# 后端服务IP（必需）
|
||
BACKEND_SERVICE_HOST=172.17.173.71
|
||
|
||
# 后端服务端口（可选，默认3001）
|
||
BACKEND_SERVICE_PORT=3001
|
||
```
|
||
|
||
**说明**：
|
||
- 这两个环境变量在容器启动时通过 `envsubst` 注入到Nginx配置
|
||
- 不需要重新构建镜像，只需配置环境变量
|
||
- 符合云原生12-Factor App原则
|
||
|
||
### 健康检查配置
|
||
|
||
```yaml
|
||
Liveness存活检查:
|
||
方式: HTTP GET
|
||
路径: /
|
||
端口: 80
|
||
初始延迟: 10秒
|
||
检查间隔: 10秒
|
||
超时时间: 3秒
|
||
失败阈值: 3次
|
||
|
||
Readiness就绪检查:
|
||
方式: HTTP GET
|
||
路径: /
|
||
端口: 80
|
||
初始延迟: 5秒
|
||
检查间隔: 5秒
|
||
超时时间: 3秒
|
||
失败阈值: 2次
|
||
```
|
||
|
||
### Nginx代理规则
|
||
|
||
```nginx
|
||
# 后端服务上游配置
|
||
upstream backend {
|
||
server 172.17.173.71:3001 fail_timeout=30s max_fails=3;
|
||
keepalive 32;
|
||
}
|
||
|
||
# API代理规则
|
||
location /api/ {
|
||
proxy_pass http://backend;
|
||
}
|
||
|
||
location /health {
|
||
proxy_pass http://backend;
|
||
}
|
||
|
||
location /test/ {
|
||
proxy_pass http://backend;
|
||
}
|
||
|
||
# SPA fallback
|
||
location / {
|
||
try_files $uri $uri/ /index.html;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 五、部署对比
|
||
|
||
### 与Node.js后端部署对比
|
||
|
||
| 对比项 | Node.js后端 | 前端Nginx |
|
||
|--------|------------|-----------|
|
||
| **复杂度** | ⭐⭐⭐⭐ | ⭐ |
|
||
| **部署时间** | 约2小时（遇到4个问题） | 约10分钟（一次成功） |
|
||
| **实例规格** | 1核2GB | 0.5核1GB |
|
||
| **环境变量数** | 15+ | 2 |
|
||
| **启动时间** | 约30秒 | 约5秒 |
|
||
| **遇到的问题** | 4个（bash/config/pino/require） | 0个 |
|
||
| **镜像大小** | 838MB | 91.9MB |
|
||
| **健康检查路径** | `/health` | `/` |
|
||
|
||
**结论**：前端Nginx部署非常简单，一次成功，零问题！
|
||
|
||
---
|
||
|
||
## 🏗️ 六、完整架构
|
||
|
||
### 当前部署架构
|
||
|
||
```
|
||
用户请求（未来）
|
||
↓
|
||
[公网SLB] ← 待配置
|
||
↓
|
||
[前端Nginx] http://172.17.173.72:80 ✅ 已部署
|
||
├── 静态资源：/, /assets/*, /vite.svg
|
||
└── API代理：/api/*, /health, /test/*
|
||
↓
|
||
[Node.js后端] http://172.17.173.71:3001 ✅ 已部署
|
||
├── 连接数据库
|
||
├── 调用Python微服务
|
||
└── 业务逻辑处理
|
||
↓ ↓
|
||
[PostgreSQL RDS] [Python微服务]
|
||
✅ 已部署 http://172.17.173.66:8000
|
||
✅ 已部署
|
||
```
|
||
|
||
### 服务清单
|
||
|
||
| 服务 | 内网地址 | 规格 | 状态 | 部署时间 |
|
||
|------|---------|------|------|---------|
|
||
| 前端Nginx | http://172.17.173.72:80 | 0.5核1GB | ✅ 运行中 | 2025-12-25 |
|
||
| Node.js后端 | http://172.17.173.71:3001 | 1核2GB | ✅ 运行中 | 2025-12-25 |
|
||
| Python微服务 | http://172.17.173.66:8000 | 1核2GB | ✅ 运行中 | 2025-12-24 |
|
||
| PostgreSQL | pgm-xxx:5432 | 2核4GB | ✅ 运行中 | 2025-12-24 |
|
||
|
||
---
|
||
|
||
## 🎯 七、下一步工作
|
||
|
||
### 高优先级 🔴
|
||
|
||
- [ ] **配置公网SLB**：绑定前端服务，提供公网访问入口
|
||
- [ ] **配置域名**：申请域名并绑定到SLB
|
||
- [ ] **SSL证书**：配置HTTPS（阿里云免费SSL或Let's Encrypt）
|
||
- [ ] **前端实例扩容**：从1个扩容到2个，实现高可用
|
||
|
||
### 中优先级 🟡
|
||
|
||
- [ ] **监控告警**：配置SAE应用监控和告警规则
|
||
- [ ] **日志分析**：配置日志服务SLS，集中管理日志
|
||
- [ ] **CDN加速**：配置阿里云CDN，加速静态资源访问
|
||
- [ ] **安全加固**：配置WAF防火墙，防护常见攻击
|
||
|
||
### 低优先级 🟢
|
||
|
||
- [ ] **性能优化**：启用HTTP/2，优化Nginx配置
|
||
- [ ] **压力测试**：进行并发压力测试
|
||
- [ ] **备份策略**：配置自动备份和恢复流程
|
||
|
||
---
|
||
|
||
## 📈 八、资源使用情况
|
||
|
||
### 实例资源
|
||
|
||
```yaml
|
||
当前配置:
|
||
CPU: 0.5核
|
||
内存: 1GB
|
||
实例数: 1个
|
||
|
||
实际使用（预估）:
|
||
CPU使用率: <10%
|
||
内存使用率: <30%
|
||
网络带宽: <10Mbps
|
||
```
|
||
|
||
### 成本估算
|
||
|
||
```yaml
|
||
SAE成本（单实例）:
|
||
0.5核1GB: 约¥30-50/月
|
||
|
||
扩容到2实例后:
|
||
总成本: 约¥60-100/月
|
||
|
||
建议:
|
||
测试阶段使用1个实例
|
||
生产环境使用2个实例（高可用）
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 九、故障排查指南
|
||
|
||
### 常见问题
|
||
|
||
#### 问题1：容器启动失败
|
||
|
||
**症状**：容器反复重启
|
||
|
||
**可能原因**：
|
||
- 环境变量 `BACKEND_SERVICE_HOST` 未配置
|
||
|
||
**解决方法**：
|
||
```bash
|
||
# 在SAE控制台检查环境变量配置
|
||
# 确保 BACKEND_SERVICE_HOST 和 BACKEND_SERVICE_PORT 已正确配置
|
||
```
|
||
|
||
#### 问题2：健康检查失败
|
||
|
||
**症状**：实例状态显示"不健康"
|
||
|
||
**可能原因**：
|
||
- Nginx未正常启动
|
||
- 健康检查路径错误
|
||
|
||
**解决方法**：
|
||
```bash
|
||
# 查看容器日志
|
||
# 检查是否有 "nginx: configuration file test is successful"
|
||
```
|
||
|
||
#### 问题3：前端无法代理到后端
|
||
|
||
**症状**：访问 `/health` 返回404或502
|
||
|
||
**可能原因**：
|
||
- 后端地址配置错误
|
||
- 网络不通（安全组规则）
|
||
|
||
**解决方法**：
|
||
```bash
|
||
# 1. 检查启动日志中的 Backend Service 地址
|
||
# 2. 测试后端是否可访问
|
||
curl http://172.17.173.71:3001/health
|
||
|
||
# 3. 检查安全组规则是否允许内网互通
|
||
```
|
||
|
||
---
|
||
|
||
## 🎓 十、关键经验总结
|
||
|
||
### 成功因素
|
||
|
||
1. **运行时配置**：后端地址通过环境变量注入，不写死在镜像中
|
||
2. **简单架构**：Nginx极其稳定，配置简单
|
||
3. **充分准备**：提前准备好所有配置信息
|
||
4. **参考经验**：借鉴Node.js后端部署经验
|
||
|
||
### 与Node.js对比的优势
|
||
|
||
1. **零问题部署**：没有遇到任何问题，一次成功
|
||
2. **资源节省**：只需要0.5核1GB
|
||
3. **启动快速**：5秒即可启动
|
||
4. **配置简单**：只需2个环境变量
|
||
|
||
### 云原生设计的体现
|
||
|
||
1. **配置外部化**：通过环境变量注入配置
|
||
2. **无状态设计**：可以水平扩展
|
||
3. **健康检查**：支持Liveness和Readiness探针
|
||
4. **日志标准化**：输出到stdout/stderr
|
||
|
||
---
|
||
|
||
## 🌐 十一、内网地址汇总（重要！）
|
||
|
||
### 所有服务内网地址
|
||
|
||
```bash
|
||
# 前端Nginx（入口）
|
||
http://172.17.173.72:80
|
||
|
||
# Node.js后端（API）
|
||
http://172.17.173.71:3001
|
||
|
||
# Python微服务（文档处理）
|
||
http://172.17.173.66:8000
|
||
|
||
# PostgreSQL数据库
|
||
pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432
|
||
```
|
||
|
||
**配置公网访问时需要用到这些地址！**
|
||
|
||
---
|
||
|
||
## 📚 十二、相关文档索引
|
||
|
||
### 前端部署文档
|
||
- [07-前端Nginx-SAE部署操作手册.md](./07-前端Nginx-SAE部署操作手册.md) - 完整部署步骤
|
||
- [06-前端Nginx-SAE容器部署指南.md](./06-前端Nginx-SAE容器部署指南.md) - 技术架构详解
|
||
|
||
### 后端部署文档
|
||
- [12-Node.js后端-SAE部署操作手册.md](./12-Node.js后端-SAE部署操作手册.md)
|
||
- [15-Node.js后端-部署成功总结.md](./15-Node.js后端-部署成功总结.md)
|
||
|
||
### 总览文档
|
||
- [00-部署进度总览.md](./00-部署进度总览.md) - 部署状态总览
|
||
|
||
---
|
||
|
||
## 🎉 最终结论
|
||
|
||
**AI临床研究平台核心服务已全部部署成功！**
|
||
|
||
✅ PostgreSQL数据库（2025-12-24）
|
||
✅ Python微服务（2025-12-24）
|
||
✅ Node.js后端（2025-12-25）
|
||
✅ 前端Nginx（2025-12-25）
|
||
|
||
**完整链路测试通过**：
|
||
- 前端静态资源 ✅
|
||
- 前端→后端代理 ✅
|
||
- 后端→数据库 ✅
|
||
- 后端→Python ✅
|
||
|
||
**系统状态**：全部运行正常，可以进行功能测试和业务验证！🎊
|
||
|
||
---
|
||
|
||
> **文档版本**：v1.0
|
||
> **创建时间**：2025-12-25 20:00
|
||
> **维护者**：开发团队
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|