zh deploy settings

系统环境设置

配置系统运行的一些环境信息，文件位于 data/config.yaml。 一般不需要修改。

admins: []
api:
    port: 5300
    webhook_prefix: 'http://127.0.0.1:5300'
    extra_webhook_prefix: ''
    global_api_key: ''  # 全局 API Key。非空时即可直接用于 HTTP API 与 MCP 服务（/mcp）鉴权，无需登录态、无需数据库记录、无需 lbk_ 前缀；留空则关闭。明文存储，仅在可信/内网部署启用并配合 HTTPS。
command:
    enable: true
    prefix:
    - '!'
    - ！
    privilege: {}
concurrency:
    pipeline: 20
    session: 1
proxy:
    http: ''
    https: ''
system:
    instance_id: ''
    edition: community
    recovery_key: ''
    allow_modify_login_info: true
    disabled_adapters: []
    limitation:
        max_bots: -1
        max_pipelines: -1
        max_extensions: -1
    task_retention:
        # 内存中最多保留的已完成异步任务记录数量
        completed_limit: 200
    jwt:
        expire: 604800
        secret: ''
database:
    use: sqlite
    sqlite:
        path: 'data/langbot.db'
    postgresql:
        host: '127.0.0.1'
        port: 5432
        user: 'postgres'
        password: 'postgres'
        database: 'postgres'
vdb:
    use: chroma
    qdrant:
        url: ''
        host: localhost
        port: 6333
        api_key: ''
    seekdb:
        mode: embedded  # 'embedded' 或 'server'
        # 嵌入式模式配置：
        path: './data/seekdb'
        database: 'langbot'
        # 服务器模式配置（mode='server' 时生效）：
        host: 'localhost'
        port: 2881
        user: 'root'
        password: ''
        tenant: ''  # 可选，用于 OceanBase 多租户场景
    milvus:
        uri: 'http://127.0.0.1:19530'
        token: ''
        db_name: ''
    pgvector:
        host: '127.0.0.1'
        port: 5433
        database: 'langbot'
        user: 'postgres'
        password: 'postgres'
    valkey_search:
        host: 'localhost'
        port: 6379
        db: 0
        username: ''      # 可选（ACL 用户）
        password: ''      # 可选（ACL / requirepass），不会记录到日志
        tls: false        # 可选，用于 toB/SaaS 场景
        index_algorithm: 'HNSW'    # HNSW（近似）或 FLAT（精确）
        distance_metric: 'COSINE'  # COSINE、L2 或 IP
        request_timeout: 5000      # 单次请求超时时间（毫秒）
storage:
    use: local
    cleanup:
        # 是否定期清理本地/S3 上传文件和旧日志文件
        enabled: true
        # 清理检查间隔，单位为小时
        check_interval_hours: 1
        # 超过此天数的根目录上传文件会被删除
        uploaded_file_retention_days: 7
        # 最多保留此天数内的 LangBot 日志文件
        log_retention_days: 3
    s3:
        endpoint_url: ''
        access_key_id: ''
        secret_access_key: ''
        region: 'us-east-1'
        bucket: 'langbot-storage'
plugin:
    enable: true
    runtime_ws_url: 'ws://langbot_plugin_runtime:5400/control/ws'
    enable_marketplace: true
    display_plugin_debug_url: 'ws://localhost:5401/plugin/debug/ws'
    binary_storage:
        # 单个插件二进制存储值的最大字节数
        max_value_bytes: 10485760
monitoring:
    auto_cleanup:
        # 是否自动清理过期监控记录
        enabled: true
        # 监控记录保留天数，超过此天数的记录会被删除
        retention_days: 30
        # 清理检查间隔，单位为小时
        check_interval_hours: 1
        # 每个监控表单批删除的过期记录数量
        delete_batch_size: 1000
