1. บทนำ Backstage.io
Backstage เป็น open-source framework สำหรับสร้าง Developer Portal หรือ Internal Developer Platform (IDP) พัฒนาโดย Spotify และปัจจุบันเป็น CNCF Incubating Project ตั้งแต่ปี 2020
ปัญหาหลักของทีมพัฒนาในองค์กรขนาดใหญ่คือ "ความยุ่งเหยิงของเอกสารและเครื่องมือ" - ไม่รู้ว่าบริการไหนรันอยู่ที่ไหน ใครเป็นคนดูแล และจะเริ่มต้นโปรเจคใหม่อย่างไร Backstage เข้ามาแก้ปัญหานี้ด้วยการรวมทุกอย่างไว้ในที่เดียว
ในปี 2025 Backstage ได้รับการพัฒนาอย่างต่อเนื่องด้วย New Frontend System, Actions Registry และ MCP server support ทำให้เป็นตัวเลือกอันดับต้นๆ สำหรับการสร้าง Developer Portal
2. ทำไมต้องใช้ Backstage
ปัญหาที่พบบ่อย
- ไม่รู้ว่า microservice ไหนรันอยู่ที่ไหน
- เอกสารกระจัดกระจายในหลายที่ (Confluence, Notion, Google Docs)
- การ onboarding พนักงานใหม่ใช้เวลานาน
- ไม่รู้ว่าใครเป็น owner ของบริการไหน
- สร้างโปรเจคใหม่ไม่มี standard
Backstage ช่วยแก้
- Software Catalog รวมทุกบริการในที่เดียว
- Docs-as-Code เอกสารอยู่ในโค้ด
- Self-service portal ลดเวลา onboarding
- Ownership tracking ชัดเจน
- Software Templates สร้างโปรเจคแบบ standard
ประโยชน์ที่ได้รับ
3. สถาปัตยกรรม Backstage
Backstage ใช้สถาปัตยกรรมแบบ Plugin-based ทำให้สามารถขยายความสามารถได้ตามต้องการ โครงสร้างหลักประกอบด้วย Core, Plugins แลย App Shell
สถาปัตยกรรม Backstage
Core Components
- • Software Catalog - ระบบทะเบียนซอฟต์แวร์
- • Software Templates - เทมเพลตสร้างโปรเจค
- • TechDocs - เอกสารจาก Markdown
- • Search - ค้นหาข้อมูลทั้งหมด
Plugin System
- • Core Plugins - มาพร้อม Backstage
- • Community Plugins - 200+ plugins
- • Custom Plugins - สร้างเองได้
- • Dynamic Loading - โหลดแบบ dynamic
4. ฟีเจอร์หลักของ Backstage
Software Catalog
ระบบทะเบียนซอฟต์แวร์ที่รวบรวมข้อมูลทุกบริการ, API, website, library และ resource ในองค์กร
- • แสดง owner และ dependencies
- • ติดตาม lifecycle status
- • รองรับ entity types หลายแบบ
- • Ingest จาก multiple sources
Software Templates
เทมเพลตสำหรับสร้างโปรเจคใหม่อย่างรวดเร็ว พร้อม best practices และ standard configurations
- • สร้างโปรเจคจาก template
- • Parameterized templates
- • GitHub/GitLab integration
- • CI/CD pipeline setup อัตโนมัติ
TechDocs
ระบบเอกสารที่แปลง Markdown เป็นเว็บไซต์ เอกสารอยู่ใกล้โค้ด (Docs-as-Code)
- • MkDocs compatible
- • Markdown + Mermaid diagrams
- • ค้นหาได้จาก Search
- • เชื่อมโยงกับ Catalog
Search
ค้นหาทุกอย่างในที่เดียว ไม่ว่าจะเป็น services, documentation, plugins หรือ resources
- • รองรับ Elasticsearch, Lunr
- • ค้นหาจากหลาย sources
- • Filter และ sort ได้
- • Real-time indexing
5. การติดตั้ง Backstage
สิ่งที่ต้องเตรียม
Software Requirements
- • Node.js 18.x หรือใหม่กว่า
- • Yarn 1.x (Classic)
- • Git
- • Docker (optional)
Database (Production)
- • PostgreSQL 13+ (แนะนำ)
- • MySQL 8+
- • SQLite (development)
1 สร้าง Backstage App ใหม่
# สร้าง Backstage app ใหม่
npx @backstage/create-app@latest
# ระบบจะถามชื่อ app (เช่น my-backstage)
# และ database (เลือก SQLite สำหรับ development)
2 เข้าสู่โฟลเดอร์และ start server
# เข้าสู่โฟลเดอร์โปรเจค
cd my-backstage
# ติดตั้ง dependencies
yarn install
# start development server
yarn dev
Backstage จะรันที่ http://localhost:3000
3 ตั้งค่า Database (Production)
# config/app-config.yaml
backend:
database:
client: pg
connection:
host: ${POSTGRES_HOST}
port: ${POSTGRES_PORT}
user: ${POSTGRES_USER}
password: ${POSTGRES_PASSWORD}
database: backstage
4 ตั้งค่า GitHub Integration
# config/app-config.yaml
integrations:
github:
- host: github.com
token: ${GITHUB_TOKEN}
catalog:
locations:
- type: url
target: https://github.com/myorg/my-repo/catalog-info.yaml
สร้าง GitHub Personal Access Token ที่ Settings → Developer settings → Personal access tokens
6. Plugins ยอดนิยม 2025
Backstage มี plugins มากกว่า 200 ตัว แบ่งเป็นหลายประเภท เช่น CI/CD, Monitoring, Security, Cloud และ Source Control
CI/CD Plugins
- Jenkins
- GitHub Actions
- GitLab CI
- CircleCI
Monitoring
- Datadog
- Grafana
- PagerDuty
- New Relic
Cloud & K8s
- Kubernetes
- ArgoCD
- AWS
- GCP
ตัวอย่าง: ติดตั้ง GitHub Plugin
# ติดตั้ง GitHub plugin packages
cd packages/app
yarn add @backstage/plugin-github-actions
cd ../../packages/backend
yarn add @backstage/plugin-github-actions-backend
// เพิ่ม GitHub Actions tab ใน Entity page
import { EntityGithubActionsContent } from '@backstage/plugin-github-actions';
const entityPage = (
<EntityLayout>
<EntityLayout.Route path="/ci" title="CI/CD">
<EntityGithubActionsContent />
</EntityLayout.Route>
</EntityLayout>
);
7. Software Templates
Software Templates ช่วยให้ทีมสามารถสร้างโปรเจคใหม่ได้อย่างรวดเร็ว พร้อม best practices และ configurations ที่ standard ทำให้ลดเวลา setup และเพิ่มความสอดคล้องของโค้ด
Software Template Workflow
ตัวอย่าง Template YAML
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
name: nodejs-service-template
title: Node.js Service Template
description: สร้าง Node.js microservice พร้อม CI/CD
spec:
owner: platform-team
type: service
parameters:
- title: ข้อมูลโปรเจค
required:
- component_id
- owner
properties:
component_id:
title: ชื่อ Service
type: string
description: ชื่อ unique ของ service (เช่น user-api)
owner:
title: Owner
type: string
description: Team ที่ดูแล
ui:field: OwnerPicker
description:
title: คำอธิบาย
type: string
description: อธิบายว่า service นี้ทำอะไร
steps:
# Step 1: สร้าง repository จาก template
- id: fetch-base
name: Fetch Base
action: fetch:template
input:
url: ./content
values:
name: ${{ parameters.component_id }}
owner: ${{ parameters.owner }}
description: ${{ parameters.description }}
# Step 2: Publish ไป GitHub
- id: publish
name: Publish to GitHub
action: publish:github
input:
allowedHosts: ['github.com']
description: ${{ parameters.description }}
repoUrl: github.com?owner=${{ parameters.owner }}&repo=${{ parameters.component_id }}
# Step 3: ลงทะเบียนใน Catalog
- id: register
name: Register in Catalog
action: catalog:register
input:
catalogInfoUrl: https://github.com/${{ parameters.owner }}/${{ parameters.component_id }}/blob/main/catalog-info.yaml
output:
links:
- title: Repository
url: ${{ steps.publish.output.remoteUrl }}
- title: Open in Catalog
icon: catalog
entityRef: ${{ steps.register.output.entityRef }}
8. Software Catalog
Software Catalog เป็นหัวใจของ Backstage ที่เก็บข้อมูลทุก entity ในองค์กร ไม่ว่าจะเป็น services, APIs, websites, resources หรือ teams
Component
Software หรือ service ที่รันอยู่ เช่น API, website, library
Group
Team หรือ organization unit ที่ดูแล entities
User
บุคคลในองค์กร
ตัวอย่าง catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: user-api
description: API สำหรับจัดการข้อมูลผู้ใช้
tags:
- nodejs
- express
- rest-api
annotations:
github.com/project-slug: myorg/user-api
backstage.io/techdocs-ref: dir:.
jenkins.io/job-full-name: myorg/user-api-build
spec:
type: service
lifecycle: production
owner: team-backend
system: user-management
dependsOn:
- component:default/user-database
apiConsumedBy:
- component:default/web-frontend
providesApis:
- api:default/user-api-rest
9. ตัวอย่างการใช้งานจริง
Use Case 1: Onboarding พนักงานใหม่
พนักงานใหม่สามารถเข้าถึงข้อมูลทั้งหมดในที่เดียว ลดเวลา from 2 weeks เป็น 3 days
ขั้นตอน:
- เข้า Backstage → ดู Software Catalog
- ค้นหา service ที่ต้องการเรียนรู้
- อ่าน TechDocs ที่เชื่อมโยงกับ service นั้น
- ดู owner และติดต่อได้ทันที
- สร้าง test project จาก Software Template
Use Case 2: ค้นหา Service Dependencies
ก่อน update service สามารถตรวจสอบได้ว่ามี services อื่นที่ใช้งานอยู่หรือไม่
# ค้นหา services ที่ขึ้นต่อกับ user-api
query:
filters:
- kind: component
- relations: dependsOn
target: component:default/user-api
Use Case 3: สร้าง Microservice ใหม่
Developer สามารถสร้าง microservice ใหม่ได้ใน 5 นาที แทนที่จะใช้เวลา 2 ชั่วโมง
สิ่งที่ได้:
- ✓ GitHub repository พร้อมโค้ด template
- ✓ CI/CD pipeline (GitHub Actions)
- ✓ Kubernetes deployment manifests
- ✓ Dockerfile
- ✓ Documentation skeleton
- ✓ ลงทะเบียนใน Software Catalog อัตโนมัติ
10. แก้ไขปัญหาที่พบบ่อย
ปัญหา: Database connection failed
Error: connect ECONNREFUSED 127.0.0.1:5432
แก้ไข: ตรวจสอบ environment variables และ database connection string ใน app-config.yaml
ปัญหา: Entities ไม่แสดงใน Catalog
Catalog: No entities found matching query
แก้ไข: ตรวจสอบ catalog-info.yaml location และ GitHub token permissions
# ตรวจสอบ catalog locations
yarn backstage-cli catalog inspect --entity <entity-ref>
ปัญหา: GitHub OAuth authentication failed
แก้ไข: ตรวจสอบ GitHub OAuth App settings และ callback URL
# app-config.yaml
auth:
environment: development
providers:
github:
development:
clientId: ${GITHUB_CLIENT_ID}
clientSecret: ${GITHUB_CLIENT_SECRET}
callbackUrl: http://localhost:3000/api/auth/github/handler/frame
ปัญหา: Plugin ไม่โหลด
แก้ไข: ลอง clear cache และ reinstall dependencies
# Clear cache และ reinstall
rm -rf node_modules packages/*/node_modules
yarn cache clean
yarn install
สรุป
Backstage.io เป็นเครื่องมือที่ช่วยให้องค์กรสามารถสร้าง Developer Portal หรือ Internal Developer Platform (IDP) ได้อย่างมีประสิทธิภาพ ด้วยฟีเจอร์หลัก:
- Software Catalog - รวบรวมข้อมูลทุกบริการในที่เดียว
- Software Templates - สร้างโปรเจคใหม่อย่างรวดเร็ว
- TechDocs - เอกสาร Docs-as-Code
- Plugins - ขยายความสามารถได้ไม่จำกัด
สำหรับองค์กรที่ต้องการเพิ่ม Developer Experience และลดเวลา onboarding Backstage เป็นตัวเลือกที่คุ้มค่าที่สุดในปี 2025-2026