极狐GitLab Mattermost

您可以在您的极狐GitLab 服务器上运行极狐GitLab Mattermost 服务。Mattermost 不是极狐GitLab 的单一应用程序的一部分,与极狐GitLab 之间有很好的集成,我们的 Omnibus 安装程序允许您轻松安装它。但它是来自一家独立公司的独立应用程序。

前提条件

极狐GitLab Mattermost 的每个版本都是在 Linux 的 AMD 64 芯片组上编译和手动测试的。不支持 ARM 芯片组和操作系统,如 Raspberry Pi。

快速入门

极狐GitLab Mattermost 希望在自己的虚拟主机上运行。在您的 DNS 设置中,您需要两个指向同一台机器的条目,例如,gitlab.example.commattermost.example.com

极狐GitLab Mattermost 默认是禁用的。要启用它:

  1. 编辑 /etc/gitlab/gitlab.rb 并添加 Mattermost 外部 URL:

    mattermost_external_url 'https://mattermost.example.com'
    
  2. 重新配置极狐GitLab:

    sudo gitlab-ctl reconfigure
    
  3. 确认极狐GitLab Mattermost 可通过 https://mattermost.example.com 访问并被授权连接到极狐GitLab。使用极狐GitLab 授权 Mattermost 允许用户将极狐GitLab 用作 SSO 提供商。

如果应用程序在同一台服务器上运行,Omnibus GitLab 包会尝试使用极狐GitLab 自动授权极狐GitLab Mattermost。

自动授权需要访问极狐GitLab 数据库。如果极狐GitLab 数据库不可用,您将需要使用授权极狐GitLab Mattermost 部分中描述的过程,手动授权极狐GitLab Mattermost 以访问极狐GitLab。

配置 Mattermost

可以使用 Mattermost 系统控制台配置 Mattermost。在 Mattermost 文档中 提供了大量的 Mattermost 设置列表及其可以设置的位置。

虽然建议使用系统控制台,但您也可以使用以下选项之一配置 Mattermost:

  1. 直接通过 /var/opt/gitlab/mattermost/config.json 编辑 Mattermost 配置。
  2. 通过更改 gitlab.rb 中的 mattermost['env'] 设置来指定用于运行 Mattermost 的环境变量。以这种方式配置的任何设置都将从系统控制台禁用,并且必须重新启动 Mattermost 才能更改。

使用 HTTPS 运行极狐GitLab Mattermost

将 SSL 证书和 SSL 证书密钥放在 /etc/gitlab/ssl 中。如果目录不存在,请创建它:

sudo mkdir -p /etc/gitlab/ssl
sudo chmod 755 /etc/gitlab/ssl
sudo cp mattermost.gitlab.example.key mattermost.gitlab.example.crt /etc/gitlab/ssl/

/etc/gitlab/gitlab.rb 中指定如下配置:

mattermost_external_url 'https://mattermost.gitlab.example'
mattermost_nginx['redirect_http_to_https'] = true

如果还没有命名您的证书和密钥 mattermost.gitlab.example.crtmattermost.gitlab.example.key,那么还需要添加如下所示的完整路径。

mattermost_nginx['ssl_certificate'] = "/etc/gitlab/ssl/mattermost-nginx.crt"
mattermost_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/mattermost-nginx.key"

其中 mattermost-nginx.crtmattermost-nginx.key 分别是 SSL 证书和密钥。

设置完成后,运行 sudo gitlab-ctl reconfigure 以应用更改。

使用外部的 PostgreSQL 服务运行极狐GitLab Mattermost

默认情况下,Mattermost 使用 Linux 安全包捆绑的 PostgreSQL 服务。如果您想使用具有外部 PostgreSQL 服务的 Mattermost,这需要特定的配置。既有的极狐GitLab 使用外部 PostgreSQL 连接配置不会自动继承给 Mattermost。

  1. 编辑 /etc/gitlab/gitlab.rb 并制定如下配置:

    mattermost['sql_driver_name'] = 'postgres'
    mattermost['sql_data_source'] = "user=gitlab_mattermost host=<hostname-of-postgresql-service> port=5432 sslmode=required dbname=<mattermost_production> password=<user-password>"
    
  2. 创建一个与您在 mattermost['sql_data_source'] 中定义的用户名和密码值相匹配的 PostgreSQL 用户。
  3. 创建一个与所使用的 dbname 值相匹配的PostgreSQL数据库。
  4. 确保 user 拥有使用 dbname 创建的数据库的权限。
  5. 重新配置极狐GitLab 并重启 Mattermost 以让变更生效:
  6. Reconfigure GitLab and restart Mattermost to apply the changes:

    sudo gitlab-ctl reconfigure && sudo gitlab-ctl restart mattermost
    

