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
393 lines
9.9 KiB
Markdown
393 lines
9.9 KiB
Markdown
# 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
|
||
> **维护人员**：开发团队
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|