Flipt 常用命令与运维实战（核心篇）

Flipt v2 运维核心实操：CLI 命令全集与 evaluate/validate 实测回显、管理/评估/OFREP REST API 的 curl 真实输出、GitOps 改 YAML 热加载全链路、文件即状态的备份恢复，以及六个真实排障案例沉淀，附生产运维检查清单。

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

Flipt 常用命令与运维实战（核心篇）

作为本专栏的核心实操篇，本文以 Flipt v2.14.1 为基准，把日常运维中最常用的能力串成一条可复现的实战线：CLI 命令全集 → REST/gRPC API 实测 → GitOps 工作流（改 YAML 热加载）→ validate 校验门禁 → 备份恢复 → 排障实录。文中所有命令输入与输出均为实验环境真实回显（Docker Compose 单机形态，HTTP 8135 / gRPC 8136，容器名 flipt-v2.14.1-server，详见《Flipt Docker Compose 部署实战》）。

一、CLI 全景：flipt 命令族

v2 的 CLI 相比 v1 做了大裁剪，先看主命令真实回显：

$ flipt --help
Flipt is a cloud-native, self-hosted, feature flag solution that manages feature flags in your Git repositories

Usage:
  flipt [command]

Examples:
$ flipt server
$ flipt config init
$ flipt --config /path/to/config.yml migrate


Available Commands:
  config      Manage Flipt configuration
  evaluate    Evaluate a flag
  help        Help about any command
  license     Manage Flipt Pro license
  migrate     Run pending database migrations
  quickstart  Interactive setup wizard for Flipt Git storage
  server      Run the Flipt server
  validate    Validate Flipt flag state (.yaml, .yml) files

Flags:
  -h, --help      help for flipt
  -v, --version   version for flipt

Use "flipt [command] --help" for more information about a command.

版本信息用全局标志获取（v2 无 version 子命令，实测 flipt version 报 unknown command）：

$ flipt -v

    _________       __
   / ____/ (_)___  / /_
  / /_  / / / __ \/ __/
 / __/ / / / /_/ / /_
/_/   /_/_/ .___/\__/
         /_/

Version: v2.14.1
Commit: 3f59af5a2755d17c4e65b9a341d0c184135621fa
Build Date: 2026-10-23T02:48:17Z
Go Version: go1.27.3
OS/Arch: linux/amd64

迁移提示：v1 中常见的 flipt export/import/doctor/bench 等子命令在 v2 中已移除（实测 unknown command）。v2 的状态即 Git 仓库，导出/导入诉求由 git 本身承担。

二、服务生命周期管理

2.1 启动与配置指定

$ flipt server --help
Run the Flipt server

Usage:
  flipt server [flags]

Flags:
      --config string   path to config file
  -h, --help            help for server
  • 裸机/二进制部署：flipt server --config /opt/flipt/config.yml；
  • 配置查找顺序：--config > ~/.config/flipt/config.yml > /etc/flipt/config/default.yml；
  • Docker/Compose 部署时，服务重启用 docker compose restart（配置文件挂载为 :ro，改动后重启生效——服务器配置不支持运行中热加载，与 features.yaml 的热加载机制区分开）。

2.2 Compose 场景的日常命令

cd /opt/flipt                      # compose.yml 所在目录
docker compose up -d               # 启动（首次或配置变更后）
docker compose restart             # 应用 config.yml 变更
docker compose logs -f --tail 100  # 跟踪日志
docker compose ps                  # 状态确认
docker compose down                # 停止（保留数据目录）

启动成功的标志日志（实测回显）：

INFO environment configured successfully {"key": "default", "hash": "8637d52d0fa8453c1e07a87d01895cd77eae986e"}
INFO grpc server listening on [::]:9000
INFO listening on [::]:8080...
INFO starting internal http server on localhost:8081
INFO flipt started

