企业官网建设流程全解析

• 后端
• 前端

本指南基于 Flagsmith 官方文档 core-management.md 展开，系统讲解在 Flagsmith 中创建、编辑、克隆和删除功能标志（Feature Flag）的完整流程，并深入剖析多变量标志（Multivariate / A/B/n）、远程配置（Remote Config）以及常见故障排查。文章同时结合本仓库api/features等目录下的源码实现与数据模型，帮助读者在掌握界面操作之外，进一步理解底层"标志定义（Feature）— 环境状态（FeatureState）— 多变量选项（MultivariateFeatureOption）"的运行机制，做到既会操作、又懂原理。

功能标志（Feature Flag）在 Flagsmith 中的定位

在 Flagsmith 中，功能标志被用来分类并监控用户行为或事件，例如检测垃圾邮件或滥用行为。你可以通过标志的开/关状态以及附带的标志值（Feature Value）来驱动业务逻辑：当某个用户触发了异常行为时，后端可以读取对应标志并将其标记为可疑，从而执行封禁、限流或告警等后续动作。

从数据模型上看，Flagsmith 的核心设计是"标志定义与标志状态分离"：

• Feature（api/features/models.py）定义了一个标志的"元数据"：名称、所属项目、默认启用状态、初始值、类型（STANDARD / MULTIVARIATE）、描述、标签、是否仅服务端可用（is_server_key_only）、是否归档（is_archived）以及所有者（owners / group_owners）等。这些属性面向整个项目生效。
• FeatureState（api/features/models.py）则描述该标志在某个环境（environment）中的具体状态：是否启用（enabled）、值（通过 FeatureStateValue 关联）、所属身份（identity）、所属分段（feature_segment）等。

因此，你在 Flagsmith 中"每个项目创建一次标志、在每个环境中分别编辑标志"，这一使用习惯恰好对应了上述两层模型的设计意图。

创建功能标志（Creating a Feature Flag）

在仪表盘（Dashboard）中创建一个新功能标志，操作路径如下：

1. 进入仪表盘的Features（功能）区域。
2. 点击Create Feature（创建功能）。
3. 为标志输入一个描述性的名称，例如new_ui_enabled。
4. 根据功能规格填写可用字段。注意：这些字段的值会应用到你的所有环境上，之后你可以对每个环境单独进行调整：
   • Enabled by default（默认启用）：决定该标志在所有环境中的初始状态。之后可以针对每个环境单独修改。
   • Value（值，可选）：除了布尔开/关状态，你还可以为标志选择一种格式并填写一个值（字符串、数字、布尔值或 JSON），详见下文 远程配置（Remote Config）。
   • Tags（标签，可选）：用标签对标志进行分类；也可以添加protected标签，防止标志被误删除。
   • Description（描述，可选）：为标志补充一段说明文字。
   • Server-side only（仅服务端可用）：开启后，该标志将无法被客户端 SDK 访问。
5. 点击Create Feature完成创建。

:::tip 如果点击Create A/B/n Test按钮，可以为 A/B 测试定义多组取值。关于此操作的更多细节，请参考 A/B Testing 指南。 :::

从源码层面印证上述字段：Feature模型的name、initial_value、description、default_enabled、type、tags、is_archived、is_server_key_only、owners、group_owners等字段都定义在 api/features/models.py 中；而创建接口的序列化器CreateFeatureSerializer的fields列表（api/features/serializers.py）完整暴露了这些可写字段。其中default_enabled默认值为False（即新标志默认关闭），initial_value默认None，is_server_key_only默认False，与界面上"默认关闭、值可选、服务端仅用可勾选"的行为一致。

关于protected标签与删除保护

文档提到可以通过给标志添加protected标签来"防止它们被意外删除"。在界面中，被标记为protected的标志会进入删除保护流程——当你尝试删除这类标志时，系统会要求额外的确认（输入标志名称以确认删除），从而降低误删风险。这是标签（Tag）在 Flagsmith 中承担的一种"元数据即策略"的用法：标签本身只是项目级的分类对象，但通过protected这一约定名称，它同时充当了删除保护标记。如果需要更细粒度的权限管控，请参考 Permissions and Roles 文档。

