配置参考

本项目包含 5 个核心服务：backend / executor-manager / memory-service / executor / frontend。 启用 AI 听记时，还会增加独立的 ai-note-worker 计算服务。

资源下载工具使用执行器管理器自动生成的内部变量 POCO_RESOURCE_DOWNLOAD_ENV_KEYS， 限定可用于下载认证的用户环境变量名称。该变量无需手动配置，用户变量不能覆盖它； 平台内部密钥、模型配置变量和系统运行变量不会因此开放给下载工具。 下载默认限制为单文件 256 MiB、每会话受管理的下载文件累计 1 GiB、并发 2 个， 连接超时 10 秒、读取空闲超时 30 秒、请求总时限 120 秒。 HTTP 压缩传输支持 gzip 与标准 deflate，按解压后的实际大小计入限制，解压过程同样分块限量。 这些限制由执行器代码控制，下载内容保存到工作区 downloads/，随正常工作区快照持久化。 Playwright MCP 子进程使用内部变量 POCO_PLAYWRIGHT_LANE_ID 关联下载事件与浏览器调用通道， 由路由器生成，用户变量不能覆盖，无需手动配置。 浏览器已有响应仅在未压缩且 Content-Length 不超过 1 MiB 时自动归档； 未知大小、压缩、超限或显式指定文件名的响应仍按原参数执行。 浏览器文本超过 16 KiB 时尝试保存为工作区文件；归档失败保留原始结果。 原生下载归档仅支持本地浏览器，远程浏览器继续使用原下载流程。 归档失败或超时不取消原下载，不关闭共享浏览器通道，也不改变任务状态。 快照前最多等待归档清理 5 秒；未完成的增强写入会收到取消标记，原快照继续执行。 HTTP 下载失败会返回 request_state：not_started 表示尚未发起资源请求， may_have_started 或 unknown 表示可能已发送。切换获取方式前需确认已发送 POST 的执行结果， 避免重复创建导出任务等业务副作用。增强无法处理的场景允许继续使用原浏览器或脚本流程。

依赖项包括：

• postgres
• S3 兼容对象存储（可选本地 rustfs，也可使用 Cloudflare R2 等云服务）

下面列出各服务常用环境变量（含含义与默认值）。在生产环境请务必替换所有 change-this-*、弱口令与默认密钥。

---

配置来源与生效范围

本文区分服务独立运行的 Settings 默认值、Compose 插值默认值和后台已保存配置。Backend 中可持久化的系统/模型设置按读取链路优先于环境默认；修改环境后还应检查后台实际保存值。

根目录 .env 是 Compose 插值来源，不是自动传入每个服务的环境文件。当前主/worker 编排未传入 SCHEDULE_CONFIG_PATH 或挂载调度文件，也未传入 Manager 的 WORKBENCH_ANALYSIS_INTERVAL_SECONDS、WORKBENCH_ANALYSIS_BATCH_LIMIT、WORKBENCH_ANALYSIS_MAX_BATCHES_PER_TICK、WORKBENCH_ANALYSIS_MAX_TICK_SECONDS，以及听记媒体探测/转换超时、夜间窗口细项和 DB_WAIT_TIMEOUT_SECONDS；只在根 .env 添加这些值不会生效。独立运行可直接设置；容器部署需明确增加对应 environment 和必要文件挂载。

Backend（FastAPI）

必需（否则无法启动或关键功能不可用）：

• DATABASE_URL：必填的 Backend 主数据库连接串，仅支持 PostgreSQL，示例：postgresql://postgres:postgres@postgres:5432/poco。未配置或传入 SQLite 等其他数据库连接时，Backend 会拒绝启动。
• DATABASE_POOL_SIZE（默认 100）：每个 Backend 进程保留的 SQLAlchemy 常驻连接数。
• DATABASE_MAX_OVERFLOW（默认 100）：常驻连接全部占用时，每个 Backend 进程允许临时增加的连接数。
• DATABASE_POOL_TIMEOUT_SECONDS（默认 3）：连接池耗尽后等待连接的最长秒数，超时后立即返回错误，避免请求无限阻塞。
• SECRET_KEY：后端密钥（用于安全相关逻辑）
• AUTH_STATE_ENCRYPTION_KEY（可选）：浏览器 Auth State 加密密钥。可填写 Fernet key 或强随机字符串；留空时本地开发会从 SECRET_KEY 派生，生产环境建议单独配置。
• INTERNAL_API_TOKEN：内部调用鉴权 token（Executor Manager 调用 Backend 内部接口会用到）
• ROOT_PASSWORD / ROOT_PASSWORD_SALT：首次创建固定 root 账号时使用的初始密码和密码盐。数据库中已存在 root 时，启动不会再用环境变量覆盖其密码；通过前端修改的密码会在重启后继续生效。
• S3_ENDPOINT：S3 兼容服务地址
• 本地 rustfs：http://rustfs:9000
• Cloudflare R2：https://<accountid>.r2.cloudflarestorage.com
• S3_ACCESS_KEY / S3_SECRET_KEY：S3 访问凭证
• S3_BUCKET：S3 bucket 名称（需存在；本地 rustfs 可用 rustfs-init 创建；R2 请在控制台提前创建）

定时任务联动产物使用 scheduled-task-artifacts/ 对象前缀。生产环境需为该前缀单独设置生命周期过期规则。使用“前置完成后触发”时，保留期应长于下游 Run 允许的最长排队和重试时间；使用“按自身计划取最新产物”时，还应覆盖上游两次有效产物之间可能出现的最长间隔，否则数据库中的历史产物记录可能已经对应不到可下载对象。系统不会硬编码最大产物年龄；具体操作见部署说明。

执行器按会话运行时代次保存本地事件日志，以 20ms 窗口合并文本片段，每批最多 100 项、1MiB，超过 1MiB 的单个事件单独成批发送。后端在数据库事务提交后确认并推送 SSE；多个后端实例通过 PostgreSQL 通知唤醒查询。每个运行时的内存待写队列最多 1000 项、16MiB，未确认日志最多 20000 项、64MiB。达到上限会停止执行并报告记录不完整，不会丢弃消息后继续宣告成功。

常用：