在单独的服务器上运行极狐GitLab Mattermost

如果您想在两个独立的服务器上运行极狐GitLab 和极狐GitLab Mattermost,GitLab 服务仍将设置在您的极狐GitLab Mattermost 服务器上,但它们不会接受用户请求或消耗系统资源。您可以在极狐GitLab Mattermost 服务器上使用以下设置和配置详细信息,来有效禁用捆绑到 Omnibus 包中的极狐GitLab 服务。

mattermost_external_url 'http://mattermost.example.com'

# Shut down GitLab services on the Mattermost server
gitlab_rails['enable'] = false
redis['enable'] = false
postgres_exporter['enable'] = false
grafana['enable'] = false

然后按照 授权极狐GitLab Mattermost 部分 中的相应步骤操作。最后,要启用与极狐GitLab 的集成,请在极狐GitLab 服务器上添加以下内容:

gitlab_rails['mattermost_host'] = "https://mattermost.example.com"

默认情况下,GitLab Mattermost 要求所有用户注册极狐GitLab 并禁用通过电子邮件注册选项。请参阅 Mattermost 上的极狐GitLab SSO 文档

使用极狐GitLab 手动(重新)授权极狐GitLab Mattermost

重新授权极狐GitLab Mattermost

要重新授权极狐GitLab Mattermost,您首先需要撤销现有授权。可以在极狐GitLab 的 设置 > 应用 区域中完成。然后按照以下步骤完成授权。

授权极狐GitLab Mattermost

导航到极狐GitLab 中的 设置 > 应用 区域。创建一个新应用程序,并为 Redirect URI 使用以下内容(如果使用 HTTPS,请将 http 替换为 https):

http://mattermost.example.com/signup/gitlab/complete
http://mattermost.example.com/login/gitlab/complete

请注意,您无需在 范围 下选择任何选项。 选择 保存应用程序

创建应用程序后,您将获得一个“应用程序 ID”和“秘密”。 需要的另一条信息是极狐GitLab 实例的 URL。 返回运行极狐GitLab Mattermost 的服务器并使用您在上面收到的值编辑 /etc/gitlab/gitlab.rb 配置文件,如下所示:

mattermost['gitlab_enable'] = true
mattermost['gitlab_id'] = "12345656"
mattermost['gitlab_secret'] = "123456789"
mattermost['gitlab_scope'] = "read_user"
mattermost['gitlab_auth_endpoint'] = "http://gitlab.example.com/oauth/authorize"
mattermost['gitlab_token_endpoint'] = "http://gitlab.example.com/oauth/token"
mattermost['gitlab_user_api_endpoint'] = "http://gitlab.example.com/api/v4/user"

保存更改,然后运行 sudo gitlab-ctl reconfigure。 如果没有错误,您的极狐GitLab 和极狐GitLab Mattermost 应该正确配置。

指定用户和群组的数字标识符

Omnibus GitLab 创建一个用户和群组 mattermost。 您可以在 /etc/gitlab/gitlab.rb 中为这些用户指定数字标识符,如下所示:

mattermost['uid'] = 1234
mattermost['gid'] = 1234

运行 sudo gitlab-ctl reconfigure 以应用更改。

设置自定义环境变量

如有必要,您可以通过 /etc/gitlab/gitlab.rb 设置由 Mattermost 使用的自定义环境变量。如果 Mattermost 服务器在公司 Internet 代理后面运行,这会很有用。在 /etc/gitlab/gitlab.rb 中提供一个带有哈希值的 mattermost['env']。例如:

mattermost['env'] = {"HTTP_PROXY" => "my_proxy", "HTTPS_PROXY" => "my_proxy", "NO_PROXY" => "my_no_proxy"}

运行 sudo gitlab-ctl reconfigure 以应用更改。

连接到捆绑的 PostgreSQL 数据库

如果您需要连接到捆绑的 PostgreSQL 数据库并使用默认的 Omnibus GitLab 数据库配置,您可以作为 PostgreSQL 超级用户连接:

sudo gitlab-psql -d mattermost_production

备份极狐GitLab Mattermost

通用的 Mattermost 备份和灾难恢复 文档可用作需要备份的指南。

备份捆绑的 PostgreSQL 数据库

如果您需要备份捆绑的 PostgreSQL 数据库并使用默认的 Omnibus GitLab 数据库配置,您可以使用以下命令进行备份:

sudo -i -u gitlab-psql -- /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql mattermost_production | gzip > mattermost_dbdump_$(date --rfc-3339=date).sql.gz

