xinyin025/LangBot
1
0
Fork 0
mirror of https://github.com/langbot-app/LangBot.git synced 2026-10-30 04:15:45 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
6dcbcf6eac02268d8a70c232d0a7c71035bc60b5
LangBot/zh/deploy/settings.mdx
T

436 lines
20 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: "系统环境设置"
description: "完整说明 LangBot config.yaml 的 API、并发、数据库、向量库、存储、插件、MCP、监控与 Box 配置。"
---
LangBot 的运行配置位于 `data/config.yaml`。首次启动会从默认模板生成该文件；下面的示例与 LangBot 仓库中的 [`src/langbot/templates/config.yaml`](https://github.com/langbot-app/LangBot/blob/master/src/langbot/templates/config.yaml) 保持一致。
<Info>
大多数自部署用户只需要关注公网地址、数据库/向量库、对象存储与 Box Runtime。未理解用途的容量和 Cloud 安全上限建议保持默认值。
</Info>
## 完整默认配置
```yaml
# HTTP API 与 WebUI 配置。
api:
port: 5300
webhook_prefix: 'http://127.0.0.1:5300'
extra_webhook_prefix: ''
# WebUI 与 API 分开部署时填写浏览器访问来源；OAuth 只信任此值和 webhook_prefix。
webui_url: ''
# 全局 API 密钥；留空表示禁用。生产环境请通过环境变量注入并妥善保密。
global_api_key: ''
# Workspace 相关配置。
workspace:
# 成员邀请链接与可选邮件发送设置。
invitations:
# 邀请链接使用的 WebUI 公网地址；留空时回退到 api.webui_url 和 api.webhook_prefix。
public_web_url: ''
# provider 留空时只生成链接；可选 resend 或 smtp。
email:
provider: ''
from: ''
timeout_seconds: 10
resend:
api_url: 'https://api.resend.com/emails'
api_key: ''
smtp:
host: ''
port: 587
username: ''
password: ''
starttls: true
ssl: false
# 命令系统、命令前缀与权限映射。
command:
enable: true
prefix:
- '!'
- ！
privilege: {}
# 流水线、会话以及排队请求的并发准入上限。
concurrency:
pipeline: 20
session: 1
pending_queries: 1000
pending_queries_per_workspace: 100
# Webhook 数量与实例级并发请求上限，防止无界排队。
webhooks:
max_per_workspace: 16
max_inflight_requests: 16
# Cloud 单个逻辑实例的运行安全上限，不代表套餐权益。
cloud:
# 超过目录上限的权威更新会整体拒绝，不会静默截断。
directory:
max_active_workspaces: 1000
max_snapshot_workspaces: 1000
max_snapshot_memberships: 20000
max_response_bytes: 33554432
# 出站 HTTP/HTTPS 代理。
proxy:
http: ''
https: ''
# 实例身份、全局资源限制与运行时保留策略。
system:
instance_id: ''
edition: community
recovery_key: ''
allow_modify_login_info: true
disabled_adapters: []
# 所有 asyncio.to_thread 任务共享的有界线程池。
blocking_executor:
max_workers: 8
max_pending: 128
max_inflight_per_scope: 4
# 对外访问 IP；部分机器人平台要求将其加入可信 IP 白名单。
outbound_ips: []
# 实例级数量限制；-1 表示不限制。
limitation:
max_bots: -1
max_pipelines: -1
max_extensions: -1
max_knowledge_bases: -1
# SaaS 可强制统一沙箱作用域；普通自部署保持空字符串。
force_box_session_id_template: ''
# 异步任务记录、日志与用户主动任务并发限制。
task_retention:
completed_limit: 200
max_log_chars: 200000
max_active_user_tasks: 256
max_active_user_tasks_per_workspace: 8
# 进程内会话缓存限制；这不是持久聊天记录。
session_retention:
max_entries: 2000
max_entries_per_workspace: 200
idle_ttl_seconds: 86400
max_conversations_per_session: 20
max_messages_per_conversation: 100
# 浏览器连接、Workspace 代理缓存与发送队列上限。
websocket_retention:
max_connections: 1024
max_connections_per_workspace: 32
max_workspace_proxies: 1024
max_conversations_per_workspace: 200
max_messages_per_conversation: 100
conversation_idle_ttl_seconds: 86400
send_queue_size: 100
# 单次上游响应的字符数与流式分块上限。
response_limits:
max_generated_chars: 1048576
max_stream_chunks: 100000
# JWT 有效期和签名密钥；生产环境必须设置随机密钥。
jwt:
expire: 604800
secret: ''
# 业务数据库配置；可选 sqlite 或 postgresql。
database:
use: sqlite
sqlite:
path: 'data/langbot.db'
# PostgreSQL 连接池及超时设置。
postgresql:
# 非空时优先于拆分字段，并保留 TLS 与查询参数。
url: ''
host: '127.0.0.1'
port: 5432
user: 'postgres'
password: 'postgres'
database: 'postgres'
pool_size: 10
max_overflow: 10
pool_timeout_seconds: 30
pool_recycle_seconds: 1800
statement_timeout_ms: 60000
lock_timeout_ms: 5000
idle_in_transaction_session_timeout_ms: 60000
# Cloud 发布迁移的运维级连接配置。
cloud_migration:
# 仅填写环境变量名；运维角色必须与运行时角色分离。
operator_dsn_env: 'LANGBOT_CLOUD_MIGRATION_DSN'
# 向量数据库配置；只需配置 use 选中的后端。
vdb:
use: chroma
# 限制进程内集合或索引句柄数量。
runtime_cache_limit: 1024
# Qdrant 连接参数。
qdrant:
url: ''
host: localhost
port: 6333
api_key: ''
# SeekDB 是可选功能；源码/包管理器部署需安装 langbot[seekdb] extra。
# 官方 Docker/Kubernetes 镜像已包含该依赖。
# 嵌入式模式的平台支持取决于 pylibseekdb wheel。
seekdb:
mode: embedded
path: './data/seekdb'
database: 'langbot'
host: 'localhost'
port: 2881
user: 'root'
password: ''
tenant: ''
# Milvus 连接参数。
milvus:
uri: 'http://127.0.0.1:19530'
token: ''
db_name: ''
# pgvector 可复用业务 PostgreSQL，也可连接独立数据库。
pgvector:
use_business_database: false
# 发布迁移只为这些向量维度创建 ANN 索引。
allowed_dimensions: [384, 512, 768, 1024, 1536]
host: '127.0.0.1'
port: 5433
database: 'langbot'
user: 'postgres'
password: 'postgres'
# 需要启用 Search 模块的 Valkey 服务。
valkey_search:
host: 'localhost'
port: 6379
db: 0
password: ''
username: ''
tls: false
index_algorithm: 'HNSW'
distance_metric: 'COSINE'
request_timeout: 5000
# 对象存储、读取上限与定期清理策略。
storage:
use: local
# 单次读入 Core 内存的对象大小上限；内置实现硬上限为 64 MiB。
max_object_read_bytes: 10485760
# 本地或 S3 上传文件及旧日志的周期清理。
cleanup:
enabled: true
check_interval_hours: 1
uploaded_file_retention_days: 7
log_retention_days: 3
max_files_per_run: 1000
# S3 连接与同步操作并发限制。
s3:
endpoint_url: ''
access_key_id: ''
secret_access_key: ''
region: 'us-east-1'
bucket: 'langbot-storage'
max_concurrency: 16
# 插件 Worker 的实例级硬资源上限与准入预算。
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'
# 插件清单不能提高或覆盖这些限制。
worker:
max_cpus: 1.0
max_memory_mb: 512
max_pids: 128
max_open_files: 256
max_file_size_mb: 512
max_workers: 16
max_total_cpus: 8.0
max_total_memory_mb: 8192
max_installations: 10000
max_concurrent_restarts: 1
restart_failure_threshold: 8
restart_failure_window_seconds: 30.0
restart_circuit_open_seconds: 60.0
require_hard_limits: false
# 插件二进制存储单值大小限制。
binary_storage:
max_value_bytes: 10485760
# MCP 生命周期并发和本地 stdio 传输开关。
mcp:
# 实例级 MCP 启停并发，硬上限为 128。
lifecycle_concurrency: 16
# 关闭后仅禁用本地 stdio MCP，不影响 HTTP/SSE MCP。
stdio:
enabled: true
# 监控查询工作量与历史数据清理策略。
monitoring:
# 限制分页、导出、详情、时序桶和高 offset 查询。
query_limits:
page_rows: 1000
export_rows: 10000
detail_rows: 2000
timeseries_buckets: 1000
max_offset: 1000000
# 过期监控记录的分批自动清理。
auto_cleanup:
enabled: true
retention_days: 30
check_interval_hours: 1
delete_batch_size: 1000
max_batches_per_table_per_run: 4
# Box 沙箱 Runtime 总配置。
box:
# 关闭后不连接或启动 Box，并禁用依赖沙箱的工具和 stdio MCP。
enabled: true
# 可选 local、docker、nsjail 或 e2b。
backend: 'local'
# 外部 WebSocket Runtime 地址；留空时自动管理本地 Runtime。
runtime:
endpoint: ''
# 会话、进程、Workspace 扫描、准入记录和 RPC 文件上限。
limits:
max_sessions: 64
max_managed_processes: 64
max_completed_processes: 256
max_workspace_entries: 100000
max_admission_records: 100000
max_rpc_file_bytes: 20971520
# Cloud v2 强制准入与硬配额；普通 OSS 默认关闭。
admission:
required: false
logical_session_id: 'global'
required_backend: 'nsjail'
max_sessions: 1
max_managed_processes: 0
max_grant_ttl_sec: 300
max_timeout_sec: 120
cpus: 1.0
memory_mb: 512
pids_limit: 128
read_only_rootfs: true
workspace_quota_mb: 0
readiness_cache_sec: 15
# 本地工作目录、Skill 目录、挂载根目录与可选磁盘配额。
local:
profile: 'default'
image: ''
# Docker 部署应改为容器可挂载的绝对宿主机路径。
host_root: './data/box'
default_workspace: ''
skills_root: 'skills'
allowed_mount_roots:
- './data/box'
- '/tmp'
workspace_quota_mb: null
# 每个 MCP stdio 进程的默认 nsjail cgroup 内存上限（MiB）。
default_memory_mb: 1536
# Docker 沙箱额外设置。
docker:
cpu_limit_enabled: true
# E2B 或自托管兼容服务设置。
e2b:
api_key: ''
api_url: ''
template: ''
# LangBot Space OAuth、模型网关和遥测设置。
space:
url: 'https://space.langbot.app'
models_gateway_api_url: 'https://api.langbot.cloud/v1'
oauth_authorize_url: 'https://space.langbot.app/auth/authorize'
disable_models_service: false
disable_telemetry: false
```
## 配置分组说明
### API、WebUI 与成员邀请
- `api.port`：LangBot HTTP API 与 WebUI 的监听端口，默认 `5300`。
- `api.webhook_prefix`：对外可访问的服务地址，用于生成机器人平台的 Webhook 回调地址；生产环境通常应设置为反向代理后的 HTTPS 域名。
- `api.extra_webhook_prefix`：需要同时展示第二个回调入口时使用，留空即不启用。
- `api.webui_url`：WebUI 与 API 跨域部署时的浏览器端规范来源，例如开发环境的 `http://localhost:3000`。OAuth 回调只信任该配置与 `webhook_prefix`，不会信任请求中的 `Host` 或 `Origin` 请求头。
- `api.global_api_key`：供自动化程序、HTTP Service API 和内置 MCP 服务使用的全局密钥。设置后可通过 `X-API-Key` 或 `Authorization: Bearer` 鉴权，无需登录会话或数据库中的 `lbk_` 密钥；留空表示关闭。
- `workspace.invitations.public_web_url`：邀请链接使用的 WebUI 公网地址；留空时依次回退到 `api.webui_url`、`api.webhook_prefix`。
- `workspace.invitations.email`：可选的邀请邮件发送配置。`provider` 支持 `resend`、`smtp`，留空时只生成邀请链接、不发送邮件。
<Warning>
`global_api_key`、JWT 密钥、数据库密码、S3 密钥、Resend/SMTP 密钥和 E2B API Key 都属于敏感信息。生产环境优先使用环境变量注入，不要提交到 Git，也不要通过明文 HTTP 暴露服务。
</Warning>
### 命令、并发与 Webhook 限制
- `command`：控制命令系统是否启用、命令前缀以及权限映射。
- `concurrency.pipeline`：实例同时处理的流水线请求数量；`concurrency.session`：同一会话允许的并发数量。
- `concurrency.pending_queries` 与 `pending_queries_per_workspace`：限制“排队中 + 执行中”的请求总量，防止突发流量形成无限队列。
- `webhooks.max_per_workspace`：每个 Workspace 最多调度的启用 Webhook 数量，硬上限为 `64`。
- `webhooks.max_inflight_requests`：全实例同时发送的 Webhook 请求数，硬上限为 `128`；槽位占满时会快速失败，不会无限积压任务。
### Cloud 目录安全上限
`cloud.directory` 是单个 LangBot Cloud 逻辑实例的**运行安全上限**，不是套餐权益：
- `max_active_workspaces`：允许加载的活跃 Workspace 数量，Core 绝对上限为 `5000`。
- `max_snapshot_workspaces` / `max_snapshot_memberships`：一次签名目录快照允许携带的 Workspace 与成员关系数量。
- `max_response_bytes`：签名控制面响应在验证前允许缓冲的最大字节数，默认 `32 MiB`、绝对上限 `64 MiB`。
超过这些上限的权威目录更新会被整体拒绝，而不是静默截断。普通自部署用户通常不需要修改这一组。
### 系统限制与内存保留
- `system.instance_id`、`edition`、`recovery_key`：实例身份、发行版与恢复信息；除非部署流程明确要求，否则保持默认。
- `system.disabled_adapters`：禁用的消息平台适配器列表。
- `system.blocking_executor`：限制所有 `asyncio.to_thread` 工作共享的线程池、排队任务和单 Workspace 占用，防止阻塞调用拖垮进程。
- `system.limitation`：实例级机器人、流水线、扩展、知识库数量限制；`-1` 表示不限制。`force_box_session_id_template` 用于 SaaS 强制统一沙箱作用域，普通自部署应保持空字符串。
- `task_retention`：异步任务记录、日志字符数和用户主动任务并发上限。
- `session_retention`：进程内会话缓存上限与空闲 TTL；它不是持久聊天记录。
- `websocket_retention`：浏览器连接数、Workspace 代理缓存、对话缓存与发送队列上限。
- `response_limits`：限制单次上游模型响应的字符数和流式分块数。
- `system.jwt.expire` 以秒为单位；生产环境应显式设置不可预测的 `system.jwt.secret`。
### 数据库与向量数据库
- `database.use` 支持 `sqlite` 与 `postgresql`。SQLite 适合单机轻量部署；多实例或较高并发建议使用 PostgreSQL。
- `database.postgresql.url` 非空时优先于拆分的 `host`、`port`、`user`、`password`、`database` 字段，并可保留 TLS 与查询参数。
- PostgreSQL 的 `pool_size`、`max_overflow`、连接池超时与回收参数共同限制连接资源；三个数据库超时字段只应用于 Cloud 运行时连接。
- `database.cloud_migration.operator_dsn_env` 指定 Cloud 发布迁移读取的运维级 DSN 环境变量。运维角色必须与运行时角色分离，密码不要写入配置文件或命令行参数。
- `vdb.use` 选择向量后端。页面列出了 Qdrant、SeekDB、Milvus、pgvector 与 Valkey Search 的连接参数；只需要配置实际选中的后端。
- `vdb.use: seekdb` 在源码部署中要求执行 `uv sync --extra seekdb`，包管理器部署使用 `uvx --from 'langbot[seekdb]@latest' langbot`。官方 Docker/Kubernetes 镜像已包含该依赖，无需额外构建参数。
- `vdb.runtime_cache_limit` 限制进程内集合/索引句柄数量。
- `vdb.pgvector.use_business_database: true` 表示复用 `database.postgresql`；`allowed_dimensions` 限定发布迁移创建 ANN 索引的向量维度。
- `vdb.valkey_search` 需要带 Search 模块的 Valkey 服务，例如 `valkey/valkey-bundle:9.1.0`。连接按需建立，支持 HNSW/FLAT 与 COSINE/L2/IP。
### 存储、插件、MCP 与监控
- `storage.use` 选择本地或 S3 存储；`max_object_read_bytes` 限制一次读入 Core 内存的对象大小，内置 Local/S3 实现的硬上限为 `64 MiB`。
- `storage.cleanup` 控制上传文件与日志的周期清理。`max_files_per_run` 限制一次扫描的文件数，硬上限 `10000`。
- `storage.s3.max_concurrency` 限制委托给工作线程的同步 boto3 操作数量。
- `plugin.worker` 定义所有插件安装都不能突破的 CPU、内存、PID、打开文件、文件大小与全局 Worker 预算；插件清单不能抬高这些上限。重启参数用于抑制 Runtime 重启风暴。
- `plugin.binary_storage.max_value_bytes` 限制单个插件二进制存储值，默认 `10 MiB`。
- `mcp.lifecycle_concurrency` 限制 MCP 启停并发，硬上限 `128`；`mcp.stdio.enabled` 可独立禁用本地 stdio MCP，而不影响 HTTP/SSE MCP。
- `monitoring.query_limits` 限制分页、CSV 导出、详情、时序桶和高 offset 查询在内存/数据库中的工作量。
- `monitoring.auto_cleanup` 控制监控数据保留与分批删除；`max_batches_per_table_per_run` 防止单个 Workspace 的积压长期占用 PostgreSQL。
### Box 沙箱
- `box.enabled` 是总开关。关闭后不会连接或启动 Box Runtime，并禁用原生沙箱工具、Skill 添加/编辑和 stdio MCP；只读 Skill 列表以及 HTTP/SSE MCP 仍可使用。
- `box.backend` 可选 `local`、`docker`、`nsjail`、`e2b`；`box.runtime.endpoint` 用于连接外部 WebSocket Runtime，留空时使用本地自动管理 Runtime。
- `box.limits` 限制会话、托管进程、已完成进程、Workspace 扫描条目、准入记录和 RPC 文件大小。
- `box.admission` 是 Cloud v2 的强制准入与硬资源配额。普通 OSS 默认 `required: false`；流水线、Workspace 权益或工具调用都不能放宽 Runtime 拥有的限制。
- `box.local` 配置本地工作目录、Skill 根目录、允许挂载根目录和可选磁盘配额。Docker 部署时，`host_root` 应使用 Box 容器可挂载的绝对宿主机路径。
- `box.default_memory_mb` 是每个 MCP stdio 进程的默认 nsjail cgroup 内存上限。Node.js MCP 通常比 Python MCP 占用更多内存；过低时常见 `return_code=137`。
- `box.docker.cpu_limit_enabled: false` 只取消 Docker 的 CPU 参数，内存与 PID 限制仍然生效。
- `box.e2b` 用于 E2B 或自托管兼容服务。
### LangBot Space
- `space.url`：Space OAuth 与 API 服务地址。
- `space.models_gateway_api_url`：LangBot MaaS 的 OpenAI 兼容模型网关地址。
- `space.oauth_authorize_url`：OAuth 授权页地址。
- `space.disable_models_service` / `disable_telemetry`：分别关闭 Space 模型服务与遥测上报。
## 通过环境变量设置
任何嵌套配置都可以转换为“大写 + 双下划线”环境变量：
- `API__PORT` → `api.port`
- `WORKSPACE__INVITATIONS__PUBLIC_WEB_URL` → `workspace.invitations.public_web_url`
- `CONCURRENCY__PENDING_QUERIES_PER_WORKSPACE` → `concurrency.pending_queries_per_workspace`
- `DATABASE__POSTGRESQL__POOL_SIZE` → `database.postgresql.pool_size`
- `STORAGE__CLEANUP__MAX_FILES_PER_RUN` → `storage.cleanup.max_files_per_run`
- `PLUGIN__WORKER__MAX_TOTAL_MEMORY_MB` → `plugin.worker.max_total_memory_mb`
- `MCP__STDIO__ENABLED` → `mcp.stdio.enabled`
- `BOX__DEFAULT_MEMORY_MB` → `box.default_memory_mb`
启动时，LangBot 会读取环境变量、应用对应配置，并写入 `data/config.yaml`。
<Note>
Docker 部署中，统一把 `BOX__*` 环境变量设置在 `langbot` 服务上。LangBot 会通过 INIT RPC 将 Box 配置传给 `langbot_box`；直接在 `langbot_box` 服务上设置 `LANGBOT_BOX_*` 或 `BOX__*` 不会被读取。
</Note>
Reference in New Issue View Git Blame Copy Permalink