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

9.9 KiB

Raw Blame History

AI临床研究平台 - 部署文档使用指南

文档版本：v1.0
创建日期：2025-12-25
用途：帮助您快速找到需要的部署文档

🎯 快速导航

我应该看哪个文档？

根据您的需求选择：

场景	推荐文档	说明
🚀 完整部署系统（推荐）	17-完整部署实战手册-2025版.md	基于实战经验，包含所有坑点和解决方案
📚 学习部署原理	01-快速部署SOP-零基础版.md	零基础完整教程
🔍 查询资源信息	00-部署进度总览.md	IP地址、密码、环境变量等
🐍 只部署Python服务	09-Python微服务-SAE部署操作手册.md	Python微服务部署步骤
🟢 只部署Node.js后端	12-Node.js后端-SAE部署操作手册.md	Node.js后端部署步骤
🎨 只部署前端Nginx	07-前端Nginx-SAE部署操作手册.md	前端Nginx部署步骤
🗄️ 只部署数据库	08-PostgreSQL数据库部署操作手册.md	PostgreSQL数据库部署
❌ 遇到问题排查	15-Node.js后端-部署成功总结.md	常见问题及解决方案

📁 文档结构说明

核心文档（必读）

📂 05-部署文档/
├── 📄 00-部署进度总览.md                    ⭐⭐⭐⭐⭐
│   └── 作用：资源速查、IP地址、环境变量、文档索引
│
├── 📄 17-完整部署实战手册-2025版.md        ⭐⭐⭐⭐⭐
│   └── 作用：完整部署流程、实战经验、问题解决
│
└── 📄 01-快速部署SOP-零基础版.md           ⭐⭐⭐⭐
    └── 作用：零基础教程、详细原理讲解

服务部署手册（按需查看）

📂 服务部署操作手册/
├── 📄 09-Python微服务-SAE部署操作手册.md   ⭐⭐⭐
├── 📄 12-Node.js后端-SAE部署操作手册.md    ⭐⭐⭐
├── 📄 07-前端Nginx-SAE部署操作手册.md      ⭐⭐⭐
└── 📄 08-PostgreSQL数据库部署操作手册.md   ⭐⭐⭐

技术详解文档（深入理解）

📂 技术详解/
├── 📄 04-Python微服务-SAE容器部署指南.md
├── 📄 05-Node.js后端-SAE容器部署指南.md
├── 📄 06-前端Nginx-SAE容器部署指南.md
└── 📄 10-Node.js后端-Docker镜像构建手册.md

配置清单（必备参考）

📂 配置清单/
└── 📄 11-Node.js后端-SAE部署配置清单.md   ⭐⭐⭐
    └── 作用：21个环境变量详细说明

问题修复记录（故障排查）

📂 问题修复/
├── 📄 13-Node.js后端-镜像修复记录.md
├── 📄 14-Node.js后端-pino-pretty问题修复.md
├── 📄 15-Node.js后端-部署成功总结.md       ⭐⭐⭐
└── 📄 16-前端Nginx-部署成功总结.md

🚀 不同场景的推荐阅读路径

场景1：首次完整部署（新手）

阅读顺序：

✅ 先看：17-完整部署实战手册-2025版.md（2小时）
- 了解完整流程
- 准备所需资源
- 按步骤执行
✅ 遇到问题时参考：
- 15-Node.js后端-部署成功总结.md
- 00-部署进度总览.md（查询资源信息）
✅ 想深入了解时看：
- 01-快速部署SOP-零基础版.md

预计时间：3.5 - 6小时

场景2：更新某个服务（熟练用户）

例如：更新Node.js后端代码

操作流程：

✅ 修改代码

✅ 本地构建镜像：

cd backend
npm run build
docker build -t backend-service:v1.4 .

✅ 推送到ACR：

docker tag backend-service:v1.4 \
  crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.4
docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.4

✅ 在SAE控制台：
- 进入应用 nodejs-backend-test
- 点击【部署应用】
- 选择新版本 v1.4
- 确认部署

参考文档：

12-Node.js后端-SAE部署操作手册.md（第3-4步）
00-部署进度总览.md（查ACR地址）

预计时间：15-30分钟

场景3：修改环境变量

例如：修改Python服务地址

操作流程：

✅ 登录SAE控制台
✅ 进入应用（如 nodejs-backend-test）
✅ 点击【应用配置】→【环境变量】
✅ 修改变量值
✅ 点击【重启应用】（⚠️ 不是"部署应用"！）

参考文档：

