TSS 开发指南

引言

它山石BI（简称TSS）是一个开源的B/S架构的数据管理平台，在线协同采集数据、集中清洗数据、自动分发数据，以数据为导向，兼顾流程，多级授权，提供一站式、全方位管理一个企业的数据的生成、分析、呈现、感知、流通、共享等综合解决方案。基于本软件开发数字化管理系统（BI）的开发人员及系统管理人员，可以但不限于：数据分析人员、程序员、软件公司管理人员、Excel高级用户、总经理助理等。

系统架构

系统部署

   硬件环境：CPU 双核+、内存1G+、硬盘10G+
   运行环境：JDK1.7/1.8 + Tomcat7 + MySQL，操作系统支持linux/mac os/windows
   浏览器：Chrome、FireFox、IE11、Edge等主流浏览器，推荐使用Chrome
   系统安装详细参考：http://www.boubei.com/doc/tss/manual/tss-install.html

服务器环境部署拓扑图

Getting Start

基于TSS的开发和使用过程大致如下：

  • 1、在TSS注册一个开发者账号，并用此账号登录（Admin账号也可以直接作为开发者使用）
  • 2、开发人员根据功能需求预先创建所需角色
  • 3、开始创建资源：数据表、数据服务、报表等
  • 4、将资源的访问及管理权限授给对应角色
  • 5、管理员创建用户人员（或由用户自己注册），并为其设置角色
  • 6、用户登录系统，访问已经开放的资源
打开登录界面，注册一个开发者账号（如果是独立安装TSS，跳过注册，直接使用Admin账号登录，Amdin拥有系统所有权限。初始密码: www.boubei.com ）.

注册完成后系统会自动登录（如果密码设置过于简单，系统会要求修改成更安全的密码后才允许进入系统）。你可以看到开发者所拥有的全部功能菜单，也可以看到其它开发者（如果存在的话）开发完成后发布出来的功能模块。下面开始你的开发之旅吧，如果你没任何开发经验，也不用担心，我们的软件和案例足够简单。
第一个开发案例可以参照：《BI案列-开发SAAS版营业记账》，可以在半小时内让您对TSS全貌有个大致的了解。

设置角色

资源和角色是TSS二次开发的两大主线，资源包括：数据表、数据服务、报表、栏目、门户导航、用户组织等，角色用来划分资源的权限，一个角色可以对应多个人。如果给某角色分配了某资源的操作权限，那么只有属于该角色的用户才能拥有此资源的操作权限。在一个企事业单位的人员组织里，角色通常等同于岗位，设置角色可以优先按照既有的岗位来设置。按岗位信息一一创建角色后，给不同岗位的人授予对应的角色，一个人可以有多个岗位。


在开发一个功能模块之前，开发者应该预先已经知晓：此功能的用户群体（角色）是谁。所以第一步我们先创建角色。打开【开发管理】下功能菜单【设置角色】，开始创建角色，下图示例：创建一个名为“老板”角色的截图。保存成功后，右边角色组下可以看到新建的角色节点。


更多角色（组）操作参考《TSS管理员手册》里《4.7章 授权管理》.


数据源

数据源定义及作用

数据源（Data Source）泛指存放数据的数据库服务器，可以是某个业务系统数据库，也可以是其备库、只读库，或者清洗库，数据库类型支持MySQL、Oracle、SQLServer、PostgreSQL等常见的关系型数据库。对TSS而言，数据源是查询、清洗、采集数据的先提条件，有了数据源，数据才得以被采集、被查询、被分发、被清洗、被重新写入；流程运转产生数据才能长久存放。可以说，数据源是一切数据活动的基础。

通常程序需要对数据进行读写操作时，需要先连接数据源指向的数据库，获取连接后再通过连接来读取或写入数据，提交事务后再释放连接。 但这个过程比较耗时。连接池的作用是把使用完的数据库连接缓存起来，需要用的时候直接从池里返回一个连接，使用完成后再释放回池里，避免重复创建。 TSS的连接池使用的自身的“对象缓存池管理”模块，可以方便的在创建数据源的同时完成数据库连接池的创建。

