keyfil/教程/单点/20250220-Metersphere安装及SSO接入指南.md

<!-- Space: qifu -->
<!-- Parent: 后端技术&知识&规范 -->
<!-- Parent: 技术方案 -->
<!-- Parent: 基建 -->
<!-- Parent: 03-接入指南 -->
<!-- Title: 20250220-Metersphere安装及SSO接入指南 -->
<!-- Attachment: ../材料/app.zip -->

<!-- Macro: :anchor\((.*)\):
     Template: ac:anchor
     Anchor: ${1} -->
<!-- Macro: \!\[.*\]\((.+)\)\<\!\-\- width=(.*) \-\-\>
     Template: ac:image
     Url: ${1}
     Width: ${2} -->
<!-- Macro: \<\!\-\- :toc: \-\-\>
     Template: ac:toc
     Printable: 'false'
     MinLevel: 2 
     MaxLevel: 4 -->
<!-- Include: 杂项/声明文件.md -->

<!-- :toc: -->

# Metersphere 安装及 SSO 接入指南

## 附件列表
- [app.zip](../../材料/app.zip)

## Metersphere 安装启动

- 可以参考：https://metersphere.io/docs/v3.x/installation/offline_installation/

### 下载离线安装包

- 下载地址：https://community.fit2cloud.com/#/products/metersphere/downloads
- 版本：v3.6.1-lts

### 解压安装包

```shell
#- 解压安装包
tar zxvf metersphere-offline-installer-v3.6.1-lts.tar.gz 
```

### 执行安装脚本

```shell
#- 进入安装包目录
cd metersphere-offline-installer-v3.x.y
#- 运行安装脚本
/bin/bash install.sh
```

### 访问并登录

- URL: http://服务器IP:8081
- 用户名: admin
- 初始密码: metersphere

## Metersphere OIDC 配置

### 获取源码

```shell
git clone -b v3.6.1-lts --depth 1 https://github.com/metersphere/metersphere.git
```

### 添加代码

- `backend/app` 下
- 将附件 [app.zip](../../材料/app.zip) 中的增量代码拷贝到对应目录
- 编译 `backend/app`
    - Maven `settings.xml` 添加 mirror
    - ```xml
      <mirror><id>nexus</id><name>this is my nexus</name><url>https://repository.fit2cloud.com/content/groups/public/</url><mirrorOf>*</mirrorOf></mirror>
      ```
    - 进入目录 `backend/app` 执行 `mvn clean compile`

### 将新增的文件加入镜像

#### 解压 `metersphere-offline-installer-v3.6.1-lts/images/metersphere.tar`

```shell
cd metersphere-offline-installer-v3.6.1-lts/images/
mkdir ./metersphere
tar zvf metersphere.tar -C ./metersphere
```

#### 进入 Metersphere 源码层

```shell
cd ./metersphere/8b79e2bdad1b9e90a7a5a44478c8b82a59d72e628f65b00cb7d9e77476910762/

tar zvf layer.tar

cd /metersphere/io/metersphere/
```

#### 拷贝 class 到刚刚的目录

- 拷贝 `target/classes/io/metersphere/exclude` 文件夹
- 拷贝 `target/classes/io/metersphere/keycloak` 文件夹

### 重新打包镜像

#### 重新生成 layer.tar

- 回到 `8b79e2bdad1b9e90a7a5a44478c8b82a59d72e628f65b00cb7d9e77476910762` 目录
- ```shell
  tar cvf layer.tar ./metersphere

  rm -rf metersphere
  ```

#### 重新生成镜像包

- 回到 `metersphere-offline-installer-v3.6.1-lts/images/` 目录
- ```shell
  #!/bin/bash
  
  echo "into folder"
  cd ./metersphere
  
  echo "tar metersphere.tar"
  tar cvf metersphere.tar *
  
  echo "out folder"
  cd ../

  echo "replace metersphere.tar"
  mv ./metersphere/metersphere.tar ./
  ```

