# YUAN_OJ_API

**Repository Path**: arohtea/yuan_-oj_-api

## Basic Information

- **Project Name**: YUAN_OJ_API
- **Description**: 一款OJONLINE产品,支持主流语言的编译和运行,基于judge0开源项目,支持竞赛,作业发布,教学实验上传等功能,目前仍在开发ing
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-17
- **Last Updated**: 2026-04-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Yuan OJ Backend

基于 `Spring Boot 3 + Spring Cloud Alibaba + Nacos + Judge0` 的在线判题后端。

当前主线已经包含：

- 普通代码题判题链路
- SQL Lab 实训题链路
- 网关、用户、题目、提交、判题、竞赛、讨论、题解、通知等服务

这份 README 的目标很直接：让同事拿到仓库后，能尽快把项目跑起来做联调和测试。

## 1. 技术栈

- Java `17`
- Maven `3.9+`
- Spring Boot `3.2.5`
- Spring Cloud `2023.0.1`
- Spring Cloud Alibaba `2022.0.0.0`
- MyBatis-Plus `3.5.5`
- MySQL `8`
- Redis `7`
- RabbitMQ Management
- Nacos `2.x`
- Judge0 `1.13.1`
- Docker / Docker Compose

## 2. 模块与端口

| 模块 | 端口 | 说明 |
| --- | --- | --- |
| `yuan-oj-gateway` | `8080` | 网关，统一入口 |
| `yuan-oj-user-service` | `8081` | 用户、登录、JWT |
| `yuan-oj-problem-service` | `8082` | 题目、测试用例、SQL Lab 配置 |
| `yuan-oj-submission-service` | `8083` | 提交、运行记录、投递判题任务 |
| `yuan-oj-judge-service` | `8084` | 普通题判题、Judge0 集成、SQL Lab 调度 |
| `yuan-oj-contest-service` | `8085` | 竞赛 |
| `yuan-oj-discussion-service` | `8086` | 讨论 |
| `yuan-oj-solution-service` | `8087` | 题解 |
| `yuan-oj-notification-service` | `8088` | 通知 |
| `yuan-oj-sql-runner-service` | `8089` | SQL Lab 执行层，负责起临时 MariaDB 容器 |

## 3. 目录说明

```text
.
├── database/                         # 数据库脚本
├── docs/                             # 项目文档
├── judge0-v1.13.1/                   # Judge0 本地部署文件
├── yuan-oj-common/                   # 公共模块
├── yuan-oj-gateway/                  # 网关
├── yuan-oj-user-service/             # 用户服务
├── yuan-oj-problem-service/          # 题目服务
├── yuan-oj-submission-service/       # 提交服务
├── yuan-oj-judge-service/            # 判题服务
├── yuan-oj-contest-service/          # 竞赛服务
├── yuan-oj-discussion-service/       # 讨论服务
├── yuan-oj-solution-service/         # 题解服务
├── yuan-oj-notification-service/     # 通知服务
└── yuan-oj-sql-runner-service/       # SQL Lab 执行服务
```

## 4. 快速开始总览

推荐按这个顺序做：

1. 本机启动 `MySQL / Redis / Nacos`
2. 用 Docker 启动 `RabbitMQ Management`
3. 导入数据库脚本
4. 启动仓库里自带的 Judge0
5. 确认 `sql-runner` 可访问 Docker，因为 SQL Lab 的 MariaDB 由 Docker 动态拉起
6. 按你的环境决定是否修改 `10.18.229.42` 相关配置
7. 统一配置 `JWT_SECRET` 和 `INTERNAL_API_TOKEN`
8. 编译并启动各个微服务
9. 打开 Nacos、RabbitMQ、Judge0 做联通检查

## 5. 本机启动 MySQL / Redis / Nacos

这三个依赖按当前项目约定，默认都是本机直跑，不用 Docker。

### 5.1 本机依赖要求

- MySQL: `localhost:3306`
- Redis: `localhost:6379`
- Nacos: `localhost:8848`

如果你跑的是 Nacos `2.x`，还要保证：

- `9848`
- `9849`

这两个 gRPC 端口也能正常监听，否则 Spring Cloud Alibaba 客户端可能出现注册异常。

### 5.2 当前主线默认配置

主线代码默认就是按这组地址写的：

- MySQL：`jdbc:mysql://localhost:3306/yuan_oj`
- Redis：`localhost:6379`
- Nacos：`localhost:8848`

所以你只需要保证这三个服务先在本机启动起来即可。

### 5.3 管理入口

- Nacos: `http://localhost:8848/nacos`
  默认账号密码通常是 `nacos / nacos`

## 6. 用 Docker 启动 RabbitMQ Management

RabbitMQ 我建议直接用 Docker 起，最省事。

