AIclinicalresearch/docs/05-部署文档/18-部署文档使用指南.md

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：首次完整部署（新手）

阅读顺序：

1. ✅ 先看：17-完整部署实战手册-2025版.md（2小时）

   • 了解完整流程
   • 准备所需资源
   • 按步骤执行

2. ✅ 遇到问题时参考：

   • 15-Node.js后端-部署成功总结.md
   • 00-部署进度总览.md（查询资源信息）

3. ✅ 想深入了解时看：

   • 01-快速部署SOP-零基础版.md

预计时间：3.5 - 6小时

---

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

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

操作流程：

1. ✅ 修改代码
2. ✅ 本地构建镜像：

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

3. ✅ 推送到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
   

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

参考文档：

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

预计时间：15-30分钟

---

场景3：修改环境变量

例如：修改Python服务地址

操作流程：

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

参考文档：

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

预计时间：5分钟

---

场景4：问题排查

遇到问题时的查找顺序：

1. ✅ 先查：17-完整部署实战手册-2025版.md 第9节

   • 包含实际遇到的所有问题及解决方案
   • 环境变量名错误
   • config目录缺失
   • pino-pretty报错
   • ES Module兼容性
   • bash路径问题

2. ✅ 再查：15-Node.js后端-部署成功总结.md

   • 详细的问题修复历程

3. ✅ 具体问题查：

   • 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-25）

1. ✅ 新增：17-完整部署实战手册-2025版.md

   • 基于实际部署经历编写
   • 包含所有坑点和解决方案
   • 完整的部署流程和验证步骤

2. ✅ 更新：00-部署进度总览.md

   • 添加实战手册引用
   • 更新内网IP地址
   • 添加公网访问地址

3. ✅ 新增：18-部署文档使用指南.md（本文档）

   • 帮助快速找到需要的文档

历史版本

• 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个核心文档

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

部署成功的关键

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

---

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