@xuanyue202/wecom-app-relay 2026.3.21

package/README.md

@@ -0,0 +1,267 @@
+# wecom-app-relay
+
+企业微信自建应用 WebSocket 中继服务器。
+
+将企微回调通过 WebSocket 转发给 OpenClaw extension 客户端，客户端的回复通过中继调用企微 API 发送。**extension 端无需公网 IP**。
+
+## 架构
+
+```
+企微用户 → 企微服务器 → [HTTP 回调] → wecom-app-relay (公网服务器)
+                                           ↕ [WebSocket]
+                                      OpenClaw extension (可在内网)
+                                           ↕
+                                      wecom-app-relay → [企微 API] → 企微用户
+```
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+# npm 全局安装
+npm install -g @xuanyue202/wecom-app-relay
+
+# 或 npx 直接运行
+npx @xuanyue202/wecom-app-relay --config relay.config.json
+
+# 或从源码运行
+cd wecom-app-relay
+pnpm install
+pnpm dev -- --config relay.config.json
+```
+
+### 2. 创建配置文件
+
+创建 `relay.config.json`：
+
+```json
+{
+  "host": "0.0.0.0",
+  "port": 9080,
+  "authToken": "你的认证密钥-随机生成一个长字符串",
+  "accounts": {
+    "default": {
+      "token": "企微回调Token",
+      "encodingAESKey": "企微回调EncodingAESKey（43位）",
+      "receiveId": "企业ID",
+      "corpId": "企业ID",
+      "corpSecret": "应用Secret",
+      "agentId": 1000002,
+      "webhookPath": "/wecom"
+    }
+  }
+}
+```
+
+> **`authToken`** 是 extension 客户端连接中继时的认证密钥，请使用随机字符串，与企微的 token 无关。
+
+### 3. 启动中继
+
+```bash
+wecom-app-relay --config relay.config.json
+```
+
+输出：
+
+```
+[relay] listening on 0.0.0.0:9080
+[relay] WebSocket endpoint: ws://0.0.0.0:9080/ws
+[relay] Webhook endpoint:   http://0.0.0.0:9080/webhook
+[relay] WeCom callback [default]: http://0.0.0.0:9080/wecom
+```
+
+### 4. 配置企微后台
+
+在企微管理后台 → 应用管理 → 你的自建应用 → API 接收消息：
+
+- **URL**：`http://你的服务器IP:9080/wecom`
+- **Token**：与配置文件中 `accounts.default.token` 一致
+- **EncodingAESKey**：与配置文件中 `accounts.default.encodingAESKey` 一致
+
+在「企业可信 IP」中添加中继服务器的公网 IP。
+
+### 5. 配置 OpenClaw extension
+
+编辑 `~/.openclaw/openclaw.json`：
+
+```json
+{
+  "channels": {
+    "wecom-app": {
+      "enabled": true,
+      "mode": "ws-relay",
+      "token": "企微回调Token",
+      "encodingAESKey": "企微回调EncodingAESKey",
+      "corpId": "企业ID",
+      "corpSecret": "应用Secret",
+      "agentId": 1000002,
+      "wsRelayUrl": "ws://你的中继服务器IP:9080/ws",
+      "wsRelayWebhookUrl": "http://你的中继服务器IP:9080/webhook"
+    }
+  }
+}
+```
+
+## 配置参考
+
+### 配置文件字段
+
+| 字段 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `host` | string | `0.0.0.0` | 监听地址 |
+| `port` | number | `9080` | 监听端口 |
+| `authToken` | string | 必填 | WebSocket 认证密钥 |
+| `accounts` | object | 必填 | 企微账户配置（支持多账户） |
+
+### 账户字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `token` | string | 企微回调 Token |
+| `encodingAESKey` | string | 企微回调加密密钥（43 位） |
+| `receiveId` | string | 接收者 ID（通常等于 corpId） |
+| `corpId` | string | 企业 ID |
+| `corpSecret` | string | 应用 Secret |
+| `agentId` | number | 应用 AgentId |
+| `apiBaseUrl` | string | 企微 API 地址（默认 `https://qyapi.weixin.qq.com`） |
+| `webhookPath` | string | 企微回调路径（默认 `/wecom`） |
+
+### 环境变量
+
+也可以通过环境变量配置（无配置文件时使用）：
+
+| 环境变量 | 对应字段 |
+|----------|---------|
+| `RELAY_AUTH_TOKEN` | `authToken` |
+| `RELAY_HOST` | `host` |
+| `RELAY_PORT` | `port` |
+| `WECOM_CORP_ID` | `accounts.default.corpId` + `receiveId` |
+| `WECOM_CORP_SECRET` | `accounts.default.corpSecret` |
+| `WECOM_AGENT_ID` | `accounts.default.agentId` |
+| `WECOM_TOKEN` | `accounts.default.token` |
+| `WECOM_AES_KEY` | `accounts.default.encodingAESKey` |
+| `WECOM_WEBHOOK_PATH` | `accounts.default.webhookPath` |
+
+## HTTP 端点
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET/POST | `/{webhookPath}` | 企微回调（GET 验证 URL，POST 接收消息） |
+| POST | `/webhook` | 接收客户端响应，代调企微 API 发送 |
+| GET | `/health` | 健康检查，返回连接状态 |
+
+## 安全特性
+
+- **认证密钥**：WebSocket 连接需提供 `authToken`（constant-time 比较，防时序攻击）
+- **认证超时**：连接后 10 秒未认证自动断开
+- **心跳检测**：每 30 秒 ping，90 秒无响应断开
+- **速率限制**：每分钟最多 120 条消息
+- **请求体限制**：HTTP/WebSocket 消息最大 1MB
+- **Session 校验**：webhook 响应必须携带有效 session_id
+- **后连接顶替**：同一账户新连接自动断开旧连接
+- **企微签名验证**：回调请求经过签名校验，防伪造
+
+## 多账户配置
+
+支持同时代理多个企微自建应用：
+
+```json
+{
+  "authToken": "shared-auth-token",
+  "accounts": {
+    "app1": {
+      "token": "token-1",
+      "encodingAESKey": "key-1",
+      "receiveId": "ww_corp_1",
+      "corpId": "ww_corp_1",
+      "corpSecret": "secret-1",
+      "agentId": 1000002,
+      "webhookPath": "/wecom/app1"
+    },
+    "app2": {
+      "token": "token-2",
+      "encodingAESKey": "key-2",
+      "receiveId": "ww_corp_2",
+      "corpId": "ww_corp_2",
+      "corpSecret": "secret-2",
+      "agentId": 1000003,
+      "webhookPath": "/wecom/app2"
+    }
+  }
+}
+```
+
+## 协议兼容性
+
+兼容 [lsbot](https://github.com/ruilisi/lsbot) relay 协议。extension 客户端也可以连接 `bot.lingti.com` 公共中继服务（注意共享 IP 和凭证信任问题）。
+
+## 反向代理与 HTTPS
+
+### 有域名（推荐）
+
+用 Caddy 自动签发 Let's Encrypt 证书：
+
+```
+your.domain.com {
+    reverse_proxy localhost:9080
+}
+```
+
+extension 配置：
+```json
+{
+  "wsRelayUrl": "wss://your.domain.com/ws",
+  "wsRelayWebhookUrl": "https://your.domain.com/webhook"
+}
+```
+
+### 无域名（纯 IP + 自签证书）
+
+用 Caddy 自签证书，加密传输但不防中间人：
+
+```
+:443 {
+    tls internal
+    reverse_proxy localhost:9080
+}
+```
+
+extension 配置需加 `wsRelayInsecure: true`：
+```json
+{
+  "wsRelayUrl": "wss://123.45.67.89/ws",
+  "wsRelayWebhookUrl": "https://123.45.67.89/webhook",
+  "wsRelayInsecure": true
+}
+```
+
+> **安全说明**：自签证书场景下，传输通道已加密，但无法验证服务器身份。wecom_raw 模式下对话内容本身仍由企微 AES-256-CBC 加密，中间人只能看到密文。
+
+### Nginx 方案
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name your.domain.com;  # 或 _（纯 IP）
+
+    ssl_certificate     /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://127.0.0.1:9080;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_read_timeout 86400s;
+    }
+}
+```
+
+> `proxy_read_timeout` 设大值避免 WebSocket 长连接被 nginx 超时断开。
+
+## 部署建议
+
+- 可使用 systemd 或 pm2 管理进程
+- 日志输出到 stdout/stderr，可接入日志收集系统