### 替换 sha256

#### 获取 新的 sha256

```shell
docker images -a | grep metersphere-ce

#- 移除已有镜像
docker rmi registry.fit2cloud.com/metersphere/metersphere-ce:v3.6.1-lts

#- 获取错误
docker load -i metersphere.tar
```

#### 替换 sha256

- 新建脚本 `replace.sh`

```shell
#!/bin/bash
old=$1
new=$2

echo "old sha: $old, new sha: $new"
sed -i -E "s@${old}@${new}@g" ./metersphere/4873db853f2435741102f62cfd03cf0fb59f36df4e1467f3ad0e16582894d195.json
```

- 执行脚本

```shell
bash replace.sh oldsha newsha
```

- 重新生成 metersphere.tar
  参考 [重新生成 metersphere.tar](#重新生成镜像包)

### 替换旧镜像

```shell
docker images -a | grep metersphere-ce

#- 移除已有镜像
docker rmi registry.fit2cloud.com/metersphere/metersphere-ce:v3.6.1-lts

#- 获取错误
docker load -i metersphere.tar
```

### 重启服务

```shell
msctl down -v

msctl up -d --remove-orphans
```

### 数据库添加认证源

```sql
INSERT INTO `metersphere`.`auth_source` (`id`, `configuration`, `enable`, `create_time`, `update_time`, `description`,
                                         `name`, `type`)
VALUES ('metersphere',
        0x7B22636C69656E744964223A226D65746572737068657265222C22736563726574223A22387566514636387A6F4869514739676D456D434A4776755939554F644D513769222C22726564697265637455726C223A22687474703A2F2F6C6F63616C2E6D657465727370686572652E636F6D2F73736F2F63616C6C6261636B2F6B6579636C6F616B222C226175746855726C223A22687474703A2F2F6B6579636C6F616B2E716966752E636F6D2F7265616C6D732F6B657966696C2F70726F746F636F6C2F6F70656E69642D636F6E6E6563742F61757468222C22746F6B656E55726C223A22687474703A2F2F6B6579636C6F616B2E716966752E636F6D2F7265616C6D732F6B657966696C2F70726F746F636F6C2F6F70656E69642D636F6E6E6563742F746F6B656E222C2275736572496E666F55726C223A22687474703A2F2F6B6579636C6F616B2E716966752E636F6D2F7265616C6D732F6B657966696C2F70726F746F636F6C2F6F70656E69642D636F6E6E6563742F75736572696E666F222C226D617070696E67223A227B5C227573657269645C223A5C227375625C222C5C22757365726E616D655C223A5C227072656665727265645F757365726E616D655C222C5C22656D61696C5C223A5C22656D61696C5C227D227D,
        b'1', 0, 100, '企业微信登录', '企业微信', 'OIDC');


UPDATE auth_source
SET configuration = '{\"clientId\":\"metersphere\",\"secret\":\"8ufQF68zoHiQG9gmEmCJGvuY9UOdMQ7i\",\"redirectUrl\":\"http://metersphere.xxx.com/sso/callback/keycloak\",\"authUrl\":\"http://keycloak.xxx.com/realms/keyfil/protocol/openid-connect/auth\",\"tokenUrl\":\"http://keycloak.xxx.com/realms/keyfil/protocol/openid-connect/token\",\"userInfoUrl\":\"http://keycloak.xxx.com/realms/keyfil/protocol/openid-connect/userinfo\",\"mapping\":\"{\\\"userid\\\":\\\"sub\\\",\\\"username\\\":\\\"preferred_username\\\",\\\"email\\\":\\\"email\\\"}\"}'
WHERE id = 'metersphere';
```

- 替换 configuration 中的信息
    - `clientId`
    - `secret`
    - `redirectUrl`
    - `authUrl`
    - `tokenUrl`
    - `userInfoUrl`

### 测试