```bash
docker run -d \
  --name rabbitmq-management \
  -p 5672:5672 \
  -p 15672:15672 \
  -e RABBITMQ_DEFAULT_USER=admin \
  -e RABBITMQ_DEFAULT_PASS=admin \
  rabbitmq:4-management
```

启动后可访问：

- RabbitMQ 管理台：`http://localhost:15672`
- AMQP 端口：`5672`

说明：

- 当前 `submission-service` 和 `judge-service` 默认 RabbitMQ 账号密码就是 `admin / admin`
- `rabbitmq:4-management` 的 `5672` 和 `15672` 端口来自 RabbitMQ 官方 Docker 文档

## 7. 导入数据库

先创建空库，再执行核心脚本：

```bash
mysql -uroot -p123456 < database/schema.sql
mysql -uroot -p123456 < database/test_data.sql
```

说明：

- `database/schema.sql` 已包含普通题和 SQL Lab 相关核心表
- `database/test_data.sql` 是核心题目测试数据
- 讨论区、题解、通知、比赛、排名、标签活动这些模块表，已整理到 `database/modules/<模块名>/`
- 如果你需要完整导入某个模块，要先执行它的 `schema.sql`，再执行它的 `test_data.sql`
- 具体导入顺序见 [database/README.md](./database/README.md)
- 如果你拿已有旧库反复执行，末尾的 `ALTER TABLE problem ADD COLUMN problem_type ...` 可能因为列已存在而报错
- 最稳的方式是直接对空库首次导入

## 8. SQL Lab 的 MariaDB 说明

这里容易和业务主库搞混：

- 业务主库是 `MySQL`，按当前约定在本机直接运行
- SQL Lab 用的 `MariaDB` 不是本机常驻数据库
- SQL Lab 的 `MariaDB` 由 `yuan-oj-sql-runner-service` 通过 Docker 动态创建临时容器

也就是说：

- 你不需要另外手工常驻启动一个本地 MariaDB 服务
- 但如果你要测试 SQL Lab，必须保证 `sql-runner` 指向的 Docker daemon 可用
- 对应 Docker 主机上最好已经有 `mariadb:11.4`，或者至少具备拉取该镜像的能力

如果你只测试普通代码题，不测 SQL Lab，这一块可以先不管。

## 9. 启动 Judge0

仓库里已经带了 Judge0 的部署目录：

- [judge0-v1.13.1/docker-compose.yml](./judge0-v1.13.1/docker-compose.yml)
- [judge0-v1.13.1/judge0.conf](./judge0-v1.13.1/judge0.conf)

启动方式：

```bash
cd judge0-v1.13.1
docker compose up -d db redis
docker compose up -d
docker compose ps
```

启动后可访问：

- Judge0 Docs: `http://localhost:2358/docs`

说明：

- `judge0.conf` 里已经带了 Redis 和 Postgres 密码
- 如果你只是本地联调，一般不需要改这个文件
- Judge0 官方更推荐在 Linux 环境运行；Windows 本地联调建议用 Docker Desktop + WSL2 或 Linux 虚拟机

## 10. 当前默认配置里的一个重要事实

主线代码目前不是“全本地默认”，而是“混合默认”：

- MySQL、Redis、Nacos 默认指向本机
- RabbitMQ 默认指向 `10.18.229.42:5672`
- Judge0 默认指向 `http://10.18.229.42:2358`
- SQL Runner 默认通过 `tcp://10.18.229.42:2375` 访问远程 Docker
- SQL Lab 的 MariaDB 由 `sql-runner` 在 Docker 中动态创建，不是本机常驻依赖

也就是说：

### 9.1 如果你们团队都能访问 `10.18.229.42`

那你只需要本机启动：

- MySQL
- Redis
- Nacos

Docker 启动：

- RabbitMQ Management
- Judge0

然后就能比较快地把项目跑起来。

### 9.2 如果你想完全本地化测试

那至少要改这 3 个文件：

- [yuan-oj-submission-service/src/main/resources/application.yml](./yuan-oj-submission-service/src/main/resources/application.yml)
- [yuan-oj-judge-service/src/main/resources/application.yml](./yuan-oj-judge-service/src/main/resources/application.yml)
- [yuan-oj-sql-runner-service/src/main/resources/application.yml](./yuan-oj-sql-runner-service/src/main/resources/application.yml)

建议改成：

```yaml
# submission-service
spring:
  rabbitmq:
    host: localhost
    port: 5672
    username: admin
    password: admin
```

```yaml
# judge-service
spring:
  rabbitmq:
    host: localhost
    port: 5672
    username: admin
    password: admin

judge0:
  api-url: http://localhost:2358
```

```yaml
# sql-runner-service
sql-runner:
  docker:
    host: tcp://127.0.0.1:2375
    tls-verify: false
    cert-path:
```

