16-配置文件详解

Judge0 的配置系统采用分层架构设计，通过环境变量驱动核心行为，支持灵活的部署定制。本页面深入剖析从配置文件到运行时行为的完整配置链路。

配置架构总览

flowchart TB
    subgraph "配置文件层"
        A["judge0.conf<br/>主配置文件"] 
        B["docker-compose.yml<br/>服务编排配置"]
        C["config/database.yml<br/>Rails数据库配置"]
    end

    subgraph "环境变量加载层"
        D["scripts/load-config<br/>配置加载脚本"]
        E["scripts/server<br/>服务启动脚本"]
        F["scripts/workers<br/>工作进程脚本"]
    end

    subgraph "Rails运行时层"
        G["Config Module<br/>配置常量模块"]
        H["Submission Model<br/>提交模型"]
        I["IsolateJob<br/>沙箱执行任务"]
    end

    A --> D
    B --> D
    D --> E
    D --> F
    E --> G
    F --> G
    G --> H
    G --> I

配置系统遵循「配置文件 → 环境变量 → Rails常量」的单向数据流。judge0.conf 作为主配置入口，通过 load-config 脚本加载为环境变量，最终在 Rails 应用启动时由 Config 模块（app/helpers/config.rb）消费。

Sources: judge0.conf, scripts/load-config, app/helpers/config.rb

judge0.conf 核心配置段

judge0.conf 是 Judge0 的主配置文件，采用 Shell 变量格式，便于 Docker 环境直接加载。文件按功能分为七大配置段。

服务端通用配置

变量名	默认值	说明
JUDGE0_TELEMETRY_ENABLE	true	遥测数据收集开关
RESTART_MAX_TRIES	10	启动失败自动重试次数
MAINTENANCE_MODE	false	维护模式开关
MAINTENANCE_MESSAGE	Judge0 is currently in maintenance.	维护模式提示信息
ENABLE_WAIT_RESULT	true	允许客户端同步等待提交结果
USE_DOCS_AS_HOMEPAGE	false	是否将文档页设为主页
DISABLE_IMPLICIT_BASE64_ENCODING	false	禁用隐式Base64编码

维护模式启用后，系统将拒绝创建和删除提交请求，返回配置的维护提示信息。此配置常用于版本升级或数据迁移期间的服务保护。

Sources: judge0.conf

提交行为配置

变量名	默认值	说明
ENABLE_COMPILER_OPTIONS	true	允许用户设置编译器选项
ALLOWED_LANGUAGES_FOR_COMPILER_OPTIONS	空	允许设置编译器选项的语言列表
ENABLE_COMMAND_LINE_ARGUMENTS	true	允许用户设置命令行参数
ENABLE_SUBMISSION_DELETE	false	允许删除已完成的提交
ENABLE_CALLBACKS	true	允许使用回调通知
CALLBACKS_MAX_TRIES	3	回调最大重试次数
CALLBACKS_TIMEOUT	5	回调超时时间（秒）
ENABLE_ADDITIONAL_FILES	true	允许上传附加文件
SUBMISSION_CACHE_DURATION	1	提交结果缓存时长（秒）
ENABLE_BATCHED_SUBMISSIONS	true	启用批量提交功能
MAX_SUBMISSION_BATCH_SIZE	20	批量提交最大数量

这些配置控制用户对提交行为的自定义能力。ENABLE_SUBMISSION_DELETE 默认禁用以防止误操作，CALLBACKS_* 系列配置则服务于 webhook 集成场景。

Sources: judge0.conf, app/controllers/submissions_controller.rb

Worker 并行配置

变量名	默认值	说明
INTERVAL	0.1	轮询间隔（秒）
COUNT	2*nproc	并行 worker 数量
MAX_QUEUE_SIZE	100	队列最大容量

COUNT 的默认值 2*nproc 表示 worker 数量为 CPU 核心数的两倍，通过 load-config 脚本动态计算。MAX_QUEUE_SIZE 控制同时等待处理的提交上限，超出时新提交将被拒绝。

Sources: judge0.conf, scripts/load-config

访问控制配置

变量名	说明
ALLOW_ORIGIN	允许的跨域来源（空格分隔）
DISALLOW_ORIGIN	禁止的跨域来源（空格分隔）
ALLOW_IP	允许的 IP 地址列表
DISALLOW_IP	禁止的 IP 地址列表

跨域配置通过 Rack::Cors 中间件实现，DISALLOW_ORIGIN 使用负向正则匹配排除指定来源。IP 访问控制则在应用层实现白名单/黑名单逻辑。

Sources: judge0.conf, config/application.rb

