yuetsh
1a059d0b88
设计文档写的是「不双跑不灰度」，这次改主意了。理由：「只换前后端」形态下新栈
本来就不碰数据库进程，双跑的增量风险只剩「两个后端同时写同一个库」这一条；
换来的是**正式切换退化成改一行 NPM 上游**，比停机切换更稳，回滚也不用停任何容器。
## 两个新变量
WEB_PORT 对外端口。8080 还被旧 backend 占着（机房是 81）
JUDGE_STATE_DIR 判题机运行状态目录
JUDGE_STATE_DIR 是必须的：不设的话新旧两个 judger 会同时往
`data/judge_server/{run,log}` 里写。默认值用嵌套写法跟着 DATA_DIR 走
（`${JUDGE_STATE_DIR:-${DATA_DIR:-../data}/judge_server}`，compose 支持嵌套默认值，
试过），所以一次性切换那条路径完全不受影响。
test_case 和 public/upload 仍然共享 —— 那是故意的，测试点和题面图片两边必须
看到同一份。
## 手册
新增第四节「并行试跑」，后面章节顺移（原四~九 → 五~十），两处交叉引用一并改了。
第五节拆成两条路径：试跑过的只需改 NPM 上游 + 事后停旧栈；没试跑的走原来那套。
第七节回滚同理。
试跑那节写明了三件容易踩的：NPM 的 Websockets Support 必须打开（漏了的话页面
一切正常，唯独「判题中…」永远不动，而刷新一下结果就出来，自测很难发现）、
两边登录态不互通、以及双写的是真实数据不是沙盒（别在 oj2 上办正式比赛）。
## 验证
试跑形态 `config` 解析：判题机目录落到 judge_server_oj2、端口 8090、test_case
仍指向共享的那份；不设新变量时默认值一个没变（judge_server / 8080）。
四份 compose `config -q` 全通过。
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
5.9 KiB
CLAUDE.md
OJ2 是判题狗（Online Judge）的后端重写：Django 6 → Bun + TypeScript，前后端同仓。
上一代在 ../OnlineJudge/（Django）和 ../ojnext/（Vue SPA），两者都已冻结，
是回滚路径，任何情况下都不要改。
设计文档：docs/specs/2026-08-06-bun-backend-rewrite-design.md
切换手册：docs/specs/phase5-cutover-runbook.md ← 上线当天照这份走
仓库结构
| 目录 | 作用 |
|---|---|
apps/api/ |
后端。Hono + Drizzle + BullMQ，编译成单二进制 |
apps/web/ |
前端。从 ojnext 原样搬来的 Vue 3 SPA |
packages/contract/ |
前后端共用的 Zod 契约 |
docker/ |
Dockerfile + 三套 compose（dev / debian / school） |
docs/specs/ |
设计、端点清单、各阶段评审报告与演练报告 |
本机环境
Docker 可用，全套依赖都能在本机跑起来（PostgreSQL、Redis、判题沙箱）， 镜像也能在本机构建并完整演练上线。这一点和上一代不同，别沿用"本机跑不起来后端" 的旧假设。
bun install
bun run db:up # 起 postgres(5433) / redis(6380) / 判题沙箱(8081)
bun run dev # api(3000) + worker + web(5173) 一起起
首次要先建 .env（照 .env.example）。判题机 token 两边必须一致：
.env 的 JUDGE_SERVER_TOKEN 和 docker/.env 的 OJ2_JUDGE_TOKEN。
常用检查：
bunx tsc --noEmit -p apps/api # 后端类型检查
bun run --filter '@oj2/api' check:routes # 路由遮蔽检查，加完路由跑一下
cd apps/web && bun run build # 前端构建（vite 不做类型检查，构建即验证）
不要写测试 —— 沿用上一代的项目约定。验证靠实跑：起服务、打接口、看结果。
几件必须知道的事
单二进制是有代价的
apps/api 编译成 bun build --compile 的单二进制，所以运行时不能依赖
node_modules。任何 require.resolve / Bun.resolveSync / __dirname 去找文件的
写法，本地都正常、编译后都会炸，而且只在离开仓库目录后才炸（在仓库里跑时它顺着
cwd 摸到了 node_modules，假装没事）。
资源要用 with { type: "file" } 内嵌。.node 原生模块还要额外注意：这个写法
只有打包器认、bun run 不认，所以必须按形态分叉 —— 见 apps/api/src/vendor/jieba.ts
的注释，那里把坑写全了。
改完这类代码，dev 和编译两种形态都要跑一遍。 我吃过亏：只验了编译产物， dev 直接起不来。
路径解析看 runtime.ts
编译后 import.meta.dir 恒为 /$bunfs/root，往上三级就是文件系统根。
相对路径一律走 runtime.ts 的 pathBase，别自己拼。
SQL 判题会 spawn「自己」
judge/sql/index.ts 起的子进程是二进制自身 + sql-child 子命令（因为编译后磁盘上
没有 child.ts 可以 spawn）。所以入口必须有 argv 分发，否则「起自己」变成
「把整个程序再跑一遍」→ 指数级 fork。这不是假想，开发时炸过一次开发机。
OJ2_SQL_CHILD 那道递归闸不要删。
加路由要防遮蔽
Hono 按注册顺序匹配，不是静态优先（实测确认过，别凭直觉）。/problems/:id
注册在 /problems/random 前面的话，后者永远进不去 —— 而且不报错、不警告，
只是静默走进前一条的 handler。阶段 4 真实发生过一次，两个教师用的分析端点被吃掉，
一直到评审才发现。
加完路由跑 bun run --filter '@oj2/api' check:routes。
判题状态码要三处同步
apps/api/src/judge/status.ts、apps/web/src/utils/constants.ts、
以及上一代的 ../OnlineJudge/submission/models.py（回滚时要对得上）。
题目表情 reaction 的语义 key 同理。
比赛只有 ACM 模式
没有 OI。上一代残留的 OI 分支在阶段 0 已经砍掉，不要"顺手补回来"。
前端要兼容老 Chrome
机房电脑 Chrome < 94。mermaid-legacy 等 fallback 依赖和 vite 的构建 target
不能动，vite.config.ts 里有注释说明。
数据库
Drizzle schema 是从生产库 drizzle-kit pull 出来的，不写迁移。
新旧后端跑在同一套表结构上（阶段 5 演练逐列比对过，零差异），这是回滚能成立的前提 ——
所以改 schema 前先想清楚回滚怎么办。
生产库的几个约定：
raw_password明文列要保留，老师用它找学生密码。不要"顺手清理"。judge_server_heartbeat保留。problem.prompt是给未来 AI 预留的，当前没接线，不要删。
部署
三套 compose 在 docker/：dev（本机）、debian（服务器）、school（机房）。
机房那套没有 postgres，连的是服务器的库。 两个站点共用一个数据库， 但各有各的 Redis 和判题沙箱 —— 所以上线那天两边必须一起切。
compose.debian.yml 有两种形态，靠 env 切换：
- 只换前后端（上线用这个）：设
DATA_DIR/DB_HOST/REDIS_HOST， 沿用旧栈已经在跑的 postgres 和 redis，只起 api / worker / web / judge。 - 自带数据（本机、演练）：不设那几个变量，起栈时加
--profile local-data。 - 并行试跑（上线前先挂
oj2.xuyue.cc跑几天）：在「只换前后端」基础上再加WEB_PORT（8080 被旧 backend 占着）和JUDGE_STATE_DIR（两个判题机不能共用运行目录）。 这种形态下旧栈一个容器都不用停，正式切换退化成改一行 NPM 上游。
⚠️ DATA_DIR 默认值 ../data 是 OJ2/data，不是部署目录的 data/。
沿用旧数据却忘了设它，会静默起一套空数据（空库、没测试点、图片 404），
而且不报错 —— 这是切换当天唯一会静默走歪的地方。
细节和演练结果都在 docs/specs/phase5-cutover-runbook.md。