• RUN_MIGRATIONS（默认 true）：Backend 容器启动脚本开关，启用时执行 alembic upgrade heads。
• DB_WAIT_TIMEOUT_SECONDS（默认 60）：容器启动脚本等待数据库可达的时间。
• HOST（默认 0.0.0.0）、PORT（默认 8000）
• BACKEND_URL：Backend base URL。Backend 用它生成任务浏览器实时预览 WebSocket 地址和知识库 OAuth 回调地址；Executor Manager / Worker 也用它访问 Backend。Frontend 未配置 INTERNAL_API_BASE_URL 时会将它作为服务端请求的兼容回退。启用知识库 Agent 检索时，Backend 进程中的该值必须是浏览器可访问且不含路径、参数或账号信息的 HTTP(S) Origin。
• MESSAGE_DELIVERY_RECOVERY_TIMEOUT_SECONDS（默认 900）：终态消息长时间无法补齐时，等待多久后标记为“消息不完整”。此状态不会释放成功通知或下游任务；后台继续重放，补齐后转为 synced，再检查产物等完成条件。
• Backend 默认允许任意跨域来源访问 API，无需配置跨域来源白名单。
• APP_TITLE（独立运行默认 Poco Agent，主 Compose 默认 AI Agent）：前端公共配置接口 GET /api/v1/public-config 返回的应用标题（appTitle）
• OPENAPI_LOGIN_TOKEN_TTL_SECONDS（默认 86400，范围 60~86400）：POST /openapi/v1/auth/token 签发的登录 Token 有效期（秒）。调用方不能通过请求参数修改有效期。
• OPENAPI_BACKGROUND_MAX_PENDING_PER_KEY（默认 20）：单个 API Key 允许同时存在的未完成后台运行数，包含排队、执行和结果同步阶段。
• OPENAPI_BACKGROUND_MAX_PENDING_PER_USER（默认 50）：同一用户全部 API Key 允许同时存在的未完成后台运行总数。
• OPENAPI_BACKGROUND_MAX_RUNNING_PER_KEY（默认 2）：单个 API Key 最多同时执行的后台运行数；普通对话运行不受该限制影响。
• OPENAPI_BACKGROUND_QUEUE_CAPACITY_MULTIPLIER（默认 10）：全局后台任务容量相对于支持 openapi 调度模式的在线 Worker 总容量的倍数。
• OPENAPI_BACKGROUND_FALLBACK_WORKER_CAPACITY（默认 5）：Worker 注册表尚无记录时，用于计算全局后台任务容量的兼容容量；注册表已有记录但没有在线 Worker 时拒绝新后台任务。
• OPENAPI_BACKGROUND_QUEUE_TIMEOUT_SECONDS（默认 3600，最小 60）：后台任务在队列中等待的最长时间，超时后以 queue_timeout_error 结束。
• OPENAPI_BACKGROUND_POLL_LIMIT_PER_SECOND_PER_INSTANCE（默认 10）：单个 API Key 在单个 Backend 实例上的后台结果查询频率上限。
• XGT_SSO_BASE_URL（可选）：抚顺新钢铁 SSO 根地址，例如 http://10.6.77.168。配置后，系统会自动拼接认证入口 /sso/auth、APP 登录接口 /sso/doLogin、用户信息接口 /login/getUserInfo 和注销接口 /login/doSimpleLoginOut。用户信息中的 data.empNo 用作工号，data.secondUnit 会同步到用户部门。
• JIANLONG_SSO_BASE_URL（可选）：建龙集团认证中心根地址，例如 https://server-auth.ejianlong.com。需要与 JIANLONG_SSO_APP_ID、JIANLONG_SSO_APP_SECRET 同时配置才会显示“建龙集团 SSO 登录”入口。
• JIANLONG_SSO_LOGOUT_URL（可选）：建龙集团 SSO 注销接口。配置后，通过该 SSO 登录的浏览器会显示“切换账号”。
• JIANLONG_SSO_APP_ID（可选）：建龙集团认证中心应用 ID，用于授权码登录跳转和后端换取访问令牌。
• JIANLONG_SSO_APP_SECRET（可选）：建龙集团认证中心应用密钥，仅后端使用，不会返回给前端。
• SSO_HTTP_TIMEOUT_SECONDS（默认 10）：后端请求 SSO 接口的超时时间（秒）。
• EXECUTOR_MANAGER_URL：Executor Manager 地址，示例：http://executor-manager:8001
• LEGACY_UNBOUND_SESSION_WORKER_ID（可选）：升级到多 worker 前已有 session 没有 bound_worker_id。如果这些历史 session 的本地工作区仍在原单机节点上，把该值设为原节点的 EXECUTOR_WORKER_ID，避免历史会话被新 worker 抢占后丢失本地工作区上下文。主 docker-compose.yml 默认使用 local-worker
• MEMORY_SERVICE_URL（默认空）：记忆服务地址。留空时，后端记忆管理接口返回 service_enabled=false，不会直接读写记忆数据库。
• MEMORY_SERVICE_API_KEY（默认空）：访问记忆服务的 Bearer Token（可选）。
• MEMORY_DEFAULT_TENANT_ID（Backend 独立运行默认 default，Compose 默认 poco）：调用记忆服务时使用的默认租户标识，各服务必须保持一致。
• MEMORY_SERVICE_TIMEOUT_SECONDS（Backend 独立运行默认 12，Compose 默认 60）：后端调用记忆服务管理接口的 HTTP 超时时间（秒）。
• GOTENBERG_URL（Backend 独立运行默认空，主 Compose 默认 http://gotenberg:3000）：Gotenberg 服务根地址。主 docker-compose.yml 已集成并默认启用 Gotenberg；也可以配置 Backend 能够访问的其他服务地址。地址只在 Backend 使用，不会返回给浏览器。显式留空时 HTML 和 Markdown 保持浏览器打印回退，其他格式不新增 PDF 操作。部署与连通性说明见 部署指南。
• GOTENBERG_API_TIMEOUT（主 Compose 默认 120s）：Gotenberg 单次 API 请求的最长执行时间，使用 Go duration 格式，例如 90s、2m。
• GOTENBERG_TIMEOUT_SECONDS（Backend 独立运行默认 60，主 Compose 默认 130，范围 1~600）：Backend 等待 Gotenberg 转换和响应的超时时间（秒），应略大于 GOTENBERG_API_TIMEOUT。已配置服务但转换失败时会直接提示失败，不会静默切换为浏览器打印。
• SNOWFLAKE_WORKER_ID（默认 0）、SNOWFLAKE_DATACENTER_ID（默认 0）：Snowflake ID 生成器配置（取值 0~31）。单实例可不配置，多实例需分配不同值避免冲突。
• S3_PUBLIC_ENDPOINT：对外可访问的 S3 地址，用于生成给浏览器的预签名 URL（本地可用 http://localhost:9000）。独立运行未设置时使用 S3_ENDPOINT；主 Compose 默认 http://localhost:9000，外部存储必须显式覆盖
• S3_REGION（默认 us-east-1；Cloudflare R2 通常建议设为 auto）
• S3_FORCE_PATH_STYLE（默认 true，对 MinIO/RustFS 一般需要；Cloudflare R2 通常建议设为 false）
• S3_PRESIGN_EXPIRES：预签名 URL 过期秒数（默认 300）
• MAX_UPLOAD_SIZE_MB（默认 100）
• USER_APP_MAX_DOCUMENT_SIZE_MB（默认 1，最小 1）：应用数据单条记录的最大 JSON 内容大小（MB，1MB = 1024 × 1024 字节），按序列化后的 UTF-8 字节数计算；部分更新按合并后的完整记录校验。共享和个人私有记录均不设置数量上限
• USER_APP_MAX_FILE_STORAGE_MB（默认 10240，即 10GB）：应用数据中，页面上传到单个应用的文件总量上限（MB）。文件存放在上述 S3 中，请按存储容量调整；单个文件固定上限 10MB，每个应用最多 10000 个文件
• Gotenberg PDF 导出支持 HTML、Markdown，以及其 LibreOffice 路由支持的 Word、Excel、PowerPoint、OpenDocument、图片、电子书等格式；现有 PDF 文件继续下载原文件，不做二次转换。HTML/Markdown 的预渲染内容上限为 10MB，其他源文件沿用 MAX_UPLOAD_SIZE_MB。完整扩展名以 Gotenberg 官方列表 为准。
• ANTHROPIC_DEFAULT_HAIKU_MODEL：后端与 Poco Agent 运行时共用的轻量模型别名；后端“推荐追问”在未显式配置 FOLLOWUP_MODEL 时会使用它
• FOLLOWUP_MODEL（默认空）：后端生成“推荐追问”时使用的模型名（可选覆盖）；为空时回退到 ANTHROPIC_DEFAULT_HAIKU_MODEL
• SESSION_TITLE_MODEL：后端生成“任务标题建议”时使用的模型名（用于重命名弹窗“自动生成”）
• SESSION_SUMMARY_MODEL：后端生成整段会话摘要时使用的模型名
• PUBLISH_CENTER_SELECTOR_MODEL：发布中心自动发布时，用于多 HTML 候选内容审核与选择的模型名
• WORKBENCH_ANALYSIS_MODEL：智能工作台分析使用的模型名；若显式传空值，会使用默认模型配置
• WORKBENCH_ANALYSIS_MAX_TOKENS（默认 4196）：智能工作台单次分析请求的 max_tokens
• WORKBENCH_EMBEDDING_URL（默认 http://m3e:6008/v1/embeddings）：智能工作台和定时任务“语义去重”共用的向量接口地址
• WORKBENCH_EMBEDDING_API_KEY（默认 sk-aaabbbcccdddeeefffggghhhiiijjjkkk）：向量接口 Bearer Token（仅填 token 本体，不含 Bearer 前缀）
• WORKBENCH_EMBEDDING_MODEL（默认 m3e）：当前模型配置使用的语义向量模型，同时用于智能工作台和定时任务查重
• WORKBENCH_EMBEDDING_TIMEOUT_SECONDS（默认 8）：向量接口超时时间（秒）
• SCHEDULED_TASK_SEMANTIC_SIMILARITY_THRESHOLD（默认 0.75，范围 0~1）：定时任务语义相似候选的提示阈值；精确重复任务始终阻止创建
• CAPABILITY_RERANK_MODEL（默认 bge-reranker-base）：能力推荐接口 POST /api/v1/capabilities/recommend 使用的重排模型名（请求地址与鉴权复用 ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN）

通用界面后台系统配置（通过管理后台维护，不是 Backend 启动环境变量）：

