跳转至

部署和维护 / 配置文件

DataFlux Func 先加载镜像内的默认配置文件 config.yaml，再使用用户配置文件、配置片段或环境变量覆盖默认值。用户只需要保存实际需要覆盖的配置项，不要复制或修改完整的内置配置。

1. 用户配置文件

标准容器部署使用 /data/user-config.yaml 作为用户配置文件。宿主机位置及其他配置、数据目录请参考部署和维护 / 数据保存位置 / DataFlux Func 配置。

用户配置文件必须是 YAML 映射，配置项名称区分大小写。例如：

user-config.yaml
1
2
LOG_LEVEL: "INFO"
TIMEZONE : "Asia/Shanghai"

只保存需要覆盖的配置项

不要将镜像内的完整 config.yaml 复制到 user-config.yaml。完整配置中包含以下划线开头的内部配置项，旧版本副本还会覆盖新版本提供的默认值。

SECRET 由标准部署流程随机生成并写入用户配置文件。安装完成后不得修改，否则已有登录令牌、连接器密码、Access Key 等加密数据将无法正常使用。

2. 配置加载和覆盖

2.1 加载优先级

DataFlux Func 按以下顺序加载配置，后加载的值覆盖先加载的同名值：

优先级 配置来源 说明
1 内置 config.yaml 提供完整默认配置和配置项类型
2 include 配置片段 按 include 列表顺序加载；同一路径内按文件名排序加载
3 用户 user-config.yaml 覆盖内置配置和配置片段
4 DFF_ 前缀的环境变量 优先级最高，覆盖前述所有配置来源

映射和列表采用整项覆盖，不会递归合并。例如，在用户配置文件中配置 OIDC_ROLE_MAP 会替换默认映射，而不是向默认映射中追加内容。

2.2 配置片段

于 8.0.23 版本新增

内置配置文件 config.yaml 默认依次包含以下配置片段：

