13 KiB
多副本部署:把"进程只有一个"这个假设从代码里拿掉
对应缺口: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。
必须一致的三样:
- 同一份引导配置(尤其
db_host/db_name); - 同一个
jwt_secret——A 副本签的令牌到了 B 副本必须验得过,否则表现为"隔几次就掉登录", 是最难复现的那类故障; - 同一个库(本来就该是一个)。
不需要粘滞会话:登录态是无状态 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 时得手工验。