boxlang-configuration

BoxLang 配置

BoxLang 是一个 AI 原生软件生产力平台，用于构建、现代化和运行应用程序，让开发者与 AI Agent 协同工作。

概览

BoxLang 运行时通过 boxlang.json 配置。首次启动时，该文件会自动创建在 BoxLang 主目录中。无需修改文件，即可通过环境变量或 Java 系统属性覆盖所有设置。

如果配置问题涉及 Application.bx 中特定于应用的行为（this.name、生命周期回调、每个应用各自的调度器／监视器、嵌套应用隔离），请同时参考 application-descriptor 技能。

---

配置文件位置

运行时	默认位置
OS / CLI / MiniServer	~/.boxlang/config/boxlang.json
CLI 项目覆盖（v1.18+）	当前工作目录下的 ./.boxlang.json；仅当未设置 BOXLANG_CONFIG / --bx-config 时使用
AWS Lambda	{lambdaRoot}/boxlang.json
Google Cloud Functions	{gcfRoot}/boxlang.json
CommandBox	~/.commandbox/servers/{home}/WEB-INF/boxlang/config/boxlang.json

在启动时覆盖主目录：

boxlang --home /path/to/custom-home

---

环境变量覆盖

任何设置都可以通过环境变量或 JVM 属性覆盖，使用 BOXLANG_ 前缀（snake_case）或 boxlang. 前缀（点号表示法）：

# Enable debug mode
BOXLANG_DEBUGMODE=true

# Set log level for runtime logger
boxlang.logging.loggers.runtime.level=TRACE

# Set as JVM argument
java -Dboxlang.debugMode=true -jar boxlang.jar

支持使用 JSON 值进行复杂覆盖：

BOXLANG_DATASOURCES='{"mainDB":{"driver":"postgresql","host":"db.example.com"}}'

---

环境变量替换

在 boxlang.json 中使用 ${env.VAR:default} 引用环境变量：

{
    "datasources": {
        "mainDB": {
            "driver":   "postgresql",
            "host":     "${env.DB_HOST:localhost}",
            "port":     "${env.DB_PORT:5432}",
            "database": "${env.DB_NAME:myapp}",
            "username": "${env.DB_USER:app}",
            "password": "${env.DB_PASSWORD}"
        }
    }
}

内置路径替换变量：

变量	解析为
${boxlang-home}	BoxLang 主目录
${user-home}	OS 用户主目录
${user-dir}	当前工作目录
${java-temp}	Java 临时目录

---

核心指令

{
    // Compiled class output directory
    "classGenerationDirectory": "${boxlang-home}/classes",

    // Compiler backend: "asm" (default, best performance) or "java"
    "compiler": "asm",

    // Store compiled classes on disk (recommended: true for production)
    "storeClassFilesOnDisk": true,

    // Never re-check class files (recommended: true for production)
    "trustedCache": false,

    // Cache class resolver lookups (recommended: true)
    "classResolverCache": true,

    // Clear class files on startup (use only for debugging)
    "clearClassFilesOnStartup": false,

    // Global class paths (.bx file discovery)
    "classPaths": [
        "${boxlang-home}/global/classes"
    ],

    // Custom component directories
    "customComponentsDirectory": [
        "${boxlang-home}/global/components"
    ],

    // Default datasource name
    "defaultDatasource": "",

    // Max completed threads tracked per request
    "maxTrackedCompletedThreads": 1000,

    // Enable debug output in responses
    "debugMode": false
}

---

数据源

{
    "datasources": {
        "mainDB": {
            "driver":   "postgresql",
            "host":     "${env.DB_HOST:localhost}",
            "port":     5432,
            "database": "myapp",
            "username": "${env.DB_USER:app}",
            "password": "${env.DB_PASSWORD}"
        },
        "legacyMySQL": {
            "driver":   "mysql",
            "host":     "db2.internal",
            "port":     3306,
            "database": "legacy",
            "username": "${env.MYSQL_USER}",
            "password": "${env.MYSQL_PASS}",
            // Connection pool settings
            "connectionTimeout":   30,
            "maximumPoolSize":     10,
            "minimumIdle":         2
        }
    }
}

支持的驱动程序：postgresql、mysql、mssql、oracle、derby、h2、sqlite。

