单机模式部署安装MaxId统一身份认证系统

## 说明
1. 我们不建议采用单机模式部署安装MaxId统一身份认证系统，在单机模式下，如果MaxId服务器出现故障（如断电、断网、例行维护等），将导致所有接入MaxId的第三方应用无法登录，造成灾难故障。
2. 我们建议采用集群模式部署安装MaxId统一身份认证系统，在集群模式下，一台或几台服务器出现故障，不会影响MaxId的正常运行。
3. 安装环境，软、硬件要求见[安装MaxId统一身份认证系统之前的准备工作](http://doc.jzkg.cn/doc/1206/ "安装MaxId统一身份认证系统之前的准备工作")。在阅读本文之前，您应该先按照要求准备相应的软、硬件环境。本文以Ubuntu 20.04，Mysql 8.0为例说明。

## 安装部署
### JDK安装
[JDK安装教程](https://blog.csdn.net/qq_42557044/article/details/124935468 "JDK安装教程")
(需将教程中的JDK版本更换成MaxId所需的Openjdk 20版本)
### MYSQL安装
[Mysql安装教程](https://www.cnraksmart.com/7436.html "Mysql安装教程")

### Nginx安装
[Nginx安装教程](https://blog.csdn.net/weixin_41302755/article/details/123175079 "Nginx安装教程")

### License申请
MaxId统一身份认证系统，是收费软件系统，需要有License才能正常部署。在您部署之前，应从官方获得正版的License。如果您还没有License，想先部署、测试的话，那么可以在部署之前，先到官方在线申请免费使用3天的License，在线申请url为：http://app.jzkg.cn

在申请License之前，需要先获得MaxId统一身份认证后端所在服务器的Ipv4地址（即Ip地址）、Ipv6地址和Mac物理地址。方法为在控制台中输入：ifconfig 命令即可看到。

申请成功后，您将得到文件：license.xml，将这个文件放到：conf文件目录下面即可。假设您的安装包文件的路径为/data/maxid/conf，则将license.xml放在/data/maxid/conf/license.xml ，注意Linux系统区分大小写，默认license.xml 均小写。

钉钉，微信，企业微信，短信服务-http://doc.jzkg.cn/doc/1194/

### MaxId主程序安装
1. 将打包好的安装文件上传至服务器指定文件夹中，并解压。本文安装示例中MaxId所在的路径为：/data/maxid/

2. 进入conf目录，将你的license.xml放在此目录下，license.xml 必须全部小写，本文示例的路径为：/data/maxid/conf/license.xml

3. 如果你已经配置了Java变量，则不会修改Java路径，如果未配置，则需要修改maxid.sh和kc.sh文件中的java路径，见下图。

![](/media/202312/2023-12-04_092651_616846.png)

4. 修改配置文件。进入conf目录，修改配置文件：keycloak.conf

```
#阿里云短信配置
spi-phone-default-service=aliyun
spi-message-sender-service-aliyun-region=cn-hangzhou
spi-message-sender-service-aliyun-signname=锦中集团 #锦中集团为短信签名，此处必须修改为您自己的签名，此签名需进入阿里云后台申请，并且需要阿里云审核
spi-message-sender-service-aliyun-key=LTAI5t82gRxbJd0yyT8B8n2q #短信Key，请替换成你自己的
spi-message-sender-service-aliyun-secret=sm9aErWV2abwH73Zc83DphZwqkhqhh #短信密钥，请替换成你自己的
spi-message-sender-service-aliyun-auth-template=SMS_136861653 #短信模板Id，请替换成你息的，用于发送验证码

#默认欢迎页启动主题
spi-theme-welcome-theme=maxid

# Database
#数据库类型
db=mysql
#数据库用户名
db-username=root #请替换成你自己的
//数据库密码
db-password=root #请替换成你自己的
#数据库地址
db-url=jdbc:mysql://192.168.1.100/maxid #请替换成你自己的

# ssl证书
https-certificate-file=${kc.home.dir}/sslcert/your_cert.pem
https-certificate-key-file=${kc.home.dir}/sslcert/your_cert.key
#上面的pem和key的路径可以使用绝对路径，也可使用相对路径，其中的${kc.home.dir}指maxid的根目录，因此上面两个文件的路径也可用绝对路径：/data/maxid/sslcert/your_cert.pem  /data/maxid/sslcert/your_cert.key 替代

# Hostname for the MaxId server.
hostname=id.jzkg.cn #域名
#http的端口
#http-port=8080 #在正式生产环境下，请删掉此行，或注释掉

#https的端口
#在正式生产环境下，必须使用https方式访问
https-port=443

#https的默认端口为443，我们建议采用443端口，如果改成其它端口，比如8443，即使在MaxId应用服务器的外层再加上Nginx转端口，将8443转成443，MaxId也无法使用443端口正常访问。因此，此处的端口，要与用户实际浏览器访问的端口一致。
```
4. 配置MaxId增强插件
MaxId增强插件是一个独立的应用，它单独以一个不同于MaxId主体程序的端口运行。插件的默认端口是8088，建议保持不变，如果需要修改可以在 Enhance_plugins中application.propertie 中修改。
![](/media/202312/2023-12-02_161752_900640.png)

5. 运行MaxId

##### 首次启动
首次启动MaxId时，它会自动初始化数据库。首次启动MaxId前，我们还需要简单做下操作：
- 给bin目录中的maxid.sh和kc.sh赋予执行权限（完整路径为：/data/maxid/bin/maxid.sh 或/data/maxid/bin/kc.sh），命令为：
```
sudo chmod a+x maxid.sh
sudo chmod a+x kc.sh
```
-build一下maxid，命令为：
```
sudo ./kc.sh build
```
-需要将防火墙中端口打开，本文示例在安装时，MaxId主程序采用的是443端口，增强插件采用的是8088端口，打开防火墙的命令为：
```
sudo ufw allow 443
sudo ufw allow 8088
```
-首次启动前，我们需要为MaxId设置一个管理员用户和密码。

命令为：
```
export KEYCLOAK_ADMIN=用户名
export KEYCLOAK_ADMIN_PASSWORD=密码
```
请将上面代码中的用户名和密码改为你自己的，我们强烈建议将密码设置为带大写字母、小写字母、数字、特殊符号的8位以上复杂密码。
- 最后执行首次启动命令
```
sudo KEYCLOAK_ADMIN=$KEYCLOAK_ADMIN KEYCLOAK_ADMIN_PASSWORD=$KEYCLOAK_ADMIN_PASSWORD ./maxid.sh start
```
见下图：
![](/media/202312/2023-12-04_094526_984281.png)

首次启动时，MaxId需要做初始化数据库等一系列操作，大约需要等待1-3分钟。启动成功后，用浏览器打开：https://{maxid的ip}:port  （下面的示例截图中，本文端口采用https的默认端口443，因此不需要加端口）应该能看到类似下图的界面：
![](/media/202312/001_20231205113437431640.jpg)
- 出现这个错误，是因为你的域名SSL证书与当前IP不一致导致的，点击图中的“继续前往...”，可以看到MaxId界面。 此时，还不能通过域名访问，因为还没有配置Nginx（当然，如果你的域名直接指向到了MaxId服务器，并且不经过Nginx，通过域名能够正常访问。）
- 用http方式访问增强插件的8088端口，http://{maxid的ip}:增强插件port ，应该能看到类似下面的截图，看到下面的截图说明增强插件启动成功：
![](/media/202312/002_20231205114110306097.jpg)

##### 非首次启动
非首次启动，直接运行sudo ./maxid.sh start 即可，

### Nginx配置

总体来说，Nginx上location节点需要做两段配置，一段为MaxId主体程序，一段为增强插件。
以下为在Nginx上配置的相关代码：
```
server {
	listen  443 ssl; #此处端口应与keycloak.conf中的端口一致
	server_name   id.jzkg.cn;#此处为你的已经绑定SSL证书的域名
	#以下两行代码为SSL证书配置，由于是https方式访问，在MaxId和Nginx中均需配置此证书，如果Nginx和MaxId不在同一台服务器上，只需将MaxId中的证书文件复制到Nginx服务器上，并且将下面的证书路径改为你自己的路径即可
	ssl_certificate /data/maxid/sslcert/your_cert.pem;
	ssl_certificate_key /data/maxid/sslcert/your_cert.key;
	#禁止在 header中出现 Nginx服务器版本，防止黑客利用版本洞攻击
	server_tokens off;
	fastcgi_param  HTTPS  on;
	fastcgi_param  HTTP_SCHEME https;

location / {
		proxy_pass https://192.168.1.101/;#此处更换为你的MaxId服务器的Ip及端口，本示例中端口为443，默认可以不写
		proxy_set_header HOST $host;
		proxy_set_header X-Real-IP $remote addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 
		proxy_set_header X-Forwarded-Proto $scheme;
	}

location /enhance_plugins/ {
		proxy_pass https://192.168.1.101:8088/;#此处的8088为增强插件的启动端口
		proxy_set_header HOST $host;
		proxy_set_header X-Real-IP $remote_addr;
		proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
		proxy_set_header X-Forwarded-Proto $scheme;
	}
}
```
### 开机自动启动
以下以Ubuntu 20.04 操作系统为例介绍
1. 进入/etc/systemd/system 目录，新建maxid.service文件，命令为：sudo touch maxid.service
2. sudo vi maxid.service修改文件，增加以下内容：

```
[Unit]
Description=MaxId service
After=syslog.target

[Service]
Type=simple
User=root
ExecStart=/data/maxid/bin/maxid.sh start #此处的maxid.sh文件，请更换为你自己的实际路径
SuccessExitStatus=143
Restart=always

[Install]
WantedBy=multi-user.target

```
然后，依次执行命令：
systemctl enable maxid.service (将maxid设置为开机自启)
systemctl start maxid.service（立即启动maxid服务）

除此之外，你可能还会用到以下常用命令
systemctl disable maxid.service(禁用maxid的开机自启)
systemctl is-enabled maxid.service(查看maxid是否设置了开机自启)
systemctl status maxid.service(检查maxid的运行状态)
systemctl restart maxid.service(重新启动maxid服务)
systemctl daemon-reload（重新加载maxid的配置文件，当你修改了maxid.service文件后，需要执行此行命令以使其生效）

### 后续
至此，MaxId已经配置安装启动成功，接下来还需要进入MaxId进行一些初始化设置才能正常使用，具体请参考：[安装部署MaxId首次启动后需要进行的配置操作](http://doc.jzkg.cn/doc/1209/ "安装部署MaxId首次启动后需要进行的配置操作")