ZengQingming/JoyD

Fork 0

Files

zqm ed54296f62 taskkill /F /IM nginx.exe

2026-03-20 16:51:31 +08:00

17 KiB

Raw Blame History

企业微信智控未来系统项目规则

1. 项目背景与目标

项目背景：用户拥有一个未经认证的企业微信，包含应用"智控未来"，以及两台服务器（服务器A：公网服务器47.109.191.115 - pactgo.cn，配置SSL证书，外网可访问；服务器B：内网服务器，安装LMStudio，只能访问外网，外网无法直接访问）
项目目标：使用Rust和官方原生微信小程序技术栈实现：用户通过企业微信应用"智控未来"和微信小程序进行聊天，下发任务。任务经服务器A（网关）通过WebSocket反向连接转发到服务器B（SmartClaw），B上的LMStudio进行AI处理后返回结果给用户。
核心架构：WebSocket反向连接（B主动连接A），Embedded-Redis（仅A启动），HeedDB嵌入式数据库，原生小程序（WXML+WXSS+JS）。

2. 系统架构

2.1 整体架构

sequenceDiagram
    participant User as 用户
    participant WeChat as 企业微信/小程序
    participant Gateway as 网关服务（服务器A）
    participant SmartClaw as SmartClaw服务（服务器B）
    participant LMStudio as LMStudio

    User->>WeChat: 发送消息/任务
    WeChat->>Gateway: HTTPS回调请求
    Gateway->>SmartClaw: WebSocket转发任务
    SmartClaw->>SmartClaw: 处理任务（智能控制核心逻辑）
    SmartClaw->>LMStudio: HTTP调用LMStudio API
    LMStudio-->>SmartClaw: SSE流式返回结果
    SmartClaw-->>Gateway: WebSocket回传结果
    Gateway-->>WeChat: HTTPS回调响应
    WeChat-->>User: 显示结果

2.2 组件说明

组件	职责	技术栈
企业微信应用	用户交互界面，接收用户消息和任务	企业微信JS-SDK
微信小程序	用户交互界面，接收用户消息和任务	WXML + WXSS + JavaScript（官方原生）
网关服务（服务器A）	接收HTTPS请求，WebSocket反向连接，Embedded-Redis多用户管理	Rust + Actix Web + Embedded-Redis
SmartClaw服务（服务器B）	WebSocket客户端，处理任务，调用LMStudio，HeedDB存储	Rust + Actix Web + HeedDB
智能控制核心逻辑	核心业务逻辑，处理用户任务，调用LMStudio	Rust
LMStudio	提供AI能力，SSE流式响应	第三方工具

3. 技术选型

3.1 后端技术栈

技术	版本	用途
Rust	1.70+	后端开发语言
Actix Web	4.0+	Web框架，处理HTTP/WebSocket请求
Tokio	1.0+	异步运行时
Serde	1.0+	序列化/反序列化
Reqwest	0.11+	HTTP客户端
Embedded-Redis	最新版	嵌入式Redis（仅网关服务启动）
HeedDB	最新版	嵌入式K/V数据库（Sled底层）

3.2 前端技术栈

技术	版本	用途
WXML + WXSS + JavaScript	最新版	微信小程序官方原生技术栈
企业微信JS-SDK	最新版	企业微信网页开发
微信开发者工具	最新版	官方IDE，完整API支持
wx.request()	原生API	HTTP客户端
wx.connectSocket()	原生API	WebSocket通信

4. 网络通信方案

4.1 企业微信/小程序与网关服务通信

企业微信：使用企业微信回调机制，网关服务提供HTTPS接口接收企业微信的消息推送，回调地址：https://pactgo.cn/wecom
微信小程序：使用HTTPS接口与网关服务通信，实现消息发送和任务下发，接口地址：https://pactgo.cn/api/v1/

4.2 网关服务与SmartClaw服务通信

由于SmartClaw服务在内网中，外网不能访问它，采用WebSocket反向连接方案：

