# FinClip 小程序开放平台 POC 指导手册 - 私有化部署
FinClip 是小程序运行时 SDK。无论是移动应用，还是电脑、电视、车载主机等设备，在集成 FinClip 小程序 SDK 之后，都能快速获得运行小程序的能力。
FinClip 提供小程序 SDK 与小程序管理后台。开发者可迁移并部署已有小程序到自己的应用中，从而获得足够灵活的小程序开发与管理体验。
FinClip 不仅兼容微信小程序语法，还提供一整套小程序开发与管理工具集。开发者无需学习新的语法与框架，即可使用 FinClip IDE、小程序管理后台、小程序开发文档与 FinClip App，低成本、高质量地完成从开发测试到预览上线的全部工作。
FinClip 可以帮助企业快速集成自研及第三方业务应用；助力企业构建超级应用，实现复杂业务线的松耦合；帮助企业培养平台化的运营思维与组织架构。
# 1.1 POC 目的
本 POC 指导旨在通过实际操作，帮助您了解 FinClip 小程序开放平台管理系统的主要功能与优势。通过此过程，您可以评估产品是否满足企业的实际需求，产品的真实功能或性能是否与供应商宣传的一致，评估系统与业务需求的兼容性，并以此作为采购决策的依据。
# 1.2 POC 目标
本次 POC 的目标是帮助您成功体验 FinClip 小程序开放平台管理系统的核心功能，包括 FinClip 小程序容器 SDK、FinClip 小程序管理后台、FinClip 生态构建、FinClip 小游戏等功能模块。期望通过此过程，帮助您确认项目可行性、评估项目绩效、评估项目潜力，为后续决策提供重要依据。
# 2. 准备阶段
# 2.1 环境要求
# 2.1.1 操作系统
FinClip 小程序开放平台使用 Docker 进行服务部署。我们推荐使用 Linux 操作系统来运行 FinClip 小程序服务。当然，如果您的操作系统满足运行 Docker 的要求，即可运行 FinClip 平台。我们建议您使用以下系统运行 FinClip 小程序服务：
| 操作系统 | 版本要求 |
|---|---|
| Ubuntu | ≥ 20.04, 22.04 |
| CentOS | ≥ 7.9 |
| Debian | ≥ 11 |
# 2.1.2 硬件配置
FinClip 小程序开放系统对运行环境没有要求，可以运行在 TCE 裸金属、虚拟机或云服务器上。为保证系统正常运行，FinClip 运行所需的最低服务器配置如下：
| 类别 | 规格 |
|---|---|
| 服务器数量 | 1 台 |
| 服务器内存 | 8 G |
| CPU 核心数 | 4 C |
| 磁盘空间 | 200 G |
# 2.1.3 网络配置
FinClip 小程序开放系统服务内部通信使用 Docker 内部网络通信。但我们需要为 FinClip SDK 和 Web 服务访问我们的系统提供一个外部可访问的端口。系统默认端口为 8000，通信协议为 TCP。当然，您也可以更改对外开放的端口号，例如 80 或 443。
| 协议 | 端口 | 描述 |
|---|---|---|
| TCP | 8000 | 组织运营管理后台及 API |
# 2.1.4 操作权限
FinClip 小程序开放系统在部署过程中需要使用 root 权限进行以下操作：
- Docker：运行 Docker 需要 root 权限，没有 root 权限的普通用户将无法操作 Docker。
- 更改数据目录权限：在服务部署过程中，需要更改数据存储目录的权限，以确保数据写入成功。
# 2.2 人员要求
为确保本次 POC 能达到预期目标，需要组建一个跨职能团队协同工作，因为不同领域的专业知识和技能组合对于提高整体验证工作和项目的可行性至关重要。我们需要您安排以下角色参与产品测试：
| 序号 | 角色 | 人数 | 职能 |
|---|---|---|---|
| 1 | 项目经理 | 1 | 1. 负责整体项目把控，包括 POC 方案的制定、执行与监控，确保整个 POC 方案顺利实施并达到预期效果。 2. 负责测试 FinClip 小程序平台核心功能。 3. 负责 POC 体验的组织、总结、汇报等工作。 |
| 2 | App 开发者 | 2~3 | 1. 负责测试 FinClip 小程序容器 SDK，包括 iOS SDK、Android SDK、PC SDK 等，并输出 SDK 测试报告。 2. 负责输出可供体验、演示、汇报的安装包，包括但不限于 apk、ipa、exe、dmg 等。 |
| 3 | 前端开发 | 1 | 1. 负责测试 FinClip Studio 小程序开发工具，并输出 FinClip Studio 测试报告。 2. 负责输出一个可供体验的小程序，确保该小程序在 FinClip Studio 上正确运行，并在 FinClip 小程序平台的管理后台发布。 |
| 4 | 运维工程师 | 1 | 1. 负责提供 FinClip 小程序数字化管理系统的运行环境。 2. 负责 FinClip 小程序数字化管理系统的安装部署，为本次 POC 的顺利执行提供环境支持，并参与软件功能测试与问题排查。 |
# 3. 安装部署
若您的服务器可被远程访问，凡泰极客团队工程师可提供安装部署服务。
在本章中，我们将介绍如何在您的私有化服务器上搭建一套 FinClip 小程序开放平台系统。
# 3.1 安装 Docker
FinClip 小程序开放系统使用 Docker (opens new window) 进行服务部署。Docker 是一个开源项目，用于将应用程序自动部署为可移植的独立容器，这些容器可以在云中或本地运行。首先，我们需要在您的服务器上安装 Docker。有关如何安装 Docker 的说明，请参阅：安装 Docker Engine (opens new window)
# 3.2 下载软件安装包
FinClip 开放系统软件安装包包含 Docker 镜像和 Docker Compose 配置文件。我们会定期将安装包推送到指定仓库。您可以通过版本号获取不同版本。这里我们以 FinClip 版本 1.3.1 为例。您可以通过下载链接直接下载：下载链接 (opens new window)，或通过命令行下载。命令行如下：
wget https://temp-1251849568.cos.ap-guangzhou.myqcloud.com/finclip-cloud-v1.3.1.tar.gz
# 3.3 加载镜像
下载完成 FinClip 小程序开放系统软件安装包后，您将获得一个后缀为 .gz 的压缩包文件。将该压缩包文件解压到您需要安装的目录下，然后使用 Docker 命令将镜像文件加载到 Docker 中。您可以通过以下命令行完成：
- 导航到压缩包位置并解压
tar xvf ./finclip-cloud-v1.3.1.tar.gz
- 加载镜像
cd finclip-cloud
docker load -i images.tgz
# 3.4 修改文件配置
# 3.4.1 License 配置
FinClip 小程序开放系统的启动和运行依赖于 License。您可以通过联系 FinClip 官网 (opens new window) 或您的 FinClip 业务联系人获取 FinClip 小程序开放系统的 License，然后在 fc-private.yaml 文件中配置 License：
- 编辑 fc-private.yaml 文件，修改 License 配置信息
LICENSE_ENCRYPTION_STR: " 在此处填写您的 License 字符串 "
# 3.4.2 自定义配置
此配置项为可选。
- 修改业务访问的服务监听端口。默认端口为 :8000。编辑 .env 文件修改端口配置。
gateway_port: "填写您的端口"
- 修改数据库及静态资源存储路径，默认目录：./data，编辑 .env 文件修改
BASE_STORAGE_DIR: " 输入您的数据库和静态资源存储路径 "
# 3.5 启动服务
在您确认上述文件配置内容正确后，我们可以启动服务。首先，我们需要启动基础服务，确保数据库、中间件等成功启动。然后，启动 FinClip 配置服务。最后，启动 FinClip 小程序开放平台管理系统的业务微服务。
- 初始化文件存储信息，并为文件目录授予特殊读写权限
bash init.bash
- 启动基础服务，包括 mysql、redis、minio 和 consul 服务
docker compose up -d mysql redis minio consul elasticsearch && sleep 15
- 启动 FinClip 配置服务
docker compose up -d quark && sleep 10
- 启动 FinClip 小程序开放平台管理系统的业务微服务
docker compose up -d
- 最后，您可以通过以下命令行快速确认所有服务是否正常运行。当您看到所有服务的状态均为 "Up" 时，表明服务已成功启动。
docker compose ps
# 3.6 访问系统
通过 Docker 确认服务正常启动后，您可以通过以下链接访问系统，以确认系统是否已成功搭建。
| 网站名称 | 访问链接 | 账户 | 说明 |
|---|---|---|---|
| 管理后台 | http://IP:PORT/ops#/ (opens new window) | admin | PORT: 端口号，默认 8000；IP: 服务器 IP 地址，例如 172.217.163.46 |
| 开发者后台 | http://IP:PORT/dev#/ (opens new window) | 自行注册 | |
# 4. 验证步骤
您需要准备以下材料和内容来完成 FinClip 的 POC 验证。
# 4.1 验证准备
# 4.1.1 账户准备
# 4.1.1.1 获取验证码
系统部署时未集成短信通道，因此系统内所有短信验证功能均无法使用。
您可以通过登录管理后台（初始账户通常为：admin），然后导航至 [管理后台 - 开发管理 - 自定义配置 - 产品安全配置 - 启用通用验证码] 来获取一个通用验证码。该验证码可用于平台所有验证入口。
# 4.1.1.2 注册账户
- ① 进入开发者后台，点击页面上的"注册"
- ② 输入您的账户、邮箱地址和验证码，设置登录密码，然后点击"注册"以成功注册
# 4.1.1.3 升级为商业账户
- ③ 进入开发者后台，依次点击左下角"用户名 - 升级账户"，进入企业认证页面
- ④ 分别填写企业主体信息和管理员信息（测试阶段以下信息不会进行核验，可随意填写，包括企业营业执照等材料）
- ⑤ 提交成功后，会显示提交成功的页面。
- ⑥ 登录管理后台，然后通过 [管理后台 - 生态 - 自建组织管理 - 组织详情 - 点击通过] 来"通过"企业审核。
# 4.1.2 登录 FinClip Studio
- ① 下载 请确保您的 FinClip Studio (opens new window) 版本是最新版本。如果不是，您可以下载我们最新版本的 FinClip Studio (opens new window)。
- ② 配置服务器 FinClip Studio 默认连接地址为 FinClip SAAS 环境。您需要将其更改为您的私有环境，然后登录。打开 FinClip Studio，点击左下角「登录 - 服务器配置 - 自定义服务器 - 输入访问 FinClip 服务的域名或 IP」：
- ③ 登录账户 服务配置完成后，输入"第 4.1.1 节"中准备的账户和密码，点击"登录"，即可完成 FinClip Studio 的登录。
# 4.1.3 登录 FinClip App
- ① 下载 iPhone 用户请登录 App Store 搜索「 FinClip (opens new window) 」下载。 Android 用户请点击「 下载链接 (opens new window) 」或前往「腾讯应用宝」、「Google Play 商店」下载最新版 FinClip APP。
- ② 下载 FinClip App 默认连接地址为 FinClip SAAS 环境。您需要将其更改为您的私有环境，然后登录。操作如下：
# 4.1.4 演示示例
如果您希望获取一些演示示例，可以通过以下方法下载；否则，可以跳过此步骤。
| 类型 | 名称 | 开发语言 | 下载地址 | 备注 |
|---|---|---|---|---|
| 小程序 | 示例小程序 | 微信原生语法 | https://gitee.com/finclip/miniprogram-demo | FinClip 示例小程序，可用于测试小程序中相关 API 和组件的能力 |
| SDK | Android SDK | Java | https://gitee.com/finclip/android-demo | Android 演示示例（实现初始化、打开小程序、自定义 API 等） |
| iOS SDK | https://gitee.com/finclip/ios-demo | iOS 演示示例（实现初始化、打开小程序、自定义 API 等） | ||
| PC SDK | https://gitee.com/finclip/finclip-desktop-demo | PC 端演示示例（实现初始化、打开小程序、自定义 API 等） |
# 4.2 验证方案
在POC验证过程中，优先验证主流程有助于在早期发现可能影响整个项目的重大问题。在确认主流程可行性后，再进行功能验证，可以避免在基础流程不可行时浪费资源测试具体功能。因此，本次POC的验证方案对主流程验证进行了详细描述。
# 4.2.1 主流程验证
为确保主流程验证的完整性，在此步骤中，请先使用我们提供的示例代码小程序。在您的App中运行我们的示例代码小程序，确保主流程完整无误后，再替换为您的小程序，最后进行相应的功能验证。
# 4.2.2 验证目标
通过FinClip小程序开放平台系统提供的能力，在目标软件App上正确运行FinClip示例小程序。
# 4.2.3 验证流程
# 4.2.4 验证步骤
# 4.2.4.1 创建小程序
| 类别 | 内容 |
|---|---|
| 测试编号 | M0001 |
| 测试项 | FinClip小程序数字管理系统 - 开发者门户 |
| 测试功能 | 创建小程序 |
| 前置条件 | 在浏览器上打开FinClip小程序平台 - "开发者门户"并成功登录。 |
| 测试步骤 | 1. 进入"小程序"目录，点击"新建"按钮，将弹出小程序文本框。 2. 依次填写"小程序名称"、"项目类型：选择Mini-Program"、"分类：选择工具"、"项目简介"、"项目描述"、"图标"等信息，点击"确认"创建小程序。 3. 点击新创建的小程序，查看详情，进入"信息详情" - "隐私设置" - "配置"，将弹出小程序数据政策。 4. 选择"不会以任何方式处理用户信息"并点击"确认"。 |
| 预期效果 | 1. 成功创建小程序后，进入"小程序"目录，可以从列表中查看刚刚创建的小程序。 2. 点击相应的小程序，可以查看其基本信息，包括名称、AppID等详情。 |
# 4.2.4.2 添加域名/IP白名单
| 类别 | 内容 |
|---|---|
| 测试编号 | M0002 |
| 测试项 | FinClip小程序数字管理系统 - 管理门户 |
| 测试功能 | 添加域名/IP白名单 |
| 前置条件 | 在浏览器上打开FinClip小程序开放平台 - "开发"并成功登录。 |
| 测试步骤 | 1. 进入"开发 - 域名"目录，点击"域名配置"按钮，将弹出域名管理输入框。 2. 在白名单输入框中，输入小程序需要访问的业务域名或IP，点击"确认"。 |
| 预期效果 | 1. 域名白名单配置成功。导航至"开发 - 域名"目录，可以查看相应的域名及白名单/黑名单。 |
# 4.2.4.3 创建小程序项目
| 类别 | 内容 |
|---|---|
| 测试编号 | M0003 |
| 测试项 | FinClip小程序开放平台管理系统 - FinClip Studio |
| 测试功能 | 创建小程序项目 |
| 前置条件 | 打开FinClip Studio并完成登录。 |
| 测试步骤 | 1. 打开FinClip Studio，点击「+」按钮，将弹出创建小程序页面。 2. 输入「项目名称」，选择「项目目录」，选择「小程序」类型，选择「模板」作为项目模板，点击右下角的「创建」按钮。 |
| 预期效果 | 1. FinClip Studio自动创建项目并进行编译。 2. 在FinClip Studio中，可以预览小程序示例模板。 |
# 4.2.4.4 上传小程序代码包
| 类别 | 内容 |
|---|---|
| 测试编号 | M0004 |
| 测试项 | FinClip小程序开放平台管理系统 - FinClip Studio |
| 测试功能 | 上传小程序代码包 |
| 前置条件 | 打开FinClip Studio并完成登录。 |
| 测试步骤 | 1. 点击FinClip Studio顶部的"上传"按钮，弹出小程序上传页面。 2. 选择AppID（即步骤1中创建的小程序ID），输入"版本号"，输入"描述"，点击"确认"。 |
| 预期效果 | 小程序上传成功，并弹出"上传成功"提示信息。 |
# 4.2.4.5 提交小程序审核
| 类别 | 内容 |
|---|---|
| 测试编号 | M0005 |
| 测试项 | FinClip小程序开放平台管理系统 - 开发者门户 |
| 测试功能 | 提交小程序审核 |
| 前置条件 | 在浏览器上打开FinClip小程序开放平台 - "开发"并成功登录。 |
| 测试步骤 | 1. 进入"小程序"目录，点击新创建的小程序，查看详情，进入"信息详情" - "版本" - "审核版本"。 2. 按照"提交审核" - "填写审核信息（可选）" - "确认信息" - "下一步" - "确认"的步骤提交审核。 |
| 预期效果 | 在审核版本中，可以查看审核版本信息和提交信息。 |
# 4.2.4.6 审核小程序
| 类别 | 内容 |
|---|---|
| 测试编号 | M0006 |
| 测试项 | FinClip小程序开放平台管理系统 - 管理门户 |
| 测试功能 | 审核小程序 |
| 前置条件 | 在浏览器上打开FinClip小程序开放平台 - "管理门户"并成功登录。 |
| 测试步骤 | 1. 进入「首页」-「待办事项」-「审核状态」，找到上述步骤中提交审核的小程序，点击「详情」，将弹出小程序审核页面。 2. 检查小程序信息，确认无误后，点击页面底部的「通过」按钮，审核成功。 |
| 预期效果 | 1. 小程序已通过审核，上述待审核小程序将从待办事项列表中移除。 2. 进入"开发者门户"，前往"小程序"目录，点击小程序查看详情，小程序状态将显示为"已通过"。 |
# 4.2.4.7 发布小程序
| 类别 | 内容 |
|---|---|
| 测试编号 | M0007 |
| 测试项 | FinClip小程序开放平台管理系统 - 开发者门户 |
| 测试功能 | 发布小程序 |
| 前置条件 | 在浏览器上打开FinClip小程序开放平台 - "开发者门户"并成功登录。 |
| 测试步骤 | 1. 进入<小程序>目录，点击新创建的小程序，查看详情，进入<信息详情> - <版本> - <审核版本>，点击<发布到线上版本>，将出现发布弹窗。 2. 选择<全量发布>，点击<确认>，小程序发布完成。 |
| 预期效果 | 刷新页面，小程序状态变为 - 已发布。 |
# 4.2.4.8 创建宿主应用
如果您没有宿主应用，可以跳过此步骤，直接前往第4.2.4.12节通过[方法二] FinClip App打开小程序预览。
| 类别 | 内容 |
|---|---|
| 测试编号 | M0008 |
| 测试项 | FinClip小程序开放平台管理系统 - 开发者门户 |
| 测试功能 | 创建宿主应用 |
| 前置条件 | 在浏览器上打开FinClip小程序开放平台 - "开发者门户"并成功登录。 |
| 测试步骤 | 1. 进入"宿主应用"目录，点击"新建"按钮，将弹出新建应用输入框。 2. 依次填写"应用名称"、"所属组织"、"简介"、"其他团队可见 - 否"、"应用自动关联小程序 - 是"、"上传图标"等信息，点击"确认"创建应用。 3. 进入"宿主应用"目录，点击"宿主应用名称"，进入"BundleID" - "添加BundleID"，将弹出添加BundleID的窗口。 4. 选择BundleID应用平台，此处选择"Android"/"iOS"，输入App的BundleID，点击"确认"完成添加。 |
| 预期效果 | 进入"宿主应用"目录，点击"宿主应用名称"，进入"BundleID"，可以看到新增了一条数据，在此可以查看API Server、SDK Key和SDK Secret等信息。 |
# 4.2.4.9 关联小程序
| 类别 | 内容 |
|---|---|
| 测试编号 | M0009 |
| 测试项 | FinClip小程序开放平台管理系统 - 开发者门户 |
| 测试功能 | 绑定小程序 |
| 前置条件 | 在浏览器上打开FinClip小程序开放平台 - "开发者门户"并成功登录。 |
| 测试步骤 | 1. 进入"宿主应用"目录，点击"宿主应用名称"，进入"绑定小程序" - "配置小程序"，将弹出编辑小程序的窗口。 2. 勾选已发布的小程序，点击"确认"完成小程序关联。 |
| 预期效果 | 进入"宿主应用"目录，点击"宿主应用名称"，进入"绑定小程序"，可以看到新增了一条数据，并查看绑定小程序列表。 |
# 4.2.4.10 集成SDK
| 类别 | 内容 |
|---|---|
| 测试编号 | M00010 |
| 测试项 | FinClip小程序开放平台管理系统 - FinClip SDK |
| 测试功能 | 集成FinClip SDK |
| 前置条件 | 拥有宿主App且具备可运行的源代码。 |
| 测试步骤 | 1. Android App集成 :Android集成指南 2. iOS App集成 :iOS集成指南 3. HarmonyOS App集成:HarmonyOS集成指南 4. 桌面应用集成 :PC集成指南 更多FinClip SDK指南，请参考 :FinClip SDK文档中心 |
| 预期效果 | App成功集成了SDK，集成后代码编译无错误，App编译打包等流程通过。 |
# 4.2.4.11 初始化SDK
| 类别 | 内容 |
|---|---|
| 测试编号 | M0011 |
| 测试项 | FinClip小程序开放平台管理系统 - FinClip SDK |
| 测试功能 | 集成FinClip SDK |
| 前置条件 | App已成功集成FinClip SDK |
| 测试步骤 | 1. Android SDK初始化:Android初始化指南 2. iOS SDK初始化:iOS初始化指南 3. HarmonyOS SDK初始化 :HarmonyOS初始化指南 4. 桌面SDK初始化 :PC初始化指南 更多FinClip SDK初始化指南，请参考 :FinClip SDK文档中心 |
| 预期效果 | FinClip SDK初始化成功。通过初始化SDK的API回调信息，返回初始化成功。 |
# 4.2.4.12 打开小程序
| 类别 | 内容 |
|---|---|
| 测试编号 | M0012 |
| 测试项 | FinClip小程序开放平台管理系统 - FinClip SDK |
| 测试功能 | 集成FinClip SDK |
| 前置条件 | 1. 小程序已成功发布。 2. App已集成FinClip SDK并初始化成功。 3. [可选] 已下载并登录FinClip App |
| 测试步骤 | [方法一] 通过宿主App打开小程序 1. Android App打开小程序步骤:Android打开小程序指南 2. iOS App打开小程序步骤:iOS打开小程序指南 3. HarmonyOS App打开小程序步骤:HarmonyOS打开小程序指南 4. 桌面端打开小程序步骤:PC打开小程序指南 更多使用FinClip SDK打开小程序的指南，请参考 :FinClip SDK文档中心 [方法二] 通过FinClip App扫码打开小程序 1. 获取小程序二维码：前往「FinClip管理后台 - 开发者门户 - 小程序 - 版本」查看二维码。 2. 打开FinClip App，进入首页，点击二维码扫描按钮，即可打开小程序。 |
| 预期效果 | 在App中打开小程序并进行预览 |
# 5. 参考资料
| 类别 | 资料名称 | 资料链接 |
|---|---|---|
| 开发者门户 | 操作手册 | 操作手册 (opens new window) |
| 操作视频 | 操作视频 (opens new window) | |
| FinClip SDK | iOS SDK指南文档 | SDK指南文档 (opens new window) |
| iOS SDK集成视频 | SDK集成视频 (opens new window) | |
| Android SDK指南文档 | SDK指南文档 (opens new window) | |
| Android SDK集成视频 | SDK集成视频 (opens new window) | |
| 桌面端SDK指南文档 | SDK指南文档 (opens new window) | |
| FinClip Studio | 小程序开发指南 | 小程序开发指南 (opens new window) |
| 用户手册 | 用户手册 (opens new window) | |
| 教学视频 | 教学视频 (opens new window) | |
| FinClip App | 操作手册 | 操作手册 (opens new window) |
| 常见问题 | 常见问题 | 常见问题 (opens new window) |
# 6. 总结
感谢您的体验。至此，FinClip小程序管理平台系统的POC主流程测试已完成，您可以继续对FinClip小程序管理平台系统进行功能验证。