Flipt 配置参数详解

系统讲解 Flipt v2 双层配置体系：服务器配置 flipt.yaml 的加载优先级、storage/environments/credentials/authentication 等核心块与默认值，以及声明式 features.yaml 的 flag/variant/segment/rule/rollout 结构与评估上下文，附生产配置骨架与配置类排障速查表。

FliptGoDevOps工程运维自动化2026/10/28

Flipt 配置参数详解

Flipt v2 的"配置"分两个层次，务必区分：

  1. 服务器配置（本文第一至五部分）：决定 Flipt 进程自身如何运行——监听端口、日志、存储后端、环境映射、认证方式等，载体是 flipt.yaml/config.yml（官方默认路径 /etc/flipt/config/default.yml）；
  2. 声明式特性状态（本文第六部分）：决定"有哪些开关、怎么灰度"，载体是 Git 仓库中的 features.yaml（schema version 1.6），它是 Flipt 评估的数据源。

本文基于 Flipt v2.14.1 撰写，参数结构以官方文档（docs.flipt.io/v2/configuration）与官方默认配置模板为据，实验环境为 Docker Compose 单机形态（详见《Flipt Docker Compose 部署实战》）。

一、配置加载机制与优先级

1.1 查找顺序

flipt server 启动时按以下顺序定位配置文件（官方文档明确）：

  1. --config 标志显式指定（如 flipt server --config /opt/flipt/config.yml）；
  2. {{ USER_CONFIG_DIR }}/flipt/config.yml（USER_CONFIG_DIR 取决于操作系统与用户，Linux root 用户为 /root/.config/flipt/config.yml）；
  3. /etc/flipt/config/default.yml（Docker 镜像内置路径，也是默认生效路径）。

实测注记：镜像内置的 default.yml 是一份全注释的默认值模板（首行带 # yaml-language-server: $schema=... 的 schema 引用），即不提供任何自定义配置时 Flipt 也能按模板默认值启动。此外 flipt config init 子命令可交互式生成一份配置文件（空回车采用默认值，root 用户生成于 /root/.config/flipt/config.yml）。

1.2 环境变量替换与 Secret 引用

配置文件支持两类动态注入，这是生产环境隐藏敏感信息的主要手段：

  • 环境变量替换：${env:VARIABLE_NAME}，例如：

    authentication:
  required: ${env:FLIPT_CUSTOM_AUTH_REQUIRED}

    官方特别强调：v1 的 ${VARIABLE_NAME} 简写语法在 v2 不再支持，必须写显式的 ${env:...} 前缀。

  • Secret 引用：${secret:provider:key} 形态，配合 secrets 提供方使用，例如文件提供方 ${secret:file:ci-token} 映射 /etc/flipt/secrets/ci-token，也支持 HashiCorp Vault（${secret:vault:flipt/tokens:ci-token}）、AWS Secrets Manager、GCP Secret Manager、Azure Key Vault（后四类为 Pro 特性）。

1.3 Schema 校验

官方为服务器配置提供 JSON Schema 与 Cue Schema（仓库 config/flipt.schema.json 与 config/flipt.schema.cue），可用于编辑器智能提示与 CI 校验。默认模板首行的 yaml-language-server 注释即利用了这一点——在支持 YAML Language Server 的编辑器中打开配置即可获得字段级校验。

二、服务器配置（flipt.yaml）顶层结构总览

以官方默认模板为基准，v2 配置文件的顶层块如下：

顶层块作用默认值要点
log日志级别/输出/编码level: INFO、encoding: console、grpc_level: ERROR、file: 空（不落文件）
uiWeb 控制台开关与主题enabled: true、default_theme: system
cors浏览器跨域策略enabled: false、allowed_origins: "*"（启用后建议收敛来源）
cache评估结果缓存enabled: false、backend: memory、ttl: 60s
server监听协议与端口protocol: http、host: 0.0.0.0、http_port: 8080、grpc_port: 9000、https_port: 443
db数据库连接（见下文说明）url: file:/var/opt/flipt/flipt.db（内嵌 SQLite）、连接池参数
tracing分布式追踪enabled: false、exporter: jaeger（Jaeger 默认 localhost:6831）
meta更新检查等元行为check_for_updates: true
storagev2 核心：存储后端定义无默认实例，需至少定义一个（见第四部分）
environmentsv2 核心：环境与存储映射无默认实例（Docker 实测首次启动自动创建 default）
credentialsGit 远端凭据集无默认
authenticationAPI 认证与会话required: false（默认全部开放）

说明：Helm Chart 的 values 示例中还出现 metrics（enabled: true、exporter: prometheus）与 meta.telemetry_enabled、ui.topbar 等字段，可按官方《配置总览》属性表按需启用。

