docs(deploy): Update deployment documentation for Node.js backend

Summary: - Created Node.js backend Docker image build guide - Updated deployment progress overview with backend status - Updated system status documentation Backend build achievements: - Fixed 200+ TypeScript compilation errors (200+ to 0) - Completed Prisma reverse sync (32 models from RDS) - Manually added 30+ Prisma relation fields - Successfully built Docker image (838MB) - Pushed image to ACR (v1.0 + latest tags) Documentation updates: - Added 10-Node.js后端-Docker镜像构建手册.md - Updated 00-部署进度总览.md with backend deployment status - Updated 00-系统当前状态与开发指南.md with latest progress - Fixed date format (2024 -> 2025) Next steps: - Deploy Node.js backend to SAE - Configure environment variables - Test end-to-end functionality Status: Backend Docker image ready for SAE deployment
2025-12-25 08:21:21 +08:00
parent ef967d7d7c
commit 691dc2bc98
112 changed files with 986 additions and 57 deletions
--- a/docs/05-部署文档/00-部署进度总览.md
+++ b/docs/05-部署文档/00-部署进度总览.md
@@ -1,7 +1,7 @@
 # 🚀 AI临床研究平台 - 部署进度总览

 > **文档用途**：统一展示项目部署状态、资源信息、操作手册索引  
-> **更新时间**：2024-12-24  
+> **更新时间**：2025-12-24  
 > **维护人员**：开发团队

 ---
@@ -10,10 +10,10 @@

 | 服务名称 | 部署状态 | 镜像版本 | 部署位置 | 完成时间 | 操作文档 |
 |---------|---------|---------|---------|---------|---------|
-| **PostgreSQL数据库** | ✅ 已完成 | PostgreSQL 15 | RDS | 2024-12-24 | [08-PostgreSQL数据库部署操作手册.md](./08-PostgreSQL数据库部署操作手册.md) |
-| **前端Nginx服务** | ✅ 已完成 | v1.0 | SAE（待部署） | 2024-12-24 | [07-前端Nginx-SAE部署操作手册.md](./07-前端Nginx-SAE部署操作手册.md) |
-| **Python微服务** | ✅ 已完成 | v1.0 | SAE（轻量版） | 2024-12-24 | [09-Python微服务-SAE部署操作手册.md](./09-Python微服务-SAE部署操作手册.md) |
-| **Node.js后端** | ⏳ 待开始 | - | - | - | - |
+| **PostgreSQL数据库** | ✅ 已完成 | PostgreSQL 15 | RDS | 2025-12-24 | [08-PostgreSQL数据库部署操作手册.md](./08-PostgreSQL数据库部署操作手册.md) |
+| **前端Nginx服务** | ✅ 已完成 | v1.0 | SAE（待部署） | 2025-12-24 | [07-前端Nginx-SAE部署操作手册.md](./07-前端Nginx-SAE部署操作手册.md) |
+| **Python微服务** | ✅ 已完成 | v1.0 | SAE（轻量版） | 2025-12-24 | [09-Python微服务-SAE部署操作手册.md](./09-Python微服务-SAE部署操作手册.md) |
+| **Node.js后端** | ✅ 已完成 | v1.0 | SAE（待部署） | 2025-12-24 | [10-Node.js后端-Docker镜像构建手册.md](./10-Node.js后端-Docker镜像构建手册.md) |
 | **Dify AI服务** | ⏳ 待开始 | - | - | - | - |

 **图例说明**：
@@ -40,7 +40,7 @@
 |---------|---------|---------|---------|---------|
 | **python-extraction** | v1.0 | 1.12GB | `crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.0` | `crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.0` |
 | **ai-clinical_frontend-nginx** | v1.0 | ~50MB | `crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v1.0` | `crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/ai-clinical_frontend-nginx:v1.0` |
-| **nodejs-backend** | - | - | `crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend` | `crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend` |
+| **backend-service** | v1.0 | 838MB | `crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0` | `crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0` |

 ---

@@ -99,7 +99,7 @@
 | `common_schema` | 公共模块 | 0 | 预留 |
 | `information_schema` | 系统元数据 | - | PostgreSQL标准 |

-**关键数据量**（截至2024-12-24）：
+**关键数据量**（截至2025-12-24）：
 - 用户：3条
 - AI项目：2条
 - 文献：1204条
