Skip to content

Commit 2dd213a

Browse files
shumingyang-opencodeshumingyang-opencode
committed
Round 2 deepen: gitlab-tech-zh-tw — project-level examples, perf/quality/security, cross-site comparison, checklists
1 parent 68bcf87 commit 2dd213a

8 files changed

Lines changed: 773 additions & 0 deletions

‎docs/unit-01-gitlab-intro.html‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -200,6 +200,108 @@ <h2>進階挑戰題</h2>
200200
<li><strong>GitLab CE vs EE 功能差距分析：</strong>調查三個 GitLab EE 獨有的功能（如 Audit Events、Merge Train、Code Owners），說明它們在 50 人以上的團隊中如何提升合規性與效率。</li>
201201
</ol>
202202

203+
<!-- ═══════ Round 2 Deepen ═══════ -->
204+
<h2>專案級端到端 Worked Example</h2>
205+
<h3>情境：企業 DevOps 平台建置專案（devops-platform）</h3>
206+
<p>一家 30 人新創決定全面導入 GitLab 自架，把「群組與權限、MR 流程、CI/CD、Pages、稽核」一次到位。這是跨單元的整站整合案例——把單元 1–7 的知識收束成一個可交付的專案。</p>
207+
<div class="demo-block">
208+
<div class="demo-label">專案檔案樹 · TREE</div>
209+
<pre>devops-platform/
210+
├── README.md <span class="hl-c"># 專案總覽、決策紀錄、驗收清單</span>
211+
├── docker-compose.yml <span class="hl-c"># GitLab CE + Runner 一鍵部署（單元 1）</span>
212+
├── .env.example <span class="hl-c"># 環境變數範本（不含任何密碼）</span>
213+
├── config/
214+
│ └── gitlab.rb <span class="hl-c"># 備份、HTTPS、稽核設定</span>
215+
├── scripts/
216+
│ ├── bootstrap.sh <span class="hl-c"># 初始化：建群組/專案/權限（單元 2）</span>
217+
│ ├── backup.sh <span class="hl-c"># 每日 02:00 備份（cron）</span>
218+
│ └── verify.sh <span class="hl-c"># 驗收腳本（單元 1 知識）</span>
219+
├── docs/
220+
│ ├── architecture.md <span class="hl-c"># 架構圖（Nginx→GitLab→Gitaly→Runner）</span>
221+
│ └── runbook.md <span class="hl-c"># 日常維運手冊</span>
222+
└── .gitlab-ci.yml <span class="hl-c"># 平台自身的 CI：每日驗證備份（單元 6）</span></pre>
223+
</div>
224+
<div class="demo-block">
225+
<div class="demo-label">關鍵檔案 · KEY FILES</div>
226+
<pre><span class="hl-c"># docker-compose.yml（一鍵起 GitLab + Runner）</span>
227+
services:
228+
gitlab:
229+
image: gitlab/gitlab-ce:latest
230+
hostname: gitlab.example.com
231+
ports: ["80:80", "443:443", "2222:22"]
232+
volumes:
233+
- ./config:/etc/gitlab
234+
- ./data:/var/opt/gitlab
235+
- ./logs:/var/log/gitlab
236+
runner:
237+
image: gitlab/gitlab-runner:latest
238+
volumes: ["/var/run/docker.sock:/var/run/docker.sock"]
239+
240+
<span class="hl-c"># scripts/verify.sh（驗證健康、版本、備份、稽核）</span>
241+
#!/usr/bin/env bash
242+
curl -sI https://gitlab.example.com | head -1
243+
sudo gitlab-ctl status
244+
sudo gitlab-rake gitlab:backup:status | tail -2
245+
ls /srv/backup/ | tail -1 <span class="hl-c"># 最新備份檔</span></pre>
246+
</div>
247+
<div class="demo-block">
248+
<div class="demo-label">驗證命令與輸出 · VERIFY</div>
249+
<pre>$ docker compose ps
250+
NAME STATUS PORTS
251+
gitlab healthy 0.0.0.0:80->80, 0.0.0.0:2222->22
252+
runner running 0.0.0.0:8093->8093
253+
254+
$ ./scripts/verify.sh
255+
HTTP/1.1 302 Found <span class="hl-c"># 302 = 登入頁正常</span>
256+
run: alertmanager: (pid 1520) 2s; run: gitaly: (pid 1501) 3s
257+
Backup: 2026-08-17 02:00 · tar (18 MB) · done
258+
OK</pre>
259+
</div>
260+
<div class="callout"><strong>專案級收斂：</strong>單元 1 講「GitLab 是什麼」，這個專案把定義變成可交付物——你能列出架構、寫出部署、跑出驗收。這是「讀懂」與「做得出來」的分界線。</div>
261+
262+
<h2>效能 / 品質 / 安全深度</h2>
263+
<h3>效能：自架 GitLab 的關鍵調校</h3>
264+
<table>
265+
<tr><th>面向</th><th>調整</th><th>影響</th></tr>
266+
<tr><td><strong>Puma</strong></td><td>依 CPU 數調 workers（<code>puma['worker_processes']</code>）</td><td>Web 併發吞吐量</td></tr>
267+
<tr><td><strong>Sidekiq</strong></td><td>依佇列分流（mailers、pipelines、archive 各開 process）</td><td>CI 排程與背景任務延遲</td></tr>
268+
<tr><td><strong>Gitaly</strong></td><td>獨立節點＋檔案快取；大型 repo 開 <code>git pack-objects</code> 快取</td><td>clone / push 速度</td></tr>
269+
<tr><td><strong>Runner</strong></td><td>用 tag 分群、Docker executor + 共掛快取 volume</td><td>CI 排隊等待與快取命中率</td></tr>
270+
</table>
271+
<h3>品質：備份、升級與災難復原</h3>
272+
<ul>
273+
<li>Omnibus 內建 <code>gitlab-backup create</code>，備份檔含 DB、repo、uploads；<strong>設定 RPO/RTO</strong>（例如 RPO=24h、RTO=4h）後寫進 runbook。</li>
274+
<li>升級節奏：先讀 <a href="https://docs.gitlab.com/update/upgrade_paths/" rel="noopener">upgrade path</a>，跳太多版會強制中間版；備份後才升級。</li>
275+
<li>品質的證據是「還原演練」，不是「有備份」——每季實際還原到空機器一次。</li>
276+
</ul>
277+
<h3>安全：讓平台自己可信</h3>
278+
<ul>
279+
<li>強制 <strong>2FA</strong>（instance 層級）、LDAP/SSO 對接公司帳號、停用自助註冊。</li>
280+
<li>開啟 <strong>Audit Events</strong>（EE）：誰在何時改了權限、刪了專案、下了批准——合規稽核的必要證據。</li>
281+
<li>安全頭部（HSTS/CSP）、僅 HTTPS、PAT 一律設到期與最小 scope。</li>
282+
</ul>
283+
284+
<h2>站際比較對照表</h2>
285+
<table>
286+
<tr><th>面向</th><th>gitlab</th><th>github</th><th>markdown</th><th>yaml</th><th>json</th></tr>
287+
<tr><td>核心定位</td><td>一體化 DevOps 平台</td><td>社群生態代管平台</td><td>人類可讀的文件格式</td><td>人類可讀的設定格式</td><td>機器可讀的資料格式</td></tr>
288+
<tr><td>開源程度</td><td>CE 完整開源</td><td>平台閉源</td><td>開放標準</td><td>開放標準</td><td>開放標準</td></tr>
289+
<tr><td>託管模式</td><td>雲端＋可自架</td><td>雲端為主</td><td>純文字檔</td><td>純文字檔</td><td>純文字/程式產生</td></tr>
290+
<tr><td>與本單元關係</td><td>主角</td><td>直接對照</td><td>README/Wiki 用 MD 寫</td><td>.gitlab-ci.yml 用 YAML 寫</td><td>GitLab API 回傳 JSON</td></tr>
291+
<tr><td>自動化程度</td><td>高（平台內建）</td><td>高（平台內建）</td><td>低（人工撰寫）</td><td>中（設定驅動）</td><td>高（程式驅動）</td></tr>
292+
</table>
293+
294+
<h2>互動式檢核清單</h2>
295+
<div class="demo-block">
296+
<div class="demo-label">進階驗收清單 · CHECKLIST</div>
297+
<pre>- [ ] docker-compose 一鍵起 GitLab + Runner，資料持久化
298+
- [ ] 已設定每日備份，且還原演練成功過一次
299+
- [ ] 全員強制 2FA、停用自助註冊、PAT 皆設到期
300+
- [ ] 至少一個 pipeline 在 Runner 上跑綠
301+
- [ ] 已寫出 architecture.md 與 runbook.md 並交接
302+
- [ ] 掃描確認無任何 token / 密碼 commit 進 repo</pre>
303+
</div>
304+
203305
</div>
204306
<footer>這是 GitLab 繁體中文教學站 · 由 OpenCode 建置<br>
205307
<span class="footer-license">本站教學內容（繁體中文解說）為本站原創，採 CC-BY-4.0；技術名詞與操作引用自 <a href="https://docs.gitlab.com/" rel="noopener">GitLab Docs</a> 與 <a href="https://git-scm.com/doc" rel="noopener">Git 官方文件</a>。</span></footer>