办公首页人物目录、图片路径及成组文案由后端版本内置。用户仅在办公模式的“个性化”菜单中选择人物，并按账号保存；每个人物独立保留自己的文案数组，欢迎语和提示文案在进入或刷新首页时只随机选择一次。前端按账号和界面语言缓存最近一次成功配置，并预加载当前人物图片；/office-home/ 静态资源缓存策略为 1 天有效期和 7 天后台重新验证期。动画及加载失败处理见管理员配置。管理员维护全局界面主题和以下人物排除配置：

• office_home_excluded_characters（默认空列表）：在“系统配置 → 通用设置 → 办公首页排除人物”的下拉菜单中勾选一个或多个人物；不勾选表示不排除。当前主题全部被排除时仍保留该主题原始顺序中的第一个人物。已有选择被排除后，切换到第一个可选人物并保存到账号。用户刷新页面后生效，无需重新构建或重启服务。

知识库不使用系统配置项。管理员在 管理后台 → 连接器管理 上传独立的 WeKnora knowledge-base ZIP，填写 Origin、Client ID 和 Client Secret 后发布，所有正常登录用户都可以连接自己的账号。知识空间由用户在 WeKnora 授权页选择，不配置全局空间 ID。WeKnora 中登记的回调地址必须为 ${BACKEND_URL}/api/v1/connectors/oauth/callback。完整流程见连接器与知识库检索。

AI 听记后台系统配置（通过管理后台维护，不是 Backend 启动环境变量）：

• ai_note_enabled（默认 false）：是否启用 AI 听记。关闭时，前端首页左侧工作分组不会展示 AI 听记入口。
• ai_note_realtime_enabled（默认 true）：是否启用 AI 听记实时记录。关闭后不影响上传文件的离线听记。
• realtime_asr_provider（默认 qwen_v2）：实时语音 ASR 提供方。实时语音输入和 AI 听记实时记录共用该配置，目前仅支持 qwen_v2 流式文字预览，不启用实时说话人或声纹识别。
• realtime_asr_base_url（默认 http://127.0.0.1:8766）：实时语音 Qwen v2 ASR 服务根地址，必须是 Backend Web 进程可访问的地址。多节点部署时建议显式配置为独立实时 ASR 服务地址。
• realtime_asr_api_key（默认空）：实时语音 ASR Bearer Token。留空时回退到 ai_note_asr_api_key。
• ai_note_asr_provider（默认 qwen_v2）：离线听记 ASR 提供方。qwen_v2 使用原生异步任务接口；openai_compatible 保留旧的同步 multipart 转写接口。
• ai_note_asr_base_url（默认 http://127.0.0.1:8766）：离线听记 Qwen v2 ASR 服务根地址。生产环境必须配置为 ai-note-worker 可访问的地址。
• ai_note_asr_url（默认 http://127.0.0.1:8766/compat/openai/v1/audio/transcriptions）：OpenAI 兼容模式 ASR 请求地址，仅 ai_note_asr_provider=openai_compatible 时必填。
• ai_note_asr_api_key（默认空）：离线听记 ASR Bearer Token。后台展示时应脱敏，普通前端接口不得返回明文。
• ai_note_asr_model（默认 qwen3-asr-1.7b）：离线听记 ASR 模型名。兼容模式请求时作为 multipart form 字段 model 传递。
• ai_note_asr_options：Qwen v2 ASR 识别选项 JSON，默认开启 diarize、identify_speakers、with_punc、with_words，并包含 poll_interval_seconds=2、timeout_seconds=1800。
• ai_note_summary_model：AI 听记摘要模型名，必填。为空时摘要阶段直接失败，不回退到其他模型。
• ai_note_summary_max_tokens（默认 6000）：AI 听记单次摘要请求允许模型生成的最大 Token 数。使用会输出思考内容的兼容模型时，需要为思考过程和最终 JSON 共同预留足够空间。
• ai_note_max_file_size_mb（默认 200）：AI 听记单文件大小上限。
• ai_note_max_duration_seconds（默认 7200）：AI 听记单媒体文件时长上限。

AI 听记声纹库不增加新的系统配置。管理员可在 管理后台 → 听记记录 → 声纹库 直接维护组织级声纹；普通用户可在 AI 听记页提交个人声纹，由管理员审核通过后发布。所有 AI 听记统一使用 ASR 侧已经生效的说话人。

• 声纹管理只使用 Qwen v2 ASR 已有的 /v2/speakers* 接口。ai_note_asr_base_url 是唯一管理入口，录入、查询、认领、更新、追加样本和删除都请求该离线地址；Poco 不会向 realtime_asr_base_url 发起声纹管理请求。
• Backend Web 进程必须能够访问 ai_note_asr_base_url。realtime_asr_base_url 仍负责实时语音识别，但不参与声纹 CRUD。
• 最终说话人和声纹识别只由 ai_note_asr_base_url 对应的离线服务执行；实时服务不参与声纹匹配，因此实时预览不依赖两个服务共享声纹数据库。
• Backend 只通过离线入口调用 /v2/capabilities 检查声纹能力。管理员直接录入或追加样本时也只通过离线入口调用 /v2/speakers/identify 检查音频是否可处理，并忽略声纹匹配结果。
• Backend 不根据 /v2/speakers/identify 的匹配结果判断重复声纹，预检通过后会直接创建新的 ASR 说话人。历史绑定仍指向 ASR 自动登记的占位声纹时，Backend 会使用已持久化的认领键调用 /v2/speakers/{speaker_id}/claim 恢复原绑定。
• 原始声纹样本保存在 S3_* 指向的私有对象存储中，用于追加和失败重试。每个档案最多 16 个样本，单个样本不超过 20MB、全部样本合计不超过 100MB；部署方应同时落实对象存储加密、访问审计和数据保留策略。
• 历史样本删除只通过离线入口调用 ASR 单模板删除接口，并至少保留一个样本。批量删除对象存储文件时，只要 S3 返回任一逐项错误，本地档案就会保留以便重试。
• Poco 的实时、离线目标绑定仍复用离线管理入口返回的同一个 speaker_id 与模板 ID，但不再请求实时 ASR 地址维护声纹状态；实时转写链路不会消费这些声纹绑定。

文生图后台系统配置（通过管理后台维护，不是 Backend 启动环境变量）：

• text_to_image_enabled（默认 false）：是否向后续新启动的 Executor 容器注入内置文生图工具。
• text_to_image_model（默认 gpt-image-2）：文生图工具调用 OpenAI 兼容图片生成接口时使用的模型名。

日志（Python 服务通用）：

• DEBUG（默认 false）
• LOG_LEVEL（默认随 DEBUG/非 DEBUG 变化；建议显式设为 INFO）
• UVICORN_ACCESS_LOG（默认 false）
• LOG_TO_FILE（默认 false）：是否写本地文件日志
• LOG_DIR（默认 ./logs）、LOG_BACKUP_COUNT（默认 14）
• LOG_SQL（默认 false）：是否打印 SQLAlchemy SQL（注意敏感信息）

AI Note Worker（启用 AI 听记时）

AI Note Worker 是 AI 听记的独立计算服务，负责领取听记任务、校验媒体文件、抽取视频音轨、调用 ASR、调用 LLM 摘要并回写 Backend。它不直连数据库，不是 AI 听记业务数据的 owner。

必需：

• BACKEND_URL：Backend 地址，示例：http://backend:8000
• INTERNAL_API_TOKEN：必须与 Backend 的 INTERNAL_API_TOKEN 一致，用于调用内部任务 claim/progress/complete/fail API。
• ANTHROPIC_AUTH_TOKEN：摘要模型访问 token。Worker 启动时会校验该值非空。
• ANTHROPIC_BASE_URL（默认 https://api.anthropic.com）：摘要模型网关地址。
• AI_NOTE_WORKER_ID：当前 Worker 的稳定节点 ID，多实例部署时必须唯一。
• AI_NOTE_MAX_CONCURRENT_JOBS（默认 1，建议 1 或 2）：单个 Worker 同时处理的听记任务数上限。
• AI_NOTE_TEMP_DIR：媒体文件下载、ffprobe 检查、ffmpeg 抽音轨和临时文件使用的目录。

常用：

