极狐GitLab Mattermost

你可以在极狐GitLab服务器上运行一个极狐GitLab Mattermost 服务。Mattermost 不是极狐GitLab 的单一应用程序的一部分。Mattermost 和极狐GitLab 之间有很好的集成，我们的 Linux 软件包允许你安装它。然而，Mattermost 是一个来自不同公司的独立应用程序。 极狐GitLab 支持无法帮助你解决超出极狐GitLab 集成的 Mattermost 特定问题。

前提条件#

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

入门#

极狐GitLab Mattermost 期望在其自己的虚拟主机上运行。在 DNS 设置中，你需要两个指向同一台机器的条目。例如，gitlab.example.com 和 mattermost.example.com。

极狐GitLab Mattermost 默认情况下是禁用的。要启用它：

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

   ruby
   mattermost_external_url 'https://mattermost.example.com'

2. 重新配置极狐GitLab：

   shell
   sudo gitlab-ctl reconfigure

3. 确认极狐GitLab Mattermost 可以在 https://mattermost.example.com 访问，并获得连接到极狐GitLab 的授权。授权 Mattermost 使用极狐GitLab 允许用户使用极狐GitLab 作为 SSO 提供商。

Linux 软件包尝试自动授权极狐GitLab Mattermost 与极狐GitLab 的集成，如果应用程序在同一台服务器上运行。

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

配置 Mattermost#

可以使用 Mattermost 系统控制台配置 Mattermost。

虽然推荐使用系统控制台，但你也可以使用以下选项之一来配置 Mattermost：

1. 直接通过 /var/opt/gitlab/mattermost/config.json 编辑 Mattermost 配置。
2. 通过更改 gitlab.rb 中的 mattermost['env'] 设置来指定运行 Mattermost 所用的环境变量。以这种方式配置的任何设置都将从系统控制台禁用，无法在不重启 Mattermost 的情况下更改。

运行极狐GitLab Mattermost 并使用 HTTPS#

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

shell
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 中指定以下配置：

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

如果你没有将证书和密钥命名为 mattermost.gitlab.example.crt 和 mattermost.gitlab.example.key，那么你还需要添加完整路径，如下所示。

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

其中 mattermost-nginx.crt 是 SSL 证书，mattermost-nginx.key 是 SSL 密钥。

设置配置后，运行 sudo gitlab-ctl reconfigure 以应用更改。

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

默认情况下，Mattermost 使用 Linux 软件包捆绑的 PostgreSQL 服务。如果你想使用外部 PostgreSQL 服务运行 Mattermost，则需要其特定的配置。极狐GitLab 使用的现有外部 PostgreSQL 连接配置不会自动继承给 Mattermost。

1. 编辑 /etc/gitlab/gitlab.rb 并指定以下配置：

   ruby
   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'] 中定义的 user 值和 password 值匹配的 PostgreSQL 用户。

3. 创建一个与使用的 dbname 值匹配的 PostgreSQL 数据库。

4. 确保 user 对创建的数据库具有权限。

5. 重新配置极狐GitLab 并重启 Mattermost 以应用更改：

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

在其自己的服务器上运行极狐GitLab Mattermost#

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

ruby
1mattermost_external_url 'http://mattermost.example.com'
2
3# 关闭 Mattermost 服务器上的极狐GitLab 服务
4gitlab_rails['enable'] = false
5redis['enable'] = false
6postgres_exporter['enable'] = false
7grafana['enable'] = false

然后按照授权极狐GitLab Mattermost 部分中的适当步骤进行操作。最后，为了启用与极狐GitLab 的集成，请在极狐GitLab 服务器上添加以下内容：

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

默认情况下，极狐GitLab Mattermost 要求所有用户使用极狐GitLab 注册，并禁用通过电子邮件注册的选项。

手动（重新）授权极狐GitLab Mattermost 与极狐GitLab#

重新授权极狐GitLab Mattermost#

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