关于 db 块：v2 的特性状态已全面转向 Git 存储，但默认模板仍保留 db 配置（默认指向内嵌 SQLite 文件 /var/opt/flipt/flipt.db，可改为 PostgreSQL DSN），CLI 的 flipt migrate（"Run pending database migrations"）即面向该数据库配置。不要把 v1 的"开关状态存数据库"心智带入 v2——管理平台的内部数据（如认证记录）与特性状态是两回事。

三、高频参数块详解

3.1 log：日志

log:
  level: INFO          # DEBUG/INFO/WARN/ERROR
  file: /var/opt/flipt/flipt.log   # 留空输出到 stdout
  encoding: console    # console 或 json（生产建议 json 便于采集）
  grpc_level: ERROR    # gRPC 框架级日志独立控制

排障时把 level 调到 DEBUG 可看到存储层的完整行为（本文《部署实战》中的 Git fetch/push 链路日志即 DEBUG 级别所获）。

3.2 server：监听

server:
  protocol: http       # http 或 https（v2.0.0 起）
  host: 0.0.0.0
  http_port: 8080      # REST API + UI
  grpc_port: 9000      # gRPC API
  https_port: 443      # protocol 为 https 时生效

另有一个未出现在默认模板、但实测存在的内部端口：8081（启动日志 starting internal http server on localhost:8081，承载内部健康检查等）。

3.3 cors 与 cache

cors:
  enabled: false
  allowed_origins: "*"     # 启用后务必收敛为具体域名列表

cache:
  enabled: false
  backend: memory          # memory 或 redis
  ttl: 60s
  memory:
    eviction_interval: 5m  # 过期项清理周期
  redis:
    host: localhost
    port: 6379

评估是纯内存快照计算，默认无缓存已很快；高并发 + 规则复杂时可开启缓存。选择 redis 后端时注意与 authentication.session.storage 的 redis 配置是相互独立的两个块。

3.4 meta 与遥测

meta:
  check_for_updates: true   # 启动时检查新版本

内网/隔离环境建议显式置为 false（本文实验配置同时关闭了 check_for_updates 并在 compose 中关停遥测外联）。

四、v2 核心：storage 与 environments

这是 v2 相对 v1 变化最大的两个块，也是 GitOps 能力的根基。

4.1 storage：存储后端

一个配置文件可定义多个命名存储，每个存储包含后端（backend）与可选的 Git 远端（remote）：

storage:
  default:
    backend:
      type: local            # local 或 memory
      path: /var/opt/flipt/repo   # local 后端的仓库目录
    remote: https://github.com/<org>/<repo>.git
    branch: main
    poll_interval: 30s       # 远端轮询周期
    fetch_policy: lenient    # 首次启动远端不可达时不阻塞启动
  github:                    # 生产推荐形态（官方 git-sync 指南）
    remote: "https://github.com/<your-username>/<your-repo>.git"
    branch: "main"
    poll_interval: "30s"
    credentials: "github"    # 引用 credentials 块
    backend:
      type: local
      path: "/path/to/local/clone"

要点：

  • backend.type: memory 为纯内存形态（Helm 示例即用 memory），重启即失（配合 remote 拉取可重建）；local 则在本地目录维护完整裸 Git 仓库；
  • remote 支持 https://、ssh://、git:// 协议；实测 file:// 不被支持且静默忽略（日志中 remoteConfig: null 即未生效）；
  • 未配置 remote 的 local 形态，官方 README 明确警告：目录删除即状态丢失。

4.2 environments：环境映射

environments:
  default:
    name: default
    default: true
    storage: default        # 引用 storage 定义
    directory: default      # 仓库内的环境目录
  production:
    name: "Production"
    storage: "github"       # 多环境可共享同一存储后端
    directory: "production" # 各环境目录必须唯一

环境是 v2 的一等概念：每个环境绑定一个 storage + 仓库目录，features.yaml 按 <directory>/<namespace>/features.yaml 组织。多环境共享存储时目录不能冲突（官方 git-sync 指南明确）。运行时管理 API 通过 x-flipt-environment: <key> 请求头切换目标环境（默认 default，实测确认）。

4.3 credentials：Git 凭据

credentials:
  github:
    type: access_token
    access_token: ${env:GITHUB_TOKEN}   # 强烈建议环境变量/secret 注入

在 storage.<name>.credentials 中按名字引用。除 access_token 外，官方指南覆盖 GitHub PAT 的 repo/contents 读写 scope 要求；Gitea/GitLab/Bitbucket/Azure DevOps 等任意 Git 服务端均可（企业 SCM 深度集成属 Pro）。

五、authentication：认证与会话

完整结构（本文实验验证过的形态）：

