GitLab CI/CD 執行器部署與自動化測試實戰指南

#!/usr/bin/env bash

# GitLab Runner 註冊配置腳本
# 提供非互動式註冊功能，支援批次部署多個執行器

set -euo pipefail

# 配置參數
readonly GITLAB_URL="https://gitlab.example.com/"
readonly REGISTRATION_TOKEN="your-project-registration-token"
readonly EXECUTOR_TYPE="docker"
readonly DEFAULT_DOCKER_IMAGE="alpine:latest"
readonly RUNNER_TAG_LIST="docker,linux,automated-testing"

# 函式：驗證必要工具是否已安裝
# 確保 gitlab-runner 與 docker 命令可用
validate_prerequisites() {
    echo "驗證系統先決條件"
    
    # 檢查 GitLab Runner 是否已安裝
    if ! command -v gitlab-runner &> /dev/null; then
        echo "錯誤：找不到 gitlab-runner 指令，請先安裝 GitLab Runner" >&2
        return 1
    fi
    
    # 顯示已安裝的 GitLab Runner 版本
    echo "已安裝的 GitLab Runner 版本："
    gitlab-runner --version
    
    # 檢查 Docker 是否已安裝（使用 Docker executor 時必要）
    if [[ "$EXECUTOR_TYPE" == "docker" ]]; then
        if ! command -v docker &> /dev/null; then
            echo "錯誤：找不到 docker 指令，請先安裝 Docker" >&2
            return 1
        fi
        
        # 驗證 Docker 服務是否正在執行
        if ! docker info &> /dev/null; then
            echo "錯誤：Docker 服務未執行，請啟動 Docker" >&2
            return 1
        fi
        
        echo "Docker 服務狀態正常"
    fi
    
    echo "先決條件驗證完成"
    return 0
}

# 函式：註冊單一 GitLab Runner
# 參數：
#   $1 - 執行器描述名稱
#   $2 - 執行器標籤（可選，以逗號分隔）
register_runner() {
    local runner_description="$1"
    local runner_tags="${2:-$RUNNER_TAG_LIST}"
    
    echo "開始註冊執行器：$runner_description"
    
    # 執行非互動式註冊命令
    # 使用 sudo 確保有足夠權限修改系統配置
    if sudo gitlab-runner register \
        --non-interactive \
        --url "$GITLAB_URL" \
        --registration-token "$REGISTRATION_TOKEN" \
        --executor "$EXECUTOR_TYPE" \
        --docker-image "$DEFAULT_DOCKER_IMAGE" \
        --description "$runner_description" \
        --tag-list "$runner_tags" \
        --run-untagged="false" \
        --locked="false" \
        --access-level="not_protected"; then
        
        echo "執行器註冊成功：$runner_description"
        return 0
    else
        echo "錯誤：執行器註冊失敗" >&2
        return 1
    fi
}

# 函式：驗證已註冊的執行器狀態
# 檢查執行器是否能夠正常連接 GitLab 主機
verify_registered_runners() {
    echo "驗證已註冊的執行器狀態"
    
    # 使用 verify 命令檢查所有已註冊執行器的連接狀態
    if sudo gitlab-runner verify; then
        echo "所有執行器驗證通過"
        return 0
    else
        echo "警告：部分執行器驗證失敗" >&2
        return 1
    fi
}

# 函式：顯示已註冊的執行器清單
list_registered_runners() {
    echo "=========================================="
    echo "已註冊的執行器清單"
    echo "=========================================="
    
    # 使用 list 命令顯示所有已註冊的執行器資訊
    sudo gitlab-runner list
    
    echo "=========================================="
}

# 函式：批次註冊多個執行器
# 參數：
#   $1 - 執行器基礎名稱
#   $2 - 註冊數量
batch_register_runners() {
    local base_name="$1"
    local count="${2:-1}"
    
    echo "批次註冊 $count 個執行器"
    echo "基礎名稱：$base_name"
    
    for ((i=1; i<=count; i++)); do
        local runner_name="${base_name} ${i}"
        echo "----------------------------------------"
        echo "註冊執行器 $i/$count"
        
        if ! register_runner "$runner_name"; then
            echo "警告：執行器 $i 註冊失敗，繼續處理下一個" >&2
        fi
        
        # 在註冊之間加入短暫延遲，避免過載 GitLab 伺服器
        sleep 2
    done
    
    echo "批次註冊完成"
}

