deploy: Complete 0126-27 deployment - database upgrade, services update, code recovery
Major Changes: - Database: Install pg_bigm/pgvector plugins, create test database - Python service: v1.0 -> v1.1, add pymupdf4llm/openpyxl/pypandoc - Node.js backend: v1.3 -> v1.7, fix pino-pretty and ES Module imports - Frontend: v1.2 -> v1.3, skip TypeScript check for deployment - Code recovery: Restore empty files from local backup Technical Fixes: - Fix pino-pretty error in production (conditional loading) - Fix ES Module import paths (add .js extensions) - Fix OSSAdapter TypeScript errors - Update Prisma Schema (63 models, 16 schemas) - Update environment variables (DATABASE_URL, EXTRACTION_SERVICE_URL, OSS) - Remove deprecated variables (REDIS_URL, DIFY_API_URL, DIFY_API_KEY) Documentation: - Create 0126 deployment folder with 8 documents - Update database development standards v2.0 - Update SAE deployment status records Deployment Status: - PostgreSQL: ai_clinical_research_test with plugins - Python: v1.1 @ 172.17.173.84:8000 - Backend: v1.7 @ 172.17.173.89:3001 - Frontend: v1.3 @ 172.17.173.90:80 Tested: All services running successfully on SAE
This commit is contained in:
336
docs/05-部署文档/0126部署/06-IIT回调地址修复方案.md
Normal file
336
docs/05-部署文档/0126部署/06-IIT回调地址修复方案.md
Normal file
@@ -0,0 +1,336 @@
|
||||
# 🔧 IIT回调地址修复方案
|
||||
|
||||
> **文档版本**：v1.0
|
||||
> **创建日期**：2026-01-26
|
||||
> **适用范围**：IIT Manager Agent模块
|
||||
> **变更类型**：配置修复 + 地址变更
|
||||
|
||||
---
|
||||
|
||||
## 📋 一、问题描述
|
||||
|
||||
### 1.1 当前状态
|
||||
|
||||
IIT Manager Agent模块目前使用 **natapp内网穿透** 进行开发调试：
|
||||
|
||||
```yaml
|
||||
开发环境回调URL: https://devlocal.xunzhengyixue.com/api/v1/iit/patient-wechat/callback
|
||||
使用方式: natapp内网穿透映射到本地127.0.0.1:3001
|
||||
适用场景: 本地开发调试
|
||||
```
|
||||
|
||||
### 1.2 目标状态
|
||||
|
||||
部署到SAE生产环境后，需要使用**真实生产域名**：
|
||||
|
||||
```yaml
|
||||
生产环境回调URL: https://iit.xunzhengyixue.com/api/v1/iit/patient-wechat/callback
|
||||
使用方式: 直接访问SAE服务
|
||||
适用场景: 生产环境
|
||||
```
|
||||
|
||||
### 1.3 涉及的回调类型
|
||||
|
||||
| 回调类型 | 开发环境URL | 生产环境URL |
|
||||
|---------|------------|------------|
|
||||
| **企业微信回调** | `https://devlocal.xunzhengyixue.com/api/v1/iit/wechat/callback` | `https://iit.xunzhengyixue.com/api/v1/iit/wechat/callback` |
|
||||
| **微信服务号回调** | `https://devlocal.xunzhengyixue.com/api/v1/iit/patient-wechat/callback` | `https://iit.xunzhengyixue.com/api/v1/iit/patient-wechat/callback` |
|
||||
| **REDCap DET Webhook** | `http://localhost:3001/api/v1/iit/webhooks/redcap` | `https://iit.xunzhengyixue.com/api/v1/iit/webhooks/redcap` |
|
||||
|
||||
---
|
||||
|
||||
## 🔍 二、代码中的地址检查
|
||||
|
||||
### 2.1 已确认的地址引用位置
|
||||
|
||||
通过代码搜索，发现以下位置涉及回调地址：
|
||||
|
||||
**1. 文档中的地址（需要更新）**：
|
||||
- `backend/WECHAT_MP_CONFIG_READY.md`
|
||||
- `backend/WECHAT_ENV_CONFIG.md`
|
||||
- `backend/src/modules/iit-manager/docs/微信服务号接入指南.md`
|
||||
- `backend/DEPLOY_TO_SAE_FOR_WECHAT_MP.md`
|
||||
|
||||
**2. 测试脚本中的地址（保持开发地址，用于本地测试）**：
|
||||
- `backend/src/modules/iit-manager/test-wechat-mp-local.ps1`
|
||||
- `backend/src/modules/iit-manager/test-wechat-mp-plain.ps1`
|
||||
- `backend/src/modules/iit-manager/test-patient-wechat-config.ts`
|
||||
|
||||
**3. 代码生成工具中的地址（需要更新提示信息）**：
|
||||
- `backend/src/modules/iit-manager/generate-wechat-tokens.ts`
|
||||
|
||||
### 2.2 代码本身无需修改
|
||||
|
||||
**重要发现**：代码本身没有硬编码回调地址！
|
||||
|
||||
回调处理是**被动接收**的，URL配置在：
|
||||
- 企业微信后台
|
||||
- 微信服务号后台
|
||||
- REDCap系统设置
|
||||
|
||||
代码只需要正确响应请求即可。
|
||||
|
||||
---
|
||||
|
||||
## 🔧 三、配置修复步骤
|
||||
|
||||
### 3.1 企业微信回调配置
|
||||
|
||||
**登录企业微信管理后台**：
|
||||
1. 访问：https://work.weixin.qq.com/wework_admin/loginpage_wx
|
||||
2. 使用管理员账号登录
|
||||
|
||||
**修改应用回调URL**：
|
||||
1. 进入【应用管理】→【IIT Manager Agent】
|
||||
2. 找到【接收消息】配置
|
||||
3. 修改URL：
|
||||
```
|
||||
旧：https://devlocal.xunzhengyixue.com/api/v1/iit/wechat/callback
|
||||
新：https://iit.xunzhengyixue.com/api/v1/iit/wechat/callback
|
||||
```
|
||||
4. 保持Token和EncodingAESKey不变：
|
||||
```
|
||||
Token: oXlRBm1YnvMy2SbDLbvAdDd5Gq3oBGq
|
||||
EncodingAESKey: v88eT3O9bMW897h4btr7v7qvQImlMf31edTQCmuhOhO
|
||||
```
|
||||
5. 点击【保存】
|
||||
6. 等待企业微信验证回调URL
|
||||
|
||||
### 3.2 微信服务号回调配置
|
||||
|
||||
**登录微信公众平台**：
|
||||
1. 访问：https://mp.weixin.qq.com/
|
||||
2. 使用管理员账号登录
|
||||
|
||||
**修改服务器配置**：
|
||||
1. 进入【设置与开发】→【基本配置】
|
||||
2. 找到【服务器配置】
|
||||
3. 点击【修改配置】
|
||||
4. 修改服务器地址(URL)：
|
||||
```
|
||||
旧：https://devlocal.xunzhengyixue.com/api/v1/iit/patient-wechat/callback
|
||||
新：https://iit.xunzhengyixue.com/api/v1/iit/patient-wechat/callback
|
||||
```
|
||||
5. 保持Token和EncodingAESKey不变
|
||||
6. 点击【提交】
|
||||
7. 等待微信验证服务器配置
|
||||
|
||||
### 3.3 REDCap DET配置（如使用）
|
||||
|
||||
**在REDCap管理后台配置**：
|
||||
1. 登录REDCap Control Center
|
||||
2. 进入项目设置
|
||||
3. 找到Data Entry Trigger (DET)配置
|
||||
4. 修改Webhook URL：
|
||||
```
|
||||
旧：http://localhost:3001/api/v1/iit/webhooks/redcap
|
||||
新：https://iit.xunzhengyixue.com/api/v1/iit/webhooks/redcap
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ 四、验证步骤
|
||||
|
||||
### 4.1 验证服务可访问
|
||||
|
||||
```bash
|
||||
# 1. 验证健康检查端点
|
||||
curl https://iit.xunzhengyixue.com/api/v1/iit/health
|
||||
|
||||
# 预期返回：{ "status": "ok", ... }
|
||||
```
|
||||
|
||||
### 4.2 验证企业微信回调
|
||||
|
||||
```bash
|
||||
# 企业微信调试工具会自动验证
|
||||
# 或手动测试GET请求（URL验证）
|
||||
|
||||
curl "https://iit.xunzhengyixue.com/api/v1/iit/wechat/callback?msg_signature=test×tamp=123&nonce=abc&echostr=hello"
|
||||
|
||||
# 如果返回echostr内容（hello），说明验证通过
|
||||
```
|
||||
|
||||
### 4.3 验证微信服务号回调
|
||||
|
||||
```bash
|
||||
# 微信平台会自动发送验证请求
|
||||
# 验证成功后状态显示"已启用"
|
||||
```
|
||||
|
||||
### 4.4 端到端测试
|
||||
|
||||
1. **企业微信测试**：
|
||||
- 在企业微信中向IIT Manager Agent发送消息
|
||||
- 确认收到AI回复
|
||||
|
||||
2. **微信服务号测试**：
|
||||
- 关注服务号并发送消息
|
||||
- 确认收到回复
|
||||
|
||||
3. **REDCap测试**（如配置）：
|
||||
- 在REDCap中保存一条记录
|
||||
- 确认触发Webhook并处理成功
|
||||
|
||||
---
|
||||
|
||||
## 📝 五、文档更新清单
|
||||
|
||||
### 5.1 需要更新的文档
|
||||
|
||||
以下文档中的地址引用需要更新或添加说明：
|
||||
|
||||
| 文档路径 | 更新内容 |
|
||||
|---------|---------|
|
||||
| `backend/WECHAT_MP_CONFIG_READY.md` | 添加生产环境URL说明 |
|
||||
| `backend/WECHAT_ENV_CONFIG.md` | 更新URL配置说明 |
|
||||
| `backend/DEPLOY_TO_SAE_FOR_WECHAT_MP.md` | 确认生产URL正确 |
|
||||
| `docs/03-业务模块/IIT Manager Agent/00-模块当前状态与开发指南.md` | 更新回调URL状态 |
|
||||
|
||||
### 5.2 代码文件更新（可选）
|
||||
|
||||
更新提示信息，帮助开发者区分环境：
|
||||
|
||||
**`generate-wechat-tokens.ts`**：
|
||||
```typescript
|
||||
console.log('回调URL配置：');
|
||||
console.log(' 开发环境：https://devlocal.xunzhengyixue.com/api/v1/iit/patient-wechat/callback');
|
||||
console.log(' 生产环境：https://iit.xunzhengyixue.com/api/v1/iit/patient-wechat/callback');
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 六、环境切换说明
|
||||
|
||||
### 6.1 开发环境（本地调试）
|
||||
|
||||
```yaml
|
||||
使用方式: natapp内网穿透
|
||||
启动命令: natapp.exe -authtoken=YOUR_TOKEN -subdomain=devlocal
|
||||
回调URL: https://devlocal.xunzhengyixue.com/...
|
||||
后端地址: 127.0.0.1:3001
|
||||
```
|
||||
|
||||
### 6.2 SAE测试环境
|
||||
|
||||
```yaml
|
||||
使用方式: SAE服务 + 测试数据库
|
||||
回调URL: https://iit.xunzhengyixue.com/...（可配置测试域名）
|
||||
后端地址: SAE内网IP:3001
|
||||
```
|
||||
|
||||
### 6.3 SAE生产环境
|
||||
|
||||
```yaml
|
||||
使用方式: SAE服务 + 生产数据库
|
||||
回调URL: https://iit.xunzhengyixue.com/...
|
||||
后端地址: SAE内网IP:3001
|
||||
公网访问: https://iit.xunzhengyixue.com/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 七、注意事项
|
||||
|
||||
### 7.1 域名备案
|
||||
|
||||
`iit.xunzhengyixue.com` 域名必须已完成ICP备案，否则无法在微信平台使用。
|
||||
|
||||
**确认状态**：✅ 已备案（根据历史记录）
|
||||
|
||||
### 7.2 SSL证书
|
||||
|
||||
回调URL必须使用HTTPS，确认SSL证书：
|
||||
- 证书有效期
|
||||
- 证书链完整
|
||||
- 域名匹配
|
||||
|
||||
### 7.3 防火墙/安全组
|
||||
|
||||
确保SAE服务可以接收来自：
|
||||
- 企业微信服务器的请求
|
||||
- 微信公众平台服务器的请求
|
||||
- REDCap服务器的请求
|
||||
|
||||
### 7.4 Token和密钥管理
|
||||
|
||||
**切勿泄露**：
|
||||
- Token
|
||||
- EncodingAESKey
|
||||
- Corp Secret
|
||||
|
||||
这些密钥在开发和生产环境可以相同，但要确保安全存储。
|
||||
|
||||
---
|
||||
|
||||
## 📊 八、检查清单
|
||||
|
||||
### 部署前
|
||||
|
||||
- [ ] 确认SAE后端服务已部署并正常运行
|
||||
- [ ] 确认 `https://iit.xunzhengyixue.com/api/v1/iit/health` 可访问
|
||||
- [ ] 确认域名SSL证书有效
|
||||
|
||||
### 配置修改
|
||||
|
||||
- [ ] 企业微信回调URL已更新
|
||||
- [ ] 微信服务号回调URL已更新
|
||||
- [ ] REDCap DET URL已更新（如使用）
|
||||
|
||||
### 验证
|
||||
|
||||
- [ ] 企业微信URL验证通过
|
||||
- [ ] 微信服务号URL验证通过
|
||||
- [ ] 企业微信消息收发正常
|
||||
- [ ] 微信服务号消息收发正常
|
||||
- [ ] REDCap Webhook触发正常（如使用）
|
||||
|
||||
---
|
||||
|
||||
## 📞 九、问题排查
|
||||
|
||||
### 问题1：URL验证失败
|
||||
|
||||
**可能原因**：
|
||||
- 后端服务未启动
|
||||
- SSL证书问题
|
||||
- 回调路由未注册
|
||||
|
||||
**排查步骤**：
|
||||
1. 检查健康端点：`curl https://iit.xunzhengyixue.com/api/v1/iit/health`
|
||||
2. 检查回调端点：`curl https://iit.xunzhengyixue.com/api/v1/iit/wechat/callback`
|
||||
3. 查看SAE日志
|
||||
|
||||
### 问题2：消息无响应
|
||||
|
||||
**可能原因**：
|
||||
- 消息加解密配置错误
|
||||
- AI服务调用超时
|
||||
- 数据库连接问题
|
||||
|
||||
**排查步骤**：
|
||||
1. 检查SAE日志中的错误信息
|
||||
2. 确认环境变量配置正确
|
||||
3. 测试AI服务连接
|
||||
|
||||
### 问题3：超时错误
|
||||
|
||||
**可能原因**：
|
||||
- 微信要求5秒内响应
|
||||
- AI处理时间过长
|
||||
|
||||
**解决方案**：
|
||||
- 代码已使用异步回复模式（setImmediate）
|
||||
- 确保先返回空字符串，再异步推送消息
|
||||
|
||||
---
|
||||
|
||||
> **最后更新**：2026-01-26
|
||||
> **维护人员**：开发团队
|
||||
> **参考文档**：
|
||||
> - [企业微信开发文档](https://developer.work.weixin.qq.com/document/)
|
||||
> - [微信公众平台开发文档](https://developers.weixin.qq.com/doc/offiaccount/Getting_Started/Overview.html)
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user