• HOST / PORT（默认 0.0.0.0 / 8010）：Worker /health 服务监听地址和端口。
• AI_NOTE_POLL_INTERVAL_SECONDS（默认 3）：空队列时轮询间隔。
• AI_NOTE_CLAIM_LEASE_SECONDS（默认 900）：Worker claim 任务租约时长。
• AI_NOTE_REQUEST_TIMEOUT_SECONDS（默认 120）：Worker 调用 Backend 和对象存储预签名 URL 的普通请求超时。
• AI_NOTE_ASR_TIMEOUT_SECONDS（默认 1800）：调用 ASR 接口的请求超时。
• AI_NOTE_LLM_TIMEOUT_SECONDS（默认 120）：调用摘要模型的请求超时。
• AI_NOTE_FFPROBE_TIMEOUT_SECONDS（默认 60）：ffprobe 探测媒体时长的超时。超时视为文件处理失败，不重试。
• AI_NOTE_FFMPEG_TIMEOUT_SECONDS（默认 300）：ffmpeg 从视频中抽取音轨的超时。超时视为文件处理失败，不重试。
• LOG_LEVEL、UVICORN_ACCESS_LOG：日志级别和访问日志开关。

AI Note Worker 通过 Backend 内部接口领取任务，任务 payload 会包含 ASR provider、地址、模型、密钥、识别选项和摘要模型。Worker 日志不得打印 ai_note_asr_api_key、对象存储签名 URL、完整转写文本或完整模型输出。

Executor Manager

必需（否则无法启动或无法调度执行）：

• BACKEND_URL：Backend 地址，示例：http://backend:8000。动态 Executor 会使用该地址直连 Backend 实时消息入口，因此该地址还必须能从 Executor 容器访问。
• INTERNAL_API_TOKEN：必须与 Backend 的 INTERNAL_API_TOKEN 一致。Manager 用它签发仅限单个 session/run、短时有效的实时消息令牌，任务请求不会把全局 token 直接作为实时回调凭证。
• CALLBACK_TOKEN：必须显式配置，且与 Executor 执行请求中的 callback_token 一致；为空或默认占位值时 Executor Manager 会拒绝启动，避免运行时回调 403
• CALLBACK_BASE_URL：必须能被 Executor 容器访问到，Docker Compose 默认 http://host.docker.internal:8001
• EXECUTOR_WORKER_ID：Executor Manager 的稳定节点 ID。本地单机主 compose 默认 local-worker；多节点部署时每台机器必须显式配置为唯一且重启后不变的值，例如 worker-a、worker-b
• EXECUTOR_WORKER_BOOT_ID：Executor Manager 容器实例 ID。容器启动脚本默认使用 Docker 容器 hostname 自动生成，同一容器重启时保持不变，容器重建后自动变化，无需手动配置
• EXECUTOR_MANAGER_PUBLIC_URL：Backend 访问该 Executor Manager 的地址，例如 http://10.0.0.11:8001。未配置时回退到 CALLBACK_BASE_URL
• EXECUTOR_WORKER_HEARTBEAT_INTERVAL_SECONDS（默认 10）：节点注册后的心跳间隔。Backend 会用心跳状态判断 worker 是否可接新 session
• EXECUTOR_IMAGE：Executor 镜像名（Executor Manager 会通过 Docker API 拉起该镜像）
• EXECUTOR_CPU_LIMIT：每个动态拉起的 Executor 容器可使用的最大 CPU 核数；0 或不配置表示不限制
• EXECUTOR_MEMORY_LIMIT：每个动态拉起的 Executor 容器可使用的 RAM + swap 总上限；支持 512m、2g、4096m 等 Docker 单位，空值或 0 表示不限制
• EXECUTOR_PUBLISHED_HOST：Executor Manager 访问“已映射到宿主机端口”的 Executor 容器时使用的 host（本地裸跑一般是 localhost；Compose 内推荐 host.docker.internal）
• BROWSER_STREAM_PUBLISHED_HOST：Executor Manager 生成任务浏览器实时预览上游地址时使用的 host。前端不再直连 worker，而是连接 Backend 的 WebSocket 代理；因此分布式部署通常保持 host.docker.internal 或 manager 自身可访问动态 Executor 端口的地址即可
• WORKSPACE_ROOT：工作区根目录（必须是宿主机路径，因为会被 bind mount 到 Executor 容器）
• S3_ENDPOINT / S3_ACCESS_KEY / S3_SECRET_KEY / S3_BUCKET：用于导出 workspace 到对象存储（否则相关接口会失败）
• Cloudflare R2 通常建议：S3_REGION=auto，S3_FORCE_PATH_STYLE=false
• Executor Manager 运行时默认设置 BOTO_EXPERIMENTAL__NO_EMPTY_CONTINUE=true，避免空对象上传进入 botocore 的 Expect: 100-continue 流程；通常无需在部署配置中重复声明，显式设置仍可覆盖

多节点执行采用 session 粘性和本地工作区：

• 新 session 首次被某个 EXECUTOR_WORKER_ID claim 后，会绑定到该 worker
• 历史未绑定 session 会优先由 LEGACY_UNBOUND_SESSION_WORKER_ID 指定的原节点 claim 并回填绑定
• 后续同一 session 的 run、停止、浏览器流、会话历史补偿和清理都会按绑定 worker 路由
• WORKSPACE_ROOT 仍是每台机器本地目录，不需要 NFS；完成后的工作区文件继续通过 S3_* 导出和访问
• worker 进入 draining 后不再接新 session，但已绑定 session 仍可继续执行
• 用户级远程浏览器会按 tenant_id + user_id 绑定到创建它的 worker；登录态 flush、停止和删除都会回到该 worker

执行模型（跑任务时必需）：

• ANTHROPIC_AUTH_TOKEN：Poco Agent 运行时模型访问 token
• ANTHROPIC_BASE_URL：模型网关地址，可按部署环境配置
• DEFAULT_MODEL：Poco Agent 运行时默认模型
• POCO_EXECUTION_SCENE：系统自动注入的本轮执行场景，值为 business 或 office，用于核对场景化模型解析结果，无需手动配置
• POCO_MODEL_CONFIG_ID：系统自动注入的本轮有效后台模型配置 ID；仅在后台没有可用模型配置、回退到 Executor 自身环境变量时为空，用于排查模型切换是否生效，无需手动配置
• 首页语音输入使用后台系统配置中的实时语音 ASR 配置：
• voice_input_enabled（默认关闭）：是否在首页输入框显示语音输入入口
• ANTHROPIC_DEFAULT_HAIKU_MODEL：下发到 Executor 容器，作为轻量模型别名
• Poco Agent 运行时兼容开关：由系统按需注入，用于控制 Subagent 模型、推理强度、后台任务和非必要网络流量；通常不需要手动配置
• CLAUDE_CODE_SUBAGENT_MODEL：普通任务沿用后台的子代理模型设置。专家团运行时，SDK 子进程中的此项被清空，成员模型改由执行快照中的 AgentDefinition.model 分别指定，避免主编排模型覆盖成员选择；无需增加部署环境变量。
• 后台系统配置 experimental_agent_teams_enabled（默认关闭）：启用代理团队实验功能；开启后，Executor Manager 会向新 Executor 容器注入 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
• 后台系统配置 text_to_image_enabled（默认关闭）：启用后，Executor Manager 会向新 Executor 容器注入 POCO_TEXT_TO_IMAGE_ENABLED=1、POCO_TEXT_TO_IMAGE_MODEL，并将 MCP_TOOL_TIMEOUT 提高到 600000 毫秒，以覆盖生图长耗时。
• 后台系统配置 artifact_continuation_enabled（默认关闭）：控制 HTML/Markdown 分享页和发布页的“继续探索”能力。全局开启后仍需分享者或发布页管理员逐项启用；匿名访问者不显示入口，续聊会话归当前登录用户所有。
• POCO_TEXT_TO_IMAGE_API_KEY / POCO_TEXT_TO_IMAGE_BASE_URL：平台级文生图 OpenAI 兼容接口配置，会作为默认值转发到动态 Executor 容器；未配置专用 key 时，工具会回退读取 OPENAI_API_KEY / OPENAI_BASE_URL。用户级环境变量优先级高于平台级默认值。
• DISABLE_AUTOUPDATER（默认 1）：下发到 Executor 容器，用于禁用自动更新行为
• ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL / ANTHROPIC_MODEL / ANTHROPIC_REASONING_MODEL：由系统自动注入到 Executor 容器，且始终等于 DEFAULT_MODEL
• VISION_MODEL（可选）：会注入到 Executor 容器，供 understand_image 使用（通常在 POCO_MODEL_MULTIMODAL_ENABLED=0 时需要）
• POCO_PLAYWRIGHT_IMAGE_RESPONSES（默认 omit）：Playwright MCP 是否在工具返回里内嵌截图/图片（base64）
• omit：不内嵌（推荐，避免截图过大导致 MCP JSON 消息超限卡死）
• allow：允许内嵌（截图较大时可能触发 1MB 上限）
• POCO_PLAYWRIGHT_MCP_MAX_LANES（默认 30）：单个 Executor 容器内最多保留的 Playwright MCP Router lane 数量；Router 默认启用，仍只启动一个 Chrome/CDP；小于 2 时按 2 处理，以保留 main lane；超过后会回收较旧 lane，避免无限启动 Node 进程。
• POCO_PLAYWRIGHT_MCP_ROUTING_LEDGER（默认空）：Playwright MCP Router 的带外路由账本路径；通常保持为空，系统会写入 WORKSPACE_PATH/.poco/playwright-routing.jsonl。仅在排查路由问题或特殊部署路径时覆盖。
• POCO_ASYNC_SUBAGENT_JOIN_TIMEOUT_SECONDS（默认 7200）：SDK 产生首个结果后，等待关联后台任务、工具和主 Agent 自动续执行全部结束的最长时间。超时会停止该会话的 SDK 进程，并将未完成请求标记为失败。

