快速开始（商户 + 开发者）

对接 OAuth 前，商户与开发者各做一步；缺任何一步都会看到「域名未授权」。

商户侧（SaaS 开通）

1. 注册 / 登录 — 用户名密码或微信扫码（一个微信仅绑一个商户号）
2. 购买套餐 → 我的订单 复制订单号 → 联系管理员确认收款开通
3. 我的域名 — 添加业务域（如 appeal.example.com）并启用
4. 本页「域名授权检测」或 API 确认 authorized: true

开发者侧（改代码 + 开放平台）

1. 业务 OAuth URL：官方域名 → open.aikex.ink（路径参数不变）
2. redirect_uri 填业务站完整 HTTPS 回调（不是 open 站地址）
3. 微信/支付宝后台：网页授权域 / 回调域 → open.aikex.ink
4. 业务站 callback 用自己的 AppSecret 调官方 API 换 openid（open 不参与）

架构一句话：open 只校验白名单并中转跳转；C 端用户 openid 只存在业务站数据库。

商户中心

入口：/user/dashboard。用于管理白名单订阅，不是业务站用户系统。

账号与微信绑定

• 可在 账号设置 绑定微信，登录页扫码直达本商户号
• 一个微信只能绑定一个商户账号；绑到已有 wx 快捷号时会自动合并域名与订单
• 解绑后该微信扫码不再进入本账号；建议 wx 快捷号先设置用户名密码再解绑

商户中心看不到 OAuth 成功/拦截日志、全站其它商户数据、业务 C 端用户 openid。

购买套餐与订单开通

open 采用商户自助下单 + 管理员确认收款，非在线支付网关。

1. 登录 → 购买套餐 → 点击「创建订单」
2. 我的订单 复制订单号（trade_no）
3. 联系平台管理员确认收款（线下约定方式）
4. 管理员在后台开通后，订阅时长、域名配额、支持的 OAuth 类型自动生效
5. 进入「我的域名」添加业务站 host

订阅过期后 OAuth 会被拒绝（「商户订阅已过期」），续费并开通后请确认域名仍为「启用」。

域名管理

在 我的域名 维护 OAuth 白名单。

添加域名

规则要点

• 白名单匹配 redirect_uri 的 host，不匹配路径；同一 host 下多个 callback 路径只需加一条
• 通配 *.example.com 匹配子域，不匹配 example.com 本身
• 测试域与生产域须分别添加（各占配额）
• 「关闭」或删除后 OAuth 立即失效；订阅过期也无法启用
• 支持的 OAuth 类型由套餐决定（公众号 / 开放平台 / 支付宝 / 企业微信等）

风控说明

平台会定期探测业务站可用性与页面内容。站点不可访问、响应过慢或含违规关键词时，域名可能被自动封禁，OAuth 拒绝。封禁后须修复业务站并联系管理员解封。

三种角色与数据边界

open 站同时服务平台运营、购买中转服务的商户、以及商户业务站上的 C 端用户。对接前请先理解谁能看到什么。

平台管理员能看到什么？

• 能看：商户账号、商户域名、OAuth 中转日志（AppID、redirect_uri、域名、IP、时间）、拦截日志、商户订单
• 不能看：业务站 C 端用户的 openid、昵称、手机号 — open 只做 OAuth 跳转，不代换 token、不存终端用户身份

别人用自家公众号对接，我能看到他们的用户吗？

不能。商户使用自己的 AppID；用户授权后微信把 code 经 open 中转回业务站；业务站用自己的 AppSecret 调微信官方接口得到 openid。该请求不经过 open。

商户能看到什么？

仅自己的域名、订单、套餐；看不到其他商户数据，也看不到全站 OAuth 日志。

redirect_uri 规则（必读）

state 参数

业务站传入的 state（防 CSRF、携带 returnTo 等）授权完成后会原样回到业务 callback。业务站应校验 state 与发起时一致。

scope（微信公众号）

微信公众号 · 网页授权

微信内置浏览器 H5 登录。使用商户自己的服务号/订阅号 AppID。

代理 URL

https://open.aikex.ink/connect/oauth2/authorize?appid=APPID&redirect_uri=URL_ENCODE(业务回调)&response_type=code&scope=snsapi_userinfo&state=STATE#wechat_redirect

微信公众平台配置

设置与开发 → 功能设置 → 网页授权域名 → open.aikex.ink（不含 https://）

业务域不要填进微信后台，仅在 open 商户中心白名单。

微信开放平台 · 网站应用扫码

https://open.aikex.ink/connect/qrconnect?appid=APPID&redirect_uri=URL_ENCODE(业务回调)&response_type=code&scope=snsapi_login&state=STATE#wechat_redirect

开放平台 → 网站应用 → 授权回调域 → open.aikex.ink

支付宝开放平台

用户授权（auth_code）

https://open.aikex.ink/alipayoauth?app_id=APPID&redirect_uri=URL_ENCODE(业务回调)&scope=auth_user&state=STATE

回调经 /alipayreturn 中转，业务站收到 auth_code，再调支付宝 API 换 user_id。

第三方应用授权（app_auth_code）

https://open.aikex.ink/alipayappauth?app_id=APPID&redirect_uri=URL_ENCODE(业务回调)&state=STATE

授权回调地址域名 → open.aikex.ink

企业微信 · 网页授权