备份 data 目录和 config.json

Mattermost 有一个 data 目录和 config.json 文件,它们也需要备份:

sudo tar -zcvf mattermost_data_$(date --rfc-3339=date).gz -C /var/opt/gitlab/mattermost data config.json

恢复极狐GitLab Mattermost

如果您之前创建了极狐GitLab Mattermost 的备份,您可以运行以下命令来恢复它:

# Stop Mattermost so we don't have any open database connections
sudo gitlab-ctl stop mattermost

# Drop the Mattermost database
sudo -u gitlab-psql /opt/gitlab/embedded/bin/dropdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production

# Create the Mattermost database
sudo -u gitlab-psql /opt/gitlab/embedded/bin/createdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production

# Perform the database restore
# Replace /tmp/mattermost_dbdump_2021-08-05.sql.gz with your backup
sudo -u mattermost sh -c "zcat /tmp/mattermost_dbdump_2021-08-05.sql.gz | /opt/gitlab/embedded/bin/psql -U gitlab_mattermost -h /var/opt/gitlab/postgresql -p 5432 mattermost_production"

# Restore the data directory and config.json
# Replace /tmp/mattermost_data_2021-08-09.gz with your backup
sudo tar -xzvf /tmp/mattermost_data_2021-08-09.gz -C /var/opt/gitlab/mattermost

# Fix permissions if required
sudo chown -R mattermost:mattermost /var/opt/gitlab/mattermost/data
sudo chown mattermost:mattermost /var/opt/gitlab/mattermost/config.json

# Start Mattermost
sudo gitlab-ctl start mattermost 

Mattermost 命令行工具 (CLI)

mmctl 是一个针对 Mattermost 服务器的命令行工作,安装在本地且使用 Mattermost API,当然也可以远程使用。您必须为 Mattermost 配置本地连接或使用本地登录凭据(不是通过极狐GitLab SSO)认证为管理员。可执行路径位于 /opt/gitlab/embedded/bin/mmctl

通过本地连接使用 mmctl

对本地连接,mmctl 二进制和 Mattermost 必须运行在同一个服务器上。要启用本地套接字(socket):

  1. 编辑 /var/opt/gitlab/mattermost/config.json,添加一下内容:

    {
        "ServiceSettings": {
           ...
            "EnableLocalMode": true,
            "LocalModeSocketLocation": "/var/tmp/mattermost_local.socket",
            ...
        }
    }
    
  2. 重启 Mattermost:

    sudo gitlab-ctl restart mattermost
    

然后您可以在您的 Mattermost 实例上使用 sudo /opt/gitlab/embedded/bin/mmctl --local 来运行 mmctl 命令。

比如,要展示用户列表:

$ sudo /opt/gitlab/embedded/bin/mmctl --local user list

13dzo5bmg7fu8rdox347hbfxde: appsbot (appsbot@localhost)
tbnkwjdug3dejcoddboo4yuomr: boards (boards@localhost)
wd3g5zpepjgbfjgpdjaas7yj6a: feedbackbot (feedbackbot@localhost)
8d3zzgpurp85zgf1q88pef73eo: playbooks (playbooks@localhost)
There are 4 users on local instance

通过远端连接使用 mmctl

对于不能够使用套接字(socket)的远端连接或本地连接,创建一个非 SSO 用户,然后赋予此用户管理员权限。这些凭据就可以被用来认证 mmctl 了:

$ /opt/gitlab/embedded/bin/mmctl auth login http://mattermost.example.com

Connection name: test
Username: local-user
Password:
 credentials for "test": "local-user@http://mattermost.example.com" stored

配置极狐GitLab 和 Mattermost 集成

您可以使用该插件订阅 Mattermost 以接收有关议题、合并请求和拉取请求的通知,以及有关合并请求审查、未读消息和任务分配的个人通知。如果您想使用斜杠命令来执行创建和查看议题等操作,或触发部署,请使用极狐GitLab Mattermost 斜杠命令

plugin 和 slash 命令可以一起使用或单独使用。

电子邮件通知

为极狐GitLab Mattermost 设置 SMTP

这些设置由系统管理员通过 Mattermost 系统控制台进行配置。在 系统控制台环境 > SMTP 选项卡上,您可以输入 SMTP 提供商提供的 SMTP 凭据,或者输入 127.0.0.1和端口 25 以使用 sendmailMattermost 文档 中提供了有关所需特定设置的更多信息。

这些设置也可以在 /var/opt/gitlab/mattermost/config.json 中配置。

电子邮件批处理

启用此功能允许用户控制他们接收电子邮件通知的频率。