box:
    enabled: true  # Box Runtime 总开关。false 时禁用沙箱、Skill 添加/编辑和 stdio MCP 等依赖 Box 的功能。
    backend: 'local'  # 'local' (Docker/nsjail), 'docker', 'nsjail', 或 'e2b'。可通过 BOX__BACKEND 写入。
    runtime:
        endpoint: ''  # 外部 Box Runtime 基础 URL，如 'ws://127.0.0.1:5410'。留空时，非 Docker 部署使用本地自动管理的 Runtime；Docker 部署连接 Compose 网络中的 langbot_box:5410。
    local:
        profile: 'default'
        image: ''  # 自定义本地沙箱镜像。留空使用 profile 默认值。
        host_root: './data/box'  # 本地工作区挂载的主机根目录。Docker 部署时应使用可被 langbot_box 挂载的绝对主机路径。
        default_workspace: ''  # 默认为 '<host_root>/default'。
        skills_root: 'skills'  # Box 管理的 Skill 包目录。相对路径会解析到 host_root 下。
        allowed_mount_roots:  # 默认为 ['<host_root>']。
            - './data/box'
            - '/tmp'
        workspace_quota_mb: null  # 可选磁盘配额上限（>=0）。null=套餐默认值。
    default_memory_mb: 1536  # 每个 MCP stdio 进程的 nsjail cgroup 内存上限（MB）。Node.js 类 MCP（npx/bunx）因 V8+WASM 需要更多内存，过低会导致进程被 OOM 杀死（return_code=137）。可用 BOX__DEFAULT_MEMORY_MB 覆盖。  # 可选磁盘配额覆盖 (>= 0)。null 表示使用 profile 默认值。
    docker:
        cpu_limit_enabled: true  # false 时 Docker 沙箱容器不传 --cpus；内存和 PID 限制仍然生效。
    e2b:
        api_key: ''  # 也可通过 E2B_API_KEY 环境变量设置。
        api_url: ''  # 自托管部署的自定义 API URL。
        template: ''  # 默认模板 ID（如 'base', 'python-3.11'）。
space:
    # Space 服务 URL
    url: 'https://space.langbot.app'
    # Space 模型请求 API URL（MaaS）
    models_gateway_api_url: 'https://api.langbot.cloud/v1'
    # OAuth 授权页面 URL
    oauth_authorize_url: 'https://space.langbot.app/auth/authorize'
    disable_models_service: false
    disable_telemetry: false

配置说明

• storage.cleanup.uploaded_file_retention_days 只清理存储根目录下的临时上传文件，不会清理插件配置文件或带目录的内部对象。
• storage.cleanup.log_retention_days 按日志文件名中的日期清理旧日志，默认最多保留 3 天。
• SQLite 作为数据库时，监控记录自动清理后会直接释放数据库文件空间。
• plugin.binary_storage.max_value_bytes 用于限制插件单个二进制存储值大小，默认 10 MiB。
• WebUI 侧边栏的“存储分析”页面可查看数据库、日志、上传文件、向量库、插件、MCP、临时文件等空间占用和清理候选项。
• vdb.valkey_search 基于 Valkey Search 模块，通过官方异步客户端 valkey-glide 接入，支持向量搜索、全文搜索和混合搜索三种模式。需要运行已加载该模块的服务，例如 valkey/valkey-bundle:9.1.0（docker run -d -p 6379:6379 valkey/valkey-bundle:9.1.0）。注意：混合搜索采用先过滤再 KNN 的模型，因此 vector_weight 参数虽被接受但不会生效（Valkey Search 原生限制）。连接为惰性建立，服务不可用或配置错误不会阻塞启动。详见 Valkey Search 集成文档。
• api.global_api_key 是面向 Agent / 自动化的全局 API Key：设置后，调用 HTTP API 或内置 MCP 服务（/mcp）时在请求头携带 X-API-Key: <key> 或 Authorization: Bearer <key> 即可鉴权，无需登录会话、无需在数据库中创建 lbk_ 密钥。它是明文写在 config.yaml 中的，请仅在可信 / 内网环境启用，并通过 HTTPS 暴露。详见 API Key 鉴权。

通过环境变量设置

config.yaml 中的配置可以通过环境变量进行设置。环境变量名称为大写字母，使用双下划线连接，例如：API__PORT 代表 api.port。

• API__PORT 代表 api.port
• CONCURRENCY__PIPELINE 代表 concurrency.pipeline
• DATABASE__SQLITE__PATH 代表 database.sqlite.path
• STORAGE__CLEANUP__UPLOADED_FILE_RETENTION_DAYS 代表 storage.cleanup.uploaded_file_retention_days
• STORAGE__CLEANUP__LOG_RETENTION_DAYS 代表 storage.cleanup.log_retention_days
• MONITORING__AUTO_CLEANUP__RETENTION_DAYS 代表 monitoring.auto_cleanup.retention_days
• PLUGIN__BINARY_STORAGE__MAX_VALUE_BYTES 代表 plugin.binary_storage.max_value_bytes
• BOX__ENABLED 代表 box.enabled
• BOX__BACKEND 代表 box.backend
• BOX__LOCAL__HOST_ROOT 代表 box.local.host_root
• BOX__LOCAL__SKILLS_ROOT 代表 box.local.skills_root

在启动时，LangBot 会读取所有环境变量，将对应的配置应用到 config.yaml 中并写入到 data/config.yaml 文件中。

Note

Box 相关配置应设置在 langbot 服务上，使用统一的 BOX__* 环境变量。LangBot 会在启动时写入 data/config.yaml，并通过 INIT RPC 将 Box 配置传给 langbot_box。不要在 langbot_box 服务上设置 LANGBOT_BOX_* 或 BOX__*，这些变量不会被直接读取。