多商户系统路由分组设计：如何把密钥从路由配置中安全迁走

上周接了一个多商户商城项目的维护，打开路由配置文件的时候，我愣了好几秒。route.php 里除了大量的路由分组，居然还躺着一堆商户密钥，支付回调验签的 key、开放平台的 secret，甚至有的商户数据库密码都写在注释旁边。那个瞬间，我先想到的不是代码风格问题，而是这事必须处理，否则早晚出事。今天这篇就围绕这个场景聊聊：多商户系统的路由分组到底该怎么设计，密钥为什么会跑到路由配置里，以及怎么用稳妥的方式把密钥迁走。如果你也在维护带商户功能的后台，或者正在从单商户往多商户改造，这篇应该能帮你少踩几个坑。

1. 路由分组：多商户项目的“交通枢纽”

1.1 多商户架构下的路由分组为什么绕不开

单商户系统里所有接口面对同一类用户，路由简单直接，登录、订单、商品各管各的。但多商户系统完全不一样，同一套代码要服务平台管理员、商户管理员、商户店员、C端消费者，多角色之间还要做严格的资源隔离。路由分组就是这套隔离机制的第一道闸口。它把一组请求按照前缀、域名或中间件圈起来，让它们统一走同一套规则，比如都要登录、都要校验商户状态、都要带上当前商户上下文。我用一个小区门禁做类比：小区里各家有各家的门锁，但单元门是公共通道；路由分组就相当于单元门，先确认你有资格进入这个单元，后面才放行到具体房间。没有这个设计，多商户项目就像整栋楼只有一个大平层，谁串谁家都分不清。

在实际项目里，路由分组还能解决一个很实际的问题：可读性和可维护性。几百条接口全部平铺在一个文件里，改一个中间件都可能误伤其他接口；按分组拆开后，平台接口、商户接口、开放接口各自独立，团队协作时也不容易冲突。更重要的是，分组的边界往往就是权限的边界。商户A的请求如果进了商户B的分组，中间件立刻就能识破并拒绝。所以多商户项目的路由设计，从来不只是路径好不好看的问题，而是安全模型的第一层地基。

1.2 一个典型的路由分组长什么样

以 Laravel 为例，这是很多 PHP 多商户项目的选择。一个常规的商户端路由分组常写成这样：

php复制Route::prefix('merchant/{merchant_id}')
    ->middleware(['auth:merchant', 'load.merchant'])
    ->group(function () {
        Route::get('orders', [OrderController::class, 'index']);
        Route::post('refunds', [RefundController::class, 'store']);
    });

前缀 merchant/{merchant_id} 表示商户端接口都挂在 /merchant/xxx 下面，后面的 orders、refunds 会拼接成 /merchant/123/orders。middleware 数组里的 load.merchant 是自定义中间件，用来从数据库加载商户信息，并把当前商户实例注入容器，后续控制器和 Service 都能拿到。

如果你用的是 Node.js，Express 里的等价写法是：

javascript复制router.use('/merchant/:merchantId', loadMerchant, authMerchant);
router.get('/merchant/:merchantId/orders', OrderController.index);

核心思路一致：先通过 URI 参数把请求绑定到某个商户，再经过身份认证和商户加载中间件，最后才进业务逻辑。所谓“路由分组 + 中间件”，就是多商户项目里最基础也是最关键的组合拳。

1.3 路由分组与密钥的关系

中间件要做的事往往不止身份认证，还涉及签名校验、数据解密、第三方接口调用，而这些动作几乎都要用到商户密钥。比如服务商模式接入微信支付时，支付回调通知需要先解密报文，退款结果通知要验签；再比如商户调用物流查询接口，要在 header 里带上 appkey。这些密钥按商户不同而不同，属于“商户上下文”的一部分。

于是问题就出现了：如果当初设计时没把密钥归入商户上下文的加载逻辑，而是随手写在路由文件里，路由分组就成了藏密钥的重灾区。我见过很离谱的写法，路由文件顶部定义了一堆 define('MERCHANT_SECRET', 'xxx')，然后各分组中间件直接用这个常量，导致所有商户公用同一个密钥。真出事的时候连隔离都做不到，一个商户秘钥泄露，全平台都跟着暴露。所以讨论路由分组，必须把密钥管理一起拉进设计里，否则分组做得再漂亮，安全上也是漏的。

2. 藏在路由配置文件里的“密钥”是怎么来的

2.1 开发时的“快”与后来的“债”

