# 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 - 为编程竞赛提供可靠的评测服务