认证与授权配置

变量名	默认值	说明
AUTHN_HEADER	X-Auth-Token	认证请求头名称
AUTHN_TOKEN	空（禁用）	认证令牌
AUTHZ_HEADER	X-Auth-User	授权请求头名称
AUTHZ_TOKEN	空（禁用）	授权令牌

认证机制要求每个请求携带指定的 Header 键值对。授权机制则用于保护特定 API 端点（如删除提交、批量查询），区分普通用户和特权用户。

Sources: judge0.conf

Redis 配置

变量名	默认值	说明
REDIS_HOST	redis	Redis 服务地址
REDIS_PORT	6379	Redis 端口
REDIS_PASSWORD	必填	Redis 访问密码
RESQUE_NAMESPACE	Resque默认	Redis命名空间

Redis 用于 Resque 任务队列的持久化存储，RESQUE_NAMESPACE 支持多环境隔离部署。

Sources: judge0.conf, config/initializers/resque.rb

PostgreSQL 配置

变量名	默认值	说明
POSTGRES_HOST	db	数据库主机
POSTGRES_PORT	5432	数据库端口
POSTGRES_DB	postgres	数据库名称
POSTGRES_USER	postgres	数据库用户
POSTGRES_PASSWORD	必填	数据库密码

数据库连接池大小由 RAILS_SERVER_PROCESSES * RAILS_MAX_THREADS 动态计算，确保高并发下的连接复用。

Sources: judge0.conf, config/database.yml

沙箱执行配置

沙箱配置是 Judge0 的核心，决定代码执行的资源限制和安全边界。这些配置映射到 isolate 沙箱工具的参数。

时间与内存限制

变量名	默认值	说明
CPU_TIME_LIMIT	5	默认CPU时间限制（秒）
MAX_CPU_TIME_LIMIT	15	用户可设置的最大CPU时间
CPU_EXTRA_TIME	1	超时后额外等待时间（秒）
MAX_CPU_EXTRA_TIME	5	用户可设置的最大额外时间
WALL_TIME_LIMIT	10	默认墙钟时间限制（秒）
MAX_WALL_TIME_LIMIT	20	用户可设置的最大墙钟时间
MEMORY_LIMIT	128000	默认内存限制（KB）
MAX_MEMORY_LIMIT	512000	用户可设置的最大内存

CPU_TIME_LIMIT 计量纯 CPU 计算时间，不包含等待 I/O 的时间。WALL_TIME_LIMIT 作为防御性配置，用于捕获死循环或睡眠状态的程序。

Sources: judge0.conf, app/jobs/isolate_job.rb

进程与线程限制

变量名	默认值	说明
STACK_LIMIT	64000	默认栈大小限制（KB）
MAX_STACK_LIMIT	128000	用户可设置的最大栈大小
MAX_PROCESSES_AND_OR_THREADS	60	默认最大进程/线程数
MAX_MAX_PROCESSES_AND_OR_THREADS	120	用户可设置的最大进程/线程数
ENABLE_PER_PROCESS_AND_THREAD_TIME_LIMIT	false	启用逐进程/线程时间限制
ALLOW_ENABLE_PER_PROCESS_AND_THREAD_TIME_LIMIT	true	允许用户启用逐进程时间限制

逐进程限制通过 cgroups 实现，当启用时会消耗额外系统资源但提供更精细的控制粒度。

Sources: judge0.conf, app/jobs/isolate_job.rb

文件与网络限制

变量名	默认值	说明
MAX_FILE_SIZE	1024	默认最大文件大小（KB）
MAX_MAX_FILE_SIZE	4096	用户可设置的最大文件大小
NUMBER_OF_RUNS	1	执行次数（取平均值）
MAX_NUMBER_OF_RUNS	20	用户可设置的最大执行次数
REDIRECT_STDERR_TO_STDOUT	false	将stderr重定向到stdout
MAX_EXTRACT_SIZE	10240	解压附加文件总大小限制（KB）
ALLOW_ENABLE_NETWORK	true	允许用户控制网络访问
ENABLE_NETWORK	false	默认是否启用网络访问

NUMBER_OF_RUNS 大于1时，系统会执行多次并计算平均时间和内存，适用于性能基准测试场景。

Sources: judge0.conf, app/jobs/isolate_job.rb

Rails 应用配置

除 judge0.conf 外，Rails 应用本身也有一组独立配置参数。

变量名	默认值	说明
RAILS_ENV	production	Rails运行环境
RAILS_MAX_THREADS	nproc	每个进程的线程数
RAILS_SERVER_PROCESSES	2	服务进程数
SECRET_KEY_BASE	随机生成	生产密钥