WARN no license key provided; additional features are disabled. 属正常提示（未安装 Pro 许可，社区功能不受影响）。

2.3 健康检查与探针

$ curl -s http://localhost:8135/health
{"status":"ok"}
$ curl -s 'http://localhost:8135/health?service=evaluation'
{"status":"ok","service":"evaluation"}
$ curl -s 'http://localhost:8135/health?service=management'
{"status":"ok","service":"management"}

三个端点分别对应进程、评估快照与管理面就绪状态，可直接用作监控探针（k8s 中映射为 liveness/readiness probe）。gRPC 端口 9000 的探活同样走 /health?service=grpc。

三、REST API 实测

3.1 管理 API：开关/分群的增改查

v2 管理 API 前缀为 /api/v2，资源按 environments/<env>/namespaces/<ns>/resources 组织，请求体使用 @type 指明 protobuf Any 类型。创建布尔开关（实测）：

$ curl -s -H 'Content-Type: application/json' \
    -X POST http://localhost:8135/api/v2/environments/default/namespaces/default/resources \
    -d '{"key":"checkout-dark-mode","payload":{"@type":"flipt.core.Flag","key":"checkout-dark-mode","name":"Checkout Dark Mode","description":"结算页暗色主题灰度开关","type":"BOOLEAN_FLAG_TYPE","enabled":true}}'
{"revision":"5cb9542..."}

返回的 revision 即本次变更生成的 Git 提交哈希——管理 API 的每次写操作都是一次 Git 提交，git log 就是变更审计日志。更新（PUT）同样以整份 payload 提交：

$ curl -s -H 'Content-Type: application/json' \
    -X PUT http://localhost:8135/api/v2/environments/default/namespaces/default/resources \
    -d '{"key":"checkout-dark-mode","payload":{"@type":"flipt.core.Flag","key":"checkout-dark-mode","name":"Checkout Dark Mode","description":"结算页暗色主题灰度开关","type":"BOOLEAN_FLAG_TYPE","enabled":false,"rollouts":[{"type":"SEGMENT_ROLLOUT_TYPE","description":"内测用户直接开启","segment":{"value":true,"segments":["beta-users"],"segmentOperator":"OR_SEGMENT_OPERATOR"}},{"type":"THRESHOLD_ROLLOUT_TYPE","description":"按实体 20% 灰度","threshold":{"percentage":20,"value":true}}]}}'
{"revision":"..."}

创建分群（Segment）：

$ curl -s -H 'Content-Type: application/json' \
    -X POST http://localhost:8135/api/v2/environments/default/namespaces/default/resources \
    -d '{"key":"beta-users","payload":{"@type":"flipt.core.Segment","key":"beta-users","name":"Beta Users","description":"内测用户群","match_type":"ALL_MATCH_TYPE","constraints":[{"type":"STRING_COMPARISON_TYPE","property":"plan","operator":"eq","value":"beta"}]}}'
{"revision":"..."}

列出资源与查看环境：

$ curl -s http://localhost:8135/api/v2/environments
{"environments":[{"key":"default","name":"default","default":true,"configuration":{"ref":"main","directory":"default","remote":"git://10.89.57.1/flags.git"}}]}

$ curl -s http://localhost:8135/api/v2/environments/default/namespaces/default/resources
{"resources":[{"typeUrl":"type.googleapis.com/flipt.core.Flag","value":"<protobuf base64>"}]}

（列表返回 protobuf Any 的 base64 编码值；人读形态直接看 Git 仓库里的 features.yaml。）

3.2 评估 API：布尔/变体/批量

布尔评估（分群命中，实测）：

$ 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"}

阈值灰度命中与未命中（实测）：

$ curl -s -H 'Content-Type: application/json' http://localhost:8135/evaluate/v1/boolean \
    -d '{"flagKey":"checkout-dark-mode","entityId":"u13","context":{"plan":"pro"}}'
{"enabled":true,"flagKey":"checkout-dark-mode","entityId":"u13","reason":"THRESHOLD_MATCH_EVALUATION_REASON"}