SDK 原生后台输出由执行器通过 CLAUDE_CODE_TMPDIR 固定保存在当前工作区的 .poco/sdk-tmp/ 中；该内部路径不接受模型环境变量覆盖。容器退出后仍保留宿主机工作区中的输出。单个会话最多同时运行 8 个原生 Agent，超过上限的新建请求会被工具入口明确拒绝。

请求准入上限为每会话 32 条、每用户 128 条尚未被 SDK 确认接收的输入。调度优先分配给活动会话较少的用户；不设置每用户活动会话数量上限，实际并发受执行器容量约束。额度在每次 SDK 结果入账后重新检查，到限后在同一事务中关闭运行时准入并生成停止命令。停止按 Worker 控制周期执行，因此不承诺逐 Token 硬限额。

• POCO_ENABLE_IMAGE_GUARD_MCP（默认 0）：是否注入可选的图片修复 MCP（repair_image_for_model）
• 0：不注入图片修复 MCP
• 1：同时注入图片修复 MCP（用于理解失败时兜底）
• POCO_MODEL_MULTIMODAL_ENABLED（默认 1）：当前模型是否支持原生多模态图片输入
• 1：允许 Executor 发送原生图片块给模型，且不注入 understand_image MCP
• 0：禁用原生图片块，并注入 understand_image MCP 走工具链
• MEMORY_SERVICE_URL（默认空）：传递给动态拉起的 Executor 容器的记忆服务地址；为空时 Executor 记忆检索/写入自动禁用
• MEMORY_SERVICE_API_KEY（默认空）：传递给 Executor 容器访问记忆服务的 Bearer Token（可选）
• MEMORY_DEFAULT_TENANT_ID（独立运行默认 default，Compose 默认 poco）：传递给 Executor 容器的默认租户标识
• MEMORY_SERVICE_TIMEOUT_SECONDS（默认 60）：Executor 调用记忆服务超时时间（秒）
• MEMORY_SEARCH_TOP_K（保留配置，默认 5）：会注入 Executor，并作为 MemoryClient 未收到 top_k 时的默认值；当前自动召回和内置查询工具都会显式传 5，因此单独修改它不会改变这两条内置链路
• MEMORY_SEARCH_MIN_SCORE（默认 0.45）：Executor 侧融合前语义分阈值

调度与拉取：

• EXECUTOR_MANAGER_HEALTHCHECK_URL（默认 http://127.0.0.1:8001/api/v1/health）：Executor Manager 容器内自检地址
• EXECUTOR_MANAGER_HEALTHCHECK_TIMEOUT_SECONDS（默认 15）：单次自检请求超时时间（秒）
• EXECUTOR_MANAGER_HEALTHCHECK_FAILURE_THRESHOLD（默认 3）：连续失败次数达到阈值后停止进程，由 Docker Compose restart: always 重启容器
• EXECUTOR_MANAGER_HEALTHCHECK_INTERVAL_SECONDS（默认 15）：自检间隔（秒）
• EXECUTOR_MANAGER_HEALTHCHECK_START_PERIOD_SECONDS（默认 60）：容器启动后的自检宽限期（秒）
• EXECUTOR_MANAGER_HEALTHCHECK_STOP_GRACE_SECONDS（默认 5）：自检触发重启时等待主进程优雅退出的时间（秒），超时后强制结束
• TASK_PULL_ENABLED（默认 true）：是否从 Backend run queue 拉取任务
• MAX_CONCURRENT_TASKS（默认 5，最小值 1）：单个 Executor Manager worker 同时执行的 run 数上限。worker 注册和心跳时会把该值上报为节点 capacity，后台「执行节点」里的运行负载分母来自这里。
• MAX_EXECUTOR_CONTAINERS（默认 10）：单个 worker 允许保留的 executor 容器总量上限。它限制 Docker 中由 Executor Manager 拉起的运行容器数量，包含正在执行的容器，也可能包含暂时保留用于多轮会话复用的 warm/persistent 容器。它不参与 Backend 的 worker 负载调度，也不会作为节点 capacity 上报。
• TASK_PULL_INTERVAL_SECONDS（默认 5）：immediate、openapi 和 scheduled 拉取规则的兜底轮询间隔。即时对话和 OpenAPI 请求会在 Backend 入队后主动唤醒 Executor Manager，通常不需要依赖该间隔触发。
• TASK_PULL_IMMEDIATE_ENABLED（默认 true）：当前 Worker 是否领取普通即时对话。
• TASK_PULL_OPENAPI_ENABLED（默认 true）：当前 Worker 是否领取 OpenAPI 请求，包括流式、非流式、后台异步和结构化输出请求。
• TASK_PULL_SCHEDULED_ENABLED（默认 true）：当前 Worker 是否领取定时任务。
• DOCKER_GID：Linux 上容器访问 Docker socket 所用组 ID，应与宿主机 socket 的组一致。
• TASK_PULL_NIGHTLY_TIMEZONE 默认 UTC，TASK_PULL_NIGHTLY_START_HOUR=2、TASK_PULL_NIGHTLY_START_MINUTE=0，TASK_PULL_NIGHTLY_WINDOW_MINUTES=360，TASK_PULL_NIGHTLY_POLL_INTERVAL_SECONDS=2。默认窗口对应北京时间 10:00–16:00，部署时按业务时区明确设置；当前两份编排未传入这些窗口细项。
• TASK_PULL_NIGHTLY_ENABLED（默认 true）：当前 Worker 是否在夜间窗口领取 nightly 任务。

未配置时以上四种任务类型默认全部启用，便于单机和普通多节点直接部署。配置项控制的是 Worker 注册时上报的 schedule_modes 以及它可以从 Backend 队列领取的任务类型，不会改变 API 的请求或响应格式。需要划分专用节点时，将该节点不负责的类型设为 false；例如专用 OpenAPI Worker 保持 TASK_PULL_OPENAPI_ENABLED=true，并将另外三项设为 false。如果普通 Worker 不应再处理 OpenAPI，则将它的 TASK_PULL_OPENAPI_ENABLED 设为 false。

