锦中产品安装手册及安装包编制说明及要求

# 安装手册

## 安装手册的编制目的及阅读对象

安装手册的编制目的是为了让用户在安装锦中公司的软件产品时，在不咨询（或少咨询）锦中工程师时，能够独立、自行安装。

安装手册的阅读对象为软件产品的安装人，根据软件产品的不同，对安装人的要求也不一样。举例来说：

1. 锦中学工管理系统的安装人，可能是锦中工程师、学校信息中心的老师，或者锦中公司合作伙伴的工程师等。但无论哪种安装人，都具备一定的IT水平，因此安装手册在编制时，可以默认安装人具有一定的服务器管理、运维知识。
2. 汇硕Wiki产品的安装人，可能是某个企业的办公文员，安装手册在编制时，应当默认安装人不具备服务器管理、运维知识，在软件系统中应当提供“下一步“傻瓜式的安装流程，在安装手册中，应当尽可能详细地描述安装过程、步骤。

## 安装环境

安装手册中，应当标明明确的软/硬件配置要求。一般来说，对于“系统类”软件，硬件配置要求至少应当有服务器端配置要求和用户端配置要求。服务器端应当注明安装软件系统所需的硬件最低配置、建议配置、软件要求。用户端应注明配置要求。

下方是锦中某管理系统的配置要求，仅供参考：

1. **服务器端硬件最低配置**

至少需要一台服务器（数据库和应用安装在同一台服务器上）

CPU：2.40GHz或以上，至少需要2核

内存：4G

硬盘：可用空间 80G以上

其它方面无特殊要求

最低要求仅供演示使用。

2. **服务器端硬件建议配置**

建议两台服务器，数据库和应用各一台服务器。

应用服务器建议配置如下：

CPU：2.40GHz或以上，建议8核

内存：8G

硬盘：可用空间 200G以上

数据库服务器建议配置如下：

（此处省略）

其它方面无特殊要求，建议根据使用用户数量酌情增减。

3. **服务器端软件配置要求**

操作系统：
Windows： Windows Server 2019（或以上版本） 
IIS：Windows自带IIS即可
.Net Framework 4.8

Linux：Ubuntu 20.04.1 （或以上版本） 
Tomcat9（或以上版本）
JDK：1.8（或以上版本）

数据库：My Sql 8.0（或以上版本），或 Sql Server 2014（或以上版本）
其它：
Redis 7.0 （或以上版本）

4. **用户端软件配置要求**

浏览器：Chrome、Firefox、Safari、Edge等chrome内核的浏览器常规版本均可

操作系统：支持上述浏览器即可，对操作系统无特殊要求。

## 安装步骤

1. 应当根据不同的操作系统，给出不同的安装方法。对于可以Docker安装的软件系统，也应当给出Docker环境下的安装步骤。
2. 凡是在上方“安装环境”中涉及的软件，除了操作系统和浏览器外，所有的软件都应当给出安装步骤和方法。对于一些常用、常见、常规的软件，可以在安装手册中给出官方的安装步骤或方法，可以附上官方链接。但是，有特殊配置的，必须在安装手册中给出说明。有些软件有默认的账号、密码、端口号，在安装手册中应当注明，在哪里修改这些默认参数，安全起见，并应当建议用户不要采用默认密码。
3. 在软件系统中，需要用到第三方的软件、环境、服务的，应当在安装手册中给出详细的描述。比如，如果需要用到企业微信，或者公众号、小程序等，应当在安装手册中详细注明这些服务的申请步骤、申请成功之后的配置方法。如果第三方服务的官方有详细说明的，应当附上相应的链接。参考：<http://doc.jzkg.cn/doc/390/> 
4. 应当给出软件系统中配置参数的详细说明。不同的开发语言、框架的配置文件路径不一样，比如Asp.Net语言框架的配置文件通常为：web.config，.Net Core语言框架的配置文件通常为：appsettings.json，Java语言框架的配置文件通常为*.yml 或 *.properties。一般情况下，在软件系统的开发阶段，应当在这些配置文件中给出参数的详细解释。但是在安装手册中，也应当给出系统安装之后，这些参数默认做哪些配置。比如：在.Net Core语言框架appsettings.json文件中，有ConnectionString（数据库连接字符串）的详细说明，但如果在安装手册中不对ConnectionString做出说明，用户并不知道还要配置这个参数。