大部分密钥出现在路由配置里，都不是架构师故意为之，而是被业务逼出来的。举个例子，接入多商户支付时，运营后台需要给每个商户配置独立商户号和 API 密钥，开发在联调阶段为了快速看到效果，直接在路由回调里写：

php复制$secret = 'a9f7c6d3e5b2...';
$sign = md5($secret . $request->input('order_no'));

测试没问题，代码复制到正式项目，这个 $secret 就成了路由文件里的“合法居民”。后面接手的同事看到路由文件里都是 $secret，也会以为这里的密钥就该这么放，于是继续往里加。这种快捷方式就像装修时图省事把电线埋在墙里却不留检修口，短期跑得很欢，后面出问题只能拆墙。

很多项目是因为“服务商模式接入多商户”而开始引入商户系统的。服务商模式下，平台代商户发起支付、代商户处理回调，每个商户都有一套自己的商户号和密钥。由于服务商模式的核心能力是动态读取商户配置，早期实现图省事直接把它们放进了路由文件里。结果商户数量一多，route.php 动辄上千行，密钥穿插在路由规则中间，肉眼几乎无法扫描，随便一搜就能看到一堆私钥和密码。

2.2 路由文件里常见的那几类密钥

支付密钥是最常见的。很多项目把 apiclient_key.pem 内容直接贴在路由文件的注释块里，或者把 APIv3 key 写成一个字符串常量。开放平台 AppSecret 也经常出现在路由代码中，因为开发者需要在这里请求第三方接口换取 access_token，一复制就留下了。签名盐则更隐蔽，它往往藏在一些自己写的加密辅助函数旁边，表面上不是密钥，但一旦泄露，伪造签名、越权访问都可能发生。

2.3 为什么说这是定时炸弹

密钥在路由配置里主要有三方面问题。

第一，泄露面太大。路由配置文件通常要交给前端联调、上传到 Git 仓库、同步到多个环境，只要一个环节泄出去，所有商户的密钥都跟着见光。我之前见过一个项目，因为 route.php 被误推到公开仓库，不到半天就被扫描工具发现，下游商户的支付密钥全部需要重置，损失非常大。第二，权限模型被打破。多商户系统里，不同商户应该持有不同密钥，如果路由文件里写了一个全局密钥，等于所有商户共用一把钥匙，你甚至没法判断是哪个商户在调用。第三，运维困难。商户续约、解约、密钥轮换时，你得改代码重新上线，而不是在后台点一下就能更新；发布过程中一旦校验不过，线上支付、回调直接受影响。

把这些风险放在一起看，你就知道路由文件里不能出现任何密钥字面量，这不是洁癖，而是底线。

3. 把密钥从路由配置里挪出去的正确姿势

3.1 先分清哪些该进配置，哪些该进数据库

很多新手会问：不放在路由文件里，那就都放到 .env 里呗？其实不对。要分两类：平台级密钥和商户级密钥。

平台级密钥是系统本身使用的，比如短信服务商的 AppKey、对象存储的密钥，全项目共用一份，放在环境变量或配置中心，和具体商户无关。商户级密钥则每个商户都不一样，而且商户数量是动态的，今天开通一个、明天关闭一个，放到 .env 里根本没发维护。正确做法是进数据库。建一张 merchant_credentials 表，以 merchant_id + channel 作为唯一索引，存每个商户在不同渠道的密钥，后台可以随时增删改查，代码里也可以按需读取。

判断标准很简单：如果这个密钥在部署时是固定的，就用配置；如果它会跟着业务数据动态变化，就进数据库。商户的支付密钥显然属于后者，它应该和商户信息一样，是业务数据的一部分。

3.2 密钥存储的加密设计

密钥进数据库不意味着可以明文存。商户密钥需要拿原文去调第三方接口，所以不能用哈希，必须使用可逆加密。常用的做法是使用 AES-256-GCM，应用内置一个根密钥（放在 .env 或 KMS 里），数据库里保存密文，需要使用时先解密再注入内存。

Laravel 里可以直接用 Crypt facade：

php复制$encrypted = Crypt::encryptString($merchantSecret);
$secret = Crypt::decryptString($encrypted);

如果项目规模再大一点，根密钥不要直接放在应用代码里，而是放到云厂商的 KMS 或开源 Vault 中，应用启动时拉一次根密钥到内存，之后用内存里的根密钥解密商户密钥。这样做的好处是：即使数据库被拖库，攻击者拿到的也是一堆密文，没有根密钥根本解不开。在实际操作中，我还建议把解密操作集中到一个服务类里，不要在多个控制器里各自 decryptString，不然以后换加密算法时你会哭。

