MaxKey本地运行实战指南

主页传送门 ： 📀 传送

---

前言

---

    有一段时间没看官网文档了，实在是被恶心到了，恶意弹窗要star 踏马的，本来的star我都给他取消掉，纯纯der,恶心人来了。

概述

---

MaxKey单点登录认证系统，谐音为马克思的钥匙寓意是最大钥匙，是业界领先的IAM-IDaas身份管理和认证产品；支持OAuth 2.x/OpenID Connect、SAML 2.0、JWT、CAS、SCIM等标准协议；提供安全、标准和开放的用户身份管理(IDM)、身份认证(AM)、单点登录(SSO)、资源管理和权限管理等。

开发环境准备

---

之前的4.0版本的更新了 。

官网上虽然是这么写的 但是根据实测，最新版的v4.0.2中 node版本最好用node20以上的版本。

从gitee或者github 下载下来代码

程序目录

---

一级目录	二级目录	说明
README.md		关于MaxKey项目
LICENSE		Apache License v2许可证
NOTICE		MaxKey版权声明
ReleaseNotes.txt		GA版本发布记录描述
config		构建方式配置Jar,Docker,Standard
maxkey-authentications		登录认证
	maxkey-authentication-core	登录认证-核心功能
	maxkey-authentication-provider	登录认证-认证服务
	maxkey-authentication-social	登录认证-社交账号
maxkey-common		通用基础包和工具类
maxkey-core		基础包
maxkey-synchronizers		身份同步器
	maxkey-synchronizer	同步器接口
	maxkey-synchronizer-activedirectory	微软Active Directory同步器
	maxkey-synchronizer-feishu	飞书同步器
	maxkey-synchronizer-ldap	标准LDAP同步器
	maxkey-synchronizer-dingtalk	钉钉同步器
	maxkey-synchronizer-workweixin	企业微信同步器
maxkey-lib		引入本地jar包
maxkey-persistence		数据库持久化和实时数据同步
maxkey-protocols		认证协议实现
	maxkey-protocol-authorize	认证协议及单点注销实现
	maxkey-protocol-cas	CAS认证协议实现
	maxkey-protocol-extendapi	扩展API实现
	maxkey-protocol-formbased	Formbased实现，桌面认证实现开发浏览器插件实现
	maxkey-protocol-jwt	JWT实现
	maxkey-protocol-oauth-2.0	OAuth 2.x，OpenID Connect实现
	maxkey-protocol-saml-2.0	SAML 2.0实现
	maxkey-protocol-tokenbased	tokenbased实现
maxkey-starter		通用starter组件
	maxkey-starter-captcha	图形验证码starter组件
	maxkey-starter-ip2location	IP地址转归属地starter组件
	maxkey-starter-otp	OTP动态口令starter组件
	maxkey-starter-sms	短信发送starter组件
	maxkey-starter-web	web公共starter组件
maxkey-web-apis		web-api接口
	maxkey-web-api-rest	REST身份管理接口
	maxkey-web-api-scim	SCIM2.0身份管理接口
maxkey-web-frontend		web前端
	maxkey-web-app	认证服务前端
	maxkey-web-mgt-app	管理服务前端
maxkey-webs		web服务
	maxkey-web-maxkey	认证系统
	maxkey-web-mgt	管理系统
	maxkey-web-openapi	开放API接口
	maxkey-gataway	基于Spring Cloud套件的网关服务
shellscript		Window和LINUX启动脚本
sql		数据库MYSQL脚本,GA版本对应SQL
checkstyle		编码规范配置
build.gradle		默认工程构建及版本控制
build_cnf.gradle		工程构建配置脚本
gradle.properties		版本参数配置
settings.gradle		项目引入
gradle		gradle的配置
release.bat		标准和Jar构建版本
release_docker.bat		docker构建版本
release_cnf_docker.bat		构建Docker配置
release_cnf_standard.bat		构建标准配置
release_cnf_tradition.bat		构建传统配置
release_cnf_jar.bat		构建Jar配置
setEnvVars.bat		JDK及Gradle路径配置,开发人员配置

环境配置

---

