企业微信集成常见问题

应用配置相关

Q: 如何在企业微信中创建应用？

A: 创建企业微信应用的步骤如下：

登录企业微信管理后台（work.weixin.qq.com）
进入「应用管理」→「自建」
点击「创建应用」
填写应用信息：
- 应用名称：建议使用「Sira AI助手」
- 应用介绍：描述助手功能
- 应用logo：上传应用图标
选择可见范围：建议先设置为小范围测试
点击「创建应用」完成

注意事项：

确保企业微信管理员权限
记录下 AgentID 和 Secret，配置时需要使用

Q: 如何获取企业微信的 CorpID 和 AgentID？

A: 获取步骤：

获取 CorpID：

登录企业微信管理后台
点击右上角「我的企业」
在「企业信息」页面找到「企业ID」，即为 CorpID

获取 AgentID：

进入「应用管理」
点击您创建的应用
在应用详情页面可以看到「AgentId」

获取 Secret：

在应用详情页面
点击「查看Secret」
通过企业微信扫码验证后获得

重要提醒： Secret 只能查看一次，请妥善保存！

Q: 回调 URL 如何配置？

A: 回调 URL 配置步骤：

在 Sira AI 中：
- 创建应用时会自动生成回调 URL
- 格式通常为：https://your-domain.com/api/weixin/{助手ID}
在企业微信管理后台：
- 进入应用设置页面
- 找到「接收消息」设置
- 将 Sira AI 生成的 URL 填入「URL」字段
- 设置 Token（任意字符串，需与 Sira AI 中保持一致）
- 设置 EncodingAESKey（点击随机获取）
验证配置：
- 点击「保存」按钮
- 企业微信会向您的 URL 发送验证请求
- 配置正确会显示「保存成功」

Q: 为什么接收不到企业微信消息？

A: 常见原因及解决方法：

1. 网络连接问题

确保服务器可以访问 qyapi.weixin.qq.com
检查防火墙是否阻止了相关端口

2. 回调 URL 配置错误

检查 URL 是否可公网访问
确认 HTTPS 证书有效
验证 URL 路径是否正确

3. Token 和 EncodingAESKey 不匹配

检查 Sira AI 中配置的 Token 是否与企业微信一致
确认 EncodingAESKey 配置正确

4. 应用权限问题

确认用户在应用的可见范围内
检查应用是否被停用

5. 服务器问题

查看 Sira AI 后台日志
确认服务正常运行
检查数据库连接状态

调试方法：

bash

# 检查网络连通性
curl -I https://qyapi.weixin.qq.com

# 测试回调 URL
curl -X POST "https://your-domain.com/api/weixin/{助手ID}" \
  -H "Content-Type: application/xml" \
  -d '<xml></xml>'

Q: AI Bot 应用和传统应用有什么区别？

A: 详细对比：

特性	AI Bot 应用	传统应用
API 版本	最新 AI Bot API	传统消息 API
响应方式	流式响应（打字效果）	一次性回复
配置复杂度	简单，自动化程度高	需要手动配置回调
用户体验	更自然，类似真人对话	响应较生硬
消息限制	支持更长内容	有字符限制
多媒体支持	更好的图片、文件处理	基础多媒体支持
实时性	实时流式输出	需要等待完整响应

推荐使用 AI Bot 应用，除非有特殊需求必须使用传统模式。

Q: 如何将传统应用升级为 AI Bot？

A: 升级步骤：

在企业微信管理后台：
- 进入应用管理页面
- 选择要升级的应用
- 在设置中查找「AI Bot」选项
- 启用 AI Bot 功能
在 Sira AI 中：
- 编辑对应的应用 (Application)
- 将「应用类型」改为「AI Bot」
- 重新配置相关参数
测试验证：
- 发送测试消息
- 观察是否有流式输出效果
- 确认功能正常工作

注意： 升级过程中可能会短暂中断服务，建议在业务低峰期操作。

权限和安全相关

Q: 如何设置应用的使用权限？

A: 权限设置方法：

1. 企业微信后台设置：

进入应用详情页面
找到「可见范围」设置
选择使用方式：
- 全员可见：所有企业成员可使用
- 部门可见：指定部门成员可使用
- 个人可见：指定具体人员可使用

2. Sira AI 中的权限控制：

访问控制设置
IP 白名单（可选）
时间段限制（可选）

