Help us learn about your current experience with the documentation. Take the survey.

GitLab Mattermost

  • Offering: GitLab Self-Managed

您可以在 GitLab 服务器上运行 GitLab Mattermost 服务。Mattermost 并非 GitLab 单体应用的一部分。Mattermost 和 GitLab 之间有良好的集成，我们的 Linux 包允许您安装它。但是，Mattermost 是来自另一家公司的独立应用程序。GitLab 支持无法帮助您解决 Mattermost 特定的问题，除非涉及与 GitLab 的集成。如果您需要关于 Mattermost 本身的帮助，请参阅 社区支持资源。

前置条件

每个 GitLab Mattermost 版本都在 Linux 的 AMD 64 芯片集上编译并手动测试。不支持 ARM 芯片集和操作系统，如树莓派。

入门指南

GitLab Mattermost 期望在独立的虚拟主机上运行。在您的 DNS 设置中，需要两个指向同一台机器的记录。例如，gitlab.example.com 和 mattermost.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. 确认可以在 https://mattermost.example.com 访问 GitLab Mattermost 并授权其连接到 GitLab。授权 Mattermost 与 GitLab 集成允许用户使用 GitLab 作为 SSO 提供商。

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

自动授权需要访问 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.crt 和 mattermost.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.crt 是 SSL 证书，mattermost-nginx.key 是 SSL 密钥。

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

使用外部 PostgreSQL 服务运行 GitLab Mattermost

默认情况下，Mattermost 使用 Linux 包捆绑的 PostgreSQL 服务。如果您想将 Mattermost 与外部 PostgreSQL 服务一起使用，它需要特定的配置。现有的 GitLab 使用的外部 PostgreSQL 连接配置 不会自动继承给 Mattermost。

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

    mattermost['sql_driver_name'] = 'postgres'
mattermost['sql_data_source'] = "user=gitlab_mattermost host=<postgresql-service-hostname> port=5432 sslmode=required dbname=<mattermost_production> password=<user-password>"

  2. 创建与 mattermost['sql_data_source'] 中定义的 user 值和 password 值匹配的 PostgreSQL 用户。

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

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

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

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

在独立服务器上运行 GitLab Mattermost

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

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

# 关闭 Mattermost 服务器上的 GitLab 服务
alertmanager['enable'] = false
gitlab_exporter['enable'] = false
gitlab_kas['enable'] = false
gitlab_rails['enable'] = false
grafana['enable'] = false
letsencrypt['enable'] = false
node_exporter['enable'] = false
postgres_exporter['enable'] = false
prometheus['enable'] = false
redis_exporter['enable'] = false
redis['enable'] = false

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

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

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

手动（重新）授权 GitLab Mattermost 与 GitLab 集成

重新授权 GitLab Mattermost

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

授权 GitLab Mattermost

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

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

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

应用程序创建后，您将获得一个 应用程序 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 应该已正确配置。

指定数字用户和组标识符

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

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

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

设置自定义环境变量

如有必要，您可以通过 /etc/gitlab/gitlab.rb 设置自定义环境变量供 Mattermost 使用。如果 Mattermost 服务器在企业互联网代理后运行，这可能会很有用。在 /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 数据库并且使用默认的 Linux 包数据库配置，您可以以 PostgreSQL 超级用户身份连接：

sudo gitlab-psql -d mattermost_production

备份 GitLab Mattermost

GitLab Mattermost 不包含在常规的 Linux 包备份 Rake 任务中。

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

备份捆绑的 PostgreSQL 数据库

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

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 的备份，可以运行以下命令恢复它：

# 停止 Mattermost 以避免任何打开的数据库连接
sudo gitlab-ctl stop mattermost

# 删除 Mattermost 数据库
sudo -u gitlab-psql /opt/gitlab/embedded/bin/dropdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production

# 创建 Mattermost 数据库
sudo -u gitlab-psql /opt/gitlab/embedded/bin/createdb -U gitlab-psql -h /var/opt/gitlab/postgresql -p 5432 mattermost_production

# 执行数据库恢复
# 将 /tmp/mattermost_dbdump_2021-08-05.sql.gz 替换为您的备份
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"

# 恢复 data 目录和 config.json
# 将 /tmp/mattermost_data_2021-08-09.gz 替换为您的备份
sudo tar -xzvf /tmp/mattermost_data_2021-08-09.gz -C /var/opt/gitlab/mattermost

# 如需要修复权限
sudo chown -R mattermost:mattermost /var/opt/gitlab/mattermost/data
sudo chown mattermost:mattermost /var/opt/gitlab/mattermost/config.json

# 启动 Mattermost
sudo 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，并添加以下行：

    {
    "ServiceSettings": {
       ...
        "EnableLocalMode": true,
        "LocalModeSocketLocation": "/var/tmp/mattermost_local.socket",
        ...
    }
}

  2. 重启 Mattermost：

    sudo gitlab-ctl restart mattermost

然后您可以使用 sudo /opt/gitlab/embedded/bin/mmctl --local 在您的 Mattermost 实例上运行 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)
本地实例上有 4 个用户

通过远程连接使用 mmctl

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

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

连接名称: test
用户名: local-user
密码:
 "test" 的凭据 "local-user@http://mattermost.example.com" 已存储

配置 GitLab 和 Mattermost 集成

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

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

电子邮件通知

为 GitLab Mattermost 设置 SMTP

这些设置由系统管理员通过 Mattermost 系统控制台进行配置。在系统控制台的 环境 > SMTP 选项卡中，您可以输入 SMTP 提供商提供的 SMTP 凭据，或使用 127.0.0.1 和端口 25 来使用 sendmail。有关所需具体设置的更多信息，请参阅 Mattermost 文档。

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

电子邮件批处理

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

可以在 Mattermost 系统控制台 中启用电子邮件批处理，方法是导航到 环境 > SMTP 选项卡，并将 启用电子邮件批处理 设置设置为 True。

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

升级 GitLab Mattermost

升级 Mattermost 版本时，必须检查 Mattermost 的 重要升级说明，以解决需要执行的任何更改或迁移。

GitLab Mattermost 可以通过常规的 Linux 包升级过程进行升级。当升级 GitLab 的早期版本时，只有在 Mattermost 配置设置未在 GitLab 外部更改的情况下才能使用此升级过程。也就是说，没有对 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 包控制的目录之外，以便可以独立管理和升级。请遵循 Mattermost 迁移指南 将您的 Mattermost 配置设置和数据移动到另一个目录或独立于 Linux 包的服务器。

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

Linux 包附带的 GitLab Mattermost 版本和版本

下表概述了 GitLab 15.0 及更高版本的 Mattermost 版本更改：

GitLab 版本 Mattermost 版本 备注
18.1 10.8
18.0 10.7
17.11 10.6
17.9 10.4
17.7 10.2
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

Mattermost 升级说明提到了与 PostgreSQL 和 MySQL 数据库一起使用时的不同影响。Linux 包附带的 GitLab Mattermost 使用 PostgreSQL 数据库。

Linux 包捆绑了 Mattermost 团队版，这是一个免费开源版本，不包含其商业功能。要升级到 Mattermost 企业版，请参阅 Mattermost 关于升级的文档。

OAuth 2.0 序列图

下图是 GitLab 作为 Mattermost 的 OAuth 2.0 提供商的序列图。您可以使用它来排查集成工作时的错误：

%%{init: { "fontFamily": "GitLab Sans" }}%%
sequenceDiagram
accTitle: GitLab as OAuth 2.0 provider
accDescr: Sequence of actions that happen when a user authenticates to GitLab through Mattermost.

    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 部署的帮助和支持，请参阅：