功件树

Jamobo2_v1.0.12.0 / README.md

#### 概况
本项目为Web项目，使用Java/Jsp＋MongoDB＋Bootstrap开发，包含初始化安装、用户注册登录和授权、用户角色权限管理、MongoDB事务处理、日志以及JUnit单元测试等功能。

用户访问本项目部署的网站时，通过网站根目录中的index.jsp来判断是否进行过初始化安装配置；如果未进行初始化配置，则进入“安装配置页”，否则进入网站“首页”。

本项目为第一个基于FunctreeX2功件规范开发功件树和功件的范例，所包含功件的对外方法（接口）完全参照FX2规范要求开发。

本项目JDK版本为8.0以上，MongoDB版本为3.2以上，Bootstrap版本为3.3.5，默认MongoDB数据库配置如下：dbHost = "localhost", dbPort = 27017, dbName = "jamobo", dbUser = "jamoboUser", dbPassword = "jamoboPwd"，依赖包如下：commons-fileupload-1.3.1.jar、commons-io-2.5.jar、mail.jar、mongo-java-driver-3.2.2.jar、fastjson-1.2.20.jar、log4j-api-2.8.1.jar、log4j-core-2.8.1.jar。

MongoDB启动时，需要增加“auth”选项来开启用户认证；在开启“auth”前，使用如下示例在MongoDB中创建用户：
```shell
use admin
db.createUser({user:'userAdmin',pwd:'adminPwd',roles:[{role:'userAdminAnyDatabase',db:'admin'}]})
use jamobo
db.createUser({user:'jamoboUser',pwd:'jamoboPwd',roles:[{role:'readWrite',db:'jamobo'}]})
```

#### 功件位置
根据FunctreeX2功件规范要求，创建的所有功件相关的程序文件均位于f目录（包）下，功件树根目录src中包含的是网站程序的底层功件，web中包含的是显示层功件，网站程序依赖的Jar包，根据Servlet应用要求放置于web目录下的WEB-INF/lib目录；test中则是单元测试部分的功件，不属于网站运行程序。

#### 功件说明
项目中的X功件为公共类，包含数据库访问以及初始化配置信息，同时其还是一个ServletFilter，处理URLRewrite和网页字符集设置相关功能；XPage功件为Web首页，其中包含了前端程序需要的程序库以及页头、页尾，其中网页链接中的x参数的处理，有“页头（PageHeader）”子功件来完成，页头子功件为所有显示网页功件的包含页，包含了页面公共导航条的处理和显示，页尾子功件（PageFooter）为所有显示网页功件的包含页，包含了网站版权信息、联系我们等。

Setup和SetupPage功件为初始化安装部分底层和显示层功件，User和UserPage功件是网站用户注册、登录、信息展示相关的底层和显示层功件，AlertPage功件则用于全站点的信息展示页面。

Role功件为系统用户角色相关功件，Permission为系统权限相关功件，包含了初始化数据和相关方法，为UserPage中的角色管理等提供底层访问方法。

Authorization功件用于用户的授权管理相关功能，包括用户是否登录的检查、用户登录成功后的授权信息产生、获取和清除，用户授权信息保存在内存Cache中，所以本项目适合于单机部署，未来通过升级Authorization功件可适用于分布式部署。

项目中的网页类型功件之间调用链接，遵循FunctreeX2功件规范中的一级接口原则，即仅通过功件主文件互相访问，只有一个请求参数x，参数值为一个JSON格式的字符串，例如：
- 访问“提示页”功件的链接
```html
AlertPage?x={'$a':{alertMessage:'提示信息。'}}
```
- 访问“用户页”功件中的注册页面的链接
```html
UserPage?x={'$a':{}}
```
- 访问“用户页”功件中的登录页面的链接
```html
UserPage?x={'$f':{'$n':'Login'}}
```
- 访问“用户页”功件中的忘记密码页面的链接
```html
UserPage?x={'$f':{'$n':'ForgotPassword'}}
```
- 访问“用户页”功件中的用户列表页面的链接
```html
UserPage?x={'$b':{}}
```

在test功件树根目录下的功件，为单元测试需要的功件，不属于网站运行程序，其中用户测试功件（UserTest）是用户功件的关键点测试，而全测试功能（XTest）除了包括用户测试相关内容，还包括MongoDB的事务测试内容。

#### 使用Docker安装本项目程序的说明
下面以CentOS7.2为例，对Docker安装本网站应用程序的步骤进行简要说明：
- 安装Docker：
  - 使用yum命令安装Docker：
```shell
yum install docker
```
  - 将Docker设为开启自启动服务：
```shell
systemctl enable docker.service
```
通过下列方法启动和停止Docker服务：
```shell
systemctl start docker.service
systemctl stop docker.service
```
  - 查看Docker版本、信息和帮助：
```shell
docker version
docker info
docker help
```

- 下载MongoDB、Tomcat镜像：
  - 下载镜像：
```shell
docker pull functree/mongodb:3.4.2
docker pull functree/tomcat:8-jre8
```
  - 查看镜像：
```shell
docker images
```

