• 人工智能
• AI Agent
• Agent 编排
• 低代码
• AI 技能
• RAG

在 Nexent 中，后端与 SDK 的配置遵循一条清晰的分层规则：环境变量只在 backend/consts/const.py 中读取一次，应用层与服务层从常量模块导入或显式传参，SDK 侧仅通过构造函数/函数参数接收配置值。本文以 configuration.md 这份配置规则文档为核心，结合仓库源码逐条展开每条规则的实现方式、代码边界与验证手段，读完后可掌握在 Nexent 中新增、修改配置项的完整流程与自检清单。

配置规则的完整清单

.agents/skills/nexent-backend/references/configuration.md 是 Nexent 后端变更技能（SKILL.md 中“Environment configuration and SDK configuration parameters”对应条目）的参考文档，适用于所有 backend/SDK Python 配置变更。其规则共六条：

下面结合仓库实际代码，逐条说明这些规则是如何落地和被验证的。

规则一：环境变量读取的单一入口backend/consts/const.py

Nexent 后端有数十个环境相关配置项（Elasticsearch、MinIO、Redis、Ray、Celery、OAuth/CAS、沙箱、监控等），它们全部集中在 backend/consts/const.py 中定义，该文件是当前仓库中os.getenv调用的最主要位置。

dotenv 加载优先级

文件开头显式加载本地开发用.env，且不覆盖已存在的环境变量：

# Load environment variables # Explicitly sourced deployment variables take precedence over a nearby # developer .env file. This is required for tmux/K8s-local verification and # avoids silently replacing operator-provided service addresses. load_dotenv(override=False)

见 const.py。override=False的含义是：容器/K8s 等部署环境显式注入的变量（如运维提供的服务地址）永远优先于开发机附近的.env文件，避免本地文件“静默替换”部署配置。

默认值与类型解析的集中化

配置项普遍采用“环境变量 + 默认值 + 类型转换”的形式，例如：

RUNTIME_SERVICE_URL = os.getenv("RUNTIME_SERVICE_URL", "http://localhost:5014").rstrip("/") MAX_KNOWLEDGE_FILE_SIZE_MB = parse_positive_int( os.getenv("MAX_KNOWLEDGE_FILE_SIZE_MB"), "MAX_KNOWLEDGE_FILE_SIZE_MB", 100 )

对资源上限类配置，仓库提供了统一的校验工具 backend/utils/config_validation.py：parse_positive_int/parse_positive_float在未设置时回退默认值，在设置但非法（非数字、非正数）时抛出ValueError。注意const.py顶部的双导入逻辑：

try: from backend.utils.config_validation import parse_positive_float, parse_positive_int except ModuleNotFoundError: # The production service runs with ``backend`` as the working directory, # where backend-local modules are imported from the top-level package. from utils.config_validation import parse_positive_float, parse_positive_int

见 const.py。这说明生产服务以backend作为工作目录运行，本地模块按顶层包导入，而仓库根目录运行时则按backend.前缀导入——两种入口都能解析到同一份常量定义。

启动期配置校验：非法值直接拒绝启动

const.py中部分关键配置在模块加载时做硬校验，非法值会立即raise ValueError，把“配置错误”暴露在进程启动阶段而非运行期。例如运行时时线程容量配置（const.py）：

RUNTIME_AGENT_ID_MAX_CONCURRENT_RUNS = int( os.getenv("RUNTIME_AGENT_ID_MAX_CONCURRENT_RUNS", "50") ) RUNTIME_AGENT_THREAD_MAX_WORKERS = int(os.getenv("RUNTIME_AGENT_THREAD_MAX_WORKERS", "200")) ... if RUNTIME_AGENT_ID_MAX_CONCURRENT_RUNS <= 0: raise ValueError("RUNTIME_AGENT_ID_MAX_CONCURRENT_RUNS must be greater than zero") if RUNTIME_AGENT_THREAD_MAX_WORKERS <= 0: raise ValueError("RUNTIME_AGENT_THREAD_MAX_WORKERS must be greater than zero")

同类校验还出现在RUNTIME_AGENT_THREAD_QUEUE_TIMEOUT_SECONDS、RUNTIME_PARALLEL_EXECUTOR_TIMEOUT_SECONDS、RUNTIME_MCP_TOOL_TIMEOUT_SECONDS（const.py）以及 JWT 有效期JWT_EXPIRY（const.py）等处。对布尔类配置，文件里统一的解析风格是os.getenv("X", "false").lower() in ("true", "1", "yes", "on")，如AGENT_AUTOMATION_ENABLED、CAS_ENABLED（const.py）。

典型配置项与默认值速览

从const.py的结构看，配置按功能域分组注释，便于按域定位。以下摘录几组有代表性的配置（默认值以当前仓库为准）：

完整的配置分组可在 backend/consts/const.py 中按注释小节查阅：向量库、上传、Supabase、OAuth/CAS、租户资源上限、MinIO、Postgres、Redis/Ray/Celery、记忆系统（MMR、Dreaming）、监控/OTEL、Agent 沙箱等。

