渠道配置指南

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

> **搜索标签**: 渠道, 渠道配置, 邮件, 短信, 通知
---

# 渠道管理配置指南

本文档详细说明如何配置各个渠道（微信公众号、微信小程序、企业微信、企业微信服务商）。

## 目录

1. [微信公众号配置](#微信公众号配置)
2. [微信小程序配置](#微信小程序配置)
3. [企业微信配置](#企业微信配置)
4. [企业微信服务商配置](#企业微信服务商配置)
5. [常见问题](#常见问题)

---

## 微信公众号配置

### 获取配置信息

#### 1. 登录微信公众平台

访问：https://mp.weixin.qq.com/

#### 2. 进入基本配置

路径：设置与开发 → 基本配置

#### 3. 获取配置信息

**AppID 和 AppSecret**：
- 点击"开发者ID（AppID）"旁边的"查看"
- 输入公众号管理员密码
- 复制 AppID 和 AppSecret

**Token**：
- 任意自定义字符串，例如：`your-secret-token-2024`
- 长度要求：3-32个字符
- 仅支持字母、数字、下划线

**EncodingAESKey**：
- 随机生成或自定义
- 长度要求：43个字符
- 字符集：A-Z, a-z, 0-9

**服务器URL**：
- 格式：`https://yourdomain.com/api/wechat/callback/{channelId}`
- 示例：`https://example.com/api/wechat/callback/12345678-1234-1234-1234-123456789012`
- 注意：必须是HTTPS协议
- 注意：域名需要备案

**消息加解密方式**：
- **明文模式**：消息不加密，适合开发环境
- **兼容模式**：支持明文和密文，自动识别
- **安全模式**：消息完全加密，推荐生产环境使用

### 配置步骤

#### 步骤1：填写配置

在渠道管理页面 → 微信公众号 → 基础配置，填写以下信息：

| 字段 | 说明 | 示例 |
|------|------|------|
| AppID | 微信公众号的唯一标识 | wx1234567890abcdef |
| AppSecret | 微信公众号的密钥 | a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 |
| 服务器URL | 消息接收地址 | https://example.com/api/wechat/callback/123 |
| Token | 验证令牌 | my-secret-token-2024 |
| EncodingAESKey | 消息加解密密钥 | 43位随机字符串 |
| 消息加解密方式 | 加密模式选择 | 安全模式 |

#### 步骤2：保存配置

点击"保存配置"按钮，系统会验证必填字段。

#### 步骤3：配置微信公众平台

1. 在微信公众平台"服务器配置"中，填写：
   - URL：服务器URL
   - Token：与系统配置一致
   - EncodingAESKey：与系统配置一致
   - 消息加解密方式：与系统配置一致

2. 点击"提交"按钮

3. 微信会发送GET请求验证服务器，验证通过后配置生效

#### 步骤4：测试配置

在渠道管理页面点击"测试"按钮，验证配置是否正确。

### 验证成功标志

✅ 微信公众平台显示"服务器配置已启用"
✅ 可以接收到粉丝发送的消息
✅ 菜单可以正常发布
✅ 模板消息可以正常发送

---

## 微信小程序配置

### 获取配置信息

#### 1. 登录微信小程序管理后台

访问：https://mp.weixin.qq.com/

#### 2. 进入开发管理

路径：开发 → 开发管理 → 开发设置

#### 3. 获取AppID和AppSecret

**AppID**：
- 开发者ID（AppID）可以直接看到

**AppSecret**：
- 点击"生成AppSecret"
- 扫码确认
- 复制AppSecret（仅显示一次）

### 配置步骤

#### 步骤1：填写配置

在渠道管理页面 → 微信小程序 → 基础配置，填写以下信息：

| 字段 | 说明 | 示例 |
|------|------|------|
| AppID | 微信小程序的唯一标识 | wx1234567890abcdef |
| AppSecret | 微信小程序的密钥 | a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 |

#### 步骤2：保存配置

点击"保存配置"按钮。

#### 步骤3：配置小程序服务器域名

在微信小程序管理后台 → 开发 → 开发设置 → 服务器域名，配置：

- **request合法域名**：https://yourdomain.com
- **uploadFile合法域名**：https://yourdomain.com
- **downloadFile合法域名**：https://yourdomain.com

### 验证成功标志

✅ 可以正常获取用户信息
✅ 可以正常调用小程序接口
✅ 用户数据可以正常同步

---

## 企业微信配置

### 获取配置信息

#### 1. 登录企业微信管理后台

访问：https://work.weixin.qq.com/

#### 2. 进入应用管理

路径：应用管理 → 应用 → 自建应用

#### 3. 获取配置信息

**企业ID（CorpId）**：
- 我的企业 → 企业信息 → 企业ID

**AgentId**：
- 应用管理 → 应用 → 自建应用 → AgentId

**AgentSecret**：
- 应用管理 → 应用 → 自建应用 → Secret → 查看
- 复制Secret

### 配置步骤

#### 步骤1：填写配置

在渠道管理页面 → 企业微信 → 基础配置，填写以下信息：

| 字段 | 说明 | 示例 |
|------|------|------|
| 企业ID（CorpId） | 企业微信的企业ID | ww1234567890abcdef |
| AgentId | 应用的AgentId | 1000002 |
| AgentSecret | 应用的Secret | a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 |

#### 步骤2：保存配置

点击"保存配置"按钮。

#### 步骤3：配置可信域名

在企业微信管理后台 → 应用管理 → 应用 → 自建应用 → 开发 → 企业微信授权登录，配置：

- **授权的网页域名**：https://yourdomain.com

### 功能使用

#### 通讯录同步

点击"同步通讯录"按钮，系统会自动同步：
- 部门列表
- 用户列表
- 组织架构

#### 消息推送

在"消息推送"Tab中：
1. 选择接收人（部门或用户）
2. 输入消息内容
3. 点击"发送"按钮

### 验证成功标志

✅ 可以正常同步通讯录
✅ 可以正常发送应用消息
✅ 成员可以正常接收消息

---

## 企业微信服务商配置

### 获取配置信息

#### 1. 登录企业微信服务商后台

访问：https://open.work.weixin.qq.com/

#### 2. 进入应用管理

路径：应用管理 → 网页应用 → 自建应用

#### 3. 获取配置信息

**服务商CorpId**：
- 我的企业 → 企业信息 → 企业ID

**SuiteId**：
- 通用开发参数 → SuiteId

**SuiteSecret**：
- 通用开发参数 → SuiteSecret → 查看
- 复制Secret

**SuiteTicket**：
- 系统会自动获取，无需手动配置

### 配置步骤

#### 步骤1：填写配置

在渠道管理页面 → 企业微信服务商 → 服务商配置，填写以下信息：

| 字段 | 说明 | 示例 |
|------|------|------|
| 服务商CorpId | 企业微信服务商的企业ID | ww1234567890abcdef |
| SuiteId | 应用的SuiteId | ww1234567890abcdef |
| SuiteSecret | 应用的Secret | a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6 |

#### 步骤2：保存配置

点击"保存配置"按钮。

#### 步骤3：配置回调URL

在服务商后台 → 应用管理 → 应用 → 开发 → 接收消息，配置：

- **URL**：https://yourdomain.com/api/wework-provider/callback

### 功能使用

#### 工资通知模板

1. 在"工资通知模板"Tab中点击"新建模板"
2. 填写模板名称和内容
3. 使用变量：`{{员工姓名}}`、`{{工资总额}}`等
4. 保存模板

#### 发送记录

在"发送记录"Tab中查看：
- 发送时间
- 接收人
- 发送状态
- 消息内容

### 验证成功标志

✅ 可以正常创建工资通知模板
✅ 可以正常发送工资通知
✅ 可以正常查看发送记录

---

## 常见问题

### 微信公众号

**Q: 服务器配置验证失败？**

A: 请检查：
1. 服务器URL是否正确（必须是HTTPS）
2. Token是否与微信公众平台配置一致
3. 服务器是否正常运行
4. 防火墙是否阻止了微信的请求

**Q: 消息收不到？**

A: 请检查：
1. 服务器配置是否启用
2. 消息加解密方式是否正确
3. EncodingAESKey是否正确
4. 服务器日志是否有错误

**Q: 菜单发布失败？**

A: 请检查：
1. AppID和AppSecret是否正确
2. 菜单结构是否符合规范（最多3个一级菜单，每个最多5个子菜单）
3. 菜单类型和参数是否正确

### 微信小程序

**Q: 获取用户信息失败？**

A: 请检查：
1. AppID和AppSecret是否正确
2. 服务器域名是否配置
3. 小程序是否已授权登录

### 企业微信

**Q: 通讯录同步失败？**

A: 请检查：
1. 企业ID、AgentId、AgentSecret是否正确
2. 应用是否有通讯录权限
3. 企业微信后台是否启用了通讯录API

**Q: 消息推送失败？**

A: 请检查：
1. 接收人是否存在
2. 消息内容是否符合规范
3. 应用是否有发送消息权限

### 企业微信服务商

**Q: 工资通知发送失败？**

A: 请检查：
1. 服务商CorpId、SuiteId、SuiteSecret是否正确
2. 回调URL是否正确配置
3. 授权的企业是否有权限

---

## 相关资源

- [微信公众平台文档](https://developers.weixin.qq.com/doc/offiaccount/OA_Web_Apps/Basic_Information/Overview.html)
- [微信小程序文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)
- [企业微信文档](https://developer.work.weixin.qq.com/document/)
- [企业微信服务商文档](https://developer.work.weixin.qq.com/document/path/90665)

---

## 技术支持

如有问题，请联系：
- 技术支持邮箱：support@example.com
- 问题反馈：https://github.com/yourrepo/issues