Files

HaHafeng 6124c7abc6 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

2026-02-27 14:35:25 +08:00

11 KiB

Raw Permalink Blame History

🎉 前端Nginx - 部署成功总结

部署完成时间：2025-12-25 19:55
镜像版本：v1.0
内网地址：http://172.17.173.72:80
部署状态：✅ 运行中
健康检查：✅ 通过（HTTP 200）

📊 一、部署信息概览

应用配置

应用名称: frontend-nginx-service
命名空间: cn-beijing:test-airesearch
地域: 华北2（北京）
部署方式: 容器镜像

实例规格

CPU: 0.5核
内存: 1GB
实例数: 1个
规格选择理由:
  - 前端只提供静态资源和代理转发
  - 资源消耗极低
  - 0.5核完全足够
  - 对比：后端需要1核2GB，Python需要1核2GB

镜像信息

镜像仓库: 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

网络配置

内网地址: 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. 启动日志验证

============================================
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. 静态资源测试

测试命令：

curl -I http://172.17.173.72/

测试结果：

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应用验证

测试命令：

curl http://172.17.173.72/ | head -20

测试结果：

<!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. 前端→后端代理测试（关键！）

测试命令：

curl http://172.17.173.72/health

测试结果：

healthy

验证结果：✅ 前端到后端的代理完全正常工作！

5. 健康检查日志

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秒检查一次

🎯 四、关键配置

环境变量配置

# 后端服务IP（必需）
BACKEND_SERVICE_HOST=172.17.173.71

# 后端服务端口（可选，默认3001）
BACKEND_SERVICE_PORT=3001

说明：

这两个环境变量在容器启动时通过 envsubst 注入到Nginx配置
不需要重新构建镜像，只需配置环境变量
符合云原生12-Factor App原则

健康检查配置

Liveness存活检查:
  方式: HTTP GET
  路径: /
  端口: 80
  初始延迟: 10秒
  检查间隔: 10秒
  超时时间: 3秒
  失败阈值: 3次
  
Readiness就绪检查:
  方式: HTTP GET
  路径: /
  端口: 80
  初始延迟: 5秒
  检查间隔: 5秒
  超时时间: 3秒
  失败阈值: 2次

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配置
压力测试：进行并发压力测试
备份策略：配置自动备份和恢复流程

📈 八、资源使用情况

实例资源

当前配置:
  CPU: 0.5核
  内存: 1GB
  实例数: 1个

实际使用（预估）:
  CPU使用率: <10%
  内存使用率: <30%
  网络带宽: <10Mbps

成本估算

SAE成本（单实例）:
  0.5核1GB: 约¥30-50/月
  
扩容到2实例后:
  总成本: 约¥60-100/月
  
建议:
  测试阶段使用1个实例
  生产环境使用2个实例（高可用）

🔧 九、故障排查指南

常见问题

问题1：容器启动失败

症状：容器反复重启

可能原因：

环境变量 BACKEND_SERVICE_HOST 未配置

解决方法：

# 在SAE控制台检查环境变量配置
# 确保 BACKEND_SERVICE_HOST 和 BACKEND_SERVICE_PORT 已正确配置

问题2：健康检查失败

症状：实例状态显示"不健康"

可能原因：

Nginx未正常启动
健康检查路径错误

解决方法：

# 查看容器日志
# 检查是否有 "nginx: configuration file test is successful"

问题3：前端无法代理到后端

症状：访问 /health 返回404或502

可能原因：

后端地址配置错误
网络不通（安全组规则）

解决方法：

# 1. 检查启动日志中的 Backend Service 地址
# 2. 测试后端是否可访问
curl http://172.17.173.71:3001/health

# 3. 检查安全组规则是否允许内网互通

🎓 十、关键经验总结

成功因素

运行时配置：后端地址通过环境变量注入，不写死在镜像中
简单架构：Nginx极其稳定，配置简单
充分准备：提前准备好所有配置信息
参考经验：借鉴Node.js后端部署经验

与Node.js对比的优势

零问题部署：没有遇到任何问题，一次成功
资源节省：只需要0.5核1GB
启动快速：5秒即可启动
配置简单：只需2个环境变量

云原生设计的体现

配置外部化：通过环境变量注入配置
无状态设计：可以水平扩展
健康检查：支持Liveness和Readiness探针
日志标准化：输出到stdout/stderr

🌐 十一、内网地址汇总（重要！）

所有服务内网地址

# 前端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 - 完整部署步骤
06-前端Nginx-SAE容器部署指南.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
维护者：开发团队

11 KiB Raw Permalink Blame History Unescape Escape

🎉 前端Nginx - 部署成功总结

📊 一、部署信息概览

应用配置

实例规格

镜像信息

网络配置

🚀 二、部署过程

部署时间线

✅ 三、部署验证

1. 启动日志验证

2. 静态资源测试

3. React应用验证

4. 前端→后端代理测试（关键！）

5. 健康检查日志

🎯 四、关键配置

环境变量配置

健康检查配置

Nginx代理规则

📊 五、部署对比

与Node.js后端部署对比

🏗️ 六、完整架构

当前部署架构

服务清单

🎯 七、下一步工作

高优先级 🔴

中优先级 🟡

低优先级 🟢

📈 八、资源使用情况

实例资源

成本估算

🔧 九、故障排查指南

常见问题

问题1：容器启动失败

问题2：健康检查失败

问题3：前端无法代理到后端

🎓 十、关键经验总结

成功因素

与Node.js对比的优势

云原生设计的体现

🌐 十一、内网地址汇总（重要！）

所有服务内网地址

📚 十二、相关文档索引

前端部署文档

后端部署文档

总览文档

🎉 最终结论

11 KiB

Raw Permalink Blame History