RAILS_MAX_THREADS 和 RAILS_SERVER_PROCESSES 共同决定并发处理能力。生产环境中建议根据 CPU 核心数和预期负载调整。

Sources: judge0.conf, config/puma.rb

Docker Compose 服务配置

Docker Compose 定义了四个核心服务的编排关系。

services:
  server:      # HTTP API 服务
    image: judge0/judge0:latest
    volumes:
      - ./judge0.conf:/judge0.conf:ro
    ports:
      - "2358:2358"
    privileged: true

  worker:      # 后台任务处理
    image: judge0/judge0:latest
    command: ["./scripts/workers"]
    volumes:
      - ./judge0.conf:/judge0.conf:ro
    privileged: true

  db:           # PostgreSQL 数据库
    image: postgres:16.2
    env_file: judge0.conf

  redis:        # Resque 任务队列
    image: redis:7.2.4
    command: ["--requirepass $$REDIS_PASSWORD"]
    env_file: judge0.conf

所有服务通过 env_file 加载相同的 judge0.conf，确保配置一致性。privileged: true 是 isolate 沙箱正常运行的必要条件。

Sources: docker-compose.yml

配置加载时序

启动脚本的执行顺序确保配置在应用启动前完成加载：

sequenceDiagram
    participant S as scripts/server
    participant L as scripts/load-config
    participant R as Rails App
    participant C as Config Module

    S->>L: source ./scripts/load-config
    L->>L: 查找 judge0.conf
    L->>L: 加载环境变量
    L->>L: 设置默认值
    L->>S: export 所有变量
    S->>S: rake db:create db:migrate db:seed
    S->>R: rails s -b 0.0.0.0
    R->>C: 初始化 Config 模块
    C->>C: 读取 ENV[...] 常量化

load-config 脚本的优先级逻辑：容器内 /judge0.conf 优先于 /api/judge0.conf，允许 Docker 卷挂载覆盖默认配置。

Sources: scripts/load-config, scripts/server

Config 模块实现

Config 模块（app/helpers/config.rb）将环境变量转换为 Ruby 常量，供整个应用访问：

module Config
  # 布尔型配置：ENV == "true" 时为真
  MAINTENANCE_MODE = ENV["MAINTENANCE_MODE"] == "true"

  # 数值型配置：支持默认值
  CPU_TIME_LIMIT = (ENV["CPU_TIME_LIMIT"].presence || 5).to_f

  # 列表型配置：空格分隔
  ALLOWED_LANGUAGES_FOR_COMPILER_OPTIONS = 
    ENV["ALLOWED_LANGUAGES_FOR_COMPILER_OPTIONS"].to_s.strip.split
end

这种设计将配置访问统一为常量引用，避免运行时重复解析环境变量带来的开销。

Sources: app/helpers/config.rb

配置验证与约束

Submission 模型在创建时验证用户请求的参数是否在系统允许范围内：

validates :cpu_time_limit,
  numericality: { greater_than_or_equal_to: 0, 
                   less_than_or_equal_to: Config::MAX_CPU_TIME_LIMIT }
validates :memory_limit,
  numericality: { greater_than_or_equal_to: 2048, 
                   less_than_or_equal_to: Config::MAX_MEMORY_LIMIT }

此机制确保用户自定义参数不会超过系统管理员设定的安全上限。

Sources: app/models/submission.rb

典型部署配置示例

生产环境推荐的最小 judge0.conf 配置：

# === 必填项 ===
REDIS_PASSWORD=your_redis_password_here
POSTGRES_PASSWORD=your_postgres_password_here

# === 安全强化 ===
ENABLE_SUBMISSION_DELETE=false
ENABLE_NETWORK=false
MAX_CPU_TIME_LIMIT=10
MAX_MEMORY_LIMIT=256000

# === 性能调优 ===
COUNT=4          # 根据CPU核心数调整
MAX_QUEUE_SIZE=200
RAILS_SERVER_PROCESSES=4
RAILS_MAX_THREADS=8

# === 运维配置 ===
JUDGE0_TELEMETRY_ENABLE=false  # 禁用遥测
MAINTENANCE_MODE=false

此配置关闭遥测收集、禁用网络访问、设置合理的资源限制，适合对安全要求较高的私有部署场景。

下一步

配置完成后，建议进一步了解：

• Docker Compose 服务架构 – 深入理解服务编排细节
• 安全机制与沙箱隔离 – isolate 沙箱的隔离原理
• 性能调优与扩展 – 高并发场景优化指南

相关条目

• 10-Language 语言配置模型
• 17-Docker Compose 服务架构