• TASK_CLAIM_LEASE_SECONDS（默认 180）：claim 的租约时间。需要覆盖 Manager 侧从 claim 到成功 start_run 的耗时（可能包含技能/附件 staging、拉起 Executor 容器等），否则 run 可能在租约过期后被重新 claim，导致重复调度/重复启动容器。
• STREAM_CALLBACK_TOKEN_TTL_SECONDS（默认 604800，即 7 天）：Executor 直连 Backend 实时回调的令牌有效期。该值应大于系统允许的最长 run 时长，最低为 3600 秒。
• SCHEDULE_CONFIG_PATH：可选，提供 TOML/JSON schedule 配置时会作为完整的拉取规则来源，不再读取上述四个 TASK_PULL_*_ENABLED 开关。自定义文件必须显式列出当前 Worker 需要领取的全部 schedule_modes；需要处理 OpenAPI 请求时，必须包含值为 openapi 的启用规则。仓库中的 executor_manager/schedules.toml 提供了四种类型全部开启的参考配置。
• SCHEDULED_TASKS_DISPATCH_INTERVAL_SECONDS（默认 30）：Executor Manager 调用 Backend 内部接口扫描并入队到期定时任务的间隔（秒）。同一时间段定时任务较多时，可适当调小间隔并配合较小的 batch size，让到期任务分批进入 run queue。
• SCHEDULED_TASKS_DISPATCH_BATCH_SIZE（默认 5）：每次扫描最多将多少个到期定时任务入队。该值越大，到期任务越快进入队列，但 Backend 写入和后续 Executor Manager 拉取压力也越集中；生产环境可按容量调整。
• SCHEDULED_TASK_ARTIFACT_MAX_FILES（默认 1000）：限制单轮定时任务联动产物的文件数，同时限制同一会话工作区内共享历史产物快照的单次及累计文件数
• SCHEDULED_TASK_ARTIFACT_MAX_SIZE_MB（默认 500）：限制单轮定时任务联动产物的未压缩总大小，同时限制同一会话工作区内共享历史产物快照的单次及累计未压缩总大小（MB）
• WORKBENCH_ANALYSIS_INTERVAL_SECONDS（默认 60）：智能工作台分析拉取任务的触发间隔（秒）
• WORKBENCH_ANALYSIS_BATCH_LIMIT（默认 3）：每次调用 Backend 内部 /workbench/analyze-due 的 limit
• WORKBENCH_ANALYSIS_MAX_BATCHES_PER_TICK（默认 5）：单次调度 tick 内最多连续排空的批次数
• WORKBENCH_ANALYSIS_MAX_TICK_SECONDS（默认 45）：单次调度 tick 用于智能工作台排空的最长耗时（秒）

回调队列（进程内公平队列，Executor Manager -> Backend）：

正常高频流消息由 Executor 直达 Backend，不占用该队列。这里承载普通状态、终态等 Manager 回调，以及实时直达失败后的有序批量降级。

• CALLBACK_QUEUE_ENABLED（默认 true）：是否启用回调队列（关闭时改为同步直转发）
• CALLBACK_QUEUE_STREAM_SHARDS（默认 32）：用于估算单会话内存队列容量（与 CALLBACK_QUEUE_STREAM_MAXLEN 一起计算）
• CALLBACK_QUEUE_STREAM_MAXLEN（默认 400000）：用于估算单会话内存队列容量上限
• CALLBACK_QUEUE_FORWARD_RETRY_ATTEMPTS（默认 6）：转发 Backend 的最大重试次数
• CALLBACK_QUEUE_FORWARD_RETRY_BASE_SECONDS（默认 0.2）：重试退避基准秒数
• CALLBACK_QUEUE_FORWARD_RETRY_MAX_SECONDS（默认 5.0）：重试退避最大秒数
• STREAM_OUTBOX_REPLAY_ENABLED（默认 true）：是否扫描本节点 WORKSPACE_ROOT 中 Executor 留下的消息 outbox 并自动补发
• STREAM_OUTBOX_REPLAY_INTERVAL_SECONDS（默认 5）：outbox 扫描间隔（秒）
• STREAM_OUTBOX_REPLAY_MAX_RUNS_PER_TICK（默认 20）：每轮最多处理的运行时日志或终态清单数
• STREAM_OUTBOX_REPLAY_CONCURRENCY（默认 2）：每轮并发补发的运行时日志数
• STREAM_OUTBOX_REPLAY_BATCH_SIZE（默认 100）：单批最多消息数
• STREAM_OUTBOX_REPLAY_BATCH_BYTES（默认 1048576）：单批消息体目标上限（字节），实际不超过协议上限 1048576；超过上限的单个事件单独成批

Warm 容器（用于降低首 token 延迟）：

• WARM_CONTAINER_ENABLED（默认 true）：是否启用 warm 容器机制
• WARM_CONTAINER_IMMEDIATE_ENABLED（默认 true）：是否对 schedule_mode=immediate 和 schedule_mode=openapi 的交互式对话启用 warm 容器
• WARM_CONTAINER_IDLE_TTL_SECONDS（默认 600）：容器空闲保留时长（秒，默认 10 分钟）
• WARM_CONTAINER_CLEANUP_INTERVAL_SECONDS（默认 60）：清理任务运行间隔（秒）

远程浏览器（用户登录入口，可选）：

用途：在前端「设置 -> 远程浏览器」里打开 VNC 画面，手动登录网站。远程浏览器与任务浏览器都只通过 Backend Auth State 持久化登录态；Chrome Profile/cache 仅为容器内临时运行时数据。当前持久化范围为 cookies/localStorage；需要稳定复用登录态的任务建议使用 Playwright MCP 浏览器链路。

• 用户基础浏览器（VNC/noVNC）容器使用 EXECUTOR_IMAGE
• 镜像需包含桌面/VNC/noVNC，并监听 8080（/vnc/）
• BROWSER_BASE_PUBLISHED_HOST：Backend 访问“已映射到宿主机随机端口”的基础浏览器容器时使用的 host（本地裸跑一般是 localhost；主编排同机默认 host.docker.internal；边缘节点必须改为中心 Backend 可达的 worker 主机，并允许访问随机发布端口）。用户浏览器通过 Backend 固定代理 URL 访问远程浏览器。
• BROWSER_BASE_IDLE_TTL_SECONDS：基础浏览器容器空闲回收 TTL（秒，默认 600，即 10 分钟）
• BROWSER_BASE_CLEANUP_INTERVAL_SECONDS：回收任务运行间隔（秒，默认 30）
• BROWSER_BASE_AUTH_STATE_FLUSH_TIMEOUT_SECONDS：停止远程浏览器前同步 Backend Auth State 的超时（秒，默认 10）
• BROWSER_BASE_STOP_TIMEOUT_SECONDS：停止远程浏览器容器的 Docker 超时（秒，默认 3）。Chrome Profile 仅作为运行时缓存，不再阻塞停止。

工作区清理（可选）：

• WORKSPACE_CLEANUP_ENABLED（默认 false）：启用后定期处理超过保留时间的本地活动工作区
• WORKSPACE_CLEANUP_INTERVAL_HOURS（默认 24）：清理任务调度间隔
• WORKSPACE_MAX_AGE_HOURS（默认 24）：活动工作区进入清理流程前的最短保留时间
• WORKSPACE_ARCHIVE_ENABLED（默认 true）：开启时将过期工作区完整归档到 Manager 本地 archive/；关闭时直接删除
• WORKSPACE_ARCHIVE_DAYS（默认 7）：本地完整归档保留天数；归档仍在时，后续运行或首次分叉会自动恢复
• WORKSPACE_IGNORE_DOT_FILES（默认 true）

本地工作区归档包含 SDK 运行数据和隐藏目录，用于同一 Executor Manager 上的会话恢复。对象存储中的工作区导出 ZIP 会过滤运行时私有目录，只用于文件下载和预览，不能替代本地完整归档。

Executor

必需（跑任务时）：

• ANTHROPIC_AUTH_TOKEN：Poco Agent 运行时模型访问 token
• ANTHROPIC_BASE_URL：可选（同上）
• DEFAULT_MODEL：必需（executor/app/core/engine.py 会读取 os.environ["DEFAULT_MODEL"]）
• ANTHROPIC_DEFAULT_HAIKU_MODEL：可选轻量模型别名（由 Executor Manager 注入）
• ANTHROPIC_DEFAULT_OPUS_MODEL / ANTHROPIC_DEFAULT_SONNET_MODEL / ANTHROPIC_MODEL / ANTHROPIC_REASONING_MODEL：由 Executor Manager 注入，统一与 DEFAULT_MODEL 保持一致
• ENABLE_TOOL_SEARCH：Executor 启动时固定设置为 false，覆盖已有同名环境变量，包括容器注入和模型配置自定义环境变量中的值；工具搜索关闭后，连接器等工具会在每次请求中直接加载，不再依赖 ToolSearch
• CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS：由当前生效的后台模型配置反向控制；开启实验性功能时注入 0，关闭时注入 1，默认关闭。设置为 1 时会同时禁用 MCP 工具搜索
• CLAUDE_CODE_ENABLE_TASKS：固定使用新版任务工具（TaskCreate、TaskUpdate、TaskGet、TaskList），默认注入 1
• CLAUDE_CODE_PROMPT_CACHE_TTL / CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL：主 Agent 和子 Agent 的提示缓存时长参数。Executor 启动时均固定设置为 1h，覆盖已有同名环境变量，包括容器注入的值；不是可通过外部环境变量调整的默认值
• 后台模型配置的“高级配置”可按名称和值添加自定义 Executor 环境变量，最多 100 项，每项名称和值均不超过 255 个字符，不额外限制总数据大小。非空变量会在容器启动时最后合并：不存在则新增，已存在则覆盖；平台鉴权、会话身份、工作区和隔离相关变量不允许覆盖
• Poco Agent 运行时兼容开关：由 Executor Manager 注入，通常不需要手动设置；后台模型配置、系统配置和用户设置会覆盖对应行为
• CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS：由后台系统配置 experimental_agent_teams_enabled 控制；启用时注入为 1，关闭时不注入
• WORKSPACE_PATH：工作目录挂载点（默认 /workspace）