$ curl -s -H 'Content-Type: application/json' http://localhost:8135/evaluate/v1/boolean \
    -d '{"flagKey":"checkout-dark-mode","entityId":"u15","context":{"plan":"pro"}}'
{"enabled":false,"flagKey":"checkout-dark-mode","entityId":"u15","reason":"UNKNOWN_EVALUATION_REASON"}

变体评估（30/70 分发 + 粘性分桶，实测）：

$ curl -s -H 'Content-Type: application/json' http://localhost:8135/evaluate/v1/variant \
    -d '{"flagKey":"checkout-button-color","entityId":"user-1001","context":{"plan":"beta"}}'
{"flagKey":"checkout-button-color","entityId":"user-1001","variantKey":"blue","variantAttachment":"{}","reason":"MATCH_EVALUATION_REASON","segment":"beta-users"}

$ for u in user-1 user-2 user-3 user-4 user-5 user-6 user-7 user-8 user-9 user-10; do
    curl -s -H 'Content-Type: application/json' http://localhost:8135/evaluate/v1/variant \
      -d "{\"flagKey\":\"checkout-button-color\",\"entityId\":\"$u\",\"context\":{\"plan\":\"beta\"}}" \
      | python3 -c 'import json,sys; print(json.load(sys.stdin)["variantKey"])'
  done
blue
red
red
red
blue
red
red
red
blue
red

同一 entityId 重复请求结果恒定（一致性分桶），比例在 30/70 附近波动属正常抽样。

批量评估与 OFREP 标准端点（实测）：

$ curl -s -H 'Content-Type: application/json' http://localhost:8135/evaluate/v1/batch \
    -d '{"requests":[{"flagKey":"checkout-dark-mode","entityId":"user-1001","context":{"plan":"beta"}},{"flagKey":"checkout-button-color","entityId":"user-1001","context":{"plan":"beta"}}]}'
{"responses":[{"type":"BOOLEAN_EVALUATION_RESPONSE","booleanEvaluationResponse":{"enabled":true,"flagKey":"checkout-dark-mode","reason":"MATCH_EVALUATION_REASON","segment":"beta-users"}},{"type":"VARIANT_EVALUATION_RESPONSE","variantEvaluationResponse":{"flagKey":"checkout-button-color","variantKey":"blue","reason":"MATCH_EVALUATION_REASON","segment":"beta-users"}}]}

$ curl -s -H 'Content-Type: application/json' http://localhost:8135/ofrep/v1/evaluate/flags/checkout-dark-mode \
    -d '{"context":{"targetingKey":"user-1001","plan":"beta"}}'
{"key":"checkout-dark-mode","value":true,"reason":"SEGMENT_MATCH","variant":null,"metadata":{"flagSet":"","flagType":"boolean","description":"..."}}

OFREP 端点使任意 OpenFeature OFREP Provider 无需专用 SDK 即可接入。

四、flipt evaluate：命令行评估（gRPC）

$ flipt evaluate --help
Evaluate a flag

Usage:
  flipt evaluate [flagKey] [flags]

Flags:
  -a, --address string        address of Flipt instance. (default "http://localhost:8080")
  -c, --context stringArray   evaluation request context as key=value.
  -e, --entity-id string      evaluation request entity id. (default "c104b9dc-3b9b-4035-8534-473e69c801c7")
      --environment string    flag environment (default "default")
  -h, --help                  help for evaluate
  -i, --interval duration     interval between requests in watch mode. (default 1s)
  -n, --namespace string      flag namespace. (default "default")
  -r, --request-id string     evaluation request id.
  -t, --token string          client token used to authenticate access to Flipt instance.
  -w, --watch                 enable watch mode.

实测（gRPC 通道 + 客户端 token）：

