Hydro 在线评测系统实战指南:从免费 SaaS 体验到一键部署与插件化扩展

原创2026-10-14 12:41:071,612 阅读
文章标签:后端前端教育

Hydro 在线评测系统实战指南:从免费 SaaS 体验到一键部署与插件化扩展

本文围绕 Hydro 开源在线评测系统的英文官方说明展开,系统讲解其"高性能、易部署、轻量、可扩展"的核心定位,并深入仓库源码剖析一键安装脚本、domain 多空间机制、插件加载器与 CLI 运维工具的真实实现。读者读完可掌握 Hydro 的两种使用路径(免自建 SaaS 与自托管部署)、部署产物与进程构成,以及如何基于模块化插件体系扩展系统能力。

项目定位:高性能、易部署、轻量、可扩展的在线评测系统

Hydro 是一个面向信息学竞赛场景的高性能在线评测(Online Judge)系统。其英文官方说明 README-EN.md 给出的定位十分凝练:易部署(提供安装脚本)、轻量、可扩展(easy to deploy, light weight and extensible)。它并非从零起步的软件,而是以旧版 vijos/vj4 为前身演进而来,继承了其 UI 框架思路。

从仓库结构看,Hydro 采用 monorepo 组织形式,顶层 package.json 通过 workspaces 聚合了 packages/*、framework/*、plugins/*、examples/plugins/* 等目录。其中核心服务端位于 packages/hydrooj,评测机位于 packages/hydrojudge,前端位于 packages/ui-default,而 framework 则承载了路由、序列化、校验等基础框架能力。这种"核心 + 插件 + 独立前端"的分层结构,正是"轻量与可扩展"得以实现的组织基础。

无需自建:免费 SaaS 与 domain 多空间机制

官方说明给出了一个对初学者极具价值的特性:项目方提供了完全免费的 SaaS 服务(hydro.ac),用户可以不去自托管,直接注册体验全部功能。其核心支撑是 Hydro 的 domain(域/空间) 机制——单套系统内可创建多个相互独立的"空间",每个空间拥有独立的管理员、题目、用户与权限边界。

官方文档给出了清晰的体验路径:注册账号后,进入 MyAccount > MyDomains > Create Domain 即可创建自己的空间。这意味着:

  • 对不熟悉 Linux 运维的教师、学生,可以零成本、零门槛地使用系统;
  • 对想先评估功能再决定自建的团队,可以先用 SaaS 验证方案。

在源码层面,domain 机制由 packages/hydrooj/src/model/domain.ts 的 DomainModel 实现。其 add() 方法(第 62-77 行)在创建空间时会写入 roles、bulletin 等基础字段,触发 domain/create 总线事件,并将创建者设为 root 角色:

static async add(domainId: string, owner: number, name: string, bulletin: string) {
    const ddoc: DomainDoc = {
        _id: domainId, lower: domainId.toLowerCase(), owner, name,
        bulletin, roles: {}, avatar: '',
    };
    await bus.parallel('domain/create', ddoc);
    await coll.insertOne(ddoc);
    await DomainModel.setUserRole(domainId, owner, 'root', true);
    return domainId;
}

同时,DomainModel 通过 LRU 缓存(max: 1000, ttl: 300 * 1000)缓存域信息,并定义了三种加入方式(JOIN_METHOD_NONE 禁止加入、JOIN_METHOD_ALL 任意加入、JOIN_METHOD_CODE 邀请码加入)以及加入有效期选项(3 小时到永久),这些字段直接对应创建空间时的配置界面,也是"不同空间相互隔离、可独立管理"的实现基础。

一键部署:安装脚本的完整流程

对于需要自托管的场景,README 强调其"易部署"——安装脚本自动完成环境准备与组件安装。仓库中的 install/install.sh 与 install/install.ts 提供了完整实现,整个流程可概括为以下几个阶段:

1. 权限与前置检查 脚本要求以 root 运行(非 root 时自动调用 sudo 提权),随后依次检查:CPU 是否支持 avx 指令集(否则 mongod 可能无法运行,降级使用 mongodb@v4.4)、/dev/shm 临时目录大小(过小会影响高并发评测)、是否安装宝塔面板(存在兼容性风险)、是否 CentOS(内核过低,明确拒绝安装)。这些检查结果会以警告列表的形式在安装结束时集中打印。

2. 环境与运行时安装 脚本通过 Nix 包管理器安装 Node.js、pm2、yarn、mongodb、mongosh、gcc、python3、caddy、go-judge(沙箱)等组件,并根据 IP 归属自动选择国内或国际镜像源(可通过 REGION 环境变量或 --substituters= 参数覆盖)。arm64 设备(如树莓派)会自动在 /boot/cmdline.txt 中启用 memory cgroup 并提示重启。

3. 数据库初始化 创建 MongoDB 专用用户 hydro(随机 32 字节 hex 密码),并将连接串写入 ~/.hydro/config.json:

{ "uri": "mongodb://hydro:<随机密码>@127.0.0.1:27017/hydro" }

4. 生成评测机与反代配置

  • ~/.hydro/judge.yaml:评测机连接配置,含 server_url、uname/password、concurrency、memoryMax、tmpfs_size、parallelism 等参数;
  • ~/.hydro/mount.yaml:沙箱挂载配置,将 nix 环境的 bin/lib 只读绑定进沙箱,并设置 /w、/tmp 两个 tmpfs;
  • ~/.hydro/Caddyfile:Caddy 反向代理配置,默认监听 80 端口,静态资源直出、动态请求反代至 127.0.0.1:8888,并启用 zstd/gzip 压缩。

5. 进程编排与收尾 使用 pm2 统一托管 hydro-sandbox、mongod、caddy、hydrooj,执行 pm2 startup 与 pm2 save 实现开机自启,并顺带设置 vm.swappiness=1 优化评测稳定性。此外,安装器支持自动检测本机 HustOJ / UOJ(Docker 版)并询问是否一键迁移历史数据到 Hydro。

值得注意的是,中文版 README.md 明确声明:安装完成后注册的第一个用户将自动获得超级管理员权限。这与源码中 UserModel.setSuperAdmin()(packages/hydrooj/src/model/user.ts 第 496-499 行)将用户权限置为 PRIV.PRIV_ALL 的实现相呼应,部署者完成安装后直接注册即可接管整个系统。

轻量运行架构:无状态核心与多机扩展

从中文版说明与仓库结构可以推断,Hydro 的设计原则之一是核心系统无状态:Web 服务节点可以随意增删而不影响系统运行,评测队列会在所有在线的评测机之间自动均衡分配,不同评测服务器间的测试数据由系统按需拉取、缓存管理,评测机"上线即用",无需手动同步数据。这也是 README 声称其"轻量"的深层原因——服务端只承担调度与存储职责,重活由评测机(hydrojudge)分担。

进程层面,单机部署的完整拓扑为:caddy(80 端口反代)→ hydrooj(8888 端口 Web 服务)→ mongod(数据存储),评测侧为 hydro-sandbox(本机监听 5050 端口的沙箱服务)→ hydrooj 内部的 worker。安装脚本将这一整套以 pm2 进程组的形式托管,单机即可运行完整系统,符合"轻量"的定位。

插件系统:热插拔的扩展机制

"可扩展"是 Hydro 官方定位的另一关键词,其落点是模块化插件系统。插件加载的核心实现在 packages/hydrooj/src/loader.ts:

  • Loader 服务维护插件状态机(FiberState.PENDING / LOADING / FAILED),并每 10 秒巡检一次,将仍处于 pending/loading/failed 的插件输出到日志,便于运维定位加载问题;
  • reloadPlugin() 支持插件热更新:当系统设置变化导致插件配置不一致时,会基于 system/setting 事件自动重建插件实例,且全程使用 cac 解析命令行、支持从 nix 环境路径(HYDROPATH)解析插件;
  • 插件的配置通过 Schemastery Schema 声明,由 SettingService 统一管理,支持作用域(configScope)隔离。

插件可调用的能力面由 packages/hydrooj/src/plugin-api.ts 统一导出,包括但不限于:ProblemModel、ContestModel、UserModel、RecordModel、DomainModel、StorageModel 等全部核心模型,Handler、ConnectionHandler、Router、Subscription 等服务端基础设施,以及 buildContent、rating、difficulty、sendMail 等工具函数。

默认安装即带四个插件:@hydrooj/ui-default(默认前端)、@hydrooj/hydrojudge(评测机)、@hydrooj/fps-importer(FPS 题库导入)、@hydrooj/a11y,记录在 ~/.hydro/addon.json 中。仓库 examples/plugins 目录提供了最小插件示例(如 ui-next-plugin 展示了如何自定义前端页面),可作为插件开发的入门参照。

CLI 运维:备份、恢复与交互式管理

Hydro 提供了完整的命令行运维入口,入口实现位于 packages/hydrooj/src/entry/cli.ts。值得强调的是其交互模式:不带参数运行 hydrooj cli 会进入 REPL 提示符 hydrooj>,可直接输入 hydrooj cli <model> <function> <args> 形式的命令,例如 hydrooj cli system set server.host 0.0.0.0;非交互模式下则以 hydrooj cli <模型名> <方法名> <参数> 直接调用模型方法,参数支持数字、ObjectId、JSON 对象自动解析。

数据备份与恢复由 packages/hydrooj/src/commands/db.ts 提供:

  • hydrooj backup:将数据库与文件数据打包为时间戳命名的 zip(支持 --dbOnly 仅备份数据库,也支持 --r 指定 restic 仓库做增量备份);
  • hydrooj restore <文件>:恢复备份,通过 mongorestore --drop 重建数据库并还原文件数据。

此外还提供 hydrooj diag 快速诊断、hydrooj patch、hydrooj addon add/remove 等命令,覆盖插件管理、打补丁与系统体检等日常运维场景。

开源许可证与附加条款

Hydro 使用 AGPLv3 并附带附加条款 进行分发(详见 LICENSE)。官方说明基于 AGPLv3 第 7 节明确了三条额外义务:

  1. 不得移除软件中展示的版权声明(对应 AGPLv3 7(b));
  2. 分发修改版软件时,必须以合理方式改变软件名或版本号以区别于原版(对应 AGPLv3 7(c));
  3. 未经许可,不得使用作者姓名、商标或 Logo 宣传该软件(对应 AGPLv3 7(d))。

中文版 README 给出了具体落地方案:部署 Hydro 时需在页面底部保留 Powered by Hydro 字样;对源码做出修改后,同样需以 AGPL-3.0-or-later 开源,并可以 Powered by Hydro, Modified by xxx 的格式在页脚注明。此外,仓库内 framework/、examples/、install/ 目录采用更宽松的 MIT 协议,packages/ui-default/ 则仅以 AGPL-3.0 授权,引用相关代码时需留意目录差异。

贡献与社区

项目欢迎社区参与,贡献规范见 CONTRIBUTING.md。官方说明特别提到:当前正在征集韩语与日语翻译的贡献者,母语为这两种语言的开发者可直接通过社区联系项目组提交 Pull Request。官方联系方式如下(以纯文本列出,供检索):

  • Email:i@undefined.moe
  • QQ 用户群:1085853538
  • Telegram 群:@hydrodev
  • Telegram:@undefinedmoe

项目在致谢部分特别提及:GitHub(代码托管与工作流)、criyle(评测沙箱实现)、Vijos(UI 框架)。

仓库资源导航

围绕本文主题,可继续深入阅读的仓库关键文件:

登录后查看全文
Hydro