276 lines
7.2 KiB
Markdown
276 lines
7.2 KiB
Markdown
# BitOJ - Online Judge System
|
||
|
||
BitOJ是一个功能完整的在线程序设计竞赛评测系统服务端，支持多语言编程、自动化评测、安全沙箱环境等核心功能。
|
||
|
||
## 系统概述
|
||
|
||
BitOJ采用分布式架构设计，通过XML-RPC协议与前端Web系统通信，支持高并发评测任务处理。系统具备完善的安全机制，能够在受限环境中安全执行用户提交的代码。
|
||
|
||
## 功能特性
|
||
|
||
### 核心功能
|
||
- **多语言支持**: 支持C/C++、Java、Python、Pascal、C#、Bash等多种编程语言
|
||
- **自动评测**: 自动编译、运行、比对输出结果
|
||
- **安全沙箱**: 限制程序执行时间、内存使用、文件访问等
|
||
- **分布式架构**: 支持多评测机协同工作
|
||
- **灵活的判题**: 支持标准比对、容错比对、自定义判题脚本
|
||
|
||
### 评测结果类型
|
||
- **AC** (Accepted): 程序正确
|
||
- **WA** (Wrong Answer): 答案错误
|
||
- **TLE** (Time Limit Exceeded): 超时
|
||
- **MLE** (Memory Limit Exceeded): 内存超限
|
||
- **RE** (Runtime Error): 运行时错误
|
||
- **CE** (Compile Error): 编译错误
|
||
- **PE** (Presentation Error): 格式错误
|
||
- **OLE** (Output Limit Exceeded): 输出超限
|
||
- **SE** (System Error): 系统错误
|
||
|
||
## 系统架构
|
||
|
||
### 目录结构
|
||
```
|
||
bitoj/
|
||
├── python/ # 核心Python模块
|
||
│ ├── engine.py # 评测引擎主控制器
|
||
│ ├── datasource.py # 数据源管理(XML-RPC通信)
|
||
│ ├── entity.py # 数据实体定义
|
||
│ ├── engineconfig.py # 引擎配置管理
|
||
│ ├── judgescript.py # 判题脚本管理
|
||
│ ├── tester.py # 测试器实现
|
||
│ └── ojunit.py # 单元测试基类
|
||
├── scripts/ # 脚本文件
|
||
│ ├── compare-file.py # 文件比较工具
|
||
│ └── run-guard.py # 运行时沙箱守护
|
||
├── utils/ # 工具类
|
||
│ └── xmlrpc-debug-proxy.py # XML-RPC调试代理
|
||
└── conf-demo.py # 配置示例文件
|
||
```
|
||
|
||
### 核心模块说明
|
||
|
||
#### JudgeEngine (engine.py)
|
||
评测引擎核心控制器，负责：
|
||
- 多线程任务调度
|
||
- 提交队列管理
|
||
- 评测流程控制
|
||
- 异常处理和恢复
|
||
|
||
#### DataSource (datasource.py)
|
||
数据源管理模块，提供：
|
||
- XML-RPC通信接口
|
||
- 数据库连接管理
|
||
- 提交信息获取
|
||
- 结果回写功能
|
||
- 网络异常重试机制
|
||
|
||
#### Tester (tester.py)
|
||
测试器实现，包含：
|
||
- **SimpleTester**: 单一语言测试器
|
||
- **ComboTester**: 组合测试器(如bounds checking)
|
||
- 编译环境管理
|
||
- 运行时沙箱控制
|
||
- 资源限制监控
|
||
|
||
#### Entity (entity.py)
|
||
数据实体定义：
|
||
- **Submit**: 代码提交实体
|
||
- **Problem**: 题目信息实体
|
||
- **TestCase**: 测试用例实体
|
||
- **PresetCode**: 预置代码实体
|
||
|
||
## 支持的编程语言
|
||
|
||
| 语言 | 版本 | 编译器 | 特殊功能 |
|
||
|------|------|--------|----------|
|
||
| C | GCC 3.3 | gcc-3.3 | 支持bounds checking |
|
||
| C++ | GCC 3.3 | g++-3.3 | 标准C++支持 |
|
||
| Java | 1.5/1.6 | javac | JVM内存管理 |
|
||
| Python | 3.x | python3 | 解释执行 |
|
||
| Pascal | FPC 2.2 | fpc | Free Pascal |
|
||
| C# | Mono 2.0 | gmcs | .NET框架 |
|
||
| Bash | 3.x | bash | Shell脚本 |
|
||
|
||
## 安全机制
|
||
|
||
### 资源限制
|
||
- **时间限制**: 可配置的CPU时间上限
|
||
- **内存限制**: 虚拟内存使用限制
|
||
- **进程限制**: 子进程数量控制
|
||
- **文件限制**: 输出文件大小限制
|
||
|
||
### 沙箱隔离
|
||
- **用户隔离**: 使用专用的ojrun用户执行代码
|
||
- **目录隔离**: 限制文件系统访问范围
|
||
- **权限控制**: 最小权限原则执行用户代码
|
||
|
||
### 安全防护
|
||
- **恶意代码检测**: 过滤危险系统调用
|
||
- **网络访问限制**: 禁止网络连接
|
||
- **文件权限管理**: 只读访问数据文件
|
||
|
||
## 安装配置
|
||
|
||
### 系统要求
|
||
- Linux操作系统 (推荐Ubuntu/Debian)
|
||
- Python 2.6+
|
||
- 相应编程语言的编译器/解释器
|
||
- sudo权限用于沙箱管理
|
||
|
||
### 用户配置
|
||
创建评测专用用户：
|
||
```bash
|
||
# 创建ojrun用户组
|
||
for i in {01..99}; do
|
||
sudo useradd -m -s /bin/false ojrun$i
|
||
done
|
||
```
|
||
|
||
### 目录设置
|
||
```bash
|
||
# 创建必要目录
|
||
sudo mkdir -p /var/lib/bitoj
|
||
sudo chmod 755 /var/lib/bitoj
|
||
|
||
# 设置数据目录
|
||
mkdir -p data/default
|
||
mkdir -p log
|
||
```
|
||
|
||
### 配置文件
|
||
复制并编辑配置文件：
|
||
```python
|
||
# 基于conf-demo.py创建配置
|
||
config.add_xmlrpc_datasource('http://your-oj-frontend/ojfeeder.php')
|
||
config.debug = False
|
||
config.no_cleanup = False
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 启动评测引擎
|
||
```bash
|
||
cd bitoj/python
|
||
python engine.py
|
||
```
|
||
|
||
### 配置数据源
|
||
```python
|
||
# 添加XML-RPC数据源
|
||
config.add_xmlrpc_datasource('http://frontend-url/ojfeeder.php')
|
||
|
||
# 配置评测线程数
|
||
config.test_threads = 4
|
||
|
||
# 设置获取间隔
|
||
config.fetch_interval = 1
|
||
```
|
||
|
||
### 自定义判题
|
||
系统支持三种判题方式：
|
||
|
||
1. **标准文本比较**: 逐字符比较输出
|
||
2. **容错文本比较**: 允许格式错误(PE)
|
||
3. **自定义判题脚本**: 支持特殊判题逻辑
|
||
|
||
## API接口
|
||
|
||
### XML-RPC方法
|
||
- `get_submits(judge_id, limit)`: 获取待评测提交
|
||
- `get_problem(problem_id)`: 获取题目信息
|
||
- `get_tests(problem_id, full)`: 获取测试用例
|
||
- `update_submit_status(submit_id, status)`: 更新提交状态
|
||
- `update_submit_test_results(submit_id, results)`: 更新测试结果
|
||
|
||
## 性能优化
|
||
|
||
### 并发评测
|
||
- 支持多线程并发评测
|
||
- 可配置评测线程数量
|
||
- 智能任务队列管理
|
||
|
||
### 缓存机制
|
||
- 测试用例文件缓存
|
||
- 预置代码缓存
|
||
- 编译结果复用
|
||
|
||
### 资源管理
|
||
- 用户池管理避免用户耗尽
|
||
- 临时文件自动清理
|
||
- 内存使用监控
|
||
|
||
## 监控和调试
|
||
|
||
### 日志系统
|
||
- 详细的执行日志记录
|
||
- 可配置的日志级别
|
||
- 异常堆栈跟踪
|
||
|
||
### 调试工具
|
||
- XML-RPC调试代理
|
||
- 单元测试覆盖
|
||
- 性能分析支持
|
||
|
||
### 状态监控
|
||
- 评测队列长度监控
|
||
- 系统资源使用统计
|
||
- 异常错误计数
|
||
|
||
## 扩展开发
|
||
|
||
### 添加新语言支持
|
||
1. 在`engineconfig.py`中定义新的`SimpleTester`
|
||
2. 配置编译和运行命令
|
||
3. 设置资源限制参数
|
||
4. 编写相应的guard脚本
|
||
|
||
### 自定义判题脚本
|
||
```python
|
||
class CustomJudge:
|
||
def judge(self, sid, tid, tin, tout, result, errfile, rundir=None):
|
||
# 实现自定义判题逻辑
|
||
return 'AC' # 返回判题结果
|
||
```
|
||
|
||
## 故障排除
|
||
|
||
### 常见问题
|
||
1. **编译失败**: 检查编译器路径和权限
|
||
2. **运行超时**: 调整时间限制配置
|
||
3. **权限错误**: 确认ojrun用户配置正确
|
||
4. **网络错误**: 检查XML-RPC连接配置
|
||
|
||
### 调试步骤
|
||
1. 启用debug模式: `config.debug = True`
|
||
2. 保留临时文件: `config.no_cleanup = True`
|
||
3. 查看详细日志输出
|
||
4. 使用单元测试验证功能
|
||
|
||
## 安全注意事项
|
||
|
||
1. **定期更新**: 保持系统和编译器版本更新
|
||
2. **权限最小化**: 确保ojrun用户权限最小
|
||
3. **网络隔离**: 评测机与外网隔离
|
||
4. **监控异常**: 建立异常行为监控机制
|
||
|
||
## 许可证
|
||
|
||
本项目遵循开源许可证，详情请查看LICENSE文件。
|
||
|
||
## 贡献指南
|
||
|
||
欢迎提交问题报告和功能请求。如需贡献代码，请：
|
||
1. Fork本仓库
|
||
2. 创建功能分支
|
||
3. 提交改动
|
||
4. 发起Pull Request
|
||
|
||
## 联系方式
|
||
|
||
如有问题或建议，请通过以下方式联系：
|
||
- 提交Issue到GitHub仓库
|
||
- 发送邮件到项目维护者
|
||
|
||
---
|
||
|
||
BitOJ - 为编程竞赛提供可靠的评测服务 |