Specify Report Runner Service 技术文档

一、镜像概述和主要用途

Specify Report Runner Service 是一个围绕 Jasper Reports 库实现的轻量级 Web 服务包装器，专为 Specify 7 应用设计，用于报表和标签的生成与管理。该服务通过 Web 接口提供报表生成能力，无缝集成到 Specify 7 web 应用中，满足其报表功能需求。

二、核心功能和特性

• 报表与标签生成：基于 Jasper Reports 库，支持 Specify 7 所需的各类报表和标签生成。
• Web 服务包装：提供 HTTP 接口，便于 Specify 7 应用调用。
• 字体自定义：支持通过字体扩展 JAR 文件自定义报表字体，避免因字体缺失导致的显示异常。
• 条形码生成：集成 barbecue 条形码生成库，支持报表中的条形码渲染（需解决特定版本问题，详见“常见问题”）。
• 轻量部署：可通过 Maven Jetty 插件快速启动，或配置为系统服务长期运行。

三、使用场景和适用范围

适用场景

• Specify 7 应用环境中需要动态生成报表、标签的业务场景。
• 需在 Specify 7 web 界面中集成报表任务入口，供用户直接操作报表生成。

部署要求

• 安全性：服务无内置认证机制，需部署在与 Specify 7 服务器同一机器或私有子网，仅绑定内部不可路由地址，避免外部访问。
• 兼容性：需与 Specify 7（开发分支）配合使用，通过配置文件关联。

四、环境要求

• Java 环境：Java JDK ≥ 1.7。
• 构建工具：Apache Maven 2。

五、安装与配置

5.1 源码获取与编译

1. 克隆仓库：

   git clone <仓库地址>  # 替换为实际仓库地址
   cd report-runner-service
   

2. 编译项目：

   mvn compile
   

5.2 测试运行

通过 Maven Jetty 插件启动测试服务器：

mvn jetty:run

• 默认运行在 localhost:8080。
• 可修改 jetty.xml 调整端口和绑定地址（如更改监听接口以限制访问）。

5.3 Specify 7 配置

1. 编辑 Specify 7 开发分支的配置文件（通常为 specifyweb/settings/local_specify_settings.py），添加或修改以下参数：

   REPORT_RUNNER_HOST = "报表服务所在主机地址"  # 如 localhost
   REPORT_RUNNER_PORT = "报表服务端口"          # 如 8080
   

2. 重启 Specify 7 服务，Web 应用顶部任务栏将显示“报表”任务入口。

5.4 字体配置

问题说明

若报表中使用的字体未提供给服务，将默认使用内置 PDF 字体，可能导致显示异常（如文本截断、样式差异）。

配置方法

1. 创建字体扩展 JAR 文件（包含所需字体及变体：常规、斜体、粗体、粗斜体）。
2. 将字体扩展 JAR 文件复制到 src/main/webapp/WEB-INF/lib/ 目录。
3. 重新编译项目（mvn compile）使配置生效。

参考：创建字体扩展文件教程（按 iReport 说明操作时需包含字体变体）。

六、部署方案

6.1 作为 SystemD 服务运行

创建 SystemD 服务脚本（路径：/etc/systemd/system/specify-report-runner.service），内容如下：

[Unit]
Description=Specify Report Runner Service
Wants=network.target
ConditionPathExists=/home/specify/report-runner-service  # 替换为实际项目路径

[Service]
User=specify  # 替换为实际运行用户
WorkingDirectory=/home/specify/report-runner-service     # 替换为实际项目路径
ExecStart=/usr/bin/mvn jetty:run  # 启动命令

[Install]
Alias=ireportrunner.service

服务管理命令

• 启动服务：systemctl start specify-report-runner
• 设置开机自启：systemctl enable specify-report-runner
• 查看状态：systemctl status specify-report-runner

七、常见问题与故障排除

7.1 条形码文本缺失

问题描述

使用无头 JRE 运行时，barbecue 条形码生成库（版本 1.5-beta1）存在 bug，导致即使报表定义中启用了条形码文本显示，文本仍可能缺失。

解决方法

1. 克隆 barbecue 仓库并编译安装修复后的开发版本（1.9-dev）：

   git clone [***]
   cd barbecue/barbecue
   mvn compile
   mvn install
   

2. 修改本项目的 pom.xml，将 barbecue 依赖版本从 1.5-beta1 更新为 1.9-dev：

   <!-- 原依赖 -->
   <dependency>
       <groupId>net.sourceforge.barbecue</groupId>
       <artifactId>barbecue</artifactId>
       <version>1.5-beta1</version>
   </dependency>
   
   <!-- 修改后 -->
   <dependency>
       <groupId>net.sourceforge.barbecue</groupId>
       <artifactId>barbecue</artifactId>
       <version>1.9-dev</version>
   </dependency>
   

3. 重新编译项目使依赖生效：mvn compile。