管理数据源

从顶部菜单打开《开发管理》--> 《数据源》，进入数据源管理界面。进入后会默认打开一个空表单，可以直接开始填写创建数据源。填写完成后可以先进行测试，能否成功连接。如果可以连接成功，则可以点【保存】按钮，完成数据源的创建。保存成功后，左边的列表里多出一个数据源。同时在《开发管理》→ 《缓存监控》，可以看到新建数据源对应的连接池，如下图：

点击左侧数据源列表中的需要修改的数据源，或者右键点击数据源选择【修改数据源】。会打开一个和新建界面一样格式的编辑界面，可以对其中某些配置项进行修改。修改完，点【保存】成功后，系统会自动更新数据源对应的连接池：销毁池中已存在的连接，然后重新初始化连接池。（可能有连接正在执行SQL中，此时系统会等待执行完成被释放后再销毁）。

右键点击要删除的数据源，选择【删除数据源】，系统提示是否确认删除，点击确定完成删除。删除后此数据源对应的连接池也将被移除。

数据库连接池

在上一章节里我们创建数据源时，指定了数据源连接参数信息：最大连接个数、连接有效期、初始化连接个数、等待时间。这些参数被用在了连接池初始化及运行：

  • 最大连接个数：限定了能同时获取到的最大连接数，防止系统无限消耗数据库资源
  • 连接有效期：连接超过有效期即被销毁，防止僵尸连接出现
  • 初始化连接个数：系统启动时，即开始初始化少量的连接个数，以便及时调用
  • 等待时间：当连接都被占用时，且个数已到达阈值（即无法再生成新的连接），当前请求无法获取到连接，开始进行等待状态，如果超过等待时间还是没有连接被返回池中，则抛出异常提示，提醒系统管理员当前连接池资源紧张，此时管理员可以对连接池的参数进行针对性调整。
下面截图来自一个访问并发比较高的系统，以便更好说明如何监控连接池：
可以看到该系统维护了多个连接池，通过观察最后一列【忙碌中】，可以看到每个连接池中处于忙碌状态的个数，如果其个数长时间接近或等于【池容量】，则说明该连接池处于非常忙碌状态。有两种可能会导致这种情形出现：
  • 1、并发访问量大，这种情形优先考虑增加【池容量】，以支持更多的并发量。
  • 2、连接单次占用时间很长，甚至迟迟不能被释放，比如有些SQL语句查询性能出现问题（SQL欠优化、索引异常、死锁等都有可能是诱因），此时连接始终被这些耗时的SQL占用着，直到耗尽所有连接。这种情形体现在缓存监控面板里，数据列【命中占时(微秒/次)】的值会逐渐变大。此时加大【池容量】也只能延缓系统奔溃，无法根本上解决问题。需要尽快找出是哪些SQL挂住，可以求助DBA，或者观察TSS的另一个《量能监控》面板（详细参考后面介绍《量能监控》面板的章节），找出后，停用关闭耗时SQL所属的数据服务，待优化后再重新启用打开服务。

当数据库异常（数据库宕机、网络异常、账号异常）时，系统将无法获取连接，这种情形如果目标数据库没有有效的超时机制，会导致系统请求一直处于等待连接生成中，进而耗尽系统线程资源，此时应紧急停用“问题数据源”，直至数据库访问恢复正常，再重新启用该数据源。

在“缓存监控”界面左侧的缓存池列表里，右键点击选中要变维护的缓存池，选择【维护缓存策略】，界面将打开该缓存池的明细信息，及缓存策略，如下图：
在缓存池明细里，我们可以查看每个具体连接的被使用情况：存活时间、命中次数、状态（空闲|忙碌），如果是忙碌状态的话还可以看出当前一次任务持续执行的时间。 在缓存策略的弹出表单里，可以看到该连接池的详细配置参数。参数修改保存后，连接池将被会做相应更新。把策略状态设为【停用】，然后保存，此后将无法再从此连接池获取任何连接，如果尝试连接系统会弹框提示数据源正在停用维护中。