授权极狐GitLab Mattermost#

转到极狐GitLab 的 设置 > 应用 区域。创建一个新应用程序，并为 重定向 URI 使用以下内容（如果你使用 HTTPS，请将 http 替换为 https）：

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

确保选择 可信 和 机密 设置。在 范围 下，选择 read_user。然后，选择 保存应用程序。

创建应用程序后，会提供一个 Application ID 和 Secret。另一个需要的信息是极狐GitLab 实例的 URL。返回运行极狐GitLab Mattermost 的服务器并使用上面收到的值编辑 /etc/gitlab/gitlab.rb 配置文件，如下所示：

ruby
1mattermost['gitlab_enable'] = true
2mattermost['gitlab_id'] = "12345656"
3mattermost['gitlab_secret'] = "123456789"
4mattermost['gitlab_scope'] = "read_user"
5mattermost['gitlab_auth_endpoint'] = "http://gitlab.example.com/oauth/authorize"
6mattermost['gitlab_token_endpoint'] = "http://gitlab.example.com/oauth/token"
7mattermost['gitlab_user_api_endpoint'] = "http://gitlab.example.com/api/v4/user"

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

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

Linux 软件包创建了一个用户和群组 mattermost。你可以在 /etc/gitlab/gitlab.rb 中指定这些用户的数字标识符，如下所示：

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

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

设置自定义环境变量#

如果需要，你可以通过 /etc/gitlab/gitlab.rb 设置 Mattermost 使用的自定义环境变量。如果 Mattermost 服务器在公司互联网代理后面运行，这可能很有用。在 /etc/gitlab/gitlab.rb 中提供一个具有哈希值的 mattermost['env']。例如：

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

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

连接到捆绑的 PostgreSQL 数据库#

如果需要连接到捆绑的 PostgreSQL 数据库，并且使用默认的 Linux 软件包数据库配置，你可以以 PostgreSQL 超级用户身份连接：

shell
sudo gitlab-psql -d mattermost_production

备份极狐GitLab Mattermost#

极狐GitLab Mattermost 不包括在常规Linux 软件包备份 Rake 任务中。

一般的 Mattermost 备份和灾难恢复文档可以作为需要备份内容的指南。

备份捆绑的 PostgreSQL 数据库#

如果你需要备份捆绑的 PostgreSQL 数据库，并且使用默认的 Linux 软件包数据库配置，可以使用以下命令进行备份：

shell
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 文件也需要备份：

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

恢复极狐GitLab Mattermost#

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

shell
1# 停止 Mattermost，以便我们没有任何打开的数据库连接
2sudo gitlab-ctl stop mattermost
3
4# 删除 Mattermost 数据库
5sudo -u gitlab-psql /opt/gitlab/embedded/bin/dropdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production
6
7# 创建 Mattermost 数据库
8sudo -u gitlab-psql /opt/gitlab/embedded/bin/createdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production
9
10# 执行数据库恢复
11# 替换 /tmp/mattermost_dbdump_2021-08-05.sql.gz 为你的备份
12sudo -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"
13
14# 恢复数据目录和 config.json
15# 替换 /tmp/mattermost_data_2021-08-09.gz 为你的备份
16sudo tar -xzvf /tmp/mattermost_data_2021-08-09.gz -C /var/opt/gitlab/mattermost
17
18# 如果需要，修复权限
19sudo chown -R mattermost:mattermost /var/opt/gitlab/mattermost/data
20sudo chown mattermost:mattermost /var/opt/gitlab/mattermost/config.json
21
22# 启动 Mattermost
23sudo gitlab-ctl start mattermost

Mattermost 命令行工具 (CLI)#

mmctl 是一个用于 Mattermost 服务器的 CLI 工具，它在本地安装并使用 Mattermost API，但也可以远程使用。你必须为本地连接配置 Mattermost 或使用本地登录凭据（而不是通过极狐GitLab SSO）进行管理员身份验证。可执行文件位于 /opt/gitlab/embedded/bin/mmctl。