- 创建MongoDB、Tomcat容器：
  - 首先在本地建立目录：/data/mongodb/db，作为MongoDB数据库存储地址，然后创建并启动临时MongoDB容器，此容器在退出后会自动删除：
```shell
docker run --rm --name mongodb -p 127.0.0.1:27017:27017 -v /data/mongodb/db:/data/db functree/mongodb:3.4.2
```
  - 保持上述临时MongoDB容器的启动窗口，另开一个终端窗口，使用下列命令进入临时MongoDB容器：
```shell
docker exec -it mongodb /bin/bash
```
  - 在临时MongoDB容器中，键入下列命令，进入MongoDB：
```shell
mongo
```
  - 进入MongoDB后，在MongoDB中键入下列命令，创建两个MongoDB账号：
```shell
use admin
db.createUser({user:'userAdmin',pwd:'adminPwd',roles:[{role:'userAdminAnyDatabase',db:'admin'}]})
use jamobo
db.createUser({user:'jamoboUser',pwd:'jamoboPwd',roles:[{role:'readWrite',db:'jamobo'}]})
```
  - 键入exit退出MongoDB，再次键入exit退出上述临时MongoDB容器，此容器将自动停止并删除。然后通过下列命令创建并启动名称为“mongodb”的MongoDB容器，作为Tomcat的连接数据库：
```shell
docker run -d --name mongodb -p 127.0.0.1:27017:27017 -v /data/mongodb/db:/data/db functree/mongodb:3.4.2 --auth
```
  - 在本地建立目录：/usr/local/tomcat/webapps，作为Tomcat的Web程序部署地址，然后创建并启动Tomcat容器：
```shell
docker run -d --name tomcat -p 80:8080 -v /usr/local/tomcat/webapps:/usr/local/tomcat/webapps --link mongodb:mongodb functree/tomcat:8-jre8
```
  - 使用下列命令进入Tomcat容器，可根据需要修改Tomcat的server.xml或catalina.sh文件：
```shell
docker exec -it tomcat /bin/bash
```
  - MongoDB、Tomcat容器创建并启动成功后，建立/usr/lib/systemd/system/docker_mongodb.service和/usr/lib/systemd/system/docker_tomcat.service这两个文件，其中/usr/lib/systemd/system/docker_mongodb.service文件内容如下：
```shell
[Unit]
Description=mongodb container
Requires=docker.service
After=docker.service
[Service]
Restart=always
ExecStart=/usr/bin/docker start -a mongodb
ExecStop=/usr/bin/docker stop -t 2 mongodb
[Install]
WantedBy=default.target
```
/usr/lib/systemd/system/docker_tomcat.service文件内容如下：
``````shell
[Unit]
Description=tomcat container
Requires=docker_mongodb.service
After=docker_mongodb.service
[Service]
Restart=always
ExecStart=/usr/bin/docker start -a tomcat
ExecStop=/usr/bin/docker stop -t 2 tomcat
[Install]
WantedBy=default.target
```

- 通过下列命令将MongoDB、Tomcat容器设为开机自启动服务：
```shell
systemctl enable docker_mongodb
systemctl enable docker_tomcat
```
  - 通过下列命令查看MongoDB、Tomcat容器的日志内容：
```shell
docker logs mongodb
docker logs tomcat
```
  - 通过下列命令查看MongoDB、Tomcat容器的运行情况：
```shell
docker ps -a
```

- 部署Jamobo2应用程序：
  - 修改本项目中的web/WEB-INF/web.xml文件，示例如下，注意mongoDbHost对应的值为mongodb，即上述MongoDB容器的名称：
```xml
    <init-param>
      <param-name>webRootPath</param-name>
      <param-value>http://www.domain.com</param-value>
    </init-param>
    <init-param>
      <param-name>mongoDbHost</param-name>
      <param-value>mongodb</param-value>
    </init-param>
```
  - 将本项目打包为war文件，命名为ROOT.war，然后通过ftp或scp命令，将ROOT.war上传部署到Tomcat容器的Web程序部署地址：/usr/local/tomcat/webapps，再通过下列命令重新启动Tomcat容器：
```shell
docker stop tomcat
```
或
```shell
systemctl restart docker_tomcat
```

- 可能出现的问题：
  - Tomcat容器启动后，可能出现访问其Web服务端口没有响应的情况，几分钟或十几分钟后Tomcat服务才启动完成，通过docker logs tomcat命令可以看到下列异常日志：
```shell
08-Mar-2017 01:48:16.043 INFO [localhost-startStop-1] org.apache.catalina.util.SessionIdGeneratorBase.createSecureRandom Creation of SecureRandom instance for session ID generation using [SHA1PRNG] took [98,989] milliseconds.
```
上述日志显示出两个问题：一个是时间不正确，一个是SecureRandom产生时间过长；解决上述Tomcat启动缓慢和日志时间不正确的办法是，修改Tomcat的catalina.sh文件，增加下列内容：
```shell
JAVA_OPTS="$JAVA_OPTS -Djava.security.egd=file:/dev/./urandom -Duser.timezone=GMT+08"
```