可选：

• WORKSPACE_GIT_IGNORE：额外写入到 .git/info/exclude 的忽略规则（逗号/换行分隔）
• Poco Agent 输出上限、归因、后台任务、记忆等兼容开关由系统统一注入；确需覆盖时应先在测试环境验证
• MCP_TIMEOUT：MCP 连接/初始化超时（毫秒，默认 120000；可覆盖）
• MCP_TOOL_TIMEOUT：MCP 工具调用超时（毫秒，默认 120000；可覆盖），必须配置为正整数。后台模型高级配置会在保存时拒绝非法值；直接注入 Executor 的非法值会让任务以明确的配置错误失败。符合条件的即时交互任务注册了定时任务提案工具，或注册了需要用户确认的连接器工具时，Executor 会通过 SDK 子进程环境将该值提高到至少 900000（15 分钟），覆盖 10 分钟确认窗口及后续执行；已有更大值则保留。该 SDK 子进程中的其他 MCP 工具共享此超时，不修改 Executor 全局环境，其他任务仍使用原配置。
• NPM_CONFIG_REGISTRY（默认 https://registry.npmmirror.com）：Executor 容器内 npm 使用的 registry
• VISION_MODEL：供内置工具 understand_image 调用视觉识别接口时使用的模型名（请求认证与地址复用 ANTHROPIC_AUTH_TOKEN / ANTHROPIC_BASE_URL）
• POCO_TEXT_TO_IMAGE_ENABLED / POCO_TEXT_TO_IMAGE_MODEL：由 Executor Manager 根据后台系统配置注入，通常不手动设置。
• POCO_TEXT_TO_IMAGE_API_KEY / POCO_TEXT_TO_IMAGE_BASE_URL：文生图工具优先读取的 OpenAI 兼容图片生成接口配置；POCO_TEXT_TO_IMAGE_BASE_URL 可填根地址（如 https://api.openai.com/v1）或完整 /v1/images/generations 地址。
• OPENAI_API_KEY / OPENAI_BASE_URL：当未配置专用 POCO_TEXT_TO_IMAGE_* 时的兜底来源。
• POCO_PLAYWRIGHT_MCP_MAX_LANES：任务浏览器使用 Playwright MCP 时的并行 subagent lane 上限，通常保持默认值即可。
• POCO_PLAYWRIGHT_MCP_ROUTING_LEDGER：Playwright MCP Router 路由账本路径，通常不手动设置。
• POCO_ASYNC_SUBAGENT_JOIN_TIMEOUT_SECONDS：Executor 在首个结果后等待 SDK 会话进入 idle 的超时时间；生产环境建议不低于默认 7200 秒，避免后台 Agent 和主 Agent 续执行尚未结束时超时。
• POCO_ENABLE_IMAGE_GUARD_MCP：控制是否注入可选工具 repair_image_for_model
• POCO_MODEL_MULTIMODAL_ENABLED：控制是否启用原生多模态图片输入（关闭后注入 understand_image 并走工具链）
• MEMORY_SERVICE_URL：Executor 访问 memory-service 的地址；为空时记忆检索/写入自动禁用
• MEMORY_SERVICE_API_KEY：Executor 访问记忆服务的 Bearer Token（可选）
• MEMORY_DEFAULT_TENANT_ID（独立运行默认 default，Compose 默认 poco）：Executor 请求记忆服务时的默认租户
• MEMORY_SERVICE_TIMEOUT_SECONDS（默认 60）：Executor 调用记忆服务超时（秒）
• MEMORY_SEARCH_TOP_K（保留配置，默认 5）：是 MemoryClient 未收到 top_k 时的默认值；当前自动召回和内置查询工具都会显式传 5，因此单独修改它不会改变这两条内置链路
• MEMORY_SEARCH_MIN_SCORE（默认 0.45）：记忆融合前语义分阈值
• POCO_WORKSPACE_DIFF_MAX_FILES（默认 20）：Workspace 状态中最多为多少个已跟踪变更文件计算 diff，超出时仅保留增删行统计（降低大仓库开销）
• POCO_WORKSPACE_DIFF_MAX_CHARS（默认 120000）：单次 Workspace 状态刷新中 diff 内容总字符预算，超出后自动截断/跳过剩余 diff
• DEBUG / LOG_LEVEL / LOG_TO_FILE 等日志变量（同上）

Frontend

