使用说明

1. 产品概览

微信开放平台的「授权回调域」只能填写一个域名。当你有多个业务站点（例如 wx.is3.cn、www.example.com）都需要微信扫码登录时， 每个站点单独申请网站应用既麻烦，也无法共用用户体系。

本网关把微信 OAuth 流程收敛到一个固定域名上：业务站点只负责跳转和换票， 微信只认识网关这一个回调域，用户资料则由业务后端凭密钥安全获取。

2. 微信平台准备

1. 登录 微信开放平台（open.weixin.qq.com），进入「管理中心 → 网站应用」。
2. 创建或打开一个已通过审核的网站应用，记录 AppID 与 AppSecret。
3. 在「授权回调域」中填写网关域名，例如 login.fps5.cn。
4. 确认该网站应用已绑定开放平台账号，否则可能拿不到 unionid。

3. 部署网关

3.1 环境要求

3.2 上传与伪静态

把项目上传到服务器，将网站运行目录设置为 public。Nginx 伪静态参考：

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Apache 环境已自带 public/.htaccess，确认 mod_rewrite 已开启即可。 首次部署后请给 database/ 与 runtime/ 写权限。

4. 初始化与系统设置

1. 浏览器访问 https://login.fps5.cn/admin/init，创建管理员账号与密码。
2. 使用管理员账号登录 https://login.fps5.cn/admin。
3. 进入「系统设置」，填写微信 AppID、AppSecret。
4. 填写「网关地址」，例如 https://login.fps5.cn，保存后所有跳转都会使用该地址。
5. 设置 ticket 有效期（默认 300 秒，建议 120–600 秒）。
6. 生产环境务必关闭模拟模式，保存设置。

5. 创建接入项目

普通用户：微信扫码登录后进入「用户后台 → 我的项目 → 申请项目」，填写项目名称、允许域名、默认回调地址并提交，等待管理员审核。

管理员：可进入「管理员后台 → 项目管理」直接新增项目，或对用户提交的项目执行「通过 / 拒绝 / 停用 / 删除」。

一个业务站点对应一个项目，主要字段如下：

保存后系统会生成一对凭证：

6. 业务站接入

业务站只需要两个动作：把用户送到网关，以及在回调里用 ticket 换取用户资料。

6.1 第一步：跳转发起授权

业务站生成随机 state 并保存在 Session，然后 302 到网关：

// 生成并保存 state，防止 CSRF
session_start();
$state = bin2hex(random_bytes(16));
$_SESSION['wx_state'] = $state;

$query = http_build_query([
    'client_id'    => 'ak_你的client_id',
    'redirect_url' => 'https://wx.is3.cn/callback.php',
    'state'        => $state,
]);

header('Location: https://login.fps5.cn/oauth/authorize?' . $query);
exit;

6.2 第二步：回调换取用户

微信授权完成后，浏览器会回到你的 redirect_url，并携带 code（一次性 ticket）和 state。 请先校验 state，再由后端调用用户信息接口：

$state = $_GET['state'] ?? '';
if (empty($_SESSION['wx_state']) || !hash_equals($_SESSION['wx_state'], $state)) {
    exit('state 校验失败，请重新登录');
}
unset($_SESSION['wx_state']);

$ch = curl_init('https://login.fps5.cn/api/user/info');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        'client_id'     => 'ak_你的client_id',
        'client_secret' => 'sk_你的client_secret',
        'code'          => $_GET['code'] ?? '',
    ]),
]);
$json = json_decode(curl_exec($ch), true);
curl_close($ch);

if (($json['code'] ?? 0) !== 200) {
    exit('登录失败：' . ($json['msg'] ?? '未知错误'));
}

// 建议用 unionid 作为跨站点统一用户标识
$_SESSION['openid']  = $json['data']['openid'];
$_SESSION['unionid'] = $json['data']['unionid'];
$_SESSION['user']    = $json['data'];

header('Location: /index.php');
exit;

6.3 用 unionid 识别同一个人

同一个微信开放平台账号下，不同网站应用返回的 openid 不同，但 unionid 一致。 如果多个业务站需要共享账号体系，请以 unionid 作为主键； 仅单站使用时，使用 openid 即可。

7. 网关用户体系

除了给业务站提供 OAuth 中转，网关自身也内置了微信扫码注册 / 登录： 用户访问 /user/login 扫码，首次自动创建账号，之后直接登录。

• 用户身份以 openid 为唯一键，重复扫码只更新资料，不会重复建号。
• 用户数据保存在 gw_users 表，可通过 status 字段停用账号。
• 用户登录与业务站授权互不影响：用户登录态保存在网关 Session，业务站仍通过 ticket 获取资料。
• 模拟模式下，用户登录会直接以模拟用户进入用户中心，便于本地验证页面。

8. 上线检查清单

• 网关域名已启用 HTTPS，证书有效。
• 微信开放平台「授权回调域」= 网关域名（不带协议与路径）。
• 后台已填写 AppID / AppSecret，且 模拟模式已关闭。
• 网关地址与真实访问地址完全一致（协议、域名均一致）。
• 每个业务项目都配置了明确的允许域名，未留空。
• client_secret 只存在于业务后端，未出现在前端或仓库中。
• 业务回调已校验 state，并在失败时给出重新登录入口。
• database/ 已纳入备份，SQLite 文件不会随发布被覆盖。
• 已用真实微信完整走通一次：扫码 → 回调 → 换取用户 → 建立会话。

9. 常见问题