authentication:
  required: true              # 一键启用全 API 认证
  session:
    domain: "flipt.yourorg.com"  # session 方法启用时必填
    secure: true                # 建议 HTTPS
    csrf:
      key: "<openssl rand -base64 64 生成>"
    token_lifetime: 24h
    storage:
      type: memory            # memory（默认，重启失效）或 redis
      redis:                  # redis 模式
        mode: single          # single 或 cluster
        host: localhost
        port: 6379
    cleanup:
      grace_period: 24h       # 过期 token 保留期（审计）
  exclude:
    evaluation: true          # 按段豁免：/evaluate/v1/* 匿名可访问
  methods:
    token:                    # 静态 token（非 session 兼容）
      enabled: true
      storage:
        tokens:
          ci_token:
            credential: "${secret:file:ci-token}"
            metadata:
              name: "CI Pipeline Token"
    oidc:                     # session 兼容，UI 登录依赖它
      enabled: true
      email_matches:
        - "^.*@flipt\\.io$"
      providers:
        google:
          issuer_url: "https://accounts.google.com"
          client_id: "..."
          client_secret: "${secret:file:google-secret}"
          redirect_address: "https://flipt.yourorg.com"
          scopes: [email, profile]
          # algorithms: [ES256]          # 默认 [RS256]
          # fetch_extra_user_info: true  # UserInfo 端点补充 claims
          # discovery_url: ...           # Azure AD B2C 等特殊场景
          # claims_mapping: {email: "/emails/0"}  # 非标 claims 映射
          # authorize_parameters: {audience: "..."}

关键行为（均经实测或官方文档核实）：

配置效果
required: true所有 API 401：{"code":16,"message":"request was not authenticated"}
exclude.evaluation: true评估接口匿名 200，管理 API 仍 401
methods.token静态 token 走 Authorization: Bearer <credential>；嵌套层级为 methods.token.storage.tokens（实测《配置总览》表格的 methods.token.tokens 写法不生效）
无 session 方法UI 无法登录（token 方法不能建立浏览器会话）
session storagememory 重启即失效；redis 可跨实例共享会话（多副本部署必配）

六、声明式特性状态：features.yaml 结构

features.yaml 是评估数据的唯一来源，存放在 Git 仓库的 <环境目录>/<命名空间>/features.yaml。本节字段说明以官方 Concepts 文档 + v2.14.1 实测为准。

6.1 文件骨架

version: "1.6"          # 声明式 schema 版本
environments:
  default:              # 环境键，须与 environments 配置对应
    namespaces:
      default:          # 命名空间键
        flags: [...]    # 开关列表
        segments: [...] # 分群列表

6.2 Flag：布尔开关（含 Rollout）

- key: checkout-dark-mode
  name: Checkout Dark Mode
  description: 结算页暗色主题灰度开关
  enabled: false
  type: BOOLEAN_FLAG_TYPE
  rollouts:
  - type: SEGMENT_ROLLOUT_TYPE       # 分段灰度
    description: 内测用户直接开启
    segment:
      value: true                    # 命中分群时返回值
      segments: [beta-users]
      segmentOperator: OR_SEGMENT_OPERATOR
  - type: THRESHOLD_ROLLOUT_TYPE     # 阈值灰度
    description: 按实体 20% 灰度
    threshold:
      percentage: 50                 # 0-100，按 entityId 一致性哈希分桶
      value: true
  • 多条 rollout 自上而下顺序匹配；阈值分桶对同一 entityId 粘性（实测同实体重复评估结果恒定）；
  • 灰度比例调整 = 改 percentage → 提交推送 → 下个轮询周期生效，无需重启。

6.3 Flag：变体开关（含 Rule/Distribution）

- key: checkout-button-color
  name: Checkout Button Color
  type: VARIANT_FLAG_TYPE
  enabled: true
  defaultVariant: blue               # 所有规则未命中时的兜底变体
  variants:
  - key: blue
    name: Blue
  - key: red
    name: Red
  rules:
  - segments: [beta-users]           # 规则绑定的分群
    segmentOperator: OR_SEGMENT_OPERATOR
    distributions:
    - variant: blue
      rollout: 30                    # 分群内流量百分比
    - variant: red
      rollout: 70
  • variants[].key 唯一，defaultVariant 必须是已定义变体；
  • rollout 数值按分群内比例分桶，实验组数据可从评估响应的 variantKey 采集。

6.4 Segment：分群与约束

- key: beta-users
  name: Beta Users
  description: 内测用户群
  match_type: ALL_MATCH_TYPE          # ALL（且）/ ANY（或）
  constraints:
  - type: STRING_COMPARISON_TYPE
    property: plan                    # 匹配评估上下文中的 key
    operator: eq                      # eq/neq/empty/notEmpty/prefix/suffix/contains 等
    value: beta