---

缓存

{
    "caches": {
        // Default cache (used when no cache name specified)
        "default": {
            "provider": "BoxCacheProvider",
            "properties": {
                "maxObjects":       1000,
                "defaultTimeout":   60,
                "defaultLastAccessTimeout": 0,
                "objectStore":      "ConcurrentStore"
            }
        },
        // Named cache for templates
        "templates": {
            "provider": "BoxCacheProvider",
            "properties": {
                "maxObjects": 500,
                "defaultTimeout": 120
            }
        }
    }
}

---

执行器

{
    "executors": {
        // Default executor for runAsync() — virtual threads
        "boxlang-tasks": {
            "type": "virtual",
            "coreThreads": 20
        },
        // CPU-bound work pool
        "cpu-work": {
            "type": "fixed",
            "coreThreads": 8
        },
        // Elastic pool for bursty I/O
        "io-tasks": {
            "type": "cached"
        },
        // Scheduler pool
        "scheduler": {
            "type": "scheduled",
            "coreThreads": 5
        }
    }
}

执行器类型：virtual（默认，Project Loom）、fixed、cached、scheduled、work_stealing。

---

日志记录

{
    "logging": {
        "logsDirectory": "${boxlang-home}/logs",
        "level": "WARN",   // Global default: TRACE, DEBUG, INFO, WARN, ERROR
        "loggers": {
            "runtime":    { "level": "INFO" },
            "scheduler":  { "level": "INFO", "async": true },
            "datasource": { "level": "WARN" },
            "cache":      { "level": "WARN" },
            "modules":    { "level": "INFO" }
        }
    }
}

---

安全性

{
    "security": {
        // Regex patterns for blocked Java class imports
        "disallowedImports": [],
        // Blocked BIF names
        "disallowedBifs": [],
        // Blocked component names
        "disallowedComponents": [],
        // Whether Java system props/env are in server.system scope
        "populateServerSystemScope": true,
        // Explicit upload extension whitelist (overrides disallowed list)
        "allowedFileOperationExtensions": [],
        // Blocked file upload/move extensions
        "disallowedFileOperationExtensions": []
    }
}

---

模块

配置启动时加载的模块及模块专属设置：

{
    "modules": {
        // Modules to load on startup (in addition to auto-discovered modules)
        "load": [ "bx-compat-cfml", "bx-orm" ],
        // Modules to skip loading even if present
        "exclude": [],
        // Per-module settings
        "settings": {
            "bx-orm": {
                "autoManageSession": true,
                "dialect":           "PostgreSQLDialect"
            }
        }
    }
}

---

调度器

{
    "scheduler": {
        // Default task timeout (0 = no timeout)
        "defaultTimeout": 0,
        // How long to wait for scheduled tasks to complete on shutdown
        "shutdownTimeout": 30,
        // Executor to use for scheduled tasks
        "executor": "scheduler"
    }
}

---

监视器

配置用于文件系统监控的内置 WatcherService。监视器会响应文件／目录变更，并可触发热重载、资源构建或自定义自动化操作。

{
    "watcher": {
        // Recurse into subdirectories by default
        "recursive": true,
        // Hold events until no new event arrives within this window (ms); 0 = off
        "debounce": 300,
        // Emit at most one event per window and drop the rest (ms); 0 = off
        "throttle": 0,
        // Suppress noisy intermediate events from atomic save patterns (temp + rename)
        "atomicWrites": true,
        // Startup delay before watchers begin processing events (ms)
        "delay": 0,
        // Auto-stop watcher after this many consecutive listener errors (0 = disabled)
        "errorThreshold": 10,
        // Named watcher definitions auto-started at runtime startup
        "definitions": {
            "hot-reload": {
                "paths":    "${user-dir}/src",
                "listener": "app.listeners.HotReloadListener"
            },
            "assets": {
                "paths":     [ "${user-dir}/resources/css", "${user-dir}/resources/js" ],
                "recursive": false,
                "throttle":  500,
                "listener":  "app.listeners.AssetPipelineListener"
            }
        }
    }
}

监视器定义属性

