Pcion's Blog

Git 是目前最常見的版本控制工具，無論是個人專案、團隊協作，或是 CI/CD 流程，幾乎都會透過 Git 來管理程式碼版本。若團隊使用 GitLab 作為 Git repository 平台，開發者除了要先在本機安裝 Git，也需要準備好 GitLab 的存取權限，才能順利 clone 專案。

本文會示範如何在 Ubuntu 環境安裝 Git，並使用 GitLab 的 Personal Access Token 透過 HTTPS clone repository。範例會以 https://inner.gitlab.dev/pcion123/docker-test.git 作為 repository URL，實際操作時請替換成自己的 GitLab 網址、帳號與專案路徑。

前置需求

開始前，請先確認已具備以下條件：

• 一台可以使用終端機操作的 Ubuntu 主機
• 具備 sudo 權限的使用者帳號
• 可以連線到 GitLab 服務的網路環境
• 已經擁有 GitLab 帳號，且有目標 repository 的讀取權限

如果 GitLab 是公司內部或實驗環境自架的服務，也要先確認主機能解析 GitLab 的網域名稱。例如本文範例使用 inner.gitlab.dev，因此 Ubuntu 主機必須能正確連到這個位址。

GitLab 除了可以管理 Git repository、Merge Request 與 CI/CD，也內建 Container Registry 功能。開啟後，每個專案都可以擁有自己的映像檔倉庫，讓團隊把 Docker image 與程式碼放在同一個 GitLab 專案中管理，後續也能搭配 GitLab CI/CD 自動 build、push 與部署。

本文會示範如何在 GitLab Self-Managed 環境中開啟 Container Registry，並透過 Docker CLI 完成登入、build、tag、push 與 GitLab Web UI 驗證。範例環境使用 inner.gitlab.dev 作為 GitLab 網域，並使用 5050 作為 Container Registry 對外連接埠。

前置需求

開始設定前，請先確認環境符合以下條件：

• 已經安裝 GitLab Self-Managed，並可正常登入 GitLab Web UI
• 可以使用具備 sudo 權限的帳號登入 GitLab 主機
• GitLab 主機的網域名稱或 IP 可以被 Docker client 解析與連線
• Docker client 已安裝 Docker Engine 或 Docker Desktop
• 防火牆、VM port forwarding、安全群組或上層網路設備已開放 Container Registry 使用的連接埠

如果 GitLab 是正式環境，建議搭配 HTTPS 與正式憑證使用；如果只是內網測試環境，也可以先使用 HTTP，但 Docker client 端通常需要額外設定 insecure registry，否則會因為未使用 TLS 而拒絕連線。

GitLab Community Edition，也就是常見的 gitlab-ce，是 GitLab 提供的自架版本。它會把 Git repository、Issue、Merge Request、CI/CD、Wiki 與基本專案管理功能整合在同一套 Web 服務中，很適合用來架設團隊內部的 Git 平台，或是在測試環境中熟悉 GitLab Self-Managed 的操作方式。

本文會依照 GitLab 官方 Ubuntu Linux package 安裝文件，示範如何在 Ubuntu 上安裝 gitlab-ce，並完成第一次登入。官方文件可以參考：Install the Linux package on Ubuntu。

前置需求

開始安裝前，請先確認環境符合以下條件：

• Ubuntu 22.04 或 Ubuntu 24.04
• 可以使用具備 sudo 權限的帳號
• 主機可以連線到 https://packages.gitlab.com/* 與 https://storage.googleapis.com/packages-ops/*
• 若要讓外部使用者連線，需要先準備好 GitLab 使用的網域名稱或固定 IP
• 若使用 HTTPS 網址，需要確認 80 與 443 連接埠可以從外部連入，讓 GitLab 可以透過 Let’s Encrypt 申請憑證

GitLab 是一套資源需求相對高的服務，正式部署前也建議先閱讀官方的 installation requirements，確認 CPU、記憶體與儲存空間是否足夠。若只是本機測試或 VM 練習，也要預留足夠的記憶體與磁碟空間，避免安裝或重新設定過程中失敗。

簡介

Windows Terminal 不只是把 PowerShell、命令提示字元、WSL 或其他 shell 集中在同一個視窗中，它也支援 Panes，也就是在同一個分頁內切出多個終端機窗格。透過畫面分割，可以同時查看多個命令列工作，不需要在不同分頁或不同視窗之間來回切換。

例如在開發時，可以左邊執行本機服務，右邊查看 Git 狀態；也可以上方跑測試，下方保留一個 shell 用來查詢檔案或執行臨時指令。這種使用方式很適合需要同時觀察多個 CLI 工作的情境。

本文整理 Windows Terminal 畫面分割的常用操作，包含建立窗格、切換焦點、調整大小、關閉窗格，以及透過設定檔自訂快捷鍵。

官方文件參考：Windows Terminal Panes

這篇文章記錄如何透過 opentelemetry-collector 蒐集 Spring Boot 應用程式產生的監控數據，並將應用程式端送出的 traces、metrics 與 logs 統一交由 OpenTelemetry Collector 接收與處理。

OpenTelemetry Collector 在整個流程中扮演中介層的角色。Spring Boot 應用程式會透過 OTLP 將資料送到 Collector，Collector 再依照設定把不同類型的 telemetry data 分別交給對應的 exporter。這樣可以讓應用程式端維持一致的輸出方式，後續若要更換監控後端，也能集中調整 Collector 設定。

