142 KiB
统一身份(Hub)对接与用户同步
本文是 Hub 对接的配置文档:开关怎么开、每个配置项管什么、登录什么时候问 Hub、定时同步和「立即同步」分别做什么、哪些本地数据会被改、出问题先看哪里。
对端的接口口径见两份文档(本文只写本系统这边的实现与配置):登录、免登与组织人员
同步看《dsh-hub 统一门户 第三方系统对接指南》(仓库根目录 third-party-integration.md),
角色 / 权限码 / 数据范围看《Hub 权限接口交互文档》(permission-integration.md,实现见 §9)。
1. 能开哪几件事
| 能力 | 打开方式 | 说明 |
|---|---|---|
| 统一门户免登 | OA_HUB_APP_CODE + OA_HUB_INTEGRATION_KEY(默认已开 OA_HUB_SSO_ENABLED=true) |
用户在 Hub 门户点本系统卡片,带 ticket 落到 /sso,本系统后端拿应用密钥换身份(见 5.2) |
| 只允许免登 | OA_HUB_LOGIN_MODE=sso |
本系统不再收账号密码,登录页只留「前往统一门户」,注册/找回密码一律没有(对接指南 1.4) |
| 登录校验走 Hub | OA_HUB_ENABLED=true + OA_HUB_LOGIN_MODE=hub/hybrid |
账号密码由 Hub 判定,本地口令退居第二道 |
| 定时全量同步 | 系统设置 →「同步定时任务」里打开「允许定时同步」(默认开),排期同页可配 | 按排期拉全量组织与人员,默认每天凌晨 1 点;也可以每周/每月挑几天,或者按间隔跑(见 7) |
| 增量同步 | OA_HUB_SYNC_CHANGES_ENABLED=true(默认开) |
按游标轮询变更流水,几十秒内把人与部门的改动落到本地,排期那趟全量退成每日校对(见 8.1) |
| 一键实时同步 | 人员管理页 / 系统设置页的「立即同步」按钮 | 走同一条同步逻辑,用于特殊情况实时补数据 |
| 统一身份权限 | OA_HUB_PERM_ENABLED=true(默认关) |
角色、权限码与数据范围向 Hub 要口径;shadow 只对照、enforce 才参与判定(见 §9) |
| 企业微信消息推送 | 「消息通知」里建一个 hub_wecom 渠道(要 OA_HUB_BASE_URL + OA_HUB_INTEGRATION_KEY) |
待办 / 催办 / 办结这些提醒交给 Hub 代发成企业微信应用消息,卡片点开回到本系统那张单;本系统不持有企微密钥(见 §15) |
| 本地会话空闲超时 | OA_SESSION_IDLE_MINUTES=120(默认 0 = 不启用) |
Hub 登出不会回收本系统的会话,这一段只能自己管:空闲到点就要求重新登录(见 5.3) |
OA_HUB_ENABLED 是总闸,关掉以后登录、同步、页面入口全部回到接入前的样子。
上面这些开关都能在系统设置 → 统一身份认证配置里改,保存即生效,见 §3;下文的 环境变量是它们的默认值与兜底。
Hub 要调的接口路径一个都没写死在代码里:登录这一层十条(验证码、登录、校验 token、
当前用户、全量目录、变更流水、免登票据校验、可见应用列表、发起免登跳转、企业微信消息推送)在 config.toml
的 [hub.api],权限那一层再加九条(me/roles、me/permissions、me/data-scope、
directory/scoped 与五条 admin/*)在 [hub.perm.api]。Hub 换前缀、挂网关反向代理、
改版换路径,改配置就行,见 §4 的两张「接口路径」表与 §3。
2. 最小可用配置
出厂值写在 backend/config.toml 的 [hub] / [hub.api] / [hub.sync](仓库里那份只写
跟默认值不同的项和几个常用开关,全量清单与逐项中文注释在模板 config.toml.example),
也可以走环境变量或容器 -e,环境变量优先级更高:
[hub]
enabled = true
base_url = "https://hub.example.com"
# 拉全量组织人员的长期密钥(找 Hub 管理员领):目录接口只认它
directory_key = "<Hub 下发的目录密钥>"
# 可选:老的 Bearer token 口径,二选一,配了目录密钥就不用配
# service_token = "<Hub 下发的长期 token>"
# service_account = "svc_oa"
# service_password = "****"
# 免登两件套(对接指南第 3、4 节):Hub 管理员注册应用时给的应用编码 + 应用密钥明文
app_code = "oa"
integration_key = "<Hub 注册/轮换应用时那一次回显的密钥>"
# 配这两项之前先让 Hub 管理员把本系统注册成应用并把落地地址登记好:
# launch_url / redirect_uris = https://<本系统>/api/v1/auth/sso/callback(或别名 /sso/hub,
# 只想让票据走前端落地页就填 /sso),再勾上「可访问角色」,详见 5.2.1
# 可选:统一门户首页,留空就用上面的 base_url
# portal_url = "https://hub.example.com"
# 可选:接口路径不是写死的,Hub 换前缀 / 挂网关时改这里(默认就是文档口径)
[hub.api]
captcha = "/auth/captcha"
login = "/auth/login"
verify_token = "/api/v1/auth/token/verify"
me = "/api/v1/auth/me"
directory = "/api/v1/auth/directory"
directory_changes = "/api/v1/auth/directory/changes"
ticket_verify = "/api/v1/auth/tickets/verify"
apps = "/api/v1/auth/apps"
launch = "/api/v1/auth/apps/{code}/launch"
notify_wecom = "/api/v1/auth/notify/wecom/messages" # 企业微信推送(对接文档 9.6,见 §15)
[hub.sync]
enabled = true
# 可选:角色 / 权限码 / 数据范围向 Hub 要口径(权限文档第 3~8 节),默认关闭
# 全部子项与逐条注释见 config.toml.example 的 [hub.perm] / [hub.perm.api]
[hub.perm]
enabled = false
mode = "shadow" # shadow = 只对照;enforce = 以统一身份为准
同一份内容用环境变量写也行(名字见 §4 的对照表),只在容器编排里注入密钥时更常用:
OA_HUB_ENABLED=true
OA_HUB_BASE_URL=https://hub.example.com
# 拉全量组织人员的长期密钥(目录接口只认它)
OA_HUB_DIRECTORY_KEY=<Hub 下发的目录密钥>
# 免登两件套(应用密钥明文只在 Hub 注册/轮换那一次回显,别提交进代码仓库)
OA_HUB_APP_CODE=oa
OA_HUB_INTEGRATION_KEY=<Hub 下发的免登应用密钥>
# 可选:老的 Bearer token 口径,配了上面那项就不用配
# OA_HUB_SERVICE_TOKEN=<Hub 下发的长期 token>
# 或者:OA_HUB_SERVICE_ACCOUNT=svc_oa
# OA_HUB_SERVICE_PASSWORD=****
# 可选:角色 / 权限码 / 数据范围向 Hub 要口径(见 §9),默认全关
# OA_HUB_PERM_ENABLED=true
# OA_HUB_PERM_MODE=enforce
# OA_HUB_PERM_APPLICATION_ID=oa
# 可选:本地会话空闲多久要求重新登录(分钟,0 = 不启用,见 5.3)
# OA_SESSION_IDLE_MINUTES=120
拉全量组织人员只需要一把密钥:目录接口 GET /api/v1/auth/directory 用长期密钥
认服务端调用,本系统把它放在配置项「目录密钥」([hub] directory_key /
OA_HUB_DIRECTORY_KEY)里,随请求头 X-Directory-Key: <密钥> 带出去,不需要账号
密码、也不登录换 token。线上 Hub 的回话口径(实测):不带这个头回
401 {"code":"401001","message":"token已失效"},密钥不对回
401 {"code":"401001","message":"集成密钥无效"},都不带响应体,密钥正确时一次
回全量组织树 + 人员清单。没配密钥时本系统会在 Hub 那句 token已失效 后面补一句
「需要目录密钥,请在系统设置里填」,省得照着这句话去查登录 token。
密钥配好之后状态接口与同步记录里写 credential: directory_key。
OA_HUB_SERVICE_TOKEN / OA_HUB_SERVICE_ACCOUNT 是老的 Bearer token 口径,留着
兼容旧部署:没配目录密钥时才轮到它们(token / account),两者都没有就匿名请求
(credential: anonymous,只在对方确实不校验的部署上拉得到)。集成账号登不上时
同步会退回匿名拉取并在自检里报出来。
只想要「登录走 Hub、先不自动同步」,去系统设置 →「同步定时任务」把「允许定时同步」关掉;
这一项只在界面上配,配置文件与环境变量都不认它(见 7);
只想同步、登录仍走本地口令,设 OA_HUB_LOGIN_MODE=local。
3. 日常怎么改:改一次存数据库,不用重启
这一组配置项现在改在哪儿:
hub/hub_sync的元数据(中文名、说明、取值范围、 密钥标记)只在后端app/dbconfig.py登记一处。读写口是统一身份专用的GET/PUT /api/v1/hub/config(等价于PUT /api/v1/config/hub),配置文件与OA_HUB_*环境变量给的是出厂值与兜底值。系统设置页目前只摆出「站点信息」一组, Hub 这些项在页面上没有表单:改它们走配置文件、环境变量,或直接调上面那两个接口。
出厂值在配置文件里,日常改动都在系统设置 → 统一身份认证配置里做
(该页需要 system:setting 权限,表单分「连接与登录 / 同步凭证 / 组织人员同步」三组,
每项的中文名、说明、取值范围都由后端 GET /api/v1/hub/config 现给,前端不抄一份):
- 存在数据库:保存写进
oa_system_setting的config:hub/config:hub_sync/config:hub_perm三行, 逐键存 —— 只动这次改的那几项,同组其它项不跟着落库,界面上保存过什么库里就有什么。 配置文件里的值不会被写进库。 - 立即生效:点「保存」就生效。本进程的取值快照立刻失效,HTTP 客户端按新地址重建,
缓存的同步 token 一并丢掉,所以下一次登录、下一趟同步用的就是新值;其它进程
(多 worker / 多实例)最多
OA_CONFIG_CACHE_SECONDS秒(默认 2 秒)后自己跟上, 也可以直接POST /api/v1/config/reload催一次。全程不重启。 - 优先级:环境变量
OA_HUB_*> 数据库(界面上保存过的) >config.<环境名>.toml的[hub]config.toml的[hub]> 代码默认值(配置文件按OA_ENV分档,见 README「多套环境」)。 每一项都带着来源标记(env/database/file/default), 被环境变量设了值的项在界面上禁用并写明是哪个变量,页面底部还列出全部生效的变量名。 - 改回出厂值:把某一项的值传
null(界面上的按钮叫「改回出厂值」),库里删掉这一键, 这一项立刻回到config.toml里的值;那一行空了就整行删掉。 - 改配置文件要重启:
config.toml是出厂值,只在启动时读一次;而且这一项如果在界面上 保存过,库里那份会一直压着它。容器环境变量同理,是启动时读的。 - 密钥只进不出:
目录密钥、长期 token与集成账号密码在任何只读接口里都只回 空串加一个secret_set布尔,保存接口的返回值里也只有改动的项名;保存时留空表示 「这栏没改」,要清掉请点「改回出厂值」。操作日志里也只记改了哪一项,不带密钥值。 - 先测再存:「测试连接」把界面上还没存的值一起发给
POST /hub/probe,服务端按这份 草稿跑一遍自检(不落库、不改配置,试完把临时拿到的 token 丢掉再还回去)。 - 应急总闸:地址写错、所有人都登不进来时,把「应急总闸」
hub_disabled打开保存, 登录与同步立刻一律回本地。这一项在**「系统设置 → 统一身份应急总闸」**那张卡片上 直接切(只需要system:setting权限,不用登服务器):打开是安全方向,点一下就存; 关掉会把登录交回统一身份平台,所以先弹确认,弹层里还能先POST /hub/probe自检一次 再决定。界面上进不来时才在服务器上设OA_HUB_DISABLED=true重启 —— 变量优先, 那时卡片上的开关是灰的,并会写明摘掉变量之后按哪一稿走。OA_HUB_LOCAL_ACCOUNTS(默认admin)里的账号永远只用本地口令,总有人进得来。
界面上的开关与下表的环境变量一一对应。
4. 全部配置项
下表的「默认值」是代码里的兜底值;实际生效值 = 环境变量 > 数据库(界面上保存过的) >
config.toml > 这一列。想知道某一项现在到底是谁给的,看 GET /api/v1/hub/config
的 sources(env / database / file / default),界面上也逐项标着。
登录相关:
| 变量 | 默认值 | 说明 |
|---|---|---|
OA_HUB_ENABLED |
false |
总闸。关掉即纯本地登录,行为与接入前一致 |
OA_HUB_BASE_URL |
空 | Hub 站点地址,不带结尾 /。为空时等于没开 |
OA_HUB_LOGIN_MODE |
hybrid |
hub 只认 Hub;hybrid Hub 优先、Hub 不可用时回退本地口令;sso 只允许统一门户免登(本系统不再收账号密码,见 5.2);local 不查 Hub |
OA_HUB_TIMEOUT_SECONDS |
10 |
单次 HTTP 超时 |
OA_HUB_BREAKER_SECONDS |
5 |
Hub 失联(连不上 / 超时 / 5xx)之后的冷却窗口。窗口里每 2 秒仍放一个请求去真试探,其余立刻按「服务不可用」返回,不再各等一遍超时。0 = 关掉这层。见 §14 |
OA_HUB_MAX_INFLIGHT |
8 |
同时卡在等 Hub 上的请求数上限,超出的先排 0.2 秒队、排不上立刻返回「服务不可用」。0 = 不限制。见 §14 |
OA_HUB_VERIFY_TOKEN |
true |
登录拿到 token 后再调 POST /api/v1/auth/token/verify 复核一次 |
OA_HUB_AUTO_PROVISION |
true |
Hub 认了这个账号但本地没有时,就地建号(JIT) |
OA_HUB_LOCAL_ACCOUNTS |
admin |
应急通道:这些账号永远只用本地口令登录,不去问 Hub;账号名也不会被统一身份接管(见 5.1)。login_mode=sso 时它是唯一还能用口令进门的路,内置超管任何时候都算在里面 |
OA_HUB_SSO_ENABLED |
true |
允许统一门户免登这条通道(见 5.2)。关掉之后带 ticket 落地一律被拒 |
OA_HUB_APP_CODE |
空 | 免登三件套之一:Hub 注册应用时给的 code,也就是跳转地址 /api/v1/auth/apps/{code}/launch 里的 {code};票据回来之后与它比对,对不上按串号拒 |
OA_HUB_INTEGRATION_KEY |
空 | 免登三件套之二:票据校验用的应用密钥明文,随请求头 X-Integration-Key 带出;密钥类配置,接口只回「已设置」,明文不外出 |
OA_HUB_PORTAL_URL |
空 | 统一门户首页:没登录时把用户送回哪里(对接指南要求回 Hub 站点首页)。留空用 hub_base_url |
OA_HUB_SSO_STATE_REQUIRED |
false |
免登必须校验 state:默认只要求「带回来的 state 必须对上」;打开后连「门户压根没带回 state」也拒,而门户直点卡片正是没带回的那条路(见 5.2) |
接口路径(config.toml 的 [hub.api],十条都不写死在代码里;只写路径部分,站点地址
另配 hub_base_url;值不带开头的 / 会自动补上,写完整 URL、带空格或 .. 会被挡):
| 变量 | 配置文件里 | 默认值 | 干什么用 |
|---|---|---|---|
OA_HUB_PATH_CAPTCHA |
[hub.api] captcha |
/auth/captcha |
登录页取验证码(本地模式不调) |
OA_HUB_PATH_LOGIN |
[hub.api] login |
/auth/login |
账号密码登录,由 Hub 判定 |
OA_HUB_PATH_VERIFY_TOKEN |
[hub.api] verify_token |
/api/v1/auth/token/verify |
登录拿到 token 之后复核一次 |
OA_HUB_PATH_ME |
[hub.api] me |
/api/v1/auth/me |
Hub 用户首登建号时取部门 |
OA_HUB_PATH_DIRECTORY |
[hub.api] directory |
/api/v1/auth/directory |
全量组织树 + 人员清单,同步全靠它 |
OA_HUB_PATH_DIRECTORY_CHANGES |
[hub.api] directory_changes |
/api/v1/auth/directory/changes |
组织人员变更流水,增量同步按游标轮询它(见 8.1) |
OA_HUB_PATH_TICKET_VERIFY |
[hub.api] ticket_verify |
/api/v1/auth/tickets/verify |
免登票据校验,只由本系统后端带 X-Integration-Key 调用 |
OA_HUB_PATH_APPS |
[hub.api] apps |
/api/v1/auth/apps |
可见应用列表(门户落地页数据源,要用户登录态),本系统只用它在自检里验门户通不通 |
OA_HUB_PATH_LAUNCH |
[hub.api] launch |
/api/v1/auth/apps/{code}/launch |
发起免登跳转,{code} 调用时换成 hub_app_code |
这十条在「统一身份登录」配置组里叫「接口路径:xxx」,改完保存立刻生效;
GET /api/v1/hub/status 的 api_paths 会如实回显当前用的十个路径,连通性自检的
步骤名也带着路径,排查「到底在打哪个接口」时不用猜。免登跳转那一项带 {code} 占位符,
写坏了会退回出厂路径,不会因为一处笔误把免登整条通道弄哑。
同步凭证相关(定时任务和一键同步用,浏览器登录不用):
| 变量 | 默认值 | 说明 |
|---|---|---|
OA_HUB_DIRECTORY_KEY |
空 | 目录密钥,同步就靠它。长期密钥,随请求头 X-Directory-Key 带出;密钥类配置,接口只回「已设置」,明文不外出 |
OA_HUB_SERVICE_TOKEN |
空 | 老的 Bearer token 口径,没配目录密钥时才用它调 /api/v1/auth/directory |
OA_HUB_SERVICE_ACCOUNT |
空 | 集成账号;没配 token 时用它登录换 token |
OA_HUB_SERVICE_PASSWORD |
空 | 集成账号密码 |
OA_HUB_CAPTCHA_AUTO_SOLVE |
true |
集成账号登录时自动应答 Hub 验证码(算术型或直接回传答案的那种) |
OA_HUB_DIRECTORY_NEEDS_TOKEN |
false |
老口径:目录接口除了密钥还必须有 Bearer token 时打开。打开后集成账号换不到 token 就直接报错,不再静默退回匿名拉 |
OA_HUB_PASSWORD_MANAGED_BY_HUB |
false |
密码归不归 Hub 管。打开后本地不再设/改登录密码(password_authority() 返回 hub),前端隐藏重置密码入口、组织管理里拒写 |
同步行为相关(「允许定时同步」那一档例外:它只在界面上配,见 7):
| 变量 | 默认值 | 说明 |
|---|---|---|
OA_HUB_SYNC_WHEN |
daily |
同步频率:daily 每天 / weekly 每周选几天 / monthly 每月选几天 / interval 按间隔。写错回落到 daily(口径见 7) |
OA_HUB_SYNC_TIME |
01:00 |
本地时间 HH:MM 跑,默认凌晨 1 点。写错回落到 01:00;只有 interval 那一档不看这一项 |
OA_HUB_SYNC_WEEKDAYS |
1,2,3,4,5 |
每周哪几天,只在 weekly 起作用:1=周一 … 7=周日,可多选。一个都没认出来时退回周一到周五 |
OA_HUB_SYNC_MONTHDAYS |
1 |
每月哪几天,只在 monthly 起作用,取值 1–31。当月没有 30/31 号就顺延到当月最后一天,不会整月一次都不跑 |
OA_HUB_SYNC_INTERVAL_MINUTES |
1440 |
按间隔:从上一趟跑完开始计时,隔多少分钟再跑,只在 interval 起作用,取值 30–43200。这一档每次都是全量导出,别调太小 |
OA_HUB_SYNC_ORGS |
true |
关掉则只同步人员,不动 oa_unit |
OA_HUB_SYNC_BIND_LOCAL_BY_CODE |
true |
本系统自己加的部门,组织编码跟 Hub 某个部门一样且这个编码本地只用过一次,就认成同一个部门(补 hub_org_id),不再另建重名部门。编码有歧义就跳过并写进同步记录 |
OA_HUB_SYNC_INCLUDE_DISABLED_UNITS |
true |
带上 Hub 已停用的组织(include_disabled=true),否则整棵子树拿不到 |
OA_HUB_SYNC_OFFBOARD |
true |
Hub 里已消失的同步账号置为「已停用」,只停用,不删除 |
OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT |
40 |
离职停用熔断:一趟里等着停用的人超过本地同步账号总数的这个百分比、并且超过 OA_HUB_SYNC_OFFBOARD_GUARD_MIN_PEOPLE 人时,这一趟一个都不停用,只报数并把该趟标成 partial(见 6.1.1)。同一个百分比也管部门侧:要停用的部门超过 max(OA_HUB_SYNC_UNIT_OFFBOARD_GUARD_MIN, 同步部门总数 × 百分比) 时一个都不停(见 6.2)。取值 0–95,0 = 关掉熔断 |
OA_HUB_SYNC_OFFBOARD_GUARD_MIN_PEOPLE |
20 |
熔断线的人数底线:熔断线取「同步账号总数 × 百分比」与这个数里的较大者,所以几十人的小部署裁掉几个人不会被比例挡下来、天天弹熔断。取值 0–5000,0 = 只看百分比。百分比本身设 0 时这一项不起作用 |
OA_HUB_SYNC_UNIT_OFFBOARD_GUARD_MIN |
5 |
部门侧熔断线的个数底线,口径同上。部门总数比人少一个量级,沿用人员那侧的 20 这条线永远不会触发,等于没有熔断。取值 0–5000 |
OA_HUB_SYNC_ROSTER_FLOOR_PERCENT |
50 |
账号让位的清单人数下限:Hub 这次回的人员数不足「可参照基准 × 这个百分比」时,认定目录正在被清空或重导,这一趟一个登录名都不让位(撞车照旧只报数)。实测 2026-11-05 测试站一天之内从 100 人掉到 1 人,靠这一条挡住了把上百个登录名刷成 hub-lost-*。取值 0–100,0 = 不设下限 |
OA_HUB_SYNC_RECLAIM_LOST_ACCOUNTS |
true |
僵尸账号让位:本地已停用、且这一趟完整清单里查无此人的同步账号,把登录名腾开(改成 hub-lost-<user_id>-<原名>),好让 Hub 的现任主人拿回账号名(见 6.1.1)。只在人数对得上的全量同步里生效,增量事件、被截断或突然缩水的清单一律不让位。关掉就退回「撞车只报数、永远不处理」 |
OA_HUB_SYNC_SKIP_UNCHANGED |
true |
permission_version 与上次一致时跳过写入(只作用于排期跑的那趟,手动同步永远强拉) |
OA_HUB_SYNC_MEMBER_LIMIT |
5000 |
单次导出人员上限,取值 1–5000。人比这多就调大,别靠截断结果跑同步 |
OA_HUB_SYNC_EMAIL_DOMAIN |
空 | 建号时按 账号@域名 补邮箱;Hub 的人员清单不带邮箱 |
OA_HUB_SYNC_LOCKED_ACCOUNTS |
admin |
只读名单:这些账号名代表统一身份平台自己的管理员,OA 里不许改资料/角色/启停/口令、不许删除,也不许在人员页先占同名建号(见 6.5) |
OA_HUB_SYNC_PROTECT_ADMINS |
true |
本地自建的 role=admin 账号不参与同步,防止被改名/换部门/停用;同步来的人后来被授予管理员角色不受这一项影响 |
OA_HUB_SYNC_RETRY_MINUTES |
10 |
排期那趟失败后的补试间隔 |
OA_HUB_SYNC_RETRIES |
3 |
当天最多补试次数,超过就只留一条失败记录 |
OA_HUB_SYNC_CHANGES_ENABLED |
true |
增量同步:按游标轮询变更流水(见 8.1)。关掉只剩排期全量 + 界面上的「立即同步」 |
OA_HUB_SYNC_CHANGES_INTERVAL_SECONDS |
45 |
轮询周期(秒),取值 15–3600。文档建议 30–60;后台线程每分钟醒一次,实际间隔不会小于这个周期 |
OA_HUB_SYNC_CHANGES_LIMIT |
200 |
单批条数,取值 1–500(Hub 侧上限 500)。同一批循环拉到 has_more=false 才提交游标 |
OA_HUB_SYNC_CHANGES_FULL_ON_GAP |
true |
落后过多就回全量:游标比 Hub 侧最老的流水还旧、或收到只带 id 与 status/parent_id 的组织变更事件时,改拉一次全量重对齐(文档 6.4)。关掉就只记日志,等排期那趟全量补 |
统一身份权限相关(口径见 §9;没有独立密钥 —— 权限接口复用登录那套凭证,所以前置条件是
OA_HUB_ENABLED=true 且站点地址已填,否则等于没开):
| 变量 | 默认值 | 说明 |
|---|---|---|
OA_HUB_PERM_ENABLED |
false |
总开关。关掉时权限完全按本系统的角色矩阵走,连一次 Hub 都不问(热路径上没有网络调用) |
OA_HUB_PERM_MODE |
shadow |
shadow 只把 Hub 的口径显示出来给管理员对账,判定仍按本地角色矩阵;enforce 以统一身份为准 |
OA_HUB_PERM_APPLICATION_ID |
空 | 问 Hub 要哪个应用的权限(权限文档第 6 节的 application_id)。留空用免登那个 OA_HUB_APP_CODE |
OA_HUB_PERM_CACHE_SECONDS |
60 |
按人缓存权限的时长(秒),取值 0–86400;0 = 每个请求现问(只在测试环境这么干)。问失败之后的冷却固定 15 秒,不占这个窗口 |
OA_HUB_PERM_SCOPE_MODE |
merge |
数据范围口径:merge 本地角色与 Hub 各给一个范围时取更大的那个;hub 完全照 Hub 给的 |
OA_HUB_PERM_ADMIN_QUERY |
true |
手上没有本人 Hub 令牌时(免登进来的用户就是这种)用同步凭证走 admin/users/{id}/roles 代查;关掉则这类用户只用本地权限 |
OA_HUB_PERM_KEEP_LOCAL |
true |
Hub 一个本系统认得的权限码都没给出来时(权限还没登记、角色还没绑)保留本地权限,免得一处没配好把所有人锁在门外 |
权限接口路径(config.toml 的 [hub.perm.api],九项都不写死在代码里,口径同上面那九项
登录路径;带 {role_id} / {user_id} 占位符的三项在调用时才填值,占位符写坏退回出厂路径):
| 变量 | 配置文件里 | 默认值 | 干什么用 |
|---|---|---|---|
OA_HUB_PERM_PATH_ROLES |
[hub.perm.api] roles |
/api/v1/auth/me/roles |
当前用户的角色(权限文档第 5 节),要用户令牌 |
OA_HUB_PERM_PATH_PERMISSIONS |
[hub.perm.api] permissions |
/api/v1/auth/me/permissions |
当前用户的权限码,带 application_id 查询参数(第 6 节) |
OA_HUB_PERM_PATH_DATA_SCOPE |
[hub.perm.api] data_scope |
/api/v1/auth/me/data-scope |
当前用户的数据范围(第 7 节) |
OA_HUB_PERM_PATH_DIRECTORY_SCOPED |
[hub.perm.api] directory_scoped |
/api/v1/auth/directory/scoped |
按调用者数据权限过滤的组织人员导出(第 11 节),与全量目录同结构 |
OA_HUB_PERM_PATH_ADMIN_ROLES |
[hub.perm.api] admin_roles |
/api/v1/auth/admin/roles |
角色目录,数据范围就配在每一项上(第 8 节) |
OA_HUB_PERM_PATH_ADMIN_PERMISSIONS |
[hub.perm.api] admin_permissions |
/api/v1/auth/admin/permissions |
权限目录:GET 查、POST 登记,权限页的对账与一键登记走这一条 |
OA_HUB_PERM_PATH_ADMIN_ROLE_PERMISSIONS |
[hub.perm.api] admin_role_permissions |
/api/v1/auth/admin/roles/{role_id}/permissions |
某个角色绑了哪些权限码(第 8 节) |
OA_HUB_PERM_PATH_ADMIN_USER_ROLES |
[hub.perm.api] admin_user_roles |
/api/v1/auth/admin/users/{user_id}/roles |
某个人的角色,服务端代查用的就是它(第 8 节) |
OA_HUB_PERM_PATH_ADMIN_USER_DATA_SCOPE |
[hub.perm.api] admin_user_data_scope |
/api/v1/auth/admin/users/{user_id}/data-scope |
指定用户的数据范围(第 7 节给管理员留的那一条) |
这十六项在「统一身份权限」配置组里,GET/PUT /api/v1/hub/config 一并管,保存即生效;
GET /api/v1/hub/permissions/status 会如实回显当前生效的九条路径与缓存占用。
5. 登录链路
浏览器 UnisOA Hub
│ 账号+密码+验证码 ─►│ │
│ │ POST /auth/login ──────► │ 校验账号密码与验证码
│ │ ◄── access_token ─────── │
│ │ POST /api/v1/auth/token/verify
│ │ 认/建本地账号 + 落库 │
│ ◄── 本地 JWT ─────│ │
要点:
- 验证码是 Hub 的。登录页
GET /auth/captcha只是把 Hub 的验证码转发过来; 本地模式下这个接口直接回required=false,前端不会多出输入框。验证码是一次性 的,登录失败后前端会自动换一张。 - 本地发的还是 UnisOA 的 JWT。Hub 的 token 只在登录这一瞬用于校验,不落库、 不下发给浏览器,后续接口仍然按本地的权限角色与数据范围走。
hybrid的回退是有条件的:只有 Hub 连不上、超时、返回 5xx/500001才回退 本地口令。Hub 明确说「账号或密码错误」(401001)或「验证码错误」(400001) 时直接拒登,不会再拿本地口令兜一层,否则等于给弱口令开了后门。 Hub 实际还有另一种错误口径 —— 不套统一响应,只回{"error":"invalid_captcha", "message":"验证码错误或已过期"}。这种error名在 400/401/403 下同样按「被拒」处理 (invalid_captcha会提示重新填验证码);只有 404 仍算「服务不可用」,因为那多半是 接口路径配错了,提示去查配置比提示密码错有用。- 应急账号:
OA_HUB_LOCAL_ACCOUNTS里的账号跳过 Hub,只用本地口令。这一栏默认是 空的:启动时按内置超管现在的账号名把它种进库,内置超管改名时跟着搬(自己加的 应急账号不动),不会出现「名单还指着旧账号名」那种走本地口令的暗门。内置超管 通常不在 Hub 的花名册里,没有这个口子,一开 Hub 就会把自己锁在系统外。需要更多口子就逗号隔开:OA_HUB_LOCAL_ACCOUNTS=localadmin,ops。 这份名单存在数据库里(oa_system_setting的config:hub→hub_local_accounts, 界面上那一栏叫「应急账号(永远走本地口令)」),保存即生效、不用重启;配置文件里 的那一行只是库里还没存过时的出厂值。内置超管任何时候都算在名单里:这一栏被清空 也进得来门,只是没有别的应急账号可用了。 这一栏还是硬护栏:这些账号名永远不会被统一身份接管,Hub 哪天建一个同名的人 也会让给本地(同步记录里会点名),免得后门的source被改成hub之后跟着 Hub 停用。 想反过来让内置超管也走统一身份,见 5.1。 - 停用即时生效:
OA_HUB_VERIFY_TOKEN=true时,Hub 判定token_user_inactive的账号即使口令正确也拒登,并回ACCOUNT_DISABLED。 - Hub 停用 ≠ 本地立刻停用:本地人员的停用靠同步落地,最坏延迟到下一次排期同步 同步;要立刻生效就点一次「立即同步」。
5.1 把内置超管让位给统一身份的 admin
默认内置超管叫 admin,又钉在应急通道名单里,于是 Hub 那个 admin 同步进来时账号名
已经被占,永远对不上号。要让 Hub 的 admin 正常同步并走统一身份登录,是把本地这个改成
应急账号,一行配置:
[seed]
admin_account = "localadmin" # 内置超管改名;库里已有的那一行启动时跟着改
重启后 seed._align_admin_account 会把那一行改名(按账号存的岗位、共享名单、流程配置
由 hub_refs 一起搬;运行态的人员引用本来就是账号,改名动不到它们),并在 system.admin_account 记一笔。
这一笔从此就是内置超管账号名的户口:配置文件不用一直写它,没写就用库里记着的那个
(OA_ADMIN_ACCOUNT 或 [seed] admin_account 再点名时才当作"又要改名")。应急名单也
不用跟着改 —— 内置超管在代码里就永远走本地口令;要把别的账号也放进来,才去动
「应急账号」那一栏(存库即生效)。之后:
localadmin+ 本地口令 = 应急入口,Hub 挂了、密钥写错、人被误停用都进得来;admin这个账号名空出来了,Hub 的admin由同步正常建号,走统一身份登录;- 同步建号一律是普通成员,不会因为它叫 admin 就自动给管理员角色(那等于让上游 目录决定谁能管本地系统)。要给它权限,人员页里手工授予一次即可。
OA_HUB_SYNC_PROTECT_ADMINS 管的是本地自建的号:内置超管、界面上手工建的管理员
不参与同步。同步进来的人被授予管理员角色之后照旧跟着 Hub 走(改名、换部门、停用),
以前按 role=admin 一刀切会把这个人在提升那一刻冻住。
5.2 统一门户免登(门户票据换本地会话)
对接指南 1.4 把话说死了:登录只发生在 Hub 一处,下游不再自己认人,也不再留第二种登录方式。
本系统因此有一条独立于账号密码的通道,OA_HUB_LOGIN_MODE=sso 时它是唯一一条(应急账号除外)。
浏览器 UnisOA Hub
│ 打开登录页 ──────────────►│ │
│ ◄── state + 门户地址 ────│ POST /auth/sso/state │
│ │ 随机 state 写进 HttpOnly Cookie
│ 整页跳统一门户,登录后点本系统卡片 │
│ │ ◄── POST /api/v1/auth/apps/{code}/launch
│ ◄── 302 到 /sso?ticket=…&state=… ─────────────────────── │
│ POST /auth/sso/login ────►│ │
│ {ticket, state} │ POST /api/v1/auth/tickets/verify
│ │ ── X-Integration-Key ───────►│ 一次性消费
│ │ ◄── active + sub + account ──│
│ ◄── 本地 JWT ─────────────│ 按 sub 认人/建号 + 落库 │
Hub 侧要先做的三件事:注册应用拿到 code 与密钥明文、launch_url 填下面两条落地地址
之一、在「可访问角色」里勾上允许进本系统的角色(一个都没勾时谁都不能看到这张卡片,管理员也不例外)。
「哪两条」见下表,GET /api/v1/hub/status 的 sso.callback_url / sso.alias_url 会直接把
完整地址回显到系统设置页的 Hub 状态卡上(悬停「免登回调地址」那一行),照抄即可。
5.2.1 两种落地口径:票据交给前端,还是直接交给后端
对接指南 1.1 只把票据写到"落到下游页面"这一层,本系统两条都实现,验票认人完全共用
app/api/auth.py:_sso_person_from_ticket,配哪一条效果一样:
launch_url 填 |
票据落在哪 | 换会话的接口 | 说明 |
|---|---|---|---|
https://<本系统>/sso |
前端落地页,由页面把 ticket POST 回来 |
POST /api/v1/auth/sso/login |
最省事的默认口径 |
https://<本系统>/api/v1/auth/sso/callback |
后端,浏览器不参与验票 | POST /api/v1/auth/sso/exchange |
推荐给对票据口径较严的对接方 |
https://<本系统>/sso/hub |
同上 | 同上 | 回调的别名,与《对接指南》3.1 的举例写法一致 |
后端回调这一条是 302 一路走完的:
浏览器 UnisOA Hub
│ ◄── 302 /sso/hub?ticket=…&state=… ────────────────│ 门户点卡片
│ ── GET /api/v1/auth/sso/callback ──►│ │
│ │ ── tickets/verify ──►│ 一次性消费
│ │ ◄─ active + sub ─────│ 认人 / 建号
│ ◄── 302 /sso#code=<一次性短码> ────│ │
│ (同时下发 HttpOnly Cookie oa_sso_handoff) │
│ ── POST /api/v1/auth/sso/exchange ─►│ │
│ (短码 + 那条 Cookie 一起交回来)│ │
│ ◄── 本地会话(同 /auth/sso/login)──│ 此刻才建会话、写登录日志
- 票据从此不进浏览器:不进前端脚本、不进浏览历史、不进代理日志,也不跟着 Referer 出站。
- 后端也不把本地令牌拼在 302 的地址上,上来的是
app/service/sso_handoff.py发的一条短码: 60 秒即失效(sso.code_ttl_seconds)、库里只存哈希、只能用一次,而且必须配着回调当场下发的oa_sso_handoff(HttpOnly + SameSite=Lax)才能兑换。短码被人在地址栏里翻出来也没用—— 它不在别人的浏览器里,兑换就会被拒。 - 短码放在地址的
#片段里(/sso#code=…),浏览器不会把它发给任何第三方。 - 回调失败不返回 JSON(那是浏览器整页跳转过来的,用户只会看到一屏
{"code":401,…}), 一律 302 回/sso?error=<稳定原因码>,句子由前端按语言包说;码表见app/api/auth.py:LANDING_REASONS,前端映射见frontend/src/views/auth/ssoErrors.ts。 稳定码之外不透传任何后端文案,票据原值也绝不出现在 302 地址里。 ?redirect=/todo这类站内路径可以带在回调地址上,后端只认/开头且非//、/\的写法, 其余一律丢掉;它不进 302 地址,随短码存库,兑换时随会话一起回给前端。- 回调与别名两条都匿名可调(
backend/scripts/check_route_guards.py的匿名白名单里有名有姓), 鉴权靠 Hub 签发的一次性票据本身。
前端只有两个页面参与:
- 登录页
frontend/src/views/auth/LoginView.vue:GET /api/v1/settings/public的hub.sso_only为真时不再渲染账号密码表单,也不摆一屏等人点按钮:挂载完立刻让后端写好state再整页跳去统一门户。这一屏从头到尾不会出现一张没人填的表单 —— 公开配置还没到手时 转圈配「正在确认你的统一门户身份」(这一档通常不会发生:配置随index.html一起到位, 见本节末那两扇门),人已经送出去时转圈配「正在前往统一门户」。 想留本地口令那扇门就访问/login?local=1—— 那一档sso_only在页面上就当不成立, 自动跳转根本不启动,应急用的内置超管不会被抢在门外。 只有门户连着把人原样退回来(自动跳的预算用完,见下条)才停在这一屏,把「前往统一门户」 那颗按钮交回给人自己点;这一屏也顺手不再去要那张用不上的验证码。 - 无感跳转的三条护栏(
frontend/src/utils/ssoJump.ts,单测ssoJump.spec.ts):- 接住来路:对接指南 1.4 写明门户不解析
redirect之类的查询参数,绕门户一圈回来 地址上就没有它了。所以跳出去之前把想去的站内路径存进sessionStorage(unisoa_sso_return),落地页在没有redirect时取回来,取一次即清; 后端回调带回来的session.redirect与地址栏上的redirect都排在它前面。 - 数着跳:同一浏览器标签页里 60 秒窗口内最多自动跳 2 次,第 3 次起停下让人自己点, 免得「OA 把人送去门户 → 门户把人送回 OA → 又送去门户」来回打转;免登成功落地或人 自己点一次按钮都会把这份预算清零。
- 只在这一档自动跳:
sso档没有第二种登录方式,跳走不损失什么;hybrid/local还得给账号密码那扇门留位置,一律照旧停在登录页。 跳转本身失败(POST /auth/sso/state挂了)也照样把人送出去 —— 这一趟的目的是让人出去, 不是让人等在原地。
- 接住来路:对接指南 1.4 写明门户不解析
- 落地页
frontend/src/views/auth/SsoCallbackView.vue(/sso):认地址上那一样东西——?ticket=(前端落地口径,交给POST /auth/sso/login)、#code=(后端回调口径,交给POST /auth/sso/exchange)、?error=(后端已经拒了,只照原因码说一句话,一次请求都不再发)—— 然后用history.replaceState把它从地址栏抹掉、进站。 - 落地不再先闪一屏「正在确认你的统一门户身份」(企微卡片点开的那一路最扎眼):
换会话这一步从落地页的
onMounted提到了frontend/src/utils/ssoLanding.ts,main.ts:bootstrap一进来就把请求发出去,与语言包、路由块并行下载——以前它排在 这三四个资源往返之后,浏览器必然先画一屏登录版面再走人。路由守卫(router.beforeEach里那一条ssoLandingTarget)等这一趟回来:换到会话就直接送去目标页,sso-callback这条路由连确认都不会确认,它的懒加载块也就压根不下载;只有兑失败或地址上压根没凭证, 才把落地页交出来那句能看懂的话加「回到统一门户」。这一屏因此只剩失败态, 等待态换成了index.html里那幅进站骨架(320ms 之内不出现,出现也不是登录卡)。 一个凭证只兑一次由ssoLanding认凭证原文兜住(bootstrap、守卫、落地页三处调的是 同一个 promise),红线照旧:绝不重试、落地后立刻history.replaceState抹掉凭证。 单测:utils/ssoLanding.spec.ts(只兑一次、来路顺位、抹地址栏)、router/ssoGuard.spec.ts(成功时这一屏不激活)。
前端拿公开配置有两扇门,两扇共用 app/public_config.py 那一处口径:
- 随文档一起来:发
index.html时后端把同一份内容注成window.__APP_CONFIG__(app/web_shell.py,开发模式由 vite 的inject-public-settings插件做同样的事)。 画第一笔之前浏览器就知道这一档是免登还是账号密码、门户地址是什么,不必先转一圈GET /api/v1/settings/public再决定画哪一屏。站点名里带</script>也不会改写脚本边界; 问不出配置(库还没起来)就按原样发文件,页面宁可多问一次也不该打不开。 自检:python3 scripts/check_web_shell.py。 - 挂载之后问一次:
GET /api/v1/settings/public,接口与注入不一致时以接口为准 (服务工作者只在断网时拿缓存的外壳,联网时导航永远先走网络,见sw.template.js)。
后端几条硬规定(对应代码在 app/api/auth.py:sso_login 与 app/service/sso_state.py):
- 票据只出现在服务端到服务端那一步:本系统后端带
X-Integration-Key调POST /api/v1/auth/tickets/verify,浏览器不参与校验;密钥不出接口、不进日志。 - 绝不重试:票据是"先查即删"的一次性票(对接指南 4.4),重试只会把一次正常登录变成
"票据已被使用"。落地页失败之后不会再自动调第二次,页面上也只给「回到统一门户」。
同理,前端落地那条(
POST /auth/sso/login/POST /auth/sso/exchange)回的 401 是 业务结果,不是"会话过期":这两条写在frontend/src/api/client.ts:AUTH_ENDPOINTS里, 不走静默续期。少了这一条,落地那一刻浏览器里压根没有会话可续,续期失败会把人从 「回到统一门户重新点一次」那一屏抢去登录页,而sso档的登录页又会当场自动跳回门户。 - 业务失败看
data.active与reason:ticket_invalid/ticket_expired/ticket_audience_mismatch拒登并提示回门户重新点;user_inactive除了拒登,还把本地 账号置为停用并清掉它的刷新令牌,绝不回落到旧会话(对接指南 1.4 / 4.3)。 - 比对
app_code:校验回来的app_code与hub_app_code不一致直接拒 (SSO_APP_MISMATCH),挡的是"A 应用的密钥配到了 B 应用"这类串号。 - 只按
sub建映射:sub就是本地users.hub_user_id;account只是展示与认领线索, 不按email、display_name自动合并账号(对接指南第 5 节)。票据没带sub直接拒。 state防会话固定与票据注入:从本系统发起的免登先由POST /auth/sso/state生成随机state,值放在 HttpOnly + SameSite=Lax 的 Cookie 里(前端读不到明文)。落地时比两层,都走 常数时间比对,无论结果如何 Cookie 立刻作废:- Cookie 那一层证明「地址栏里的
state是本系统发出去的」,不是别人随手编的; - 票据那一层证明「Hub 签的这张票据本来就是开给这个
state的」—— 对接指南 4.4 要求state在校验响应里原样回传,回传值与浏览器交回来的那条不一致就直接拒 (SSO_STATE_REJECTED)。少了这一层,攻击者就能拿自己的票据配上别人的state, 把对方登成他自己。 带回来了才比对,没带回来不拦:对接指南 1.4 写明门户前端不解析redirect之类的查询 参数,3.2 又规定state为空就不拼进落地地址,所以「在门户里点卡片」这一条主路径落地时 压根不会带state——哪怕本系统刚刚在登录页发过一条(登录页跳门户之前一定会发)。因此OA_HUB_SSO_STATE_REQUIRED=false(默认)下,「没有 Cookie」与「有 Cookie 但落地没带回state」两种情况都放行,只要落地带了state,上面两层比对一层都不跳过。打开它之后这两种 一律被拒,等于只承认「门户把state一路带回来」的那条链路,开之前先跟 Hub 侧确认清楚, 否则会被自己锁在门外。
- Cookie 那一层证明「地址栏里的
sso模式下的后门:login_mode=sso关的是账号密码这条通道,应急账号(内置超管 任何时候都算一个)照旧走本地口令,免得把管理员锁在自己的系统外面。- 配不齐就等于没开:
hub_base_url+hub_app_code+hub_integration_key缺任何一项, 免登通道就是关闭的(GET /hub/status的sso.missing会点名缺哪一项),登录页也不会把 用户送去一个进不来的地方。
5.3 会话生命周期与空闲超时
对接指南第 8 节把这一段划给下游:Hub 那边登出不会回收已经建好的下游会话,Hub 也不向 下游推送登出通知。本地会话能活多久、多久不动人就算过期,只能本系统自己定。
| 变量 | 默认值 | 说明 |
|---|---|---|
OA_SESSION_IDLE_MINUTES |
0 |
空闲多久要求重新登录(分钟),0 = 不启用(老部署行为不变)。属「安全」配置组,界面上保存即生效 |
口径(app/security.py 与 app/api/auth.py:refresh):
- 访问令牌被压到不超过空闲窗口:开了空闲超时之后,签发访问令牌时把有效期压到
min(access_token_minutes, idle)。访问令牌是自包含 JWT,发出去之后在后端拦不住, 只在刷新那一步查空闲等于没做。 - 空闲看的是最近一次活动,不是签发时间:记在
oa_refresh_token.last_used_at上, 所以活跃用户不会被刷新令牌的老化提前踢下线。超过窗口没动过 → 这张刷新令牌就地作废, 续期返回 401(reason=SESSION_IDLE),只能重新登录;只允许免登的部署里这就等于回门户 重新点一次卡片。 - 心跳:
POST /api/v1/auth/session/touch(需登录)只把last_used_at推到当下, 不放行任何请求;没开空闲超时时直接回{idle_minutes: 0, touched: false}。前端src/utils/sessionIdle.ts在有登录态时挂这个心跳(最多一分钟一次),本地也有一条 同样的空闲计时:一动不动到点就清本地会话送回登录页。活动时间写在localStorage, 免得一个没人看的后台标签页把正在另一个标签页里干活的人登出。 - 窗口值前端拿得到:
GET /api/v1/settings/public的session.idle_minutes, 据此决定要不要挂心跳与计时;0 就什么都不做。 - Hub 侧停用仍然会当场切断:免登校验回
user_inactive时除了拒登,还把本地账号置为 停用并清掉它的刷新令牌(见 5.2),不会让人靠着旧会话继续留在里面。 - Hub 的
token/verify只在登录那一刻复核一次(OA_HUB_VERIFY_TOKEN,默认开;token_user_inactive直接拒登)。权限文档第 10 节建议「在自己的会话校验里调本接口」, 本系统不把用户自己的 Hub 访问令牌落库,所以本地会话活着的那段时间手里没有 Hub 令牌可验 —— 「这个人现在还有效吗」由三件事兜住:Hub 说人停用时本地跟着停用并清刷新令牌(上面那条)、 排期全量与增量同步把 Hub 侧停用的人停用(见 6 与 8.1)、以及本节这条空闲超时把会话窗口收紧。 Hub 侧登出不会通知本系统(对接指南第 8 节),这是既成事实,不是省掉的一步。
6. 同步落库规则
数据来自 GET /api/v1/auth/directory(带 include_disabled_users=true),一次拿
到完整组织树和同一批人员的扁平清单。人员以扁平清单为准,组织树只用来建部门。
字段映射:
| Hub 字段 | 本地列 | 规则 |
|---|---|---|
users[].user_id |
users.hub_user_id |
唯一的身份键(唯一索引)。清单里没带 user_id 的人不建号也不认领,只计数上报 |
users[].account |
users.account |
普通字段:Hub 改了账号本地跟着改(新账号没人占用才改)。只有还没绑过 Hub 主键的本地账号才允许按账号认领(source 改成 hub);账号已属于别的 Hub 主键时跳过不覆盖 |
users[].display_name |
users.display_name |
姓名,直接对齐 |
users[].organization_id |
users.organization_id |
经 oa_unit.hub_org_id 换成部门主键;映射不到时保留原部门,不把人踢成无部门 |
users[].mobile |
users.mobile |
手机号。只有 Hub 这次确实带了号码才动这一列:mobile/phone/telephone/phone_number/phonenumber/mobile_number 依次取第一个非空,洗成「可选 + 加 5~15 位数字」再写(全角转半角、去掉 -/()/空格;010-62345678 这种座机洗不出来)。洗不出来的人计数上报、本地值原样保留;Hub 压根没带这个字段时同样不碰本地值——这一列可能是 HR 自己录的,「没下发」绝不能被写成「清空」。同步记录里三个数分开:mobile_returned(清单里有多少个合法号码)、mobile_updated(本地刷了几条)、mobile_invalid(Hub 带了号码字段但不是号码) |
users[].wecom_userid |
users.wecom_user_id |
企业微信 UserID(企微工作通知的 touser)。实测(2026-10-21,member_limit=5000):对方下发的键是 wecom_userid,100 人里 98 人带这一键,5 个人的企微号和 account 并不相同(chenhang → rdpnr_chenhang 这种),是只有对方才有的信息。取字段不赌拼写:键名先去掉 _/-/空格再转小写比对,wecom_userid/WecomUserID/wecomUserId/external_userid/external_id 都算,external_identities[] 里 provider 是企微那一条的 external_id 也认(那里的 user_id/id 是这条映射记录或 Hub 人员主键,不收)。洗完只认企微自己那套字符集(字母、数字与 ./-/_/@,2~64 位,0 这种「没有」的写法不算号),洗不出来的记 wecom_invalid、本地原样保留。「没号就不带键」是实测行为:Hub 不会给一个空串,所以清空这一半按整趟清单判断——只要这趟清单里有人带过这个键,就说明这一列已下发,没带的那个人就是没企微号,本地跟着清空(wecom_cleared);整趟一个键都没出现过就是接口还没这一列,全员不动。企微 UserID 会被删掉再分配给另一名员工,只写不清等于把张三的待办推给拿走这个号的下一任。增量事件不按这个口径:实测最近 30 条 source=wecom 的用户事件里只有 3 条带这个键,一条补丁证明不了整个接口有没有这一列,所以补丁里没带就一律不动。这一列照抄上游、不本地去重:Hub 把同一个号同时发给几个人(2026-11-05 测试站实测 user_id=1 与 user_id=455 都带着 chenhao2),这几个人都挂着这个号,发给这个号会同时送达他们;同步只记 wecom_conflicts 报数,不替上游改数据。判撞号那一步先 flush 再查库:Session 是 autoflush=False 建的,同一批变更里前一条刚挂上的号还没落下去就查,会漏报。这句提示一趟只写一次、里面的人数按整趟累计:增量同步每条完整人员事件都要过同一套落库逻辑,提示统一放到收尾报(实测 2026-11-05 一趟变更同步把同两句提示重复写了 5 遍,数字还停在第一次的 1 人) |
users[].status |
users.status |
1 → 正常;其余一律 → 已停用(Hub 只承诺「非 1 即停用/待审核」)。注意:Hub 在 Hub 侧被停用的人不会出现在清单里,停用实际表现为「不在清单」,走下面「不在清单里就停用」那条规则 |
organizations[].organization_id |
oa_unit.hub_org_id |
组织归属的唯一依据(唯一索引)。写上一律不清空:界面上改不动,Hub 里消失也只是停用不删除 |
organizations[].code |
oa_unit.code |
组织编码。alias 只在新建部门时按编码起个头,之后归本地 |
organizations[].name |
oa_unit.name |
名称;改名或挪父级后连带重算 path 与部门 distinguished_name |
organizations[].status |
oa_unit.status |
1 → 正常;其余一律 → 已停用(与 users.status 同一套数字) |
organizations[].path / member_count |
不落库 | 前者是 Hub 按 organization_id 拼的 /1/2/,只用来还原层级(见 6.4),本地另有 O2OA 口径的 path;后者按 organization_id 现算 |
列宽是本地表的硬约束(Hub 那边没承诺长度),同步在写库前一律按列裁一刀,
免得一个长名字让整批同步回滚:account 190、display_name 100、email 190、
mobile 32(洗过之后最长 16,留的是余量)、wecom_user_id 190(企微 UserID 洗过之后最长 64,同样是余量)、oa_unit.code 190、oa_unit.name 255;oa_unit.path 与各类 DN 都是 512,
所以部门名还要按父级路径剩的空间再收一次,展示用的 DN 串同样封顶在 512。
界面上手工录入超过 190 字的组织编码会被直接拒掉,不会抛数据库错。
同步不会碰的东西:
users.password_hash:本地已存在的账号口令不动;同步新建的账号是随机口令, 本来也只能回 Hub 登录。users.role与权限角色(oa_auth_role):这是 UnisOA 自己的菜单/接口/数据范围 体系,Hub 侧的角色不参与同步。users.wecom_user_id不参与任何身份判定:认人只认hub_user_id(6.1),这一列只是 「要给这个人发企微消息」时查出来的收件地址,为空就是发不了,既不影响登录也不影响待办。source='local'的账号:除了被同名认领,永不改名、换部门或停用;本地自建的role='admin'账号在OA_HUB_SYNC_PROTECT_ADMINS=true时连认领都跳过,OA_HUB_LOCAL_ACCOUNTS里的应急账号名任何时候都不被认领(见 5.1)。- 界面上对只读账号的改动:内置超管与
OA_HUB_SYNC_LOCKED_ACCOUNTS名单上的账号 在人员页整行只读,改资料/改角色/停用/重置密码/删除都会被拒(见 6.5)。 - 删除:同步只把人置为「已停用」,永不删行,历史待办和审批轨迹不会悬空。
界面上删人同理要慎重:绑过
hub_user_id的账号默认删不掉(400 提示改用「停用」), 确认后果后带?force=true才能删;删掉的是本地行和锚点,Hub 那边不受影响。
两条来自接口文档的保护:
truncated=true说明人员清单被member_limit截断,这一趟只写不撤,运行记录 标成partial,并在说明里提示调大OA_HUB_SYNC_MEMBER_LIMIT。- Hub 返回的人员清单为空且
total_users=0时直接放弃写入并记failed,避免把 本地同步账号整批停用。 - 部门同理:清单完整(未截断)时,Hub 已经不存在的同步部门(
hub_org_id不为空 且没出现在这次导出里)置为「已停用」,同样只停用不删除;本地自建部门不在判据里。 - Hub 的目录接口不下发已停用人员(实测:
include_disabled_users/include_disabled两种写法、true/false两个值都试遍,返回的人数与total_users一个字没变,清单里status清一色是 1)。所以同步请求照常带上include_disabled_users=true,但别指望它起作用: 「在 Hub 停用」和「从 Hub 消失」在我们这边是同一件事,都按离职停用处理,人员停用数只可能 来自「这次不在清单里」,永远不会来自status != 1。对面哪天改成下发停用人员,逻辑照样成立。
6.1 身份只认 Hub 的 user_id
每次同步都是全量清单,本地不给自己造身份。判据只有一个 users.hub_user_id:
- 先按 Hub 主键找人;找不到才看账号,而账号只允许认领还没绑过主键的本地账号
(手工建的、或历史遗留的)。认领只改
hub_user_id/source,users.id不变。 - 账号已经绑在别的 Hub 主键上就跳过并计数,绝不覆盖:把两条记录并成一条,等于把两个人 的权限、待办、流程历史搅在一起。
- 清单里没带
user_id的人一律不处理(计数写进同步记录)。宁可少一个人,也不要靠账号猜身份。 - 「这个人是不是离职了」也只看主键:
source='hub'且主键没出现在这次清单里才停用。 以前还附带「账号也找不到」,Hub 一改名就会把在职的人判成离职。 - 唯一索引
uq_users_hub_user_id从库上兜住「一个 Hub 主键对两个人」。老库里真有重复时, 启动时保留人在的那一行,多出来的行只解掉 Hub 主键、退回本地账号,不删数据。 - 正因为身份只认这个主键,在 OA 删人等于把锚点一起删掉:之后 Hub 改名、停用、重新启用
都再也对不回本地。所以删人接口默认拦住绑过主键的账号,
force=true才放行;删完之后 Hub 清单里还有这个人,下一趟会按自动建号重建一条新主键的记录(权限、共享名单要重配), Hub 清单里已经没有这个人(在 Hub 被停用就是这种),删掉就是真没了,不会复活。
登录侧同口径:_person_from_hub() 先按 hub_user_id 查,其次账号,最后才是提交名;
只在本地主键为空时补绑,从不改写已有的 hub_user_id。账号改名留给定时同步做,
因为只有同步会连带把按账号存的审批引用一起搬走。
6.1.1 Hub 换了一套数据之后:账号让位与离职熔断
上面那条「不抢别人的账号」有一个盲区。Hub 的变更流水只记 upsert、不记删除(实测
2026-11-04 测试站:346 条流水里 344 条来自企微同步、2 条来自 Hub,op 清一色 upsert,
而流水里出现过的 117 个账号名只剩 100 个还在目录里)。Hub 一合并人、一重导数据,账号名会
挪到另一个 user_id 上,而被删掉的那个 user_id 本地永远不会知道。于是每一趟全量同步都
在同一个地方撞车:
- 活着的人(按主键命中)要把账号名改成 Hub 给的新值,可这个名字被一条绑着已消失主键的 本地行占着 → 判成「账号已属于另一个统一身份」跳过,而且下一趟、下下趟照样跳过;
- 占着名字的僵尸行则因为主键不在清单里被停用。
- 界面上看到的就是同一个人两条:一条「正常」但登录名是上辈子别人的(
unishero挂着 潘朝钊、zhoujin挂着潘远银),一条「已停用」占着正确的登录名。企业微信 UserID 同理, 号压在僵尸行上,活人的待办一直推不到。测试库那次撞上 96 个这种死锁的改名 + 40 个企微号冲突。
两个口子都在 service/hub_sync.py:
- 账号让位(
_retire_lost_accounts,OA_HUB_SYNC_RECLAIM_LOST_ACCOUNTS)。这一条动的 是别人的登录名,所以门槛叠了四层。行本身要同时满足:source='hub'、本地已停用、 这一趟完整清单里没有他的hub_user_id、账号名不在应急名单里;这一趟还要 ① 由调用方声明这是全量清单(complete_roster=True)、② 没被member_limit截断、 ③ 清单人数对得上(_roster_floor:不少于「上一次同步记下来的人数」与「本地带hub_user_id的账号数」里较小那个的OA_HUB_SYNC_ROSTER_FLOOR_PERCENT(默认一半)。 实测 2026-11-05 测试站目录一天之内从 100 人掉到 1 人,少了这一条,那一趟会把 98 个登录名统统刷成hub-lost-*)。让位只改账号名(hub-lost-<user_id>-<原名>):users.id、姓名、 状态、hub_user_id全不动,按主键挂的权限照旧,按账号存的引用跟着这一行搬(account_map记「原名 → 让位名」,不接链)。腾开的账号名当趟就归回 Hub 的现任主人,企业微信 UserID 也一并从僵尸行清空、当场写回 Hub 认定的现任号主。 要求「已停用」是有意的:这一趟刚发现查无此人时只停用,下一趟才动账号名,Hub 抖一下不至于 顺手把人改名。增量那条路(_apply_user_event)一次只搬来一个人,传默认的complete_roster=False,一个登录名都不许动 —— 否则一条企微同步事件就敢改全库的账号名。 改名与让位都计入该趟的updated(SyncStats.renamed_ids+ 让位人数),不然"这趟只改了 账号名"的同步在历史列表里会显示成「无变更」。 - 离职停用熔断(
_offboard_missing,OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT,默认 40)。 等着停用的人数(只数还没停用的)超过max(OA_HUB_SYNC_OFFBOARD_GUARD_MIN_PEOPLE, 本地同步账号总数 × 百分比)(默认 20 人)时,这一趟一个 都不停用,同步记录里报出「本该停用多少人」并把该趟标成partial。判成离职不可自动挽回: 下一趟同步只会把清单里的人重新启用,指错了 Hub 的那些人永远回不来。「清单为空就不写」 那道保险只管全空,挡不住「Hub 换了一套人也有一百人」。
「同步前体检」(GET /api/v1/hub/preview)与真跑共用同一套判据:会让位的账号不再算进
account_conflicts,另给 account_releases;offboard_pending 是这一趟真会停用的人数,
offboard_guard.tripped 说明熔断会不会挡下来,warning 里写清怎么核对。测试
scripts/check_hub_sync_lost_account.py 钉这二十三项。
6.1.2 同步记录要能核对:三类动作成列,名单进 details
一趟同步真正动过的人,以前只写在 oa_hub_sync_run.message 那段文本里,而那一列只留 2000 字:
测试站 2026-11-05 那趟让位 68 个账号、跟随 Hub 改名 14 人,同步历史里只看得见「更新 99 人」,
提示一多末尾还被裁掉半句,看完不知道该去核对谁。现在这三类会改到别人的动作各自成列,
名单与其余计数另存一份有界 JSON:
| 字段 | 含义 | 为什么单独摆 |
|---|---|---|
renamed |
这一趟真正换掉登录名的人数 | 历史单据是按账号存的,改名前的单会从「我发起的」「我的待办」里查不到 |
reclaimed |
已停用、Hub 又查无此人的账号让出登录名的个数 | 动的是别人的登录名,行本身不动 |
units_rebound |
Hub 换了 organization_id 之后按「编码 + 名称」认回原部门的个数 |
认错了就是两棵重名树,认对了才谈得上不裂树 |
details |
account_renames / name_renames / reclaimed_accounts / rebound_units(每类前 20 条)+ 各类完整总数 + counts / mobile / wecom / guards + notes(提示按条原文) |
名单被上限裁掉时报得出「共 N 条」;message 裁掉后半句也不丢信息 |
unchanged(界面上的「无变更」)把这三列一并算进去,只做了一次批量改名的那趟不再显示成没干活。
名单条数上限 DETAIL_ITEM_LIMIT 只防一条 JSON 装下上千个名字,计数不受它影响;增量轮询每几十秒
就记一行,所以这里只放小字段,不塞清单本身。测试 scripts/check_hub_sync_details.py。
6.2 Hub 管骨架,本地管扩展
组织同样是全量同步,但接管范围划得很清楚:
| 归谁 | 字段 |
|---|---|
| Hub | name、code、status、parent_id(层级挪动连带重算子树 path 与部门 DN) |
| 本地 | alias、description、order_number、manager_person_id,以及挂在任何部门下面的自建部门 |
配套行为:
- 界面上改 Hub 部门的名称/编码/状态/上级会被当场拒掉(放过去也只是让下一趟同步盖回来),
改负责人、排序、说明、简称照改;
DELETE /org/units/{id}对 Hub 部门直接拒绝 ——hub_org_id一丢就再也对不回对方那个组织,下趟同步只会新建一个空部门, 负责人和按部门配的权限、审批规则全丢。 - 本系统自己先建了部门怎么办:同步时如果它的
code跟 Hub 某个部门一模一样、而这个编码 本地只用了这一次,就认成同一个部门(补写hub_org_id),部门主键与它身上的流程权限 原样保留;编码撞车就不猜,按新部门建并记进同步记录。这一条由系统设置「组织人员同步」组里的 「按编码认领本地部门」(OA_HUB_SYNC_BIND_LOCAL_BY_CODE)控制。 - Hub 把
organization_id整体换了号(重导数据、合并组织,实测测试站 2026-11-04: 25~36 变成 2~13):本地只按主键认部门,认不出来就会把整棵树再建一遍,界面上出现两个 「紫光汇智」,人搬去新行,而按oa_unit.id配的数据范围与审批规则留在老行上悄悄失效。 所以开了「按编码认领本地部门」时,编码与名称都对得上、而原主键已经不在这趟清单里的 老部门会被认回来(换新主键,本地oa_unit.id不动,子树与挂在这身上的配置都留在原地)。 编码或名称对不上就不认(不靠单一字段硬猜);这个编码名称已经被在职部门占了也不认 (那已经是上一次换号留下的重复,再认就出第三个);同名同编码的壳子有好几具时看谁底下 还挂着人,只有一支住人就认那一支(口径同解绑撞车主键时的「留人多的那支」),分不出来就 不猜、按新部门建并写进同步记录。 已经裂开的树不会自己合上,GET /api/v1/hub/preview用organizations.zombie_units把壳子数量与样例报出来并写进warning。以前只能一具一具「先解绑再删除」,现在GET /api/v1/org/units/shells列出这些壳子并逐条说明删不掉的原因,POST /api/v1/org/units/shells/cleanup一键清掉删得掉的那几具(判据见find_shell_units, 删除前逐条重算,不认前端传来的旧名单)。验收见scripts/check_hub_sync_unit_reclaim.py(21 项) 与scripts/check_hub_sync_shell_units.py(21 项)。 - 一趟要停用的部门超过
max(OA_HUB_SYNC_UNIT_OFFBOARD_GUARD_MIN, 同步部门总数 × OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT)时 一个都不停,只报数并把该趟标成partial(units_offboard_guarded)。停一个部门等于 把它下面所有人的数据范围与按部门配的审批规则一起摘掉,错一批比少停几个代价大得多; 底线默认 5 而不是人员那侧的 20,因为部门总数本来就比人少一个量级。 - 编码对不上又确实是同一个部门,用
POST /org/units/{id}/hub-binding手工绑定 (一个 Hub 组织只能对一个部门),反过来DELETE同一个地址解绑。解绑是唯一会清空hub_org_id的入口,解绑后这个部门改由本地维护,Hub 那边那个组织会被当成没同步过的 新部门重建一个。 - 本地自建部门挂在「Hub 已经消失或停用」的部门下面时,结构与状态都原样保留(Hub 只管
自己那一支),但同步记录与
/hub/directory/preview会把这类部门的数量报出来, 免得那条支路在 Hub 眼里断了没人知道。 uq_oa_unit_hub_org_id从库上兜住「一个 Hub 组织对出两个部门」。真有重复时保留人多的 那一支,多出来的行只解掉 Hub 主键变成本地部门,不删数据。
6.3 配好权限、角色之后再全量同步会不会坏
分两层看,结论是:按主键挂的权限一个不掉;按名字存的引用同步会帮忙搬走,搬不动的会点名。
- 不会掉的那层:权限角色
oa_person_auth_role挂users.id,数据范围按oa_unit.id递归算,部门负责人存manager_person_id,流程定义存部门/人员主键。同步不改主键、不删行、 不写users.role,所以配好权限再跑一百趟全量同步也是原样。前提是hub_user_id/hub_org_id唯一且不被清空 —— 上面两节做的正是这件事。 - 会悄悄失效的那层:审批岗位
oa_role.list_auth、岗位组oa_group.list_identity/list_person、流程环节审批人(oa_activity.config的taskValues)、流程可发起人 / 可见人 / 管理员、代理人、日程与网盘的共享名单和owner。这些存的是部门路径、部门名、 登录账号、姓名,运行时时现解析(service/org.py::_expand)。Hub 一改名、一挪层级、 一换账号,字符串就解析不到人了:环节审批人算出来是空的,流程卡在第一个节点,界面上 一个错误都不报。 - 所以同步收尾时在同一个事务里把这些搬到新值(
service/hub_refs.py):部门路径、账号是 照搬的;部门名与姓名要先过一遍歧义检查——解析顺序是 「人员账号/姓名 > 部门 > 审批岗位 > 岗位组」,旧名被人员占着、或新名字撞上 某人的账号/姓名时不搬(搬过去等于把审批人换成另一批人),只写进同步记录点名。 界面组织树里给 Hub 部门打了标记,被接管的字段直接置灰。 - 运行态那一层(
oa_work.creator_identity、oa_task.identity、表单里type=user那一格) 既不搬也不该搬:那张单记的是"当时的那个人",而它存的就是登录账号,同步改姓名、 改部门对它没有影响。以前它存的是身份 DN,同步一改名历史单据就整页消失,这就是换口径的全部理由 (见 person-reference-design.md;系统还在开发期,旧写法的 数据不做迁移,读侧也不再为 DN 留解析分支)。 - 唯一的例外是改登录账号:历史行按口径不跟着账号搬家,旧账号上压着的单会从「我发起的」 「我的待办」里查不到。同步不会偷偷改回去,但会在同步记录里数给你看("这几个登录账号改了名, 库里还压着按旧账号存的历史行:xxx(n 条)")。账号是本部署对外认人的业务键, 上游系统存的也是它——真要改账号,先确认 Hub 那边改的不是一个已经在别处被当外键用的编码。
- 同步前想先看影响面:
GET /hub/directory/preview的impact会给出这趟会改名的部门数、 会挪层级的部门数、会改账号/姓名的人数,以及refs_at_risk—— 配置里正好指着这些名字的 引用清单(岗位、环节、共享名单,带在哪个字段)。organizations里另有本地自建部门的规模:local_units/claimable_by_code/local_hanging_units。 - 停用不是删除:Hub 里消失的人与部门在本地都只是「已停用」,他的待办、已办、审批轨迹、
权限角色成员关系都还在;Hub 把人或组织加回来,下一趟同步自动接上(人员按主键重新启用,
部门按
hub_org_id重新启用)。真离职的人要清出去,走界面上的停用/删除,不靠同步。
6.4 组织层级怎么还原(Hub 是扁平下发)
organizations 有两种下发口径,本地都支持,判据写在 service/hub_sync.py::_org_tree:
| 口径 | 长什么样 | 层级从哪来 |
|---|---|---|
| 嵌套 | 父组织的 children 里带着下级 |
嵌套位置 |
扁平(真实 Hub 的 auth/directory) |
所有组织平铺成一张清单,children 是空数组 |
parent_id;没给就退到 path(/1/8/10/ 的倒数第二段就是上级) |
本地自己的 oa_unit.path 一直是 O2OA 口径的名称路径(紫光汇智\软件开发部\),
DN 是它的 o= 形式,Hub 的 id 路径不原样落库,只拿来还原父子关系;认完层级再按
本地口径重算 path 与 distinguished_name。(人的那一层只改 users.organization_id:
一人多身份那张档案副本表已经下线,部门路径与 DN 用的都是人员表上这一份当前口径。)
只认嵌套会怎样:扁平清单被当成一排根部门,界面上组织架构全平、path 与 DN 停在一级,
于是「本部门及下级」的数据范围、审批岗位里勾了「含下级」的部门、按部门路径存的引用
全部解析不到人 —— 同步记录是绿的,用起来处处不对。这就是这套还原逻辑存在的理由。
对不上号的情况一律不猜,写进同步记录让人去看:
- 上级不在这份清单里(Hub 删了上级或清单没带全)→ 按一级部门落库,记一条 「Hub 有 N 个组织的上级不在这份清单里」;
- 层级里出现环 → 断掉最外层那条向上的边,子树原样跟着走(连子树一并摘掉等于 把整支下级判成「Hub 里没有了」而停用);
- 同一个组织重复下发 → 只认第一次出现的那条。
审批岗位、共享名单这类按字符串存的引用,除了本地的部门名与 path,也认 Hub 的
id 路径(/1/8/10/ 或 1/8/10,取末段按 hub_org_id 精确匹配,见
service/org.py::_find_units),从 Hub 控制台复制过来就能直接用;这个写法不依赖
父级,所以那个组织之后被挪走也不用改。
想先看清这趟会不会挪层级:GET /hub/directory/preview 的 impact.moved_units
就是按这套口径算出来的「上级会变动的部门数」。
6.5 哪几个账号在 OA 里只读
人员页上有两类账号整行只读(徽标「只读」,鼠标停上去说明原因),三个动作全禁用; 接口侧同样拒绝,绕过界面直接调接口也改不动:
| 谁 | 凭什么被认出来 | 为什么锁 |
|---|---|---|
内置超管(本部署 localadmin) |
账号名等于库里记着的那个(system.admin_account;[seed] admin_account 只负责改名) |
应急入口。改掉账号名或停用它,Hub 一有动静就没有进门的路 |
统一身份的管理员(默认 admin) |
source='hub' 且账号名在 OA_HUB_SYNC_LOCKED_ACCOUNTS 里 |
名称/部门/启停归 Hub;再让人在 OA 里把角色挪走、或把名字改得和 Hub 对不上,等于把管理员身份悄悄搬到别人身上 |
配套口径:
- 名单上的账号名也不许在人员页先建同名账号。名字被本地占掉之后,Hub 把真人下发下来时
认领不上(本地那个号没有
hub_user_id,同步又不许抢别人占用的账号名),最后剩下一个 谁也对不上的假管理员。 - 要轮换应急口令,用本人的「修改密码」(
POST /auth/password),它不受这条限制 ——[seed] admin_password只在建号时生效,没有第二个入口。 - 只读只管界面:定时同步照旧按 Hub 的话改这些人的资料与启停。Hub 把管理员停用了, 本地跟着停用,这是数据主人的权利,不该被本地护栏挡住。
- 想放开:在系统设置「组织人员同步 - 统一身份的管理员账号」里把名字删掉,保存即生效。 内置超管那条不看这个配置,只认库里记着的那个内置超管账号。
7. 定时任务与补试(同步排期)
排期在系统设置 →「同步定时任务」(/settings/sync-jobs,system:setting)上配,
也可以直接 PUT /api/v1/config/hub_sync;存的是运行配置,改完下一轮调度判断就走新
排期,不用重启。
「允许定时同步」这一项(hub_sync_enabled)只在界面上配:配置文件与环境变量都不
参与取值(出厂模板里也没有这一行了,文件里残留的那一行会在启动日志里点名说"不生效"),
默认开着。它以前能被出厂值、部署模板或 scripts/purge_people_org.py 这类脚本关掉,
于是定时任务悄悄不跑、人在界面上只看得到"已关闭"——现在挡着的时候那句话会直接说清
在哪一格打开。同组的排期参数(OA_HUB_SYNC_WHEN 等)仍是"文件给出厂值、界面存过就以
界面为准"这一套。调度跑在应用自带的后台线程里(app/main.py 的 _scheduler_loop,
60 秒一轮),排期算法与到点判定集中在 app/service/sync_jobs.py,due_now 只是它
的一层转发 —— 页面上显示的「下一次执行」和后台判断用的是同一段代码,不会两边各算一套。
升级注意:以前在环境变量里写 OA_HUB_SYNC_ENABLED=false 的部署,升级后这一行不再
管用 —— 界面上没存过就是默认开着,定时同步会开始跑。要停同步就去界面上关那一格,或者用
仍然认环境变量的应急总闸 OA_HUB_DISABLED(它连登录一起回本地,见 §4)。
四档频率(OA_HUB_SYNC_WHEN):
| 档位 | 看哪些配置 | 排期含义 |
|---|---|---|
daily |
sync_time |
每天 HH:MM 跑一次(改造前的唯一口径,行为没变) |
weekly |
sync_time + sync_weekdays |
选中的那几天各自 HH:MM 跑一次 |
monthly |
sync_time + sync_monthdays |
选中的那几个「几号」各自 HH:MM 跑一次;当月没有 30/31 号就顺延到当月最后一天 |
interval |
sync_interval_minutes |
从上一趟跑完开始计时,隔够一轮再跑,不看 sync_time |
到点判定这几条四档通用:
- 没到排期点不跑;
- 这一趟已经有一条
trigger=schedule且状态为success/partial/skipped的记录, 不再跑(手动同步不算,trigger=manual不占排期的坑); - 失败了每隔
OA_HUB_SYNC_RETRY_MINUTES分钟补试,最多OA_HUB_SYNC_RETRIES次; - 停机错过了排期点,起来后的第一轮补跑一次 —— 但只在排期点之后 12 小时内
(
sync_jobs.LATE_GRACE_HOURS)。错过一整天的 monthly 不会在三天后突然补一趟, 而是等下一个排期。
配置写歪了不会让同步悄悄停掉:档位名不认识退回 daily,星期一个都没认出来退回周一
到周五,几号一个都没认出来退回每月 1 号。页面上也会直接说出这一趟被什么挡住了
(总闸关闭 / 未启用统一身份 / 没填站点地址 / 定时同步关闭)。
排期状态用 GET /api/v1/hub/schedule(org:person,只读)一次拿全:全量与增量两个
任务的 next_runs、口径说明、倒计时,以及最近执行记录。
跑成之后把 permission_version 记进 oa_system_setting 的 hub_directory 键,
下次版本没变就跳过写入。每次执行都在 oa_hub_sync_run 留一行,页面上的「同步
历史」读的就是它。
8. 一键实时同步
- 页面入口:人员管理 页头的「立即同步」按钮、系统设置 的统一身份卡片,以及
系统管理 → 同步定时任务 的执行记录。都在
org:person权限下才可见,未启用 Hub 时不渲染。 - 「终止」按钮只在判定卡住时出现,判据只写在
src/utils/hubSync.ts一处(后端自报running, 或后端重启后running已是假、但最近那条记录还停在running),页头与执行记录共用,免得两边口径不一。 - 接口:
POST /api/v1/hub/sync(org:person)。跟定时任务同一条代码路径,只是trigger=manual,因此不受OA_HUB_SYNC_SKIP_UNCHANGED影响,点了就真拉。 - 并发保护:同一进程里同时只允许一个同步,重复点击回
已有同步任务正在执行;跨副本那把 Redis 锁 挡下来时说的是另一句另一个副本(主机名:进程号)正在跑同步。两句说的是不同的锁,报障时先分清是哪 一句。增量同步与手动全量共用同一把锁,所以后台每几十秒那趟撞上手动点击是正常现象,等几秒即可。 拿锁之后、进收尾try之前那一段(写游标 + 建「进行中」记录)自己负责交还锁:这段漏出异常 (库断、表结构落后报Unknown column)会把本进程那把锁永久握着,症状就是"明明没同步、点立即同步 一直回已有同步任务正在执行",且历史里一条记录都没有。验收见backend/scripts/check_hub_sync_lock_leak.py。 - 「进行中」有两种卡法,各有各的出口。一种是没人收尾的残留:后端被 kill、容器被驱逐时,
oa_hub_sync_run里那条status=running再也没人改它,同步历史一直显示「进行中」,页头那颗 按钮也跟着一直按住。hub_sync.reap_stale_runs在后端启动时与GET /hub/status里各清一次, 判据是「开始超过STALE_RUN_GRACE_SECONDS(30 分钟)且没有任何副本持同步锁」——真在跑的同步 持着锁,够不着这一档。 - 另一种是想叫停真在跑的那一趟:页面上的「终止」按钮走
POST /api/v1/hub/sync/cancel(org:person)。它先request_cancel()落一个停止信号(进程内一份 + Redis 一份,存的是按下 那一刻的时间戳),再把挂着「进行中」的记录一律标成cancelled(grace_seconds=0,刚起步的也算), 然后用cache.force_release放行跨副本锁、再交还本进程那把线程锁,不必干等锁的一小时 TTL。 正在跑的那一趟在下一个检查点自己停手:拉完目录、写完部门、写完人员各一次,_sync_units/_sync_people每CANCEL_CHECK_EVERY(25)行一次,增量轮询每一轮一次;抛出HubSyncCancelled之后记录写成cancelled而不是failed——否则一次人为终止会被当成同步失败,接着被retry_minutes补试把刚叫停的活儿重新捞起来跑。 - 停止信号按时间戳比对(
cancel_requested(stats.started_at),即「这一趟开始之后有没有人按过」), 所以终止完马上重开的那一趟不会被上一趟留下的旧标记误停;标记本身CANCEL_TTL_SECONDS(一小时) 后自己消失。返回里stopping=true表示终止时确实有一趟在跑、它会在几秒内停手,false表示只是 清掉了残留。已写进库的人员与部门不回滚,下一趟照常从 Hub 全量重对齐。 - 返回:这次运行的完整汇总(新增/更新/停用/部门变更/人员总数/数据版本/耗时/说明), 前端弹结果框并顺带刷新列表。
- 手动同步会写一条操作日志(
hub_sync),在「操作日志」页可查。
8.1 增量同步:变更流水轮询
排期那趟全量是"每日校对",这一条负责把改动尽快落下来(对接指南 6.2、6.3):
后台线程(按 OA_HUB_SYNC_CHANGES_INTERVAL_SECONDS 醒) Hub
│ GET /api/v1/auth/directory/changes?since=<cursor>&limit=200
│ ── X-Directory-Key ──────────────────────────────────►│
│ ◄── changes[] + cursor + oldest_seq + newest_seq + has_more
│ 逐条幂等落库(upsert 按主键覆盖,delete 按主键软删)
│ has_more=true 就同一 cursor 接着翻,翻到 false 才提交游标
- 开关、周期、单批条数见 §4 的
OA_HUB_SYNC_CHANGES_*。 - 首次对齐:本地还没有游标时先在 Hub 侧探一次流水尾部(
newest_seq),记下它再改拉 一次全量,此后才按游标追。中间真有的改动会在下一轮增量里重放一次,都是幂等 upsert,无害。 - 游标只在批次落干净之后才往前推:中途抛错就原地不动,下一轮从原地重拉,不会出现 "流水没落库但游标已经跑掉";要回全量的那一批先丢掉,等全量盖完才推游标,全量没跑成则 游标继续留在原地。
- 什么时候回全量(
OA_HUB_SYNC_CHANGES_FULL_ON_GAP):since比 Hub 侧oldest_seq还旧(流水被裁剪、本系统停机过久)、组织变更事件只带id与status/parent_id(推不出父子关系)、或事件里的部门在本地压根没镜像到。 - 事件主键先认
entity_id,再按entity分支取键:data里的键名随来源变化 (source=hub用id,source=wecom用organization_id/user_id,对接指南 6.4 明说这个坑), 所以entity=user只在user_id/id里找,entity=organization只在organization_id/id里找,两边都不拿对方的字段凑数。人的补丁里organization_id是「调去哪个部门」,把它当人主键会使:轻则查无此人被跳过,重则把改动落到部门号那个 人身上。实体类型没带或不认识时才退回「挨个试」的老口径。 - 失败不影响业务请求:拉取失败只写运行态
changes_error加一条trigger=changes的 同步记录,并按OA_HUB_SYNC_RETRY_MINUTES退避重试。增量流不是唯一可信来源, 排期那趟全量每天照样整体校一次。 - 手动拉一次:
POST /api/v1/hub/changes/sync(org:person),人员管理页头的 「拉取变更」按钮就是它,与定时跑同一条逻辑,所以"落后过多会改拉全量"在这儿同样成立。 - 看进度:
GET /api/v1/hub/status的changes段回cursor/newest_seq/lag/poll_at/error;cursor是null表示还没与 Hub 对齐过(第一次必然回一次全量)。
9. 统一身份权限对接(角色 / 权限码 / 数据范围)
对应仓库根目录的《Hub 权限接口交互文档》(permission-integration.md)。那份文档只负责
查询:Hub 交出「这个人在这个应用里有哪些权限码、能看多大数据范围」,业务资源与最终的
数据过滤仍然由本系统自己判(那份文档第 9 节)。开关见 §4「统一身份权限相关」,实现集中在
app/service/hub_perm.py,取数客户端在 app/service/hub.py。
一句话概括设计:Hub 给口径,本地做判定,谁也不覆盖谁。Hub 的角色不会被写成本地角色,
本地角色矩阵(AuthRole)还是管理员手工维护的那一份;关掉 hub_perm_enabled 立刻回到
对接前的行为,库里什么都没动。
9.1 怎么问:先 /me/*,问不到再代查
同一个问题有两种问法,取决于本系统手上有没有这个人自己的 Hub 访问令牌:
| 场景 | 问法 | 用的凭证 |
|---|---|---|
| Hub 账号密码登录 | GET /me/roles + GET /me/permissions?application_id=xxx + GET /me/data-scope(第 5~7 节) |
本人登录换来的 Hub 访问令牌 |
| 统一门户免登、本地应急登录 | GET /admin/users/{user_id}/roles + GET /admin/users/{user_id}/data-scope(第 7、8 节) |
服务端同步凭证(目录密钥 / 长期 token) |
- 免登用户手上没有 Hub 令牌:门户票据校验只回
sub/account,不换发下游可用的 Hub 访问令牌,所以这条路问不了/me/*。打开hub_perm_admin_query(默认开)之后由服务端 拿同步凭证代查;关掉它免登用户就只用本地权限,这不算错误。 - 代查要
hub_user_id:账号必须在同步或首登时绑上过 Hub 用户(见 6.1),纯本地账号 代查不到,直接算「没问到」,按本地权限走。 - 角色 → 权限码这一跳要自己补:
/admin/users/{id}/roles只给角色,权限码得按角色逐个问GET /admin/roles/{role_id}/permissions。这张角色码表全员共用,进程内缓存一次就够, 保存 Hub 配置或点过一次登记之后整表清空。 - 服务端令牌问不到
/me/*:那份文档第 1 节写明/me/*认的是用户令牌,拿集成账号的 token 去问只会问到集成账号自己的权限。代码里不混用,也绝不拿没有sub的令牌去问/me/*。 - 本人的 Hub 令牌只在那一次请求的上下文里,不落库、不进缓存、不出接口。
9.2 缓存、权限版本与取不到时的退路
- 按人缓存
hub_perm_cache_seconds秒(默认 60)。那份文档第 3 节说得很直白:业务系统 可以自行缓存权限,但失效要自己负责 —— 所以界面上留了「重新拉取」,POST /api/v1/auth/permissions/refresh就是不等缓存过期的那一个。 - 取不到就按本地权限走,并给这个人 15 秒冷却,免得每个请求都去撞一次 Hub 超时; Hub 恢复后下一批请求自动回到正常口径。热路径上只有一次字典查找,网络调用发生在登录时、 缓存过期的那一次,以及管理员手动刷新时。
- 每次取数都把 Hub 的
permission_version原样带出来,界面上原样显示;对账时用它判断 「Hub 那边是不是刚改过」。
9.3 两种模式:shadow 与 enforce
shadow(默认)只把 Hub 的口径显示出来给管理员对账,判定仍按本地角色矩阵;enforce 才让
Hub 的权限码与数据范围真的参与判定。两条硬保险:
- 本地管理员永不被降级:内置超管与应急账号(见 5.1)是 Hub 配错时唯一还能进门的那条路,
is_admin为真时 Hub 的口径只显示、不改判定。 - Hub 一个本系统认得的权限码都没给时保留本地权限(
hub_perm_keep_local,默认开): 权限还没登记到 Hub、角色还没绑人的时候,严格照 Hub 判定等于把所有人锁在门外。真要 「Hub 说没有就没有」,把它关掉。
判定顺序(hub_perm.overlay):shadow / 本地管理员 / 「Hub 无可识别权限码且 keep_local」
三种情况一律不改;否则把 CurrentUser.permissions 换成 Hub 给的本系统认识的那部分权限码,
数据范围按 hub_perm_scope_mode 并进来(merge:本地与 Hub 两边给的部门都能看)或整份覆盖
(hub:以 Hub 为准,本地角色作废);Hub 权限码里出现 * 时数据范围直接给到最大。
两条路都走 CurrentUser.apply_scope(),改口径的同时把 data_grant 一起换掉,不让两者各说一套。
- 数据范围映射:
SELF→self、ORG→unit、ORG_AND_CHILDREN→unit_and_below、ALL→all;一个人多个角色时 Hub 自己取最大(那份文档第 6 节)。 custom只在本地有:Hub 那一层没有"勾一批部门"的说法,映射表里也没有它。于是merge模式下本地自定义角色勾的部门会跟 Hub 给的部门口径并存(并集),hub模式下整份 以 Hub 为准、本地勾的部门当场作废——想在界面上看出差别,看auth/me里那份hub_permission的applied与生效范围。- Hub 给了本系统权限目录里没有的 code:只列出来提醒,不参与判定。这类 code 多半是 Hub 上给别的应用登记的,或者本系统还没实现这个功能。
- 只读展示不影响判定:
GET /api/v1/auth/me的hub_permission带的就是这一份口径 (含applied与「没参与判定是因为什么」那句原因),任何界面想显示权限来源都不用再调一次接口。
9.4 权限目录对账与一键登记
GET /api/v1/hub/permissions/catalog 比两个目录:本系统 app/permissions.py:CATALOG 里的
权限码,与 Hub 上 application_id 这个应用登记的权限码(第 8 节)。
missing= 本系统有、Hub 上没有 → 界面上「登记 N 项」逐个POST /api/v1/auth/admin/permissions(type=api,展示名先用 code 本身,Hub 管理端可以改)。重复登记是幂等成功, 登记也不等于绑角色,绑人仍然在 Hub 管理端做。extra= Hub 上有、本系统目录里没有 → 只报出来,不做删除。- 登记需要服务端凭证在 Hub 上是管理员,普通集成账号会被拒(
403/403001)。 这是一次写操作,进操作日志(action=hub_permission),日志里只有 code 列表,不带密钥。
9.5 界面上在哪看
「组织管理 → 权限角色」页顶部的「统一身份权限」面板(HubPermissionPanel.vue,需要
system:setting):左边是我自己在 Hub 上的角色、权限码、数据范围、权限版本与取数方式,
外加一句「这次有没有参与判定、没参与是因为什么」;右边是目录对账与一键登记,再往下能按账号
代查,看某个人按当前口径实际会拿到什么。hub_perm_enabled 关着时整块面板不渲染 ——
没对接权限的部署看不到这块东西。
9.6 自检、按数据权限导出与失败口径
POST /api/v1/hub/probe 在原有步骤之后追加权限这几项:角色与权限(/me/permissions,
没有用户令牌时改用 admin/roles)、权限目录对账、按数据权限导出人员。只有 enforce
模式下问不到才让整次自检判死:shadow 模式下 Hub 还没登记权限、集成账号不是 Hub 管理员,
都不该让自检红一片。
- 两个导出接口选哪一个(权限文档第 11 节):排期全量、一键同步、增量补齐走的都还是全量
GET /api/v1/auth/directory—— 本系统是受信集成,镜像的是整个花名册,停用的人也要拿到才能 把本地账号跟着停用。GET /api/v1/auth/directory/scoped只在自检里拉一次证明这条通了: 它与全量目录同结构,但人员按调用者数据权限过滤,而且忽略include_disabled_users(数据权限只覆盖启用用户),拿它做下线检测必然漏人。集成账号自己没被分配组织或数据权限 不可用时 Hub 回403001,自检把这一条记成「没问到」但不判死 —— 那不是本系统的毛病。 - 本系统对外的错误码:权限接口问不到 →
HUB_PERMISSION_UNAVAILABLE,点「重新拉取」时把 Hub 原话带回来,好过只说「失败了」。 - 数据范围问不到时
hub_scope是空串、界面显示--;此时enforce也只换权限码,不动 本地数据范围。
10. 状态与自检接口
| 接口 | 权限 | 用途 |
|---|---|---|
GET /api/v1/auth/captcha |
匿名 | 登录页验证码(转发 Hub;本地模式回 required=false) |
GET /api/v1/auth/sso/state |
匿名 | 发起免登:写一条随机 state 到 HttpOnly Cookie,回 state 与门户地址;免登没配齐回 SSO_DISABLED(见 5.2) |
POST /api/v1/auth/sso/login |
匿名 | 免登落地换本地会话:{ticket, state} → Hub 校验 → 按 sub 认人 → 发本地 JWT(见 5.2) |
GET /api/v1/auth/sso/callback(别名 GET /sso/hub) |
匿名 | 免登回调(后端落地口径):Hub 把浏览器 302 到这里,后端当场验票认人,再 302 回 /sso#code=<一次性短码>;失败 302 回 /sso?error=<稳定原因码>,全程不给 JSON、不回显票据(见 5.2.1) |
POST /api/v1/auth/sso/exchange |
匿名 | 用回调发出的短码换本地会话:短码 + 回调下发的 oa_sso_handoff HttpOnly Cookie 双要件,60 秒内用一次即废;出参同 /auth/sso/login,多一个 redirect(见 5.2.1) |
POST /api/v1/auth/session/touch |
登录 | 空闲超时心跳:只把刷新令牌的「最近活动时间」推到当下,不放行任何请求;没开 session_idle_minutes 时回 {idle_minutes: 0, touched: false}(见 5.3) |
POST /api/v1/auth/permissions/refresh |
登录 | 不等缓存过期,重新问一次自己的统一身份权限;对照模式下也照给 Hub 的口径,只是不参与判定(见 §9) |
GET /api/v1/hub/status |
登录 | 当前开关、模式、同步时间、凭证来源、上次同步结果,另有 sso(免登配齐没有、缺哪一项,并回出该去 Hub 后台填的三条落地地址 callback_url / alias_url / landing_url)、changes(游标、落后条数、上次报错)与 permission(权限这一层现在怎么配的,见 §9)三段。不回传任何密钥 |
GET /api/v1/hub/schedule |
org:person |
只读:同步定时任务的排期视图。全量与增量两个任务的频率口径、未来 3 次执行时间、下一次倒计时、被什么挡住、近 30 天跑了几个,外加最近的执行记录(见 7) |
POST /api/v1/hub/changes/sync |
org:person |
手动拉一次变更流水,与定时跑同一条逻辑(见 8.1) |
POST /api/v1/hub/sync |
org:person |
一键同步 |
POST /api/v1/hub/sync/cancel |
org:person |
终止这趟同步:给真在跑的那一趟发停手信号(有就叫 stopping=true),把没人收尾的「进行中」记录标成「已终止」、强制放行同步锁,返回收尾了几条与两把锁的情况(见 8) |
GET /api/v1/hub/sync/runs |
org:person |
最近 N 次同步记录:除各类计数外还回 renamed / reclaimed / units_rebound 与 details(改名与让位的名单、熔断挡住了多少、按条原文的提示,见 6.1.2) |
GET /api/v1/org/units/shells |
org:unit |
列出 Hub 换过主键之后留下的空壳部门,逐条给出删不掉的原因(挂着人 / 有下级 / 被权限角色当数据范围)(见 6.2) |
POST /api/v1/org/units/shells/cleanup |
org:unit |
一键清理这些壳子:{"ids": [], "dryRun": false},ids 留空 = 清掉全部符合条件的;删除前逐条重算判据,dryRun 一行都不动,真删时写一条操作日志(org_unit_shell_cleanup) |
GET /api/v1/hub/directory/preview |
org:person |
只读体检:拉一次全量做对比,给出本地会新增/认领/停用多少,不写库、不记同步记录 |
POST /api/v1/hub/probe |
system:setting |
连通性自检:全量目录接口(用目录密钥拉一次)+ 密钥/同步凭证 + 登录验证码逐项体检;带 {"values": {...}} 就按这份还没保存的草稿测,不落库 |
GET /api/v1/hub/config |
system:setting |
统一身份配置页数据源:生效值 values、每一项的完整元数据 items(含 env 名、范围、来源、env_locked)、中文名 labels、说明 hints、来源 sources、被环境变量钉住的 env_locks、密钥只给 secret_set 布尔,另有 config_file 指向库里那一行 |
PUT /api/v1/hub/config |
system:setting |
保存并立即生效。{"values": {"项": 值}},只写改动过的键,值传 null = 改回出厂值;校验不过整批不写(HUB_CONFIG_INVALID);改动写操作日志(hub_config),不带密钥值 |
GET /api/v1/hub/permissions/status |
system:setting |
权限对接的当前口径(十六项配置、生效的九条路径、缓存占用)加上「我自己」问到的 Hub 权限(见 §9) |
POST /api/v1/hub/permissions/self/refresh |
system:setting |
立刻重新问一次自己的权限;问不到时把 Hub 原话带回来(HUB_PERMISSION_UNAVAILABLE),不只回一句「失败了」 |
GET /api/v1/hub/permissions/preview?account= |
system:setting |
代查某个本地账号:Hub 那边给了它什么,以及它按当前口径实际会拿到什么(权限码 + 数据范围) |
GET /api/v1/hub/permissions/catalog |
system:setting |
本系统权限目录 vs Hub 上这个应用的权限目录,missing / extra 两个差集 |
POST /api/v1/hub/permissions/catalog/register |
system:setting |
把 missing 那几项登记到 Hub(幂等,登记不等于绑角色)。写操作,进操作日志 action=hub_permission,只记 code 列表 |
GET /api/v1/config、GET|PUT /api/v1/config/{组} |
system:setting |
全站配置入口(hub / hub_sync / hub_perm 只是其中三组),语义与上面两个一致 |
POST /api/v1/config/reload |
system:setting |
丢掉进程内取值快照立刻重读,多实例部署时想立刻对齐可以用它 |
「立即同步」按钮旁就是「同步前体检」与「拉取变更」:正式同步前先看规模和差异,尤其是
member_limit 是否会把人员清单截断(truncated=true 时体检会把警告原样报出来)。体检对话框
把会动到什么直接摆成数字格子:这趟真停用多少人/多少个部门(offboard_pending,被熔断
挡下就是 0)、熔断线在哪(offboard_guard,写清百分比与"不少于 N"那条底线一起算出来的上限)、
会有几个登录名跟着改名(account_renames)、几个僵尸账号让位(account_releases)、
几个登录名撞车(account_conflicts)、几个重名壳子部门(zombie_units,点名到名字)。
account_releases_allowed=false 时对话框里会说明为什么这趟一个登录名都不动。壳子那几具
旁边直接给「清理 N 个空壳部门」:后端没回 zombie_units_deletable、或每一具都还挂着删不掉的
原因(zombie_unit_samples[].blockers)时不摆这颗按钮 —— 不拿全部壳子去赌删除安全。删完当场重新体检。
「同步定时任务」页在排期与增量之外多了一段同步落库口径:同步部门、带上已停用的组织、
按编码认领本地部门、离职停用、离职停用熔断(%)与它的人数底线、部门停用的个数底线、
让已查无此人的账号腾出登录名、让位名单的清单人数下限(%)、版本没变就跳过、
保护本地自建的管理员、单次导出人员上限、建号补全域名、统一身份的管理员账号。
三条底线以前是代码里的常量(20 / 5 / 50%),几十人的团队和上千人的部署被同一条线拦着,
想调只能改代码发版;现在跟百分比一样是配置项,取值与出厂默认值是否走偏由
scripts/check_hub_sync_details.py 钉住。这些配置项本来就在
PUT /api/v1/config/{组} 里能改,只是界面上看不见——清过库或换过站点的人不知道自己站在
"会停人、会改登录名"这一档上,下一趟全量就把人停掉了。标签与说明取自 dbconfig,
保存时按每一项自己所属的组分别提交(hub_sync_include_disabled_units 挂在 hub 组下,
混进 hub_sync 那一批会被后端按"不认识的配置项"整批打回)。
GET /hub/status 里的 breaker 是熔断与在飞闸门现在的样子:cooling / secondsLeft
(是不是还在冷却、还剩几秒)、inflight(此刻几条线程卡在等 Hub)、blockedTotal /
refusedTotal(累计挡下过多少次,只看趋势)。界面上那句「统一身份服务不可用」到底是刚
真试过、还是被冷却挡下的,看这两个字段就知道,不用猜。见 §14。
11. 数据库变更
首次启动自动补齐,不需要手工执行 SQL(app/db.py:ensure_columns):
| 表 | 新增 | 用途 |
|---|---|---|
users |
source(local/hub)、hub_user_id、hub_synced_at |
账号归属与同步水位;hub_user_id 上是唯一索引 uq_users_hub_user_id(NULL 不参与唯一性,本地账号照样可以为空) |
users |
wecom_user_id |
企业微信 UserID 的本地镜像(varchar(190) NOT NULL DEFAULT '',空串 = 没有)。只有人员同步会写它,界面上改不动、也不参与登录与身份判定;开发库实测落库 98/100 个统一身份账号(Hub 没带这个键的 2 人为空)。不建索引——唯一的反向查询是同步写入前判一次「这个号有没有挂在别人身上」,而全量同步本来就整表读进内存,等真出现按企微号搜人的接口再加 |
oa_unit |
hub_org_id、code、status |
组织映射键(唯一索引 uq_oa_unit_hub_org_id)、组织编码、启停(status 取代老的 enabled 布尔列,老值启动时自动搬过去后删除老列) |
| 消费口径 | 组织树 / 部门列表 / 设计器审批人目录 | 三处都按 status 出数:树里带停用徽标,GET /process/approvers 的部门项带 status/status_label,停用的部门在选审批人来源时看得出来 |
oa_hub_sync_run |
新表 | 每次同步的执行记录(含 credential、member_limit、truncated、units_offboarded),兼作定时排期的幂等凭据 |
oa_sso_handoff |
新表 | 后端免登回调发出的一次性短码(code_hash 唯一、bind_hash 绑浏览器、redirect、expires_at、used_at)。只存哈希,60 秒即失效,过期一条随下一次发放顺手清掉(见 5.2.1) |
两个唯一索引由 app/db.py:ensure_indexes() 在启动时补建(create_all 只在建表那一刻
生效)。老库里真有更早那版「按账号认领」留下的重复主键时,先按 6.1 / 6.2 说的解掉重复行
再建索引;万一还是建不起来,只记一条 warning 日志,不阻断启动。被取代的两个老普通索引
(idx_users_hub_user_id、ix_oa_unit_hub_org_id)会在同一趟里删掉。
oa_system_setting 里的键:hub_directory 存 permission_version 等同步运行态;
config:hub、config:hub_sync 与 config:hub_perm 存界面上保存过的统一身份配置(逐键存,密钥原样存、
接口回显才掩码)。这两行是运行配置的一部分,同一张表里还可能有
config:site / config:security / config:storage / config:server。
再早的版本把统一身份配置整包存在 hub 键、站点信息存在 site 键、存储配置存在
runtime 键。首次启动时 app/dbconfig.py:migrate_legacy() 会把这三行里的字段
逐项并进对应的 config:* 行,然后把老行删掉 —— 升级不用手工迁数据,也不会出现
同一个配置两处生效。配置文件里的值不会被写进这些行,行里只有界面上真正保存过的项。
12. 排障
| 现象 | 先看 |
|---|---|
| 登录提示「统一身份认证服务暂不可用」 | curl 一下 OA_HUB_BASE_URL/auth/captcha;再看是不是超时阈值太小 |
| 提示里带「N 秒之内先不重复等它」或「先不排它的队」 | 这是熔断/在飞闸门在挡(见 §14),不是新故障。它在替你省掉一次次十秒空等:Hub 真挂了时,登录页被反复打开会把 worker 线程占满,连与 Hub 无关的接口都跟着排队。想确认 Hub 现在的死活就点「连通性自检」(自检绕开熔断,一定真试一次),或者看 GET /hub/status 的 breaker |
| Hub 挂一会儿,整个系统都跟着卡 | 先按上一行确认熔断与 OA_HUB_MAX_INFLIGHT 有没有被调成 0(关掉这两层就等于让所有线程一起去陪葬);再看 OA_HUB_TIMEOUT_SECONDS 是不是被调得很大 |
| 登录提示「验证码错误或已失效」 | 前端没带上刚取的那张验证码,或 Hub 的验证码有效期比用户填写时间短 |
| 验证码填错却提示「统一身份认证服务暂不可用」 | Hub 用的是不带 code 的 error 名口径(如 invalid_captcha)。已按「被拒」识别,会提示重新填验证码;若还是提示不可用,抓一次 Hub 的响应体看 error 是什么 |
同步/自检报 token已失效 或「需要目录密钥」 |
没配目录密钥:Hub 的目录接口只认 X-Directory-Key,在系统设置「目录密钥」里填上保存即可(不重启),或设 OA_HUB_DIRECTORY_KEY |
同步/自检报 集成密钥无效 |
密钥填错了(粘了空格、粘了头名、或 Hub 那边换过一把);界面上重填一次,GET /api/v1/hub/status 的 credential 应变成 directory_key |
状态接口里 credential: anonymous |
目录密钥和 Bearer 凭证都没配:只有对方明确不校验目录接口时才拉得到,否则会一路报 401 |
| 自检里「同步凭证」这项红 | 配了 OA_HUB_SERVICE_* 但凭证已失效;配好目录密钥就不依赖它了 |
| 同步报「Hub 返回的人员清单为空」 | 凭证权限不够或 Hub 数据异常,这一趟已自动放弃,本地未被改动 |
同步结果 partial |
人员清单被 member_limit 截断,调大 OA_HUB_SYNC_MEMBER_LIMIT |
| 某个 Hub 有账号的人进不来 | 看 OA_HUB_LOGIN_MODE 是不是 hub,以及 OA_HUB_AUTO_PROVISION 是否被关 |
| 本地超管登录不上 | 内置超管不需要出现在「应急账号」名单里也能走本地口令,先确认登录用的账号名是不是库里 system.admin_account 记着的那个(改过名就用新名字),再确认口令 |
Hub 的 admin 同步不进来 / 认领不上 |
本地有个同名的内置超管挡着(应急通道 + 保护本地管理员两道护栏)。按 5.1 把内置超管改名成 localadmin,admin 就让出来了;同步记录里那句「跟本地应急账号同名」就是这个意思 |
| 界面上存了配置像没生效 | 先看该项的来源标记:env = 被环境变量钉住了(界面上是灰的),file = 值传过 null 改回了出厂值,database 才是界面上存的那份。再看 GET /hub/status 的 forced_off(应急总闸开着时界面值一律让位,forced_off_locked 说明它是不是被环境变量钉住的) |
| Hub 挂在网关后面 / 换了路径前缀 | 登录那十个接口路径都是配置项:在「统一身份登录」里改「接口路径:xxx」保存即可(或改 config.toml 的 [hub.api] 再重启),不用改代码;权限那九条同理,见 §4 第二张路径表 |
| 自检里接口路径看着不对 | GET /hub/status 的 api_paths 是当前真正在用的登录十条路径,权限那九条在 GET /hub/permissions/status 的 config.api_paths;步骤名里也带着路径,对照一下就知道是站点地址错了还是路径错了 |
改了 config.toml 没反应 |
出厂值只在启动时读一次,要重启;而且这一项如果在界面上保存过,库里那份一直压着它 —— 想听文件的先在界面上点「改回出厂值」 |
| 另一台实例没跟上 | 每个进程各自缓存,最多 OA_CONFIG_CACHE_SECONDS 秒(默认 2)后自己跟上;要立刻对齐就 POST /api/v1/config/reload |
| 保存完谁都登不进来 | 内置超管走本地口令进得来,在「系统设置 → 统一身份应急总闸」把开关打开保存,登录立刻回本地;连界面都进不去时才在服务器上设 OA_HUB_DISABLED=true 重启(效果一样,但界面上的开关会被它钉成灰的)。OA_HUB_LOCAL_ACCOUNTS 里的账号本来就不受影响 |
保存报 HUB_CONFIG_INVALID |
message 就是没过的那一项(地址格式、HH:MM、人员上限 1–5000 等),整批都没写库 |
| 免登点卡片提示「统一门户拒绝了本次免登请求」 | Hub 那侧的密钥或应用编码不对(对接指南 4.5 的 401/403/404 都归到这一句):curl -X POST -H 'Authorization: Bearer <admin token>' https://<本系统>/api/v1/hub/probe,看自检里「免登票据接口」那一项怎么说;Hub 轮换过密钥就重新填 OA_HUB_INTEGRATION_KEY |
| 免登提示「免登校验未通过:…」 | state 没对上(对接指南 5.2):打开了 OA_HUB_SSO_STATE_REQUIRED 又是不带 state 的门户直跳,或者 Cookie 被浏览器当第三方 Cookie 挡了。要么让门户把 state 带回来,要么关掉这一项 |
| 免登提示「这张票据不是发给本系统的」 | hub_app_code 与票据所属应用不是同一套:应用编码与免登应用密钥要成对配 |
免登提示账号已停用(user_inactive) |
预期行为:Hub 说这个人停用了,本地账号会被停用、刷新令牌被清空,要恢复先在 Hub 启用 |
免登压根没启用:落地页显示「统一门户免登还没有启用」,日志里一行 免登回调被拒(SSO_DISABLED) |
三件套没配齐(对接指南 5.2 的"配不齐就等于没开")。GET /api/v1/hub/status 的 sso.missing 直接点名缺哪几项:Hub 站点地址、本系统的应用编码、免登应用密钥。界面上补齐保存即生效,改 config.*.toml 要重启 |
回调(GET /api/v1/auth/sso/callback 或别名 /sso/hub)回的是 302 而不是 JSON |
预期行为:回调是浏览器整页跳转过来的入口,失败一律 302 /sso?error=<稳定原因码>,句子由前端语言包说。error 码表见 app/api/auth.py:LANDING_REASONS,前端映射见 frontend/src/views/auth/ssoErrors.ts,落地页角落也把码原样显示出来供报障 |
回调报 SSO_TICKET_INVALID / SSO_TICKET_EXPIRED |
手搓的票据、旧的票据、刷新过的落地地址都会这样:票据只能由 Hub POST /auth/apps/{code}/launch 签发,默认 30 秒过期、先查即删,回门户重新点一次卡片即可 |
兑换短码报 SSO_HANDOFF_INVALID |
后端回调发出的短码 60 秒过期、只能用一次,还必须配着回调当场下发的 oa_sso_handoff HttpOnly Cookie:把落地地址发给别人、换浏览器打开、浏览器挡了 Cookie,都会是这个结果,回门户重新点一次 |
Hub 上 launch_url 照《对接指南》举例填了 /sso/hub,点卡片却只剩一张空页 |
老版本前端只有 /sso 这一条路由,没有这个后端别名;升级到本版本即通(/sso/hub 与 /api/v1/auth/sso/callback 是同一个入口),或直接把 launch_url 填成完整回调地址(见 5.2.1) |
| 门户里看不到本系统卡片 | Hub 侧应用未启用/未可见,或「可访问角色」没勾到用户所属角色(未授权的应用对所有人隐藏,管理员也不例外)。这一步在 Hub 管理端,本系统帮不上 |
changes.cursor 一直是 null |
还没与 Hub 对齐过:第一趟会探流水尾部并回一次全量,全量没跑成游标就不会出现。看 changes.error 与那条 trigger=changes 的同步记录 |
changes.lag 越差越多 |
变更量超过单批消化能力:调大 OA_HUB_SYNC_CHANGES_LIMIT(Hub 上限 500)或缩短周期;since 落到 oldest_seq 之前会自动回全量,实在追不动点一次「立即同步」 |
| 增量同步之后部门层级看着不对 | 组织变更事件不带 path(对接指南 6.4):收到 status / parent_id 类事件时本系统会改拉一次全量,前提是 OA_HUB_SYNC_CHANGES_FULL_ON_GAP 开着 |
组织架构是一排平级的部门、path 与部门 DN 对不上 |
Hub 是扁平下发(层级只在 parent_id 与 id 路径 path 里),见 6.4;升级到按 parent_id 还原层级的版本后重跑一次同步即恢复 |
| 同步把某人停用了 | 看 oa_hub_sync_run.message,再确认 Hub 那边该账号的 status 与是否在清单里 |
| 同步把某个部门停用了 | 只有 hub_org_id 不为空的同步部门会被停用;本地自建部门不受影响,被停用也不会删 |
| 在 OA 删了人,再去 Hub 把他停用,回来同步毫无反应 | 必然的:Hub 的目录接口不下发已停用人员,人在 Hub 停用后不在清单里;本地这行又已经删掉、hub_user_id 锚点没了,没有任何东西能对上号。恢复办法见 6.1:让 Hub 把人启用回清单,下趟同步自动重建一条新主键(权限重配);日常请用「停用」而不是「删除」 |
| 同步的停用数一直是 0,人却确实少了 | 停用只可能来自「这次不在清单里」,status != 1 那条分支永远走不到(Hub 不下发停用人员),核对一下 total_users 与本地同步账号数 |
| 权限面板整块看不见 | hub_perm_enabled 关着就是不渲染(没对接权限的部署不该看见这块东西)。GET /api/v1/hub/permissions/status 的 config.enabled 会告诉你它到底开没开 |
| 面板显示「未生效」 | config.active 是 hub_perm_enabled + Hub 总闸 + 站点地址三者与的结果,任一项没齐就只是配了、没在问 Hub |
| 权限面板说「没问到统一身份权限」 | 先看 me.source:空 = 一次都没问到。免登用户没有 Hub 令牌,要靠服务端代查,检查 hub_perm_admin_query 是否被关、这个账号有没有 hub_user_id(见 6.1);纯本地账号本来就代查不到,按本地权限走是对的 |
开了 enforce 之后有人什么都点不动 |
多半是 Hub 那边权限没登记或角色没绑:hub_perm_keep_local 只挡得住「一个可识别权限码都没给」这一种,给了一部分就照那一小部分判。先用 shadow + 代查把口径看清楚,再切 enforce |
| 权限登记按钮点了报被拒 | POST /api/v1/auth/admin/permissions 要求服务端凭证在 Hub 上是管理员(回 403 / 403001)。换成 Hub 管理员的密钥,或者干脆在 Hub 管理端手工登记 —— 本系统不认识的那些 code 只能在那边绑角色 |
| 面板上有「本系统还不认识的权限码」 | 预期行为:Hub 给了但本系统权限目录里没有的 code 只提醒不生效,多半是 Hub 上给别的应用登记的,或本系统还没做这个功能 |
| 自检里权限那几条红 | 只有 enforce 模式才把它们算成自检失败;shadow 模式下这些步骤只报问题不判死。集成账号不是 Hub 管理员时 admin/* 那几条本来就是 403,/me/* 照样能用 |
| 「按数据权限导出人员」那一条报 403001 | 集成账号自己没被分配组织/数据权限时 Hub 就该这么回(权限文档第 11 节),自检不因此判死 |
| 人在 Hub 改了权限但 OA 里没变 | 默认按人缓存 60 秒:等过期、点面板上的「重新拉取」,或让那个人调 POST /api/v1/auth/permissions/refresh。Hub 那边还要看 permission_version 有没有真的变 |
| 刚才是好的,Hub 抖了一下之后权限就没了 | 取不到就按本地权限走,并有 15 秒冷却;Hub 恢复后自动回到正常口径,不需要重启 |
关掉 hub_perm_enabled 想回老行为 |
立刻回到对接前:本地角色矩阵从没被 Hub 覆盖过,本系统也不存 Hub 的用户令牌 |
13. 验收
先说一句现状:下面这几条挂在
backend/tests/上,那个目录已经不在了(2026-10 清掉的), 所以这一节目前跑不起来,留着是说明这一层原本验到哪。眼下真能跑的替身只有这几条:python3 scripts/check_hub_breaker.py(熔断与在飞闸门,见 §14,不连库不碰真 Hub)、python3 scripts/check_notify_hub.py(企业微信推送那一层,见 §15,进程内起一台假 Hub, 预算、幂等键、逐人原因分档、请求级错误全在里面) 与python3 scripts/check_binding.py(取数与候选来源那套校验口径)。 推送这一路还多一条连着开发库跑接口那一层的:python3 scripts/check_notify_hub_api.py(真TestClient+ 假 Hub,验notify/meta、渠道保存校验、测试发送带深链、回查与补发)。 桩服务那一整套(登录、免登、回调、权限对接、配置分层)要恢复得先把测试脚手架补回来。
一条命令拉起 Hub 桩服务 + 一套临时库上的后端,跑完自己收干净(会自建自删
unis_oa_hubtest 库,不碰开发库):
cd backend
python3 tests/hub_integration.py # 456 项断言,自带三台 Hub 桩:默认路径(含权限接口)/ 网关路径 / 目录接口要密钥
python3 tests/hub_integration.py --keep # 跑完不关进程,便于手工复现
python3 tests/hub_integration.py --keep-db # 保留临时库
python3 tests/hub_integration.py --only test_flat_org_payload # 只跑一个用例,改完快速回归
python3 tests/local_admin.py # 对着在跑的后端验:只有一个本地管理员,账号名与名单都在库里
覆盖:验证码登录、答错/密码错被拒、Hub 判停用则拒登、首登自动建号、应急账号(含改名让位给
统一身份 admin 的部署与审批引用搬迁)、Hub 挂掉时本地口令兜底;
免登一整条链路(发起写 state、落地换会话、票据重复使用/过期/串号/人被停用四类失败、
sso 模式下账号密码通道关闭而应急账号仍可登录、state 强制校验那一档);
后端免登回调一整条链路(302 只带一次性短码且地址里搜不到票据、短码兑会话并真用得着那份令牌、
用过/换浏览器/过期/凭空编四种都兑不到、回调上 state 两层比对照样拦、票据被 Hub 拒时按稳定
原因码 302 回来、别名 /sso/hub 不被前端壳子接走、回调这条路也能首次自动建号、登录日志落在
兑换那一步、/hub/status 回出该去 Hub 填的回调地址);
Hub 把票据校验接口按 401/403/404 拒掉时(密钥不对、应用没启用、路径不存在)也都归成
「统一门户拒绝了本次免登请求」,并且提示里点名该查哪一项;
本地会话生命周期(开了空闲超时后访问令牌不超过窗口、公开配置把窗口告诉前端、心跳推一格、
窗口内刷新照常给新令牌、一动不动超窗要求重新登录、超时的刷新令牌就地作废);
统一身份权限一整层(Hub 口令登录问用户自己的 me/*、免登用户由服务端代查 admin/*、
数据范围四档翻译、Hub 独有的权限码只提醒不生效、代查同时回「按当前口径实际会拿到什么」、
目录对账与一键登记、重复登记幂等、问不到时不把人锁在门外、shadow 只展示不判定、
enforce 才改判定、口径在界面上改完保存即生效、自检点到角色/权限/数据范围与按数据权限导出);
增量同步(首次对齐必回全量、按游标逐条落库、has_more 翻到底才提交游标、流水缺口回全量、
组织 status/parent_id 事件回全量、source=hub 与 source=wecom 两种键名、
删除事件软删、拉取失败退避与手动 POST /hub/changes/sync);一键同步的建部门/code+status 落列/认领同名账号/停用/
下线不删行/Hub 删掉的部门被停用而本地自建部门不动/本地超管不受影响/截断时只写不撤;
接口路径全部来自配置:另起一台把接口挂在 /gw/sso/* 上的 Hub 桩,只靠配置文件的实例
照样能登录与同步,把站点地址改回默认那套桩(路径不变)自检必须报打不到,再把路径改回
默认值立刻恢复,全程不重启;GET /hub/status 的 api_paths 如实回显,改过的路径来源
标成 database;目录密钥单独立一组用例:另起一台"目录接口必须带 X-Directory-Key"的桩
(缺头回 token已失效、头不对回 集成密钥无效,与线上一致),没配密钥的实例同步必须失败
且提示说的是密钥,界面上存进密钥不重启就同步成功、同步记录写 credential=directory_key,
换成错密钥立刻报错、改回来立刻恢复,接口返回值与自检结果里都搜不到密钥明文;
不带任何凭证的实例(桩不校验密钥那套)也能同步(credential=anonymous);同步前体检
只读不写并如实报截断;定时任务的到点、跳过与补试口径;还有配置的分层——只靠配置文件
起来的实例(不给任何 Hub 环境变量)在界面上打开就能登录、配置文件里的值不入库、
库里只有界面上保存过的项、密钥不回显、非法值整批不写、值传 null 改回出厂值、
环境变量压过库里、OA_HUB_DISABLED 压过界面值。
端口默认自动挑一组空闲的(主实例 + 匿名同步实例 + 只靠配置文件的实例 + 接口路径实例 + 目录密钥实例 + 仅免登实例 + 免登错密钥实例 + 票据拒绝码实例 + 空闲超时实例 + 权限对接实例 共 11 个,Hub 桩三台), 被占用时会直接说清是哪个端口,不会拿旧实例的应答糊弄断言。
配置分层本身的 108 项断言在 tests/config_db.py,与统一身份无关的那部分在那边跑。
14. Hub 不回话时,怎么不让它把整个系统拖住
这一节讲的不是"Hub 挂了怎么修",而是Hub 挂了之后本系统怎么自保。做这件事的动机是
一次实测:这台开发机上 hubtest.oa.unissense.tech 能连上 TCP 但不回话,于是登录页每次
打开都要空等满 hub_timeout_seconds(默认 10 秒)才报"服务不可用"。真正的问题不是慢,
是陪葬:同步接口跑在同一个 worker 线程池里(默认 40 条),44 个人同时打开登录页就把
池子占满,GET /org/tree 这种和 Hub 毫无关系的接口出现了一次 10 秒的卡顿,验证码自己的
p95 也从 10 秒涨到 20 秒(排在别人后面,等于等了两轮超时)。
两道闸,都在 app/service/hub.py,都是运行配置(界面上「统一身份登录」里改,保存即生效):
| 名字 | 配置项 | 管什么 |
|---|---|---|
| 冷却(熔断) | hub_breaker_seconds,默认 5 秒 |
有人已经因为 Hub 不回话而失败之后,接下来这几秒别再一起去撞。窗口内每 2 秒放一个请求去真试探,所以 Hub 恢复最多两秒就被发现 |
| 在飞上限 | hub_max_inflight,默认 8 |
同时允许几条线程卡在等 Hub 上。超出的先排 0.2 秒队,排不上立刻返回"服务不可用"。这一道管的才是同时冲上来的第一波——冷却是在第一次失败之后才生效的,第一波只能靠它限量 |
四条口径值得写明白:
- 只认"不回话"。连不上、超时、5xx 才进冷却;Hub 明确拒绝(账号密码错、验证码错)恰恰 证明它是活的,一格都不记 —— 否则用户多输错几次密码就能把 Hub "熔断"掉;
- 错误本身没换。被挡下的那一路抛的还是
HubUnavailable、还是retryable=True, 所以hybrid模式照旧回退本地口令、hub模式照旧报HUB_UNAVAILABLE、应急账号照旧走 本地口令 —— 只是不再白等十秒; - 健康部署碰不到它。Hub 正常时响应只有几十毫秒,0.2 秒的排队谁也排不上,行为等于没变;
真嫌管得宽就把两项调大或填
0关掉(填 0 就退回"所有线程一起去陪葬"); - 自检绕开它。「连通性自检」(
POST /hub/probe)是管理员主动问"现在通不通", 一定真去打一次,不会被冷却糊弄成"不可用"。
效果就是开头那一组数(一个进程、Hub 装死、44 个并发登录页):
| 加之前 | 加之后 | |
|---|---|---|
| 验证码 p50 | 10.0s | 0.23s |
| 验证码 p95 | 20.0s(等了两轮) | 10.0s(只有真在等的 8 个) |
同时打 GET /org/tree |
出现一次 10.0s 卡顿 | p50 15ms / 最大 269ms |
行为由 scripts/check_hub_breaker.py 钉住:本地造一个"接了电话不说话"的假 Hub,
把「第一次照等、之后立刻回错、每 2 秒放一个探测、自检绕开、恢复即清零、被拒不算失联、
并发第一波最多陪葬 N 条线程、Hub 正常时并发全过、填 0 整层关掉」九条逐一验过,
不连库也不碰真 Hub,随时能跑。
15. 企业微信消息推送(Hub 代发)
对接文档 9.6 那一套。本系统只负责说清"这句话该对谁说、点开该落到哪一页",
Hub 负责把它换成企业微信的应用消息投出去、认出点卡片的人、再签一张一次性票据把人送回来。
本系统不持有企业微信密钥,不实现企业微信授权,也不接触 code 与 access_token,
与「企业微信只对接 Hub,下游不需要企微凭证」这条边界(third-party-integration.md §7)一致。
15.1 三件事各自落在哪
| 对接文档要求的事 | 本系统的落点 |
|---|---|
| 发通知时调一次 HTTP | 「消息通知 → 企业微信(经统一身份 Hub 推送)」渠道(hub_wecom)。写通知的入口还是 engine.notify(),入队与站内信同一事务,真发在后台调度线程里:service/channels.py::_hub_send → POST {hub_base_url}{hub_path_notify_wecom},请求头 X-Integration-Key |
在已有的免登落地端点里读 redirect 并跳一下 |
不用新增端点:GET /api/v1/auth/sso/callback(别名 /sso/hub)本来就接 redirect,只放行站内路径(sso_handoff.safe_path),验完票发一次性短码 302 回 /sso#code=…,前端换会话后照 redirect 落页。推送链路与门户免登只差这一个参数,state 为空是正常的(见 5.2) |
| 保存 Hub 回传的逐人投递结果,留作自己的重试队列 | oa_notify_delivery 每个收件人一行,本身就是退避重试队列(60s / 5min / 30min,用满进死信);Hub 那份逐人明细原样存在 response.hub 里,界面上看得见原因、企微号与那条永久链接;「回查送达」按钮走 POST /notify/deliveries/{id}/recheck → GET {hub}{path}/{msg_key}(9.6.7,只读、可反复点) |
15.2 渠道要配的东西少到只有四格
站点地址与应用密钥不在渠道上,跟着「系统设置 → 统一身份」走,与免登换票、目录导出
共用同一把(hub_integration_key)——一把密钥冒充不了另一个系统发消息。渠道上只有:
| 配置 | 默认 | 说明 |
|---|---|---|
msgtype |
textcard |
textcard 是卡片 + 可点链接,markdown 是纯文字提醒。没有单据可指的事件(会议提醒)会自动退成 markdown,免得发一张点开没反应的卡片 |
with_link |
true |
关掉就是纯提醒:不带 target_path,Hub 那边不生成链接、也不占用深链 |
title_limit |
64 |
留给自己的标题额度。Hub 会在标题前强制加 【应用名称】,两边合计 ≤128 字符,超长是 400 整条被拒(不是替你截断)。本系统不知道自己在 Hub 上叫什么,所以默认只敢用一半 |
receiver |
["user_id","account"] |
按哪一列认人,顺序即优先级,见 15.3。Hub 只认 user_id(本地 users.hub_user_id)与 account(本地 users.account)两种标识,写第三种保存时就挡下 |
markdown 有一个只能靠人记住的脾气:它在企业微信微工作台里不展示(对接文档 9.6.9
自查清单那一条)。会话里照样收得到,但人想"事后翻出来再看一眼"时在工作台里找不到它。
所以要留痕、能回看的(办结、超时、待办)用 textcard,只图一眼可见的瞬时提醒才换
markdown——这一条本系统查不了,也没法替谁兜住。
事件订阅(待办 / 催办 / 阅件 / 办结 / 超时 / 会议)与其它渠道同一套勾选,收件人也不单独配: 站内信发给谁,这一路就发给谁。
15.3 收件人:按哪一列认人是渠道上可配的一项
发给谁不用配:站内信发给谁这一路就发给谁(engine.notify() 传的那串人员引用就是
登录账号,口径见 service/personref.py)。要配的只有用哪一列向 Hub 要到这个人——
渠道上 config.receiver 那根数组,顺序即优先级:
| 取值 | 本地列 | 脾气 |
|---|---|---|
user_id |
users.hub_user_id(目录接口的 entity_id) |
Hub 的人员主键。账号能被别人注册走、姓名会改、登录名也会在 Hub 侧改,只有它从头到尾指向同一个人,所以默认押它 |
account |
users.account |
区分大小写的精确匹配,2026-10-20 起还会随企业微信「Hub账号」扩展属性被同步改写(9.5),押它迟早对不上;但主键没同步过来的环境只有这一条路 |
界面上给四档(channels.HUB_RECEIVER_PRESETS):Hub 用户 ID 优先(默认,
["user_id","account"])、登录账号优先、只认 Hub 用户 ID、只认登录账号。
只勾一种就不退回另一种——那是管理员明确说过"只按这一列发",宁可把这个人跳过并在
投递记录里写明"按渠道配的收件人标识(…)取不到值",也别悄悄换成另一列把消息送错人。
认不出的取值保存时就 400 挡下(写错一个字母的代价本来是"这个人静默收不到")。
要加一种标识只需三行:HUB_RECEIVER_FIELDS(名字与本地列)、HUB_RECEIVER_VALUES
(怎么取值)、HUB_RECEIVER_SQL(覆盖数怎么统计)。渠道配置、入队、发送、回查、
界面清单都跟着认它,Hub 那边多认一种标识时不用改别的。
落库与排查跟着这一档走:
oa_notify_delivery.target_field记target那一串是按哪一列取的(user_id/account,其它渠道留空)。一串10086分不清是 Hub 主键还是某个人的登录名,而这两件事 的排查方向完全不同;升级前的老记录这一列为空,读的一路按值猜(纯数字只可能是主键), 口径与改造前一字不差。- 发送这一刻重认一次(
hub_target_for):入队之后又跑了一趟组织人员同步、或者管理员 刚把这一档换掉,排队里的记录就按新的口径发;发出去后把真正用的那一对标识写回记录, 「回查送达」才有得对(它拿target去比 Hub 回显的receiver)。人查不到(账号被删) 才回落到记录里那一对。 - 渠道列表带一份
hubCoverage:在职账号里每一种标识各能覆盖多少人、几种都试一遍能发到 多少人、怎么配都发不到的有几个。换档之前先在编辑框里看见这几个数,比投出一堆skipped再回头查便宜。
15.4 msg_key:跨重试不变,人工补发才换世代
msg_key = oa-<渠道编码>-<投递记录 id>。投递记录的 id 天生满足文档 9.6.4 那句话——
超时、进程重启、退避重发,键都不变,Hub 三选一(已投过回缓存 / 整批没投过重发 /
还在发回 409),本系统不需要判断"到底投没投出去"再决定换不换键。
只有一种情况要换:已经投出去过的那一条被人工重发。同键只会命中 Hub 的幂等缓存,
一个人也不会多收到,但界面会显示"已重发",运维以为发了其实没发。所以 resend() 检测到
response.hub.status 是 sent / partial 时把世代号加一,键变成 …-r2、…-r3。
15.5 逐人结果分档:Hub 的 reason → 本系统的状态
HTTP 200 + code=="200" 只代表 Hub 听懂了,收到没有看 recipients[].status。
一个人失败不带走同批其他人,而每条记录只有一个收件人,所以 Hub 的整体 status 在这里
不会见到 partial(真见到也按这个人自己那条算)。
Hub 的 reason |
落成 | 为什么 |
|---|---|---|
rate_limited、api_error、表外的未知原因 |
failed(按退避同键重发) |
稍后再试有可能成,宁可多试三轮 |
user_not_found、user_disabled、wecom_not_bound、wecom_rejected、unlicensed |
skipped |
这个人现在收不到,但不是故障:没认领、没绑企微、不在可见范围、缺许可。和"这个账号没有邮箱"是同一档,与失败分开统计,补完就地重发 |
invalid_message、quota_exceeded、daily_limit_exceeded |
dead |
重试一百次也不会成:正文/链接太长、当日配额用尽(次日重发)、这个人今天收满了 |
请求级 401 / 403 / 400 |
dead |
密钥不对、开关没开、参数不合法,改完才谈得上重发(400 说"应用未登记首页地址"时文案会点名 home_url) |
请求级 409 / 500 / 503、连不上 |
failed |
409 是并发保护、5xx 与网络是 Hub 的事,同键稍后重发是安全的 |
限流类原因是 Hub 在调企业微信之前拦下的(企业微信对超频消息静默丢弃不报错), 所以这些人是真没收到,同键整体重发不会让他们收到两条。
失败原因后面还会附一句企业微信自己说的话(wecom_errcode / wecom_errmsg),只在失败时
附一次。逐人 reason 说的是"哪一类",企微那句才是"具体哪一处"——真环境撞到的
81013 user & party & tag all invalid 就是这个人不在应用可见范围(或成员已离职),
拿那个码去企微 devtool 一查到底,比照着"通常是可见范围问题"猜快。
15.6 深链:只发相对路径,域名由 Hub 现拼
target_path 发的是站内相对路径:待办 / 催办 / 超时发 /todo/<task_id>(审批人自己的
页面,点开就能同意/退回),其余发 /work/<job>,没有单据就不带。绝不拼
site_front_url:Hub 按本系统登记的 home_url 在点击时刻现拼绝对地址(9.6.6),
本系统写死域名等于把域名焊进一条永久有效的链接里,以后换域名历史消息全成死链。
/todo/<task_id> 还多一道按人的闸:engine.notify() 对整批收件人只传一个 task=,
而那是个人页面,所以一人一条入队时 (channels.hub_task_links) 会核一下这条待办
到底是不是这个人的——不是(例如"外部审批那一环超时"同时知会兜底管理员,或那条待办
已经被办掉了)就把 task 抹掉,深链退回 /work/<job>。少这一道,管理员点开的是
"不是我的那条待办":审批页只读、按钮全灰。
链接本身不是凭据,是"应用 + 深链"的路由:同一张单据推十次用的是同一条链接,每次点击 现签一次性票据。转给同事点开是同事自己的身份,本系统的权限判定照旧——Hub 不管这个人 能不能看这条单据。
Hub 拼不出深链时不丢消息:本应用没登记 home_url(15.7)时,带 target_path 的
请求是请求级 400、整批一个人都不投。_hub_send 认出这一种就摘掉深链、换成
msg_key 的 -nolink 变体再发一次纯文字提醒(文档 9.6.2:target_path 留空就是
不带链接的提醒),记录里留 hub.degraded=hub_no_home,投递列表那格直接说人话。
管理员补上 home_url 之后新消息自动带回深链,不用重推历史。认不出来的 400
(标题超长那类)照旧判死、照旧只打一次——降级只多花一次调用,不会把一条真错的消息
反复重投。markdown 在微工作台不展示(15.2),所以降级这一条是"知道有单子"而不是
"事后还能翻到",home_url 该补还是得补。
Hub 用 Go 写时间,sent_at 没赋值时回的是零值 0001-01-01T00:00:00Z 而不是缺字段,
channels.hub_time() 一律当没填:投递记录里那句"发送于 0001-01-01"是假时间,
本系统自己那列 sent_at 用的是本地投递时刻。
15.7 Hub 侧的前提(本系统查不了,只能对着看)
GET /api/v1/notify/meta 会回 hub.ready / hub.missing,渠道页顶部就照着说;
下面这几条在 Hub 侧,任一没做,Hub 直接拒(投递记录里能看见原话):
- 全局推送开关 + 本应用
notify_enabled都开通(关一个就是403;PUT是整体覆盖, 编辑应用时漏传等于关掉); home_url已登记且不是站点根级文件(https://oa.example.com/index.html这种 会让深链拼成/index.html/todo/xxx,点开必打不开);launch_url指向/api/v1/auth/sso/callback(或别名/sso/hub);- 企业可信 IP 放行了 Hub 出口 IP、可信域名 = Hub 站点 origin 且不带端口、 应用可见范围覆盖全部收件人、成员基础接口许可齐(缺一类就是某几个人逐人失败);
- 上线前请 Hub 管理员用「应用接入 → 企业微信推送 → 发送测试消息」验一遍: 那是唯一不依赖本系统就能验通上面四类前提的手段。
15.8 排障与验收
python3 scripts/check_notify_hub.py(不连库、不碰真 Hub,进程内一台假 Hub)钉住:
收件人优先 Hub 主键、幂等键跨重试稳定而人工补发换世代、深链是站内相对路径、
待办深链只发给这条待办的持有人(同批旁人落 /work/<job>)、
标题/正文/markdown 字节三档预算、逐人原因分档、请求级 401/403/400 判死与 409/5xx 退避、
duplicate 算成功、回查按 receiver 回显对齐到人、入队一人一条、
以及免登落地那一半只认站内 redirect。
接口那一层由 python3 scripts/check_notify_hub_api.py 钉(连开发库 + 真 TestClient,
把 Hub 指到进程内那台假 Hub,自建的数据用完删掉):notify/meta 报得清底细、
保存时校验消息形态与标题额度、换种类不留上一档的 url/secret、测试发送真发给本人
且带 /todo 深链、回查打的是 GET {推送路径}/{msg_key}、非 Hub 记录回查给 400。
点开那一跳的落地侧由 python3 scripts/check_notify_landing.py 钉(真路由 + 假 Hub 的
POST /tickets/verify):/sso/hub?ticket=…&redirect=/todo/… 验完票 302 回
/sso#code=… 且票据原值不出现在地址里、验票只问一次不带 app_code 用的是免登那把密钥、
短码只能用第二次就废、redirect 一路带到前端且只认站内路径(//evil.example.com 当没填)、
不带 redirect 照样换得到会话、active:false 与应用串号各回一个稳定原因码。
它顺带钉住一条给运维的提醒:推送链路的票据天生不带 state(9.6.5),所以「免登必须
校验 state」打开成强制档时,从企业微信点卡片这一跳会被 SSO_STATE_REJECTED 挡在门外。
最后半米(会话换到手之后人站在哪一页)由 frontend/src/views/auth/SsoCallbackView.landing.spec.ts
钉:#code=… 与 ?ticket=…&redirect=… 两种落地形态都要把人直接送到那条待办或那张单
面前;redirect 写成 //evil.example.com 时一律不进,落回系统自己的第一屏;后端拒票
那一屏只说一句话、一次登录请求都不许多发(开了强制 state 校验时企微点开就是这个样子)。
401 有两种,别一上来就换密钥。Hub 自己答的 401 是带信封的
401 {"code":"401001","message":"集成密钥无效"} —— 那才是密钥不对;而它前面的网关对
这条路径压根没注册(Hub 版本没上 §9.6、或网关没放行)回的是一句裸
401 {"error":"unauthorized"},跟乱敲一个不存在的地址回的报文一模一样。分辨的办法不用猜:
拿同一把密钥敲一个肯定存在的路径(POST {hub}/api/v1/auth/tickets/verify),它回
401001 说明密钥没问题、推送那条是路不通;它连这个都回裸 error,才轮到怀疑密钥与站点。
投递记录里这两种的话分开写着,裸 error 那一档会把推送路径一起念出来。
真机验收清单(企微里点一次就知道):卡片点开不出现登录页、中途也不闪一屏「正在确认你的
统一门户身份」→ 一屏「正在打开 …」→ 落到该单的审批页;点开别人的单据能看不能批;
redirect 被改成 //evil.example.com 时落默认页不出站;落地页刷新不会把用户卡在
ticket_invalid(票据只能用一次)。