配置mysql环境 推荐Windows下载解压缩版本8.0.3以上 具体配置很简单 网上随便一搜就能找到，这里就不再赘述了。

配置jdk环境 需要注意jdk版本得是17以上。

配置gradle 因为项目是基于gradle构建的 所以需要配置gradle Gradle 4.02版本的gradle 需要7.2 以上，最好是8.0.2及以上版本的 现在4.04版本代码的gradle 需要8.8 以上，最好是9.0及以上版本的。 不知道如何配置的阔以参考这篇，里边写的还是挺详细的，按照操作配置就好了。Gradle 安装配置详解

配置hosts

hosts配置文件目录

C:\Windows\System32\drivers\etc\hosts

这里比较怪的是 我的电脑没有找到hosts文件 查看隐藏文件夹也没有
所以直接用命令复制一个出来

for /f %P in ('dir %windir%\WinSxS\hosts /b /s') do copy %P %windir%\System32\drivers\etc & echo %P & Notepad %P

自动打出hosts文件并且命令行出现“已复制 1 个文件”。再次刷新，应该就会出来了

在hosts 文件新增下面内容

127.0.0.1  sso.maxkey.top
127.0.0.1  mgt.maxkey.top
127.0.0.1  tokenbased.demo.maxkey.top
127.0.0.1  cas.demo.maxkey.top
127.0.0.1  oauth.demo.maxkey.top

至此，环境准备就基本OK了。
接下来就是构建项目启动项目了。

项目构建

---

需要注意的是在构建之前需要先配置jdk和gradle的环境变量

setEnvVars.bat
set JAVA_HOME=jdk安装位置\jdk
set GRADLE_HOME=gradle安装位置\gradle-8.x

修改数据库连接 把application-maxkey.properties 和application-maxkey-mgt.properties
的账号密码还有连接地址替换为自己的。

Spring boot 构建

---

1.SpringBoot Jar 构建配置

release_cnf_jar.bat

2.启动构建

gradlew build -x test或者release.bat

构建完之后出现

这四项就证明构建成功了
接下来启动MaxKeyApplication 和 MaxKeyMgtApplication后端就启动起来了。

启动这俩项的时候可能会报太长无法启动按照上图选择Shorten command line:为 JAR manifest 再重新启动即可。

标准构建

---

1.启动构建

gradlew build -x test或者release.bat

2.构建结果
构建包路径

MaxKey/build

依赖包路径

maxkey-webs/maxkey-web-manage/

maxkey-webs/maxkey-web-maxkey/

Docker 构建

---

1.Docker 构建配置

release_cnf_docker.bat

2.启动构建

gradlew build jib -x test或者release_docker.bat

3.构建结果

maxkey-web-manage/

maxkey-web-maxkey/

传统构建

---

1.传统 构建配置

release_cnf_tradition.bat

2.启动构建

gradlew build -x test或者release.bat

3.构建的结果

构建包路径：

MaxKey/build/maxkey-jars

依赖包路径：

MaxKey/build/MaxKey-v(version)GA

前端构建Build

---

1)MaxKey统一认证前端

maxkey-web-frontend/maxkey-web-app

ng build --prod --base-href /maxkey/

2)MaxKey身份安全管理前端

maxkey-web-frontend/maxkey-web-mgt-app

ng build --prod --base-href /maxkey-mgt/

问题及解决

---

“A cycle was detected in the build path of project: XXX” 

解决方法：

Eclipse Menu -> Window -> Preferences… -> Java -> Compiler -> Building -> Building path problems -> Circular dependencies -> 将Error改成Warning

Access restriction

解决方案：

Eclipse Menu -> Window -> Preferences… -> Java -> Compiler -> Errors/Warnings界面的Deprecated and restricted API下。把Forbidden reference (access rules): 的规则由默认的Error改为Warning即可。

 yarn start

CategoryInfo          : SecurityError: ，PSSecurityException
FullyQualifiedErrorId : UnauthorizedAccess

解决方案：

Set-ExecutionPolicy RemoteSigned -Scope Process

解决方案：
替换geadle 版本为8.10 重新构建启动即可

maxkey官网文档：
maxkey文档