$ flipt evaluate checkout-button-color -a grpc://flipt-v2.14.1-server:9000 \
    -e user-1001 -c plan=beta -t ft_docs_ci_1a2b3c4d5e6f
{"flag_key":"checkout-button-color","match":true,"reason":"MATCH_EVALUATION_REASON","variant_key":"blue","variant_attachment":"null","segment_keys":["beta-users"],"request_id":"00e1e1b0-4d2f-40e8-a55a-5ef800970101","request_duration_millis":0.287854,"timestamp":"2026-10-28T04:33:53.196155337Z"}

$ flipt evaluate checkout-dark-mode -a grpc://flipt-v2.14.1-server:9000 \
    -e user-2002 -c plan=pro -t ft_docs_ci_1a2b3c4d5e6f
{"flag_key":"checkout-dark-mode","enabled":true,"reason":"MATCH_EVALUATION_REASON","request_id":"68873590-c274-43d5-9f86-f151470ff86a","request_duration_millis":0.063976,"timestamp":"2026-10-28T04:33:53.554667352Z"}

三个实测踩坑点：

  1. 地址必须带协议前缀：-a flipt-v2.14.1-server:9000 报 Error: unexpected protocol flipt-v2.14.1-server，需写 grpc://...；
  2. 认证：服务器启用认证后，CLI 走 gRPC 通道需 -t <token>，否则 Error: rpc error: code = Unauthenticated desc = request was not authenticated（配置 exclude.evaluation 豁免的是 HTTP 路由，CLI 的 gRPC 调用仍需 token）；
  3. -w watch 模式按 -i 间隔持续输出评估结果，适合验证灰度变更的实时生效。

五、GitOps 工作流：改 YAML → 热加载

这是 Flipt v2 的灵魂链路，完整操作序列（全部实测）：

# 1. 克隆开关仓库（工作副本）
$ git clone git@git.example.com:platform/flags.git && cd flags

# 2. 直接编辑声明式文件：灰度阈值 20% -> 50%
$ sed -i 's/percentage: 20/percentage: 50/' default/default/features.yaml
$ grep -n 'percentage' default/default/features.yaml
              percentage: 50

# 3. 提交并推送（走 PR 评审亦可）
$ git add -A && git commit -m "rollout checkout-dark-mode threshold 20 -> 50"
$ git push origin main

# 4. Flipt 侧自动生效（服务端 DEBUG 日志实测回显）
DEBUG preparing refspec for fetch {"refspec": "+refs/heads/main:refs/remotes/origin/main"}
DEBUG fetch successful {"git_storage_type": "filesystem", "git_storage_path": "/var/opt/flipt/repo"}
DEBUG view {"branch": "main", "hash": "9a8770c3941e54e48b0e391fd303ec821d5e0ca2"}

# 5. 立即验证：无需重启，评估结果已按新阈值判定
$ curl -s -H 'Content-Type: application/json' http://localhost:8135/evaluate/v1/boolean \
    -d '{"flagKey":"checkout-dark-mode","entityId":"u17","context":{"plan":"pro"}}'
{"enabled":true,...}

实测在 poll_interval: 5s 下，推送后 5~7 秒内评估结果翻转。反向链路（UI/API 修改自动提交回仓库）同样闭环：服务端日志 starting update and push operation → creating commit → commit created successfully → pushing to remote，远端仓库随之出现 update flag default/checkout-dark-mode 等提交。

运维要点：git log（谁改的、改了什么）+ git revert（一键回滚）+ poll_interval 内自动生效，构成无需自研的变更治理三件套。

六、flipt validate：声明式文件的 CI 门禁

$ flipt validate --help
Validate Flipt flag state (.yaml, .yml) files

Usage:
  flipt validate [flags]

Flags:
  -e, --extra-schema string   path to extra schema constraints
  -F, --format string         output format: json, text (default "text")
  -h, --help                  help for validate
      --issue-exit-code int   exit code to use when issues are found (default 1)
  -d, --work-dir string       set the working directory (default ".")