多变量标志（Multivariate Flags / A/B/n）

多变量标志允许你为一个标志定义多个取值变体（variants），并为每个变体分配百分比权重，从而在同一个标志上运行 A/B/n 实验。这里有几条关键原则：

• 需要识别用户：多变量分流是按"身份（identity）"计算的。你必须先识别用户（或为其生成唯一的匿名标识，如 GUID/UUID），才能让同一个用户始终命中同一个变体。
• 按环境确定性分配：在同一个环境中，只要权重不变，同一个身份就会稳定地命中同一个变体。
• 权重稳定至关重要：如果在实验进行中修改权重，用户会被重新分桶（re-bucket），从而污染实验结果；除非你刻意想要重新洗牌，否则不要在实验中途调整权重。
• 按环境独立分桶：身份的分桶在每个环境中相互独立，同一个身份在不同环境中可能落入不同的变体。
• 百分比必须合计 100%，且至少需要两个变体。
• SDK 同时返回布尔值enabled状态与多变量value：请使用value来驱动你的实验分支逻辑。

如果需要测试未登录的流量，请为每个匿名用户生成一个唯一标识（如 GUID/UUID）并持久化存储（例如存放在 cookie 或 localStorage 中），确保同一个用户跨会话拿到同一个变体。

快速 A/B/n 配置检查清单：

1. 定义变体与权重（总计 100%）。
2. 启用该标志。
3. 在获取标志之前识别用户（或提供匿名 GUID）。
4. 在代码分支逻辑中使用标志的value。
5. 为分析目的启用所需的集成。

源码视角：多变量模型如何工作

多变量相关的数据模型集中在 api/features/multivariate/models.py：

• MultivariateFeatureOption（api/features/multivariate/models.py）保存变体取值本身，它挂在Feature上，通过key（稳定的可读标识，如big/small）与default_percentage_allocation（默认百分比分配，0～100，默认 100）定义。注意：变体的取值对所有环境是一致的，注释明确写道 "This value is the same for every environment"。
• MultivariateFeatureStateValue（api/features/multivariate/models.py）保存某个环境状态下的百分比分配：它把feature_state（某个环境中的标志状态）与multivariate_feature_option（变体）关联起来，并记录该环境下的percentage_allocation（0～100）。这正好印证了文档中"变体取值全局一致、百分比分配按环境独立"的描述。

模型中的两个@hook(AFTER_CREATE)方法进一步解释了"创建即生效"的细节：

• create_multivariate_feature_state_values：当新建一个变体选项时，自动为当前标志在所有环境中已有的 FeatureState（且没有 identity 与 feature_segment 覆盖）创建对应的MultivariateFeatureStateValue，初始分配使用default_percentage_allocation。
• make_feature_multivariate：创建变体选项后，自动把标志的type从STANDARD切换为MULTIVARIATE；同理，当最后一个变体选项被删除时（make_feature_standard），标志会回到STANDARD类型。

这一机制说明：你不需要手动维护"哪些环境参与多变量实验"——只要给标志添加变体选项，所有环境的默认状态都会自动获得这些变体及其权重，之后你可以按环境微调分配比例。

编辑功能标志（Editing a Feature Flag）

标志是按项目创建一次、按环境多次编辑的。要编辑一个已有标志：

1. 在仪表盘的Environments（环境）标签页，使用下拉框选择你要应用变更的环境。
2. 找到要编辑的标志并点击它；可以使用搜索栏按名称快速定位。

:::tip 如果你只是想将标志开/关，直接在列表视图的View列下拨动开关即可，无需进入编辑面板。 :::

