frankframework/frank2example

Frank!Framework 示例镜像文档

一、镜像概述和主要用途

该镜像为 Frank!Framework 的官方示例镜像，用于快速部署和演示基于 Frank!Framework 的集成应用。Frank!Framework 是一个开源企业集成框架，遵循企业集成模式（EIP），支持构建灵活、可配置的系统集成解决方案，适用于服务编排、数据转换、协议适配等场景。本示例镜像包含预配置的演示应用，可直接运行以展示框架核心能力，同时支持自定义配置扩展。

二、核心功能和特性

2.1 核心功能

• 多协议支持：原生支持 HTTP/HTTPS、JMS、FTP/SFTP、SMTP、JDBC 等多种通信协议，满足跨系统数据传输需求。
• 数据格式转换：内置 XML、JSON、CSV、EDI 等格式的解析与转换工具，支持自定义转换器。
• 集成模式实现：覆盖路由、过滤、聚合、拆分、重试等 40+ 企业集成模式（EIP），简化复杂业务流程设计。
• 可视化配置：通过 Frank!Console 管理界面可配置集成流程（无需编码），支持热更新配置。

2.2 镜像特性

• 开箱即用：包含预配置的示例集成流程（如 HTTP 路由、XML-JSON 转换），无需额外配置即可运行。
• 轻量级部署：基于 Java 运行时，镜像体积优化，支持容器化快速启动。
• 可扩展性：支持挂载自定义配置文件（如 FrankConfig.xml）、依赖库，扩展集成能力。
• 监控与日志：集成日志系统，支持输出 JSON 格式日志，便于集成外部监控工具（如 Prometheus）。

三、使用场景和适用范围

3.1 典型使用场景

• 企业系统集成：连接 ERP、CRM、数据库等异构系统，实现数据同步与业务流程自动化。
• 微服务通信：作为微服务间的集成层，处理服务路由、协议转换（如 HTTP 转 JMS）。
• API 网关：接收外部 API 请求，进行认证、限流、数据转换后转发至后端服务。
• 数据迁移：批量处理文件传输（FTP/SFTP）、数据库数据抽取与加载（ETL 简化场景）。

3.2 适用范围

• 开发人员：学习 Frank!Framework 集成模式、调试自定义配置。
• 测试环境：快速搭建集成流程原型，验证跨系统交互逻辑。
• 小型项目：直接部署预配置镜像，通过修改配置文件适配简单集成需求。

四、使用方法和配置说明

4.1 环境要求

• Docker 1.13+ 或 Kubernetes 1.10+
• 至少 512MB 内存（推荐 1GB+）
• 网络访问：允许容器暴露端口（默认 8080）

4.2 快速启动

4.2.1 拉取镜像

bash
docker pull docker.xuanyuan.run/frankframework/example:latest

4.2.2 运行容器（基础示例）

bash
docker run -d -p 8080:8080 --name frank-example docker.xuanyuan.run/frankframework/example:latest

• 说明：容器启动后，Frank!Framework 示例应用将运行在 http://localhost:8080。访问 http://localhost:8080/frankconsole 可打开管理界面，查看预配置的示例流程（如 HelloWorld 流程）。

4.2.3 docker-compose 配置示例

创建 docker-compose.yml 文件：

yaml
version: '3'
services:
  frank-example:
    image: docker.xuanyuan.run/frankframework/example:latest
    ports:
      - "8080:8080"  # 应用端口
      - "8000:8000"  # 调试端口（可选）
    environment:
      - LOG_LEVEL=INFO  # 日志级别：DEBUG/INFO/WARN/ERROR
      - MAX_THREADS=20  # 最大工作线程数
    volumes:
      - ./custom-config:/opt/frank/config  # 挂载自定义配置文件（可选）
      - ./logs:/opt/frank/logs  # 挂载日志目录（可选）
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

4.3 配置参数说明

4.3.1 核心环境变量

4.3.2 自定义配置文件挂载

若需修改集成流程或扩展功能，可通过挂载配置目录覆盖默认配置：

1. 本地创建配置目录（如 ./custom-config），放入自定义 FrankConfig.xml（流程定义）、deploy.properties（部署参数）等文件。
2. 启动容器时挂载目录：

bash
docker run -d -p 8080:8080 -v $(pwd)/custom-config:/opt/frank/config docker.xuanyuan.run/frankframework/example:latest

• 说明：配置文件修改后无需重启容器，Frank!Framework 会自动检测并加载更新（默认检测间隔 30 秒）。

4.4 访问示例流程

容器启动后，可通过以下路径访问预配置的示例流程：

• HelloWorld 流程：http://localhost:8080/HelloWorld，返回 JSON 格式响应 {"message": "Hello from Frank!Framework"}。
• XML 转 JSON 示例：发送 POST 请求至 http://localhost:8080/xml-to-json，请求体为 XML 数据（如 <root><name>test</name></root>），响应为转换后的 JSON。

4.5 日志与监控

• 查看日志：通过 docker logs -f frank-example 查看实时日志；或挂载日志目录（如 ./logs），日志文件位于 logs/frank.log。
• 监控接口：访问 http://localhost:8080/health 获取应用健康状态（JSON 格式），包含内存使用、线程数等指标。

五、扩展与自定义

5.1 添加依赖库

若需使用额外 Java 依赖（如数据库驱动、自定义转换器），可将 JAR 包放入本地目录（如 ./libs），通过挂载方式添加至容器类路径：

bash
docker run -d -p 8080:8080 -v $(pwd)/libs:/opt/frank/lib docker.xuanyuan.run/frankframework/example:latest

5.2 构建自定义镜像

基于示例镜像扩展，创建 Dockerfile：

dockerfile
FROM docker.xuanyuan.run/frankframework/example:latest
# 添加自定义配置
COPY ./custom-config /opt/frank/config
# 添加依赖库
COPY ./libs/*.jar /opt/frank/lib/

构建并运行：

bash
docker build -t my-frank-app:1.0 .
docker run -d -p 8080:8080 docker.xuanyuan.run/my-frank-app:1.0

六、注意事项

• 生产环境建议通过挂载配置文件和日志目录，避免配置丢失和日志溢出。
• 高并发场景需调整 MAX_THREADS 环境变量，或通过 -e JAVA_OPTS="-Xmx1g" 增加 JVM 内存。
• 示例镜像包含演示数据，生产部署前需清除或替换为实际业务配置。