属性	必填	描述
paths	是	要监控的目录路径或路径数组
listener	是	包含监听器行为的 BoxLang 类路径
recursive	否	覆盖全局递归设置
debounce	否	单个监视器的防抖设置覆盖（毫秒）
throttle	否	单个监视器的节流设置覆盖（毫秒）
atomicWrites	否	单个监视器的原子写入筛选设置覆盖
delay	否	单个监视器的启动延迟设置覆盖（毫秒）
errorThreshold	否	单个监视器的错误阈值设置覆盖

对于闭包和基于 struct 的监听器，请在运行时使用 watcherNew() 以编程方式创建监视器，而不要在 boxlang.json 中配置。

运行时监视器 BIF

watcherNew()、watcherStart()、watcherStop()、watcherRestart()、watcherList()、watcherGet()、watcherExists()、watcherShutdown()、watcherStopAll()、watcherShutdownAll()

---

运行时设置

用户定义的全局命名设置。BoxLang 不会对其进行解释。值可以是任意类型（字符串、数字、布尔值、结构体、数组），键必须唯一。

{
    "runtimeSettings": {
        "apiUrl":    "${env.API_URL:http://localhost}",
        "stripeKey": "bxsecret:AbC123...",
        "features":  { "beta": true, "regions": [ "us", "eu" ] }
    }
}

• ${env.VAR}、${env.VAR:default}、路径变量和 bxsecret: 值可在任意深度解析，包括数组内部。插值后的值为字符串。没有默认值的未解析占位符会保持原样。
• 使用 getRuntimeSetting( key, default ) BIF 读取：支持点分路径（features.beta）、从 1 开始的数组索引（features.regions.1）；不传参数时返回合并后的整个结构体；缺少键且未提供默认值时会抛出异常。
• 值为深度只读。
• Application.bx 中的 this.runtimeSettings（或 bx:application runtimeSettings={...}）会与全局结构体进行深度合并，应用层的键优先。数组和标量会被替换，而不是合并。
• 全局值会在运行时配置加载时解析一次。每次重新读取描述符时，都会重新解析 Application.bx 层的 ${...} 和 bxsecret:，然后在该请求期间缓存。应用层只有 runtimeSettings 会进行 ${...} 插值。
• 这与读取 Java 系统属性和环境变量的 getSystemSetting() 不同。

---

实验性功能

用于 BoxLang 开发中功能的功能标志。这些设置可能会更改或移除。

{
    "experimental": {
        // Compiler backend: "asm" (default, direct bytecode) or "java" (transpile to Java first)
        "compiler": "asm",
        // Capture AST JSON to /grapher/data on each parse (for tooling/debugging only)
        "ASTCapture": false
    }
}

标志	默认值	描述
compiler	"asm"	"asm" 直接编译为字节码（生产环境默认值）；"java" 会先转译为 Java 源代码
ASTCapture	false	每次解析时将 AST JSON 写入 /grapher/data — 仅用于工具和调试，绝不用于生产环境

---

应用级配置（Application.bx）

应用级设置会覆盖运行时配置中针对特定应用的设置：

class {
    // Application identity
    this.name             = "MyApp"
    this.sessionManagement = true
    this.sessionTimeout   = createTimeSpan( 0, 2, 0, 0 )

    // Datasource
    this.datasource = "mainDB"

    // Per-application datasource definition
    this.datasources = {
        localDB: {
            driver:   "h2",
            database: expandPath( "/db/local.h2" )
        }
    }

    // Java library paths
    this.javaSettings = {
        loadPaths: [ expandPath( "/lib/" ) ]
    }

    // Cache mappings
    this.caches = {
        objects: { provider: "BoxCacheProvider" }
    }

    // Directory mappings
    this.mappings = {
        "/models":   expandPath( "/app/models/" ),
        "/services": expandPath( "/app/services/" )
    }
}

---

生产环境配置检查清单

• trustedCache: true — 不会在每次请求时检查磁盘
• classResolverCache: true — 缓存类解析结果
• debugMode: false — 响应中不包含调试输出
• logging.level: "WARN" — 抑制详细日志
• 通过 ${env.VAR} 设置密钥 — 切勿在 boxlang.json 中硬编码
• 将 classGenerationDirectory 设置在高速磁盘（SSD/tmpfs）上
• 根据预期并发量调整连接池大小
• 如果不需要系统环境变量，则设置 security.populateServerSystemScope: false