数据报表&服务

报表定义

点击： 《TSS 报表开发》 定义

报表开发维护

点击： 《TSS 报表开发》 新建报表

报表可视化定制

点击： 《TSS 报表开发》 报表可视化

数据分发与共享

点击： 《TSS 报表开发》 数据分发与共享

远程访问令牌

TSS集成了数据报表和数据表，这两个模块可以方便对数据进行全方位管理。一个报表的数据服务就是一个独立的读取数据的API，其查询出来的数据既可以用于TSS系统内的报表的分析展示，也可以对外开放给第三方系统访问。同样，第三方系统也可以通过数据表的接口往数据表写入、修改、删除数据，也可以获取数据表数据记录包含的附件、日志等信息。 TSS的定位之一是成为一个数据中枢系统，统一协调各类外围系统对数据进行管理及流转。

TSS同时本身也是一个门户系统，需要协同外围业务系统进行单点登录（SSO）等操作。但基于安全考虑，通常我们不允许第三方系统直接访问TSS的接口API，访问前需要先进行必要的认证。TSS通过对第三方系统发放令牌（Token）来完成这一认证。大致步骤如下：

  • 1、第三方系统在TSS注册一个账号，TSS管理员为新账号设置相应的角色，使其有权限访问所需资源（eg: 对数据服务的查看权限，对数据表的录入/浏览权限）
  • 2、TSS管理员进入“开发管理/令牌管理”页面，新增一个令牌记录
  • 3、用户即第1步里注册的账号，令牌类型分：数据服务、数据表、单点登录、软件许可证（License）
  • 4、资源为具体报表或数据表的ID或名称（英文名、且要唯一）
  • 5、令牌Token自动生成，新建时可以自行填入；新建完成后令牌不能再修改
  • 6、过期时间，即令牌的有效期，超过该时间，令牌自动失效
  • 7、保存成功后，将生成的令牌复制并交给第三方系统用户，即可开始正式接口调用
访问示例参考api-tss.html

注1：如需匿名访问资源，则把令牌和资源权限分别授予匿名用户（Anonymous） 和 匿名角色。
注2：可直接用uName的在um_user表里存放的authToken作为uToken，无需要单独创建令牌，只需该uName有资源的相应权限即可（适用于小程序、APP等注册用户，注册时即自动生成令牌）。
注3：如何实现将报表框架页report_portlet.html和 数据表框架页recorder.html直接嵌入到第三方系统？ 利用LtpaTokenIdentifier（uName + uToken）自动登录后跳转，示例如下： http://ebi.boubei.com/tss/auth/login.do?identifier=com.boubei.tss.um.sso.othersystem.LtpaTokenIdentifier &username=JXX&sso=true&LtpaToken=C4E5EC65C90C73A0B7B6D413CEADA9E5&fromApp=OT&sso=true&target=/tss/modules/dm/recorder.html?id=12


数据表

数据表定义

点击： 《TSS 数据表开发》 数据表定义

数据表开发

点击： 《TSS 数据表开发》 数据表开发

数据表自定义页面

点击： 《TSS 数据表开发》 数据表自定义页面

数据表与Excel

点击： 《TSS 数据表开发》 数据表与Excel

附件管理

