unis-oa/docs/multi-worker-deployment.md

13 KiB
Raw Permalink Blame History

多副本部署:把"进程只有一个"这个假设从代码里拿掉

对应缺口:docs/oa-capability-review.md 里那条"单进程底座"。 落脚:backend/app/service/leader.py(跨进程租约)、app/db.py(advisory_lock 与建库白名单)、 app/main.py(调度循环、启动串行化、开放接口留痕中间件)、app/models.py::WorkerLease, 验收 backend/tests/oa_platform.py(租约那一段)与 backend/tests/db_guard.py(建库这道闸)。

0. 原来的代码默认了什么

底座是一条 uvicorn 进程 + 一条后台调度线程。有一批正确性悄悄建立在这个前提上:

位置 默认了什么 --workers 4 或两台机器之后会发生什么
_scheduler_loop 全进程只有一条调度线程 四条线程同一秒各跑一遍:延时环节唤醒四次、超时标记标四次、组织同步拉四次
写回发件箱 / 消息渠道 / 事件推送 投递由那一条线程做 同一条写回报文发两遍——对上游就是两张凭证,得走冲销
_startup 建表补列 + 初始化数据 只有一个进程在 ALTER 两个进程同时 ALTER 同一张表互相撞错误号,"我改了一半、你的被回滚"比直接起不来难查得多
hub_sync._run_lock、hub_perm._lock 进程内锁 = 全局锁 各进程一把锁,锁了个寂寞
开放接口限流 —— 已避免:限流按库里的调用留痕数判(见 docs/platform-open-api-design.md §2),不靠进程内计数

1. 后台任务:租约,不是选主协议

oa_worker_lease 一行 = 一把租约。acquire() 就是一条 UPDATE: "要么我本来就持有、要么上一任已经过期" 才把行改成自己名下并推后 expires_at,靠 InnoDB 行锁天然原子。 主进程每轮续租;主进程死了没人续,下一轮别的进程自然接管。不需要 Redis、不需要 ZooKeeper、不需要运维再加一个中间件—— 本系统的 MySQL 已经是多个副本唯一共享的状态,拿它当仲裁者是最省事的选择。

三个细节决定了它能不能真用:

  • 时钟以数据库为准(_db_now() 取 SELECT NOW())。两台 app 服务器差十秒,租约就会在它们之间来回跳, 而 MySQL 只有一台;
  • TTL 至少 3 轮调度(LEASE_ROUNDS = 3,下限 120 秒)。否则自己一轮还没跑完就被别人接走, 两边同时跑;
  • 抢不到就安静睡过这一轮,不重试、不报错、不刷日志。这里如果写成 continue 空转, 会变成"每秒几十次抢租约"把库打满。
  • 租约自己提交,不跟业务事务绑:绑一起会出现"业务回滚了租约还在我的手里", 或者反过来让两个进程同时以为自己是主。

关机和滚动发布时 _shutdown 主动 release() 交还。不交的话新副本要干等一个 TTL 才敢接手, 这段时间延时环节与消息投递是停的。别人替我交还不掉(holder 不匹配就不动), 误操作不会把正在跑的副本的租约抢走。

OA_SCHEDULER=off 那个开关是给"这个副本只接接口、完全不跑后台"这种部署留的口子, 不是用来解决重复执行的(那由租约管)。它留在环境变量而不是配置文件里,是因为 "跑几个副本、谁跑后台"属于部署层,不该出现在业务配置页上。

2. 启动:GET_LOCK 而不是租约表

建表补列与初始化数据用 MySQL 命名锁 GET_LOCK('unisoa:bootstrap', 120) 串行化。 为什么不能用上面那把租约:租约存在 oa_worker_lease 里,而建表之前这张表还不存在——先有鸡还是先有蛋。 命名锁不依赖任何表;锁跟着连接走,进程被 kill -9 时 MySQL 自动释放,不会留下解不开的锁。 数据库不支持命名锁(非 MySQL)就当"拿到了",退回单进程时代的照常跑。

3. 一个环境一个库

ensure_database() 现在先看目标库在不在,不在就查 [database] create_allowlist (OA_DB_CREATE_ALLOWLIST,默认只有 unis_oa 一个名字,结尾 * 是前缀通配,* 等于不设限)。 不在白名单就抛 SchemaCreationRefused 并直接退出进程,不是软失败—— 带着一个连错库的进程对外接客,只会让人对着一堆 500 猜原因。

