私有部署的安装
使用安装程序
对于不太了解 docker 容器化技术的用户,如果您的操作系统是 Windows 或者 Mac 系统,Sugar 提供了安装客户端来方便安装。
手动安装
Sugar的部署,对机器环境要求:
软件环境
Docker
需要您的机器安装Docker
,推荐版本为v17
及以上,Sugar可以直接运行在单机 Docker 环境上,如果需要集群化、高可用,可以使用 Docker 自带的 swarm 或者 kubernetes;Sugar的安装部署过程中需要您对 Docker 的基础知识有所了解,详见Docker 官网。
Docker 的安装建议参考官方文档,可以安装在Centos、Ubuntu、Windows、Mac等系统上。
如果 Docker 官网访问比较慢,可以试试百度网盘(提取码: 8ym5)。
MySQL
推荐使用MySQL 5.7
版本(如果用 MySQL 8 需要 --default-auth=mysql_native_password
),该 MySQL 数据库用来存储Sugar的系统数据,MySQL 需要您自己安装和运维,并且需要给Sugar创建一个空的数据库如sugarbi(排序规则使用utf8_general_ci
);当然,您可以使用 Docker 来快速安装 MySQL,详见Docker MySQL,现提供单机 Docker 情况下安装启动 MySQL 并创建sugarbi数据库流程:
上图中主要的命令行(其中lovesugar123
即数据库 root 账户的密码,您可以改成自己想要的密码):
mkdir ~/mysqlData
docker run --ulimit nofile=65100:65100 --restart unless-stopped --name sugar-mysql -p 3306:3306 -v ~/mysqlData:/var/lib/mysql -e MYSQL_ROOT_PASSWORD=lovesugar123 -d mysql:5.7 --max_allowed_packet=100M --max_connections=1000
docker run -it --link sugar-mysql:mysql --rm mysql:5.7 sh -c 'exec mysql -h"$MYSQL_PORT_3306_TCP_ADDR" -P"$MYSQL_PORT_3306_TCP_PORT" -uroot -p"$MYSQL_ENV_MYSQL_ROOT_PASSWORD"'
CREATE DATABASE IF NOT EXISTS `sugarbi` DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;
对于 MySQL,我们建议您进行每天定时备份,防止机器故障导致数据丢失,使用上图的方式,我们已经将 MySQL 的数据挂载到了~/mysqlData
文件夹下。
硬件环境
如果用户数不多(如不超过 100 人)且不严格要求高可用,单机运行即可,否则视具体情况推荐使用 Docker swarm 集群方式扩展机器;每台机器的配置建议:内存 8G 或以上、CPU(4 核或以上,如 Intel 至强 E5、酷睿 i7 或以上)、硬盘(256GB SSD 或以上)
下载
我们提供了两种获取Sugar安装包镜像的方式:
1、百度云的 docker 镜像服务
Sugar的镜像已经上传到百度云 docker 镜像服务,您可以使用以下命令获取Sugar镜像:
docker pull registry.baidubce.com/sugarbi/sugar:3.0.1
docker tag registry.baidubce.com/sugarbi/sugar:3.0.1 sugarbi/sugar:3.0.1
// 查看刚刚拉取的镜像
docker images
3.0.1
是目前Sugar的最新版本,其他的版本可参考更新日志。此种方式要求您的部署机器能够连接互联网;如果您的部署机器不能直接连接到互联网,可以使用下面的方式。
2、直接在线下载
如果您的部署机器不能连接互联网,您可以在联网的机器上点击这里下载,然后将下载的安装包拷贝到部署机器上,注意:如果您使用 swarm 来同时部署到多台机器上,需要将下载的安装包文件拷贝到所有部署机器上,并且以下的操作也需要在所有部署机器上执行。
在部署的机器上,进入到您拷贝的安装包的同目录下,
docker load -i ./sugarbi-3.0.1.tar.gz
// 上面的命令会执行数十秒,然后执行以下命令查看刚刚load的镜像
docker images
使用上面的两种方式下载Sugar的安装镜像,在最后执行docker images
都能看到如下展示即证明下载成功:
运行 Sugar
Sugar是基于 Docker 容器化的运行模式,所以安装也会比较简单,主要是提供相应的配置文件(MySQL 连接配置、License 配置等),其他基本就是一键启动。Sugar的启动有两种方式,分别对应 Docker 单机模式和多机集群模式:
一、Docker 单机运行
在 Docker 单机环境下运行Sugar很简单,分两步:
- 1、新建一个名为
env
的文件(文件名没有后缀,就是 env),并用文本编辑器打开,复制以下的内容并填写相应部分:
love_sugar=true
sugar_can_connect_local_ip=true
# MySQL数据库相关
sugar_db_username=root
sugar_db_password=lovesugar123
sugar_db_database=sugarbi
sugar_db_host=填写您安装MySQL机器的IP,即使是本机也不能使用localhost和127.0.0.1
sugar_db_port=3306
# redis配置
# 如果您需要「SQL模型中的数据缓存」或者「定时邮件」功能,需要配置这块,否侧不需要配置
# 如果您私有部署只是单机运行(即只运行一个sugar的实例),sugar已经内置,这块不需要配置
# 否则需要您自己搭建redis(2.6版本以上,最好是5的版本,可以使用类似上面mysql的docker方式来启动一个redis)
sugar_redis_host=
sugar_redis_port=
sugar_redis_password=
# license相关
sugar_company=license的组织代码
sugar_license=具体license
# 登录形式,支持 demo、email、password、oauth
# 如果是最初步的测试,可以使用demo方式,后面的其他登录方式的配置都可以不用填写
sugar_login_type=demo
# email登录模式的配置,以及「定时邮件」功能也需要这块的配置,host 是 smtp 服务器
sugar_email_host=
# port 一般是 25 或 465
sugar_email_port=
sugar_email_username=
sugar_email_password=
sugar_email_from=
# 如果 smtp 端口是 465 则需要去掉下面的注释
# sugar_email_tls=true
# oauth登录模式的配置
sugar_oauth_authorize_url=
sugar_oauth_token_url=
sugar_oauth_client_id=
sugar_oauth_client_secret=
sugar_oauth_scope=
sugar_oauth_info_url=
sugar_oauth_data_username=
sugar_oauth_data_useremail=
sugar_oauth_email_suffix=
sugar_oauth_logout_url=
sugar_oauth_token_get=
# token登录模式的配置
sugar_token_login_url=
sugar_token_login_getTokenPath=
sugar_token_login_getUserInfoURL=
sugar_token_login_getUserInfoMethod=
sugar_token_login_getUserInfoSendTokenPath=token
sugar_token_login_getUserInfoGetUserEmailPath=
sugar_token_login_getUserInfoGetUserNamePath=
sugar_token_login_email_suffix=
# 是否HTTPS,只有您部署的sugar并且设置了HTTPS证书时才需要配置
sugar_is_https=
# 是否忽略SQL语句的安全检查(准许SQL中出现drop、delete等关键词),默认是都检查,填写true时将不检查,1.9.1版本之后才支持
sugar_ignore_sql_security_check=false
# 私有部署下是否不显示home首页,直接跳到login登录页面
sugar_home_redirect_login=false
# 私有部署下是否不显示文档页面,直接跳转到login登录页面
sugar_docs_redirect_login=false
# 私有部署下是否不展示顶部导航中的文档相关入口
sugar_hide_docs_link=false
# 私有部署下是否隐藏空间广场右侧的官方示例和整个公告栏
sugar_hide_demo_and_news=false
# 私有部署下是否隐藏空间广场右下脚的产品动态
sugar_disable_product_news=0
# 私有部署下是否隐藏空间广场右下脚的快速入门
sugar_disable_entry=0
上面每项配置的具体含义详见下一章节运行配置说明
- 2、在
env
文件的目录下执行以下命令来启动Sugar
为了能让您方便的看到Sugar的日志,所以我们使用 Docker 的 Volume 将日志挂载到宿主机,新建文件夹~/sugar-log
(Sugar的运行日志将存贮在这个目录下,当然目录名称您可以随意修改,同步替换下面命令中的即可):
docker run --ulimit nofile=65100:65100 --shm-size=4g --restart unless-stopped -d -p 8000:8580 --name sugar -v ~/sugar-log:/sugar-app/log --env-file env sugarbi/sugar:3.0.1
有时您的 docker 网络环境可能配置有问题,会导致 MySQL 数据库连接不上,Sugar 还有另外一种方式 link 的方式启动。如果您的 MySQL 和 Sugar 运行在同一台机器上,并且 MySQL 是使用上面的 docker 方式启动的,您可以在env
文件中将sugar_db_host
填写为sugar-mysql
,然后使用下面的命令来启动:
docker run --link sugar-mysql --ulimit nofile=65100:65100 --shm-size=4g --restart unless-stopped -d -p 8000:8580 --name sugar -v ~/sugar-log:/sugar-app/log --env-file env sugarbi/sugar:3.0.1
其中 8000 是本地端口,可以修改成自己想要的端口,比如 80,最后在浏览器上访问 http://部署的机器 ip:8000 如果是本机部署,即访问 http://127.0.0.1:8000 ,浏览器成功访问Sugar的首页之后,您还必须进行下面的「同步数据库结构」步骤。
同步数据库结构
前面已经描述了Sugar需要您提供一个 MySQL 数据库,这个数据库用来存储Sugar的系统数据。在您第一次安装Sugar、或者每次升级Sugar时,都需要进行数据库结构的升级和同步。升级数据库结构非常简单,只需要您使用浏览器访问 http://部署的机器 ip:8000/migration 如果是本机部署,即访问 http://127.0.0.1:8000/migration , 首次访问该页面大约需要数十秒,请不要刷新浏览器耐心等待一会,如果同步成功将会看到类似下面的结果:
之后如果您多次访问该页面,将会看到这样的成功提示:
如果运行失败,您会看到类似下面的错误提示:
二、swarm 集群部署
Sugar本身是无状态的,支持多机部署来提升产品可用性,Sugar 可以部署到任意多台服务器上,然后使用类似 nginx 来做一个代理和负载均衡。
需要注意,多机模式除了需要自行搭建 MySQL 数据库,还需要再搭建一个 redis 服务,或者使用下面的方法直接内置进去。
Docker 多机集群模式,我们推荐使用 Docker 自带的 swarm,关于如何使用 swarm 请参考 Docker 官方文档。使用 swarm 部署Sugar分两步:
- 1、新建一个
sugar-compose.yml
文件,并用文本编辑器打开,复制以下的内容并填写相应部分:
下面已经将Sugar运行日志挂载到了宿主机的/sugar-log
目录下,需要您手动在所有机器上新建该目录,当然您可以使用其他的目录来存储日志。
version: '3.6'
services:
web:
image: registry.baidubce.com/sugarbi/sugar:3.0.1
deploy:
mode: replicated
# 部署的份数,可多份来提高系统的高可用性
replicas: 3
restart_policy:
condition: on-failure
ports:
- '8000:8580'
volumes:
- '/sugar-log:/sugar-app/log'
- type: tmpfs
target: /dev/shm
tmpfs:
size: 4096000000
networks:
- overlay
environment:
sugar_can_connect_local_ip: 'true'
# MySQL数据库相关
sugar_db_username: root
sugar_db_password: lovesugar123
sugar_db_database: sugarbi
sugar_db_host: 填写您安装MySQL机器的IP,即使是本机也不能使用localhost和127.0.0.1
sugar_db_port: 3306
# redis 配置,用于「SQL模型中的数据缓存」或者「定时邮件」等功能
sugar_redis_host: internal_redis
# sugar_redis_port: 如果自己搭建可能需要
# sugar_redis_password: 如果自己搭建可能需要
# license相关
sugar_company:
sugar_license:
# 登录形式,支持 demo、email、password、oauth
# 如果是最初步的测试,可以使用demo方式,后面的其他登录方式的配置都可以不用填写
sugar_login_type: demo
# email登录模式的配置,以及「定时邮件」功能也需要这块的配置
sugar_email_host:
sugar_email_port:
sugar_email_username:
sugar_email_password:
sugar_email_from:
# 如果邮箱端口是465, 则需要去掉下面的#号
# sugar_email_tls: true
# oauth登录模式的配置
sugar_oauth_authorize_url:
sugar_oauth_token_url:
sugar_oauth_client_id:
sugar_oauth_client_secret:
sugar_oauth_scope:
sugar_oauth_info_url:
sugar_oauth_data_username:
sugar_oauth_data_useremail:
sugar_oauth_email_suffix:
sugar_oauth_logout_url:
sugar_oauth_token_get:
# token登录模式的配置
sugar_token_login_url:
sugar_token_login_getTokenPath:
sugar_token_login_getUserInfoURL:
sugar_token_login_getUserInfoMethod:
sugar_token_login_getUserInfoSendTokenPath: token
sugar_token_login_getUserInfoGetUserEmailPath:
sugar_token_login_getUserInfoGetUserNamePath:
sugar_token_login_email_suffix:
# 是否HTTPS,只有您部署的sugar并且设置了HTTPS证书时才需要配置
sugar_is_https:
# 是否忽略SQL语句的安全检查(准许SQL中出现drop、delete等关键词),默认是都检查,填写true时将不检查,1.9.1版本之后才支持
sugar_ignore_sql_security_check: false
# 私有部署下是否不显示home首页,直接跳到login登录页面
sugar_home_redirect_login: false
# 私有部署下是否不显示文档页面,直接跳转到login登录页面
sugar_docs_redirect_login: false
# 私有部署下是否不展示顶部导航中的文档相关入口
sugar_hide_docs_link: false
# 私有部署下是否隐藏空间广场右侧的官方示例和公告栏
sugar_hide_demo_and_news: false
# 私有部署下是否隐藏空间广场右下脚的产品动态
sugar_disable_product_news: '0'
# 私有部署下是否隐藏空间广场右下脚的快速入门
sugar_disable_entry: '0'
internal_redis:
image: redis:5
deploy:
replicas: 1
networks:
- overlay
networks:
overlay:
上面每项配置的具体含义详见下一章节运行配置说明
- 2、在
sugar-compose.yml
文件的目录下执行以下命令来启动Sugar
docker stack deploy --compose-file sugar-compose.yml sugar
最后在浏览器上访问 http://部署的机器 ip:8000 即可看到Sugar的运行页面。并且也需要执行上面的同步数据库结构
使用 swarm 时,我们建议使用管理工具:portainer.io
三、kubernetes 集群部署
Sugar本身是无状态的,支持使用 kubernetes 集群方式来进行部署。
需要注意,kubernetes 集群部署方式除了需要自行搭建 MySQL 数据库,还需要再提供一个 redis 服务。
- 1、新建一个
sugar.yaml
文件,并用文本编辑器打开,复制以下的内容并填写相应部分:
kind: Deployment
apiVersion: apps/v1
metadata:
labels:
app: sugar
name: sugar-deployment
spec:
selector:
matchLabels:
app: sugar
replicas: 2 # 部署两份Pod实例,可根据实际情况修改
template:
metadata:
labels:
app: sugar
spec:
volumes:
- name: sugar-log
emptyDir: {} # 日志挂载的volume,可以根据实际情况修改
containers:
- name: sugar
image: registry.baidubce.com/sugarbi/sugar:3.0.1 # sugar的镜像地址,根据实际情况修改
ports:
- containerPort: 8580
volumeMounts:
- name: sugar-log
mountPath: /sugar-app/log
livenessProbe:
httpGet:
path: /static/user.png
port: 8580
initialDelaySeconds: 30
timeoutSeconds: 5
env:
- name: sugar_can_connect_local_ip
value: '1'
# MySQL数据库相关配置,必填
- name: sugar_db_host
value: 填写您安装MySQL机器的IP,即使是本机也不能使用localhost和127.0.0.1
- name: sugar_db_port
value: '3306'
- name: sugar_db_database
value: sugarbi
- name: sugar_db_username
value: root
- name: sugar_db_password
value: lovesugar123
# redis配置,必填,需要给sugar提供一个外部的redis服务,用于「SQL模型中的数据缓存」或者「定时邮件」等功能
- name: sugar_redis_host
value:
- name: sugar_redis_port
value:
- name: sugar_redis_password # 根据实际情况,一般不需要
value:
# license相关,必填
- name: sugar_company
value:
- name: sugar_license
value:
# 登录形式,必填,支持 demo、email、password、oauth、token
- name: sugar_login_type
value: demo
# email登录模式的配置,以及「定时邮件」功能也需要这块的配置
- name: sugar_email_host
value:
- name: sugar_email_port
value:
- name: sugar_email_username
value:
- name: sugar_email_password
value:
- name: sugar_email_from
value:
- name: sugar_email_tls # 如果邮箱端口是465,则需要配置为true
value:
# oauth登录模式的配置
- name: sugar_oauth_authorize_url
value:
- name: sugar_oauth_token_url
value:
- name: sugar_oauth_client_id
value:
- name: sugar_oauth_client_secret
value:
- name: sugar_oauth_scope
value:
- name: sugar_oauth_info_url
value:
- name: sugar_oauth_data_username
value:
- name: sugar_oauth_data_useremail
value:
- name: sugar_oauth_email_suffix
value:
- name: sugar_oauth_logout_url
value:
- name: sugar_oauth_token_get
value:
# token登录模式的配置
- name: sugar_token_login_url
value:
- name: sugar_token_login_getTokenPath
value:
- name: sugar_token_login_getUserInfoURL
value:
- name: sugar_token_login_getUserInfoMethod
value:
- name: sugar_token_login_getUserInfoSendTokenPath
value: token
- name: sugar_token_login_getUserInfoGetUserEmailPath
value:
- name: sugar_token_login_getUserInfoGetUserNamePath
value:
- name: sugar_token_login_email_suffix
value:
# 是否HTTPS,只有您部署的sugar并且设置了HTTPS证书时才需要配置
- name: sugar_is_https
value:
# 是否忽略SQL语句的安全检查(准许SQL中出现drop、delete等关键词),默认是都检查,填写true时将不检查,1.9.1版本之后才支持
- name: sugar_ignore_sql_security_check
value: 'false'
# 私有部署下是否不显示home首页,直接跳到login登录页面
- name: sugar_home_redirect_login
value: 'false'
# 私有部署下是否不显示文档页面,直接跳转到login登录页面
- name: sugar_docs_redirect_login
value: 'false'
# 私有部署下是否不展示顶部导航中的文档相关入口
- name: sugar_hide_docs_link
value: 'false'
# 私有部署下是否隐藏空间广场右侧的官方示例和公告栏
- name: sugar_hide_demo_and_news
value: 'false'
# 私有部署下是否隐藏空间广场右下脚的产品动态
- name: sugar_disable_product_news
value: '0'
# 私有部署下是否隐藏空间广场右下脚的快速入门
- name: sugar_disable_entry
value: '0'
---
kind: Service
apiVersion: v1
metadata:
labels:
app: sugar
name: sugar-service
spec:
ports:
- port: 8580
targetPort: 8580
nodePort: 32580
type: NodePort # 这块使用NodePort方式,并且配置了nodePort为32580端口,可以根据实际情况修改
selector:
app: sugar
上面每项配置的具体含义详见下一章节运行配置说明
- 2、在
sugar.yaml
文件的目录下执行以下命令来启动Sugar
kubectl apply -f sugar.yaml
最后在浏览器上访问 http://部署的机器 ip:32580 即可看到Sugar的运行页面。并且也需要执行上面的同步数据库结构
运行配置说明
无论是 Docker 单机还是 Docker 集群模式运行Sugar,基本都是配置一些 env 环境变量,下面对这些环境变量配置进行说明:
sugar_can_connect_local_ip
:用来控制Sugar的数据源中是否能够连接局域网的 ip,一般私有部署情况下,配置为true
即可,配置false
可以让Sugar只能连接公网域名和 ip-
MySQL 数据库相关,这块是用来配置Sugar所依赖的 MySQL 数据库,详见Sugar 所需的软件环境
sugar_db_username
: 用户名sugar_db_password
: 密码sugar_db_database
: 数据库名称sugar_db_host
: 填写您安装 MySQL 机器的 IP,即使是本机也不能使用 localhost 和 127.0.0.1sugar_db_port
: 端口号
-
License 配置,详见申请试用 License
sugar_company
: 组织代码sugar_license
: 详细的 License 内容(长串字符)
登录账号相关配置说明
sugar_login_type
: 登录账号的类型,支持 demo、password、email、oauth、token,下面对这五种登录形式分别说明:
1、demo
sugar_login_type
配置为demo
表示测试环境,登录时必须使用企业邮箱,但是验证码不会通过邮件发送,而是直接展示在页面上,用户直接复制页面上展示的验证码即可登录,如下图:
2、password
sugar_login_type
配置为password
表示使用Sugar平台自带的账号体系,用户通过用户名、密码来登录Sugar,账号可由组织的管理员统一录入。
如果您之前已经使用其他的登录方式进行了部署并登录过了Sugar私有版(例如:之前使用demo
方式部署并且登录使用了,即您私有部署的Sugar中已经有账户了),那么直接使用之前登录的企业邮箱以及默认密码sugar12345
即可直接登录。如果是初次部署,之前还没有任何用户登录过Sugar私有版,在登录之前我们需要创建一个默认账户(此账户将会成为组织的管理员),使用浏览器访问 http://部署的机器 ip:8000/openapi/createUser?name=*
即可创建一个默认的组织管理员账户,其中的*
需要按照实际情况替换成您的企业邮箱如zhangsan@baidu.com
。
创建完默认账户后,在登录时直接使用默认密码sugar12345
即可登录:
默认的组织管理员账户登录之后,可以在「组织管理」的「用户管理」中来添加其他的用户(添加的其他用户,登录密码同样是默认的sugar12345
):
所有的用户在登录之后,可点击页面顶部的「个人中心」,然后进入「个人信息管理」来修改登录密码:
如果有用户忘记了密码,组织的管理员也可以将用户的密码重置为sugar12345
,可以在「组织管理」的「用户管理」中进行密码重置操作:
3、email
sugar_login_type
配置为email
表示使用邮箱发送验证码的方式来登录。这种方式要求您的组织有企业邮箱服务,需要您给Sugar平台配置一个企业邮箱账号,该邮箱账号用来给您的组织员工发送登录验证码邮件,所以需要您填写配置文件中的这些配置:
sugar_email_host
: 您的企业邮箱服务器的域名或 ipsugar_email_port
: 企业邮箱服务器的端口号sugar_email_username
: 给Sugar使用的邮箱账户用户名,如 zhangsansugar_email_password
: 给Sugar使用的邮箱账户密码sugar_email_from
: Sugar发送邮件时的发件人邮箱,一般和邮箱用户名强相关,如 zhangsan@baidu.comsugar_email_tls
: 如果这个端口是 tls 的(比如 465 端口很可能是)则需要加这个配置,值是 true,如果不是就不需要加
4、oauth
sugar_login_type
配置为oauth
,Sugar支持使用 OAuth 2.0 的方式对接企业内部账号的单点登录系统,需要您对配置文件中的以下配置进行填写:
sugar_oauth_authorize_url
: Sugar向您的 Oauth 服务端申请认证的 URI,如 https://your-authorization-server-host/authsugar_oauth_token_get
: 默认情况下请求 sugar_oauth_authorize_url 的方式是 POST,如果需要使用 GET 方式,将该配置设置为1
即可sugar_oauth_token_url
: Sugar向您的 Oauth 服务端获取 Access Token 的 URI,如 https://your-authorization-server-host/tokensugar_oauth_client_id
: 您的 Oauth 服务端给Sugar分配的 client_idsugar_oauth_client_secret
: 您的 Oauth 服务端给Sugar分配的 client_secretsugar_oauth_scope
: 授权的范围 scope,依赖您的 Oauth 服务端,目前必填sugar_oauth_info_url
: 通过认证后,Sugar向您的 Oauth 服务端获取当前登录用户详细信息的 API,如 https://your-authorization-server-host/userinfosugar_oauth_data_username
: 用户详细信息的 API 返回数据中用来表示用户名的字段名,如 namesugar_oauth_data_useremail
: 用户详细信息的 API 返回数据中用来表示用户邮箱的字段名,如 emailsugar_oauth_email_suffix
: 如果用户详细信息的 API 返回数据中没有邮箱字段,那么我们将默认使用 用户名@${sugar_oauth_email_suffix} 方式来拼凑成邮箱,所以需要您配置您组织的企业邮箱后缀,如 baidu.comsugar_oauth_logout_url
: 当用户在Sugar上 logout 登出之后,跳转到 OAuth 服务端的登出 url,如果不配置将会默认跳转到Sugar的首页
Sugar使用的是 OAuth 2.0 的授权码模式,可参考这里了解 Oauth 2.0 的授权码模式。
上面的 OAuth 2.0 的配置,前五项都是标准的 Oauth 配置,有些 OAuth 的 server 端需要明确配置应用的redirect_uri
(即登录回调 url),Sugar的redirect_uri
是 http://部署 Sugar 的机器 ip:8000/login/oauthCallback
上面sugar_oauth_info_url
以及后面的三行是用来配置Sugar通过您的 Oauth 服务端认证后,获取当前登录用户的详细信息的 API 以及该 API 返回的数据字段信息。访问该 API 时,我们在请求的 header 头文件中加上了Authorization: Bearer ${access_token}
这样的 access_token
信息,并且在 API 的参数中也加上了,如:https://your-authorization-server-host/userinfo?access_token=${access_token}
该 API 的返回必须是 JSON 格式数据,对于最后三项配置我们根据返回 JSON 的不同格式来做简单的示例:
-
返回 JSON 如:{usermail: 'zhangsan@baidu.com', username: 'zhangsan'} 那么最后三项配置为:
sugar_oauth_data_username
: usernamesugar_oauth_data_useremail
: usermailsugar_oauth_email_suffix
:
此时返回的 JSON 数据中用户的邮箱,所以不需要配置sugar_oauth_email_suffix
-
返回 JSON 如:{name: 'zhangsan'} 那么最后三项配置为:
sugar_oauth_data_username
: namesugar_oauth_data_useremail
:sugar_oauth_email_suffix
: baidu.com
此时返回的 JSON 数据中没有用户的邮箱,所以不需要配置sugar_oauth_data_useremail
,但是必须要配置sugar_oauth_email_suffix
(注意并不是固定的 baidu.com,需要根据实际情况替换成您的企业邮箱后缀)
-
返回 JSON 如:{email: 'zhangsan@baidu.com'} 那么最后三项配置为:
sugar_oauth_data_username
:sugar_oauth_data_useremail
: emailsugar_oauth_email_suffix
:
此时返回的 JSON 数据中只有用户的邮箱,只需要配置邮箱字段名sugar_oauth_data_useremail
即可
5、token
sugar_login_type
配置为token
,Sugar 的 token 登录方式是一种便于业务方对接的登录方式,登录流程如下:
- a、Sugar 检测到用户未登录,跳转到业务方指定页面 URL1 进行登录操作
- b、用户登录成功后,业务方带上一个 token 回调 Sugar 的指定 URL2:
http://部署 Sugar 的机器 ip:8000/login/tokenLoginCallback?token=${token}
- c、我们会使用这个 token 调用业务方的 URL3 获取登录用户的信息并在 Sugar 中进行登录
需要您对配置文件中的以下配置进行填写:
sugar_login_type
: tokensugar_token_login_url
: 未登录时要跳转到的业务方登录页 url,对应流程中的 URL1sugar_token_login_getTokenPath
: 用户在登录页登录后,业务方访问 Sugar 回调 URL2 时,携带 token 信息的字段的名称,默认为 token ,如果是其他名称可以在这里配置sugar_token_login_getUserInfoURL
: 业务方提供的使用 token 获取用户信息的接口地址,对应流程中 URL3sugar_token_login_getUserInfoMethod
: 访问 URL3 的 http 方法,默认为 post,请求体为 json 格式;如果是 get 可以配置这里为:getsugar_token_login_getUserInfoSendTokenPath
: 访问 URL3 时,token 信息在请求中放置的位置。如果使用 POST 方法,配置 token 的放置路径,路径的起点为请求的 body,格式如:data.token;如果是 get 方法,直接配置在 url params 中的字段名即可。sugar_token_login_getUserInfoGetUserEmailPath
: 在获取到 URL3 的返回信息后,用户邮箱字段在返回体中的路径,路径格式例如:data.userEmail。这个字段用来在 Sugar 中唯一标识一个用户,最好是企业内的用户邮箱,如果没有,可以使用户名等字段,保证唯一即可sugar_token_login_email_suffix
: 如果业务方系统中没有使用用户邮箱作为用户标识,我们会在用户标识后添加一个 @example.com 作为邮箱后缀,您也可以通过这个环境变量自己配置这个邮箱后缀sugar_token_login_getUserInfoGetUserNamePath
: 在获取到 URL3 的返回信息后,用户名称字段在返回体中的路径,是用户真正看到的名字,路径格式例如:data.realName
日志说明以及自动清理
如上面的部署示例配置中,无论是单机 docker 部署、还是 swarm 集群部署,我们都将 Sugar 的日志挂载到了宿主机的某个目录下,在该目录下会有两个子目录:
access
:该目录下存储了所有访问的 access 日志,日志文件按照小时进行切分,例如 2021 年 01 月 01 日 08 时的 access 日志文件为:access.log.2021010108
sugar
:该目录下存储了所有的 Sugar 业务日志,包括正常的系统日志以及异常时的错误日志,日志文件也是按照小时进行切分,正常的系统日志文件名如:sugar.log.2021010108
,异常时的错误日志文件名如:sugar.log.wf.2021010108
,当您的私有部署中遇到问题时,可以尝试在错误日志中查看详细的日志记录。
从 3.0.1
版本及之后, Sugar 中支持了日志文件的自动清理,默认情况下,系统将保留最近90天
的日志文件,其余日志文件将会被自动清理。当然,你也可以配置日志文件保留的天数,可以在env
文件中添加以下配置(下面的配置表示日志文件保留120天
,如果你不想要自动清理日志文件,想要永久保留日志文件,将下面的配置填写为0
即可):
sugar_log_lifetime_day=120
Nginx 代理和 HTTPS 设置
如果您需要对私有部署的Sugar使用域名访问并且使用Nginx 来做转发代理,需要在 Nginx 代理配置中加上proxy_set_header Host $http_host;
,这样能把域名信息透传到Sugar中以保证登录回调等各种功能运行正常。
如果您需要使用HTTPS
来访问Sugar,你必须要使用上面描述的 Nginx 代理方式,需要您自己在 Nginx 层来配置 HTTPS 的证书(可以自行百度搜索配置方式),并且需要对Sugar运行配置env
文件中sugar_is_https
进行填写,填写为:sugar_is_https=1
。(swarm 运行方式下即对sugar-compose.yml
文件中填写sugar_is_https: 1
)
开启定时邮件功能
如果私有部署中您需要使用定时邮件功能,需要配置上面 env 中的 sugar_email_host
、sugar_redis_host
等,下面详细说明:
1、redis 相关配置,如果您私有部署只是单机运行(即只运行一个 sugar 的实例),sugar 已经内置,就不需要配置 redis 相关内容;如果是集群方式,需要您自己搭建 redis(2.6 版本以上,可以使用类似上面 mysql 的 docker 方式来启动一个 redis),然后需要您在 env 配置中填写 sugar_redis_host
(redis 的 host)、sugar_redis_port
(redis 的端口,默认是 6379)、sugar_redis_password
(redis 的密码,只有 redis 中设置了才需要填写,否则可以不填)
2、发送的邮箱: Sugar中已经内置了邮件发送器,但是,如果您需要固定发件人邮箱(如:sugar@yourCompany.com),那就需要您在 env 配置中填写 sugar_email_host
、sugar_email_port
、 sugar_email_username
、sugar_email_password
、sugar_email_from
邮箱相关的设置
开启 Excel/CSV 文件上传功能
如果要开启 Excel/CSV 文件上传功能(部署的 Sugar 版本需要是 1.9.5 及以上),需要在上面的配置中增加以下配置:
sugar_enable_mpp=1
sugar_mpp_use_cluster=m1
sugar_mpp_hashids=sugar
sugar_mpp_cluster_m1_type=mysql
sugar_mpp_cluster_m1_host=数据库地址
sugar_mpp_cluster_m1_port=数据库端口
sugar_mpp_cluster_m1_user=数据库用户名,最好是root账户,需要有创建账户、创建数据库、创建数据表的权限
sugar_mpp_cluster_m1_password=数据库密码
Excel 上传的实现原理是将文件导入数据库中,后续就能类似普通的数据源一样进行处理,您需要修改上面尖括号中的内容为您自己启动的服务器,目前数据库类型只支持 mysql,可以使用 MySQL 或 TiDB。
这个功能依赖 MySQL 的 LOAD DATA LOCAL INFILE
,所以如果有类似 Error Code 1148: The used command is not allowed with this MYSQL version
的报错,请在 MySQL 配置里开启 local_infile
开启数据预测功能
数据预测依赖另一个镜像,首先用下面命令下载和运行:
docker pull registry.baidubce.com/sugarbi/sugar-forecast:1.0.2
docker tag registry.baidubce.com/sugarbi/sugar-forecast:1.0.2 sugarbi/sugar-forecast:1.0.2
docker run --ulimit nofile=65100:65100 --restart unless-stopped -d -p 8043:8043 --name sugar sugarbi/sugar-forecast:1.0.2
上面的例子在主机开启了 8043 端口,然后在 sugar 的 env 中增加配置,其中 10.10.10.10 需要改成主机 IP:
sugar_enable_forecast=1
sugar_forecast_service='http://10.10.10.10:8043/prophet'
开启 AI 问答功能
如果您同时购买了 AI 问答的私有部署,并部署好了 AI 问答服务器,在 Sugar 的环境变量中加入下列变量开启该功能:
# 问答模型管理 API 地址,host 和 port 部分根据实际服务器部署情况替换
sugar_nlp_manage_endpoint=http://10.14.155.44:8096/unit/v3
# 问答 API 地址,host和 port 部分根据实际服务器部署情况替换
sugar_nlp_query_endpoint=http://10.14.155.44:8018/unit/bot/chat
sugar_nlp_open=1
# 最多可以创建多少个技能(一个技能下可包含大约 30 个数据模型),与部署问答服务的服务器配置有关,部署时与技术人员确认后填写
sugar_nlp_private_max_skill_num=3
开启 AI 问答的语音输入
如果您部署 Sugar 的服务器可以访问外网,您还可以开启 AI 问答功能的语音输入,需要提前开通百度云的短语音识别服务,有 200W 次的免费调用额度,用尽后收费大约每百万次千元级别。然后在环境变量中加入下列配置:
# 语音识别的 appid appkey secretkey,可以在上面的百度云控制台中找到
sugar_audio_recognize_appid=''
sugar_audio_recognize_appkey=''
sugar_audio_recognize_secretkey=''
自定义产品 Logo
你可以自定义 Sugar 的产品 Logo,在env
中增加配置即可(2.2.3 版本及以上才支持),如:
sugar_logo=填写Logo的网络图片地址,如:https://www.baidu.com/favicon.ico
自定义 JDBC 驱动
如果您使用的数据库不在我们支持的列表中,但有对应的 JDBC 驱动,可以通过如下方式来添加这个:
- 首先创建某个目录,比如 /home/work/jdbc/libs,将 jar 文件放到这个目录里
- 在 docker 镜像启动时用 -v 将这个目录映射为 /sugar-app/javakit/libs,参考如下写法
docker run --link sugar-mysql --ulimit nofile=65100:65100 --shm-size=4g --restart unless-stopped -d -p 8000:8580 --name sugar -v /home/work/jdbc/libs:/sugar-app/javakit/libs -v ~/sugar-log:/sugar-app/log --env-file env registry.baidubce.com/sugarbi/sugar:3.0.1
然后在创建数据源时选择「JDBC 通用数据库」。
需要注意自定义 JDBC 驱动的数据库在「测试连接」时有可能报错(但不影响正常使用),而且很可能无法使用「数据预览」功能,如果发现有问题请联系我们。
自定义内置第三方 JS、CSS 库
如果内置的第三方库不能满足需求,又无法使用外联的方式,可以用如下方式来添加:
- 创建一个目录,比如 /home/work/library,然后将第三方库放置到这里,比如 echarts.js
- 在 docker 镜像启动时用 -v 将这个目录映射为 /sugar-app/static/library,参考如下写法
docker run --link sugar-mysql --ulimit nofile=65100:65100 --shm-size=4g --restart unless-stopped -d -p 8000:8580 --name sugar -v /home/work/library:/sugar-app/static/library -v ~/sugar-log:/sugar-app/log --env-file env registry.baidubce.com/sugarbi/sugar:3.0.1
前端引用的路径就将是 <script src="/static/library/echarts.js"></script>