HaHafeng
bbf98c4d5c
Backend fixes: - Fix PgBoss task infinite loop on SAE (root cause: missing queue table constraints) - Add singletonKey to prevent duplicate job enqueueing - Add idempotency check in reviewWorker (skip completed tasks) - Add optimistic locking in reviewService (atomic status update) Frontend fixes: - Add isSubmitting state to prevent duplicate submissions in RVW Dashboard - Fix API baseURL in knowledgeBaseApi (relative path) Cleanup (removed): - Old frontend/ directory (migrated to frontend-v2) - python-microservice/ (unused, replaced by extraction_service) - Root package.json and node_modules (accidentally created) - redcap-docker-dev/ (external dependency) - Various temporary files and outdated docs in root New documentation: - docs/07-运维文档/01-PgBoss队列监控与维护.md - docs/07-运维文档/02-故障预防检查清单.md - docs/07-运维文档/03-数据库迁移注意事项.md Database fix applied to RDS: - Added PRIMARY KEY to platform_schema.queue - Added 3 missing foreign key constraints Tested: Local build passed, RDS constraints verified
268 lines
9.1 KiB
Markdown
268 lines
9.1 KiB
Markdown
# 🎉 2026年1月26-27日部署完成总结
|
||
|
||
> **部署日期**：2026-01-26 15:00 ~ 2026-01-27 08:05
|
||
> **问题修复**：2026-01-27（数据库中文编码问题）
|
||
> **总耗时**：约17小时（跨2天）+ 1小时（编码问题修复）
|
||
> **部署状态**：✅ 核心服务全部完成 + ✅ 中文编码问题已修复
|
||
> **文档日期**：2026-01-27
|
||
|
||
---
|
||
|
||
## 📊 部署成果一览
|
||
|
||
### 服务版本对比
|
||
|
||
| 服务 | 部署前 | 部署后 | 版本提升 |
|
||
|------|--------|--------|---------|
|
||
| PostgreSQL | 15 | 15 + 插件 | 新增pg_bigm/pgvector |
|
||
| Python微服务 | v1.0 | **v1.1** | ⬆️ +1 |
|
||
| Node.js后端 | v1.3 | **v1.7** | ⬆️ +4 |
|
||
| 前端Nginx | v1.2 | **v1.3** | ⬆️ +1 |
|
||
|
||
### 内网地址变更
|
||
|
||
| 服务 | 旧IP | 新IP |
|
||
|------|------|------|
|
||
| Python | 172.17.173.66 | **172.17.173.84** ✨ |
|
||
| 后端 | 172.17.173.73 | **172.17.173.89** ✨ |
|
||
| 前端 | 172.17.173.80 | **172.17.173.90** ✨ |
|
||
|
||
---
|
||
|
||
## ✅ 核心成就
|
||
|
||
### 1. 数据库升级 🔴
|
||
|
||
| 成就 | 详情 |
|
||
|------|------|
|
||
| **插件安装** | pg_bigm 1.2 + pgvector 0.8.0 |
|
||
| **环境分离** | 创建测试数据库 ai_clinical_research_test |
|
||
| **数据迁移** | 63个表完整迁移（17.51MB） |
|
||
| **Schema同步** | 16个Schema，63个模型 |
|
||
| **Prisma规范** | 统一使用Prisma管理数据库变更 |
|
||
|
||
### 2. 服务更新 🟡
|
||
|
||
#### Python微服务
|
||
- ✅ 新增pymupdf4llm（替代nougat）
|
||
- ✅ 新增openpyxl、pypandoc、python-pptx
|
||
- ✅ 镜像优化，利用Docker分层缓存
|
||
|
||
#### Node.js后端
|
||
- ✅ 修复pino-pretty生产环境错误
|
||
- ✅ 修复ES Module导入路径问题
|
||
- ✅ 环境变量完整更新
|
||
- ✅ 移除废弃的Redis/Dify配置
|
||
|
||
#### 前端Nginx
|
||
- ✅ 修复Dockerfile构建（跳过TypeScript检查）
|
||
- ✅ 代码恢复（空文件恢复）
|
||
- ✅ 环境变量更新
|
||
|
||
---
|
||
|
||
## 🔧 解决的关键问题
|
||
|
||
| 序号 | 问题 | 严重程度 | 解决方案 |
|
||
|------|------|---------|---------|
|
||
| 1 | **大量空文件** | 🔴 严重 | 从本地备份恢复 |
|
||
| 2 | **Prisma Schema不一致** | 🔴 严重 | prisma db pull 同步 |
|
||
| 3 | **pino-pretty错误** | 🔴 严重 | 条件加载（根据NODE_ENV） |
|
||
| 4 | **ES Module导入错误** | 🔴 严重 | 添加.js扩展名 |
|
||
| 5 | **TypeScript类型错误** | 🟡 中等 | 跳过类型检查，部署优先 |
|
||
| 6 | **网络构建失败** | 🟡 中等 | 重试构建，使用阿里云镜像源 |
|
||
| 7 | **数据库中文乱码（????）** | 🔴 严重 | PowerShell编码问题，容器内直接导入修复 |
|
||
|
||
---
|
||
|
||
## 📚 文档产出
|
||
|
||
| 文档 | 说明 | 价值 |
|
||
|------|------|------|
|
||
| `00-0126部署总体计划.md` | 部署计划和顺序 | ⭐⭐⭐⭐⭐ |
|
||
| `01-数据库升级方案.md` | 插件安装、环境分离 | ⭐⭐⭐⭐⭐ |
|
||
| `02-OSS环境配置方案.md` | Bucket创建、权限配置 | ⭐⭐⭐⭐ |
|
||
| `03-Python服务更新方案.md` | 依赖更新、构建部署 | ⭐⭐⭐ |
|
||
| `04-后端服务部署方案.md` | Prisma、环境变量 | ⭐⭐⭐⭐ |
|
||
| `05-前端服务部署方案.md` | Nginx部署流程 | ⭐⭐⭐ |
|
||
| `06-IIT回调地址修复方案.md` | 生产环境配置 | ⭐⭐⭐ |
|
||
| `07-0126部署状态真实记录.md` | 实时部署状态 | ⭐⭐⭐⭐⭐ |
|
||
| `database-migration-script.ps1` | 数据库迁移自动化脚本 | ⭐⭐⭐⭐ |
|
||
| `../04-开发规范/09-数据库开发规范.md` | v2.0规范更新 | ⭐⭐⭐⭐⭐ |
|
||
|
||
---
|
||
|
||
## 🎓 经验教训
|
||
|
||
### 1. 代码管理
|
||
|
||
| 问题 | 教训 | 改进措施 |
|
||
|------|------|---------|
|
||
| 大量空文件 | Git操作或AI编辑导致 | 部署前检查git status |
|
||
| 文件丢失恢复耗时 | 缺少实时备份 | 重要操作前先commit |
|
||
|
||
### 2. 依赖管理
|
||
|
||
| 问题 | 教训 | 改进措施 |
|
||
|------|------|---------|
|
||
| ES Module导入路径 | Node.js ESM要求.js扩展名 | 使用linter检查 |
|
||
| TypeScript类型错误 | 阻塞构建 | 分离类型检查和构建 |
|
||
| 网络不稳定 | npm install超时 | 使用国内镜像源 |
|
||
|
||
### 3. 部署流程
|
||
|
||
| 经验 | 说明 |
|
||
|------|------|
|
||
| ✅ Docker分层缓存 | 大幅加速构建（代码变更72秒完成） |
|
||
| ✅ 环境变量重要性 | 服务间互相依赖，IP变更需同步 |
|
||
| ✅ 部署优先策略 | 跳过类型检查，确保快速部署 |
|
||
| ✅ 文档详细记录 | 问题排查和知识沉淀 |
|
||
|
||
### 4. 数据库迁移编码问题 🔴
|
||
|
||
| 问题 | 教训 | 改进措施 |
|
||
|------|------|---------|
|
||
| **PowerShell编码破坏** | PowerShell的 `>` 重定向默认使用UTF-16 LE，`Get-Content` 默认使用GBK，导致UTF-8数据被破坏 | **✅ 解决方案：在Docker容器内直接执行导入，完全绕过PowerShell** |
|
||
| **中文显示为????** | 用户名称、租户名称、联系人等中文字段全部显示为乱码 | 使用 `docker exec ... psql -f` 直接在容器内导入，避免通过PowerShell管道 |
|
||
|
||
**问题详情（2026-01-27）：**
|
||
|
||
**现象**：部署完成后，前端显示用户名称、租户名称、联系人等信息全部为 `????` 或 `??`。
|
||
|
||
**根因分析**：
|
||
1. 数据迁移脚本 `database-migration-script.ps1` 使用 PowerShell 执行 `pg_dump` 和 `psql`
|
||
2. PowerShell 的 `>` 重定向操作符默认使用 **UTF-16 LE** 编码，不是 UTF-8
|
||
3. `Get-Content` 命令默认使用系统编码（Windows 通常是 **GBK/CP936**）
|
||
4. 虽然 `pg_dump` 指定了 `--encoding=UTF8`，但 PowerShell 的管道破坏了编码
|
||
|
||
**修复方案**：
|
||
```bash
|
||
# ❌ 错误做法（PowerShell编码问题）
|
||
docker exec ... pg_dump ... > backup.sql
|
||
Get-Content backup.sql | docker exec ... psql ...
|
||
|
||
# ✅ 正确做法（容器内直接操作）
|
||
docker exec ... pg_dump ... -f /tmp/backup_utf8.sql
|
||
docker exec ... psql ... -f /tmp/backup_utf8.sql
|
||
```
|
||
|
||
**修复步骤（2026-01-27）：**
|
||
1. ✅ 在容器内重新导出数据库（`pg_dump -f /tmp/backup_utf8.sql`）
|
||
2. ✅ 验证导出文件中文正确（`王医生`、`示范医院` 等）
|
||
3. ✅ 强制删除 RDS 测试数据库（`DROP DATABASE ... WITH (FORCE)`）
|
||
4. ✅ 重新创建数据库（`CREATE DATABASE ... ENCODING='UTF8'`）
|
||
5. ✅ 安装插件（pg_bigm、pgvector）
|
||
6. ✅ 在容器内直接导入（`psql -f /tmp/backup_utf8.sql`）
|
||
7. ✅ 验证中文数据正确显示
|
||
|
||
**验证结果**：
|
||
```
|
||
用户名：王医生、李医生、测试用户、超级管理员、Prompt工程师 ✅
|
||
租户名：示范医院、示范药企、壹证循科技、北京积水潭医院、武田制药 ✅
|
||
联系人：张主任、李经理、张院长 ✅
|
||
```
|
||
|
||
**经验总结**：
|
||
- ⚠️ **Windows PowerShell 不适合处理 UTF-8 数据**：重定向和管道会破坏编码
|
||
- ✅ **推荐做法**：数据库迁移时，在 Docker 容器内直接操作，完全绕过 PowerShell
|
||
- ✅ **验证方法**：导入后立即查询中文字段，确认显示正确
|
||
|
||
---
|
||
|
||
## 📋 当前系统配置速查
|
||
|
||
### 数据库连接（测试环境）
|
||
|
||
```bash
|
||
DATABASE_URL=postgresql://airesearch:Xibahe%40fengzhibo117@pgm-2zex1m2y3r23hdn5.pg.rds.aliyuncs.com:5432/ai_clinical_research_test?connection_limit=18&pool_timeout=10
|
||
```
|
||
|
||
### 服务内网地址
|
||
|
||
```bash
|
||
Python: http://172.17.173.84:8000
|
||
后端: http://172.17.173.89:3001
|
||
前端: http://172.17.173.90:80
|
||
```
|
||
|
||
### 公网访问
|
||
|
||
```bash
|
||
CLB: http://8.140.53.236/
|
||
域名: https://iit.xunzhengyixue.com/
|
||
```
|
||
|
||
### OSS配置（测试环境）
|
||
|
||
```bash
|
||
OSS_BUCKET=ai-clinical-data-dev
|
||
OSS_BUCKET_STATIC=ai-clinical-static-dev
|
||
OSS_INTERNAL=true
|
||
OSS_ACCESS_KEY_ID=LTAI5tBHkL39GjdLfcr77Y3f
|
||
```
|
||
|
||
---
|
||
|
||
## 🔜 待完成任务
|
||
|
||
| 任务 | 优先级 | 预计时间 | 状态 |
|
||
|------|--------|---------|------|
|
||
| **IIT回调地址配置** | 🔴 高 | 30分钟 | ⏳ 待完成 |
|
||
| **功能全面测试** | 🔴 高 | 2小时 | ⏳ 待完成 |
|
||
| **数据库中文编码修复** | 🔴 高 | 已完成 | ✅ **2026-01-27 完成** |
|
||
| **TypeScript类型修复** | 🟡 中 | 3小时 | ⏳ 待完成 |
|
||
| **性能测试** | 🟢 低 | 1小时 | ⏳ 待完成 |
|
||
| **监控告警配置** | 🟢 低 | 1小时 | ⏳ 待完成 |
|
||
|
||
---
|
||
|
||
## 📞 后续维护
|
||
|
||
### 日常更新流程
|
||
|
||
```
|
||
1. 修改代码
|
||
2. npm run build（后端）/ npx vite build（前端）
|
||
3. docker build -t service:v1.x .
|
||
4. docker push 到ACR
|
||
5. SAE控制台选择新版本部署
|
||
6. 验证功能
|
||
```
|
||
|
||
### 关键注意事项
|
||
|
||
1. ⚠️ **IP变更影响**：每次部署后检查IP是否变化，及时更新依赖服务的环境变量
|
||
2. ⚠️ **环境变量同步**：确保本地.env、SAE环境变量一致
|
||
3. ⚠️ **数据库备份**：任何Schema变更前必须备份
|
||
4. ⚠️ **版本号管理**：按语义化版本递增
|
||
5. ⚠️ **数据库迁移编码**：**Windows PowerShell 会破坏 UTF-8 编码**，必须使用容器内直接操作（`docker exec ... psql -f`）
|
||
|
||
---
|
||
|
||
## 🙏 致谢
|
||
|
||
感谢开发团队的辛勤工作，历时17小时完成了复杂的升级部署！
|
||
|
||
---
|
||
|
||
---
|
||
|
||
## 📝 后续问题修复记录
|
||
|
||
### 2026-01-27：数据库中文编码问题修复 ✅
|
||
|
||
**问题**：用户名称、租户名称、联系人等中文字段显示为 `????`
|
||
|
||
**原因**：PowerShell 编码问题导致数据迁移时 UTF-8 数据被破坏
|
||
|
||
**修复**：在 Docker 容器内直接执行导入，绕过 PowerShell 编码问题
|
||
|
||
**详情**：见"经验教训 - 数据库迁移编码问题"章节
|
||
|
||
---
|
||
|
||
> **文档版本**：v1.1
|
||
> **最后更新**：2026-01-27（添加中文编码问题修复记录）
|
||
> **维护人员**：开发团队
|
||
|