实测行为（重要）：

# 结构违规：退出码 1，报告违规字段与行号
$ flipt validate
Validation failed!

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

（exit code 1）

# 合法文件：静默通过
$ flipt validate -d /path/to/repo
（无输出，exit 0）

两个实测怪癖，CI 集成时务必知晓：

  1. validate 对 YAML 语法错误（如误用 tab 缩进）不报错（静默 exit 0），语法层建议在流水线中叠加 yamllint 或依赖编辑器 schema 校验兜底；
  2. v2 仓库中实际存在的 features.yaml（version + namespace.key 结构）可通过校验；但手写的不完整 environments 包裹结构会报 field not allowed——校验器面向的是声明式 flag state 文件本身的结构约定。

推荐的流水线门禁写法：

# CI 示例（GitLab CI 片段）
flags-validate:
  stage: test
  image: flipt/flipt:v2.14.1
  script:
    - flipt validate -d .
  rules:
    - changes:
      - "**/features.yaml"

七、config / license / migrate

7.1 flipt config：配置文件生成与编辑

$ flipt config --help
Manage Flipt configuration

Usage:
  flipt config [command]

Aliases:
  config, cfg

Available Commands:
  edit        Edit Flipt configuration
  init        Initialize Flipt configuration

Flags:
      --config string   path to config file
  -h, --help            help for config

flipt config init 为交互式向导（逐项回车取默认值，生成于用户配置目录）；flipt config edit 打开编辑器修改。裸机部署推荐用它生成初版配置再细调。

7.2 flipt license：Pro 许可管理

$ flipt license --help
Manage your Flipt Pro license for enterprise-grade features.

Flipt Pro provides:
  • Enterprise GitOps integration (GitHub, GitLab, Bitbucket, Azure DevOps)
  • Secrets management
  • GPG commit signing and merge proposals from UI
  • Air-gapped environment support (annual license)
  • Dedicated Slack support channel

License management commands:
  flipt license check              # Check current license status
  flipt license activate           # Activate a new license interactively

Usage:
  flipt license [command]
...

社区版服务器日志中的 WARN no license key provided 即对应此处；购入 Pro 后用 flipt license activate 交互式激活、flipt license check 验证有效期。

7.3 flipt migrate：数据库迁移

$ flipt migrate --help
Run pending database migrations

Usage:
  flipt migrate [flags]

Flags:
      --config string   path to config file
  -h, --help            help for migrate

面向配置中 db 块的数据库执行迁移（v2 默认指向内嵌 SQLite file:/var/opt/flipt/flipt.db）。特性开关状态在 v2 不存数据库，此命令服务于平台内部数据结构，常规 Git 存储部署无需手动执行。

八、备份与恢复：文件即状态

v2 的状态就是 Git 仓库，备份策略围绕这一点展开：

# 方式一（推荐）：状态在远端 Git 服务器，本地可随时重建
#   远端仓库本身由 Git 服务端的高可用策略保护

# 方式二：本地裸仓库打包（git bundle，单文件含全部历史）
$ git --git-dir=/opt/flipt/data/repo bundle create /backup/flipt-$(date +%F).bundle --all

# 方式三：直接归档数据目录（停机窗口内）
$ docker compose stop
$ tar czf /backup/flipt-data-$(date +%F).tar.gz data/
$ docker compose start

# 恢复演练：新机器恢复 bundle 后核对分支
$ git clone /backup/flipt-2026-10-28.bundle restored && cd restored && git log --oneline | head -5

同时纳入备份的还有两份"配置即代码"：config.yml 与 compose.yml（建议与开关仓库分开，纳入运维配置库）。会话数据若启用 redis 存储则由 redis 持久化策略覆盖，丢失仅影响登录态。

九、排障实录沉淀

