xuyue/OJ2

Files

yuetsh f6bc42f534 docs: 给 OJ2 补一份自己的 CLAUDE.md；Dockerfile 拷上 bunfig.toml

## bunfig.toml 没拷进容器，才是那批「本地能过、容器过不了」的根因

bunfig.toml 里设了 `linker = "hoisted"`，但 Dockerfile 只拷了 package.json 和
bun.lock，于是容器里用的是默认的 isolated 布局（包都在 node_modules/.bun/ 下），
本地靠"提升"才解析得到的包在容器里一律 Could not resolve —— 而本地构建始终是好的，
只有镜像构建才炸。之前是一个一个补直接依赖补过去的（那是对的、该保留），
这里让两边布局一致，是第二道保险。

带上之后装 622 个包（isolated 是 1238），镜像重建通过，二进制在容器里
serve + healthcheck 正常。

顺手补了 main.ts 帮助文本里漏掉的 healthcheck 子命令（compose 里把 command
写错时，看到的就是这行）。

## OJ2/CLAUDE.md

OJ2 是独立仓库，之前没有自己的项目指引。写了一份，重点是几条「不知道就会踩」的：

- **本机 Docker 可用**，整套依赖和上线演练都能在本机跑 —— 别沿用上一代
  "本机跑不起来后端"的旧假设
- 单二进制不能依赖 node_modules，`.node` 资源导入 dev 和编译两种形态行为不同，
  **改完两种形态都要跑**
- SQL 判题 spawn 的是二进制自己，入口必须有 argv 分发，那道递归闸不能删
- 判题状态码三处同步、raw_password 要保留、比赛只有 ACM、前端要兼容老 Chrome
- 不写迁移：新旧后端跑同一套表结构，这是回滚能成立的前提

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

2026-08-08 03:37:45 -06:00

4.4 KiB

Raw Blame History

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      # 后端类型检查
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 那道递归闸不要删。

判题状态码要三处同步

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 和判题沙箱 —— 所以上线那天两边必须一起切。

细节和演练结果都在 docs/specs/phase5-cutover-runbook.md。

4.4 KiB Raw Blame History Unescape Escape