# 函式：配置執行器並行數與檢查間隔
# 修改主配置檔案以最佳化執行器效能
configure_runner_settings() {
    local concurrent_jobs="${1:-2}"
    local check_interval="${2:-3}"
    local config_file="/etc/gitlab-runner/config.toml"
    
    echo "配置執行器全域設定"
    echo "並行任務數：$concurrent_jobs"
    echo "檢查間隔：$check_interval 秒"
    
    # 檢查配置檔案是否存在
    if [[ ! -f "$config_file" ]]; then
        echo "警告：找不到配置檔案 $config_file" >&2
        return 1
    fi
    
    # 備份原始配置檔案
    local backup_file="${config_file}.backup.$(date +%Y%m%d_%H%M%S)"
    sudo cp "$config_file" "$backup_file"
    echo "已建立配置備份：$backup_file"
    
    # 修改並行任務數設定
    # 使用 sed 替換 concurrent 行的數值
    sudo sed -i "s/^concurrent = .*/concurrent = $concurrent_jobs/" "$config_file"
    
    # 修改檢查間隔設定
    sudo sed -i "s/^check_interval = .*/check_interval = $check_interval/" "$config_file"
    
    echo "配置設定已更新"
    
    # 重新啟動 GitLab Runner 服務使設定生效
    echo "重新啟動 GitLab Runner 服務"
    sudo systemctl restart gitlab-runner
    
    # 等待服務完全啟動
    sleep 3
    
    # 驗證服務狀態
    if sudo systemctl is-active --quiet gitlab-runner; then
        echo "GitLab Runner 服務運作正常"
    else
        echo "警告：GitLab Runner 服務可能未正確啟動" >&2
    fi
    
    return 0
}

# 主程式流程
main() {
    echo "=========================================="
    echo "GitLab Runner 註冊與配置工具"
    echo "=========================================="
    
    # 步驟一：驗證系統先決條件
    if ! validate_prerequisites; then
        echo "先決條件驗證失敗，程式終止" >&2
        exit 1
    fi
    
    # 步驟二：執行批次註冊
    # 根據實際需求調整執行器名稱與數量
    local project_name="Automated-Testing-Project"
    local runner_count=2
    
    batch_register_runners "$project_name Runner" "$runner_count"
    
    # 步驟三：驗證註冊結果
    echo "=========================================="
    verify_registered_runners
    
    # 步驟四：顯示已註冊的執行器
    list_registered_runners
    
    # 步驟五：最佳化執行器配置
    echo "=========================================="
    echo "最佳化執行器配置"
    
    # 設定並行任務數為 4，檢查間隔為 3 秒
    configure_runner_settings 4 3
    
    echo "=========================================="
    echo "GitLab Runner 配置完成"
    echo "=========================================="
    
    # 顯示後續操作提示
    cat << 'EOF'

後續操作建議：
  1. 前往 GitLab 專案設定頁面驗證執行器連接狀態
     路徑：專案設定 > CI/CD > Runners

  2. 根據實際需求調整執行器標籤
     編輯配置檔案：/etc/gitlab-runner/config.toml

  3. 監控執行器資源使用狀況
     指令：sudo gitlab-runner status

  4. 查看執行器日誌排查問題
     指令：sudo journalctl -u gitlab-runner -f
EOF
}

# 僅在直接執行時啟動主程式
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
    main "$@"
fi

#!/usr/bin/env python3
"""
使用者登入功能模組
提供基本的身分驗證功能
"""

def authenticate_user(username: str, password: str) -> bool:
    """
    驗證使用者登入憑證
    
    參數：
        username: 使用者名稱
        password: 使用者密碼
        
    返回：
        驗證成功返回 True，否則返回 False
        
    範例：
        >>> authenticate_user("admin", "secure_password")
        True
        >>> authenticate_user("admin", "wrong_password")
        False
    """
    # 實務中應查詢資料庫並驗證雜湊密碼
    # 此處僅為示範目的使用硬編碼憑證
    valid_credentials = {
        "admin": "secure_password",
        "dana": "p@ssw0rd",
        "test_user": "test123"
    }
    
    # 驗證使用者名稱是否存在
    if username not in valid_credentials:
        return False
    
    # 驗證密碼是否正確
    return valid_credentials[username] == password

def validate_password_strength(password: str) -> tuple[bool, str]:
    """
    驗證密碼強度是否符合安全要求
    
    參數：
        password: 待驗證的密碼字串
        
    返回：
        (驗證結果, 錯誤訊息) 的元組
        驗證通過時返回 (True, "")
        驗證失敗時返回 (False, "具體錯誤原因")
        
    密碼要求：
        - 最少 8 個字元
        - 至少包含一個大寫字母
        - 至少包含一個小寫字母
        - 至少包含一個數字
    """
    # 檢查密碼長度
    if len(password) < 8:
        return False, "密碼長度必須至少 8 個字元"
    
    # 檢查是否包含大寫字母
    if not any(char.isupper() for char in password):
        return False, "密碼必須包含至少一個大寫字母"
    
    # 檢查是否包含小寫字母
    if not any(char.islower() for char in password):
        return False, "密碼必須包含至少一個小寫字母"
    
    # 檢查是否包含數字
    if not any(char.isdigit() for char in password):
        return False, "密碼必須包含至少一個數字"
    
    return True, ""