3. 在Value（值）标签页，你可以将标志设置为开或关，也可以编辑它的值，然后点击Update Feature Value保存变更。
4. 可选：创建分段专属标志并定义segment overrides（分段覆盖）。分段与分段覆盖的完整说明见 Segments 概念文档。保存变更时点击Update Segment Overrides按钮。
5. 在Settings（设置）标签页，你可以：
   • 为标志添加标签。
   • 将标志分配给特定的users（用户）和groups（用户组）。
   • 更新标志的描述。
   • 将标志标记为Server-side only，防止客户端 SDK 访问。
   • 将标志设为Archived（已归档）状态，表示它已不再相关。注意：归档后该标志仍会像之前一样被 API 返回，只是从日常列表中过滤掉了。
   • 完成后点击Update Settings保存。

:::tipSettings标签页的变更会影响所有环境；而编辑标志时其他标签页的变更仅对当前选中的环境生效。 :::

分段覆盖（Segment Overrides）与优先级

分段是身份（identities）的一个子集，由一组匹配身份特征（traits）的规则定义。一旦定义了分段，你就可以在某个环境中为标志创建分段覆盖：仅对属于该分段的身份生效的标志状态控制。

当为标志同时存在环境级状态、分段覆盖与身份覆盖时，FlagState 的优先级由高到低大致为：

1. 身份覆盖（identity override）；
2. 分段覆盖（segment override）；
3. 环境默认状态（environment default）。

这一点可以从FeatureState的__gt__优先级比较实现（api/features/models.py）中得到印证：当两个 FeatureState 属于同一环境、同一标志时，带有identity_id的状态优先级最高，其次才轮到带有feature_segment_id的状态，最后是环境级默认状态。理解这条优先级链，有助于你排查"为什么某个用户的标志值与预期不符"。

归档与删除的区别

• Archived（归档）：标志仍然存在、仍然会被 API 正常返回，只是从界面列表中被过滤。适合"停止关注但保留引用"的场景。
• 删除：标志被永久移除，不可恢复。任何代码中的引用都会失效，因此删除前必须确认应用中没有残留引用。

数据模型层面，Feature.is_archived（api/features/models.py）是一个普通布尔字段，默认False；而删除走的是SoftDeleteExportableModel的软删除逻辑（带deleted_at标记），并通过FeatureManager过滤，详情可继续阅读 api/features/managers.py。归档与软删除是两种不同强度的"下线"手段，建议按需选用。

克隆功能标志（Cloning a Feature Flag）

在编辑/查看标志的界面中，你可以通过克隆操作快速复制一个标志及其配置。克隆后得到的是一个拥有新名称的新标志，其初始值、标签、描述等元数据会被复制过来，之后可以按项目/环境继续调整。克隆功能适用于"从已有标志快速生成一批结构相似的新标志"的场景，能够显著减少重复配置工作。具体按钮入口位于标志编辑面板的操作菜单中（对应列表中的更多操作按钮，与删除入口同区域）。

删除功能标志（Deleting a Feature Flag）

删除一个功能标志的步骤：

1. 在Features区域找到要删除的标志，点击右侧的三点（three dots）图标。
2. 选择Remove feature（移除功能）选项。
3. 输入该功能标志的名称以确认删除。

:::caution删除功能标志是永久性的，无法撤销。在确认删除之前，请确保你的应用程序中不包含对该功能标志的任何引用。 :::

从后端实现看，删除动作最终调用delete_feature(instance)（见 api/features/views.py），它负责清理与该标志关联的 FeatureState、多变量选项等数据。删除属于不可逆操作，因此界面上要求输入标志名称作为二次确认；此外，被标记为protected的标志也会受到额外的删除保护。

故障排查（Troubleshooting）

标志没有更新（Feature Flags Not Updating）

• 请确认你在编辑标志面板的每一个标签页中都保存了各自的变更（Value、Segment Overrides、Settings 各自独立保存）。
• 检查你当前是否处于正确的项目和环境中。

多变量标志结果不一致（Multivariate Flags Giving Inconsistent Results）

• 确保在获取标志之前识别了用户。对于匿名用户，请生成唯一标识并持久化存储（如 cookie 或 localStorage），这样同一用户跨会话才会得到同一变体。
• 避免在实验进行中修改权重，因为这会重新分桶用户并使实验结果失效。

