# acoj **Repository Path**: jiangbyte/acoj ## Basic Information - **Project Name**: acoj - **Description**: A simplified online judge system built with Java and Go for a graduation project - **Primary Language**: Java - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-08-04 - **Last Updated**: 2026-07-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ACOJ ![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?logo=python&logoColor=white) ![FastAPI](https://img.shields.io/badge/FastAPI-0.116%2B-009688?logo=fastapi&logoColor=white) ![Vue](https://img.shields.io/badge/Vue-3-4FC08D?logo=vuedotjs&logoColor=white) ![PostgreSQL](https://img.shields.io/badge/PostgreSQL-4169E1?logo=postgresql&logoColor=white) ![Redis](https://img.shields.io/badge/Redis-DC382D?logo=redis&logoColor=white) ![RabbitMQ](https://img.shields.io/badge/RabbitMQ-FF6600?logo=rabbitmq&logoColor=white) ![Docker](https://img.shields.io/badge/Docker-2496ED?logo=docker&logoColor=white) ![License](https://img.shields.io/badge/License-MIT-green) ACOJ 是一个基于 FastAPI 构建的现代在线判题（Online Judge）平台，支持题目管理、代码提交与判题、竞赛举办以及用户/团队管理。 > ACOJ 由三个子项目组成： > - **acoj**（本仓库） — Web 主项目（API + 前端 + 数据库） > - **[acoj-worker](../acoj-worker/)** — 判题 worker 服务（RabbitMQ/Celery 消费判题任务） > - **[acoj-sandbox](../acoj-sandbox/)** — 判题沙箱执行器（C++ 执行引擎 + Python 封装） > 个人开发，有 bug 欢迎提，邮箱 jiangbytebiz@163.com --- ## 功能概览 - **判题核心**：多语言代码提交与判题运行，题目与测试用例管理，判题结果异步消费与状态回调 - **权限管理**：统一账号体系，角色/部门/用户组/岗位/资源菜单完整 RBAC 分层 - **系统能力**：文件管理（Local / S3 / MinIO / OSS）、字典管理、系统配置、代码生成 - **消息通讯**：站内消息、通知、公告、反馈、即时通讯、WebSocket 实时推送 - **可观测性**：结构化日志、Prometheus metrics、OpenTelemetry tracing --- ## 截图 | | | |---|---| | ![运营工作台](docs/IMAGES/img.png) | ![通知管理](docs/IMAGES/img_1.png) | | ![公告管理](docs/IMAGES/img_2.png) | ![反馈管理](docs/IMAGES/img_3.png) | | ![在线会话](docs/IMAGES/img_4.png) | ![字典管理](docs/IMAGES/img_5.png) | | ![文件管理](docs/IMAGES/img_6.png) | ![系统配置](docs/IMAGES/img_7.png) | | ![代码生成](docs/IMAGES/img_8.png) | ![账号管理](docs/IMAGES/img_9.png) | --- ## 技术栈 | 类别 | 技术 | |---|---| | 后端 | FastAPI / SQLAlchemy Async / Pydantic v2 / Gunicorn / Uvicorn | | 数据库 | PostgreSQL / MySQL / SQLite / Alembic | | 缓存会话 | Redis | | 任务队列 | Celery / celery-redbeat / RabbitMQ | | 存储 | Local / MinIO / S3 / OSS | | 管理端 | Vue 3 / Naive UI / Vite / TypeScript | | 门户端 | Nuxt 4 / @nuxt/ui | | 移动端 | uni-app | --- ## 项目结构 ```text app/ core/ 配置、安全、日志、异常、统一响应 deps/ FastAPI 依赖注入 middleware/ 中间件 modules/ 业务模块，自动发现并装配 platform/ DB、Redis、Storage、MQ、Celery、模块加载等基础设施 worker/ Celery 入口 migrations/ Alembic 迁移 scripts/ 开发、迁移、seed 辅助脚本 tests/ 测试 web/ admin/ Vue 管理端 portal/ Nuxt 门户端 admin-uniapp/ uni-app 管理端 ``` --- ## 快速开始 ### 后端 ```bash python -m venv .venv source .venv/bin/activate pip install -e ".[dev,postgres]" cp .env.example .env # 编辑 .env：DB__URL、REDIS__URL、CELERY__BROKER_URL、APP__CONFIG_CRYPTO_KEY python scripts/db/migrate.py python scripts/seed/seed_super_admin.py ./entrypoint.sh ``` 默认地址：`http://127.0.0.1:8000` 接口文档：`http://127.0.0.1:8000/docs` `./entrypoint.sh` 默认按 `all` 模式启动 API、Celery worker 和 beat。也可以显式传参切换：`./entrypoint.sh api|worker|beat|migrate|seed`。 ### 管理端 ```bash cd web/admin pnpm install pnpm dev ``` ### 门户端 ```bash cd web/portal pnpm install pnpm dev ``` ### uni-app ```bash cd web/admin-uniapp pnpm install pnpm dev:h5 ``` --- ## 配置边界 `.env` 只放部署和基础设施配置，例如应用监听、数据库、Redis、RabbitMQ、CORS、加密 key。 运行态业务配置放在数据库中： - `sys_config`：上传限制、邮件配置、模块运行参数等普通配置 - `sys_storage_config`：存储 provider、endpoint、bucket、access key、secret key 等连接配置 存储配置由管理后台维护并设置默认配置。上传接口可以只传 `storage_provider`，后端会解析到对应配置；需要精确指定时也支持 `storage_config_id`。 多实例部署依赖 Redis 广播配置变更。管理后台保存 `sys_config` 或 `sys_storage_config` 后，当前进程会立即重载配置，其它 API/worker 会通过 Redis 订阅事件刷新本地缓存。 --- ## 模块扩展 后端模块通过 `ModuleSpec` 声明式装配。新增业务模块通常只需要维护自己的 `router`、`model`、`schema`、`repository`、`service` 和 `module.py`。 外部业务模块包可通过环境变量追加扫描： ```bash HEI_MODULE_PACKAGES=your_company.modules HEI_DISABLED_MODULES=some.module HEI_ENABLED_MODULES=some.module ``` 推荐二次开发方式： - 业务代码放在独立模块内，不直接改框架启动、路由聚合和基础设施代码 - 模块间协作优先使用 `app/platform/interfaces` - 模块配置放在本模块配置模型或 `sys_config` 的模块名前缀下 - 存储连接统一走 `sys_storage_config`，不要在业务模块里硬编码 provider 密钥 --- ## Docker 单机单 Docker：一个项目容器内运行 API、worker、beat，PostgreSQL、Redis、RabbitMQ 由外部基础设施提供。 ```bash docker compose run --rm hei migrate docker compose up -d --build ``` 等价 Docker 命令： ```bash docker build -t hei-fastapi-backend . docker run --rm --env-file .env hei-fastapi-backend migrate docker run -d --name hei-fastapi-single --env-file .env -p 8000:8000 hei-fastapi-backend all ``` 单机多 Docker 多实例：复制同一个项目镜像的 `api` / `worker` 角色，基础设施仍由外部提供。 ```bash docker compose -f docker-compose.multi.yml up -d --build --scale api=2 --scale worker=2 docker compose -f docker-compose.multi.yml --profile seed run --rm seed ``` 多机多节点：面向 Swarm/外部编排，基础设施地址通过环境变量注入。 ```bash docker build -t hei-fastapi-backend:latest . docker build -t hei-fastapi-admin:latest web/admin docker network create --driver overlay --attachable hei_overlay docker node update --label-add hei.beat=true docker compose -f docker-compose.distributed.yml config | docker stack deploy -c - hei-fastapi ``` 管理端单独镜像： ```bash docker build -t hei-fastapi-admin web/admin docker run -d -e BACKEND_URL="http://host.docker.internal:8000" -p 8081:81 hei-fastapi-admin ``` --- ## 常用命令 ```bash python scripts/db/makemigration.py "describe schema change" python scripts/db/check_migration.py python scripts/db/migrate.py python -m ruff check app tests python -m pytest ``` ```bash cd web/admin pnpm build ``` 压测基线： ```bash python scripts/ops/loadtest_http.py --base-url http://127.0.0.1:8000 --path / --requests 1000 --concurrency 50 ``` --- ## 相关文档 - [docs/iam.md](docs/iam.md) - [docs/migration.md](docs/migration.md) - [docs/production.md](docs/production.md) - [migrations/README.md](migrations/README.md) - [web/admin/README.md](web/admin/README.md) - [web/portal/README.md](web/portal/README.md) - [web/admin-uniapp/README.md](web/admin-uniapp/README.md) --- ## License MIT License。详见 [LICENSE](LICENSE)。