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

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

---

## 🎯 快速导航

### 我应该看哪个文档？

根据您的需求选择：

| 场景 | 推荐文档 | 说明 |
|------|---------|------|
| 🚀 **完整部署系统（推荐）** | [17-完整部署实战手册-2025版.md](./17-完整部署实战手册-2025版.md) | 基于实战经验，包含所有坑点和解决方案 |
| 📚 **学习部署原理** | [01-快速部署SOP-零基础版.md](./01-快速部署SOP-零基础版.md) | 零基础完整教程 |
| 🔍 **查询资源信息** | [00-部署进度总览.md](./00-部署进度总览.md) | IP地址、密码、环境变量等 |
| 🐍 **只部署Python服务** | [09-Python微服务-SAE部署操作手册.md](./09-Python微服务-SAE部署操作手册.md) | Python微服务部署步骤 |
| 🟢 **只部署Node.js后端** | [12-Node.js后端-SAE部署操作手册.md](./12-Node.js后端-SAE部署操作手册.md) | Node.js后端部署步骤 |
| 🎨 **只部署前端Nginx** | [07-前端Nginx-SAE部署操作手册.md](./07-前端Nginx-SAE部署操作手册.md) | 前端Nginx部署步骤 |
| 🗄️ **只部署数据库** | [08-PostgreSQL数据库部署操作手册.md](./08-PostgreSQL数据库部署操作手册.md) | PostgreSQL数据库部署 |
| ❌ **遇到问题排查** | [15-Node.js后端-部署成功总结.md](./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. ✅ 本地构建镜像：
   ```bash
   cd backend
   npm run build
   docker build -t backend-service:v1.4 .
   ```
3. ✅ 推送到ACR：
   ```bash
   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. 环境变量名必须精确

**❌ 常见错误**：
```bash
PYTHON_SERVICE_URL=http://172.17.173.66:8000
```

**✅ 正确配置**：
```bash
EXTRACTION_SERVICE_URL=http://172.17.173.66:8000
```

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

---

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

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

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

---

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

**❌ 错误**：
```bash
DATABASE_URL=postgresql://user:Xibahe@fengzhibo117@host:5432/db
```

**✅ 正确**：
```bash
DATABASE_URL=postgresql://user:Xibahe%40fengzhibo117@host:5432/db
```

**规则**：`@` → `%40`

---

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

**SAE拉取镜像时**：
```bash
# ✅ 推荐（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  
> **维护人员**：开发团队