@@ -125,7 +125,7 @@ postgresql://airesearch:Xibahe%40fengzhibo117@pgm-2zex1m2y3r23hdn5.pg.rds.aliyun
 | 应用名称 | 状态 | 规格 | 实例数 | 端口 | 内网地址 | 公网地址 |
 |---------|------|------|-------|------|---------|---------|
 | **python-extraction-test** | ✅ 运行中 | 1核2GB | 1 | 8000 | `http://172.17.173.66:8000` | 无（仅内网） |
-| **nodejs-backend** | 待构建 | 2核4GB | 1 | 3001 | 待部署后填写 | 待部署后填写 |
+| **nodejs-backend-test** | 镜像已推送 | 1核2GB | 1 | 3001 | 待部署后填写 | 待部署后填写 |
 | **frontend-nginx** | 镜像已推送 | 1核2GB | 1 | 80 | 待部署后填写 | 待部署后填写 |

 ---
@@ -189,16 +189,19 @@ AIclinicalresearch/extraction_service/
 VPC：crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/python-extraction:v1.0
 ```

-**Node.js后端**（待构建）：
+**Node.js后端**：
 ```
 AIclinicalresearch/backend/
-├── Dockerfile             ⏳ 待创建
-├── .dockerignore         ⏳ 待创建
-└── (配置文件)            ⏳ 待确认
+├── Dockerfile             ✅ 已提交Git（改进版方案B：本地编译+Docker打包）
+├── .dockerignore         ✅ 已提交Git（优化构建上下文）
+├── prisma/schema.prisma  ✅ 已同步RDS（32个模型+30+关系字段）
+└── tsconfig.json         ✅ 已优化（排除测试文件）

