WeChat Web Client

一个基于 FastAPI + React 的微信 Web 客户端示例项目，用于连接本地或远程微信 Hook/协议服务，提供会话列表、聊天消息、媒体加载、发送消息和实时回调展示等能力。

注意：本项目涉及微信 Hook/协议相关能力，请仅在你拥有授权的环境中学习、测试和使用，并自行遵守相关法律法规与平台规则。

功能特性

• 支持 local_hook、remote_hook、remote_protocol 三种连接模式；其中 remote_hook 表示远程客户端 Hook。
• 支持远程客户端 DLL 通过 ws://.../agent 或 wss://.../agent 主动连到后端，客户端不需要公网 IP，后端复用现有接口封装向 DLL 发送 JSON 调用。
• 支持多微信账号管理，按远程 Hook agent_id 与回调 selfwxid 隔离不同账号的数据、会话和联系人缓存。
• 支持访问密钥进入系统，进入后先展示微信账号卡片，再进入对应账号的聊天窗口，避免未授权用户直接看到聊天记录。
• 后端使用 FastAPI 封装微信 Hook/协议接口，并通过 WebSocket 向前端推送账号状态、会话、联系人和新消息。
• 前端使用 React + TypeScript + Vite，实现类似 PC 微信和手机微信的聊天、通讯录和个人资料界面。
• 支持会话列表、置顶标识、未读数、@我提示、右键菜单、头像缓存、历史消息缓存和本地 SQLite 预加载。
• 支持联系人通讯录：首次点击通讯录时调用 InitContact 获取完整 wxid/gid 列表，再按每批最多 100 个调用 GetContact 补全头像、昵称和画像；后续优先读取本地 SQLite。
• 通讯录按个人、群聊、公众号、服务号、企业微信联系人分类展示，并显示好友、群、公众号、服务号、企微数量；企业微信联系人使用 企微 标识。
• 支持群聊成员详情缓存，可通过 GetChatrooMmemberDetail 获取群成员头像、昵称并复用到群资料页。
• 支持文本、图片、文件发送，以及图片、表情、语音、视频、网址消息等展示；图片/文件类接口支持 fileData 方式，适配远程 Hook。
• 支持单号群发和多号群发，可按所有好友/所有群分类发送，支持 _NoSrc 高效发送和普通发送两种方式。
• 多号群发支持账号手动选择、全选/取消全选、当前账号进度、总进度和用户配置的并发上限。
• 支持手机端自适应访问，包含 Chats / Contacts / Me 底部导航、联系人分类页、资料页、聊天页，以及左右滑动进入/返回的页面过渡。
• 支持白天/夜晚模式，PC 和手机页面统一主题风格。
• 提供自动登录脚本 backend/login_remote_hook.py，可优先尝试免扫码登录，失败后回退到扫码登录。

页面效果

以下图片为脱敏示意效果图，只展示布局和功能区域，不包含真实聊天记录、账号密钥或业务数据。

PC 端

手机端

技术栈

• 后端：Python、FastAPI、Uvicorn、httpx、WebSocket、PyYAML
• 前端：React、TypeScript、Vite、Tailwind CSS
• 通信：REST API + WebSocket

目录结构

wechat_web/
├── backend/              # FastAPI 后端与微信接口封装
├── frontend/             # React + Vite 前端
├── config.example.yaml   # 脱敏配置模板
├── config.yaml           # 本地运行配置（不会提交到 Git）
└── README.md

快速开始

1. 准备配置

复制配置模板：

cp config.example.yaml config.yaml

然后根据你的 Hook/协议服务地址、端口和回调公网 IP 修改 config.yaml。

首次启动如果没有配置访问密钥，项目会自动使用默认 key：admin。建议启动后立即修改 config.yaml 中的 web_access_key 参数，避免继续使用默认密钥。

2. 启动后端

后端使用 Python 3.13。Windows 上运行 start-all.bat 时会自动检查 Python 3.13；未安装时会优先通过 winget 安装，无法使用 winget 时改用 Python 官网安装程序。若系统里有多个 Python，可通过 PYTHON_BIN 指定 3.13 解释器。

cd backend
pip install -r requirements.txt
python login_remote_hook.py
python main.py

远程 Hook DLL 若使用 RemoteWS="ws://公网IP:5000/agent" 直连后端，server_host 需要配置为 0.0.0.0，并确保云服务器安全组放行 5000。如果只通过前端端口或 Nginx 代理 /api、/agent，后端可以只监听 127.0.0.1:5000。

3. 启动前端

cd frontend
npm install
npm run dev

前端开发服务默认由 Vite 启动，接口通过同源代理访问后端。

Windows Server 2012 R2 不在当前 Node.js 的官方支持范围内。start-all.bat 会在检测到该系统时自动设置 NODE_SKIP_PLATFORM_CHECK=1 并验证 Node/npm 是否能够实际运行；如果仍出现系统 API 或 DLL 缺失错误，需要升级到 Windows Server 2016 或更高版本。

Windows 启动时会先清理当前项目遗留的后端、Vite 和 npm 进程，并等待 server_port 确认可用后再启动；stop-all.bat 也使用相同的进程识别和端口复检逻辑。若后端端口被其他项目占用，脚本会显示占用 PID 并停止，不会误杀无关进程。

常用命令

# 前端构建
cd frontend
npm run build

# 指定 Python 3.13 启动（Linux/macOS 示例）
PYTHON_BIN=/usr/bin/python3.13 ./start-all.sh

