Skip to content

Commit 182980b

Browse files
scottsutscottsut
committed
chore: 更新单点登录配置介绍
1 parent ef6eb72 commit 182980b

File tree

1 file changed

+123
-65
lines changed

1 file changed

+123
-65
lines changed

‎source/docs/index.md‎

Lines changed: 123 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -10,20 +10,23 @@ title: 部署
1010

1111
# 1. Docker 部署
1212

13+
datart 在 dockerhub 中的公共镜像地址为 [datart/datart](https://hub.docker.com/r/datart/datart)。如果你本地已经安装了 docker，执行以下命令可以一键安装：
14+
1315
```shell
14-
docker run -p 8080:8080 datart/datart
16+
docker run -p 8080:8080 datart/datart
1517
```
16-
启动后可访问 <http://docker_ip:8080>
17-
默认账户:用户名`demo`,密码`123456`
18+
19+
镜像启动成功后，在浏览器中访问 <http://docker_ip:8080> 进入登录页。镜像中提供初始账户，用户名`demo` 密码`123456`
1820

1921
## 1.1. 配置外部数据库
20-
在没有外部数据库配置的情况下，Datart使用H2作为应用程序数据库。 强烈建议您将自己的Mysql数据库配置为应用程序数据库。
22+
23+
在没有外部数据库配置的情况下，Datart 使用 H2 作为应用程序数据库。 强烈建议您将自己的 Mysql 数据库配置为应用程序数据库。
2124

2225
创建空文件 `datart.conf` ,将以下内容粘贴到到文件中。并配置数据库连接信息。
2326

2427
```shell
2528
# 数据库连接配置
26-
datasource.ip=
29+
datasource.ip=
2730
datasource.port=
2831
datasource.database=
2932
datasource.username=
@@ -49,41 +52,42 @@ datart.webdriver-path=http://127.0.0.1:4444/wd/hub
4952

5053
`docker run -d --name datart -v your_path/datart.conf:/datart/config/datart.conf -v your_path/files:/datart/files -p 8080:8080 datart/datart`
5154

55+
# 2 本地部署
5256

53-
# 2 本地部署
5457
## 2.1 环境准备
5558

5659
- JDK 1.8+
5760
- MySql5.7+
58-
- datart安装包（datart-server-*-install.zip)
61+
- datart 安装包（datart-server-\*-install.zip)
5962
- Mail Server （可选）
6063
- [ChromeWebDriver](https://chromedriver.chromium.org/) （可选）
6164
- Redis （可选）
6265

63-
解压安装包
66+
解压安装包
67+
6468
```bash
6569
unzip datart-server-*-install.zip
6670
```
6771

6872
## 2.2 以独立模式运行
6973

70-
安装包解压后，即可运行 ./bin/datart-server.sh start 来启动datart,启动后默认访问地址是: <http://127.0.0.1:8080>,默认用户`demo/123456`
74+
安装包解压后，即可运行 ./bin/datart-server.sh start 来启动 datart,启动后默认访问地址是: <http://127.0.0.1:8080>,默认用户`demo/123456`
7175

72-
***独立模式使用内置数据库作为应用数据库，目前无法保证数据迁移，建议配置外部数据库作为应用数据库***
76+
**_独立模式使用内置数据库作为应用数据库，目前无法保证数据迁移，建议配置外部数据库作为应用数据库_**
7377

7478
## 2.3 配置外部数据库
7579

76-
***要求Mysql5.7及以上版本***
80+
**_要求 Mysql5.7 及以上版本_**
7781

78-
- 创建数据库，指定数据库编码为utf8
82+
- 创建数据库，指定数据库编码为 utf8
7983

8084
```bash
8185
mysql> CREATE DATABASE `datart` CHARACTER SET 'utf8' COLLATE 'utf8_general_ci';
8286
```
8387

84-
***注意：1.0.0-beta.2版本以前，需要手动执行`bin/datart.sql`来初始化数据库。此版本及以上版本，创建好数据库即可，在初次连接时会自动初始化数据库***
88+
**_注意：1.0.0-beta.2 版本以前，需要手动执行`bin/datart.sql`来初始化数据库。此版本及以上版本，创建好数据库即可，在初次连接时会自动初始化数据库_**
8589

86-
***首次连接数据库(或者版本升级)时,建议使用一个权限较高的数据库账号登录(建议root账号)。因为首次连接会执行数据库初始化脚本，如果使用的数据库账号权限太低，会导致数据库初始化失败***
90+
**_首次连接数据库(或者版本升级)时,建议使用一个权限较高的数据库账号登录(建议 root 账号)。因为首次连接会执行数据库初始化脚本，如果使用的数据库账号权限太低，会导致数据库初始化失败_**
8791

8892
- 基础配置：配置文件位于 config/datart.conf
8993

@@ -94,7 +98,7 @@ mysql> CREATE DATABASE `datart` CHARACTER SET 'utf8' COLLATE 'utf8_general_ci';
9498
3. datasource.database(指定数据库)
9599
4. datasource.username(用户名)
96100
5. datasource.password(密码)
97-
101+
98102
其它配置(选填):
99103
1. server.port(应用绑定端口地址,默认8080)
100104
2. server.address(应用绑定IP地址,默认 0.0.0.0)
@@ -103,19 +107,19 @@ mysql> CREATE DATABASE `datart` CHARACTER SET 'utf8' COLLATE 'utf8_general_ci';
103107
5. datart.webdriver-path(截图驱动)
104108
```
105109

106-
## 2.4. 完整配置 (可选)
110+
## 2.4. 完整配置（可选）
107111

108-
***配置文件位于 config/profiles/application-config.yml***
112+
**_配置文件位于 config/profiles/application-config.yml_**
109113

110-
***完整配置文件格式是yml格式,配置错误会导致程序无法启动。配置时一定要严格遵循yml格式。***
114+
**_完整配置文件格式是 yml 格式,配置错误会导致程序无法启动。配置时一定要严格遵循 yml 格式。_**
111115

112-
***application-config.yml直接由spring-boot处理,其中的oauth2,redis,mail等配置项完全遵循spring-boot-autoconfigure配置***
116+
**_application-config.yml 直接由 spring-boot 处理,其中的 oauth2,redis,mail 等配置项完全遵循 spring-boot-autoconfigure 配置_**
113117

114-
### 2.4.1 数据库连接信息
118+
### 2.4.1 数据库连接信息
115119

116120
**可以在 `darart.conf` 文件中配置，也可直接修改这里的配置。推荐保留这里的默认配置，把数据库信息配置到 `darart.conf`文件中**
117121

118-
***注：请务必保留连接串中的`allowMultiQueries=true`参数***
122+
**_注：请务必保留连接串中的`allowMultiQueries=true`参数_**
119123

120124
```yaml
121125
spring:
@@ -127,9 +131,9 @@ spring:
127131
password: ${datasource.password:123456}
128132
```
129133
130-
### 2.4.2 服务端属性配置 (可选)
134+
### 2.4.2 服务端属性配置（可选）
131135
132-
- Web服务绑定IP和端口
136+
- Web 服务绑定 IP 和端口
133137
134138
```yaml
135139
server:
@@ -143,7 +147,6 @@ server:
143147
datart:
144148
server:
145149
address: ${datart.address:http://127.0.0.1:8080}
146-
147150
```
148151
149152
- 其它可选配置项
@@ -152,23 +155,22 @@ datart:
152155
datart:
153156
user:
154157
active:
155-
send-mail: false # 注册用户时是否需要邮件验证，如果没配置邮箱，这里需要设置为false
158+
send-mail: false # 注册用户时是否需要邮件验证，如果没配置邮箱，这里需要设置为false
156159

157160
security:
158161
token:
159162
secret: "sHAS$as@fsdkKjd" #加密密钥
160-
timeout-min: 30 # 登录会话有效时长，单位：分钟。
163+
timeout-min: 30 # 登录会话有效时长，单位：分钟。
161164

162165
env:
163-
file-path: ${user.dir}/files # 服务端文件保存位置
164-
166+
file-path: ${user.dir}/files # 服务端文件保存位置
165167
```
166168
167-
*注意：加密密钥每个服务端部署前应该进行修改，且部署后不能再次修改。如果是集群部署，同一个集群内的secret要保持统一*
169+
_注意：加密密钥每个服务端部署前应该进行修改，且部署后不能再次修改。如果是集群部署，同一个集群内的 secret 要保持统一_
168170
169-
### 2.5 邮件服务配置 (可选)
171+
### 2.5 邮件服务配置（可选）
170172
171-
***邮件服务用于定时任务发送，用户注册/激活/邀请等功能。要体验完整的datart功能，请务必正确的邮件服务。***
173+
**_邮件服务用于定时任务发送，用户注册/激活/邀请等功能。要体验完整的 datart 功能，请务必正确的邮件服务。_**
172174
173175
- 以下为完整配置
174176
@@ -194,15 +196,15 @@ spring:
194196
enable: true
195197
```
196198
197-
***配置说明***
199+
**_配置说明_**
198200
199201
- `username`为邮箱地址，`password`邮箱服务密码，需要注意的是常见免费邮箱（如 163 邮箱、QQ 邮箱、gmail 等）这里应填客户端独立密码，可前往对应邮箱账号设置页面开启 SMTP
200202
服务，并申请客户端授权码（或独立密码，各邮箱提供商叫法不同）
201203

202204
下表为常见免费邮箱 SMTP 服务地址及端口：
203205
![mail.png](/datart-docs/images/deployment/mail.png)
204206

205-
### 2.6 截图配置 (可选)
207+
### 2.6 截图配置（可选）
206208

207209
- 截图配置用于定时任务中的发送图片功能。
208210

@@ -211,57 +213,113 @@ datart:
211213
screenshot:
212214
timeout-seconds: 60
213215
webdriver-type: CHROME
214-
webdriver-path: {Web Driver Path}
216+
webdriver-path: { Web Driver Path }
215217
```
216218

217219
- 配置说明
218220
`timeout-seconds` 指定截图超时时间
219221
`webdriver-type` 截图浏览器类型。(目前仅支持`CHROME`)
220-
`webdriver-path` webdriver地址。可执行文件的绝对地址，或远程webdriver的调用地址
222+
`webdriver-path` webdriver 地址。可执行文件的绝对地址，或远程 webdriver 的调用地址
221223

222224
*
223225

224-
注意：配置时请确保浏览器的版本和webdriver的版本匹配。推荐使用docker镜像 [selenium/standalone-chrome](https://registry.hub.docker.com/r/selenium/standalone-chrome)
225-
来配置远程截图服务。*
226+
注意：配置时请确保浏览器的版本和 webdriver 的版本匹配。推荐使用 docker 镜像 [selenium/standalone-chrome](https://registry.hub.docker.com/r/selenium/standalone-chrome)
227+
来配置远程截图服务。\*
226228

227229
```
228230
docker run -p 4444:4444 -d --name selenium-chrome --shm-size="2g" selenium/standalone-chrome
229231
```
230232
231233
- 然后配置 `webdriver-path: "http://{IP}:4444/wd/hub"`
232234
233-
### 2.7 redis (可选)
234-
- redis用于查询结果缓存
235+
### 2.7 redis（可选）
236+
237+
- redis 用于查询结果缓存
238+
235239
```yaml
240+
spring:
236241
redis:
237242
port: 6379
238243
host: { HOST }
239244
```
240245

241-
### 2.8 oauth2 (可选)
242-
243-
```ymal
244-
# security:
245-
# oauth2:
246-
# client:
247-
# registration:
248-
# cas:
249-
# provider: cas
250-
# client-id: "xxxxx"
251-
# client-name: "Sign in with CAS"
252-
# client-secret: "xxx"
253-
# authorization-grant-type: authorization_code
254-
# client-authentication-method: post
255-
# redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
256-
# scope: userinfo
257-
# provider:
258-
# cas:
259-
# authorization-uri: https://cas.xxx.com/cas/oauth2.0/authorize
260-
# token-uri: https://cas.xxx.com/cas/oauth2.0/accessToken
261-
# user-info-uri: https://cas.xxx.com/cas/oauth2.0/profile
262-
# user-name-attribute: id
263-
# userMapping:
264-
# email: "attributes.email"
265-
# name: "attributes.name"
266-
# avatar: "attributes.avatar"
246+
### 2.8 单点登录配置（可选）
247+
248+
datart 支持配置基于 OAuth2 和 LDAP 的单点登录方式。
249+
250+
用户首次使用所配置的单点登录方式登录成功后，datart 会使用用户的邮箱注册一个新账户。在此之后的登录都视为该账户登录。
251+
252+
#### 2.8.1 OAuth2
253+
254+
启用 OAuth2 登录需要在 `spring.security.oauth2.client` 下配置客户端信息，可以配置多个 OAuth2 客户端。在配置之前，需要到提供 OAuth2 服务的网站获取 `Client ID` 和 `Client Secret`
255+
256+
下面为一个 OAuth2 客户端的配置示例：
257+
258+
```yaml
259+
spring:
260+
security:
261+
oauth2:
262+
client:
263+
registration:
264+
cas:
265+
provider: cas
266+
client-id: "xxxxx"
267+
client-name: "Sign in with CAS"
268+
client-secret: "xxx"
269+
authorization-grant-type: authorization_code
270+
client-authentication-method: post
271+
redirect-uri: "{baseUrl}/login/oauth2/code/{registrationId}"
272+
scope: userinfo
273+
provider:
274+
cas:
275+
authorization-uri: https://cas.xxx.com/cas/oauth2.0/authorize
276+
token-uri: https://cas.xxx.com/cas/oauth2.0/accessToken
277+
user-info-uri: https://cas.xxx.com/cas/oauth2.0/profile
278+
user-name-attribute: id
279+
userMapping:
280+
email: "attributes.email"
281+
name: "attributes.name"
282+
avatar: "attributes.avatar"
283+
```
284+
285+
在 `spring.security.oauth2.client` 底下有 `registration` 和 `provider` 两个配置项，`registration` 包含所有客户端的注册信息，`provider` 包含所有客户端所访问的 OAuth2 服务提供者的相关信息。下方表格将参照示例说明每一个配置项的作用：
286+
287+
| 配置项 | 说明 |
288+
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
289+
| registration.[registrationId] | 注册 ID；自定义名称，示例中命名为 cas |
290+
| registration.[registrationId].provider | 关联服务提供者 ID；通过此项来关联到 provider 下配置的具体服务提供者 |
291+
| registration.[registrationId].client-id | 客户端 ID；从 OAuth2 服务网站获取的 Client ID |
292+
| registration.[registrationId].client-name | 客户端名称；内容自定义 |
293+
| registration.[registrationId].client-secret | 客户端密钥；从 OAuth2 服务网站获取的 Client Secret |
294+
| registration.[registrationId].authorization-grant-type | 授权许可类型；示例中为 `authorization_code`，更多信息请参考[The OAuth 2.0 Authorization Framework Authorization Grant types](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3) |
295+
| registration.[registrationId].client-authentication-method | 客户端认证方法；http method，示例中为 `post` |
296+
| registration.[registrationId].redirect-uri | 认证成功回调地址；支持模板语法 |
297+
| registration.[registrationId].scope | 请求范围；指从授权请求获取的内容范围，例如 openid、email 或 profile。示例中从授权请求获取了 userinfo |
298+
| provider.[providerId] | 服务提供者 ID；自定义名称，示例中命名为 cas |
299+
| provider.[providerId].authorization-uri | 授权请求的 URL |
300+
| provider.[providerId].token-uri | 获取 Token 请求的 URL |
301+
| provider.[providerId].user-info-uri | 获取用户信息请求的 URL |
302+
| provider.[providerId].user-name-attribute | 用户信息中用于标记用户名称或 ID 的属性。示例中为 id |
303+
| provider.[providerId].userMapping | 用户信息与 datart 用户的属性映射设置。datart 通过该映射配置来定位到系统中的具体用户 |
304+
305+
如想了解更多信息，可以参考 [spring security oauth2](https://docs.spring.io/spring-security/site/docs/5.2.12.RELEASE/reference/html/oauth2.html) 官方文档。
306+
307+
#### 2.8.2 LDAP
308+
309+
启用 LDAP 登录需要在 `spring.ldap` 下配置客户端信息。下面为开启 LDAP 登录的配置示例：
310+
311+
```yaml
312+
spring:
313+
ldap:
314+
urls: ldap://{IP}:{PORT}
315+
base: xxx
316+
username: { username }
317+
password: { password }
267318
```
319+
320+
| 配置项 | 说明 |
321+
| -------- | ------------------------------------------------------------------------------------------------------------- |
322+
| urls | LDAP 服务器 URL；格式固定为 `ldap://服务IP或域名:端口` |
323+
| base | 基本专有名称（DN） |
324+
| username | 使用 LDAP 服务器进行身份验证时使用的用户名（principal）；常规情况下为管理员用户的 DN（例如 cn=Administrator） |
325+
| password | 使用 LDAP 服务器进行身份验证时使用的密码（credentials） |

0 commit comments

Comments
 (0)