11-Node.js后端-SAE部署配置清单.md（环境变量说明）
17-完整部署实战手册-2025版.md（第9.2节：重启 vs 部署）

预计时间：5分钟

场景4：问题排查

遇到问题时的查找顺序：

✅ 先查：17-完整部署实战手册-2025版.md 第9节
- 包含实际遇到的所有问题及解决方案
- 环境变量名错误
- config目录缺失
- pino-pretty报错
- ES Module兼容性
- bash路径问题
✅ 再查：15-Node.js后端-部署成功总结.md
- 详细的问题修复历程
✅ 具体问题查：
- 13-Node.js后端-镜像修复记录.md（config问题）
- 14-Node.js后端-pino-pretty问题修复.md（日志问题）

📊 关键信息速查

我要查询什么信息？

需要查询的信息	在哪里找	章节
内网IP地址	`00-部署进度总览.md`	2.4 SAE应用
数据库连接串	`00-部署进度总览.md`	2.3 RDS
OSS AccessKey	`00-部署进度总览.md`	2.5 OSS
ACR镜像地址	`00-部署进度总览.md`	2.1 ACR
环境变量清单	`11-Node.js后端-SAE部署配置清单.md`	全文
VPC信息	`00-部署进度总览.md`	2.2 VPC
NAT网关配置	`00-部署进度总览.md`	2.2 NAT
公网访问地址	`00-部署进度总览.md`	2.4 SAE应用

⚠️ 重要提醒

1. 环境变量名必须精确

❌ 常见错误：

PYTHON_SERVICE_URL=http://172.17.173.66:8000

✅ 正确配置：

EXTRACTION_SERVICE_URL=http://172.17.173.66:8000

说明：代码中使用的是 EXTRACTION_SERVICE_URL，不是 PYTHON_SERVICE_URL！

2. 区分"重启应用"和"部署应用"

操作	用途	IP是否变	何时使用
重启应用	重启容器	❌ 不会	修改环境变量、调整配置
部署应用	更新镜像	✅ 会变	更新代码、更新镜像版本

教训：只修改环境变量时，用"重启应用"，避免IP变更！

3. 密码中的@符号要URL编码

❌ 错误：

DATABASE_URL=postgresql://user:Xibahe@fengzhibo117@host:5432/db

✅ 正确：

DATABASE_URL=postgresql://user:Xibahe%40fengzhibo117@host:5432/db

规则：@ → %40

4. 使用VPC地址拉取镜像（省钱）

SAE拉取镜像时：

# ✅ 推荐（VPC地址，免流量费）
crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.3

# ❌ 不推荐（公网地址，收流量费）
crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.3

💡 最佳实践建议

1. 部署前必做

阅读 17-完整部署实战手册-2025版.md
准备好环境变量清单
本地测试Docker镜像
备份数据库
记录当前版本号

2. 部署中注意

按顺序部署（数据库→Python→Node.js→前端）
每个服务部署后验证健康检查
记录内网IP地址
截图重要配置

3. 部署后验证

健康检查通过
前端可以访问
API请求正常
工具C的7大功能测试
文献筛查功能测试
响应时间 < 1秒

🔄 文档更新说明

历史版本

2025-12-24：完成基础文档创建
2025-12-25：完成实战部署，补充实战文档

📞 需要帮助？

常见问题

Q1：我是新手，从哪里开始？

A：直接看 17-完整部署实战手册-2025版.md，跟着做就行！

Q2：我只想更新代码，不想全部重新部署？

A：看你要更新的服务对应的操作手册（如 12-Node.js后端-SAE部署操作手册.md）

Q3：遇到报错了怎么办？

A：先看 17-完整部署实战手册-2025版.md 第9节，99%的问题都在里面

Q4：忘记密码或IP地址了？

A：查 00-部署进度总览.md，所有资源信息都在那里

Q5：想深入理解技术原理？

A：看对应的技术详解文档（如 05-Node.js后端-SAE容器部署指南.md）

🎯 总结

记住这3个核心文档

17-完整部署实战手册-2025版.md - 部署必看
00-部署进度总览.md - 信息速查
本文档 - 找不到文档时看这里

部署成功的关键

✅ 环境变量名必须精确
✅ 区分"重启"和"部署"
✅ 按顺序部署服务
✅ 每步都要验证
✅ 遇到问题先查文档

文档维护：请在每次部署后更新相关文档
最后更新：2025-12-25
维护人员：开发团队

9.9 KiB Raw Blame History Unescape Escape