3.3 让中间件自动加载商户密钥

密钥清理的目标，是让业务代码里不再出现任何密钥字面量。实现方式是把“根据当前路由参数加载商户密钥”这个过程收敛到中间件里。以 Laravel 为例，自定义一个 LoadMerchantCredentials 中间件：

php复制public function handle($request, Closure $next)
{
    $merchantId = $request->route('merchant_id');
    $credentials = app(MerchantCredentialService::class)
        ->getByMerchant($merchantId);

    app()->instance('merchant_credentials', $credentials);
    return $next($request);
}

路由分组里挂上这个中间件后，控制器和 Service 都可以通过 app('merchant_credentials') 拿到当前商户的密钥。密钥读取逻辑最好加一层缓存：

php复制public function getByMerchant($merchantId)
{
    return Cache::remember(
        "merchant_credential:{$merchantId}:all",
        300,
        function () use ($merchantId) {
            return $this->queryCredentials($merchantId);
        }
    );
}

路由文件里再也看不到 secret 字样，密钥的所有权归业务层，而不是路由规则。这个改动做完，每次新增商户密钥或轮换密钥时，只需要改数据库记录，不碰代码、不发布版本。

4. 实操记录：一次多商户路由配置的密钥清理

4.1 盘点现状

这个环节别急着动手，先把家底摸清楚。我在处理那个商城项目时，先在终端执行：

bash复制grep -rniE 'secret|app_secret|private_key|password|token' routes/

把 route 目录里所有疑似密钥的地方列出来，然后逐个判断：是真实密钥还是测试占位符，是只在本文件用还是被多处引用，是否已经推到远端仓库。结果让我很惊讶，光 route 文件里能找到的“真实密钥”就有十余处，支付私钥、回调 salt、短信签名都混在里面。

这里要特别提醒，排查时不要只搜常见关键词，还要搜 sk-、rsa、BEGIN 这类特征串，以及项目自定义的前缀。如果项目量级不小，也可以配合扫描工具，比如 trufflehog 可以扫 Git 历史，git-secrets 可以阻止新密钥进入提交，先把问题确认清楚再动手。

4.2 迁移密钥到数据表

先建表迁移文件：

php复制Schema::create('merchant_credentials', function (Blueprint $table) {
    $table->id();
    $table->unsignedBigInteger('merchant_id');
    $table->string('channel', 50);
    $table->text('encrypted_secret');
    $table->timestamps();
    $table->unique(['merchant_id', 'channel']);
});

然后用脚本把旧路由文件里散落的密钥逐一读出来，用 Crypt::encryptString 加密后写入 encrypted_secret 字段。写完之后必须人工对账，挑几个商户的明文、密文做解密验证，确保没有弄混。我那次就发现有两个商户的密钥在路由文件里写反了，如果没有对账直接上线，线上支付回调只有一半商户能成功。

4.3 改造路由分组与中间件

迁移完成后，把路由文件里的密钥定义全部删掉，再调整分组。改造后的 route 文件看起来是这样：

php复制Route::prefix('merchant/{merchant_id}')
    ->middleware(['auth:merchant', 'merchant.credentials'])
    ->group(function () {
        Route::get('orders', [OrderController::class, 'index']);
        Route::post('refunds', [RefundController::class, 'store']);
    });

中间件注册到 app/Http/Kernel.php 的 $routeMiddleware 里。改造完成后，跑一遍回归用例：支付回调、退款通知、商户登录、订单列表。重点看回调签名是否校验通过、控制器里通过服务类取的密钥是否正确。要注意，支付回调这种外部通知路由往往没有 merchant_id 参数，它可能带的是商户号或渠道编号，中间件里需要改成从请求体或签名参数中解析商户身份，不能只依赖路由参数。

4.4 清理仓库历史与轮换密钥

代码文件里删掉密钥并不等于安全，因为 Git 历史里还留着。需要把历史中的文件内容彻底抹掉。我推荐用 git filter-repo 清理：

bash复制git filter-repo --path routes/ --invert-paths --force

