1. 系统简介

App Pipeline 是一套服务端驱动的 Flutter App 用户分流管理系统。 它解决了一个核心问题：当你的 Flutter App 需要针对不同地区、不同用户群体展示差异化内容时， 传统方案需要重新打包发版，而 App Pipeline 让你通过 Web 管理后台实时配置规则， App 启动时自动从服务端获取分流结果，无需发版即可生效。

核心工作原理：App 启动 → 调用验证 API → 服务端按规则判断 → 返回分流结果（URL / Type / 自定义参数）→ App 渲染对应内容。

2. 快速上手：完整配置流程

以下是从零开始配置一套分流规则并集成到 Flutter App 的完整步骤，预计耗时 15–20 分钟。

3.1 系统仪表板

系统仪表板

仪表板是系统的首页，提供整体运行状态的概览视图。

3.2 App 管理

App 管理页面

App 管理页面用于维护系统中的 Flutter 应用列表，每个 App 是规则版本的顶层容器。

3.2.1 AppLink 解锁

AppLink 是一种深层连结（Deep Link）解锁机制，让用户只需点击一个连结即可永久解锁 App 内容，无需输入任何验证码或密码。每个 App 只需设定一个 AppLink，适合用于行销推广、渠道追踪和 VIP 邀请等场景。

建立 AppLink 的步骤

进入「App 管理」，点击 App 卡片右侧的展开箭头，切换至「AppLink」标签页。在 URL Scheme 欄位输入自订 scheme（如 vclock），此值必须与 App 的 AndroidManifest 和 iOS Info.plist 中设定的 scheme 完全一致。点击「建立 AppLink」按钮，系统自动生成一个 6 位数 Token，并显示完整的深层连结 URL。

AppLink 解锁流程

用户点击深层连结 → App 被唤起（冷启动或热启动）→ SDK 的 initAppLinkListener() 监听到连结 → 自动调用后端 API 完成解锁 → 触发 onUnlocked 回调 → App 显示解锁成功内容。解锁成功后，SDK 将结果写入本地缓存，后续 5 分钟内调用 verify() 直接返回 applink_unlocked，不会重复触发规则引擎。

3.3 规则版本管理

规则版本列表页面

规则版本是分流规则的核心载体，每个版本包含完整的规则层级配置和输出配置。

版本状态说明

灰度版本的送审隔离机制

灰度版本专为 App Store 送审期间设计。与普通灰度发布（按比例放行）不同，App Pipeline 的灰度模式采用「全拦截 + 选择性记录」策略：

输出模式选择指南

3.4 规则层级配置

规则层级配置页面

规则层级是版本内的单个判断步骤，多个层级按照排序权重依次执行，全部通过才视为最终通过。

3.5 用户黑名单

用户黑名单页面

用户黑名单用于封禁特定用户，封禁后该用户的所有验证请求将直接返回拦截结果，无需经过规则层级判断。黑名单的优先级高于规则层级，但低于即时覆盖。

黑名单来源

批量导入 CSV 格式

identifierType,identifierValue,reason,expiresAt
device_uid,DEVICE-UID-001,违规行为,2026-12-31 23:59:59
user_id,USER-12345,账号异常,
ip,192.168.1.1,恶意请求,2026-06-30 00:00:00

3.6 即时覆盖

即时覆盖页面

即时覆盖是系统中优先级最高的处置机制，高于所有规则层级和黑名单判断。适用于需要立即对特定用户生效的紧急场景。

3.7 SDK 生成

SDK 生成页面

SDK 生成模块根据选定的规则版本，自动生成可集成到 Flutter App 的代码。

在左侧选择目标规则版本（建议选择已发布为全量或灰度的版本）。若该 App 已设定 AppLink，还需在下方的「选择 App」下拉选单中选择对应 App；选择后，生成的 Dart 代码会自动嵌入正确的 URL Scheme，无需手动填写。点击「生成 Dart SDK」按钮，代码生成后显示在代码预览区域，点击「复制代码」一键复制。

生成的 Dart 代码包含

3.8 操作日志

操作日志页面

操作日志记录所有管理员在后台执行的关键操作，用于审计追溯和问题排查。

日志内容包含：操作时间、操作人、操作类型（创建/更新/删除/状态变更）、目标对象类型和名称、操作详情（修改前后的字段对比）。点击任意日志记录可展开查看完整的修改前后对比，以 JSON 格式展示字段变化。

3.9 验证日志

验证日志页面

验证日志记录所有来自 App 端的验证请求，是监控系统运行状态和排查用户问题的核心工具。

验证结果类型说明（resultLevel）

排查用户问题的典型流程

在搜索框输入用户的设备 UID → 找到对应的验证记录 → 展开详情查看是哪一层规则导致拦截 → 根据情况选择修改规则、解除黑名单或添加即时覆盖。

4. Flutter App 集成指南

4.1 集成步骤

import 'app_pipeline_sdk.dart';

final sdk = AppPipelineSDK(
  apiEndpoint: 'https://your-domain.com/api/verify',
);

final result = await sdk.verify(
  deviceUid: await getDeviceUid(),
  userId: currentUser?.id,
  countryCode: 'TW',
  platform: Platform.isIOS ? 'ios' : 'android',
);

if (result.allowed) {
  switch (result.outputMode) {
    case 'url':
      launchUrl(Uri.parse(result.output!.url!));
      break;
    case 'type':
      navigateByType(result.output!.type!);
      break;
    case 'custom_params':
      handleCustomParams(result.output!.params!);
      break;
  }
} else {
  showBlockedContent(result.output);
}

4.2 设备 UID 获取建议

4.3 降级策略建议

当验证 API 请求失败（网络超时、服务端错误）时，建议 App 端采用以下降级策略：

5. 常见问题（FAQ）

6. 名词对照表