以下 6 个案例全部来自本专栏实验环境的真实故障复现，每个都给出可直接对照的日志/回显。

案例一：数据目录权限导致服务起不来

现象：compose up 后容器反复重启，日志报 Git 仓库初始化失败（permission denied）
原因：镜像以 uid 10001 运行，宿主 ./data 属主为 root
处置：chown -R 100:1000 ./data && docker compose restart
预防：部署清单中固化目录属主步骤

案例二：remote 配 file:// 静默失效

现象：配置 remote: file:///var/opt/flipt/upstream.git 后，外部提交永不同步
关键日志：INFO environment configured successfully {"key": "default", "remoteConfig": null}
原因：v2 仅支持 git:///https:///ssh:// 协议，file:// 被静默忽略
处置：改用 git://（实验）或 https://+token（生产）
验证标准：日志出现 "remoteConfig": {"Name":"origin","URLs":[...]} 才算生效

案例三：Git 服务端只读，推送被拒且写操作整体失败

现象：API 创建开关报错
  {"code":13,"message":"resource type \"flipt.core.Flag\": access denied or repository not exported: /flags.git"}
服务端日志：commit created successfully {"hash": "0351..."} → pushing to remote → 失败
原因：git daemon 默认未启用 receive-pack（只读）
处置：git daemon --enable=receive-pack（实验）；生产用带认证的 HTTPS/SSH
深层结论：v2 写路径是"commit + push"事务——push 失败则 API 报错、变更回退，
         远端 Git 的可用性直接决定管理面可用性

案例四：静态 token 嵌套层级写错 → 静默 401

现象：按《配置总览》参数表写在 authentication.methods.token.tokens 下，
      服务正常启动，但携带 token 的管理 API 请求始终 401，无显式报错
处置：改为 authentication.methods.token.storage.tokens.<id>.credential（以《认证》文档为准）
验证：curl -H 'Authorization: Bearer <token>' /api/v2/environments 返回 200

案例五：CLI evaluate 报 unexpected protocol

现象：flipt evaluate checkout-button-color -a flipt-v2.14.1-server:9000
      → Error: unexpected protocol flipt-v2.14.1-server
原因：-a 地址必须显式携带协议前缀
处置：-a grpc://flipt-v2.14.1-server:9000（HTTP 走 http://）

案例六：CLI evaluate 认证失败

现象：flipt evaluate ... → Error: rpc error: code = Unauthenticated desc = request was not authenticated
原因：CLI 走 gRPC 通道；exclude.evaluation 豁免的是 HTTP 路由，gRPC 调用仍需凭据
处置：追加 -t <client token>

十、运维检查清单

  • 数据目录属主正确（uid 10001 可写），或已配置远端 remote；
  • storage.*.remote 指向可写 Git 服务端，git log 可见变更提交；
  • authentication.required: true 已开启，管理 token 走 secret 引用而非明文；
  • poll_interval 与发布时效预期匹配（生产常用 30s）；
  • /health（含 evaluation/management 参数）已接入监控；
  • 日志 encoding: json 便于采集，排障时临时切 DEBUG；
  • CI 中 flipt validate 对 features.yaml 变更做门禁（叠加 yamllint 防语法漏检）；
  • 备份策略覆盖远端 Git 仓库与服务器配置文件；
  • 升级前固定版本标签（如 v2.14.1），避免浮动标签；升级窗口内核对 flipt -v 与启动日志 hash。

延伸阅读

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

  1. Flipt v2 CLI 参考：https://docs.flipt.io/v2/cli
  2. Flipt v2 API 参考：https://docs.flipt.io/v2/reference
  3. Flipt v2 评估 API（OpenAPI）：https://github.com/flipt-io/flipt/blob/v2/rpc/flipt/openapi.yaml
  4. Flipt v2 管理API（OpenAPI）：https://github.com/flipt-io/flipt/blob/v2/rpc/v2/environments/openapi.yaml