环境变量参考

以下值以根目录和 deploy/.env.example、后端 Settings 为准。Compose 内部地址使用 api、db、redis 和 qdrant；源码开发通常使用 localhost。

配置分三层：环境变量控制启动级配置（连接、密钥、队列、沙箱等）；数据库 SiteSetting 管理运行时设置（SMTP、SSO、会话超时、上传限制、出站网络白名单等）；LLM 厂商的 Key 与 base_url 存数据库而非环境变量。

应用与网络

变量	默认/示例	说明
`PROJECT_NAME`	`Clouisle`	站点/应用名称
`SECRET_KEY`	示例占位	JWT 签名和部分内部签名，生产必换
`TIMEZONE`	`Asia/Shanghai`	时区
`ALGORITHM`	`HS256`	JWT 签名算法，可选 `HS256`/`HS384`/`HS512`
`ACCESS_TOKEN_EXPIRE_MINUTES`	`11520`（8 天）	JWT fallback 令牌有效期；有效会话默认由站点设置 `session_timeout_days`（30 天）控制
`API_BASE_URL`	Compose `http://api:8000`	服务端 API 地址
`API_V1_STR`	`/api/v1`	后端挂载全部路由的路径前缀；必须与前端构建期 `NEXT_PUBLIC_API_URL` 及 Ingress/代理转发的 `/api/v1` 保持一致
`PUBLIC_API_URL`	空	需要绝对公开 URL 时使用
`FRONTEND_URL`	`http://localhost:3000`	公开前端/SSO 回调基址
`BACKEND_CORS_ORIGINS`	`["http://localhost:3000"]`	允许的前端 Origin；接受 JSON 数组或逗号分隔列表
`NEXT_PUBLIC_API_URL`	Compose `/api/v1`	浏览器 API 基路径
`BACKEND_INTERNAL_URL`	`http://localhost:8000`	前端服务端访问 API；Compose 内为 `http://api:8000`
`OBSERVABILITY_INSTANCE_ID`	空	API 容器/Pod 实例标识，用于可观测性的实例发现；空时取主机名。同一实例内所有 Gunicorn 进程必须共用同一值
`OBSERVABILITY_INSTANCE_NAME`	空	实例显示名；空时回退到实例 ID

OBSERVABILITY_INSTANCE_ID 只在同一主机上有多个部署、主机名会冲突时才需要显式设置。API 实例每 10 秒上报一次，30 秒未更新视为 stale、60 秒视为 offline。

