开发者平台是集市生态的「应用市场 + 权限中心 + 部署台 + 小程序宿主」。developer、deploy、applet 原本是三套独立仓库,现合并为一个平台;合并期间仍是独立进程,通过 SM2 验签与短期票据互通。代码量:developer 约 9000 行 TypeScript,apps/deploy-api 约 1.9 万行,applet 约 6000 行 Node.js。这篇按登录、权限、部署、小程序展开。
登录与开发者身份
用集市账号走 OAuth:/oauth/start 跳授权,/oauth/callback 拿 code 换 token、取 userinfo,按 sub upsert 本地用户;令牌只用于换身份,不落库。
非开发者提交申请(用途、预期模块)后,管理员在 GET /api/admin/applications 看列表,用 POST /api/admin/applications/:id/review 审批。通过时要在同一事务内置 is_developer 并映射内置 developer 角色——只改状态不授角色,用户会看到「已通过」却建不了模块。花名只用于展示,不参与权限判断。
模块与 SM2 密钥
注册模块要填名称、slug、说明,提交后拿到一对 SM2 密钥,私钥只显示一次。slug 全局唯一,是总线里的模块标识。
平台只保存公钥,私钥交给模块。常规方案一旦平台被拖库,所有模块都能被伪造;只存公钥时拖库也伪造不了请求。SM2 验签只需要公钥,平台不需要知道私钥,也就不该持有。
轮换时新私钥一次性下发,旧公钥保留灰度期,期间两把都接受;立即废弃会让模块方滚动发布中的实例全部鉴权失败。
签名总线:四段 token 与三重时间
模块调平台统一带 x-model-Authorization(四段 base64url:slug、ts、nonce、sign,以点连接)和 x-model-query-time 两个头,例如 POST /api/open/modules/ping。待签名串同样四段、换行连接:slug\nts\nnonce\nqueryTime。server/src/middleware/module-auth.ts 拆 token 后做 SM2withSM3 验签,失败返回 401:
1 | // server/src/middleware/module-auth.ts |
时间校验有三层:
| 校验项 | 容差 | 拦截目标 |
|---|---|---|
ts(签名内) |
±5 分钟 | 重放数天前的旧请求 |
queryTime(独立头) |
±60 秒 | 短窗口内的缓存重放 |
nonce |
5 分钟去重缓存 | 同窗口内重复提交 |
queryTime 独立于签名,是让网关单独判断时效,所以容差比 ts 更严。nonce 用进程内 Map 记录已用值,写入前惰性清理,命中返回 401「nonce 已使用,疑似重放」。坑:Map 只在当前进程,多实例部署挡不住跨实例重放,要换 Redis。
模块反向调平台也带签名,平台用模块公钥验签,不依赖共享密钥。例如 POST /api/open/workbench/publish 注册工作台入口,GET /api/open/modules/:slug/apis 拉模块自述的接口清单。
权限模型
权限点集中在 PERMISSION_CATALOG(server/src/services/permissions.ts):developer.* 6 项(模块管理、密钥、文档、入口等),admin.* 9 项(用户、审批、角色、授权等)。角色和直授都引用目录里的 code,新增能力只加一条。
最终权限 = 角色权限(多角色取并集)± 直授(对单用户 allow / deny,deny 优先)。allow 是补一点,deny 是紧急刹车,刹车优先。
模块声明 required_permission;无权限时列表不出现(过滤,不置灰),直接访问详情返回 404,不暴露存在性。403 适合「知道资源但不能动」,404 适合「连存在都不该知道」,模块市场属于后者。管理台的用户、审批、模块、角色、直授、API 授权等操作各对应一个 admin.* 权限点,按钮背后必须有接口级判断。
部署台:项目与审批
developer 角色可自助建项目,自动成为 owner。成员分 owner / maintainer / member,还可授予可见模块范围 moduleScope。
项目与成员接口覆盖 GET/POST /api/projects、GET/POST /api/projects/:id/members、DELETE /api/projects/:id/members/:userId。
判定集中在 apps/deploy-api/src/services/project.ts:getProjectRole、canWriteProject、canReadProject、isProjectOwner、setProjectMemberScope、addModuleMember。模块范围要覆盖「列表、详情、部署、日志」四条路径,只过滤列表的话直接构造 URL 仍能看详情。
所有审批进单表 applications,用 type 区分业务,列为 (id, type, applicant_id, target_id, payload, status, approver_id, created_at);admin 发起免审并记 auto_approved_by_role。分表会把「我的待办」变成多表 UNION。状态变更写 audit_logs,部署台另有 access-log-query.ts 查访问日志(GET /api/audit-logs、GET /api/projects/:id/logs)。
部署队列、灰度与域名
点部署后进单进程队列,全局有并发上限,同一 module:env 同时只允许一个在跑。关键是入队去重和按模块加环境串行:
1 | // apps/deploy-api/src/services/deploy-worker.ts |
全局串行会互相阻塞,完全并发又会同时改同一套容器,所以按 module:env 串行。连点两次会产生两条相同部署,入队去重不能省。
取消用 cancelDeployment 经 AbortController 中断子进程;recoverStaleDeployments 在启动时把「卡在 running 但没有进程」的记录标失败。running 是内存态,进程被 kill 就丢,没有 stale 恢复,数据库会永久留着「部署中」。日志用 getDeploymentLogs 拉。
灰度发布不改域名:正式域名带指定 Header 走测试容器,不带则走正式版本,由 nginx 按 Header 路由。gray.ts 的 grayValuesNginxRegex() 把 headerValues 逐项经 escapeRegex 转义后用 | 连接;值里出现 . 或 | 会改变匹配语义,灰度范围失控。getGrayReleaseInfo(moduleName, prodUrl) 返回 headerName、recommendedValue、headerValues、versionHeaderName 与说明文案。
域名按项目维度管理(GET/POST /api/projects/:id/domains、DELETE .../:domainId),绑定后由部署流程写入反代配置。删除要先摘配置再删记录,否则「记录没了、配置还在」,请求继续打旧容器。环境变量、预览、执行记录分别走 env-config、preview、runs 接口。
脚本应用与对象存储
脚本应用要填根目录和命令,成员可手动触发。apps/deploy-api/src/services/script-apps.ts 的 validateWorkdir 要求根目录非空、以 / 开头、落在 allowedRoots 内,不满足就抛 ScriptError;命令拼接用 shellQuote 逐段转义。
normalizePath 必须是纯字符串处理,不能用 fs.realpath:路径不存在时 realpath 抛错,会把「合法但尚未创建」的目录判非法。范围判断要「等于根 或 以 根/ 开头」,只判前缀的话 /data-evil 会被 /data 放行。
对象存储按模块建 MinIO 桶、签发凭证,并支持同步历史数据:resolveModuleMinioCreds、ensureModuleBucket、syncHistoryDataToBucket、getObjectStorageStatus、listModuleBucketObjects,对应 /api/projects/:id/object-storage 及 /credentials、/objects、/sync、/sync/:jobId。同步要能续跑,几万条中断后从头开始既慢又会产生重复对象。项目数据可导出含清单的 zip(/api/projects/:id/data-export),导出前校验权限。
工作台入口、API 清单与小程序
模块注册工作台入口走 SM2 签名中转(server/src/routes/workbench-publish.ts):主站验签后落库,开发者平台不直接写主站库。模块自述接口后,平台汇总到文档页,也是授权审批的粒度——支持整组或单点 group.action;整模块授权在模块变多后必然过度授权。
小程序目前仍是独立服务(applet.ssemarket.cn),提供目录、版本审核、启动票据、设备订阅。合并后它是开发者平台的一个模块,相关能力收敛到本平台的权限与审批模型。迁移期间 App 依赖的契约不能变:
1 | POST /v1/launch-tickets 申请一次性票据(60s) |
票据只能消费一次,兑换用 Redis GETDEL 或数据库条件更新。更换会话存储时,mp_session 的名称、作用域与 HttpOnly 必须保持不变,否则已登录的小程序会全部掉线。
面试速答
- 密钥:平台只存 SM2 公钥,私钥一次性下发;轮换保留旧公钥灰度期。
- 签名:四段 token(slug / ts / nonce / queryTime),三重时间校验(±5 分钟、±60 秒、nonce 5 分钟去重)。
- 权限:权限点目录 + 角色并集 + 直授,deny 优先;模块无权限时列表不出现、详情 404。
- 部署队列:并发上限 + 同
module:env串行 + 入队去重 + 启动时清理僵尸记录。 - 灰度/脚本:nginx 按 Header 路由,值拼正则前转义;根目录白名单用纯字符串规范化。
- 小程序:一次性票据 60s,兑换
GETDEL;mp_session契约不能变。
→ 下一篇:API 平台:兼容与计费