-镜像存储位置（预留）：
-公网：crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend:v1.0
-VPC：crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/nodejs-backend:v1.0
+镜像存储位置：
+公网：crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0
+VPC：crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0
+
+镜像摘要：sha256:a4ffb61c15af1cd1ed9de187b4464a1aab773918e5b41b4df5b8ad96514f9941
 ```

 **Git提交规范**：
@@ -218,7 +221,7 @@ VPC：crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/
 ### 3.1 PostgreSQL数据库

 **部署概要**：
- **部署时间**：2024-12-24
+- **部署时间**：2025-12-24
 - **部署方式**：`pg_dump` 全量导出 → RDS导入
 - **数据迁移时长**：约12秒（90MB SQL文件）
 - **验证状态**：✅ Schema完整、数据一致、关系正确
@@ -256,7 +259,7 @@ docker run --name ai-clinical-postgres \
 - **镜像版本**：`v1.0`
 - **镜像大小**：约50MB
 - **基础镜像**：`nginx:alpine`
- **构建时间**：2024-12-24
+- **构建时间**：2025-12-24

 **镜像功能**：
 - ✅ 托管React单页应用（SPA）
@@ -292,14 +295,95 @@ docker run --name ai-clinical-postgres \

 ---

-### 3.3 Python微服务
+### 3.3 Node.js后端服务
+
+**镜像信息**：
+- **仓库名称**：`backend-service`
+- **镜像版本**：`v1.0`
+- **镜像大小**：838MB (压缩后 ~186MB)
+- **基础镜像**：`node:alpine`
+- **构建时间**：2025-12-24
+- **构建策略**：改进版方案B（本地编译+Docker打包）
+
+**构建成果**：
+- ✅ TypeScript编译成功（0错误，修复200+个错误）
+- ✅ Prisma Schema已同步RDS（32个模型）
+- ✅ 手动补全30+个关系字段
+- ✅ 镜像已推送到ACR（v1.0 + latest）
+
+**技术架构**：
+- **Node.js版本**：22.x
+- **Prisma版本**：6.17.0
+- **ORM**：Prisma（支持多Schema）
+- **Web框架**：Fastify
+- **队列系统**：pg-boss（Postgres-Only架构）
+- **缓存系统**：PostgreSQL（替代Redis）
+
+**构建产物**：
+- **Dockerfile**：`AIclinicalresearch/backend/Dockerfile`
+- **.dockerignore**：`AIclinicalresearch/backend/.dockerignore`
+- **Prisma Schema**：`AIclinicalresearch/backend/prisma/schema.prisma`
+
+**SAE配置建议**：
+- **CPU/内存**：1核 / 2GB（测试环境）
+- **实例数**：1
+- **端口**：3001
+- **健康检查**：`GET /health` 返回200
+- **环境变量**（关键配置）：
+  ```bash
+  NODE_ENV=production
+  PORT=3001
+  DATABASE_URL=postgresql://airesearch:Xibahe%40fengzhibo117@pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432/ai_clinical_research?connection_limit=18&pool_timeout=10
+  
+  # Python微服务地址
+  PYTHON_SERVICE_URL=http://172.17.173.66:8000
+  
+  # OSS配置
+  OSS_ACCESS_KEY_ID=LTAI5tB2Dt3NdvBL3G7nYGv7
+  OSS_ACCESS_KEY_SECRET=1iSN9k39RkApP93QjUhC1DcPIeMG4V
+  OSS_BUCKET=ai-clinical-research
+  OSS_ENDPOINT=oss-cn-beijing-internal.aliyuncs.com
+  
+  # JWT密钥
+  JWT_SECRET=your-secret-key-change-in-production
+  JWT_EXPIRES_IN=7d
+  
+  # LLM API Keys
+  DEEPSEEK_API_KEY=sk-7f8cc37a79fa4799860b38fc7ba2e150
+  DASHSCOPE_API_KEY=sk-75b4ff29a14a49e79667a331034f3298
+  
+  # 队列和缓存（Postgres-Only）
+  QUEUE_TYPE=pgboss
+  CACHE_TYPE=postgres
+  ```
+
+**操作文档**：
+- [10-Node.js后端-Docker镜像构建手册.md](./10-Node.js后端-Docker镜像构建手册.md) - 镜像构建详细步骤
+- [05-Node.js后端-SAE容器部署指南.md](./05-Node.js后端-SAE容器部署指南.md) - SAE部署技术指南
+
+**部署状态**：
+- ✅ Prisma反向同步完成（32个模型）
+- ✅ TypeScript编译成功（修复200+错误）
+- ✅ Docker镜像构建成功
+- ✅ 镜像已推送至ACR
+- ⏳ 待部署到SAE
+
+**关键突破**：
+1. ✅ 解决了Prisma `db pull` 后缺少关系字段的问题（手动补全30+个）
+2. ✅ 修复了TypeScript类型错误（JSON、Buffer、pg-boss等）
+3. ✅ 优化了Docker构建策略（本地编译，避免网络超时）
+4. ✅ 实现了零编译错误（200+ → 0）
+
+---
+
+### 3.4 Python微服务

 **镜像信息**：
 - **仓库名称**：`python-extraction`
 - **镜像版本**：`v1.0`
 - **镜像大小**：1.12GB
 - **基础镜像**：`python:3-slim`
- **构建时间**：2024-12-24
+- **构建时间**：2025-12-24

 **功能模块**：
 - ✅ **PDF文本提取**：PyMuPDF 1.26.7
@@ -369,7 +453,7 @@ docker run --name ai-clinical-postgres \
 http://172.17.173.66:8000
 ```

-**部署时间**：2024-12-24
+**部署时间**：2025-12-24
 **健康检查**：✅ 通过

 ---
@@ -482,7 +566,7 @@ docker exec ai-clinical-postgres pg_dump \
  > "backup_$(date +%Y%m%d_%H%M%S).sql"

 # 导入到RDS（需临时开启外网）
-cat backup_20241224_154529.sql | \
+cat backup_20251224_154529.sql | \
  docker exec -i -e PGPASSWORD="Xibahe@fengzhibo117" \
  ai-clinical-postgres psql \
  -h pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com \
@@ -557,12 +641,12 @@ aliyun sae DeployApplication \
 1. ✅ **基础设施**：VPC、NAT网关、安全组
 2. ✅ **数据库**：RDS PostgreSQL（数据迁移+验证）
 3. ✅ **对象存储**：OSS Bucket创建+权限配置