YAML
1
2
3
include:
  - "@/conf.d/*.yaml"
  - "/data/conf.d/*.yaml"
  • @/ 表示内置配置文件所在目录。该目录用于镜像随附的配置片段，不应在运行容器内直接修改。
  • /data/conf.d/*.yaml 用于用户配置片段。标准单机部署对应的宿主机目录为 {安装目录}/data/conf.d/。
  • include 项可以是单个 .yaml 文件、目录或通配符；** 可以匹配多级目录。只加载扩展名为 .yaml 的文件，不加载 .yml 文件。
  • 同一匹配结果按路径名称排序。建议使用 10-database.yaml、20-web.yaml 等带数字前缀的文件名明确覆盖顺序。

include 在用户配置文件之前解析，因此在 user-config.yaml 中重新配置 include 不会改变本次加载的片段。如需替换默认片段列表，应使用环境变量 DFF_include；一般部署直接使用默认的 /data/conf.d/*.yaml 即可。

2.3 环境变量

已有配置项可以使用 DFF_ 加配置项名称进行覆盖：

配置项 环境变量 示例值
LOG_LEVEL DFF_LOG_LEVEL "INFO"
REDIS_USE_TLS DFF_REDIS_USE_TLS "true"
PROXY_HOSTNAME_LIST DFF_PROXY_HOSTNAME_LIST "api.example.com,files.example.com"

环境变量中的空字符串或纯空白值会被忽略。程序会按内置配置项的类型转换环境变量值：布尔值建议使用 "true" 或 "false"，列表可以使用逗号或空格分隔，映射可以使用逗号分隔的 "key=value"。复杂的列表或映射建议写入 YAML 配置文件，避免环境变量转义产生歧义。

在 Helm 部署中通过 Secret 注入环境变量的方法，请参考部署和维护 / 安装部署 / Helm 部署 / 环境变量扩展支持 Secret 引用。

3. 生效和排查

配置由 Server、Worker 和 Beat 分别在启动时加载。修改文件或环境变量后，必须按照部署和维护 / 升级和重启 / 重启系统重启整个 DataFlux Func，不要只重启部分服务。

多副本部署还必须保证各服务读取到相同的用户配置、配置片段和环境变量，具体要求请参考部署和维护 / 安装部署 / 高可用部署。

重启后，可以在「管理 / 关于 / 系统工具」中点击【获取系统报告】，通过 CONFIG 查看 Server 的生效值，通过 CONFIG_SOURCE 查看各配置项来自内置配置、配置片段、用户配置文件还是环境变量。报告中的敏感值会被遮蔽。

如果服务在修改配置后无法启动，请先检查 YAML 缩进、冒号和数据类型，再参考故障排查 / 容器没有正常运行检查容器日志。

4. 相关专题

以下内容已有独立文档，本文不重复说明：

主题 相关配置 文档
配置、日志、备份和资源位置 CONFIG_FILE_PATH、LOG_FILE_PATH、AUTO_BACKUP_DB_FOLDER_PATH、RESOURCE_ROOT_PATH 部署和维护 / 数据保存位置
数据库备份及 MySQL、Redis 迁移 AUTO_BACKUP_DB_*、MYSQL_*、REDIS_* 部署和维护 / 备份和迁移
OIDC 登录 WEB_SERVER_BASE_URL、DISABLE_BUILTIN_SIGN_IN、OIDC_* 部署和维护 / OIDC 登录 / 完整配置项
固定响应头、CORS 和 IP 过滤 FIXED_HTTP_RESPONSE_HEADER_MAP、FIXED_CORS_RULE_LIST、FIXED_IP_ADDRESS_FILTER_RULE_LIST 界面和操作 / 系统设置
Helm 环境变量和 Secret DFF_* 部署和维护 / 安装部署 / Helm 部署 / 环境变量扩展支持 Secret 引用

5. 常用配置项

下表中的默认值来自当前内置配置文件 config.yaml。标准部署脚本或 Helm 配置可能进一步覆盖部分值，应以用户配置和系统报告中的生效值为准。

未列出的配置项不要随意修改

以下仅列出常用且可以直接调整的配置项。以下划线开头的内部配置项，以及本页和相关专题未说明的配置项，请勿随意修改。

5.1 基础和 Web 服务

配置项 内置默认值 说明
SECRET "your_secret" 登录令牌和敏感数据的加密密钥；标准部署时随机生成
安装完成后不得修改，也不得使用内置占位值
TIMEZONE "Asia/Shanghai" DataFlux Func 使用的时区
WEB_SERVER_BASE_URL "" 浏览器公开访问 DataFlux Func 的基地址；留空时按请求地址处理，启用 OIDC 时必须配置，详情见 OIDC 登录
WEB_BIND "0.0.0.0" Web 服务绑定 IP；"0.0.0.0" 表示监听所有网卡，"127.0.0.1" 表示仅监听本机
WEB_PORT 8088 Web 服务绑定端口
WEB_CLIENT_DISABLED false 是否禁用内置 Web 客户端；启用后不再提供 / 和 /client-app 路由，API 仍可使用
WEB_ERROR_PAGE "html" 普通 Web 错误响应格式，可选 "html"、"json"、"text"、"simple"；"simple" 仅返回 HTTP 状态
WEB_TLS_ENABLED false 是否由 DataFlux Func Web 服务直接启用 TLS
WEB_TLS_KEY_PATH "/etc/web/tls.key" TLS 私钥路径，必须是 Server 容器内可读取的文件
WEB_TLS_CERT_PATH "/etc/web/tls.cert" TLS 证书路径，必须是 Server 容器内可读取的文件
WEB_CORS_CREDENTIALS true 命中允许的 CORS 规则时，是否允许请求携带凭据；规则配置见界面和操作 / 系统设置 / 跨域资源共享
PROXY_HOSTNAME_LIST null /api/v1/do/proxy 允许访问的精确主机名列表；null 表示不启用代理
API_DOC_REQUIRE_SIGNIN true 访问 /api 接口文档时是否要求登录

5.2 日志

配置项 内置默认值 说明
LOG_LEVEL "ERROR" 日志等级，可选 "ALL"、"DEBUG"、"INFO"、"WARNING"、"ERROR"、"NONE"；Helm 配置模板默认使用 "WARNING"
LOG_FILE_PATH "/data/logs/dataflux-func.log" 日志文件路径，必须使用绝对路径；配置为空字符串时不写入日志文件
LOG_FILE_FORMAT "text" 日志文件格式，可选 "text"、"json"
LOG_FILE_LIMIT 168 最多保留的历史日志文件数量
LOG_FILE_SIZE_LIMIT "5GB" 历史日志文件的总大小上限
LOG_CONSOLE_COLOR false 控制台日志是否着色；文件日志不会着色
ENABLE_APP_LEVEL_LOG false 是否记录数据库、Redis 等应用层访问日志；排查问题时可临时启用，日志量会增加
ENABLE_UNDERLYING_LOG false 是否记录 Worker 底层组件日志；排查问题时可临时启用，日志量会增加

日志目录及宿主机映射请参考部署和维护 / 数据保存位置 / DataFlux Func 日志。

5.3 数据库

配置项 内置默认值 说明
DB_ENGINE "mysql" 数据库引擎，可选 "mysql"、"postgresql"
MYSQL_HOST "127.0.0.1" MySQL 主机地址
MYSQL_PORT 3306 MySQL 端口
MYSQL_USER "root" MySQL 用户
MYSQL_PASSWORD "" MySQL 密码；标准单机部署使用内置 MySQL 时随机生成
MYSQL_DATABASE "dataflux_func" MySQL 数据库名
POSTGRESQL_HOST "127.0.0.1" PostgreSQL 主机地址；仅在 DB_ENGINE 为 "postgresql" 时使用
POSTGRESQL_PORT 5432 PostgreSQL 端口
POSTGRESQL_USER "postgres" PostgreSQL 用户
POSTGRESQL_PASSWORD "" PostgreSQL 密码
POSTGRESQL_DATABASE "dataflux_func" PostgreSQL 数据库名

标准单机部署脚本会将 MYSQL_HOST 配置为内置服务名 "mysql"。切换数据库前应先完成数据迁移，并让所有服务同时使用相同的数据库配置。

5.4 Redis

配置项 内置默认值 说明
REDIS_HOST "127.0.0.1" Redis 主机地址
REDIS_PORT 6379 Redis 端口
REDIS_DATABASE 5 Redis 数据库编号
REDIS_USER "" Redis ACL 用户；不需要用户名时留空
REDIS_PASSWORD "" Redis 密码；标准单机部署的内置 Redis 默认留空
REDIS_USE_TLS false 是否使用 TLS 连接 Redis
REDIS_AUTH_TYPE "default" 认证方式，可选 "default"、"aliyun"；阿里云 Redis 使用 "aliyun"
REDIS_MODE "auto" 连接模式，可选 "auto"、"singleton"、"cluster"；"auto" 会探测 Redis 类型，部署拓扑限制见高可用部署

标准单机部署脚本会将 REDIS_HOST 配置为内置服务名 "redis"。MySQL、PostgreSQL 和 Redis 的主机、用户、密码及数据库名中不要混入不可见空白字符；程序检测到时会输出配置警告。

5.5 登录和访问安全

配置项 内置默认值 说明
DISABLE_SIGN_IN false 是否禁用内置、集成和 OIDC 登录；不会控制外部用户访问
DISABLE_BUILTIN_SIGN_IN false 是否禁用内置用户名密码登录；启用前必须确认其他登录方式可用，OIDC 场景见 OIDC 登录
DISABLE_INTEGRATED_SIGNIN false 是否禁用集成登录
DISABLE_OUTER_USER_ACCESS false 是否禁用外部用户访问
PROOF_OF_WORK_DIFFICULTY 4 登录接口工作量证明难度，范围为 0 到 6；0 表示禁用
BAD_SIGNIN_TEMP_LOCK_ACTIVE_COUNT 10 同一用户名连续密码错误达到此次数时开始临时锁定
BAD_SIGNIN_TEMP_LOCK_TIMEOUT_MAX 900 临时锁定和连续错误计数的最长保留时间，单位为秒

OIDC 的 Issuer、客户端、Claim 和角色同步等配置统一参考部署和维护 / OIDC 登录，不要只根据配置项名称自行拼接回调地址或角色规则。