SmartClaw服务主动连接：服务器B启动时，主动WebSocket连接到服务器A（wss://pactgo.cn/ws/control）
单一连接：服务器B与服务器A之间只建立一个WebSocket连接，不需要列表管理
长连接保持：维持持久WebSocket连接，支持心跳检测和断线重连
双向通信：服务器A通过WebSocket发送任务，服务器B处理完成后回传结果
零配置：使用Embedded-Redis（仅网关服务启动），无需独立Redis服务

4.2.1 WebSocket连接管理

服务器B与服务器A：只建立一个WebSocket连接，无需列表管理
其他设备与服务器A：通过WebSocket连接到服务器A的 /ws/task 路径，需要使用连接列表进行管理
连接管理：使用 ConnectionManager 结构体管理设备与服务器A的WebSocket连接，支持多用户多设备场景

4.3 SmartClaw服务与LMStudio通信

使用LMStudio提供的HTTP API接口进行通信
支持SSE流式响应，实时返回AI处理结果
服务器B上的LMStudio监听地址：http://127.0.0.1:1234

5. 安全考虑

5.1 网络安全

所有通信使用HTTPS加密（企业微信强制要求）
服务器A配置防火墙，只开放443端口（HTTPS）
服务器B只允许来自服务器A的WebSocket连接
使用有效SSL证书（Let's Encrypt）

5.2 认证与授权

企业微信应用使用CorpID和Secret进行认证，回调地址：https://pactgo.cn/wecom
微信小程序使用AppID和AppSecret进行认证，接口地址：https://pactgo.cn/api/v1/
服务器间WebSocket通信使用预共享密钥认证
多用户多设备状态管理使用Embedded-Redis

5.3 数据安全

敏感数据加密存储（HeedDB嵌入式数据库支持事务）
定期备份数据
实现访问控制，确保只有授权用户能访问相关功能
多用户多设备状态管理使用Embedded-Redis

6. 项目结构

Claw/
├── Server/                     # 后端服务
│   ├── gateway/                # 网关服务（服务器A）
│   │   ├── src/               # 源代码
│   │   ├── target/            # 编译产出
│   │   └── Cargo.toml         # 项目配置
│   ├── SmartClaw/             # 智能控制服务（服务器B）
│   │   ├── src/               # 源代码
│   │   ├── target/            # 编译产出
│   │   └── Cargo.toml         # 项目配置
│   └── shared/                # 共享代码
│       ├── src/               # 源代码
│       ├── target/            # 编译产出
│       └── Cargo.toml         # 项目配置
├── client/                     # 客户端代码
│   ├── wechat_app/            # 微信小程序（官方原生技术栈）
│   │   ├── pages/             # 页面目录（index, chat, task, user）
│   │   ├── utils/             # 工具函数（api.js, util.js, constant.js）
│   │   ├── components/        # 自定义组件（message, task-card, user-avatar）
│   │   ├── assets/            # 静态资源（images, icons）
│   │   ├── app.js             # 应用入口文件
│   │   ├── app.json           # 应用配置文件
│   │   ├── app.wxss           # 应用全局样式
│   │   ├── project.config.json # 项目配置文件
│   │   └── sitemap.json       # 站点地图配置
│   └── web/                   # 企业微信网页应用（可选）
│       ├── index.html         # 网页入口
│       ├── css/               # 样式文件
│       ├── js/                # JavaScript文件
│       └── assets/            # 静态资源
├── build/                      # 构建产物
│   ├── gateway/               # 网关服务构建产物
│   ├── SmartClaw/             # 智能控制服务构建产物
│   └── client/                # 客户端构建产物
├── docs/                       # 项目文档
├── scripts/                    # 脚本文件
│   ├── build.sh               # 构建脚本
│   ├── deploy_gateway.sh      # 网关服务部署脚本
│   └── deploy_smart_claw.sh   # 智能控制服务部署脚本
├── .gitignore                  # Git忽略文件
├── Cargo.toml                  # 根Rust项目配置（workspace）
├── nginx.conf                  # nginx反向代理配置
├── ssl/                        # SSL证书目录
│   ├── pactgo.cn-chain.pem     # SSL证书链
│   └── pactgo.cn-key.pem       # SSL私钥
└── README.md                   # 项目说明

7. 实施步骤

