第9章 GitLab 与 RustFS 集成:OIDC 单点登录与 S3 对象存储
← 全部文章 GitLab 与 RustFS 集成:OIDC 单点登录与 S3 对象存储 2026年8月4日 | 7分钟阅读 | 集成
GitLab 和 RustFS 可以构建一个完全自托管的平台,涵盖源码控制、CI/CD、身份认证和可扩展的对象存储。这种集成赋予团队两项实用能力:员工可以使用 GitLab 账号登录 RustFS 控制台;GitLab 可以将构建产物和其他大型对象存储在 RustFS 中,而非本地磁盘。
本指南将详细介绍这两项配置:
* 使用 GitLab 作为 RustFS 单点登录的 OpenID Connect (OIDC) 身份提供商。 * 使用 RustFS 作为 GitLab CI/CD 构建产物的 S3 兼容对象存储后端。
同样的对象存储模式还可支持 Git LFS 对象、用户上传、软件包、Terraform 状态、Pages、安全文件、外部合并请求差异以及依赖代理。
示例中使用的域名为 gitlab.example.com 和 rustfs.example.com。请将其替换为您的实际域名。在隔离的测试环境中可以使用 HTTP,但生产部署必须使用 HTTPS。
为什么要集成 GitLab 与 RustFS?
GitLab 是一个可在私有环境中部署的综合型 DevSecOps 平台。RustFS 是一个开源的高性能、S3 兼容对象存储系统,也可以完全运行在您自己的基础设施上。
将这两个平台连接起来带来以下好处:
* 集中化身份认证:通过 GitLab OIDC,用户可以使用现有的公司账号访问 RustFS。 * 可扩展的 CI/CD 存储:构建产物可以从 GitLab 服务器的本地磁盘迁移到专用的对象存储中。 * S3 兼容性:GitLab 可以通过标准的 S3 对象存储配置连接到 RustFS。 * 数据控制权:源码、凭据、元数据和构建输出都保留在您可以管理的基础设施内部。 * 独立扩展:GitLab 计算资源和 RustFS 存储容量可以分别独立扩展。
第一部分:为 RustFS 配置 GitLab OIDC 单点登录
启用 OIDC 后,GitLab 负责用户认证,而 RustFS 控制这些用户被允许执行的操作。登录流程使用 GitLab 的应用 ID 和密钥在服务间建立信任。
先决条件
在开始之前,请确保您具备:
* 正在运行的 GitLab 实例及其管理区域(Admin Area)的访问权限。 * 正在运行的 RustFS 实例及其服务环境编辑权限。 * 两个服务的 DNS 记录。 * 生产端点的 TLS 证书。 * 适用于 GitLab 用户的 RustFS IAM 策略。
安装 RustFS
RustFS 支持二进制、Docker 和 Kubernetes 部署方式。在 Ubuntu 22.04 上,您可以使用安装脚本进行快速测试部署:
```bash curl -O https://rustfs.com/install_rustfs.sh bash install_rustfs.sh ```
安装完成后,编辑 `/etc/default/rustfs`,替换 `RUSTFS_ACCESS_KEY` 和 `RUSTFS_SECRET_KEY` 的默认值。请使用强且唯一的凭据,不要保留默认的 `rustfsadmin` 值。
更新配置后重启 RustFS:
```bash sudo systemctl restart rustfs ```
打开 RustFS 控制台: https://rustfs.example.com
默认提供商的 OIDC 回调 URL 为: https://rustfs.example.com/rustfs/admin/v3/oidc/callback/default
请保留此 URL。在 GitLab 中创建 OAuth 应用时,需要精确匹配该 URL。
创建 GitLab OAuth 应用
您可以使用 GitLab Community Edition、Enterprise Edition 或其他兼容的自托管发行版。如果尚未安装 GitLab,请参阅官方的 GitLab 安装文档。
创建应用的步骤如下:
1. 以管理员身份登录 GitLab。 2. 打开管理区域(Admin Area)。 3. 选择 Applications,然后点击 New application 或 Add new application。 4. 输入描述性名称,例如 `RustFS OIDC`。 5. 将 Redirect URI 设置为: `https://rustfs.example.com/rustfs/admin/v3/oidc/callback/default` 6. 启用 `openid`、`profile` 和 `email` 作用域(scopes)。 7. 保存应用。 8. 将生成的 Application ID 和 Secret 复制到安全位置。
应用密钥属于敏感信息,请将其存储在密钥管理器或其他受保护的配置系统中,切勿放入源代码控制库。
在 RustFS 中配置 GitLab OIDC
编辑 `/etc/default/rustfs` 并添加以下环境变量:
```bash RUSTFS_BROWSER_REDIRECT_URL="https://rustfs.example.com"
RUSTFS_IDENTITY_OPENID_ENABLE=on
RUSTFS_IDENTITY_OPENID_CONFIG_URL="https://gitlab.example.com"
RUSTFS_IDENTITY_OPENID_CLIENT_ID="
将 `
示例中将 `consoleAdmin` 策略分配给通过此提供商认证的用户。在生产环境中,应遵循最小权限原则,替换为仅授予所需权限的策略。
重启服务:
```bash sudo systemctl restart rustfs ```
验证 OIDC 登录流程
打开 RustFS 控制台。登录页面现在应显示“通过 GitLab 登录”按钮。
选择该按钮并验证以下行为:
* 浏览器重定向至 GitLab。 * GitLab 对用户进行认证。 * GitLab 将浏览器重定向至 RustFS 的回调 URL。 * RustFS 控制台打开,并应用 `RUSTFS_IDENTITY_OPENID_ROLE_POLICY` 中配置的权限策略。
如果 GitLab 报告重定向 URI 不匹配,请逐字符比较 GitLab 应用中的 URI 和 `RUSTFS_IDENTITY_OPENID_REDIRECT_URI`。协议、主机名、端口、路径以及末尾斜杠的处理必须完全一致。
第二部分:将 RustFS 用作 GitLab 对象存储
GitLab 可以将多种数据类型存储在 S3 兼容服务中,包括:
* CI/CD 构建产物 * Git LFS 对象 * 用户上传 * 软件包注册表数据 * Terraform 状态 * GitLab Pages 内容 * CI/CD 安全文件 * 外部合并请求差异 * 依赖代理对象
由于 RustFS 实现了 S3 API,GitLab 可以使用 AWS 提供商,通过自定义端点和路径样式请求(path-style requests)连接它。
创建 RustFS 存储桶
计划迁移到对象存储的每种 GitLab 数据类型都应创建专用的存储桶。本示例创建了一个名为 `artifacts` 的存储桶。
您可以在 RustFS 控制台或使用兼容的客户端创建存储桶。详细步骤请参阅 RustFS 存储桶创建文档。
生产环境建议:
* 为 GitLab 使用专用的 RustFS 访问密钥。 * 仅授予该身份访问所需存储桶的权限。 * 为 RustFS S3 端点启用 TLS。 * 根据 CI/CD 需求应用生命周期和保留规则。 * 监控容量、请求错误和对象增长情况。
配置 GitLab CI/CD 产物存储
在 Omnibus GitLab 安装中,编辑 `/etc/gitlab/gitlab.rb` 并添加以下配置:
```ruby gitlab_rails['artifacts_enabled'] = true gitlab_rails['artifacts_object_store_enabled'] = true gitlab_rails['artifacts_object_store_proxy_download'] = false gitlab_rails['artifacts_object_store_remote_directory'] = 'artifacts' gitlab_rails['artifacts_object_store_connection'] = { 'provider' => 'AWS', 'region' => 'us-east-1', 'aws_access_key_id' => 'RUSTFS_ACCESS_KEY', 'aws_secret_access_key' => 'RUSTFS_SECRET_KEY', 'endpoint' => 'https://rustfs.example.com', 'path_style' => true, 'aws_signature_version' => 4 } ```
将端点和凭据替换为您 RustFS 部署中的实际值。如果 S3 API 使用专用端口,请在端点中包含它,例如 `https://rustfs.example.com:9000`。
应用 GitLab 配置:
```bash sudo gitlab-ctl reconfigure ```
测试从 GitLab 流水线上传产物
在测试项目中创建或更新 `.gitlab-ci.yml`:
```yaml stages: - build
build: stage: build script: - mkdir -p output - echo "RustFS object storage test from GitLab" > output/rustfs.txt - ls -ltr output tags: - rustfs artifacts: paths: - output/*.txt expire_in: 1 week ```
运行流水线并等待作业完成。然后在 RustFS 控制台中打开 `artifacts` 存储桶。
如果对象出现在存储桶中,说明 GitLab 正在成功将 CI/CD 产物存储在 RustFS 中,而非 GitLab 服务器的本地磁盘。
配置其他 GitLab 数据类型
GitLab 使用类似的对象存储设置来处理 LFS、上传、软件包、Terraform 状态、Pages、安全文件、外部差异和依赖代理。请为每种数据类型使用独立的存储桶名称,并应用范围较小的 RustFS 策略。
在迁移生产数据之前,请查阅当前 GitLab 对象存储文档,了解特定于您 GitLab 版本的设置。
故障排除:GitLab 与 RustFS 集成
OIDC 登录按钮未显示
请确认 `RUSTFS_IDENTITY_OPENID_ENABLE` 已设置为 `on`,GitLab 配置 URL 可以从 RustFS 主机访问,并且在更改环境文件后已重启 RustFS。
GitLab 报告重定向 URI 不匹配
在 GitLab 中注册的重定向 URI 必须与 `RUSTFS_IDENTITY_OPENID_REDIRECT_URI` 完全匹配。请特别注意 HTTP 与 HTTPS 的区别、端口号以及末尾斜杠。
GitLab 无法上传产物
检查 RustFS 端点、访问密钥、秘密密钥、存储桶名称和网络连接性。对于本指南中展示的配置,请保持启用 `path_style`,并确认 GitLab 身份拥有在 `artifacts` 存储桶中读写对象的权限。
产物仍保留在本地磁盘
运行 `sudo gitlab-ctl reconfigure`,检查 GitLab 日志中是否有对象存储错误,并验证流水线是否生成了产物。启用对象存储后,现有的本地产物并不一定会自动迁移。
常见问题
RustFS 与 GitLab 对象存储兼容吗?
是的。RustFS 提供 S3 兼容的 API,GitLab 通过其 AWS 提供商配置和自定义端点支持 S3 兼容的对象存储。
GitLab 可以认证 RustFS 用户吗?
可以。GitLab 可以作为 OIDC 身份提供商。用户通过 GitLab 登录,而 RustFS 将已认证的身份映射到本地 IAM 策略。
RustFS 可以存储 CI/CD 产物以外的内容吗?
可以。GitLab 可以使用对象存储来存储产物、LFS 对象、上传、软件包、Terraform 状态、Pages、安全文件、外部差异和依赖代理数据。
GitLab 和 RustFS 应该使用 HTTPS 吗?
是的。生产部署应在 GitLab OIDC 端点、RustFS 控制台和 S3 API 中均使用 HTTPS。TLS 保护传输过程中的凭据、令牌和应用数据。
结语
将 GitLab 与 RustFS 集成创建了一个自托管工作流,具备集中式认证和可扩展的 S3 兼容存储。OIDC 减少了对单独 RustFS 控制台凭据的需求,而对象存储则防止 CI/CD 产物和其他大文件占用 GitLab 本地磁盘空间。
建议从一个测试存储桶和受限的 IAM 策略开始,验证完整的登录和上传流程,随着存储需求的增长,再将配置扩展到更多的 GitLab 数据类型。