如何自定义GitLab在Linux的主题

在 Linux 上自定义 GitLab 主题的可选方案

• 面向不同场景提供三种做法：用户级外观设置、管理员品牌与自定义 CSS/JS、源码级主题编译。选择前请先确认你的目标与权限：仅改自己界面、全站统一风格，还是深度品牌化。

用户级外观设置

• 适用对象：普通用户，无需管理员权限。
• 操作路径：登录后点击右上角头像 → Settings → Preferences → Appearance。
• 可选项：
  • Navigation theme：切换导航栏主题，常见有 10 种风格（如 dark 等）。
  • Customize theme：代码高亮配色，提供 5 种风格可选。
• 生效方式：保存后刷新页面即可生效，仅对当前用户有效。

管理员全站品牌与自定义 CSS/JS

• 适用对象：管理员，影响全站所有用户。
• 操作步骤：
  1. 编辑配置文件
     • 打开：/etc/gitlab/gitlab.rb
  2. 可选品牌项（示例）
     • gitlab_rails[‘logo_url’] = ‘https://example.com/logo.png’
     • gitlab_rails[‘favicon_url’] = ‘https://example.com/favicon.ico’
     • gitlab_rails[‘locale’] = ‘zh_CN’
  3. 注入自定义 CSS/JS
     • 新建文件：/etc/gitlab/custom.css、/etc/gitlab/custom.js
     • 在 gitlab.rb 中启用：
       • gitlab_rails[‘custom_css’] = ‘/etc/gitlab/custom.css’
       • gitlab_rails[‘custom_js’] = ‘/etc/gitlab/custom.js’
  4. 使配置生效
     • 执行：sudo gitlab-ctl reconfigure 与 sudo gitlab-ctl restart
• 说明：CSS 可覆盖导航栏、按钮、页面背景等样式；JS 可用于埋点或交互增强。修改前建议备份相关文件与配置。

源码级主题编译与替换

• 适用对象：需要深度品牌化或全新主题，具备服务器文件修改与编译能力。
• 操作步骤（示例路径，实际以你的安装方式为准）：
  1. 备份原始主题
     • sudo cp -r /opt/gitlab/embedded/service/gitlab-rails/public/themes /opt/gitlab/embedded/service/gitlab-rails/public/themes_backup
  2. 创建自定义主题目录并复制默认主题
     • sudo mkdir -p /opt/gitlab/embedded/service/gitlab-rails/public/themes/custom
     • sudo cp -r /opt/gitlab/embedded/service/gitlab-rails/public/themes/grey /opt/gitlab/embedded/service/gitlab-rails/public/themes/custom/grey
  3. 修改样式变量
     • 编辑：/opt/gitlab/embedded/service/gitlab-rails/public/themes/custom/grey/scss/_variables.scss
     • 示例：将主色改为蓝色
       • $brand-primary: #007bff;
  4. 重新编译前端资源
     • cd /opt/gitlab/embedded/service/gitlab-rails
     • sudo bundle exec rake gitlab:assets:reconfigure RAILS_ENV=production
  5. 重启服务
     • sudo gitlab-ctl restart
  6. 验证：访问实例检查主题是否更新
• 风险提示：直接修改嵌入目录在升级时可能被覆盖，务必做好备份与版本记录。

注意事项与最佳实践

• 变更前务必备份：配置文件、主题目录与数据库关键表（如 appearance 相关设置）。
• 路径差异：Omnibus 包常见路径为 /opt/gitlab/embedded/；源码安装路径不同，操作前确认你的实际路径。
• 升级影响：源码级改动可能在升级时被覆盖，建议将自定义文件外置并通过 gitlab.rb 的 custom_css/custom_js 注入，便于迁移与回滚。
• 安全与合规：自定义 JS 可能引入 XSS 或性能问题，上线前在测试环境充分验证并限制来源。
• 渐进式实施：优先使用用户级外观或管理员级 CSS 覆盖，需要品牌重塑再考虑源码编译方案。