‎docs/unit-02-first-project.html‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,92 @@ <h2>進階挑戰題</h2>
208208
<li><strong>從 GitHub 遷移到 GitLab：</strong>描述完整遷移步驟（含 Issues、MR、Label），並列出三個遷移後需要檢查的項目（CI 設定、Webhook、Protected Branches）。</li>
209209
</ol>
210210

211+
<!-- ═══════ Round 2 Deepen ═══════ -->
212+
<h2>專案級端到端 Worked Example</h2>
213+
<h3>情境：新產品線群組建置專案（my-company）</h3>
214+
<p>公司成立「平台」與「產品」兩條產品線，需要一次建好群組樹、權限矩陣與 Visibility 策略，讓 20 人團隊各自安全進場。</p>
215+
<div class="demo-block">
216+
<div class="demo-label">群組樹與專案 · GROUP TREE</div>
217+
<pre>my-company/ <span class="hl-c">← Group（Private）</span>
218+
├── platform/ <span class="hl-c">← Subgroup：平台工程</span>
219+
│ ├── api-gateway/ <span class="hl-c">← Project（Private）</span>
220+
│ ├── user-service/ <span class="hl-c">← Project（Private）</span>
221+
│ └── shared-libs/ <span class="hl-c">← Project（Internal）</span>
222+
├── product/ <span class="hl-c">← Subgroup：產品開發</span>
223+
│ ├── web-app/ <span class="hl-c">← Project（Private）</span>
224+
│ └── mobile-app/ <span class="hl-c">← Project（Private）</span>
225+
└── my-company.gitlab.io/ <span class="hl-c">← Project（Public）對外入口（單元 7）</span></pre>
226+
</div>
227+
<div class="demo-block">
228+
<div class="demo-label">關鍵檔案 · KEY FILES</div>
229+
<pre><span class="hl-c"># .gitignore（每個新專案起手式，防密鑰入庫）</span>
230+
.env
231+
*.pem
232+
*.key
233+
node_modules/
234+
dist/
235+
.DS_Store
236+
237+
<span class="hl-c"># .gitlab-ci.yml（每個專案最基礎的 CI，單元 6）</span>
238+
stages: [test]
239+
hello:
240+
stage: test
241+
script: echo "Hello from $CI_PROJECT_PATH"</pre>
242+
</div>
243+
<div class="demo-block">
244+
<div class="demo-label">驗證命令與輸出 · VERIFY</div>
245+
<pre>$ git remote -v
246+
origin git@gitlab.example.com:my-company/platform/api-gateway.git
247+
248+
$ glab api "groups/my-company" 2&gt;/dev/null | head -c 300
249+
{"id":7,"name":"my-company","visibility":"private",...}
250+
251+
$ git push -u origin main <span class="hl-c"># 首次推送後，網頁看到 pipeline 綠燈</span>
252+
To gitlab.example.com:my-company/platform/api-gateway.git
253+
* [new branch] main -&gt; main</pre>
254+
</div>
255+
<div class="callout"><strong>專案級收斂：</strong>單元 2 的「Group / Subgroup / Visibility / 權限」在這裡變成一份群組樹＋一份權限矩陣——管理者照著建，20 人就能同時安全地進場工作。</div>
256+
257+
<h2>效能 / 品質 / 安全深度</h2>
258+
<h3>效能：讓 repo 保持輕量</h3>
259+
<ul>
260+
<li><strong>clone 速度</strong>：大型二進位檔改用 Git LFS；設定檔案大小上限（push rule），防止有人推 500MB 的 log。</li>
261+
<li><strong>歷史瘦身</strong>：定期 <code>git gc</code>，必要時用 <code>git filter-repo</code> 清掉誤入的大檔與敏感檔。</li>
262+
<li><strong>避免單體巨庫</strong>：超過一個大型專案時用 Subgroup 拆成多個 Project，CI 與權限都好管理。</li>
263+
</ul>
264+
<h3>品質：專案標準化</h3>
265+
<ul>
266+
<li>每個新專案從「樣板」建立：README + LICENSE + CHANGELOG + .gitignore + 基礎 .gitlab-ci.yml 一次給齊。</li>
267+
<li>GitLab 專案樣板可直接選（Ruby/Node/Python 等），或自建群組樣板 <code>group/project-templates</code> 統一規範。</li>
268+
</ul>
269+
<h3>安全：權限最小化與可見性稽核</h3>
270+
<ul>
271+
<li><strong>權限矩陣</strong>：Owner 僅 2 人、Maintainer 各 Lead、Developer 開發者；Guest 只給需要看 issue 的外部人員。</li>
272+
<li><strong>Visibility 稽核</strong>：定期列出全部專案與 visibility，確認沒有誤設 Public 的內部專案。</li>
273+
<li><strong>Secret 防線</strong>：.gitignore + push rules 拒 .env/*.pem；密鑰一律走 CI/CD Variables。</li>
274+
</ul>
275+
276+
<h2>站際比較對照表</h2>
277+
<table>
278+
<tr><th>面向</th><th>gitlab</th><th>github</th><th>markdown</th><th>yaml</th><th>json</th></tr>
279+
<tr><td>程式碼容器</td><td>Project（含 CI/Issues/Pages）</td><td>Repository（repo 為主）</td><td>.md 文件</td><td>.yml 設定</td><td>.json 資料</td></tr>
280+
<tr><td>組織單位</td><td>Group / Subgroup（巢狀）</td><td>Organization（單層）</td><td>—</td><td>—</td><td>—</td></tr>
281+
<tr><td>可見性</td><td>Private / Internal / Public</td><td>Private / Public（無 Internal）</td><td>由平台檔案權限決定</td><td>同左</td><td>同左</td></tr>
282+
<tr><td>權限角色</td><td>Owner→Maintainer→Developer→Reporter→Guest</td><td>Owner→Admin→Write→Read</td><td>—</td><td>—</td><td>—</td></tr>
283+
<tr><td>建立方式</td><td>New project + 樣板</td><td>New repository + 樣板</td><td>任何編輯器寫檔</td><td>任何編輯器寫檔</td><td>程式/編輯器產生</td></tr>
284+
</table>
285+
286+
<h2>互動式檢核清單</h2>
287+
<div class="demo-block">
288+
<div class="demo-label">進階驗收清單 · CHECKLIST</div>
289+
<pre>- [ ] 已建立 Group + Subgroup，並畫出權限矩陣
290+
- [ ] 每個專案都有 README / LICENSE / CHANGELOG / .gitignore
291+
- [ ] visibility 全部核對：內部專案 Private、對外專案 Public
292+
- [ ] 用 Guest 帳號實測：讀不到 Private 專案、看得到 Internal 專案
293+
- [ ] repo 內無 .env / 憑證；密鑰全部在 CI Variables
294+
- [ ] 已 push 至少一個專案並看到 pipeline 綠燈</pre>
295+
</div>
296+
211297
</div>
212298
<footer>這是 GitLab 繁體中文教學站 · 由 OpenCode 建置<br>
213299
<span class="footer-license">本站教學內容（繁體中文解說）為本站原創，採 CC-BY-4.0；技術名詞與操作引用自 <a href="https://docs.gitlab.com/" rel="noopener">GitLab Docs</a> 與 <a href="https://git-scm.com/doc" rel="noopener">Git 官方文件</a>。</span></footer>

‎docs/unit-03-branches-mr.html‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -215,6 +215,101 @@ <h2>進階挑戰題</h2>
215215
<li><strong>分支策略選型：</strong>為一個「每兩週發版、同時修 hotfix」的團隊設計分支策略，畫出 Git 圖形並說明 release 與 hotfix 的合併路徑。</li>
216216
</ol>
217217

218+
<!-- ═══════ Round 2 Deepen ═══════ -->
219+
<h2>專案級端到端 Worked Example</h2>
220+
<h3>情境：功能交付專案（feature-delivery）——從 Issue 到上線</h3>
221+
<p>一個團隊要建立「可重複的交付節奏」：用分支策略、MR 範本與發布手冊，把「一顆功能怎麼從 issue 走到上線」變成文件化、可複製的流程。</p>
222+
<div class="demo-block">
223+
<div class="demo-label">專案檔案樹 · TREE</div>
224+
<pre>feature-delivery/
225+
├── README.md <span class="hl-c"># 專案總覽與流程入口</span>
226+
├── .gitlab/
227+
│ ├── merge_request_templates/
228+
│ │ └── feature.md <span class="hl-c"># MR 描述範本（單元 3/4）</span>
229+
│ └── issue_templates/
230+
│ ├── bug.md <span class="hl-c"># Bug 範本</span>
231+
│ └── feature.md <span class="hl-c"># 功能範本（單元 5）</span>
232+
├── docs/
233+
│ ├── branching-strategy.md <span class="hl-c"># 分支策略（含圖）</span>
234+
│ └── release-playbook.md <span class="hl-c"># 發布手冊</span>
235+
└── src/
236+
└── app.py <span class="hl-c"># 範例程式</span></pre>
237+
</div>
238+
<div class="demo-block">
239+
<div class="demo-label">關鍵檔案 · KEY FILES</div>
240+
<pre><span class="hl-c"># .gitlab/merge_request_templates/feature.md</span>
241+
## 動機
242+
為什麼做這個功能？（關聯 issue：Closes #）
243+
244+
## 改動範圍
245+
- [ ] 改了哪些檔案/模組
246+
247+
## 測試
248+
- [ ] 單元測試
249+
- [ ] 手動驗證步驟
250+
251+
## 風險
252+
- [ ] 相容性 / 效能 / 安全影響
253+
254+
<span class="hl-c"># docs/branching-strategy.md（摘錄）</span>
255+
main ← 永遠可發布，禁止直接 push（保護分支）
256+
feature/* ← 從 main 開，合併回 main（squash）
257+
hotfix/* ← 從 main 開，合併回 main 後也要併回 feature 線</pre>
258+
</div>
259+
<div class="demo-block">
260+
<div class="demo-label">驗證命令與輸出 · VERIFY</div>
261+
<pre>$ git log --oneline --graph main | head -8
262+
* 9f3a21e (HEAD -&gt; main) feat: 加入搜尋 (squash) <span class="hl-c"># 乾淨的 squash 歷史</span>
263+
* 41c0f12 fix: 修正登入空白
264+
* 7b2e9d0 chore: 初始專案
265+
266+
$ git branch -r --merged main <span class="hl-c"># 找出可刪的已合併分支</span>
267+
origin/feature/12-search
268+
origin/feature/10-login-fix</pre>
269+
</div>
270+
<div class="callout"><strong>專案級收斂：</strong>分支操作（單元 3）在這裡升級成「策略 + 範本 + 手冊」三件套——個人技術變成團隊紀律。git log 乾淨，release 可預測。</div>
271+
272+
<h2>效能 / 品質 / 安全深度</h2>
273+
<h3>效能：分支與 CI 的節奏</h3>
274+
<ul>
275+
<li>每顆 MR 只觸發自己相關的 job（<code>rules: changes:</code>），文件專案不跑後端測試。</li>
276+
<li>定期刪除已合併分支（GitLab 可勾選自動刪除），避免 branch 列表塞爆、也省遠端 ref 儲存。</li>
277+
<li>Trunk-based 節奏（小 MR、頻繁合併）比長壽命分支減少衝突與合併成本。</li>
278+
</ul>
279+
<h3>品質：衝突少、歷史乾淨</h3>
280+
<ul>
281+
<li>小 commit、頻繁 pull、一次只做一件事——衝突大多不是技術問題，是節奏問題。</li>
282+
<li>統一合併方式（squash）＋MR 範本，讓每顆 MR 有動機、有範圍、有測試。</li>
283+
<li><code>git log --oneline</code> 一行懂一行：commit 訊息寫「做了什麼」。</li>
284+
</ul>
285+
<h3>安全：保護你的主線</h3>
286+
<ul>
287+
<li><strong>保護分支</strong>：main 禁止直接 push、禁止 force push、只有 Maintainer 能合併。</li>
288+
<li><strong>signed commits</strong>：可設 push rule 拒收未簽署 commit，確保來源可信。</li>
289+
<li>hotfix 走 MR（不是直接 push main），就算緊急也要留痕。</li>
290+
</ul>
291+
292+
<h2>站際比較對照表</h2>
293+
<table>
294+
<tr><th>面向</th><th>gitlab</th><th>github</th><th>markdown</th><th>yaml</th><th>json</th></tr>
295+
<tr><td>合併請求</td><td>Merge Request</td><td>Pull Request</td><td>文件版本文責</td><td>—</td><td>—</td></tr>
296+
<tr><td>分支模型</td><td>GitFlow / Trunk 皆可</td><td>同左（偏好 PR 流程）</td><td>—</td><td>—</td><td>—</td></tr>
297+
<tr><td>衝突表示</td><td>網頁 Resolve conflicts</td><td>網頁衝突解工具</td><td>diff 肉眼比對</td><td>縮排衝突難解</td><td>合併易覆蓋</td></tr>
298+
<tr><td>自動關閉</td><td>Closes #id / Fixes #id</td><td>Closes / Fixes</td><td>—</td><td>—</td><td>—</td></tr>
299+
<tr><td>保護分支</td><td>免費且細粒度</td><td>進階需付費</td><td>—</td><td>—</td><td>—</td></tr>
300+
</table>
301+
302+
<h2>互動式檢核清單</h2>
303+
<div class="demo-block">
304+
<div class="demo-label">進階驗收清單 · CHECKLIST</div>
305+
<pre>- [ ] 分支策略已文件化並全員遵守
306+
- [ ] 每顆 MR 都用範本＋Closes #issue
307+
- [ ] main 已設保護分支（禁直接 push / 禁 force push）
308+
- [ ] 已示範一次手動解衝突並記錄步驟
309+
- [ ] 已刪除所有已合併的殘留分支
310+
- [ ] 已驗證 squash 合併後 git log 歷史乾淨</pre>
311+
</div>
312+
218313
</div>
219314
<footer>這是 GitLab 繁體中文教學站 · 由 OpenCode 建置<br>
220315
<span class="footer-license">本站教學內容（繁體中文解說）為本站原創，採 CC-BY-4.0；技術名詞與操作引用自 <a href="https://docs.gitlab.com/" rel="noopener">GitLab Docs</a> 與 <a href="https://git-scm.com/doc" rel="noopener">Git 官方文件</a>。</span></footer>

0 commit comments

Comments
 (0)