这条命令会改写历史，需要团队所有成员重新克隆仓库。如果仓库没有用 filter-repo 的习惯，也可以使用 BFG，但要在正式执行前做好全量备份，并且通知所有人停止提交，避免新提交把旧提交带回远端。清理完之后，所有涉及泄露的密钥都要在第三方平台重新生成一遍，比如微信支付商户平台重置 API 密钥、支付宝开放平台重新上传应用私钥。要通知下游商户更新，并同步改掉数据库里的密文。

5. 排查实录：路由分组和密钥有关的典型坑

5.1 路由分组正确却始终匹配不上

有时候改动路由分组后，接口会突然 404。我遇到过最常见的原因是应用还缓存着旧的路由表。Laravel 里跑过 php artisan route:cache 之后，修改路由文件不会自动生效，必须先 php artisan route:clear。

其次是分组前缀冲突：你定义了 /merchant/{merchant_id}，又定义了 /merchant/{merchant_id}/orders，看起来没问题，但如果有一个路由写成了 /merchant/setting，而且它在明星路由之前加载，setting 就会被当作 merchant_id 捕获。这种问题在路由缓存开启后尤其隐蔽，很难一眼看出来。排查顺序建议是：先 php artisan route:list 看实际注册的路由是否包含你的规则，再对比中间件是否把请求挡了，最后再看有没有路由前置冲突。

5.2 中间件里拿不到商户密钥

另一个典型问题是：中间件已经挂在路由分组上，但在 handle 方法里调用 $request->route('merchant_id') 返回 null。这里面有个细节，Laravel 的路由参数在路由中间件里可以拿到，但如果你把它注册成了全局中间件，route() 可能为空。另一个原因是路由参数名字和正则不对应，比如你在分组里写的是 {merchant}，中间件里却取的 merchant_id。

解决办法是统一命名，或者在中间件里用：

php复制$merchantId = $request->route()?->parameter('merchant');

并做好兜底。密钥查询时还要注意并发问题，如果从数据库解密很慢，可以加一层 Redis 缓存，用商户 ID 加渠道做键，比如 merchant_credential:{merchantId}:wechat_pay，更新时主动删键，不要等过期时间自己刷新。

5.3 配置更新后路由状态切换失败

多商户系统里，经常有人问我：后台改了某个商户的密钥，为什么接口还是用旧密钥？这大概率是缓存没更新。商户密钥被中间件读入缓存后，如果后台直接更新数据库，缓存里还是老的。更隐蔽的是，很多人习惯在保存密钥后顺手跑一遍 php artisan config:cache，但如果你把商户密钥放在了 .env 里，修改环境变量后没有重新执行 config:cache，新值同样不会生效。这里说的“路由状态切换失败”，本质上就是配置与实际运行态不一致。

设计时应该把缓存操作封装在密钥服务里，更新密钥时先写库，再主动清理该商户的缓存键，这样下次请求自然会重新加载。缓存过期时间也不建议设太长，商户密钥这类数据优先保证一致性，而不是性能。

5.4 密钥泄露后的应急处理清单

如果真的发现密钥已经泄露，不要慌，按下面这个顺序操作能少走弯路：

1. 在第三方平台立即吊销泄露的密钥，重新生成。比如微信支付和支付宝后台都支持重置密钥。
2. 全代码仓库搜索硬编码密钥，包括历史提交，确认泄露范围。
3. 清理 Git 历史并强制推送，通知所有协作者重新克隆仓库。
4. 检查线上日志、错误上报平台里有没有打印过该密钥的明文。
5. 在 CI 流程里加入密钥扫描工具，比如 git-secrets、trufflehog，发现匹配就构建失败。
6. 对受影响商户执行密钥轮换，并保留一段时间的旧密钥灰度期，避免在途请求验签失败。

这六步尽量在半小时内完成第一轮动作，先止血，再复盘原因。很多团队在泄露发生后才想到补 CI，其实扫描工具应该是每个多商户项目的基础设施，越早接入越好。

这个项目最后我并没有只做清理就完事，而是把路由配置文件约定成了“不允许出现密钥字面量”的规范，并让团队成员在 Code Review 时用搜索命令把关。说实话，处理这种事不难，难的是让所有人都养成条件反射：审查路由文件时先敲一遍密钥搜索，看到新加入的敏感字符串就像收到报警器一样敏感。路由分组应该只定义规则，密钥应该由配置中心、密钥服务或加密数据库来管。如果你现在维护的也是多商户项目，不妨今天就去搜一遍 routes 和 controller 目录，大概率会有意外收获。与其等出事再救火，不如现在就动手。