-4. 🔄 **后端服务**：
-   - Python微服务（文档提取+数据清洗）
-   - Node.js后端（API服务器）
-5. 🔄 **前端服务**：Nginx静态资源托管
-6. 🔄 **AI服务**：Dify部署
-7. 🔄 **验证测试**：全链路功能验证
+4. ✅ **后端服务**：
+   - ✅ Python微服务（文档提取+数据清洗）- 已部署到SAE
+   - ✅ Node.js后端（API服务器）- 镜像已构建，待部署
+5. ⏳ **前端服务**：Nginx静态资源托管 - 镜像已推送，待部署
+6. ⏳ **AI服务**：Dify部署
+7. ⏳ **验证测试**：全链路功能验证

 **依赖关系**：
 ```
@@ -641,7 +725,10 @@ aliyun sae DescribeApplicationInstances --AppId xxx
 ### 高优先级 🔴
 - [x] **Python微服务**：部署到SAE并验证 ✅ 已完成
 - [x] **Python微服务**：创建SAE部署操作手册 ✅ 已完成
- [ ] **Node.js后端**：Docker镜像构建
+- [x] **Node.js后端**：Docker镜像构建 ✅ 已完成（2025-12-24）
+- [x] **Node.js后端**：Prisma反向同步 ✅ 已完成（32个模型）
+- [x] **Node.js后端**：TypeScript编译修复 ✅ 已完成（修复200+错误）
+- [x] **Node.js后端**：镜像推送到ACR ✅ 已完成
 - [ ] **Node.js后端**：部署到SAE
 - [ ] **Node.js后端**：配置环境变量（Python服务地址）

@@ -669,11 +756,12 @@ aliyun sae DescribeApplicationInstances --AppId xxx
 - [07-前端Nginx-SAE部署操作手册.md](./07-前端Nginx-SAE部署操作手册.md) - 前端Nginx部署步骤
 - [08-PostgreSQL数据库部署操作手册.md](./08-PostgreSQL数据库部署操作手册.md) - PostgreSQL部署步骤
 - [09-Python微服务-SAE部署操作手册.md](./09-Python微服务-SAE部署操作手册.md) - Python微服务部署步骤
- 待创建：Node.js后端SAE部署操作手册
+- [10-Node.js后端-Docker镜像构建手册.md](./10-Node.js后端-Docker镜像构建手册.md) - Node.js后端Docker构建详解

 ### 技术架构文档
 - [00-部署架构总览.md](./00-部署架构总览.md) - 架构设计与技术选型
 - [04-Python微服务-SAE容器部署指南.md](./04-Python微服务-SAE容器部署指南.md) - Python服务技术详解
+- [05-Node.js后端-SAE容器部署指南.md](./05-Node.js后端-SAE容器部署指南.md) - Node.js后端技术详解
 - [06-前端Nginx-SAE容器部署指南.md](./06-前端Nginx-SAE容器部署指南.md) - 前端Nginx技术详解

 ### 分析报告
@@ -683,7 +771,7 @@ aliyun sae DescribeApplicationInstances --AppId xxx

 ## 🔄 八、更新日志

-### 2024-12-24
+### 2025-12-24
 - ✅ PostgreSQL数据库部署完成
 - ✅ 前端Nginx Docker镜像构建并推送至ACR
 - ✅ Python微服务Docker镜像构建并推送至ACR
@@ -691,6 +779,11 @@ aliyun sae DescribeApplicationInstances --AppId xxx
 - ✅ 创建Python微服务SAE部署操作手册（轻量版SAE配置）
 - ✅ Python微服务成功部署到SAE（内网地址：172.17.173.66:8000）
 - ✅ 解决ACR镜像拉取权限问题（配置镜像仓库认证）
+- ✅ Node.js后端Prisma反向同步完成（32个模型，手动补全30+关系字段）
+- ✅ Node.js后端TypeScript编译修复完成（修复200+错误→0错误）
+- ✅ Node.js后端Docker镜像构建成功（838MB，改进版方案B）
+- ✅ Node.js后端镜像推送至ACR（v1.0 + latest）
+- ✅ 创建Node.js后端Docker镜像构建手册

 ---

@@ -708,5 +801,5 @@ aliyun sae DescribeApplicationInstances --AppId xxx
 ---

 > **提示**：本文档会随着部署进度持续更新，请定期查看最新版本！  
-> **最后更新**：2024-12-24
+> **最后更新**：2025-12-24

--- a/docs/05-部署文档/02-SAE部署完全指南(产品经理版).md
+++ b/docs/05-部署文档/02-SAE部署完全指南(产品经理版).md
@@ -865,3 +865,4 @@ ACR镜像仓库：



+
--- a/docs/05-部署文档/07-前端Nginx-SAE部署操作手册.md
+++ b/docs/05-部署文档/07-前端Nginx-SAE部署操作手册.md
@@ -1352,3 +1352,4 @@ SAE应用配置:



+
--- a/docs/05-部署文档/08-PostgreSQL数据库部署操作手册.md
+++ b/docs/05-部署文档/08-PostgreSQL数据库部署操作手册.md
@@ -1168,3 +1168,4 @@ docker exec -e PGPASSWORD="密码" ai-clinical-postgres psql -h RDS地址 -U air
 祝部署顺利！🎉


+
--- a/docs/05-部署文档/10-Node.js后端-Docker镜像构建手册.md
+++ b/docs/05-部署文档/10-Node.js后端-Docker镜像构建手册.md
@@ -0,0 +1,582 @@
+# Node.js 后端 - Docker 镜像构建操作手册
+
+**文档版本**: v1.0  
+**创建时间**: 2024-12-24  
+**适用范围**: AIclinicalresearch 平台 - Node.js 后端服务  
+**目标读者**: 运维工程师、后端开发工程师
+
+---
+
+## 📋 目录
+
+1. [构建概述](#构建概述)
+2. [前置准备](#前置准备)
+3. [构建流程](#构建流程)
+4. [镜像信息](#镜像信息)
+5. [故障排查](#故障排查)
+6. [最佳实践](#最佳实践)
+
+---
+
+## 1. 构建概述
+
+### 1.1 构建策略
+
+本次构建采用**改进版方案B（本地编译+Docker打包）**，相比传统方案有以下优势：
+
+| 对比项 | 传统方案 | 改进版方案B |
+|--------|----------|-------------|
+| **TypeScript编译** | Docker中执行 | 本地预编译 ✅ |
+| **依赖安装** | 完整依赖 | 仅生产依赖 ✅ |
+| **网络依赖** | 高（易超时） | 低（更稳定） ✅ |
+| **构建时间** | ~10分钟 | ~5分钟 ✅ |
+| **平台兼容性** | 有风险 | 无风险 ✅ |
+
+### 1.2 构建成果
+
+```
+镜像名称: backend-service:v1.0
+镜像大小: 838MB (压缩后 ~186MB)
+镜像ID: a4ffb61c15af
+构建时间: ~5分钟
+ACR地址: crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0
+```
+
+---
+
+## 2. 前置准备
+
+### 2.1 环境检查
+
+```powershell
+# 1. 检查Docker状态
+docker --version
+docker ps
+
+# 2. 检查Node.js环境
+node --version  # 应该显示 v22.x
+npm --version
+
+# 3. 确认当前目录
+cd D:\MyCursor\AIclinicalresearch\backend
+```
+
+### 2.2 代码准备
+
+#### ✅ 必须完成的步骤
+
+**步骤1：Prisma反向同步（必须）**
+
+```powershell
+# 设置临时RDS连接环境变量
+$env:DATABASE_URL = "postgresql://airesearch:Xibahe%40fengzhibo117@pgm-2zex1m2y3r23hdn5oo.pg.rds.aliyuncs.com:5432/ai_clinical_research?connection_limit=18&pool_timeout=10"
+
+# 执行Prisma反向同步
+npx prisma db pull
+
+# 输出应该显示：
+# ✔ Introspected 32 models and wrote them into prisma\schema.prisma
+```
+
+**步骤2：生成Prisma Client**
+
+```powershell
+npx prisma generate
+
+# 输出应该显示：
+# ✔ Generated Prisma Client (v6.17.0)
+```
+
+**步骤3：TypeScript编译（必须）**
+
+```powershell
+# 编译TypeScript代码
+npm run build
+
+# 成功输出：
+# > ai-clinical-backend@1.0.0 build
+# > tsc
+# (无错误信息)
+
+# 检查dist目录是否生成
+ls dist
+```
+
+⚠️ **重要提示**：如果编译失败，必须先修复所有TypeScript错误！
+
+---
+
+## 3. 构建流程
+
+### 3.1 完整构建步骤
+
+```powershell
+# 1. 确保在backend目录
+cd D:\MyCursor\AIclinicalresearch\backend
+
+# 2. 检查Dockerfile和.dockerignore
+ls Dockerfile
+ls .dockerignore
+
+# 3. 开始构建（需要5分钟）
+docker build -t backend-service:v1.0 .
+
+# 4. 查看构建结果
+docker images backend-service:v1.0
+```
+
+### 3.2 构建过程说明
+
+**阶段1：依赖安装（约4分钟）**
+```dockerfile
+FROM node:alpine AS builder
+RUN apk add --no-cache openssl
+COPY package*.json ./
+COPY prisma ./prisma/
+RUN npm ci --production  # 仅安装生产依赖
+RUN npx prisma generate  # 生成Prisma Client
+```
+
+**阶段2：复制本地编译结果（约10秒）**
+```dockerfile
+COPY dist ./dist  # 复制本地已编译的TypeScript代码
+```
+
+**阶段3：运行镜像打包（约1分钟）**
+```dockerfile
+FROM node:alpine
+COPY --from=builder /app/node_modules ./node_modules
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/prisma ./prisma
+```
+
+### 3.3 推送到ACR
+
+```powershell
+# 1. 登录ACR（使用个人版实例地址）
+echo "fengzhibo117" | docker login --username=gofeng117@163.com --password-stdin crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com
+
+# 输出：Login Succeeded
+
+# 2. 打标签
+docker tag backend-service:v1.0 crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0
+docker tag backend-service:v1.0 crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:latest
+
+# 3. 推送镜像
+docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0
+docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:latest
+
+# 输出：
+# v1.0: digest: sha256:a4ffb61c15af... size: 856
+# latest: digest: sha256:a4ffb61c15af... size: 856
+```
+
+---
+
+## 4. 镜像信息
+
+### 4.1 镜像地址
+
+**VPC内网地址（SAE部署使用）：**
+```
+crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0
+```
+
+**公网地址（查看和拉取）：**
+```
+crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0
+```
+
+### 4.2 镜像详情
+
+```yaml
+镜像摘要: sha256:a4ffb61c15af1cd1ed9de187b4464a1aab773918e5b41b4df5b8ad96514f9941
+大小: 838MB (压缩后 ~186MB)
+架构: linux/amd64
+基础镜像: node:alpine
+Node版本: 22.x
+标签: v1.0, latest
+```
+
+### 4.3 镜像内容
+
+```
+/app/
+├── node_modules/          # 生产依赖
+├── dist/                  # 编译后的JS代码
+├── prisma/                # Prisma Schema
+│   └── schema.prisma
+├── package.json
+└── uploads/               # 临时文件目录
+```
+
+### 4.4 启动命令
+
+```dockerfile
+CMD ["node", "dist/index.js"]
+```
+
+### 4.5 健康检查
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:3001/health', (res) => { process.exit(res.statusCode === 200 ? 0 : 1); })"
+```
+
+---
+
+## 5. 故障排查
+
+### 5.1 常见问题
+
+#### ❌ 问题1：TypeScript编译失败
+
+**症状：**
+```
+error TS2554: Expected 2-3 arguments, but got 1.
+error TS2322: Type 'XXX' is not assignable to type 'YYY'.
+```
+
+**原因：**
+- Prisma反向同步后缺少关系字段
+- 代码与Prisma生成的类型不匹配
+
+**解决方案：**
+```powershell
+# 1. 重新同步Prisma
+npx prisma db pull
+npx prisma generate
+
+# 2. 重新编译
+npm run build
+
+# 3. 如果还有错误，检查tsconfig.json配置
+```
+
+#### ❌ 问题2：Docker构建网络超时
+
+**症状：**
+```
+npm error code ECONNRESET
+npm error network aborted
+```
+
+**原因：**
+- npm镜像源网络不稳定
+- npm ci 下载依赖失败
+
+**解决方案：**
+✅ **使用改进版方案B（本次采用的方案）**
+- 本地预编译，跳过Docker中的编译步骤
+- 只安装生产依赖，减少网络传输
+
+#### ❌ 问题3：推送到ACR失败（403 Forbidden）
+
+**症状：**
+```
+Error response from daemon: login attempt to https://registry.cn-beijing.aliyuncs.com/v2/ failed with status: 403 Forbidden
+```
+
+**原因：**
+- 使用了错误的ACR地址
+- 应该使用个人版实例地址，不是企业版地址
+
+**解决方案：**
+```powershell
+# ✅ 正确的登录地址（个人版实例）
+docker login crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com
+
+# ❌ 错误的登录地址（企业版）
+docker login registry.cn-beijing.aliyuncs.com
+```
+
+#### ❌ 问题4：VPC内网地址推送超时
+
+**症状：**
+```
+failed to do request: Head "https://crpi-cd5ij4pjt65mweeo-vpc.cn-beijing.personal.cr.aliyuncs.com/...": net/http: TLS handshake timeout
+```
+
+**原因：**
+- VPC内网地址只能在阿里云VPC内访问
+- 本地开发环境无法访问VPC内网
+
+**解决方案：**
+```powershell
+# 本地开发环境使用公网地址推送
+docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0
+
+# SAE部署时使用VPC内网地址拉取（在SAE控制台配置）
+```
+
+### 5.2 验证镜像
+
+```powershell
+# 1. 检查镜像是否存在
+docker images backend-service:v1.0
+
+# 2. 查看镜像详细信息
+docker inspect backend-service:v1.0
+
+# 3. 测试运行镜像（可选）
+docker run -d `
+  --name backend-test `
+  -p 3001:3001 `
+  -e DATABASE_URL="postgresql://..." `
+  -e NODE_ENV=production `
+  backend-service:v1.0
+
+# 4. 查看容器日志
+docker logs backend-test
+
+# 5. 测试健康检查
+curl http://localhost:3001/health
+
+# 6. 清理测试容器
+docker stop backend-test
+docker rm backend-test
+```
+
+---
+
+## 6. 最佳实践
+
+### 6.1 构建前检查清单
+
+- [ ] 已完成Prisma反向同步（`npx prisma db pull`）
+- [ ] 已生成Prisma Client（`npx prisma generate`）
+- [ ] TypeScript编译成功（`npm run build`）
+- [ ] dist目录已生成且包含所有编译后的JS文件
+- [ ] Docker Desktop已启动并运行
+- [ ] 网络连接正常
+
+### 6.2 版本管理
+
+**镜像标签规范：**
+```
+v1.0       - 特定版本（推荐用于生产环境）
+latest     - 最新版本（用于测试环境）
+v1.0.1     - Bug修复版本
+v1.1.0     - 功能更新版本
+```
+
+**推送策略：**
+```powershell
+# 生产环境部署（推送特定版本）
+docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0
+
+# 测试环境部署（同时推送latest）
+docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:v1.0
+docker push crpi-cd5ij4pjt65mweeo.cn-beijing.personal.cr.aliyuncs.com/ai-clinical/backend-service:latest
+```
+
+### 6.3 构建优化
+
+**1. 利用Docker缓存**
+```dockerfile
+# ✅ 先复制package.json，利用依赖缓存
+COPY package*.json ./
+RUN npm ci --production
+
+# ✅ 最后复制代码，代码变化不影响依赖层缓存
+COPY dist ./dist
+```
+
+**2. 使用.dockerignore**
+```
+node_modules
+.env
+.env.*
+dist          # 本地dist通过COPY显式复制
+test
+tests
+*.md
+.git
+```
+
+**3. 多阶段构建**
+```dockerfile
+# 阶段1：依赖安装
+FROM node:alpine AS builder
+...
+
+# 阶段2：运行时镜像（更小）
+FROM node:alpine
+COPY --from=builder ...
+```
+
+### 6.4 安全建议
+
+1. **不要在镜像中包含敏感信息**
+   - ❌ 不要把`.env`文件复制到镜像
+   - ✅ 使用SAE环境变量注入配置
+
+2. **使用非root用户运行**
+   ```dockerfile
+   RUN addgroup -g 1001 -S nodejs && \
+       adduser -S nodejs -u 1001
+   USER nodejs
+   ```
+
+3. **定期更新基础镜像**
+   ```dockerfile
+   FROM node:alpine  # 使用最新的Alpine版本
+   ```
+
+---
+
+## 附录A：Dockerfile完整内容
+
+```dockerfile
+# ==================== 阶段 1: 依赖安装阶段 ====================
+FROM node:alpine AS builder
+
+# 替换Alpine镜像源为阿里云镜像（解决网络问题）
+RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories
+
+# 安装 Prisma 运行时依赖
+RUN apk add --no-cache openssl
+
+WORKDIR /app
+
+# 1. 复制依赖文件
+COPY package*.json ./
+
+# 2. 复制 Prisma Schema（用于生成Prisma Client）
+COPY prisma ./prisma/
+
+# 3. 只安装生产依赖（大幅减少网络传输和安装时间）
+RUN npm config set registry https://registry.npmmirror.com && \
+    npm config set fetch-retry-mintimeout 20000 && \
+    npm config set fetch-retry-maxtimeout 120000 && \
+    npm config set fetch-retries 5 && \
+    npm ci --production --prefer-offline --no-audit
+
+# 4. 生成 Prisma Client（生产环境需要）
+RUN npx prisma generate
+
+# 5. 复制本地已编译好的 dist 文件夹（跳过TypeScript编译）
+COPY dist ./dist
+
+# ==================== 阶段 2: 运行阶段 ====================
+FROM node:alpine
+
+# 替换Alpine镜像源为阿里云镜像（解决网络问题）
+RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories
+
+# 安装运行时依赖 + 时区数据
+RUN apk add --no-cache \
+    openssl \
+    curl \
+    ca-certificates \
+    tzdata
+
+# ⚠️ 统一时区：Asia/Shanghai
+ENV TZ=Asia/Shanghai
+
+# 创建非 root 用户（安全最佳实践）
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001
+
+WORKDIR /app
+
+# 从构建阶段复制产物
+COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
+COPY --from=builder --chown=nodejs:nodejs /app/dist ./dist
+COPY --from=builder --chown=nodejs:nodejs /app/package*.json ./
+COPY --from=builder --chown=nodejs:nodejs /app/prisma ./prisma
+
+# 创建上传目录（用于临时文件）
+RUN mkdir -p /app/uploads && chown -R nodejs:nodejs /app/uploads
+
+# 切换到非 root 用户
+USER nodejs
+
+# 健康检查
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+  CMD node -e "require('http').get('http://localhost:3001/health', (res) => { process.exit(res.statusCode === 200 ? 0 : 1); })"
+
+# 暴露端口
+EXPOSE 3001
+
+# 🔥 启动命令（仅启动应用，不执行数据库迁移）
+CMD ["node", "dist/index.js"]
+```
+
+---
+
+## 附录B：.dockerignore完整内容
+
+```
+# Node.js
+node_modules
+npm-debug.log
+yarn-error.log
+
+# 开发文件
+.env
+.env.*
+*.local
+
+# 构建产物（改进方案B：使用本地编译好的dist）
+# dist  # 暂时注释掉，允许复制本地dist
+
+# 测试文件
+test
+tests
+*.test.ts
+*.spec.ts
+coverage
+
+# 文档和临时文件
+docs
+*.md
+.vscode
+.idea
+.DS_Store
+Thumbs.db
+
+# 上传文件（运行时生成）
+uploads/*
+
+# Git
+.git
+.gitignore
+
+# 日志
+*.log
+logs
+
+# 临时文件
+temp
+tmp
+*.swp
+*.swo
+*~
+
+# 数据库文件（SQLite，如果有）
+*.db
+*.sqlite
+
+# 脚本文件（仅开发使用）
+scripts/*.ts
+*.bat
+*.ps1
+```
+
+---
+
+## 附录C：相关文档
+
+- [Node.js后端-SAE容器部署指南](./05-Node.js后端-SAE容器部署指南.md)
+- [部署进度总览](./00-部署进度总览.md)
+- [PostgreSQL数据库部署操作手册](./08-PostgreSQL数据库部署操作手册.md)
+- [Python微服务-SAE部署操作手册](./09-Python微服务-SAE部署操作手册.md)
+
+---
+
+**文档维护者**: AI Assistant  
+**最后更新**: 2024-12-24  
+**版本**: v1.0
+
+
--- a/docs/05-部署文档/文档修正报告-20251214.md
+++ b/docs/05-部署文档/文档修正报告-20251214.md
@@ -476,3 +476,4 @@ NAT网关成本¥100/月，对初创团队是一笔开销



+
				`@@ -1168,3 +1168,4 @@ docker exec -e PGPASSWORD="密码" ai-clinical-postgres psql -h RDS地址 -U air`
				`祝部署顺利！🎉`
				`@@ -476,3 +476,4 @@ NAT网关成本¥100/月，对初创团队是一笔开销`