#!/usr/bin/env python3
"""
登入功能單元測試套件
使用 Pytest 框架驗證身分驗證邏輯的正確性
"""

import pytest
from login import authenticate_user, validate_password_strength

class TestUserAuthentication:
    """使用者身分驗證功能測試類別"""
    
    def test_authenticate_with_valid_credentials(self):
        """
        測試使用有效憑證進行身分驗證
        預期結果：驗證成功，返回 True
        """
        assert authenticate_user("admin", "secure_password") is True
        assert authenticate_user("dana", "p@ssw0rd") is True
        assert authenticate_user("test_user", "test123") is True
    
    def test_authenticate_with_invalid_username(self):
        """
        測試使用不存在的使用者名稱進行驗證
        預期結果：驗證失敗，返回 False
        """
        assert authenticate_user("nonexistent_user", "any_password") is False
        assert authenticate_user("", "secure_password") is False
    
    def test_authenticate_with_invalid_password(self):
        """
        測試使用錯誤密碼進行驗證
        預期結果：驗證失敗，返回 False
        """
        assert authenticate_user("admin", "wrong_password") is False
        assert authenticate_user("dana", "incorrect") is False
    
    def test_authenticate_with_empty_credentials(self):
        """
        測試使用空白憑證進行驗證
        預期結果：驗證失敗，返回 False
        """
        assert authenticate_user("", "") is False
        assert authenticate_user("admin", "") is False
        assert authenticate_user("", "secure_password") is False
    
    @pytest.mark.parametrize("username,password,expected", [
        ("admin", "secure_password", True),
        ("dana", "p@ssw0rd", True),
        ("admin", "wrong", False),
        ("fake_user", "any_pass", False),
    ])
    def test_authenticate_parametrized(self, username, password, expected):
        """
        參數化測試：使用多組測試資料驗證身分驗證邏輯
        
        參數：
            username: 測試用使用者名稱
            password: 測試用密碼
            expected: 預期的驗證結果
        """
        assert authenticate_user(username, password) is expected

class TestPasswordStrength:
    """密碼強度驗證功能測試類別"""
    
    def test_validate_strong_password(self):
        """
        測試符合所有強度要求的密碼
        預期結果：驗證通過
        """
        is_valid, error_message = validate_password_strength("SecurePass123")
        assert is_valid is True
        assert error_message == ""
    
    def test_validate_password_too_short(self):
        """
        測試長度不足的密碼
        預期結果：驗證失敗，提示長度不足
        """
        is_valid, error_message = validate_password_strength("Short1")
        assert is_valid is False
        assert "長度" in error_message
    
    def test_validate_password_no_uppercase(self):
        """
        測試缺少大寫字母的密碼
        預期結果：驗證失敗，提示缺少大寫字母
        """
        is_valid, error_message = validate_password_strength("lowercase123")
        assert is_valid is False
        assert "大寫" in error_message
    
    def test_validate_password_no_lowercase(self):
        """
        測試缺少小寫字母的密碼
        預期結果：驗證失敗，提示缺少小寫字母
        """
        is_valid, error_message = validate_password_strength("UPPERCASE123")
        assert is_valid is False
        assert "小寫" in error_message
    
    def test_validate_password_no_digit(self):
        """
        測試缺少數字的密碼
        預期結果：驗證失敗，提示缺少數字
        """
        is_valid, error_message = validate_password_strength("NoDigitPass")
        assert is_valid is False
        assert "數字" in error_message
    
    @pytest.mark.parametrize("password,should_be_valid", [
        ("StrongPass123", True),
        ("AnotherGood1", True),
        ("weak", False),
        ("nouppercase1", False),
        ("NOLOWERCASE1", False),
        ("NoDigitsHere", False),
    ])
    def test_validate_password_parametrized(self, password, should_be_valid):
        """
        參數化測試：使用多組密碼驗證強度檢查邏輯
        
        參數：
            password: 測試用密碼字串
            should_be_valid: 預期的驗證結果
        """
        is_valid, _ = validate_password_strength(password)
        assert is_valid is should_be_valid

# GitLab CI/CD 管線配置檔案
# 定義自動化測試與程式碼品質檢查流程

# 宣告管線的執行階段
# 階段會按照列出的順序依次執行
stages:
  - test          # 測試階段：執行單元測試與整合測試
  - quality       # 品質階段：執行程式碼品質掃描
  - security      # 安全階段：執行安全性測試