# 前端代码检查
cd frontend
npm run lint

配置说明

config.yaml 不会被提交到仓库。公开部署或提交代码前，请确认没有把真实 IP、Token、账号信息、日志、缓存文件或聊天媒体数据提交到 Git。

远程 Hook DLL 启动参数

使用远程 Hook 模式时，DLL 启动微信的参数必须带 RemoteWS。该参数用于让远程微信客户端主动建立到 Web 后端的 WebSocket 长连接。后端的 Hook API 调用和 DLL 的实时消息回调都会复用这条连接，不再需要配置 CallBackURL。

示例：

"C:\Program Files (x86)\Tencent\WeChat391016\WeChat\WeChat.exe" RecvType=1&ConnectType=http&RemoteWS="ws://1.14.149.2:5000/agent"&StartPort=30001&RDV=<客户端自己的RDV>

RemoteWS 支持两种形式：

• ws://host:port/agent：普通 WebSocket，适合内网、测试环境，或后端端口直接暴露的部署方式。
• wss://host/agent：TLS 加密 WebSocket，适合公网正式部署，通常由 Nginx/Caddy 等反向代理提供 HTTPS/WSS 证书，并转发到后端服务端口。

如果有多个微信客户端，每个客户端仍连接同一个 RemoteWS 地址；项目会根据远程 Hook 上报的 agent_id 和回调里的 selfwxid 区分不同微信号。

主要配置项：

• wechat_mode：微信使用方式，1=本地 Hook，2=远程客户端 Hook（客户端 DLL 主动连本后端 WS/WSS），3=远程服务器协议。旧配置 login 仍兼容，可选 local_hook、remote_hook、remote_protocol。
• *_host / *_api_port / *_mgr_port：不同模式下的服务地址和端口。
• ip：部署机器的 IP 或域名，作为相关网络配置的默认主机值。
• server_host / server_port：后端主服务监听地址和端口；DLL 直连 ws://公网IP:5000/agent 时用 server_host: "0.0.0.0"，只走前端或 Nginx 代理时可用 127.0.0.1。
• web_access_key：Web 前端和 /api/* 接口访问密钥；首次启动未配置时默认使用 admin，建议在本地 config.yaml 中改成自己的值。不要提交真实值，也可通过环境变量 WECHAT_WEB_ACCESS_KEY 配置。
• hook_api_concurrency：Hook/API 并发数；本地 Hook 默认 1，远程 Hook/远程协议默认 10，用于避免慢查询阻塞 GetContact、头像、发送消息等交互接口。
• QueryDB 历史查询：不再使用旧的全局查询锁；同一账号的同一个数据库文件最多并发 4 路，第 5 个请求最多等待 10 秒，超时返回空结果并在日志中记录 pooled connection unavailable。
• frontend_host / frontend_port：前端开发服务器监听地址和端口，由 Vite 直接读取 config.yaml。Windows 的 start-all.bat 会从 frontend_port 开始检查最多 10 个连续端口，将首个空闲端口回写到 config.yaml，并在页面可访问后自动打开 http://127.0.0.1:<frontend_port>。
• agent_ws_enabled：是否启用远程客户端 DLL 主动连接本后端的 /agent WebSocket 通道；启用后 Hook API 调用会通过这条长连接发给 DLL。
• agent_ws_path：DLL 连接路径，默认 /agent。
• client_wss_host / client_wss_port / client_wss_scheme：生成 DLL 侧 RemoteWS 地址用的公网主机、端口和协议；无证书直连后端可用 client_wss_scheme: "ws"、client_wss_port: 5000，DLL 配置 RemoteWS="ws://1.14.149.2:5000/agent"；正式 TLS 部署用 client_wss_scheme: "wss"、client_wss_port: 443，DLL 配置 RemoteWS="wss://1.14.149.2/agent"。
• 使用前端端口代理 /agent 时，后端 server_port 不需要暴露公网；直连 server_port 时，需要云服务器安全组放行该端口。若使用 Nginx/Caddy，也需要保留 WebSocket Upgrade 头。
• recvtype：Hook 消息接收类型，默认 1；1 为 Hook 直接返回 msglist，2 为 protobuf/raw pb_msg。旧配置 recv_type 仍兼容。
• WECHAT_FILES_BASE：可选环境变量，用于指定本机微信文件目录；不设置时会按默认微信文件目录推导。

消息类型参考

历史消息来自 MSG*.db 的 MSG.Type 字段。当前已知类型：

Type	说明
1	文本消息
3	图片消息
34	语音消息
37	好友确认消息
40	POSSIBLEFRIEND_MSG
42	共享名片
43	视频消息
47	动画表情
48	位置消息
49	分享链接/文件/应用消息；appmsg.type=57 或 SubType=57 为引用消息。带 CompressContent 时优先调用 /GetMsgStruct 获取完整 XML。
50	VOIPMSG
51	微信初始化消息
52	VOIPNOTIFY
53	VOIPINVITE
62	小视频
9999	SYSNOTICE
10000	系统消息
10002	撤回消息

开源前注意事项

• frontend/node_modules/、后端缓存、上传文件、日志和本地配置均已通过 .gitignore 排除。
• 如果你已经误提交敏感配置，请立即撤销对应密钥或令牌，并清理 Git 历史。
• 本仓库默认不包含可运行的微信 Hook 服务本体，需要你自行准备对应服务。