本页目录展开
  1. 登录与开发者身份
  2. 模块与 SM2 密钥
  3. 签名总线:四段 token 与三重时间
  4. 权限模型
  5. 部署台:项目与审批
  6. 部署队列、灰度与域名
  7. 脚本应用与对象存储
  8. 工作台入口、API 清单与小程序
  9. 面试速答

开发者平台是集市生态的「应用市场 + 权限中心 + 部署台 + 小程序宿主」。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
2
3
4
5
// server/src/middleware/module-auth.ts
const raw = String(req.headers[MODEL_AUTH_HEADER] || '').trim();
const queryTime = String(req.headers[QUERY_TIME_HEADER] || '').trim();
const v = verifyModelToken(raw, queryTime); // 四段拆解 + SM2withSM3 验签
if (!v.ok) return res.status(401).json({ code: 401, message: v.error });

时间校验有三层:

校验项 容差 拦截目标
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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// apps/deploy-api/src/services/deploy-worker.ts
export function enqueueDeployment(id: string) {
if (running.has(id) || queue.includes(id)) return; // 去重
queue.push(id);
pump();
}
function pump() {
while (running.size < MAX_CONCURRENT) {
const idx = queue.findIndex((id) => {
const dep = getDeployment(id);
return !dep || !activeModuleEnv.has(`${dep.moduleId}:${dep.env}`);
});
if (idx === -1) break;
const id = queue.splice(idx, 1)[0];
const dep = getDeployment(id);
if (dep) start(id, `${dep.moduleId}:${dep.env}`);
}
}

全局串行会互相阻塞,完全并发又会同时改同一套容器,所以按 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
2
3
4
POST /v1/launch-tickets       申请一次性票据(60s)
POST /v1/sessions/exchange 票据换 mp_session Cookie
GET /v1/sessions/me 当前会话
GET /v1/apps 小程序目录

票据只能消费一次,兑换用 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 平台:兼容与计费