dimagi/formplayer Docker 镜像 - 轩辕镜像

FormPlayer

概述

FormPlayer是一个基于Spring Framework开发的RESTful XForm录入服务。通过用户恢复和XForm，FormPlayer支持通过JSON调用和响应进行表单录入（详见下文）。这些文件通常由CommCareHQ服务器实例托管。FormPlayer依赖CommCare库（作为子仓库包含），并通过gradle构建（含包装器文件）。

核心功能和特性

• RESTful API：提供基于HTTP的JSON接口，支持XForm表单的录入与交互
• 多数据库支持：通过Redis缓存会话实例，Postgres存储会话实例，为每个恢复用户构建SQLite数据库
• CommCare集成：依赖CommCare-core库，与CommCareHQ服务器无缝协作
• 灵活构建：支持含测试或不含测试的构建方式，提供持续测试模式
• API文档自动生成：通过SpringFox插件生成Swagger API文档

使用场景和适用范围

适用于需要集成XForm表单录入功能的CommCareHQ环境，支持本地开发、Docker容器化部署及生产环境服务，满足表单数据采集、会话管理和用户数据隔离需求。

详细使用方法和配置说明

依赖环境

• Java (OpenJDK 8)
• Redis（用于缓存会话实例）
• Postgres（用于存储会话实例）
• SQLite（为每个恢复用户构建数据库）

构建与运行

基础步骤

1. 克隆仓库

   bash
   $ git clone [***]
   

2. 下载子模块依赖

   bash
   $ git submodule update --init --recursive
   

3. 创建属性文件

   bash
   $ cp config/application.example.properties config/application.properties  # 根据需要更新属性（默认值适用于本地运行）
   

   特别注意：确保server.port值与CommCareHQ的localsettings.py中FORMPLAYER_URL的端口一致。

4. 创建数据库 运行以下命令创建formplayer数据库（执行后需输入密码，本地运行时使用CommCareHQ本地Postgres用户的密码，可在localsettings.py的DATABASES部分找到）：

   bash
   $ createdb formplayer -U commcarehq -h localhost  # 根据需要更新连接信息（默认值适用于本地运行）
   

   若Postgres运行在Docker中，需在Docker shell中执行，可通过CommCareHQ仓库的./scripts/docker bash postgres命令进入。

运行命令

• 含测试运行

  bash
  $ ./gradlew build && java -jar build/libs/formplayer.jar
  

• 不含测试运行

  bash
  $ ./gradlew assemble && java -jar build/libs/formplayer.jar
  

• 测试命令

  bash
  $ ./gradlew test
  
  # 运行单个测试
  $ ./gradlew :test --tests tests.NewFormTests.testNewForm
  
  # 持续测试模式
  $ ./gradlew test -t
  

• Linux构建注意事项：有时需运行

  bash
  $ gradle wrapper
  

故障排除

• "Could not resolve project :commcare"
  运行git submodule update --init

• 编译错误（如"no suitable constructor found for OutputFormat(Document)"）
  可能是Java版本错误，执行java -version应显示1.8。解决方法：

  • 安装OpenJDK 8
  • 配置gradle使用新Java：
    • 更新~/.gradle/gradle.properties，添加org.gradle.java.home=/JDK_PATH
    • 或在gradle命令后附加-Dorg.gradle.java.home=/JDK_PATH

在IntelliJ中运行

为支持断点调试和源码关联，建议使用IntelliJ IDE：

1. 下载IntelliJ IDE
2. 打开IntelliJ，选择"导入项目"
3. 导航到克隆的formplayer仓库，选择根目录下的build.gradle
4. 取消勾选"使用自动导入"和"为空内容根自动创建目录"，勾选"使用gradle包装器"
5. 点击"确定"

注：也可使用Android Studio，步骤同上。

保持application.properties更新

application.example.properties可能会新增必要配置，更新代码后若遇错误，可运行：

bash
diff -u config/application{.example,}.properties

缺失的配置行以-开头。

在Docker中运行

若需将FormPlayer作为CommCare HQ的Docker服务运行，从CommCare HQ仓库执行以下步骤：

1. 检查是否为Mac系统，若是，直接按照上文构建和运行步骤操作。
2. 正常启动CommCare HQ的Docker服务：scripts/docker up（仅服务）或scripts/docker runserver（HQ及服务）。
3. 运行scripts/get_webhost，将输出添加到/etc/hosts（Linux用户可执行scripts/get_webhost | sudo tee -a /etc/hosts）。
4. 若本地运行Django版CommCare HQ：
   1. 更新localsettings.py：FORMPLAYER_URL = 'http://localhost:8010'和BASE_ADDRESS = 'webhost:8000'
   2. 启动Django：./manage.py runserver 0.0.0.0:8000
5. 此后通过[***]

贡献指南

• 普通PR：仅修改Formplayer仓库代码时，在单独分支提交PR至Formplayer。

贡献commcare代码变更

Formplayer依赖commcare-core仓库，该仓库master分支不稳定，Formplayer使用formplayer分支。子模块libs/commcare应始终指向formplayer分支。

更新CommCare版本

将Formplayer更新至CommCare新版本（如2.34→2.35）时，需从commcare_X.Y分支向formplayer分支提交PR。QA完成后合并PR并更新Formplayer子模块。

API文档

FormPlayer通过Spring的Swagger插件SpringFox自动生成API文档。启动服务器后，访问http://localhost:8080/swagger-ui.html#/（根据实际主机和端口调整）查看文档。