通过本地连接使用 mmctl#

对于本地连接，mmctl 二进制文件和 Mattermost 必须在同一服务器上运行。要启用本地套接字：

1. 编辑 /var/opt/gitlab/mattermost/config.json，并添加以下行：

   json
   1{
   2    "ServiceSettings": {
   3       ...
   4        "EnableLocalMode": true,
   5        "LocalModeSocketLocation": "/var/tmp/mattermost_local.socket",
   6        ...
   7    }
   8}

2. 重启 Mattermost：

   shell
   sudo gitlab-ctl restart mattermost

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

例如，显示用户列表：

shell
1$ sudo /opt/gitlab/embedded/bin/mmctl --local user list
2
313dzo5bmg7fu8rdox347hbfxde: appsbot (appsbot@localhost)
4tbnkwjdug3dejcoddboo4yuomr: boards (boards@localhost)
5wd3g5zpepjgbfjgpdjaas7yj6a: feedbackbot (feedbackbot@localhost)
68d3zzgpurp85zgf1q88pef73eo: playbooks (playbooks@localhost)
7There are 4 users on local instance

通过远程连接使用 mmctl#

对于远程连接或无法使用套接字的本地连接，创建一个非 SSO 用户并赋予该用户管理员权限。然后可以使用这些凭据进行 mmctl 身份验证：

shell
1$ /opt/gitlab/embedded/bin/mmctl auth login http://mattermost.example.com
2
3Connection name: test
4Username: local-user
5Password:
6 credentials for "test": "local-user@http://mattermost.example.com" stored

配置极狐GitLab 和 Mattermost 的集成#

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

插件和斜杠命令可以一起或单独使用。

电子邮件通知#

为极狐GitLab Mattermost 设置 SMTP#

这些设置由系统管理员通过 Mattermost 系统控制台进行配置。在 系统控制台 > 环境 > SMTP 选项卡上，你可以输入 SMTP 提供商提供的 SMTP 凭据，或者 127.0.0.1 和端口 25 来使用 sendmail。

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

电子邮件批处理#

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

可以通过导航到 Mattermost 系统控制台 的 环境 > SMTP 选项卡，并将 启用电子邮件批处理 设置为 真 来启用电子邮件批处理。

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

升级极狐GitLab Mattermost#

极狐GitLab Mattermost 可以通过常规的 Linux 软件包更新过程进行升级。在升级极狐GitLab 的早期版本时，只有在没有在极狐GitLab 之外更改 Mattermost 配置设置的情况下才能使用更新过程。也就是说，Mattermost config.json 文件没有被更改 - 无论是直接修改的还是通过 Mattermost 系统控制台，该控制台将更改保存到 config.json。

如果你仅使用 gitlab.rb 配置 Mattermost，你可以使用 Linux 软件包升级极狐GitLab，然后运行 gitlab-ctl reconfigure 以将极狐GitLab Mattermost 升级到最新版本。

如果不是这种情况，有两种选择：

1. 使用对 config.json 所做的更改更新 gitlab.rb。这可能需要添加一些参数，因为并非 config.json 中的所有设置都在 gitlab.rb 中可用。一旦完成，Linux 软件包应该能够从一个版本升级到下一个版本的极狐GitLab Mattermost。
2. 将 Mattermost 从 Linux 软件包控制的目录中迁移出去，以便可以独立进行管理和升级。

随 Linux 软件包提供的极狐GitLab Mattermost 版本和版本#

以下是极狐GitLab 15.0 及更高版本的 Mattermost 版本更改列表：

Linux 软件包捆绑了 Mattermost 团队版，它是一个免费和开源的版本，不包括其商业功能。

OAuth 2.0 序列图#

下图是极狐GitLab 作为 Mattermost 的 OAuth 2.0 提供者的序列图。你可以使用它来排查集成工作中的错误：

Rendering chart...