准备阶段:
- 创建项目基础结构
- 初始化Git仓库
- 初始化Rust和前端项目
后端开发:
- 开发服务器A后端（网关服务）
- 开发服务器B后端（SmartClaw服务）
- 测试服务器间通信
前端开发:
- 开发微信小程序（官方原生技术栈：WXML+WXSS+JS）
- 配置企业微信应用（企业微信JS-SDK）
部署与测试:
- 编写部署脚本
- 部署到服务器
- 功能测试
- 性能测试
- 安全测试
文档编写:
- 编写项目文档
- 编写API文档
- 编写部署文档
- 编写使用文档

8. 企业微信配置详情

8.1 企业微信应用配置

应用基本信息：

应用名称：智控未来
应用主页： https://pactgo.cn
回调地址： https://pactgo.cn/wecom
使用CorpID和Secret进行认证

回调地址说明：

企业微信会将用户消息和事件推送到此地址
必须是HTTPS协议（企业微信强制要求）
路径为 /wecom，对应网关服务的 /api/v1/wecom 路由
支持GET（验证）和POST（消息推送）请求

8.2 网络通信路径

完整的消息流转路径：

用户发送消息 → 企业微信 → https://pactgo.cn/wecom → Nginx → 网关服务(/api/v1/wecom) → 处理消息

路径映射关系：

外部URL	Nginx Location	代理目标	网关路由	处理函数
`https://pactgo.cn/wecom`	`/wecom`	`/wecom`	`/wecom`	`handle_wechat_callback`

8.3 消息处理流程

URL验证（GET请求）：
- 企业微信首次配置时会发送GET请求进行URL验证
- 网关服务需要正确响应验证参数
- 验证通过后企业微信才会发送实际消息
消息推送（POST请求）：
- 用户在企业微信应用中发送消息
- 企业微信将消息POST到回调地址
- 网关服务接收并处理消息
- 返回正确响应给企业微信

8.4 路径一致性检查

企业微信配置路径：

回调地址：https://pactgo.cn/wecom

Nginx代理配置：

location /wecom {
    proxy_pass http://127.0.0.1:8000/api/v1/wecom;
}

网关服务路由：

.route("/wecom", web::post().to(handle_wechat_callback))

验证结果： ✅ 路径完全一致

9. 注意事项

</tool_call>

网络通信:
- 服务器B在内网中，使用WebSocket反向连接方案：SmartClaw服务主动连接网关服务的WebSocket
- 维持持久WebSocket连接，支持心跳检测和断线重连
- 使用Embedded-Redis进行多用户多设备状态管理
- 重要：企业微信回调地址必须保持一致
  - 企业微信配置：https://pactgo.cn/wecom
  - Nginx代理：/wecom → /api/v1/wecom
  - 网关服务路由：/wecom
  - 确保路径完全一致，否则消息无法到达网关服务
安全考虑:
- 所有通信使用HTTPS加密（企业微信强制要求）
- 服务器A配置防火墙，只开放443端口（HTTPS）
- 服务器B只允许来自服务器A的WebSocket连接
- 使用有效SSL证书（Let's Encrypt）
- 实现认证与授权机制（AppID、CorpID、API密钥）
性能考虑:
- 优化WebSocket反向连接，实现长连接和心跳检测
- 合理使用Embedded-Redis进行多用户状态管理
- 合理使用LMStudio，支持流式响应（SSE）
- 使用HeedDB嵌入式数据库，零配置高性能
- 实现异步处理，提供任务状态反馈
兼容性:
- 考虑Windows Server 2012的环境（静态链接编译）
- 确保代码在目标环境中能正常运行
- 网关服务需配置Embedded-Redis和SSL证书
- SmartClaw服务需配置HeedDB和LMStudio连接
部署环境:
- 服务器A：Windows Server 2012系统
- 服务器B：Windows Server 2012系统，安装LMStudio

9. 部署配置详情

9.1 企业微信应用配置

必须配置的参数：

应用名称：智控未来
应用主页：https://pactgo.cn
回调地址：https://pactgo.cn/wecom
CorpID：企业微信的企业ID
Secret：应用的密钥
Token：用于签名验证
EncodingAESKey：消息加解密密钥

回调地址验证：

企业微信会发送GET请求到 https://pactgo.cn/wecom 进行URL验证
网关服务必须正确响应验证参数
验证通过后才会开始推送消息