Frontend 通过 Next.js 的 同源 API 代理（/api/v1/* -> Backend）访问后端 HTTP API。浏览器只请求 Frontend 同源地址，Next.js server 优先按运行时 INTERNAL_API_BASE_URL 转发到 Backend；未配置时回退到 BACKEND_URL。需要保留公开 Backend 域名并让内部代理通过容器网络直连时，应同时配置两个变量，避免请求再次经过公开反向代理。

任务浏览器实时预览使用 WebSocket，不走 Next.js HTTP 代理；Backend 会通过 BACKEND_URL 返回浏览器可直接连接的 ws(s) 地址。

运行时（runtime）：

• INTERNAL_API_BASE_URL：Next.js 服务器侧访问 Backend 的内部地址，优先用于 /api/v1/*、/api/v2/* 同源代理及其他服务端 API 请求。Compose 未配置时依次回退到 BACKEND_URL、http://backend:8000
• BACKEND_URL：Backend 公开地址，可配置为浏览器可访问的域名，并作为未配置 INTERNAL_API_BASE_URL 时的兼容回退。兼容旧变量：POCO_BACKEND_URL
• 应用标题由 Backend 的 GET /api/v1/public-config 返回（data.appTitle），由后端变量 APP_TITLE 控制，不再使用 NEXT_PUBLIC_APP_TITLE
• 抚顺新钢铁 SSO 登录入口和注销接口由 Backend 的 GET /api/v1/public-config 返回（data.ssoAuthUrl、data.ssoLogoutUrl），由后端变量 XGT_SSO_BASE_URL 控制
• 建龙集团 SSO 登录入口由 Backend 的 GET /api/v1/public-config 返回（data.jianlongSsoAuthUrl），由后端变量 JIANLONG_SSO_BASE_URL、JIANLONG_SSO_APP_ID、JIANLONG_SSO_APP_SECRET 共同控制
• 建龙集团 SSO 注销接口由 Backend 的 GET /api/v1/public-config 返回（data.jianlongSsoLogoutUrl），由后端变量 JIANLONG_SSO_LOGOUT_URL 控制
• SITE_ANALYTICS_ENABLED（默认 false）：是否启用网站统计脚本。开启值支持 1、true、yes、y、on
• SITE_ANALYTICS_DOMAIN（默认空）：Umami 统计服务根地址，例如 http://10.6.80.164:8856。不要包含 /script.js
• SITE_ANALYTICS_WEBSITE_ID（默认空）：统计站点 ID。仅当统计开关、根地址和站点 ID 都有效时，前端才会加载统计脚本
• SITE_ANALYTICS_PERFORMANCE_ENABLED（默认 false）：是否启用 Umami Web Vitals 采集。开启值支持 1、true、yes、y、on，需要 Umami v3.1.0+
• SITE_ANALYTICS_SENSITIVE_USER_INFO_ENABLED（默认 false）：是否在 Umami identify 中额外上报 username、full_name、department

专业模式/办公模式切换不使用环境变量。管理员在用户管理中设置账号默认模式和 SSO 新用户默认模式，并通过权限菜单中的“模式切换”权限控制用户能否自行切换。账号的模式设置保存在 Backend，跨浏览器和设备生效。

启用网站统计后，前端会在用户登录态确认后调用 Umami identify，默认只上报内部用户 id。仅当 SITE_ANALYTICS_SENSITIVE_USER_INFO_ENABLED=true 时，才会额外上报 username、full_name、department。

注意：以下变量仍是构建期（build-time）生效，会被 Next.js 内联进产物（见 docker/frontend/Dockerfile 的 build args）。

• NEXT_PUBLIC_SESSION_POLLING_INTERVAL：session 轮询间隔（毫秒，默认 2500）
• NEXT_PUBLIC_MESSAGE_POLLING_INTERVAL：消息轮询间隔（毫秒，默认 2500）

容器镜像（Docker Compose）

以下变量用于覆盖 Docker Compose 中各服务的镜像，适合固定正式版本或切换到 testing 测试通道：

• BACKEND_IMAGE：Backend 镜像
• EXECUTOR_MANAGER_IMAGE：Executor Manager 镜像
• EXECUTOR_IMAGE：动态 Executor 和远程浏览器容器使用的镜像
• MEMORY_SERVICE_IMAGE：Memory Service 镜像
• AI_NOTE_WORKER_IMAGE：AI Note Worker 镜像
• FRONTEND_IMAGE：Frontend 镜像

完整沙箱镜像内将 PLAYWRIGHT_BROWSERS_PATH 固定为 /opt/poco/ms-playwright，用于定位构建时预装的 Chromium，避免工作区缓存目录覆盖后重新下载；无需在 .env 中配置。

Postgres（Docker 镜像）

• POSTGRES_DB（默认 poco）
• POSTGRES_USER（默认 postgres）
• POSTGRES_PASSWORD（默认 postgres）
• POSTGRES_PORT（默认 5432，对宿主机映射端口）
• POSTGRES_MAX_CONNECTIONS（默认 300）：Compose 内 PostgreSQL 的最大连接数。所有 Backend 实例的 DATABASE_POOL_SIZE + DATABASE_MAX_OVERFLOW 之和必须低于该值，并为 Memory Service、迁移和运维连接保留容量。

Memory Service（mem0）

当前固定使用 mem0ai[nlp]==2.0.12，主记忆、关键词字段和实体关联由同一个 Mem0 实例管理。升级 SDK 前必须执行 Mem0 SDK 升级门禁，不能只检查 /health。

常用：

• MEMORY_SERVICE_PORT（默认 8005）
• MEM0_ENABLED（默认 true）：是否启用 mem0 引擎
• MEM0_TELEMETRY（默认 false）：是否启用 Mem0 匿名遥测；私有化部署默认不连接 PostHog
• MEM0_VECTOR_PROVIDER（默认 pgvector）
• MEM0_PG_HOST / MEM0_PG_PORT / MEM0_PG_DB：Mem0 使用的 PostgreSQL 地址、端口和数据库
• MEM0_PG_USER / MEM0_PG_PASSWORD：Mem0 使用的 PostgreSQL 账号和密码
• MEM0_PG_COLLECTION（默认 poco_memories）
• MEM0_EMBEDDING_DIMS（默认 1536）：必须与既有 poco_memories.vector 维度一致
• MEM0_HISTORY_DB_PATH（Compose 默认 /data/mem0/history.db）：Mem0 现存记忆的操作轨迹和隐式消息上下文 SQLite 文件；主记忆仍在 PostgreSQL，物理遗忘会同步清理该 ID 的轨迹
• MEM0_CUSTOM_INSTRUCTIONS（默认不设置）：可覆盖事实提取规则；未设置或为空时使用服务内置的跨任务持久记忆规则和正反例
• MEM0_LLM_PROVIDER（默认 openai）
• MEM0_LLM_MODEL（默认 gpt-4o-mini）
• MEM0_LLM_API_KEY（默认回退 OPENAI_API_KEY）：可显式覆盖为独立 key
• MEM0_LLM_BASE_URL（默认回退 OPENAI_BASE_URL，再回退 https://api.openai.com/v1）：可选自定义网关
• OPENAI_API_KEY：当 MEM0_LLM_PROVIDER=openai 且未设置 MEM0_LLM_API_KEY 时的兜底来源
• OPENAI_BASE_URL（默认 https://api.openai.com/v1）：当 MEM0_LLM_PROVIDER=openai 且未设置 MEM0_LLM_BASE_URL 时的兜底来源
• MEM0_EMBEDDER_PROVIDER（默认 openai）
• MEM0_EMBEDDER_MODEL（默认 m3e）
• MEM0_EMBEDDER_API_KEY（独立运行默认空，Compose 默认 sk-aaabbbcccdddeeefffggghhhiiijjjkkk）
• MEM0_EMBEDDER_BASE_URL（独立运行默认空，Compose 默认 http://m3e:6008/v1；需开启 m3e profile 或改为可用外部服务）

检索/写入控制：

• MEMORY_SEARCH_DEFAULT_TOP_K（保留配置，默认 5）：当前运行时代码未读取该设置；/search 请求模型、自动召回和内置查询工具各自使用默认值 5，单独修改该变量不会生效
• MEMORY_SEARCH_MAX_TOP_K（默认 8）
• MEMORY_SEARCH_DEFAULT_MIN_SCORE（默认 0.45）：请求未显式传值时，Memory Service 使用的语义分阈值
• MEMORY_INGEST_MIN_CHARS（默认 10）：只控制写入候选的最小长度，不控制自动召回；自动召回的 10 字符触发门槛当前由 Executor 常量控制
• MEMORY_INGEST_MAX_CHARS（默认 6000）

Executor 的自动召回和内置查询工具当前显式发送 top_k=5，Memory Service 再用 MEMORY_SEARCH_MAX_TOP_K 限制上限；如需调整这两条内置链路的数量，应修改对应 Executor 常量并完成召回回归，不能只改环境变量。Executor 还会显式发送 MEMORY_SEARCH_MIN_SCORE；MEMORY_SEARCH_MIN_SCORE 与 MEMORY_SEARCH_DEFAULT_MIN_SCORE 默认都为 0.45，调整召回阈值时应同步修改，避免 SDK 对话链路和直接接口调用表现不一致。

Mem0 2.0.12 的 PGVector 实现固定使用 PostgreSQL 默认 public schema，因此不再提供 MEM0_PG_SCHEMA。主记忆写入 public.poco_memories，内置实体关联写入 public.poco_memories_entities，无需 Neo4j 配置。

前端本地开发

• INTERNAL_API_BASE_URL：Next.js 服务端 API 代理和服务端请求优先使用的 Backend 地址。本地裸跑可配置为 http://127.0.0.1:8000。
• BACKEND_URL：未配置 INTERNAL_API_BASE_URL 时使用的兼容回退。
• NEXT_PUBLIC_API_BASE_URL：浏览器端 API 基础地址。开发环境可设置为 Backend 地址（例如 http://localhost:8000 或局域网 Backend），让浏览器直连 Backend，避免长连接和大量 API 请求经过 Next.js dev server。Docker/生产环境建议留空，继续使用同源 API 代理。

本地 RustFS（S3 兼容对象存储，可选）

主 Compose 默认使用 registry.cn-hangzhou.aliyuncs.com/ripper/rustfs:latest 作为本地对象存储。外部 S3 可通过 S3 配置接入，现有编排仍包含 RustFS；仓库没有单独的 R2 编排。

如需替换为其他本地 S3 兼容实现，请按镜像参数调整，并保证 Backend/Executor Manager 使用的 S3_* 可用。

• RUSTFS_IMAGE：对象存储镜像（默认 registry.cn-hangzhou.aliyuncs.com/ripper/rustfs:latest）
• S3_PORT（默认 9000）
• S3_CONSOLE_PORT（默认 9001）
• RUSTFS_DATA_DIR：数据目录（默认 ./oss_data，宿主机路径，会 bind mount 到容器的 /data）
• 默认启动会运行 rustfs-data-init，自动创建 /data/${S3_BUCKET}（默认对应 oss_data/poco）并设置可写权限，避免首次启动时对象存储数据目录不存在或不可写。
• S3_ACCESS_KEY / S3_SECRET_KEY：用于访问 S3 API 的凭证（需与 rustfs 配置一致）
• S3_BUCKET：bucket 名称（默认 poco；本地 RustFS 数据目录会默认准备好，外部 S3/R2 仍需提前创建 bucket）