MkDocs × GitLab CI × Caddy 建置指南

本文件說明如何在 自建 GitLab + Caddy 的環境下，建置一套 不依賴 GitLab Pages 的文件系統，用於「對外 Docs」與「內部 KM」。

架構概覽

文件作者
  ↓ git push
GitLab Repository
  ↓
GitLab CI
  ↓
MkDocs build（產生靜態 HTML）
  ↓
/opt/docs (主機目錄)
  ↓
Caddy (HTTPS)
  ↓
docs / km 網站

目錄結構（單一 Repo，雙文件）

docs-portal/
├── docs/
│   ├── public/        # 對外文件
│   │   └── index.md
│   └── internal/      # 內部 KM
│       └── index.md
│
├── mkdocs.public.yml
├── mkdocs.internal.yml
├── .gitlab-ci.yml
└── README.md

MkDocs 設定檔

對外文件：`mkdocs.public.yml`

site_name: Dadidi Public Docs
site_description: Dadidi official technical documentation

docs_dir: docs/public
site_dir: site-public

theme:
  name: material
  language: zh-TW
  features:
    - navigation.tabs
    - navigation.sections
    - search.highlight
    - content.code.copy

plugins:
  - search

nav:
  - 首頁: index.md

內部 KM：`mkdocs.internal.yml`

site_name: Dadidi Internal KM
site_description: Internal knowledge base

docs_dir: docs/internal
site_dir: site-internal

theme:
  name: material
  language: zh-TW
  features:
    - navigation.expand
    - search.highlight
    - search.share
    - toc.follow

plugins:
  - search

GitLab CI 設定（推薦：build 用 Docker，deploy 用 Shell）

.gitlab-ci.yml

stages:
  - build
  - deploy

build_docs:
  stage: build
  image: python:3.11
  before_script:
    - pip install mkdocs mkdocs-material
  script:
    - mkdocs build -f mkdocs.public.yml
    - mkdocs build -f mkdocs.internal.yml
  artifacts:
    paths:
      - site-public/
      - site-internal/
  only:
    - main

deploy_docs:
  stage: deploy
  image: debian:12-slim
  before_script:
    - apt-get update
    - apt-get install -y rsync
  script:
    - rsync -av --delete site-public/ /opt/docs/public/
    - rsync -av --delete site-internal/ /opt/docs/internal/
  only:
    - main

deploy job 使用 shell executor，主機需先安裝 rsync：

bash sudo apt update sudo apt install -y rsync

補充：deploy 仍用 Docker executor 的注意事項

Docker executor 看不到 host 的 /opt/docs，除非明確 mount。
需在 runner 設定加入 volume：

[runners.docker]
  volumes = ["/opt/docs:/opt/docs"]

這會讓所有 docker job 都可寫主機路徑，請評估資安風險。
image 需有 rsync（或在 job 內 apt-get install -y rsync）。

主機目錄準備

在 GitLab Runner 所在主機上建立目錄：

sudo mkdir -p /opt/docs/public
sudo mkdir -p /opt/docs/internal

權限設定（`chown: 使用者無效` 常見）

如果出現 chown: 使用者無效: gitlab-runner:gitlab-runner，代表主機上沒有該使用者（runner 跑在 container 裡）。可選：

方案 A（簡單）：

sudo chown -R root:root /opt/docs
sudo chmod -R 755 /opt/docs

方案 B（精準）：以 runner container 的 UID 設權限

docker ps | grep gitlab-runner
docker exec -it <container_id> id
sudo chown -R 1000:1000 /opt/docs

不建議： - 亂建 gitlab-runner 使用者 - 將 /opt/docs 設成 777

Caddy 設定

在 Caddyfile 中新增：

docs.dadidi.org {
    root * /opt/docs/public
    file_server
}

km.dadidi.org {
    root * /opt/docs/internal
    file_server
}

重啟 Caddy：

docker restart gitlab-caddy-caddy-1

如果 Caddy 跑在 Docker container

docker-compose.yml 必須把 /opt/docs 掛進 Caddy：

caddy:
  image: caddy:latest
  restart: unless-stopped
  volumes:
    - caddy_data:/data
    - caddy_config:/config
    - ./Caddyfile:/etc/caddy/Caddyfile
    - /opt/docs:/opt/docs
  network_mode: "host"

volume 只在 container 啟動時生效，改完請重新啟動（不是只 reload）。

日常使用流程

編輯 Markdown
git push main
GitLab CI 自動 build
靜態文件自動更新
透過 Caddy 提供最新內容

注意事項 / 常見問題

rsync: command not found：image 沒 rsync，請安裝或換 image。
rsync: mkdir ... No such file or directory：Docker executor 看不到 /opt/docs，改用 shell deploy 或 mount volume。
pip: command not found：deploy job 不需要 pip，將 pip install 放在 build job。
Caddy 404 但檔案存在：Caddy container 沒掛到 /opt/docs，請加 volume 並重啟。
內部 KM 建議加 VPN / IP 限制 / Basic Auth。
rsync --delete 會同步刪除舊檔，請勿手動改 /opt/docs。
所有文件以 Git 為唯一來源（Single Source of Truth）。