本文會依序完成以下設定：

1. 安裝 OpenTelemetry Collector
2. 修改 Collector 設定檔
3. 設定 Collector 接收 OTLP 資料並輸出 Prometheus metrics
4. 在 Spring Boot 專案中加入 OpenTelemetry 相關依賴
5. 設定 Spring Boot 將資料送到 Collector

這篇文章記錄如何在 Spring Boot 應用程式中加入 micrometer-registry-prometheus，並透過 Spring Boot Actuator 暴露 Prometheus 可以抓取的 Metrics endpoint。

Grafana 與 Prometheus 的安裝流程已經在前一篇文章介紹過，因此本文會專注在 Spring Boot 與 Prometheus 之間的設定：Spring Boot 要如何產生監控指標、Prometheus 要如何抓取這些指標，以及設定完成後要如何確認資料是否正常。

整體架構

在這個監控流程中，Spring Boot 應用程式本身不會主動把資料推送到 Prometheus，而是透過 Actuator 開放 /actuator/prometheus endpoint。Prometheus 會依照設定的間隔定期呼叫這個 endpoint，將應用程式的 Metrics 抓回來儲存。

整體流程如下：

1. Spring Boot 加入 Actuator 與 Prometheus Registry 相依套件
2. Spring Boot 開放 /actuator/prometheus endpoint
3. Prometheus 設定 scrape target，定期抓取 Spring Boot Metrics
4. 在 Prometheus Web UI 確認 target 狀態與查詢 Metrics
5. Grafana 透過 Prometheus 資料來源建立 Dashboard

本文會聚焦在前四個步驟，Grafana Dashboard 的操作不會在這篇文章中展開。

這篇文章記錄如何在 Linux 環境中安裝 Prometheus、Grafana 與 Node Exporter，並透過 Grafana 匯入 Node Exporter Dashboard，建立一套基本的主機監控環境。

整體流程會先完成 Prometheus 的服務安裝，再安裝 Grafana 作為視覺化介面，接著部署 Node Exporter 讓 Prometheus 能夠收集主機 Metrics，最後在 Grafana 中設定資料來源並匯入 Dashboard。

簡介

在開發 Java 應用程式時，很多問題只有在特定環境才會出現。例如應用程式部署在遠端 Linux 主機、Docker container、Kubernetes Pod，或是某個測試環境中，單靠本機重現不一定能完整模擬實際狀況。這時候，遠端 Debug 就會變得很有用。

Java 本身提供 JDWP（Java Debug Wire Protocol）作為除錯器與 JVM 之間的溝通協議。只要啟動 Java 應用程式時開啟 JDWP debug port，VS Code 就可以透過 Debugger for Java 連線到該 JVM，像在本機除錯一樣設定中斷點、查看變數、逐步執行程式碼。

這篇文章會介紹如何使用 VS Code 連線到遠端 Java 應用程式進行 Debug，並說明 JDWP 啟動參數、VS Code launch.json 設定，以及常見連線問題的排查方式。

在 Spring Boot 應用程式中，Log 通常會先輸出到 Console 或檔案，方便開發與單機排查問題。不過當服務數量變多、部署環境變複雜後，單靠各主機上的 Log 檔案會讓查詢與追蹤變得不方便。這時可以透過 Logstash 接收 Spring Boot 輸出的結構化 Log，再寫入 Elasticsearch，讓後續查詢、分析與視覺化更加集中。

本文會記錄如何在 Linux 環境安裝 Logstash，設定 Logstash 將 TCP 收到的 JSON Log 寫入 Elasticsearch，最後再於 Spring Boot 的 logback 設定中加入 Logstash Appender，讓應用程式 Log 可以送進 Elasticsearch。

什麼是 Jaeger？

Jaeger 是一套開源的分散式追蹤系統，常用於觀察微服務架構中請求在不同服務之間的流向、耗時與錯誤位置。透過 Jaeger，可以把分散在多個服務中的 trace 資料集中起來，協助開發者分析效能瓶頸與服務之間的呼叫關係。

本文會示範如何在 Ubuntu 環境中安裝 Jaeger Tracing，並透過 systemd 將 Jaeger 設定成系統服務。這裡使用 Jaeger 的 OpenTelemetry Native Backend 設定，讓服務可以接收 OTLP gRPC 與 HTTP 格式的 trace 資料，並透過 Jaeger Query UI 查詢追蹤結果。

Jaeger 的主要功能：

• 分散式追蹤：記錄請求在多個服務之間的完整流向
• 效能分析：查看每個 span 的耗時，協助找出延遲來源
• 錯誤排查：透過 trace 資料定位服務呼叫失敗或異常的位置
• 服務觀察：搭配 OpenTelemetry 收集 trace，建立基本的可觀測性基礎

為什麼使用 Jaeger？

相較於只依賴應用程式日誌，Jaeger 可以用更直觀的方式呈現跨服務請求的完整脈絡：

1. 請求脈絡清楚：可以追蹤一次請求經過哪些服務與操作
2. 問題定位更快：能從 trace 中看出延遲、錯誤與異常發生的位置
3. 支援 OpenTelemetry：可以接收 OTLP gRPC 與 HTTP 格式的 trace 資料