From 6417e802a2b10ddf44a73d073d4923748175f906 Mon Sep 17 00:00:00 2001 From: kuse <3133746534@qq.com> Date: Wed, 23 Sep 2026 23:07:50 +0800 Subject: [PATCH] docs(configuration): document runtime environment variables in English (#5774) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs(configuration): document runtime environment variables in English * docs(configuration): correct env vars flagged in review `LOG_LEVEL` is not read by DeerFlow: log verbosity comes from `log_level` in `config.yaml`. `DEER_FLOW_ROOT` is not a process variable either — it is a host-side value that only `docker/docker-compose-dev.yaml` interpolates, and it has no fallback there, so `scripts/docker.sh` supplies one for the `make docker-*` wrapper only. Both rows are removed, and the table now lists only variables the process actually reads: `DEER_FLOW_PROJECT_ROOT`, `DEER_FLOW_HOME`, `DEER_FLOW_CONFIG_PATH`, `DEER_FLOW_SKILLS_PATH` and `AUTH_JWT_SECRET`. The config-file home for log verbosity and the host-side home for `DEER_FLOW_ROOT` are cross-referenced instead. The zh page carried the same two incorrect rows; it is corrected the same way so both locales agree. * docs(configuration): scope the project-root rule to the variable that uses it The blanket claim that relative path values resolve against `DEER_FLOW_PROJECT_ROOT` is false for two rows in this table. At this head: - `runtime_paths.runtime_home()` resolves a relative `DEER_FLOW_HOME` with `Path(env_home).resolve()`, and `config/paths.py` resolves the state directory the same way, so both land under the process working directory. - `AppConfig.resolve_config_path()` builds `Path(os.getenv("DEER_FLOW_CONFIG_PATH"))` directly, so a relative value is taken from the working directory as well. `DEER_FLOW_SKILLS_PATH` is the only one that goes through `resolve_path()`, the single project-root-aware helper (`base or project_root()`). The prose now names that variable, states that the other two are used as given, and asks operators to set them to absolute paths so writable state and the loaded config file land where they expect. The `DEER_FLOW_HOME` row repeats the absolute-path requirement, `DEER_FLOW_SKILLS_PATH` records the project-root rule, and the `DEER_FLOW_PROJECT_ROOT` row no longer implies it governs relative runtime paths in general. The zh page carries the same correction. --- .../content/en/application/configuration.mdx | 31 +++++++++++++++++++ .../content/zh/application/configuration.mdx | 24 ++++++++++---- 2 files changed, 49 insertions(+), 6 deletions(-) diff --git a/frontend/src/content/en/application/configuration.mdx b/frontend/src/content/en/application/configuration.mdx index c33a178a9..5140f38da 100644 --- a/frontend/src/content/en/application/configuration.mdx +++ b/frontend/src/content/en/application/configuration.mdx @@ -319,6 +319,37 @@ When the config schema changes, `config_version` is bumped. To merge new fields make config-upgrade ``` +## Runtime environment variables + +DeerFlow reads these from its own process environment — via a `.env` file, the +Docker environment, or the shell. + +Only `DEER_FLOW_SKILLS_PATH` resolves a relative value against +`DEER_FLOW_PROJECT_ROOT`. `DEER_FLOW_HOME` and `DEER_FLOW_CONFIG_PATH` are used +as given, so a relative value resolves against the process working directory — +set both to absolute paths so writable state and the loaded config file land +where you expect them. + +| Variable | Default | Description | +| ------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------- | +| `DEER_FLOW_PROJECT_ROOT` | current working directory | Root for project-relative defaults, including the `skills` lookup | +| `DEER_FLOW_HOME` | `/.deer-flow` | Writable directory for runtime state (threads, uploads); use an absolute path | +| `DEER_FLOW_CONFIG_PATH` | auto-discovered under project root | Absolute path to `config.yaml` | +| `DEER_FLOW_SKILLS_PATH` | `/skills` | Directory containing skill definitions (a relative value resolves against the project root) | +| `AUTH_JWT_SECRET` | auto-generated | JWT signing secret for the Gateway | + +Log verbosity is not an environment variable — set `log_level` in `config.yaml` +instead (`debug`, `info`, `warning`, or `error`; default `info`). See +[Harness Configuration](/docs/harness/configuration) for the module reference. + +`DEER_FLOW_ROOT` is a host-side variable for the Docker Compose dev stack only; +the DeerFlow process does not read it. See the +[Deployment Guide](/docs/application/deployment-guide). + +When `AUTH_JWT_SECRET` is unset, DeerFlow generates a secret on first start and +persists it to `.jwt_secret`, so sessions survive restarts. Set it explicitly in +production to keep a stable, secret value. + /.deer-flow` | 运行状态的可写目录（线程、上传文件）；建议使用绝对路径 | +| `DEER_FLOW_CONFIG_PATH` | 在项目根目录下自动发现 | `config.yaml` 的绝对路径 | +| `DEER_FLOW_SKILLS_PATH` | `<项目根>/skills` | 技能定义所在目录（相对值基于项目根解析） | +| `AUTH_JWT_SECRET` | 自动生成 | Gateway 的 JWT 签名密钥 | + +日志级别不是环境变量——请在 `config.yaml` 中设置 `log_level`（`debug`、`info`、`warning` 或 `error`，默认 `info`）。模块参考见 [Harness 配置](/docs/harness/configuration)。 + +`DEER_FLOW_ROOT` 仅是 Docker Compose 开发栈使用的主机侧变量，DeerFlow 进程不会读取它，详见[部署指南](/docs/application/deployment-guide)。 + +当 `AUTH_JWT_SECRET` 未设置时，DeerFlow 会在首次启动时生成一个密钥并持久化到 `.jwt_secret`，重启后会话仍然有效；生产环境请显式设置一个稳定的随机值。