# 安装包

1. 应当根据不同的操作系统，给出不同的安装包。当然，有些软件系统在Linux、Windows下的安装包是同一个，那么只给出一个安装包即可。
2. Docker视为独立的操作系统，对于可以用Docker安装的软件系统，也应当给出Docker环境下的安装包、Dockerfile文件等。
3. 安装包内应该包含“不带测试数据”包和“带测试数据”包。其中的测试数据包可以是一个单独的sql文件，也可以是一组Excel文件，对于是一组Excel文件的，应当在安装手册中注明如何将Excel文件导入系统，当然也可以根据软件系统的实际情况自己定义“带测试数据包”的格式。总之，“不带测试数据包”是为了让用户安装好之后即可开始配置使用，“带测试数据包”是为了让用户使用测试数据熟悉软件产品的功能。

# 安装包制作过程中经常遇到的问题

**默认密码**
所有用户的默认密码默认为：www.jzkg.cn 。在安装手册中必须注明，如果忘记密码，需将数据库中哪个表，哪个列改为什么，则密码自动变为www.jzkg.cn

**不同版本的License密钥、公钥应该不同**
比如：统一消息平台有标准版、高校版，License不应当通用。

**application.yml 配置文件**

yml的配置应尽可能简单，不需要用户配置的参数不要出现在yml中。
通常情况下，以下参数应该出现在yml中允许用户配置：
1. 启动端口Port
2. 数据库连接相关
3. Redis连接相关（如果有）
4. Powerjob连接相关（如果有）
5. Minio连接相关（如果有）
6. license地址（如果有）。建议license默认路径为jar包所在路径的jzconfig路径下的license.xml（其中的L小写）。假如jar包所在路径为/data/example.jar，则license.xml默认位置为/data/jzconfig/license.xml ，这样就允许用户不在yml中配置license路径
7. 统一身份认证相关配置（如果有）
8. 演示模式相关（如果有），如preview:enabled

通常情况下，以下参数不应该出现在yml中，不应该让用户配置：
1. License模块的modulus
2. Xss、jackson等节点

**数据库相关文件**
软件程序支持什么数据库，就应该将数据库相关的脚本、文件放在安装包中，如mysql、达梦、海量、Gauss等

**安装包中应当有模拟数据**
安装包中应当有少量模拟演示数据，模拟数据可以是任何可使用的格式。可以是Excel，让用户在界面上导入，也可以是 sql脚本，让用户在安装时导入。

# 其它要求

1. 对于已经接入“锦中应用统一管理平台“License管理模块的软件产品，必须在安装手册中注明下面一段话（允许安装手册编写人自行修改）：

------
**本软件系统，需要正确安装License后才能使用。如您是锦中公司员工，请到“锦中应用统一管理平台”（访问地址为：<http://app.jzkg.cn/> ）申请License。如您非锦中公司员工，请咨询锦中公司销售、客服人员。**

------
2. 安装手册应当有“可能遇到的问题及解决方法”模块。在编制“安装手册”过程中，编制人应当自行安装软件系统，并且尽可能多地覆盖常见的安装环境。在安装过程中遇到问题时，应当记录并形成“可能遇到的问题及解决方法”。

# 参考

1. hsoa 站点安装、部署教程 <http://doc.jzkg.cn/doc/389/> 
2. hsoa main 如何配置企业微信端 <http://doc.jzkg.cn/doc/390/> 
3. hsoa main 初次配置使用可能遇到的问题及解决办法 <http://doc.jzkg.cn/doc/391/>