新增

QYWX_IP_WHITELIST_GUIDE.md

@@ -0,0 +1,88 @@
+# 企业微信IP白名单配置指南
+
+## 问题现象
+
+同步企业微信客户时报错：
+```
+errcode: 60020
+errmsg: not allow to access from your ip
+```
+
+## 问题原因
+
+企业微信API有IP白名单限制，只有在白名单中的IP才能调用API。
+
+## 解决方法
+
+### 1. 获取服务器IP地址
+
+在服务器上运行以下命令获取公网IP：
+
+```bash
+curl ifconfig.me
+```
+
+或者查看日志中的IP地址，例如：
+```
+from ip: 8.219.70.152
+```
+
+### 2. 配置企业微信IP白名单
+
+1. 登录企业微信管理后台：https://work.weixin.qq.com/
+2. 进入"应用管理"
+3. 选择你配置的应用（使用该应用的Secret）
+4. 找到"企业可信IP"设置
+5. 点击"配置"或"修改"
+6. 添加服务器的公网IP地址
+7. 保存配置
+
+### 3. 验证配置
+
+配置完成后，等待几分钟让配置生效，然后重新运行同步命令：
+
+```bash
+php think qywx:sync-customer --force
+```
+
+## 注意事项
+
+1. **IP地址格式**：
+   - 单个IP：`8.219.70.152`
+   - IP段：`8.219.70.0/24`
+
+2. **多个IP**：如果有多个服务器，需要添加所有服务器的IP
+
+3. **动态IP**：如果服务器IP会变化，建议：
+   - 使用固定IP的服务器
+   - 或配置IP段
+   - 或使用代理服务器
+
+4. **测试环境**：开发环境和生产环境可能有不同的IP，都需要添加
+
+## 常见问题
+
+### Q: 添加IP后还是报错？
+A: 等待5-10分钟让配置生效，清除缓存后重试：
+```bash
+php think clear
+php think qywx:sync-customer --force
+```
+
+### Q: 不知道服务器IP？
+A: 在服务器上运行：
+```bash
+curl ifconfig.me
+# 或
+curl ip.sb
+# 或
+curl ipinfo.io/ip
+```
+
+### Q: 本地开发如何测试？
+A: 将本地公网IP也添加到白名单，或使用内网穿透工具（如ngrok）
+
+## 相关文档
+
+- [企业微信API - IP白名单说明](https://developer.work.weixin.qq.com/document/path/90238)
+- [企业微信错误码查询](https://open.work.weixin.qq.com/devtool/query)