环境变量清单
ai-lubricant 启动依赖配置项的唯一总表。数据服务（python main.py）读取 bootstrap_config.py，节点控制服务（python -m node_server）独立解析 node_server/config.py，不 import bootstrap_config。本页把散落在 部署文档各小节的字段集中成一份，便于一次性核对。
1. 解析优先级与约定
启动依赖统一按“环境变量优先 → .env → 内置默认值”解析。渠道、模型、API Key、重试和治理策略等业务配置存放在 PostgreSQL/Redis，不属于 .env。本地启动 python main.py / python -m node_server 会自动加载项目根 .env；外部环境变量优先于 .env。
不要提交 .env其中包含数据库密码、内部 token、引导管理员密码和节点凭据加密密钥。
.env 已被 .gitignore 排除；从 .env.example 复制模板后填入真实值。生产环境应通过 Secret 管理系统或环境变量注入敏感值。- 布尔值在
.env中使用true/false；环境变量还接受1/0、yes/no、on/off。 - 「进程」列：数据 = 数据服务（main.py）读取，控制 = 节点控制服务（node_server）读取，两 = 两者都读。
- 「必需」列指：当无环境变量、无 ini 值、无默认值时启动是否报
ConfigurationError。 - 所有配置均以
.env变量为准，表中不再存在仅 INI 的字段。
2. [server] 数据服务监听
| ini 字段 | 环境变量 | 进程 | 必需/默认 | 说明 |
|---|---|---|---|---|
host | 无 | 数据 | 固定 0.0.0.0 | main.py 末尾硬编码 uvicorn.run(app, host="0.0.0.0", port=8001)，ini 段实际未被 bootstrap_config 读取。 |
port | 无 | 数据 | 固定 8001 | 同上；需要其他地址或端口时用 uvicorn main:app --host ... --port ... 启动，不要只改 ini。 |
3. [postgres] 业务数据库（两进程共享）
| ini 字段 | 环境变量 | 进程 | 必需/默认 | 说明 |
|---|---|---|---|---|
host | POSTGRES_HOST | 两 | 必需 | PostgreSQL 主机。 |
port | POSTGRES_PORT | 两 | 必需，1–65535 | PostgreSQL 端口。 |
user | POSTGRES_USER | 两 | 必需 | 数据库用户。 |
password | POSTGRES_PASSWORD | 两 | 必需 | 数据库密码。 |
database | POSTGRES_DATABASE，兼容 POSTGRES_DB | 两 | 必需 | 主数据库名。 |
pool_min_size | POSTGRES_POOL_MIN_SIZE | 数据 | 默认 1 | 单进程连接池最小连接数，至少为 1。 |
pool_max_size | POSTGRES_POOL_MAX_SIZE | 数据 | 默认 10 | 单进程连接池上限，不能小于 pool_min_size。 |
4. [redis] 运行态真相源（两进程共享）
| ini 字段 | 环境变量 | 进程 | 必需/默认 | 说明 |
|---|---|---|---|---|
host | REDIS_HOST | 两 | 必需 | Redis 主机。 |
port | REDIS_PORT | 两 | 必需，1–65535 | Redis 端口。 |
db | REDIS_DB | 两 | 必需，≥0 | Redis 逻辑库。 |
prefix_key | 无 | 两 | 必需 | Redis key 命名空间；多套环境共用 Redis 时必须互不相同。 |
decode_responses | 无 | 两 | 必需 | 必须是布尔值；示例配置为 true。 |
max_connections | REDIS_MAX_CONNECTIONS | 两 | 必需，示例 500 | 单进程连接池上限；按进程数、Redis maxclients 和文件描述符容量规划。 |
stream_timeout | REDIS_STREAM_TIMEOUT | 数据 | 默认 10 秒 | 已取得连接后等待单条命令回包的最长时间；超时自愈重连，不影响 pubsub。 |
pool_timeout | REDIS_POOL_TIMEOUT | 数据 | 默认 10 秒 | 从连接池等待可用连接的最长时间。 |
5. [outbound] 出站上游连接池
数据服务转发到上游 LLM 的 aiohttp 连接池参数。每个出站模式实例（direct / url_prefix / network / node）独立持有连接池，环境变量对每个实例独立生效。无 ini 对应字段。
OUTBOUND_CONNECTOR_LIMIT_PER_HOST 是更细的脖子。到同一上游域名（如 api.openai.com）的连接再多账号也共用此额度；高并发打到单一上游时必须同时调大，只调 OUTBOUND_CONNECTOR_LIMIT 无效。| ini 字段 | 环境变量 | 进程 | 必需/默认 | 说明 |
|---|---|---|---|---|
| 无 | OUTBOUND_CONNECTOR_LIMIT | 数据 | 默认 100 | 单出站模式实例的并发连接总数上限。1000 并发起步建议 ≥ 2000。 |
| 无 | OUTBOUND_CONNECTOR_LIMIT_PER_HOST | 数据 | 默认 32 | 到同一上游域名的并发连接上限。集中打单一上游时按目标并发设；分散多上游可较小。 |
两值非正整数时回退默认。未设置时行为与历史版本一致（100 / 32），不影响现有部署。连接池上限还需与 POSTGRES_POOL_MAX_SIZE、REDIS_MAX_CONNECTIONS、账号 concurrent_limit 之和、文件描述符上限一起规划，任一短板都成瓶颈。
6. [monkeycode] 兼容层与节点控制面
| ini 字段 | 环境变量 | 进程 | 必需/默认 | 说明 |
|---|---|---|---|---|
compat_enabled | MONKEYCODE_COMPAT_ENABLED | 数据 | false | 启用用户门户、多用户、项目、编辑器与节点适配 API；完整 Web 平台必须开启。 |
database_url | MONKEYCODE_DATABASE_URL | 控制 | 复用主 PostgreSQL | 可选独立 asyncpg DSN；留空时 mc_* 表写入主库。 |
user_adapter_enabled | MONKEYCODE_USER_ADAPTER_ENABLED | 数据 | false | 启用系统用户适配；开启时使用下面三个 system_user_* 字段。 |
system_user_id | MONKEYCODE_SYSTEM_USER_ID | 数据 | 见 .env.example | 系统用户身份；不要随意更换已经投入使用的 ID。 |
system_user_name | MONKEYCODE_SYSTEM_USER_NAME | 数据 | 见 .env.example | 系统用户名。 |
system_user_email | MONKEYCODE_SYSTEM_USER_EMAIL | 数据 | 见 .env.example | 系统用户邮箱。 |
bootstrap_admin_email | MONKEYCODE_BOOTSTRAP_ADMIN_EMAIL | 数据 | 空 | 首次启动幂等创建平台管理员；email 为空时不创建。创建后应从 Secret 注入中移除明文密码。 |
bootstrap_admin_password | MONKEYCODE_BOOTSTRAP_ADMIN_PASSWORD | 数据 | 空 | 同上管理员密码。 |
bootstrap_admin_name | MONKEYCODE_BOOTSTRAP_ADMIN_NAME | 数据 | admin | 管理员显示名。 |
captcha_required | MONKEYCODE_CAPTCHA_REQUIRED | 数据 | true | 登录/注册是否强制 cap.js 验证；关闭仅作为 CAPTCHA/Redis 故障逃生开关。 |
session_cookie_samesite | MONKEYCODE_SESSION_SAMESITE | 数据 | lax | 同源部署保持 lax；跨站浏览器前端需设 none。 |
session_cookie_secure | MONKEYCODE_SESSION_SECURE | 数据 | false | HTTPS 生产环境建议 true；SameSite=None 时必须 true。 |
agent_compose_base_url | AGENT_COMPOSE_BASE_URL | 数据 | 空 | 数据服务访问独立节点控制服务的内部地址，例如 http://127.0.0.1:8003。 |
agent_compose_timeout | AGENT_COMPOSE_TIMEOUT | 数据 | 30 秒 | 数据服务调用节点控制服务的超时。 |
review_project_max_concurrency | 无 | 数据 | 2 | 每项目 review 任务池最大并发；全局默认，整主机统一调。 |
node_control_token | NODE_CONTROL_TOKEN（兼容 AGENT_COMPOSE_NODE_API_TOKEN） | 两 | 缺失时控制服务生成 | 数据服务→控制服务内部 Bearer token；两个进程必须完全一致。旧名仅兼容读取，新部署使用此名称。 |
node_credential_encryption_key | NODE_CREDENTIAL_ENCRYPTION_KEY（兼容 AGENT_COMPOSE_NODE_MASTER_KEY） | 控制 | 缺失时控制服务生成 | AES-256 凭据加密密钥，接受 64 位 hex 或解码后 32 字节的 Base64；生成后不可轮换，否则已加密节点凭据全部失效。 |
node_server_public_url | AGENT_COMPOSE_NODE_SERVER_PUBLIC_URL | 控制 | 空 | Go 节点实际拨号地址；留空时部分引导链接会从当前请求 origin 推导。 |
node_server_enabled | AGENT_COMPOSE_NODE_SERVER_ENABLED | 控制 | true | 节点功能紧急停用开关；不等于进程角色选择。 |
node_control_host | NODE_CONTROL_HOST | 控制 | 0.0.0.0 | Hypercorn 监听地址。 |
node_control_port | NODE_CONTROL_PORT | 控制 | 8003 | Hypercorn 监听端口。 |
agent_compose_agent_image | AGENT_COMPOSE_AGENT_IMAGE | 控制 | 空 | docker/docker-compose 节点引导脚本使用的镜像。 |
agent_compose_node_bin_dir | AGENT_COMPOSE_NODE_BIN_DIR | 控制 | 自动探测 nodes/dist | 提供节点安装包下载的二进制目录。 |
node_default_session_cpu | NODE_DEFAULT_SESSION_CPU | 控制 | 1.0 核 | 每个节点会话的全局 CPU 计费量；0 表示不按该维度准入。 |
node_default_session_memory | NODE_DEFAULT_SESSION_MEMORY | 控制 | 1073741824 字节 | 每个节点会话的全局内存计费量；0 表示不按该维度准入。 |
node_terminal_max_active_per_node | NODE_TERMINAL_MAX_ACTIVE_PER_NODE | 控制 | 10 | 单节点最大活跃终端数，至少为 1。 |
node_terminal_detached_ttl_seconds | NODE_TERMINAL_DETACHED_TTL_SECONDS | 控制 | 1800 秒 | 无浏览器挂载终端的存活秒数，至少 60。 |
.env 必须可写且持久化控制服务在缺少 token 或凭据加密密钥时会生成并回写 .env；写入失败会拒绝启动。在容器中必须挂载持久化配置，不能只把 .env 烘焙进一次性镜像。多副本控制服务也不能依赖各副本各自生成密钥。
7. [clickhouse] 请求 payload 双写（可选，默认关闭）
| ini 字段 | 环境变量 | 进程 | 必需/默认 | 说明 |
|---|---|---|---|---|
request_payload_enabled | CLICKHOUSE_REQUEST_PAYLOAD_ENABLED | 数据 | false | 启用 ClickHouse 数据源、payload 双写和对话存储。 |
request_payload_capture_enabled | CLICKHOUSE_REQUEST_PAYLOAD_CAPTURE_ENABLED | 数据 | false | 是否捕获请求正文，开启前必须完成隐私评估。 |
addr | CLICKHOUSE_ADDR | 数据 | 空 | ClickHouse 地址 host:port。 |
database | CLICKHOUSE_DATABASE | 数据 | ai_lubricant_logs | ClickHouse 库名。 |
username | CLICKHOUSE_USERNAME | 数据 | 空 | ClickHouse 用户。 |
password | CLICKHOUSE_PASSWORD | 数据 | 空 | ClickHouse 密码。 |
request_payload_ttl_days | CLICKHOUSE_REQUEST_PAYLOAD_TTL_DAYS | 数据 | 30 天 | payload 保留天数。 |
max_payload_bytes | CLICKHOUSE_MAX_PAYLOAD_BYTES | 数据 | 262144 字节 | 单条 payload 上限。 |
关闭 ClickHouse 时，模型代理主链路仍可工作；请求大字段双写和依赖 ClickHouse 的对话存储不可用。不要在未完成隐私、访问控制和 TTL 评估前捕获生产请求正文。
8. [marketplace] / [marketplace.consumer] 资源市场（可选）
两级开关：只填 repo_url 即「可看不可管」；再补 github_token 才出现 /manager/marketplace-admin 管理页。详细含义、获取方式与验证见 部署文档第 6 章。
| ini 字段 | 环境变量 | section | 说明 |
|---|---|---|---|
repo_url | MARKETPLACE_REPO_URL | marketplace | 市场仓库地址（唯一必填）。owner/repo 由它解析。 |
github_branch | MARKETPLACE_GITHUB_BRANCH | marketplace | 可选。留空用 main；地址里带 /tree/<分支> 时取那个分支。 |
github_token | MARKETPLACE_GITHUB_TOKEN | marketplace | fine-grained token，仅「管市场」需要。仅服务端内存使用，从不传输给前端。 |
modules | MARKETPLACE_MODULES | marketplace | 模块白名单，逗号分隔，默认 mcp,plugins,skills,channels,prompts,node-versions。 |
index_name | MARKETPLACE_INDEX_NAME | marketplace | 每个模块的索引文件名，默认 index.json。 |
repo_url / github_branch / modules / index_name | 同名 MARKETPLACE_* | marketplace.consumer | 消费侧只读公开 raw；留空时回退到 [marketplace] 对应字段。 |
兼容旧写法早期版本要求分别填
github_owner 和 github_repo，这两个字段仍然可用：填了 repo_url 以它为准，没填才回落到拆字段写法，已有部署升级后无需改配置。9. 进程级环境变量（无 ini 对应）
| 环境变量 | 进程 | 默认 | 说明 |
|---|---|---|---|
TZ | 两 | 系统 | 时区；compose 内设为 Asia/Shanghai。 |
DEBUG | 数据 | false | 进程调试标志；生产显式设为 false。 |
APP_VERSION | 数据 | dev | 用户门户公开的当前版本号。 |
EDITOR_SESSION_REAPER_INTERVAL | 数据 | 300 秒 | 编辑器会话回收扫描间隔，最小 60 秒。 |
EDITOR_SESSION_PENDING_TIMEOUT | 数据 | 1800 秒 | pending 会话超时，最小 60 秒。 |
EDITOR_SESSION_IDLE_TIMEOUT | 数据 | 86400 秒 | 空闲会话超时，最小 300 秒。 |
NODE_BINDING_RECONCILE_INTERVAL | 数据 | 300 秒 | 节点授权关系对账间隔，最小 60 秒。 |