# 全域變數定義
# 可被所有任務存取的環境變數
variables:
  # Python 套件安裝快取目錄
  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
  # Pytest 輸出設定
  PYTEST_OPTS: "--verbose --junit-xml=test_results.xml --cov=. --cov-report=xml --cov-report=term"

# 全域快取配置
# 定義在任務間保留的目錄，加速後續任務執行
cache:
  # 快取金鑰：基於分支名稱，確保不同分支使用獨立快取
  key: "${CI_COMMIT_REF_SLUG}"
  paths:
    - .cache/pip           # pip 下載快取
    - .venv/               # Python 虛擬環境（若使用）

# 任務：單元測試執行
unit-tests:
  # 指定任務所屬階段
  stage: test
  
  # 指定執行環境的 Docker 映像
  # 使用官方 Python 3.10 映像，基於 Debian
  image: python:3.10-slim
  
  # 任務執行前的準備步驟
  before_script:
    # 更新 pip 至最新版本，避免安裝問題
    - python -m pip install --upgrade pip
    # 安裝專案依賴套件
    - pip install -r requirements.txt
    # 安裝測試相關套件（若未包含在 requirements.txt）
    - pip install pytest pytest-cov pytest-html
  
  # 任務主要執行步驟
  script:
    # 執行 Pytest 測試框架
    # --verbose: 顯示詳細測試輸出
    # --junit-xml: 生成 JUnit 格式測試報告
    # --cov: 啟用覆蓋率統計
    # --cov-report: 指定覆蓋率報告格式
    - pytest $PYTEST_OPTS
  
  # 任務產出物配置
  # 定義需要保留的檔案，供後續使用或下載
  artifacts:
    # 即使任務失敗也保留產出物
    when: always
    # 產出物保留時間：30 天
    expire_in: 30 days
    # 測試報告配置
    reports:
      # JUnit 格式測試報告，會整合至 GitLab 介面
      junit: test_results.xml
      # Cobertura 格式覆蓋率報告
      coverage_report:
        coverage_format: cobertura
        path: coverage.xml
    # 額外保留的檔案路徑
    paths:
      - test_results.xml     # 測試結果
      - coverage.xml         # 覆蓋率報告
      - htmlcov/             # HTML 格式覆蓋率報告
  
  # 覆蓋率統計正規表達式
  # 從測試輸出中提取覆蓋率百分比
  coverage: '/(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/'
  
  # 任務執行規則
  # 定義在哪些情況下執行此任務
  rules:
    # 在合併請求中執行
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    # 在主要分支的推送中執行
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

# 任務：整合測試執行（範例）
integration-tests:
  stage: test
  image: python:3.10-slim
  
  # 服務容器：用於提供測試所需的外部依賴
  services:
    # PostgreSQL 資料庫服務
    - name: postgres:14-alpine
      alias: postgres
  
  # 環境變數：配置服務連接資訊
  variables:
    POSTGRES_DB: test_db
    POSTGRES_USER: test_user
    POSTGRES_PASSWORD: test_password
    DATABASE_URL: "postgresql://test_user:test_password@postgres:5432/test_db"
  
  before_script:
    - pip install --upgrade pip
    - pip install -r requirements.txt
    # 等待資料庫服務就緒
    - apt-get update && apt-get install -y postgresql-client
    - until pg_isready -h postgres -U test_user; do sleep 1; done
  
  script:
    # 執行需要資料庫的整合測試
    - pytest tests/integration/ --verbose
  
  # 僅在合併請求時執行整合測試
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

# 任務：程式碼品質掃描
code-quality:
  stage: quality
  
  # 使用 GitLab 官方的程式碼品質分析映像
  image: registry.gitlab.com/gitlab-org/ci-cd/codequality:latest
  
  # 允許任務失敗而不影響管線狀態
  # 適用於尚未完全符合品質標準的專案
  allow_failure: true
  
  script:
    # 執行程式碼品質分析工具
    # 輸出 GitLab 格式的品質報告
    - /analyzer run --format gitlab > gl-code-quality-report.json
  
  artifacts:
    when: always
    expire_in: 30 days
    reports:
      # 程式碼品質報告會整合至合併請求介面
      codequality: gl-code-quality-report.json
    paths:
      - gl-code-quality-report.json
  
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

# 任務：靜態安全掃描
security-scan:
  stage: security
  image: python:3.10-slim
  
  before_script:
    - pip install --upgrade pip
    # 安裝安全掃描工具
    - pip install bandit safety
  
  script:
    # Bandit：Python 程式碼安全漏洞掃描
    - bandit -r . -f json -o bandit-report.json || true
    # Safety：檢查依賴套件的已知安全漏洞
    - safety check --json > safety-report.json || true
  
  artifacts:
    when: always
    expire_in: 30 days
    paths:
      - bandit-report.json
      - safety-report.json
  
  allow_failure: true
  
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'