数据表通常都会有上传附件的需求，为此专门定义了属性为“附件”的字段类型。描述一条附件信息很简单：存放目录、附件名称、属于哪张数据表的哪一行记录。据此TSS提供了一个统一的“附件管理”功能，目的是对所有附件进行集中存放、提供统一的管理界面。任何数据表只要设置“是否上传附件”为“是”，即会自动加上附件上传功能。通常可以在编辑Form里或Grid列表右键菜单里打开如下图的附件管理界面：
上传一个附件的步骤如下:

  • 1、选择文件（本地电脑上）
  • 2、点按钮【上传附件】
  • 3、【查看】上传结果，查看图片、PDF会直接在网页里打开，其它类型附件（如Excel文档）等需要下载后，本地电脑上打开
  • 4、对传错或异常的附件可以【删除】
    • 上传附件的窗口界面，除了可以数据表里打开以外，也可以在自定义录入页面里单独打开。


    数据清洗（ETL）

    ETL概述

    TSS通过连接数据源对数据进行访问，但很多时候，数据源里的数据是原始的业务数据，存在数据量大、结构不友好、数据分散在多个数据源、数据格式不统一、无法进行关联运算等问题，增加了日常数据分析工作的难度。这要求我们建立一个设计合理、结构友好的清洗库，然后所有的分析工作都基于清洗库展开。把散落在多个数据源中的原始业务数据抽取出来，加以清洗，再存到清洗库的过程，就是TSS ETL的过程。

    TSS支持自动定时从数据库、文件、Restful Webservice抽取数据，支持在线配置ETL任务，也支持通过编写扩展代码来定制ETL。下面两节，侧重介绍通过定时器和ETL任务，来完成数据的清洗。

    定时器（JOB）管理

    TSS系统有很多定时器类，配置出不同种定时器执行着各种周期性的操作，可在【开发管理】/ 【定时Job】下查看系统自带的部分定时器。这其中负责ETL任务调度的有下面两个，这两个Job类分别可以配置多个不同触发时间和不同间隔时间的定时器。

    • ByDayETLJob：用于执行按天定时抽取汇总数据的ETL任务，适合抽取汇总数据；
    • ByIDETLJob： 用于不定时按数据ID进行抽取的ETL任务，适合同步明细数据；

    ETL任务开发

    开发流程可以参考如下流程步骤：

    • 发起任务申请：填写申请表单，同时提供任务用途、抽取逻辑设计、目标表结构设计（含建表语句）等信息内容，设计文件可以是思维导图、文件等，通过附件上传到任务申请记录下；
    • 管理员审核：管理员评估设计的合理性，决定是否开启该任务，是否需要进一步改进；
    • 开启任务：状态置为“opened”，同时为该任务指定一个任务管理员，由其监控运维ETL任务的运行。日后运行中出现异常都会有邮件推送给任务管理员。
    • 手动执行任务：ETL任务通常由Job触发，但也允许手动运行（调试或补数据）。右键点击ETL配置行，选择【立即执行】；
    • 关闭任务：如果ETL任务审批不通过，或者ETL任务已经过期，无需再继续运行，则把ETL任务状态置为“closed”。

    ETL示例

    按天抽取（日结汇总数据）

    本示例的是将存放在扩展库的记账明细数据按天汇总后，存入到清洗库的对账表里。任务每天凌晨一点执行，第一次从2017-03-01开始汇总，当某一天汇总数据抽取完成后，会记录一条日志，下次执行任务的时候会先比对日志，只对日志里尚无记录的日期进行抽取。本任务设置的“重复更新天数”为7天，所以每次执行都会强制重复抽取最近7天的数据，逐日更新至清洗库，先按天删除（参照前置操作里的SQL），再按天重新写入新数据。

    • 0、定时器需要选择ByDayETLJob的实例（定时器管理里查找【Job执行类】 = com.boubei.tss.dm.etl.ByDayETLJob）；
    • 1、输入定义里select的字段的个数和顺序要和输出定义里insert语句的问号个数及顺序一致；
    • 2、优先级 值越大的任务在同一个定时JOB里优先被执行；
    • 3、重复更新天数 适合数据被抽取后还有会更新的情形，上面截图里示例，是假设数据在7天后趋于稳定，所以7内每天抽取时需要不断覆盖更新，更新前执行前置操作，清除某天已经存在的数据重新插入。

    按ID抽取（流水明细）

    此任务每60分钟运行一次，将明细数据从本地库抽取到清洗库，第一次抽取从ID=0开始，往后每次执行任务只抽取（ID > 清洗库表已存在的最大ID）的数据。

    • 0、定时器需要选择ByIDETLJob的实例（定时器管理里查找【Job执行类】 = com.boubei.tss.dm.etl.ByIDETLJob）；
    • 1、输入定义里必须要一个叫id的字段，需要按其从小到大进行排序；
    • 2、输入定义里 select 出来的字段不能有重名，因要分页查询；
    • 3、前置操作里，max(id) 必须命名为 maxid；
    • 4、初次抽取时，以“起始任务ID”作为起始条件，后续用前置操作里查询出来的maxid；如果人为修改了起始任务ID，使其大于maxid，则优先用“起始任务ID”；
    • 5、输入定义里select的字段的个数和顺序要和输出定义里insert语句的问号个数及顺序一致；
    • 6、优先级 值越大的任务在同一个定时JOB里优先被执行；


    功能发布及维护

    功能模块发布

    开发者开发完成一个模块的各个功能点，并且把各个功能的权限授予特定的角色。此时有两种方式可以把功能推给用户使用，一种是由系统管理员为每个用户设置相应角色，这样可以快速上线新功能，比如一次开发一个报表，然后快速开放给相应角色人员使用，适合私有部署的场景。

    第二种是SAAS模式下，功能以模块化的形式开发和发布，即不只是一个报表或数据表，而是一组。开发完成后，可以对这一组的报表或数据表进行打包发布，由用户自行选择是否要选用。例如：开发者A开发完成一个《进销存管理》模块，里面包含了老板、客服、客户等多种角色，很多中小型企业都可以使用该模块，但每一个企业域下，需要能自行管理自己的人员结构及岗位。同样，开发者B开发了一个《项目管理》模块，需要使用该模块的用户群体可以自主选择此模块，并自行设置人员角色。

    第一种情况，整个TSS系统就是一个完整模块，无需发布模块；
    第二种情况，一个模块相当于一个独立的子系统，是一组角色、数据表、报表的功能总集，系统可以包含多个模块，用户可以按需选择自己所需的模块，详细例子可以参照 《BI案列-开发SAAS版营业记账》。

    模块发布步骤如下：

    • 1. 进入《功能发布》，点击【新增】按钮；
    • 2. 填写模块名称、归类；
    • 3. 勾选角色集：此模块所包含的角色，多选；
    • 4. 资源文件，报表和数据表的定制模板，可以是目录路径或文件路径,如多个路径用逗号分隔，路径为相对路径(相对于Tomcat/webapps/tss)，比如:pages/wms;
    • 5. 设置状态，分开发中、已发布、关闭三种状态，只有【已发布】状态的模块可以被用户使用；
    • 6. 完成点【保存】
    当开发者发布完成一个模块后，可以被其它注册用户（企业用户、个人用户、开发者）登录系统后看到，如下图： 用户如果想体验某个模块的功能，则点击【我要试用】，将被自动赋予模块所含的角色集，从而拥有这些角色用户的资源试用权限。如果是在第三方TSS平台试用模块，试用满意可以下载该模块，然后导入到自建的TSS平台，成为自己的私有模块，可以自由的进行二次定制，轻松解决SAAS服务难以定制化的问题。

    模块如果包含资源文件，则导出文件是一个zip压缩包；如果没有资源文件，则是一个json文件，里面包含了模块所包含的报表、数据表、角色、权限等配置信息。

    量能监控面板

    模块发布完成后，我们可以通过量能监控面板来监控模块各个功能的使用量及性能。BI系统的访问量通常会很大，而且还分峰谷，如下图的分时图表看，每天早九点查询量最大，然后整个白天查询量保持平稳，晚上开始下降，凌晨只有零星的查询。查询高峰期间，系统资源（数据库服务器、应用服务器、系统连接池等）会比较紧张，如果出现系统异常（页面打不开、查询响应缓慢等），则第一时间可以打开“量能监控”进行诊断。

    “量能监控”可查看当前正在执行中的数据查询请求，面板上方的“运行中监控”里可以看到请求的详细信息：服务名称、访问参数、访问人、重复访问次数、已运行时间、访问连接的数据源、查询结果的缓存策略（分按参数缓存、按参数+用户缓存、不缓存）、服务的开发者等。其中“已运行时间”越长的，说明该服务出现异常的可能性越大，这个时候就要单独去检查该服务查询脚本是否需要优化、数据源是否存在异常（数据库资源紧张、索引失效等），并尽快排除异常。如无法尽快排除异常，且已严重占用服务器资源（并发线程、数据库连接），则需要考虑先停用该数据查询服务，直至异常排除后再重新启用。
    上图的下半部分的图表显示的是当前分时访问统计情况，两条折线分别是“访问速度”和“访问次数”。访问速度是该时段所有访问次数的耗时求和再除以总访问次数得出的结果，单位是秒。通常访问速度会随着访问次数的上升而下降（图里体现的是访问耗时变大，即访问速度下降），当某一个时段访问耗时明显高于均值时候，需要进一步查看该时段的具体访问日志，查出最慢的是哪些查询服务，检查是否有改进的空间。
    如下图，点【数据服务】访问明细，及可以看到当天查询相应时间最长的数据服务，分别是哪些服务名称、访问参数、访问时间、访问人等信息。
    在右边部分底部，还可以看到近15天的按天统计的“访问速度”和“访问次数”图表，可以依据各自的走势判断访问量是否增长很快及访问速度是否随之在逐渐变慢，是的话需要尽早最好优化或升级硬件机器等设备。
    监控面板的左侧显示的当天（也可以点【设置条件】查询任意时间段）系统数据服务整体运行情况：服务名称、最长时长、平均时长、访问次数、超时次数（单次访问超过3秒即定位超时），按平均时长从高到低排序。平均时长越长，超时次数越多的数据服务，即是最优先需要完善的。点击左侧行，右边底部显示出改行数据服务的分时统计报表，如下图，从中可以看出该数据服务的访问次数及访问速度的走势。
    上面介绍的是对数据报表的监控，量能监控面板总共有三套监控主题：

    • 数据报表：监控数据报表&服务的访问次数及性能；
    • 数据录入：监控数据表录入数据的数量及参与人数；
    • 数据ETL：监控数据ETL抽取的数据量及ETL任务的执行性能

    邮件服务器设置

    开启系统邮件推送功能，则首先需要有一个自己的邮件服务器，可以是私有邮件服务器，也可以是三方的邮件服务器（如163邮件服务器、阿里云邮件服务器等）。

    打开【开发管理】/【系统初始化】功能菜单，找到如下图的配置项填写邮件服务器配置： 配置示例: 邮件服务器地址 | 发件人 | 收件人 | 邮件服务器认证账号 | 邮件服务器认证密码
    配置好邮件服务器后，可以在任意TSS的前台HTML页面的控制台里测试邮件服务器发送是否正常: 

    $.post("/tss/auth/message/email2", {"receivers": “xxx@xx.com”, "title": “test email”, "content": “just test”});
    在TSS里，邮件推送功能可以使用在诸多场景中：
  • 订阅/推送报表；
  • 数据数据表，数据在流转过程中可以发相应邮件来提醒相应的人；
  • 系统监控：当系统有异常（比如定时ETL任务执行出错、服务器资源紧张等），可以邮件发送给系统管理员，提醒他们尽快处理；
  • 任意前后台自定义代码里（JS或JAVA）。
    •

    系统使用反馈

    该模块的目的是方便的收集各类用户的使用反馈，以进一步完成TSS。反馈类型包括系统异常、改进意见、吐槽等，内容可以是文件描述或上传截图等形式，系统管理员在看到反馈后，可以对其进行回复，告知反馈者处理进度及处理结果。反馈者再次打开该模块后可以看到自己提交的所有反馈及处理进展。


    获得帮助：boubei@163.com  TSS社区： http://bbs.boubei.com ，QQ群：162875668