3. 细粒度权限控制：

json

{
  "departments": ["销售部", "客服部"],
  "users": ["zhangsan", "lisi"],
  "time_range": {
    "start": "09:00",
    "end": "18:00"
  },
  "weekdays": [1, 2, 3, 4, 5]
}

Q: 如何确保消息内容的安全性？

A: 安全保障措施：

1. 数据传输安全：

使用 HTTPS 加密传输
企业微信官方加密协议
消息签名验证

2. 数据存储安全：

敏感信息加密存储
定期清理过期数据
数据库访问权限控制

3. 访问控制：

身份验证机制
权限分级管理
操作日志记录

4. 合规性保障：

支持数据本地化部署
遵循企业数据安全政策
提供数据删除接口

5. 监控和审计：

python

# 示例：消息安全检查
def security_check(message):
    # 敏感词过滤
    if contains_sensitive_words(message):
        return False
    
    # 内容合规性检查
    if not compliance_check(message):
        return False
    
    # 用户权限验证
    if not user_authorized(user_id):
        return False
    
    return True

Q: 员工离职后如何处理其对话数据？

A: 数据处理流程：

1. 立即措施：

撤销企业微信应用访问权限
禁用相关应用访问

2. 数据处理：

备份重要对话记录（如需要）
匿名化处理个人信息
删除敏感数据

3. 自动化处理：

sql

-- 示例：数据清理脚本
UPDATE chat_messages 
SET user_name = '已离职员工', 
    user_id = CONCAT('deleted_', user_id),
    content = CASE 
        WHEN is_sensitive = 1 THEN '[敏感内容已删除]'
        ELSE content 
    END
WHERE user_id = '离职员工ID';

4. 审计记录：

记录数据处理操作
生成合规性报告
存档必要文档

消息处理相关

Q: 为什么助手回复很慢？

A: 常见原因及优化方法：

1. AI 模型响应慢：

问题：选择了复杂的大模型
解决：切换到响应更快的模型（如 GPT-3.5）
优化：合理设置上下文长度

2. 网络延迟：

问题：服务器与 AI 服务商距离远
解决：选择地理位置更近的服务节点
优化：使用 CDN 加速

3. 系统负载高：

问题：并发用户过多
解决：增加服务器配置
优化：启用负载均衡

4. 数据库性能：

问题：查询慢，连接池不足
解决：优化数据库索引
优化：增加连接池大小

性能监控：

python

# 响应时间监控示例
import time

@monitor_performance
def process_message(message):
    start_time = time.time()
    
    # 处理消息
    response = ai_model.generate(message)
    
    end_time = time.time()
    response_time = end_time - start_time
    
    # 记录性能指标
    log_performance("message_processing", response_time)
    
    return response

Q: 助手无法理解图片内容怎么办？

A: 图片处理问题解决：

1. 检查模型支持：

确认使用的 AI 模型支持视觉功能
推荐模型：GPT-4o、Claude 3、Gemini Pro Vision

2. 图片格式要求：

支持格式：JPG、PNG、GIF、WebP
大小限制：通常不超过 10MB
分辨率：建议不超过 4K

3. 常见问题：

图片模糊：提醒用户提供清晰图片
文字过小：建议放大或裁剪重要部分
格式不支持：转换为支持的格式

4. 优化提示词：

python

# 图片分析提示词示例
image_prompt = """
请分析这张图片，重点关注：
1. 图片中的文字内容（OCR）
2. 主要物体和场景
3. 图表数据（如果有）
4. 需要特别注意的细节

请用中文详细描述你看到的内容。
"""

5. 错误处理：

python

def process_image(image_data):
    try:
        # 图片预处理
        processed_image = preprocess_image(image_data)
        
        # AI 分析
        result = ai_model.analyze_image(processed_image)
        
        return result
    except UnsupportedFormatError:
        return "抱歉，不支持该图片格式，请提供 JPG 或 PNG 格式的图片。"
    except FileSizeError:
        return "图片过大，请压缩后重新上传（建议小于 5MB）。"
    except Exception as e:
        logger.error(f"图片处理错误: {e}")
        return "图片处理失败，请稍后重试或联系管理员。"

Q: 如何处理大量并发消息？

A: 并发处理策略：

1. 架构设计：

