# 小程序一键接入

欢迎使用微信安全网关，下面将详细介绍微信小程序快速接入安全网关，使用安全网关守护业务数据及接口安全、抵御外部恶意流量以及提升业务访问质量的的操作步骤。整个接入会在 1-3 分钟内完成，无需修改代码、无需重新发版，且不影响业务线上运行。

另外，我们也配套上线了视频课程，你可以前往文档底部的视频课程学习这一部分。

# 一、接入步骤

# 1. 微信扫码登录安全网关控制台，同意安全网关服务协议并同意即完成开通。

# 2. 如第一次登录，在初始页面，下拉选择接入「安全网关」小程序，开始接入。

如未授权小程序给网关，则需要小程序管理员扫码授权；如果小程序已经授权其他网关，则无法重复接入；
安全网关默认将小程序体验版接入安全网关微信私有链路，完全不影响线上流量，仅用作小程序体验版测试使用，请放心接入；
如选择的小程序无体验版，请重新选择有体验版的小程序接入；
如选择的小程序未在微信公众平台配置 request 合法域名，则需前往「微信公众平台-开发-开发管理-开发设置-服务器域名-request合法域名」中配置；
如选择的小程序在「微信公众平台」配置的 request 合法域名个数超过20个，平台将默认取线上有请求的前10个域名；
如选择的小程序已绑定到其他空间的网关，请重新选择未绑定过网关的小程序接入；一个小程序只能绑定到一个网关上；

# 3. 接入后可用微信扫码体验版二维码，发起请求查看安全网关链路状态。

小程序一键接入成功后，小程序体验版的所有请求都将由安全网关的「微信私有链路」保护后转发至小程序服务端；
小程序一键接入成功后，将返回小程序体验版二维码，你可微信扫码查看小程序体验版接入网关后的状态情况，也可发起请求检验链路是否正常；
扫码小程序体验版发起请求后，请求相关数据可在网关的「监控视图」中查看；
点击「完成」继续体验更多安全网关能力（正式进入控制台，下次进入不再显示引导页）；

# 4. 小程序线上版本接入安全网关，点击「修改」进入接入域名详情页面，接入版本选择「全部版本」，选择所有小程序URL，提交即可快速线上接入。

接入版本列表及具体说明如下：

全部版本：包含小程序线上版、体验版、开发版 3 个版本；
体验版：仅小程序体验版请求接入安全网关；
开发版：仅小程序开发版请求接入安全网关；

另外，每个业务配置都有独立的接入开关，关闭后小程序所有版本请求都不接入安全网关，直接走原本的公网链路，不享受安全网关的安全防护及弱网优化等能力。

# 5. 小程序线上流量灰度接入安全网关，支持接口维度灰度接入。

小程序URL，微信安全网关已打通微信公众平台，自动拉取小程序对应的 request 合法域名；
你可按照业务情况，支持部分「小程序URL」接入安全网关；
支持同个域名下添加多个路径，路径为空时默认按照前缀匹配；
如需添加新的小程序域名，请先前往「微信公众平台- request 合法域名」添加，再返回对应「接入域名」中操作；
小程序URL个数支持配置20个（更高规格的版本，该限制会有提升，具体看计费文档的细项说明）

配置灰度接入时，需要注意以下几点：

不可配置相同路径的不同灰度比例，或者不同的用户组
不可配置嵌套形式的路径，比如同时配置 /a/b 和 /a

# 二、常见问题

# 1. 使用小程序一键接入安全网关后，是否还需要小程序发版？

答：不需要小程序发版，不需要修改小程序代码，小程序流量将按照你的配置接入安全网关，受安全网关微信私有链路保护和优化；

# 2. 如果接入的小程序流量大于安全网关套餐规格，超出的流量怎么处理？

答：超出的流量将走原业务公网链路，不再受安全网关微信私有链路保护和优化，建议升级安全网关套餐；安全网关不会阻塞/拦截丢弃正常的小程序流量。

# 3. 如果不想再使用安全网关，怎么操作？

答：安全网关支持小程序快速断开接入，快速断开后小程序流量将直接走原业务公网链路，流量不受阻塞；操作路径「接入层-接入域名-目标小程序-快速断开」，或者「接入层-接入域名-修改-小程序版本不接入-提交」；

# 4. 如何判断请求是否经过了网关链路？

答：网关链路的errmsg值为gateway.call:ok，另外在返回体根级会有callid，建议在小程序端记录并上报该callid，链路出现问题可以凭此callid反馈给安全网关团队精确定位。服务端会收到安全链路的特定header：

x-wx-call-id：链路请求ID，和前端响应的一致，可以通过其来联系前后端日志。反馈问题也首选这个。
x-wx-route-tag：接入域名标记，可以根据此判断不同的接入域名转发的流量，用来区别对待
x-wx-source：请求客户端，比如微信客户端是wx_client，开发者工具是wx_devtools
x-wx-appid：请求小程序，标记请求的小程序appid
x-envoy-expected-rq-timeout-ms：网关参数，响应超时时间，一般是15秒

为安全考虑，关于网关的其他 header 信息，请在接入后发现，如有疑问请联系我们 1v1 解答。（不同的小程序接入时可能会有专门的 header 内容）

根据自身安全要求，可以通过x-wx-appid、x-wx-route-tag来设立一个白名单，只接受来自白名单接入域名或白名单小程序的请求。

# 5. 为什么接入配置后，小程序对应的版本访问还是原生链路，没有走安全链路？

答：链路生效一般在1分钟之内，如果用户正在访问该小程序，则需要等待下一次启动打开才可以。如果开发者测试验证，则建议退出微信后台，重新进入再试，如果仍然不可以，则删除掉小程序然后重新加载尝试（删除掉小程序主要是清除缓存）

# 6. 为什么接入配置后，微信开发者工具没有走安全链路？

答：开发者工具对应的是「开发版」，需要保证接入配置到「开发版」上，配置之后仍然不可以则等待一分钟再试。一般清除缓存+重启开发者工具都可以搞定。基础库版本需要在3.1.5及以上，开发者工具版本需要在1.06.2310312及以上。

# 7. 为什么接入小程序后，经过安全网关的请求耗时明显增加了？（小程序端请求变慢了）

答：可能是以下2点原因：

a. 网关接入地域与小程序服务端部署地域存在跨域情况，导致因请求跨域而耗时增加；目前安全网关已上线选择「接入地域」能力，当前支持选择「上海」、「深圳」、「天津」3个地域，后续会支持更多；为避免远距离跨域而导致请求耗时延长，请就近选择接入网关地域。例如，小程序服务端部署在深圳，请选择深圳地域；小程序服务端部署在北京，请就近选择天津地域。

b. 业务请求带宽超出免费试用版本的带宽额度，目前免费试用版带宽额度为 1Mbps；你可前往「安全网关控制台-监控视图-套餐监控」中查看「超出套餐带宽请求量」视图情况，并调整下业务请求回包大小，以避免带宽超额；