simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

chore: 整理项目结构，清理归档文件，更新部署配置

Browse Source
This commit is contained in:
Simon
2026-07-04 21:01:39 +08:00
parent 8bd4ab0366
commit 64ff1bf7d5
508 changed files with 43575 additions and 14129 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/09-部署运维/troubleshooting-故障排查/WAF转发配置异常排查协助.md
+114
View File
@@ -0,0 +1,114 @@
# WAF 转发配置申请
## 问题描述
`itsupport.servyou.com.cn` 域名无法访问，浏览器超时。需 WAF 配置转发规则。
---
## 证据链
### 1. 服务器本地 — 服务正常 ✅
```
# HTTP 已强制跳转 HTTPS（nginx 配置 301 重定向）
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# curl http://localhost/itdesk/health
<html><head><title>301 Moved Permanently</title></head>...nginx/1.27.5</html>
# HTTPS 正常响应
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# curl -k https://127.0.0.1/itdesk/health -H "Host: itsupport.servyou.com.cn"
healthy
```
### 2. SSL 证书 — 有效 ✅
```
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# echo | openssl s_client -connect 127.0.0.1:443 -servername itsupport.servyou.com.cn
CONNECTED(00000003)
depth=2 C=US, O=DigiCert Inc, CN=DigiCert Global Root G2
depth=1 C=US, O=DigiCert, Inc., CN=GeoTrust G2 TLS CN RSA4096 SHA256 2022 CA1
depth=0 C=CN, ST=浙江省, L=杭州市, O=税友软件集团股份有限公司, CN=*.servyou.com.cn
Verification: OK
Protocol: TLSv1.3, Cipher: TLS_AES_256_GCM_SHA384
Verify return code: 0 (ok)
```
证书信息：
- 主体：`CN=*.servyou.com.cn`（通配符证书）
- 颁发者：`GeoTrust G2 TLS CN RSA4096 SHA256 2022 CA1`
- 有效期：2025-12-23 ~ 2027-01-12
### 3. DNS 解析 — 指向 WAF ✅
```
# 服务器 DNS 解析到 WAF 公网 IP
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# ping -c 1 itsupport.servyou.com.cn
PING itsupport.servyou.com.cn (115.236.188.3): 56(84) bytes of data.
--- itsupport.servyou.com.cn ping statistics ---
1 packets transmitted, 0 received, 100% packet loss
```
- 解析结果：`115.236.188.3`（WAF 公网 IP）
- ping 100% 丢失（WAF 禁 ICMP，正常）
### 4. WAF 转发 — 不通 ❌
```
# 从服务器通过域名访问 HTTP（超时）
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# curl -v http://itsupport.servyou.com.cn/itdesk/health
* Trying 115.236.188.3:80...
^C（超时无响应）
# 从服务器通过域名访问 HTTPS（超时）
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# curl -v https://itsupport.servyou.com.cn/itdesk/health
* Trying 115.236.188.3:443...
^C（超时无响应）
```
### 5. 服务器外网连通性 — 正常 ✅
```
# 企微 API 可达
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# curl -s https://qyapi.weixin.qq.com/cgi-bin/gettoken
{"errcode":41004,"errmsg":"corpsecret missing", "from ip": "218.75.34.87"}
# PyPI 镜像可达
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# curl -s https://pypi.tuna.tsinghua.edu.cn/
<html><head><title>302 Found</title></head>...nginx/1.22.1</html>
```
---
## 结论
| 环节 | 状态 |
|------|------|
| 服务器（10.90.5.110） | ✅ HTTP/HTTPS 服务正常 |
| SSL 证书（*.servyou.com.cn） | ✅ 有效，TLSv1.3 |
| DNS 解析 | ✅ 指向 WAF（115.236.188.3） |
| 服务器外网连通性 | ✅ 企微 API / PyPI 均可达 |
| **WAF 转发到后端** | **❌ 未配置 — 流量未到达 10.90.5.110** |
---
## 需要配置
请 WAF/网络团队配置转发规则：
```
域名：itsupport.servyou.com.cn
源端口：80（HTTP）/ 443（HTTPS）
转发目标：10.90.5.110:80
```
---
## 服务器信息
| 项目 | 值 |
|------|-----|
| 服务器 IP | 10.90.5.110 |
| 服务端口 | 80（HTTP→HTTPS 重定向）+ 443（HTTPS） |
| 域名 | itsupport.servyou.com.cn |
| SSL 证书 | *.servyou.com.cn（DigiCert，有效期至 2027-01-12） |
| 系统 | Linux（Docker 部署，nginx 反向代理） |
docs/09-部署运维/troubleshooting-故障排查/通讯链路诊断方案.md
+138
View File
@@ -0,0 +1,138 @@
# 通讯链路诊断方案
> 日期：2026-07-03
> 目标：诊断当前系统通讯问题，无论结果启动重构方案
---
## 一、通讯链路架构
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 完整通讯链路 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 【用户 → 坐席】 │
│ ┌──────────┐ 企微回调 ┌──────────┐ 路由 ┌─────────┐ │
│ │ 用户发送 │ ──────────────→ │ 后端API │ ──────────→ │ Message │ │
│ │ 消息 │ /wecom/ │ 回调入口 │ │ Router │ │
│ └──────────┘ callback └──────────┘ └────┬────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌───────────┐ │
│ │ │ 消息入库 │ │
│ │ │ (DB存储) │ │
│ │ └───────────┘ │
│ │ │ │
│ │ ┌────────────────┘ │
│ │ ▼ │
│ │ ┌──────────┐ │
│ │ │ 坐席收到 │ │
│ │ │(WS/轮询) │ │
│ │ └──────────┘ │
│ │ │
│ 【坐席 → 用户】 │
│ ┌──────────┐ API调用 ┌──────────┐ 企微API ┌────────┐ │
│ │ 坐席发送 │ ──────────────→ │ 后端API │ ──────────→ │企微 │ │
│ │ 消息 │ POST │ 发送消息 │ /message │服务器 │ │
│ └──────────┘ /conversations└──────────┘ /send └────┬───┘ │
│ │ /{id}/messages │ │ │
│ │ ▼ ▼ │
│ │ ┌──────────┐ ┌────────┐ │
│ │ │ 消息入库 │ │用户收到 │ │
│ │ │(DB存储) │ │消息 │ │
│ │ └──────────┘ └────────┘ │
│ │ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 二、诊断检查点
### 2.1 企微回调链路（用户 → 系统）
| 检查点 | 文件位置 | 检查内容 | 预期结果 |
|--------|---------|---------|---------|
| C-01 | `wecom_callback.py` GET `/wecom/callback` | 企微URL验证 | 返回解密后的echostr |
| C-02 | `wecom_callback.py` POST `/wecom/callback` | 消息解密 | 正确解析XML并解密 |
| C-03 | `message_router.py` | 消息路由 | 正确分配会话/坐席 |
| C-04 | 数据库 `messages` 表 | 消息存储 | 消息正确写入 |
### 2.2 坐席发送链路（系统 → 用户）
| 检查点 | 文件位置 | 检查内容 | 预期结果 |
|--------|---------|---------|---------|
| C-05 | `messages.py` POST `/conversations/{id}/messages` | API入口 | 正确接收坐席消息 |
| C-06 | `wecom_service.py` `send_text_message()` | 企微API调用 | errcode=0 |
| C-07 | 企微客户端 | 用户收到消息 | 正常展示 |
### 2.3 H5 实时推送
| 检查点 | 文件位置 | 检查内容 | 预期结果 |
|--------|---------|---------|---------|
| C-08 | `ws_manager.py` | WS连接管理 | 坐席WS连接 |
| C-09 | `frontend-agent` | WS接收 | 消息实时展示 |
| C-10 | `frontend-h5` | 轮询/WebSocket | 新消息实时更新 |
---
## 三、已发现的问题
### 问题1：非文本消息不推送（messages.py:210-233）
```python
# 只有 text 类型消息才调用企微 API 推送给员工
if body.msg_type == "text":
# 调用企微API
```
**影响**：图片、文件等消息无法推送到用户微信端
### 问题2：dev_mode 短路（messages.py:215-216）
```python
if getattr(settings, 'dev_mode', False):
logger.debug(f"[DEV] 跳过企微推送: msg_id={message.id}")
```
**影响**：测试环境下消息不会推送到用户
### 问题3：企微API错误处理（messages.py:231-233）
```python
except Exception as e:
# 企微 API 调用失败不阻塞消息存储
logger.warning(f"企微消息发送失败（消息已存储）: {e}")
```
**影响**：企微API失败时仅记录日志，用户实际未收到消息
---
## 四、诊断执行记录
| 时间 | 检查项 | 结果 | 说明 |
|------|--------|------|------|
| 2026-07-03 | 代码审查 | ✅ | 完成链路分析 |
| - | C-01 企微回调 | ⏳ | 待部署环境验证 |
| - | C-05 坐席发送 | ⏳ | 待部署环境验证 |
| - | C-07 用户收到 | ⏳ | 待实际测试 |
---
## 五、结论
**当前系统通讯链路代码完整**，但存在以下已知风险：
1. 非文本消息（图片/文件）无法推送
2. dev_mode 会跳过企微推送
3. 企微API失败时静默失败
这些问题可通过系统重构进一步优化消息通讯能力。
---
## 六、下一步
**下一步**：根据诊断结果优化现有通讯链路