使用消息队列（Redis/RabbitMQ）
实现负载均衡
采用微服务架构

2. 资源优化：

连接池管理
内存缓存策略
数据库查询优化

3. 限流保护：

python

from functools import wraps
import time

def rate_limit(max_requests=100, per_seconds=60):
    def decorator(func):
        request_times = []
        
        @wraps(func)
        def wrapper(*args, **kwargs):
            now = time.time()
            # 清除过期记录
            request_times[:] = [t for t in request_times if now - t < per_seconds]
            
            if len(request_times) >= max_requests:
                raise Exception("请求频率过高，请稍后再试")
            
            request_times.append(now)
            return func(*args, **kwargs)
        
        return wrapper
    return decorator

@rate_limit(max_requests=50, per_seconds=60)
def process_message(message):
    # 处理消息逻辑
    pass

4. 监控指标：

QPS（每秒请求数）
平均响应时间
错误率
系统资源使用率

Q: 企业微信消息格式有哪些限制？

A: 消息格式限制说明：

1. 文本消息：

最大长度：4096 字符
支持换行和基础格式
不支持 HTML 标签

2. 图片消息：

格式：JPG、PNG
大小：不超过 2MB
建议尺寸：不超过 1440x900

3. 文件消息：

大小限制：20MB
支持常见办公文档格式
需要合法的文件扩展名

4. 卡片消息：

json

{
  "msgtype": "textcard",
  "textcard": {
    "title": "卡片标题（最大128字符）",
    "description": "卡片描述（最大512字符）",
    "url": "点击跳转URL",
    "btntxt": "按钮文字（最大4字符）"
  }
}

5. 特殊字符处理：

python

def sanitize_message(content):
    # 移除不支持的字符
    content = re.sub(r'[^\w\s\u4e00-\u9fff]', '', content)
    
    # 长度限制
    if len(content) > 4000:
        content = content[:4000] + "..."
    
    return content

故障排除

Q: 如何查看详细的错误日志？

A: 日志查看和分析方法：

1. 后台日志位置：

应用日志：/var/log/tcfusion/app.log
错误日志：/var/log/tcfusion/error.log
访问日志：/var/log/tcfusion/access.log

2. 日志级别设置：

python

import logging

# 开发环境：详细日志
logging.basicConfig(level=logging.DEBUG)

# 生产环境：关键日志
logging.basicConfig(level=logging.INFO)

3. 企业微信相关日志：

bash

# 筛选企业微信相关日志
grep "wechat\|weixin" /var/log/tcfusion/app.log

# 查看最近的错误
tail -f /var/log/tcfusion/error.log | grep -i error

4. 常见错误代码：

40001：不合法的 access_token
40014：不合法的 access_token
42001：access_token 超时
43004：不合法的媒体文件大小
45015：回复时间超过限制

5. 调试模式启用：

python

# 在配置文件中启用调试
DEBUG = True
WECHAT_DEBUG = True

# 记录详细请求信息
def log_wechat_request(request_data):
    logger.debug(f"WeChat Request: {json.dumps(request_data, indent=2)}")

Q: 企业微信 Token 过期如何自动刷新？

A: Token 自动刷新机制：

1. Token 生命周期：

Access Token：7200 秒（2小时）
建议提前 10 分钟刷新

2. 自动刷新实现：

python

import time
import requests
from threading import Timer

class TokenManager:
    def __init__(self, corp_id, secret):
        self.corp_id = corp_id
        self.secret = secret
        self.access_token = None
        self.expires_at = 0
        self.refresh_timer = None
    
    def get_access_token(self):
        if self.is_token_valid():
            return self.access_token
        
        return self.refresh_token()
    
    def is_token_valid(self):
        return (self.access_token and 
                time.time() < self.expires_at - 600)  # 提前10分钟
    
    def refresh_token(self):
        url = f"https://qyapi.weixin.qq.com/cgi-bin/gettoken"
        params = {
            'corpid': self.corp_id,
            'corpsecret': self.secret
        }
        
        response = requests.get(url, params=params)
        data = response.json()
        
        if data['errcode'] == 0:
            self.access_token = data['access_token']
            self.expires_at = time.time() + data['expires_in']
            self.schedule_next_refresh()
            return self.access_token
        else:
            raise Exception(f"Token刷新失败: {data['errmsg']}")
    
    def schedule_next_refresh(self):
        if self.refresh_timer:
            self.refresh_timer.cancel()
        
        # 提前10分钟刷新
        refresh_delay = max(0, self.expires_at - time.time() - 600)
        self.refresh_timer = Timer(refresh_delay, self.refresh_token)
        self.refresh_timer.start()