注意：

- 如果你把 `sql-runner` 指到本机 Docker，需要本机 Docker daemon 允许 TCP 访问
- 如果你只测试普通代码题，不测 SQL Lab，可以先不启动 `yuan-oj-sql-runner-service`

## 补充：安全与联调约定

当前主线已经切到统一 JWT 鉴权，不再接受前端自带的 `userId` / `X-User-Id` 头冒充身份。

- 所有需要登录的外部接口都要带：`Authorization: Bearer <token>`
- `JWT_SECRET` 需要在所有会校验 JWT 的服务里保持一致，而且现在必须显式配置，不再有仓库内默认值
- `INTERNAL_API_TOKEN` 需要在 `user-service / problem-service / submission-service / judge-service / sql-runner-service` 保持一致，而且现在必须显式配置，不再有仓库内默认值
- `/api/problem/internal/**`、`/api/submission/internal/**`、`/api/judge/**` 已经被网关视为内部链路，外部请求会直接被拒绝
- 这一轮没有改 `sql-runner` 的 Docker 连接方式，只新增了应用层鉴权

如果你们用 Nacos 管配置，建议直接在对应 dataId 里补：

```yaml
jwt:
  secret: 你们自己的长随机字符串

internal:
  api:
    token: 你们自己的内部调用令牌
```

## 11. 编译项目

```bash
mvn clean install -DskipTests
```

如果只是快速验证 `sql-runner` 模块，也可以单独跑：

```bash
mvn -pl yuan-oj-sql-runner-service test
```

## 12. 启动微服务

推荐顺序如下：

```bash
mvn -pl yuan-oj-user-service spring-boot:run
mvn -pl yuan-oj-problem-service spring-boot:run
mvn -pl yuan-oj-submission-service spring-boot:run
mvn -pl yuan-oj-sql-runner-service spring-boot:run
mvn -pl yuan-oj-judge-service spring-boot:run
mvn -pl yuan-oj-contest-service spring-boot:run
mvn -pl yuan-oj-discussion-service spring-boot:run
mvn -pl yuan-oj-solution-service spring-boot:run
mvn -pl yuan-oj-notification-service spring-boot:run
mvn -pl yuan-oj-gateway spring-boot:run
```

说明：

- `gateway` 最后启动
- `notification-service` 的邮件配置本地联调可以先不填
- 如果你没有 SQL Lab 场景，可以暂时跳过 `yuan-oj-sql-runner-service`

## 13. 联调检查清单

服务起来后，先看这几项：

1. Nacos 控制台里能看到各服务注册成功
2. RabbitMQ 管理台可登录
3. Judge0 的 `http://localhost:2358/docs` 能打开
4. 网关 `http://localhost:8080` 已监听
5. MySQL 中 `yuan_oj` 库和表已创建

如果要测 SQL Lab，再额外检查：

1. `yuan-oj-sql-runner-service` 已注册到 Nacos
2. `sql-runner` 指向的 Docker daemon 可访问
3. 对应 Docker 主机上能拿到 `mariadb:11.4`

## 14. 常用文档

- [接口文档](./docs/API_DOCUMENTATION.md)
- [SQL Lab Runner 部署说明](./docs/sql-lab-runner-deployment.md)
- [数据库脚本说明](./database/README.md)

## 15. 已知坑位

- `schema.sql` 不适合在已有旧库上反复无脑执行
- 当前默认配置里有一部分地址指向 `10.18.229.42`，本地全量自测前记得先改
- SQL Lab 依赖 Docker，可访问 Docker API 这件事本身也需要联通验证
- SQL Lab 的 MariaDB 是 Docker 临时容器，不是业务主库 MySQL
- Judge0 和 SQL Lab 是两套执行链路，不要混为一谈

## 16. 给同事的最短路径

如果只是想尽快把项目跑起来，按下面做：

1. 本机启动 MySQL、Redis、Nacos
2. Docker 启动 RabbitMQ Management
3. 导入 `database/schema.sql` 和 `database/test_data.sql`
4. 启动 `judge0-v1.13.1/docker-compose.yml`
5. 如果要测 SQL Lab，确认 `sql-runner` 连得上 Docker，且 Docker 能用 `mariadb:11.4`
6. 把 `10.18.229.42` 相关配置改成你自己的环境，或者确保你能访问这台机器
7. 执行 `mvn clean install -DskipTests`
8. 按顺序启动各个微服务
9. 打开 Nacos、RabbitMQ、Judge0 检查联通

## 17. 参考

- Docker Compose 官方文档：<https://docs.docker.com/compose/>
- RabbitMQ 官方 Docker 文档：<https://www.rabbitmq.com/download.html>
- Judge0 官方仓库：<https://github.com/judge0/judge0>