复用公众号 OAuth 代理路径，额外传 agentid：

https://open.aikex.ink/connect/oauth2/authorize?appid=CORPID&redirect_uri=URL_ENCODE(业务回调)&response_type=code&scope=snsapi_base&agentid=AGENTID&state=STATE#wechat_redirect

• appid = 企业 CorpID
• agentid = 应用 AgentId
• 企业微信管理后台 → 应用 → 网页授权域名 → open.aikex.ink

换用户信息在业务站调企业微信 API，open 不参与。

QQ 互联 · 网站应用（无限回调）

与微信同模式：业务站 redirect_uri 走白名单；QQ 后台只登记本站一个回调。使用商户自己的 QQ AppID。

代理 URL（QQ 用 blog 域名，与微信分离）

https://blog.aike.ink/oauth2.0/authorize?client_id=APPID&redirect_uri=URL_ENCODE(业务回调)&response_type=code&scope=get_user_info&state=STATE

别名：https://blog.aike.ink/qqoauth。底层仍是 open 中控白名单；微信/支付宝继续用 open.aikex.ink。

QQ 互联控制台（可保持不动）

• 网站地址 → https://blog.aike.ink
• 网站回调域 → https://blog.aike.ink/wp-admin/admin-ajax.php（本机已把该路径转到 open /return）

业务域只加进 open 商户中心白名单。若 WordPress 还要在同一路径接 QQ 登录，需改用独立 action 或另开回调路径，避免与中转冲突。

换 token 注意（必读）

QQ 换 access_token 时的 redirect_uri 必须与授权时发给 QQ 的一致，即：

https://blog.aike.ink/wp-admin/admin-ajax.php

不要填业务站 callback。业务站仍收到 ?code=&state=（state 为业务原值），再自行调 QQ API。

GET https://graph.qq.com/oauth2.0/token?grant_type=authorization_code&client_id=APPID&client_secret=APPKEY&code=CODE&redirect_uri=URL_ENCODE(https://blog.aike.ink/wp-admin/admin-ajax.php)

业务站处理 code（open 不参与）

授权成功后，微信/支付宝/QQ 302 到业务站 redirect_uri?code=...（支付宝为 auth_code）。业务站须用自己的 AppSecret / AppKey 调官方接口：

GET https://api.weixin.qq.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code

QQ 见上方 QQ 互联（换 token 的 redirect_uri 固定为本站 /return）。

返回的 openid / unionid 存入业务库，建立登录会话。

不要把 AppSecret / AppKey 配置在 open 站 — OAuth 对接不需要 Secret。

能力选型：OAuth / Token / 消息转发

多数商户对接登录只需 OAuth 代理。发模板消息、客服消息可能需要 Token 中控；接收关注/扫码事件需要消息转发。

域名检测 API

GET https://open.aikex.ink/api/check-domain?domain=appeal.aikex.ink

与 OAuth 拦截逻辑完全一致，可用于 CI / 上线前自检。

成功：

{"ok":true,"authorized":true,"domain":"appeal.aikex.ink","expiretime":"...","platforms":"wechat_mp,wechat_open,...","msg":"该域名已在白名单中且有效..."}

失败：

{"ok":true,"authorized":false,"domain":"unknown.example.com","msg":"该域名未授权。请注册购买套餐后在商户中心添加..."}

Access Token 中控

多站点共用 access_token，避免 refresh 互相覆盖。与 OAuth 用户登录无关；须在管理员后台添加 AppID/AppSecret 后使用。

微信：https://open.aikex.ink/token?appid=APPID&secret=SECRET
企业微信：https://open.aikex.ink/qytoken?corpid=CORPID&corpsecret=CORPSECRET

消息事件转发

由平台管理员在后台创建服务器组。公众号/企业微信服务器 URL 填：

https://open.aikex.ink/wxserver/id/{组ID}

组内配置各业务站接收 URL。XML 直传下游，open 不持久化用户消息。

标准接入流程

1. 注册商户 → 购买套餐 → 管理员开通 → 添加域名并启用
2. 本页或 API 检测域名 authorized: true
3. 业务代码：官方 OAuth 域名 → open.aikex.ink，参数不变
4. 微信/支付宝开放平台：回调域只填 open.aikex.ink
5. 业务站 callback 用 code 调官方 API 换 openid，写入业务库
6. 联调验收见 AI 对接教程 中的 testing 清单

排障速查

常见问题

业务域要填进微信公众平台吗？

不要。微信后台只填 open.aikex.ink；业务域仅在 open 商户中心白名单。

localhost 能测试吗？

不能。须 HTTPS 公网域且已加白名单。可用 test.xxx.com 等测试子域。

同一域名多个回调路径要加几次？

一次。白名单匹配 host，路径不限。

open 和 epay 什么关系？

完全独立。epay.aikex.ink 是易支付收单；open 是 OAuth 中转。

JS-SDK / 支付还要配业务域吗？

要。open 只解决 OAuth 授权回调域；其它能力仍按微信文档在业务域配置。

商户中心绑微信和业务 OAuth 有关系吗？

无直接关系。前者用于登录 open；后者用商户自己的公众号 AppID 服务 C 端用户。

完整 Agent 文档在哪里？

/docs/skill 安装 Skill，或下载 open-oauth-proxy.zip（含 reference / testing / examples）。

路径速查表