规则二：Apps 与 Services 从consts.const导入，不直接读环境

按分层约定，backend/apps/**处理 HTTP 边界，backend/services/**编排业务逻辑，两层获取配置的方式只有两种：从consts.const导入常量，或接受调用方显式传入的参数。

从源码结构看，service 层的导入方式是直接按顶层包导入（生产工作目录为backend）：

# backend/services/a2a_server_service.py from consts.const import NORTHBOUND_EXTERNAL_URL

# backend/services/agent_automation/facade.py from consts.const import ( AGENT_AUTOMATION_DEFAULT_TIMEOUT_SECONDS, AGENT_AUTOMATION_MIN_INTERVAL_SECONDS, )

backend/apps/**中同样大量以from consts.const import ...的形式引用（如 agent_app.py、config_app.py），app 层在调用 service 时把需要的配置值作为参数透传下去，而不是让 service 各自再读一次环境变量。services.md 中也有对应约束：“Import configuration fromconsts.constor accept parameters, then pass configuration into SDK calls. Do not read environment variables here.”

这样做的直接收益是：

• 配置解析（含默认值、类型转换、合法性校验）只发生在进程启动导入const.py时一处完成；
• 运行时业务代码不再依赖os.environ快照，测试时只需替换导入的常量值，无需污染全局环境（仓库测试正是这样做的，见下文“验证”一节）。

规则三与规则五：SDK 参数化，配置由调用方注入

SDK（sdk/nexent/）作为可独立分发的 Python 包，其配置约定与后端相反：不读环境变量，只通过构造函数/函数参数接收。规则明确要求 SDK 代码不新增环境变量读取，也不新增from_env()类方法。

仓库中的沙箱模块是对这条规则最直接的印证。sdk/nexent/core/agents/sandbox.py 的模块 docstring 写明：

""" Sandbox executor factory and lifecycle management. ... All environment variables are read by the backend service layer and passed in via ``SandboxConfig`` — this module never calls ``os.getenv()`` directly. """

即NEXENT_SANDBOX_DEFAULT_LEVEL、NEXENT_SANDBOX_MEMORY_LIMIT_MB、NEXENT_SANDBOX_SHELL_POLICY等环境项由后端在const.py中读取，再通过SandboxConfigdataclass 的字段传入 SDK 的沙箱工厂；SDK 内部对隔离级别（local/docker/wasm）、生命周期范围（session/system）、资源限额的判断全部基于传入的参数。

与之对应，配置值的“源头”在const.py的沙箱小节（const.py）：

NEXENT_SANDBOX_DEFAULT_LEVEL = os.getenv("NEXENT_SANDBOX_DEFAULT_LEVEL", "local").lower() """Default sandbox isolation level: local / docker / wasm. Default 'local' preserves backward-compatibility for existing deployments.""" ... NEXENT_SANDBOX_MEMORY_LIMIT_MB = int(os.getenv("NEXENT_SANDBOX_MEMORY_LIMIT_MB", "2048"))

需要说明的是，从源码结构看 SDK 中仍残留少量历史性的直接环境读取（例如sdk/nexent/core/tools/exa_search_tool.py、tavily_search_tool.py等读取DATA_PROCESS_SERVICE，monitoring.py 读取MODEL_MONITORING_*变量）。规则六的表述是“Remove superseded direct readswithin the changed path”——即每次配置变更应清理自己改动路径上被取代的直接读取，而不是要求一次性重构全库，这与 SKILL.md 中“Apply conventions to the changed scope; do not refactor unrelated legacy behavior”的原则一致。

规则四：与deploy/env/.env.example保持同步

deploy/env/.env.example是部署级配置的可提交示例文件。当前仓库中的 deploy/env/.env.example 已按功能分区组织，覆盖了：

• 必需/可选的语音服务配置（APPID、TOKEN、CLUSTER、VOICE_TYPE、SPEED_RATIO）；
• 各微服务地址（CONFIG_SERVICE_URL、RUNTIME_SERVICE_URL、NEXENT_MCP_SERVER、DATA_PROCESS_SERVICE、NORTHBOUND_API_SERVER等）；
• Postgres / MinIO / Redis / Supabase 连接配置；
• 租户与资源上限（MAX_TENANT_COUNT、MAX_KNOWLEDGE_BASES_PER_TENANT、MAX_MCP_SERVICES_PER_TENANT、MCP_REQUEST_TIMEOUT_SECONDS等）；
• 运行时时线程容量（RUNTIME_AGENT_ID_MAX_CONCURRENT_RUNS=50、RUNTIME_AGENT_THREAD_MAX_WORKERS=200等，见 .env.example）；
• Ray / Celery / 日志（LOG_LEVEL、LOG_ROTATION_INTERVAL、LOG_MAX_BYTES等）；
• OAuth 与 CAS SSO（OAUTH_LOGIN_MODE、CAS_ENABLED、CAS_HEARTBEAT_*等，见 .env.example）；
• AIDP 知识库、Agent 沙箱、官方 Agent、技能上限（SKILLS_PATH、MAX_SKILLS_PER_TENANT）等。

规则对同步的要求有两点：

1. 新增/变更变量时必须更新示例文件：这样部署者能从一个受跟踪的文件了解全部可配置项及推荐值。示例文件中的值与const.py默认值对齐，例如MAX_KNOWLEDGE_BASES_PER_TENANT=10000（.env.example）对应const.py中的默认10_000。
2. 不覆盖本地.env：.env属于本地/单机部署产物（可能含密钥），只维护示例文件。这与load_dotenv(override=False)的优先级设计配合，保证部署变量始终压过本地文件。

一致性有测试兜底

仓库用测试保证“const.py默认值 ↔.env.example示例值”不发生漂移。test/backend/consts/test_runtime_thread_config.py 中：

def test_knowledge_resource_defaults_match_deployment_example(): """Knowledge resource limits expose the documented production defaults.""" assert MAX_KNOWLEDGE_BASES_PER_TENANT == 10_000 ... example_path = Path(__file__).resolve().parents[3] / "deploy" / "env" / ".env.example" example = example_path.read_text(encoding="utf-8") for assignment in ( "MAX_KNOWLEDGE_BASES_PER_TENANT=10000", ... ): assert assignment in example

同文件还通过子进程注入环境变量、重新导入backend.consts.const来验证“显式环境变量覆盖默认值”的完整链路（test_runtime_thread_config.py）。这正对应规则六“Verify defaults and explicit configuration”的要求：默认路径与显式配置路径都要被验证到。

规则六：变更后的自检清单

完成一次配置变更后，按文档要求的检查项逐项过一遍：

1. 默认值路径：不设置任何环境变量，确认常量取到const.py中的默认值（或parse_positive_int/float的回退值）；

2. 显式配置路径：设置环境变量后重启/重新导入，确认值被正确覆盖（类型转换、.rstrip("/")、大小写归一化等行为符合预期）；

3. 游离读取扫描：在受影响的 backend/SDK 代码中检索os.getenv()/os.environ.get()，确认没有落在const.py之外。可以用 ripgrep 快速定位：

   rg -n 'os\.getenv|os\.environ\.get' backend sdk --glob '!backend/consts/const.py'

   对扫描出的命中项，区分“本次变更路径内被取代的直接读取”（应移除，改为参数传递）与“改动范围外的历史残留”（不强行重构）；

4. 示例文件同步：确认deploy/env/.env.example（或对应组件的受跟踪示例，如 sdk/benchmark/infra/langfuse/.env.example）已包含新增变量及其推荐值；

5. 调用方更新：确认所有需要该配置的 SDK 构造函数/调用点已收到显式传参，SDK 侧未新增from_env()一类的静态读取入口。

实操流程：在 Nexent 中新增一个配置项

综合以上规则，一次典型的配置变更应遵循如下步骤（以“为某功能新增开关 + 超时参数”为例）：

1. 定义在const.py：在 backend/consts/const.py 相应功能分组的注释小节内添加读取语句，遵循现有命名与解析风格；
   • 资源上限类用parse_positive_int(os.getenv("MAX_X"), "MAX_X", default)，在非法值时以ValueError快速失败；
   • 布尔类用.lower() in ("true", "1", "yes", "on")风格；
   • 必须为正数的运行参数，参照RUNTIME_*系列在模块级追加<= 0校验。
2. 传递到业务层：在相关backend/apps/*.py路由或backend/services/*.py编排函数中from consts.const import NEW_SETTING后作为行为开关/参数使用；service 需要把它继续传给 SDK 时，以参数形式向下传，不在 service 内读环境。
3. 注入 SDK：在 SDK 侧把值加入对应 dataclass/构造函数参数（参照SandboxConfig的做法），SDK 内部只消费参数；若改动路径上存在旧的直接环境读取，一并删除。
4. 更新示例：把新变量写入 deploy/env/.env.example 的对应分区，附注释说明取值范围与默认值；不要触碰任何本地.env。
5. 验证：运行/补充类似 test/backend/consts/test_runtime_thread_config.py 的测试，分别断言“默认值与示例文件一致”“环境变量可覆盖默认值”，并对启动期校验分支补一个非法值场景。

小结

Nexent 的配置管理用一条“读取点唯一、传递靠参数”的链路把后端、SDK 与部署配置解耦：const.py负责环境读取、默认值与启动期校验，Apps/Services 只做导入与透传，SDK 只接收显式参数，deploy/env/.env.example作为部署者的唯一配置清单并受测试一致性约束。对维护者而言，这套规则的价值在于配置行为在进程启动时即被完全确定和验证，运行时不存在隐式的环境依赖；对读者而言，只要抓住 configuration.md 的六条规则与本文给出的验证手段，即可在仓库中安全地完成任何后端/SDK 配置变更。

• 人工智能
• AI Agent
• Agent 编排
• 低代码
• AI 技能
• RAG