API_V1_STR（默认 /api/v1）是后端挂载全部路由的前缀：/health、/openapi.json、/embed/*、/admin/* 等都在它之下。它必须与前端构建期 NEXT_PUBLIC_API_URL（前端镜像默认 /api/v1）和 Ingress/反向代理转发的路径一致；只改其中一处会让浏览器请求或 SSR 取数 404。它不是下一个环境变量的替代品——NEXT_PUBLIC_API_URL 是浏览器可访问的相对基路径，BACKEND_INTERNAL_URL 只用于 Next.js 服务端，三者职责不同。

单文件 K8s manifest 与 Helm 默认的 frontend 工作负载不注入 BACKEND_INTERNAL_URL，因此 SSR 回退到代码默认 http://localhost:8000；需要 SSR 取数时显式设置为 http://api:8000。

数据依赖

变量	Compose 默认	说明
`POSTGRES_SERVER`	`db`	PostgreSQL 主机
`POSTGRES_PORT`	`5432`	PostgreSQL 端口
`POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB`	`postgres` / 空 / `clouisle`	数据库凭据；config 默认密码 `password`，Compose 未设置 `POSTGRES_PASSWORD` 时启动即失败（必填）
`DATABASE_URL`	自动拼接	非空时优先于分字段
`REDIS_HOST` / `REDIS_PORT`	`redis` / `6379`	Redis 连接
`REDIS_PASSWORD`	空	生产建议设置
`QDRANT_URL`	`http://qdrant:6333`	向量库地址
`QDRANT_API_KEY`	空	生产建议设置
`VECTOR_BACKEND`	`qdrant`	向量后端
`QDRANT_COLLECTION_PREFIX`	`kb_dim`	集合名前缀
`QDRANT_DISTANCE`	`Cosine`	距离函数

Celery broker 与结果后端由 REDIS_* 派生（broker redis://…/0、backend redis://…/1），无独立的 REDIS_URL/CELERY_BROKER_URL/CELERY_RESULT_BACKEND 变量。

内部网关与 Sandbox

变量	默认	说明
`INTERNAL_API_TOKEN`	空（Compose/K8s 必填）	Worker 访问 API 文件网关，必须与 API 共享
`INTERNAL_API_TOKEN_FILE`	空	从文件读取内部 Token
`API_INTERNAL_BASE_URL`	空	`UPLOAD_STORAGE_MODE=remote` 时 Worker 经此访问上传网关；Compose 设 `http://api:8000`
`UPLOAD_STORAGE_MODE`	`local`	取值 `local`/`remote`；Compose/K8s 的 Worker 与 Sandbox Worker 设 `remote` 且不挂 uploads 卷
`SANDBOX_ARTIFACT_UPLOAD_BASE_URL`	Compose `http://api:8000`	Sandbox 产物上传地址
`SANDBOX_ARTIFACT_UPLOAD_API_KEY`	空	可替代默认内部签名
`SANDBOX_RUNTIME_ENABLED`	`true`	启用沙箱运行时
`SANDBOX_FILESYSTEM_ISOLATION_ENABLED`	`true`（代码默认，官方部署同样 `true`）	在 Bubblewrap 挂载命名空间内执行可执行载荷
`SANDBOX_FILESYSTEM_ISOLATION_BINARY`	代码 `bwrap`；镜像/Compose/K8s `/usr/bin/bwrap`	Bubblewrap 可执行文件名或绝对路径
`SANDBOX_WORKER_CONCURRENCY`	`1`	Sandbox Worker 并发槽位数
`SANDBOX_WORKSPACE_ROOT`	`/tmp/clouisle-sandbox/jobs`	任务和会话目录在 Worker 上的根路径；官方部署统一为 `/var/lib/clouisle/sandbox/jobs`
`SANDBOX_CHECKPOINT_ROOT`	空	会话检查点目录；空时为工作区根目录的同级 `checkpoints`。官方部署显式设为 `/var/lib/clouisle/sandbox/checkpoints`，且必须位于工作区之外
`SANDBOX_WORKER_ID`	空	逻辑 Worker ID；空时首次启动生成并写入保留磁盘。改动值会与磁盘身份冲突并拒绝启动，同一 ID 不得跨不同磁盘
`SANDBOX_NODE_ID`	空	节点标识；K8s 用 `spec.nodeName` 注入，其他环境默认主机名
`SANDBOX_WORKER_INSTANCE_ID`	空	本次进程的实例 ID；由 Worker 监督进程分配
`SANDBOX_WORKER_HEARTBEAT_SECONDS`	`5`	心跳间隔（秒）
`SANDBOX_WORKER_HEARTBEAT_TTL_SECONDS`	`20`	心跳过期时间（秒），必须大于心跳间隔，否则启动即报错
`SANDBOX_WORKER_RECOVERY_SECONDS`	`30`	Worker 失联后开始恢复会话的等待时间（秒）
`SANDBOX_RECOVERY_POLL_SECONDS`	`0.5`	恢复轮询间隔（秒）
`SANDBOX_SESSION_MAX_RESETS`	`1`	单个会话允许的检查点恢复次数
`SANDBOX_SUPERVISOR_RESTART_SECONDS`	`1`	监督进程重启子进程前的等待（秒）
`SANDBOX_SUPERVISOR_MAX_RESTARTS`	`3`	监督进程最大重启次数
`SANDBOX_WORKSPACE_IDLE_SECONDS`	`900`	工作区空闲多久后清理（秒）
`SANDBOX_CHECKPOINT_TIMEOUT_SECONDS`	`120`	单轮检查点保存超时（秒）
`SANDBOX_MAX_DISK_MB`	`8192`	沙箱最大磁盘
`SANDBOX_SESSION_TTL_HOURS`	`24`	会话保留
`SANDBOX_SESSION_CLEANUP_BATCH_SIZE`	`100`	会话清理每批数量
`SANDBOX_DEFAULT_PYTHON_BINARIES`	`/usr/local/bin/python3`、`/usr/bin/python3`、`/bin/python3`	沙箱 Python 解释器候选路径
`SANDBOX_RESULT_TTL_SECONDS`	`86400`	结果保留
`SANDBOX_PACKAGE_INSTALL_TIMEOUT_SECONDS`	`300`	pip/npm 安装超时（秒），取值 `1`–`3600`
`SANDBOX_TASK_MEMORY_MB`	`1024`	单个任务内存上限（MB），取值 `1`–`8192`
`SANDBOX_TASK_MAX_FILE_SIZE_MB`	`1024`	单个任务可写文件大小上限（MB），取值 `1`–`8192`
`SANDBOX_TASK_MAX_OPEN_FILES`	`256`	单个任务可打开文件数，取值 `32`–`4096`
`SANDBOX_TASK_MAX_CPU_SECONDS`	`600`	单个任务 CPU 时间上限（秒），取值 `1`–`3600`
`SANDBOX_ARTIFACT_MAX_FILE_SIZE_MB`	`10`	单产物限制
`SANDBOX_ARTIFACT_MAX_TOTAL_SIZE_MB`	`10`	总产物限制

SANDBOX_WORKER_ID 与检查点目录共同决定会话亲和：同一会话的下一次执行、检查点和过期清理都会路由回它首次落地的 worker_id。因此工作区与检查点必须放在持久磁盘上；节点或磁盘丢失后这些会话无法在别的节点上恢复。

启用文件系统隔离（SANDBOX_FILESYSTEM_ISOLATION_ENABLED=true）后，项目提供的部署以 root + CAP_SYS_ADMIN 运行 sandbox-worker，用户命名空间创建走特权路径，无需修改宿主 sysctl。仅当自定义部署保持 Worker 非 root 时，才依赖宿主内核允许非特权用户命名空间，否则所有沙箱任务报 bwrap: No permissions to create new namespace：Ubuntu 23.10+ 需 sysctl -w kernel.apparmor_restrict_unprivileged_userns=0，Debian 需 sysctl -w kernel.unprivileged_userns_clone=1（宿主/节点级设置，Kubernetes 中需对每个节点生效）。完整说明见代码沙箱 → 宿主内核要求。

检索与外部服务

变量	默认	说明
`RETRIEVAL_HYBRID_KILL_SWITCH`	`false`	紧急强制向量检索
`RETRIEVAL_SHADOW_ENABLED`	`false`	混合检索影子运行
`RAG_QUERY_CONTEXTUALIZATION_ENABLED`	`false`	查询上下文改写
`RAG_QUERY_CONTEXTUALIZATION_TIMEOUT_SECONDS`	`2.0`	查询改写超时（秒）
`TAVILY_API_KEY`	空	仅用于升级时的站点搜索配置迁移：站点里尚无 Tavily 密钥时用它初始化一次，写入后即加密保存在数据库；运行时不再读取该变量

网页搜索（Tavily、Bocha、SearXNG、DeepSeek）的密钥、启用项与默认引擎都由站点级搜索配置管理：保存在全局 ToolConfig（tool_name=web_search、team_id=NULL）的加密 credentials 中，只写不回显，不是环境变量；BOCHA_API_KEY、SEARXNG_AUTH_TOKEN、DEEPSEEK_API_KEY 也没有对应的启动环境变量。入口与接口见工具 API → 站点网页搜索配置。

流式超时

变量	默认	说明
`STREAM_GLOBAL_TIMEOUT`	`3600`	全局流式超时（秒）
`STREAM_GLOBAL_TIMEOUT_WITH_TOOLS`	`5400`	带工具的全局超时（秒）
`STREAM_HEARTBEAT_INTERVAL`	`15`	心跳间隔（秒）
`STREAM_IDLE_TIMEOUT`	`180`	空闲超时（秒）
`STREAM_HTTP_CONNECT_TIMEOUT`	`10`	上游连接超时（秒）
`STREAM_HTTP_READ_TIMEOUT`	`200`	上游读取超时（秒）
`STREAM_HTTP_REASONING_READ_TIMEOUT`	`300`	推理内容读取超时（秒）
`STREAM_HTTP_WRITE_TIMEOUT`	`10`	上游写入超时（秒）
`STREAM_TOOL_TIMEOUT_HTTP`	`30`	HTTP 工具超时（秒）
`STREAM_TOOL_TIMEOUT_CODE`	`60`	代码工具超时（秒）
`STREAM_TOOL_TIMEOUT_MCP`	`60`	MCP 工具超时（秒）
`STREAM_TOOL_TIMEOUT_DOWNLOAD`	`60`	下载工具超时（秒）

Celery 与后台任务

变量	默认	说明
`CELERY_VISIBILITY_TIMEOUT_SECONDS`	`3600`	Celery 任务可见性超时（秒）
`KB_PROCESSING_RECOVERY_AFTER_SECONDS`	`600`	知识库处理卡死后的恢复等待时间（秒）
`DB_AGGREGATE_CONCURRENCY`	`4`	单个请求可同时持有的聚合查询上限，必须 `> 0`

DB_AGGREGATE_CONCURRENCY 限制的是一个 API 进程内所有聚合 fan-out 共用的信号量，用于防止单次工作台统计请求占满 Tortoise 共享连接池（默认 maxsize=5）后把自己的其余查询排在自己后面。仪表盘、Agent 与工作流统计出现连接等待或超时时可下调；把连接池整体调大不是等价方案，默认部署约 17 个进程 × 池，PostgreSQL max_connections 为 100。取值与验证方法见数据库维护与索引调优。

Worker 消费的队列不是环境变量，而是启动命令的 -Q 参数，见部署架构 → Celery 队列划分。

消息集成

飞书与微信 iLink 没有独立进程，也没有 receiver 专用的环境变量：飞书长连接由消费 agent 队列的 Worker 持有单例接收器，微信轮询由 default 队列的周期任务驱动。需要调整的是轮询规模：

变量	默认	说明
`WECHAT_POLL_BATCH_SIZE`	`64`	单个轮询批次最多认领的绑定数，取值 `1`–`512`
`WECHAT_POLL_CONCURRENCY`	`16`	一个批次内并发轮询的绑定数，取值 `1`–`128`
`WECHAT_POLL_MAX_BATCHES`	`8`	固定批次数（PostgreSQL 中的可复用槽位），取值 `1`–`128`；同时决定最多有多少个批次任务在途

三个值共同限定并发上界：批次数 × 批大小 = 单轮最多处理的绑定数。槽位与认领记录存在 PostgreSQL，所以增加 WECHAT_POLL_MAX_BATCHES 在 Worker 运行期间是安全的；调得过高的代价是同时占用的数据库连接和微信请求配额。批次在 30 秒处截止，认领 90 秒后可由其他 Worker 接管。排障步骤见故障排查，用户侧说明见微信 iLink。

飞书的 App ID/Secret、接收方式（HTTP 回调或长连接）与回调密钥都存在数据库的集成设置里，不是环境变量；修改后无需重启 Worker。

前端构建期

变量	默认	说明
`NEXT_PUBLIC_APP_VERSION`	`0.0.0-dev`	前端显示的应用版本（构建期 ARG）
`NEXT_PUBLIC_BUILD_DATE`	`unknown`	前端显示的构建时间
`DEV_ALLOWED_ORIGINS`	空	开发服务器 LAN 来源；生产构建忽略

GitHub Discussions 反馈

文档页底部的反馈表单会把同一页面的反馈聚合到 clouisle/clouisle-docs 的 GitHub Discussion。仓库必须启用 Discussions，并创建名称为 Docs Feedback 的 Discussion category。

变量	默认	说明
`GITHUB_APP_ID`	空	GitHub App 的 App ID。该 App 需要安装到 `clouisle/clouisle-docs`，并拥有 Discussions 的读写权限。
`GITHUB_APP_PRIVATE_KEY`	空	GitHub App 私钥。多行私钥可直接填写，或将换行写成 `\\n`。只在服务端配置，不能使用 `NEXT_PUBLIC_` 前缀。

反馈动作会校验页面来源、路径和消息长度；未配置 GitHub 凭据时提交会失败，不会静默丢弃反馈。

修改服务端环境变量后重启对应服务。NEXT_PUBLIC_* 在前端构建时注入，修改后必须重新构建前端。

环境变量参考

本页目录