9.2 Nginx配置验证

关键配置项：

server {
    listen 443 ssl;
    server_name pactgo.cn;
    
    # 企业微信回调 - 必须正确配置
    location /wecom {
        proxy_pass http://127.0.0.1:8000/api/v1/wecom;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # 企业微信回调特殊处理
        proxy_read_timeout 30s;
        proxy_connect_timeout 10s;
    }
}

配置检查清单：

SSL证书有效且未过期
443端口已开放
/wecom 路径正确代理到网关服务
超时设置合理（建议30秒）

9.3 网关服务配置

必须实现的路由：

// 企业微信回调 - 必须匹配企业微信配置
.route("/wecom", web::post().to(handle_wechat_callback))

// 其他路由
.route("/wechat/miniprogram/callback", web::post().to(handle_wechat_miniprogram_callback))
.route("/ws/control", web::get().to(websocket_handler))

处理函数要求：

必须实现GET方法用于URL验证
必须实现POST方法用于消息处理
必须正确验证签名
必须返回正确的响应格式

9.4 路径一致性检查

完整路径映射：

外部URL	Nginx Location	代理目标	网关路由	处理函数
`https://pactgo.cn/wecom`	`/wecom`	`/api/v1/wecom`	`/wecom`	`handle_wechat_callback`
`https://pactgo.cn/api/v1/wechat/miniprogram/callback`	`/api/v1/wechat/miniprogram/callback`	`/api/v1/wechat/miniprogram/callback`	`/wechat/miniprogram/callback`	`handle_wechat_miniprogram_callback`

验证命令：

# 测试企业微信回调地址
curl -X GET "https://pactgo.cn/wecom?msg_signature=xxx&timestamp=xxx&nonce=xxx&echostr=xxx"

# 测试微信小程序回调地址
curl -X POST "https://pactgo.cn/api/v1/wechat/miniprogram/callback" \
  -H "Content-Type: application/json" \
  -d '{"code":"test_code"}'

10. 开发计划

10.1 阶段一：基础设施搭建

配置服务器环境
安装必要的软件和依赖
搭建开发环境

10.2 阶段二：后端开发

开发网关服务（服务器A）的Web服务（Embedded-Redis多用户管理）
开发SmartClaw服务（服务器B）的Web服务（WebSocket客户端）
实现WebSocket反向连接通信（B主动连接A）
开发智能控制核心逻辑
集成LMStudio API（SSE流式响应）

10.3 阶段三：前端开发

开发微信小程序（官方原生技术栈：WXML+WXSS+JS）
配置企业微信应用（企业微信JS-SDK）
- 应用名称：智控未来
- 应用主页： https://pactgo.cn
- 回调地址： https://pactgo.cn/wecom
- 使用CorpID和Secret进行认证

10.4 阶段四：测试与部署

功能测试
性能测试
安全测试
部署到生产环境

10.5 阶段五：运维与监控

配置监控系统
制定运维计划
建立故障处理流程

10. 风险评估

风险	影响	应对措施
企业微信未经认证	可能限制部分功能	尽量使用企业微信开放的基础功能，避免需要认证的高级功能
SmartClaw服务在内网	外网无法直接访问	使用WebSocket反向连接方案：B主动连接A
LMStudio性能	可能影响处理速度	优化智能控制核心逻辑，支持SSE流式响应
网络延迟	可能影响用户体验	优化WebSocket长连接，实现心跳检测和断线重连
SSL证书配置	影响企业微信回调	使用Let's Encrypt自动化证书管理
多用户并发	可能影响系统性能	使用Embedded-Redis进行多用户状态管理

11. 结论

基于以上分析，本项目在技术、网络和成本方面都是可行的。采用WebSocket反向连接架构，使用官方原生微信小程序技术栈，实现用户通过企业微信和微信小程序与系统进行交互，完成AI任务的下发、处理和结果返回。系统具备多用户多设备管理能力，支持高并发和零配置部署。

建议按照开发计划分阶段实施，确保系统的稳定性和可靠性。同时，要注意安全防护，保护用户数据和系统资源。

17 KiB Raw Blame History Unescape Escape