这条是为了一件事:引导配置默认拿 root 连库、auto_create_schema 又开着,于是 OA_DB_NAME 打错一个字,MySQL 上就凭空多出一个"全套表 + 演示数据"的库,谁都不认领。 库已经存在时这道闸不管事,老部署和"指到已同步过组织的库"那类验收不受影响。 生产库归 DBA 管就把 auto_create_schema 关掉,改照 sql/schema.sql 手工建。

顺手加了一声提醒:启动时顺手看一眼这台 MySQL 上还有没有名字也像本系统的库 (db.stray_schemas),有就在日志里点名——一个环境一个库,多出来的大概率是某次验收被打断 留下的残留,当场说一句比半年后对着 SHOW DATABASES 回忆便宜。白名单里点名的库不算残留, 别人的库(mysql / erp_main 这种)一个都不喊;账号没有 information_schema 权限就安静跳过。

验收脚本要临时库走的是另一条路:scripts/run_all.py 与 tests/hub_integration.py 自己建、收尾自己删,共享的 MySQL 上平时只有开发库一个库。

4. 投递:租约之外还要一层认领

租约保证"同一时刻只有一个副本在跑调度",但跨轮次的边界还得靠行级认领: outbox.claim() / channels.claim() / events 同口径,一条 UPDATE ... WHERE status='pending' 把行锁给自己,抢到才发。 两层各自独立成立——就算某天调度改回多进程并行,也不会重发。

停在 sending 超过阈值的报文(进程死在发送途中)重启后当结果未知处理, 绝不盲发第二遍,recover_stuck() 把它放回队列由人看一眼。详见 docs/outbound-integration-design.md §5、docs/notification-channels-design.md §4。

5. 部署配方

5.1 先说单机怎么开:就一个变量

cd backend
OA_WORKERS=4 ./scripts/prod-api.sh          # systemd / docker 里给进程一个 OA_WORKERS=4 也一样

run.py 也认它。默认 1,不设就跟今天一模一样:一个 HTTP 进程、一条后台任务线程。 它只管 HTTP 进程数——后台任务(延时唤醒、超时提醒、Hub 同步、写回投递)一台机器上 永远只有一个进程在跑:每个进程的调度线程都去抢 oa_worker_lease,抢不到的那一轮直接睡过去。

开之前算一笔连接账(不用手算,启动时后端自己会算,超了在日志里喊一句就完事):

进程数 ×([database] pool_size + max_overflow)  ≤  MySQL 的 max_connections
     4 ×(16                        + 32)= 192   >  这台 MySQL 的 151   ← 要喊的就是这种

三条出路:OA_DB_MAX_OVERFLOW 降到 21 以下、max_connections 提到 192 以上 (还要给别的客户端留余量)、或者别开这么多。连接不够的表现不是慢而是排队: 池子默认等 30 秒,用户看到的是整个服务卡住。还要再乘一层——并发只读块 (app/parallel.py)让一个请求占最多 1 + OA_PARALLEL_WORKERS 条连接, 这两个变量是一起乘的。

实测(一套 API + 本机 MySQL 8,并发 8,各 48 次请求,两种并发都零错误零死锁):

接口 1 进程 4 进程 涨了多少
GET /org/tree(62KB 报文) 72 次/秒,p50 105ms 196~214 次/秒,p50 ~30ms 2.7~3.0 倍:序列化 + gzip 是 CPU 活
GET /draft/types 62 次/秒,p50 79ms 83 次/秒,p50 58ms 1.3 倍
POST /job 一次发起(写路径) 16.3 / 25.3 单/秒 18.0 / 21.3 单/秒 不涨(两组数互相穿过,见下)

写路径那两列是两轮各测一次(uvicorn --workers 一轮、OA_WORKERS 走 run.py 又一轮): 1 进程拿到过 16.3 和 25.3,4 进程拿到过 18.0 和 21.3 —— 两边互相穿过,所以结论是 不涨,而不是"+10%"。发起一趟的墙里全是库往返加 sync_binlog=1 的 fsync, CPU 空得很,多开进程只是多几个一起等的人。p50 反而从 300ms 抬到 350ms 这一头也说明没占到便宜。

所以:只读接口多、报文大 → 加进程真有用;写多 → 先把库挪近一点、少问几条,加进程是白加。 整个压测期间 Threads_connected 峰值只有 12(发起路径基本一请求一连接), pool_size 16 + max_overflow 32 远够用 —— 连接账要算,但它通常不是那个先撞上的墙。