权限问题（Permission Issues）

• 创建、编辑、克隆或删除功能标志可能需要额外的权限。如果你看到权限错误或相关选项被禁用，请联系你的 Flagsmith 管理员检查访问权限。更多信息请参考 Permissions and Roles 页面。

从源码看，标志相关视图的权限类为FeaturePermissions（见 api/features/views.py），它基于项目的 RBAC 体系进行校验；同时创建多变量选项等操作还会额外校验用户是否已认证（validate_multivariate_options，见 api/features/serializers.py）。因此，在排查权限问题时，除了组织角色，还需要确认你具备项目级的相应权限。

远程配置（Remote Config）

远程配置允许你在标志的开/关状态之外，再返回一个带类型的值（string、number、boolean 或 JSON）。你可以在同一个标志定义上配置远程配置值，SDK 在评估标志时会读取这些值，并应用与标志开关相同的目标定位与发布规则（targeting and rollout rules）。这意味着：

• 远程配置不只是"启用/禁用功能"，而是可以在不修改代码的情况下调整行为、阈值、文案或布局。
• 标志的布尔开/关（enabled）与远程配置值（value）是两套并行的信息：开关决定"功能是否启用"，值决定"用什么参数运行"。
• 因为远程配置复用了标志的定位规则，你可以把同一个配置值按用户、按分段、按百分比差异化下发——例如"新用户看到 A 文案、老用户看到 B 文案"。

远程配置的值类型

在 Flagsmith 中，标志值（Feature Value）支持以下格式：

这些格式的定义可以追溯到FeatureStateValue的TYPE_CHOICES（api/features/feature_states/models.py）：FeatureStateValue通过type字段记录值类型，通过string_value、integer_value、boolean_value等字段存储具体数值，SDK 在返回时会根据类型反序列化成对应语言的类型。

远程配置的典型使用场景

• 灰度阈值：用数值型标志控制"请求失败超过 N 次才告警"等阈值，无需重新发版。
• 文案与布局：用 JSON 型标志下发按钮文案、配色、功能开关矩阵，实现运营层面的即时调整。
• 多环境差异化：同一个标志在不同环境（开发/预发布/生产）下发不同的配置值，环境切换即配置切换。

数据模型视角

远程配置的核心载体是FeatureStateValue：每个环境的FeatureState都可以挂一个FeatureStateValue，它既可以承载"标志值"，也是多变量实验中"当前变体"的落地位置。创建标志时填写的initial_value（api/features/models.py）会作为所有环境的默认值种子；创建新环境时，系统会用该值生成对应环境下的FeatureStateValue。因此，"创建标志时填的值作用于所有环境"与"编辑标志值时仅作用于当前环境"这两种行为的边界，正是由"initial_value只写入一次、之后按环境各自编辑"这一机制决定的。

总结：标志生命周期最佳实践

综合界面操作与源码机制，管理 Flagsmith 功能标志时建议遵循以下实践：

1. 创建阶段：一次性定义好标志的名称、描述、标签与默认值，让新环境自动继承initial_value与default_enabled。
2. 环境阶段：在各环境中单独调整开关与值；用开关控制功能可用性，用远程配置值控制运行参数，两者解耦。
3. 实验阶段：使用多变量标志时先识别用户（或持久化匿名 GUID），权重设定后不要在实验中途改动。
4. 下线阶段：优先用归档而非删除来保留引用；确需删除时，务必先清除应用内对该标志的所有引用，并留意protected标签的保护机制。
5. 权限阶段：确保操作者具备项目级 RBAC 权限；涉及多变量创建、标志删除等高危操作时，遵守平台的二次确认流程。

通过将仪表盘的界面操作与Feature/FeatureState/MultivariateFeatureOption/FeatureStateValue四层数据模型相互对照，你不仅能熟练完成标志的日常增删改查，还能在遇到"值没生效""分桶不稳定""权限不足"等问题时，快速定位到底层原因，从而更安全、更高效地驾驭 Flagsmith 的功能管理能力。

• 后端
• 前端