环境变量参考

以下值以根目录和 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`

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_LEGACY_FALLBACK_ENABLED`	`true`	沙箱运行时任务失败时回退到进程内 legacy runner；设为 `false` 则 fail-closed 直接失败
`SANDBOX_FILESYSTEM_ISOLATION_ENABLED`	代码 `false`；镜像/Compose/K8s `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 上的根路径
`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_ARTIFACT_MAX_FILE_SIZE_MB`	`10`	单产物限制
`SANDBOX_ARTIFACT_MAX_TOTAL_SIZE_MB`	`10`	总产物限制

启用文件系统隔离（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`	空	网页搜索内置工具

流式超时

变量	默认	说明
`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 队列划分。

前端构建期

变量	默认	说明
`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_* 在前端构建时注入，修改后必须重新构建前端。

环境变量参考

本页目录