added readme

README.md

@@ -0,0 +1,276 @@
+# 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 - 为编程竞赛提供可靠的评测服务