通过转到 环境 > SMTP 选项卡,并将 Enable Email Batching 设置为 True,可以在 Mattermost 系统控制台 中启用电子邮件批处理。

这个设置也可以在 /var/opt/gitlab/mattermost/config.json 中配置。

升级极狐GitLab Mattermost

note 升级 Mattermost 版本时,务必查看 Mattermost 的 重要升级说明 以解决需要执行的任何更改或迁移。

GitLab Mattermost 可以通过常规的 Omnibus GitLab 更新过程进行升级。当升级以前版本的极狐GitLab 时,只有在极狐GitLab 之外没有更改 Mattermost 配置设置的情况下才能使用该过程(即没有直接或通过 Mattermost 系统控制台 对 Mattermost 的 config.json 文件进行任何更改,后者会将更改保存回 config.json。)

如果只使用 gitlab.rb 配置了 Mattermost,您可以使用 Omnibus 升级极狐GitLab,然后运行 gitlab-ctl reconfigure 将极狐GitLab Mattermost 升级到最新版本。

如果不是这种情况,有两种选择:

  1. 通过更改 config.json 更新 gitlab.rb。这可能需要添加一些参数,因为并非 config.json 中的所有设置都在 gitlab.rb 中可用。完成后,Omnibus GitLab 应该能够将极狐GitLab Mattermost 从一个版本升级到下一个版本。
  2. 将 Mattermost 迁移到 Omnibus GitLab 控制的目录之外,以便它可以独立管理和升级。按照 Mattermost 迁移指南 将您的 Mattermost 配置设置和数据移动到另一个独立于 Omnibus GitLab 的目录或服务器。

有关旧版本的升级通知和特殊注意事项的完整列表,请参阅 Mattermost 文档

极狐GitLab Mattermost 版本和发行版之间的映射关系

以下是极狐GitLab 15.0 以以后版本中的 Mattermost 版本变更表:

极狐GitLab 版本 Mattermost 版本 说明
17.6 10.1  
17.5 10.0  
17.4 9.11  
17.3 9.10  
17.2 9.9  
17.1 9.8  
17.0 9.7  
16.11 9.6  
16.10 9.5  
16.9 9.4  
16.7 9.3  
16.6 9.1  
16.5 9.0  
16.4 8.1  
16.3 8.0  
16.0 7.10  
15.11 7.9  
15.10 7.8  
15.9 7.7  
15.7 7.5  
15.6 7.4  
15.5 7.3  
15.4 7.2  
15.3 7.1  
15.2 7.0  
15.1 6.7  
15.0 6.6  
  • 14.5 版本维持在 Mattermost 5.39
  • 14.6 版本更新到 Mattermost 6.1 而不是 6.0

NOTE: Mattermost 升级说明提到了在使用 PostgreSQL 与 MySQL 数据库时的不同影响。随 Linux 包附带的极狐GitLab Mattermost 使用的是 PostgreSQL 数据库。

Linux 软件包和 Mattermost Team Edition 进行捆绑,这是一个免费且开源的版本,不包含任何商业功能。要升级 Mattermost Enterprise Edition ,请查阅 Mattermost 升级文档

OAuth2.0 序列图

下图是极狐GitLab 如何作为 Mattermost 的 OAuth2 provider 工作的序列图。您可以使用它来解决集成的错误:

sequenceDiagram User->>Mattermost: GET https://mm.domain.com Note over Mattermost, GitLab: Obtain access code Mattermost->>GitLab: GET https://gitlab.domain.com/oauth/authorize Note over User, GitLab: GitLab user signs in (if necessary) Note over GitLab: GitLab verifies client_id matches an OAuth application GitLab->>User: GitLab asks user to authorize Mattermost OAuth app User->>GitLab: User selects 'Allow' Note over GitLab: GitLab verifies redirect_uri matches list of valid URLs GitLab->>User: 302 redirect: https://mm.domain.com/signup/gitlab/complete User->>Mattermost: GET https://mm.domain.com/signup/gitlab/complete Note over Mattermost, GitLab: Exchange access code for access token Mattermost->>GitLab: POST http://gitlab.domain.com/oauth/token GitLab->>GitLab: Doorkeeper::TokensController#35;create GitLab->>Mattermost: Access token Note over Mattermost, GitLab: Mattermost looks up GitLab user Mattermost->>GitLab: GET https://gitlab.domain.com/api/v4/user GitLab->>Mattermost: User details Mattermost->>User: Mattermost/GitLab user ready

社区支持资源

有关您的极狐GitLab Mattermost 部署的帮助和支持,请参阅: