vault backup: 2026-07-29 14:41:51

企业微信通知.md

@@ -10,109 +10,183 @@ date: 2026-07-29
 | 企业 ID (CorpID) | `wwa979fc0ebcce602a` |
 | 应用 ID (AgentID) | `1000008` |
 | 应用 Secret | `3QIxJQfqFgACBBcybmyc_I-mOoFvicH-Y6hdQ09ldLk` |
-| 服务端 IP | `59.51.140.250`（Hermes 代理服务器 IP） |
+| Token（回调验证） | `dc56c68beba4c06984ce17c6342cacb1` |
+| EncodingAESKey（回调加密） | `WngnBCzsdXlPcdNBVG6l7auYMokMvuM94jMunTdSEHM` |
+| 回调 URL | `http://api.zilanlife.com/wecom/callback` |
+| 服务端 IP | `59.51.140.250` |
 | 可信域名 | `api.zilanlife.com` |
+| DeepSeek API Key | `sk-8a62671966e1470bb1a6b223a9a549fa` |
+| 回调服务端口 | `18790`（仅 127.0.0.1） |
 
-## 配置步骤
+---
+
+## 一、配置步骤
 
-### 1. 企业微信管理后台 — 创建自建应用
+### 1. 创建自建应用
 
 登录 [work.weixin.qq.com](https://work.weixin.qq.com) → 应用管理 → 创建应用
 
 ### 2. 创建子域名并配置服务器
 
-**DNS 解析（用户在域名管理后台操作）**：
-1. 登录域名 DNS 管理（如阿里云 DNS）
-2. 添加 A 记录：`api.zilanlife.com` → `47.109.158.218`
+**DNS（用户操作）**：A 记录 `api.zilanlife.com` → `47.109.158.218`
 
-**阿里云2 服务器 Nginx 配置（Hermes 代理执行）**：
+**Nginx（Hermes 在 aliyun2 执行）**：
 ```bash
-# 创建 Nginx 站点配置
 cat > /www/server/panel/vhost/nginx/api.zilanlife.com.conf << 'EOF'
 server {
     listen 80;
     server_name api.zilanlife.com;
     root /www/wwwroot/api.zilanlife.com;
     index index.html;
+
+    location /wecom/callback {
+        proxy_pass http://127.0.0.1:18790;
+        proxy_set_header Host $host;
+        proxy_read_timeout 60s;
+    }
 }
 EOF
-
-# 创建站点根目录
 mkdir -p /www/wwwroot/api.zilanlife.com
-
-# 放置验证文件（内容来自微信后台下载）
-echo 'j5y70gNGnVqhnH4d' > /www/wwwroot/api.zilanlife.com/WW_verify_j5y70gNGnVqhnH4d.txt
-
-# 重载 Nginx
 nginx -t && nginx -s reload
 ```
 
-⚠️ 注意：文件直接放在 `/www/wwwroot/api.zilanlife.com/` 根目录，宝塔会自动加载 `/www/server/panel/vhost/nginx/` 下的 `.conf` 文件。
-
 ### 3. 验证域名归属
 
-1. 回到企业微信应用详情页 → 可信域名 → 输入 `api.zilanlife.com`
+1. 企业微信应用详情页 → 网页授权及JS-SDK → 可信域名 → 输入 `api.zilanlife.com`
 2. 下载验证文件 `WW_verify_j5y70gNGnVqhnH4d.txt`
-3. 将文件上传到服务器根目录（见上方命令）
+3. 上传到服务器：
+```bash
+echo 'j5y70gNGnVqhnH4d' > /www/wwwroot/api.zilanlife.com/WW_verify_j5y70gNGnVqhnH4d.txt
+```
 4. 确认 `http://api.zilanlife.com/WW_verify_j5y70gNGnVqhnH4d.txt` 可访问
 5. 点击验证通过
 
-应用详情页 → 「企业可信 IP」→ 添加 `59.51.140.250`
+### 4. 配置 IP 白名单
 
-⚠️ 必须在配置可信域名之后才能操作。
+应用详情页 → 企业可信 IP → 添加 `59.51.140.250`
 
-### 4. 配置可见范围
+⚠️ 必须先完成域名验证才能操作。
 
-应用详情页 → 可见范围 → 选择需要接收消息的部门/成员
+### 5. 配置接收消息
 
-## API 调用流程
+应用详情页 → 接收消息 → 设置API接收：
 
-### 获取 Access Token
+| 字段 | 值 |
+|------|-----|
+| URL | `http://api.zilanlife.com/wecom/callback` |
+| Token | `dc56c68beba4c06984ce17c6342cacb1` |
+| EncodingAESKey | `WngnBCzsdXlPcdNBVG6l7auYMokMvuM94jMunTdSEHM` |
 
-```python
-GET https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid={CorpID}&corpsecret={Secret}
-# 返回: {"access_token": "...", "expires_in": 7200}
+消息事件勾选：用户发送的普通消息
+
+### 6. 部署回调服务
+
+Python 脚本路径：`/data/wecom_callback.py`（aliyun2）
+
+依赖安装：
+```bash
+pip3 install pycryptodome
 ```
 
-Token 有效期 7200 秒（2 小时），需缓存复用。
+启动命令：
+```bash
+nohup python3 /data/wecom_callback.py > /data/wecom_callback.log 2>&1 &
+```
 
-### 发送文本消息
+重启命令：
+```bash
+pkill -f wecom_callback.py
+nohup python3 /data/wecom_callback.py > /data/wecom_callback.log 2>&1 &
+```
+
+---
+
+## 二、回调服务架构
+
+```
+员工在企微发消息
+    ↓
+企微 POST 加密 XML → api.zilanlife.com/wecom/callback
+    ↓
+Nginx 反代 → 127.0.0.1:18790（Python 服务）
+    ↓
+1. URL 验证（GET）：解密 echostr → 返回明文
+2. 接收消息（POST）：解密消息体 → DeepSeek AI → 加密回复
+```
+
+### 核心功能
+
+1. **URL 验证**：GET 请求，解密 `echostr` 参数并返回明文（企业微信首次配置时调用）
+2. **消息接收**：POST XML 加密体，解密后得到用户消息
+3. **AI 回复**：调 DeepSeek API 生成回复
+4. **加密发送**：加密回复 XML，通过 HTTP 响应直接返回
+
+### 加密/解密
+
+- 算法：AES-256-CBC，IV 为 AES Key 前 16 字节
+- 明文结构：`16字节随机串 + 4字节消息长度(big-endian) + 消息内容 + Corpid`
+- PKCS7 填充到 32 字节倍数
+
+---
+
+## 三、API 参考
+
+### 主动发消息
 
 ```python
 POST https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token={TOKEN}
-
 {
-    "touser": "UserID",
+    "touser": "WuXingdeYeKong",
     "msgtype": "text",
     "agentid": 1000008,
     "text": {"content": "消息内容"}
 }
 ```
 
-### 获取通讯录用户
+### 获取通讯录
 
 ```python
 GET https://qyapi.weixin.qq.com/cgi-bin/user/simplelist?access_token={TOKEN}&department_id=1&fetch_child=1
 ```
+- 返回 155 人
+- `userid` 如 `WuXingdeYeKong`，不一定是姓名拼音
+- 申亮 = `WuXingdeYeKong`
 
-返回 `userlist` 数组，每个用户包含 `userid` 和 `name`。
+### Access Token
 
-### 注意事项
+- 接口：`GET /cgi-bin/gettoken?corpid=...&corpsecret=...`
+- 有效期：7200 秒（2 小时）
+- 需缓存复用
 
-- `userid` 是企业微信自动生成的，如 `WuXingdeYeKong`，不一定是姓名拼音
-- 通讯录共 155 人
-- 设计师姓名和企业微信姓名需手动匹配（销帮帮用中文名，企微用英文 userid）
+---
 
-## 诗词 API
+## 四、诗词 API
 
 - 端点：`http://47.109.158.218:1279/api/v1/poems/random`
 - 搜索：`http://47.109.158.218:1279/api/v1/poems/search?q=关键词`
-- ⚠️ 搜索是按内容不是按作者，搜"李白"返回提及李白的诗，不是李白写的
-- 要找特定作者的诗词：用 random 随机抽取直到命中
+- ⚠️ 搜索按内容不按作者，搜"李白"返回提及的诗，非李白所作
+- 按作者找：用 random 随机抽取直到命中
+
+---
+
+## 五、踩坑记录
+
+| 坑 | 现象 | 解决 |
+|----|------|------|
+| 未配可信域名 | IP 白名单无法添加 | 先验证域名，再配 IP |
+| IP 未加白 | 通讯录/user API 返回 60020 | 应用详情 → 企业可信 IP |
+| `userIds` 参数无效 | user/list 返回所有人 | 拉全量客户端建映射 |
+| 回调 Key 不一致 | URL 验证失败 | Token/EncodingAESKey 需与后台严格一致 |
+| DeepSeek Key 错误 | 401 Authorization Required | 使用正确的 sk-xxx key |
+| 搜索按内容不按作者 | 搜"李白"返回马致远 | random 抽到命中为止 |
+
+---
 
-## 已测试功能
+## 六、已验证功能
 
 - ✅ Token 获取
-- ✅ 通讯录读取（155人）
-- ✅ 发送消息到个人（申亮 = WuXingdeYeKong）
-- ✅ 诗词 API → 企业微信 端到端
+- ✅ 通讯录读取（155 人）
+- ✅ 主动发送消息
+- ✅ 诗词 → 企微发送
+- ✅ 接收消息回调 + URL 验证
+- ✅ 员工消息 → DeepSeek AI → 自动回复