3. 错误处理：

python

def handle_token_error(error_code):
    if error_code in [40001, 40014, 42001]:
        # Token 相关错误，立即刷新
        token_manager.refresh_token()
        return True
    return False

Q: 如何测试企业微信集成是否正常？

A: 完整测试流程：

1. 基础连通性测试：

bash

# 测试企业微信 API 连通性
curl "https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=YOUR_CORPID&corpsecret=YOUR_SECRET"

# 测试回调 URL
curl -X POST "https://your-domain.com/api/weixin/test" \
  -H "Content-Type: text/xml" \
  -d '<xml><ToUserName><![CDATA[toUser]]></ToUserName></xml>'

2. 消息发送测试：

python

def test_send_message():
    test_cases = [
        {
            "type": "text",
            "content": "这是一条测试消息"
        },
        {
            "type": "image", 
            "media_id": "test_image_media_id"
        },
        {
            "type": "file",
            "media_id": "test_file_media_id"
        }
    ]
    
    for test_case in test_cases:
        try:
            result = send_message_to_wechat(test_case)
            print(f"✅ {test_case['type']} 消息发送成功: {result}")
        except Exception as e:
            print(f"❌ {test_case['type']} 消息发送失败: {e}")

3. 应用功能测试：

发送简单问题测试基础回复
发送图片测试视觉识别功能
发送语音测试语音识别功能
测试记忆功能（连续对话）
测试 MCP 工具调用

4. 性能测试：

python

import asyncio
import aiohttp

async def performance_test():
    async with aiohttp.ClientSession() as session:
        tasks = []
        
        # 模拟 100 个并发请求
        for i in range(100):
            task = send_test_message(session, f"测试消息 {i}")
            tasks.append(task)
        
        results = await asyncio.gather(*tasks, return_exceptions=True)
        
        # 统计成功率
        success_count = sum(1 for r in results if not isinstance(r, Exception))
        print(f"成功率: {success_count/100*100}%")

5. 监控指标检查：

消息处理延迟 < 3 秒
成功率 > 99%
错误日志无异常
系统资源使用正常

企业微信集成常见问题 ​

应用配置相关 ​

Q: 如何在企业微信中创建应用？ ​

Q: 如何获取企业微信的 CorpID 和 AgentID？ ​

Q: 回调 URL 如何配置？ ​

Q: 为什么接收不到企业微信消息？ ​

Q: AI Bot 应用和传统应用有什么区别？ ​

Q: 如何将传统应用升级为 AI Bot？ ​

权限和安全相关 ​

Q: 如何设置应用的使用权限？ ​

Q: 如何确保消息内容的安全性？ ​

Q: 员工离职后如何处理其对话数据？ ​

消息处理相关 ​

Q: 为什么助手回复很慢？ ​

Q: 助手无法理解图片内容怎么办？ ​

Q: 如何处理大量并发消息？ ​

Q: 企业微信消息格式有哪些限制？ ​

故障排除 ​

Q: 如何查看详细的错误日志？ ​

Q: 企业微信 Token 过期如何自动刷新？ ​

Q: 如何测试企业微信集成是否正常？ ​

相关链接 ​

企业微信集成常见问题

应用配置相关

Q: 如何在企业微信中创建应用？

Q: 如何获取企业微信的 CorpID 和 AgentID？

Q: 回调 URL 如何配置？

Q: 为什么接收不到企业微信消息？

Q: AI Bot 应用和传统应用有什么区别？

Q: 如何将传统应用升级为 AI Bot？

权限和安全相关

Q: 如何设置应用的使用权限？

Q: 如何确保消息内容的安全性？

Q: 员工离职后如何处理其对话数据？

消息处理相关

Q: 为什么助手回复很慢？

Q: 助手无法理解图片内容怎么办？

Q: 如何处理大量并发消息？

Q: 企业微信消息格式有哪些限制？

故障排除

Q: 如何查看详细的错误日志？

Q: 企业微信 Token 过期如何自动刷新？

Q: 如何测试企业微信集成是否正常？

相关链接