约束类型覆盖字符串（STRING_COMPARISON_TYPE）、数字（NUMBER_COMPARISON_TYPE）、布尔（BOOLEAN_COMPARISON_TYPE）、实体 ID（ENTITY_ID_COMPARISON_TYPE）、日期时间（DATETIME_COMPARISON_TYPE）、集合（STRING_SET_COMPARISON_TYPE/UNKNOWN_SET_COMPARISON_TYPE）与正则（REGEX_COMPARISON_TYPE）。评估时请求 context 携带对应属性即可命中（如 "context": {"plan": "beta"}）。

6.5 评估上下文与分桶

评估请求的三要素（实测回显）：

$ curl -s -H 'Content-Type: application/json' \
    http://localhost:8135/evaluate/v1/boolean \
    -d '{"flagKey":"checkout-dark-mode","entityId":"user-1001","context":{"plan":"beta"}}'
{"enabled":true,"flagKey":"checkout-dark-mode","entityId":"user-1001","reason":"MATCH_EVALUATION_REASON","segment":"beta-users"}
  • entityId：分桶身份（OFREP/OpenFeature 中对应 targetingKey）；
  • reason 取值含义：MATCH_EVALUATION_REASON（分群命中）、THRESHOLD_MATCH_EVALUATION_REASON（阈值灰度命中）、DEFAULT_EVALUATION_REASON（兜底/defaultVariant）、UNKNOWN_EVALUATION_REASON（未命中）。

七、配置校验与常见配置错误

7.1 服务器配置校验

  • 编辑器层面：利用模板首行的 JSON Schema 引用获得实时校验；
  • CLI 层面：flipt config init 生成的配置天然合法；启动失败时日志会给出字段级错误（如未知字段、类型不符），修正后重启即可——服务器配置在重启时重新加载，不支持运行中热改。

7.2 features.yaml 校验

用 flipt validate 对声明式文件做 schema 校验（CI 门禁首选），实测行为：

# 结构违规（顶层写了 environments 包裹但缺少必要字段）时：
$ flipt validate
Validation failed!

- Message  : environments: field not allowed
  File     : features.yaml
  Line     : 2

（exit code 1，--issue-exit-code 可自定义）

# 合法文件：静默通过（exit 0，无输出）

实测还发现两个值得记录的怪癖：

  1. validate 的目标是声明式 flag state 文件（version + namespace/environments 结构），对 YAML 语法解析错误（如误用 tab 缩进）不报错（静默 exit 0）——语法层面请依赖编辑器/yamllint 兜底；
  2. 服务器仓库中经 API 生成的 features.yaml（version + namespace.key 结构）能被 validate 静默通过；手写的顶层 environments 包裹结构若字段不全则报 field not allowed。CI 中建议以"从仓库实际结构出发、改前改后各跑一次 validate"的方式使用。

7.3 配置类排障速查

现象根因处置
启动即报权限错误数据目录属主与容器运行用户（uid 10001）不符chown -R 100:1000 ./data
remote 配置后不拉取用了 file:// 协议（静默忽略）换 git:///https:///ssh://，DEBUG 日志确认 remoteConfig 非空
token 正确仍 401token 嵌套写错（methods.token.tokens）改为 methods.token.storage.tokens
UI 无法登录只启用了 token 方法（非 session 兼容）启用 OIDC 等 session 方法，配置 session.domain
环境变量不生效沿用 v1 ${VAR} 语法改为 ${env:VAR}
改 YAML 不生效poll_interval 过长或推送失败DEBUG 日志看 fetch successful 与目标 hash；确认远端可写

八、一份可直接落地的生产配置示例

综合本文各块，给出最小生产可用配置骨架（Git 远端 + 认证 + 评估豁免）：

log:
  level: INFO
  encoding: json

meta:
  check_for_updates: false

server:
  http_port: 8080
  grpc_port: 9000

credentials:
  git_main:
    type: access_token
    access_token: ${env:FLIPT_GIT_TOKEN}

storage:
  default:
    backend:
      type: local
      path: /var/opt/flipt/repo
    remote: https://git.example.com/platform/flags.git
    branch: main
    poll_interval: 30s
    fetch_policy: lenient
    credentials: git_main

environments:
  default:
    name: default
    default: true
    storage: default
    directory: default

authentication:
  required: true
  exclude:
    evaluation: true
  methods:
    token:
      enabled: true
      storage:
        tokens:
          ci_token:
            credential: ${secret:file:ci-token}
            metadata:
              name: CI Pipeline Token

延伸阅读

参考资料（查询日期 2026-10-28）：

  1. Flipt v2 配置总览：https://docs.flipt.io/v2/configuration/overview
  2. Flipt v2 认证配置：https://docs.flipt.io/v2/configuration/authentication
  3. Flipt v2 概念文档：https://docs.flipt.io/v2/concepts
  4. Git Sync 指南：https://docs.flipt.io/v2/guides/operations/environments/git-sync
  5. 默认配置模板（v2 分支）：https://github.com/flipt-io/flipt/blob/v2/config/default.yml