本文延续同一套 FastAPI、PostgreSQL 15、SQLAlchemy 异步 ORM 和 Vue 3 的个人运维原型。它有 Agent 辅助,未正式采用,也没有真实企业部署数据。文章只保留代码结构和失败路径,不公开 corpid、secret、Token、EncodingAESKey、真实回调地址或任何客户信息。文中出现的配置名用于说明职责,不代表可以跳过企业微信官方文档与真实环境验证。

不把“接企业微信”当成一个功能

登录、通知和回调经常在同一份配置里出现,但它们的风险并不相同。登录回答“当前用户是谁”;通知回答“一条业务消息怎样可靠地离开系统”;回调回答“如何确认收到的消息确实属于这个应用”。

如果把三者写成一个巨大的企业微信服务,最简单的一次接口变更也可能同时影响身份、任务重试和消息安全。因此原型先按链路拆分,再共享少量经过封装的配置与 HTTP 访问。每条链路都有自己的失败记录和测试边界。

这种拆分也便于公开复盘:可以讨论一次性 code、JWT 会话版本和签名比较,而不需要展示任何企业标识或网络地址。安全从写作阶段就开始,而不是发布前临时打码。

登录:一次性 code 只负责换取身份

企业微信 OAuth 登录的服务端流程,是接收前端带回的一次性 code,再由服务端调用接口换取 UserId。code 不应被当作用户身份长期保存,也不应在浏览器日志里传播。拿到平台身份后,还要在本地用户表中找到对应记录,并检查账号是否可用。

应用随后签发自己的 JWT,让企业微信 H5 和桌面后台使用同一套会话规则。JWT 的签名只能证明 token 没有按预期密钥被篡改,不能自动处理“用户刚被停用”或“角色已经变化”。因此原型在用户记录和 token 中都保留 token_version:

async def require_current_user(token: str, session: AsyncSession) -> User:
    claims = decode_application_jwt(token)
    user = await session.get(User, claims["sub"])
    if user is None or not user.is_active:
        raise Unauthorized()
    if claims["token_version"] != user.token_version:
        raise Unauthorized()
    return user

停用用户或发生需要旧会话失效的权限变化时,递增用户记录的版本,旧 token 就无法继续通过检查。这里的关键不是多一个字段,而是明确权限事实以数据库当前记录为准。新设备登录、角色变化和用户停用需要怎样影响已有会话,应写成明确策略,而不是期待 JWT 自己解决。

开发模式必须不能误入生产

本地联调有时无法完成完整 OAuth 流程,原型因此保留 WXWORK_DEV_MODE 作为开发辅助。但这个开关会改变身份来源,不能因为“部署时记得关掉”就算完成。启动逻辑需要在生产环境检测到它时直接拒绝运行:

if settings.environment == "production" and settings.WXWORK_DEV_MODE:
    raise RuntimeError("WXWORK_DEV_MODE is forbidden in production")

这个检查属于启动边界,而不是页面上的提示。还要检查测试是否覆盖了生产开启开关的失败分支,以及日志是否会打印敏感配置。开发便利可以保留,但必须让它无法静默改变生产身份验证。

Agent 生成类似分支时,我会特别审查默认值。最危险的不是明显写错的密钥,而是一个看似方便、在生产仍然生效的默认身份。

通知:沿用 outbox,不在事务里等外部接口

报修或巡检业务需要通知时,先在 notification_outbox 中写入任务,并与业务记录共享数据库事务。提交成功后由 FastAPI BackgroundTasks 做一次即时投递,定时任务再扫描尚未完成的记录作为兜底。

这条链路与上一篇文章的架构取舍一致:外部 HTTP 不参与业务事务,1、5、30 分钟以及 2、8 小时的退避用于降低连续失败造成的压力,行锁和 SKIP LOCKED 用于减少多个 worker 领取同一任务的机会。

业务事务提交
  ├─ 业务记录可见
  └─ outbox 记录可见
       ├─ BackgroundTasks:尽快尝试一次
       └─ 定时 drain:处理遗漏与失败重试

这里不能把“代码有重试分支”写成“企业微信通知已全部验证”。能够检查的是状态机、事务边界和模拟失败下的断言;真实接口限流、网络超时、平台返回变化和接收端表现,需要各自的真实环境证据。公开文章只声明实际跑过的检查,不把分支数量当作可靠性指标。

回调:先验证,再解密,再理解业务

回调处理的顺序是 URL 验证、签名检查、消息解密、结构与企业标识校验,最后才进入业务分发。任何一步失败都不能被“尽量解析”掩盖。否则攻击者构造的明文、错误应用的消息或结构缺字段的请求,都可能被业务层误当成有效事件。

原型使用 WXBizMsgCrypt 封装对应算法。签名比较采用 hmac.compare_digest,避免把普通相等比较用于安全相关签名:

expected_signature = sign_callback(canonical_fields)
if not hmac.compare_digest(received_signature, expected_signature):
    raise InvalidCallbackSignature()

message = cryptor.decrypt(encrypted_payload)
validate_message_structure(message)
validate_expected_enterprise(message.enterprise_id)

示例刻意没有提供任何真实参数。真正审查时还要确认原始请求体的处理方式是否符合官方协议、异常是否返回合适的非成功响应、日志是否避免记录完整密文或敏感字段,以及重复事件是否有幂等处理。

“解密成功”只说明消息通过了这一层处理,不代表业务操作一定应该执行。事件类型、操作者、目标记录和当前状态仍需逐项验证。

三条链路共享配置,但不共享模糊结论

企业标识、应用 secret、回调 Token 和 EncodingAESKey 应通过服务端配置注入,并限制日志输出。共用配置加载器可以减少重复,却不能让通知模块直接绕过回调校验,也不能让登录开发模式替代真实身份。

测试也应按链路组织。登录覆盖无效 code、停用用户和版本不一致;通知覆盖事务回滚、即时任务遗漏和退避;回调覆盖签名不符、解密失败、结构不完整和企业标识不匹配。模拟测试可以证明代码按预期处理这些输入,但不能声称覆盖平台的所有真实变化。

我在复盘中把“代码里存在”“本地模拟通过”“真实外部条件已验证”分成三种表述。这个区分对 Agent 辅助项目尤其重要,因为生成一段合理文本远比取得最后一种证据容易。

上线前仍然是一张未完成的清单

如果未来要把原型推进到正式环境,需要重新完成密钥管理、回调地址配置、HTTPS、平台权限、日志脱敏、重试验证和运维告警,并用真实测试企业或受控环境走通流程。任何一步没有证据,都应保留为待办,而不是沿用原型文章里的完成语气。

这次接入最有价值的产出,是把三个容易混杂的问题拆成了可以分别审查的链路:身份有版本,通知有持久化,回调有严格边界。下一篇关于看板的文章会换一个领域,但仍沿用同一条原则——先说明数据与代码能证明什么,再谈展示效果。