5.2 一台机器不够:多机

                         ┌─ uvicorn :8000  (OA_SCHEDULER=on)
Nginx / SLB ── 无粘滞 ──▶├─ uvicorn :8001  (OA_SCHEDULER=on)
                         └─ uvicorn :8002  (OA_SCHEDULER=off,只接接口)
                                   │
                              MySQL  (唯一共享状态)   MinIO (附件)

Redis 是可选的第三样,只放丢得起的东西(共享缓存、限流计数、失效广播、一把省事的锁): 填了地址多副本才有一致性,没填这套部署照样跑。见 docs/redis-integration.md。

必须一致的三样:

  1. 同一份引导配置(尤其 db_host / db_name);
  2. 同一个 jwt_secret——A 副本签的令牌到了 B 副本必须验得过,否则表现为"隔几次就掉登录", 是最难复现的那类故障;
  3. 同一个库(本来就该是一个)。

不需要粘滞会话:登录态是无状态 JWT,没有服务端 session 需要粘住。

附件必须放到共享存储。 默认 storage 的落盘驱动是本地磁盘(local), A 副本收的文件 B 副本读不到,表现是"同一个附件刷新一次能看、刷新一次 404"。 多副本之前先把附件驱动切成 MinIO/S3;并且把 fallback_to_local 关掉—— MinIO 抖一下就把文件写进某个副本的本地盘,比直接报错难查十倍。 (「网盘」那一路目前固定落本地盘,多副本部署时它不在可用范围内。)

想验证是否真的只有一个进程在跑:查 oa_worker_lease 表(name / holder / expires_at / renewals), holder 是 主机名:进程号;启动日志与 leader.status() 也是同一份数据。界面上暂时没有这一格, 加一个只读的运维卡片是很小的活,留作下一步。

6. 还没拿掉的单进程假设(诚实清单)

这一节原先列的是"会各自为政、但不会造成资损"的那批状态。其中性能与一致性那一半已经由 app/cache.py(可选 Redis)接管——填了 Redis 地址就跨副本共享,没填就还是下面括号里写的那样, 两态的行为、键位与配置见 docs/redis-integration.md。正确性那一半照旧不交给缓存:

  • service/fetch.py 的取数缓存:没配 Redis 时 N 个副本各缓存一份 cache_seconds 秒, 同一个上游最多被打 N 次,余额这种字段在不同副本上可能差一个 TTL(配了就是 L1 加一份共享的);
  • dbconfig / hubconfig 的进程内快照:没配 Redis 时界面上改了配置,其余副本最迟等 OA_CONFIG_CACHE_SECONDS 那一轮才看到,运维要预期"改完不是全员立刻生效"(配了靠广播当场作废);
  • hub._token_lock、hub_perm._lock 是进程内的:没配 Redis 时多副本可能各刷一次 Hub token, Hub 的日志看起来像有人在爆破集成账号。上游若发一次性票据,两条退路都不管用——那种票据 得改成库里取,缓存只兜得住可重取的令牌;
  • service/hub_sync._run_lock 只是省掉同进程重复触发,真正不重跑靠调度租约;配了 Redis 再叠一把跨副本锁,那是"别白跑一趟",不是正确性的那一层。

限流与计数器原先也在这一节,现在两种部署下都不是进程内计数:配了 Redis 用共享计数器, 没配就数库里的调用留痕,口径见 docs/redis-integration.md 第 1 节。

7. 验收

cd backend && PYTHONPATH=. python3 scripts/check_leader_lease.py

覆盖租约那整段口径:第一个进程抢到、第二个抢不到、持有者续租总是成功且累加次数、 holder_of 报得出主、别人不能替我交还、过期之后可被接管、交还之后为空、 库读不动(表不存在 / 连不上)时后台任务按单进程方式照跑。它只用自己的探针租约名 __check_lease__,跑完自己删,还顺手断言"调度那一条 scheduler 一个字都没变", 所以对着有服务在跑的开发库跑也安全。

原来这三条挂在 tests/oa_platform.py 与 tests/db_guard.py 上,测试目录已经不在了: 租约这一段由上面那条脚本接住;channels.claim() 的"同一封邮件只有一个进程认领得到" 与建库那道闸(白名单 / 库存在时不管事 / SchemaCreationRefused 的三条出路)目前没有 可跑的替身,改动碰到 app/outbox/channels.py 或 app/dbguard.py 时得手工验。