ApexHuasคู่มือช่างเว็บ GitHub repo

ภาคผนวก — คำสั่ง ศัพท์ และปัญหาที่เจอบ่อย

หน้านี้ไว้เปิดค้างตอนทำงานจริง ไม่ต้องอ่านจบในรอบเดียว

วงจรทำงานประจำวันแบบย่อ (สรุปทั้งเล่มใน 6 ขั้น)

1. ดึงของล่าสุด + แตก branch

git checkout develop && git pull
git checkout -b feat/ชื่องาน
1 / 6

คำสั่งประจำวัน

# ---- เริ่มงานใหม่ ----
git checkout develop && git pull          # ไปที่เส้นหลัก + ดึงของล่าสุด
git checkout -b feat/ชื่องาน               # แตก branch ใหม่

# ---- ระหว่างทำงาน ----
git status                                # แก้อะไรไปบ้าง
git diff                                  # ดูรายละเอียดที่แก้ทีละบรรทัด
git add . && git commit -m "ข้อความ"      # บันทึกงาน
npm run dev                               # เปิดเว็บในเครื่อง (localhost:3000)

# ---- ตรวจก่อนส่ง ----
npx tsc --noEmit && npm run lint && npm run build

# ---- ส่งงาน ----
git push -u origin feat/ชื่องาน
gh pr create --base develop --title "..." --body "..."
gh pr checks --watch                      # ดู CI แบบเรียลไทม์
gh pr merge <เลข> --merge --delete-branch

# ---- ปล่อยขึ้นเว็บจริง ----
gh pr create --base uat --head develop --title "Promote: ..."
gh run list --branch uat --limit 2        # ดูสถานะ deploy

# ---- ดู server ----
ssh -i ~/.ssh/google_compute_engine [email protected]
sudo docker compose -f ~/apexhuas/compose.yaml ps       # อะไรรันอยู่
sudo docker compose -f ~/apexhuas/compose.yaml logs --tail=50 app
df -h /                                   # ดิสก์เหลือเท่าไหร่

ศัพท์ทั้งหมดในเล่มนี้

คำ ความหมายสั้นที่สุด
repo โฟลเดอร์โปรเจกต์ + ประวัติการแก้ทั้งหมด
commit บันทึกงานหนึ่งครั้ง พร้อมข้อความอธิบาย
branch เส้นทางงานแยก ทำพังก็ไม่กระทบเส้นหลัก
merge รวมงานจาก branch หนึ่งเข้าอีก branch
PR (pull request) คำขอรวมงาน = จุดรีวิว + จุดที่ CI ตรวจ
conflict สองคนแก้ที่เดียวกัน ต้องเลือกด้วยมือว่าเอาแบบไหน
CI ระบบตรวจโค้ดอัตโนมัติทุก PR
CD ระบบส่งของขึ้น server อัตโนมัติหลัง merge
GitHub Actions บริการ CI/CD ของ GitHub สั่งงานผ่านไฟล์ YAML
workflow ไฟล์สั่งงาน 1 ไฟล์ใน .github/workflows/
typecheck ตรวจชนิดข้อมูล (TypeScript) จับบั๊กก่อนรัน
lint ตรวจแพทเทิร์นการเขียนที่เสี่ยงพัง
Docker image เว็บ+ทุกอย่างที่ใช้รัน ห่อเป็นก้อนเดียว (แม่พิมพ์)
container image ที่กำลังรันอยู่ (ของจริงที่ทำงาน)
Dockerfile สูตรว่าห่อ image ยังไง
compose.yaml รายการว่าระบบนี้มี container อะไรบ้าง
registry / GHCR โกดังฝาก image ให้ server มาดึง
tag (:uat) ป้ายชื่อเวอร์ชันของ image
VM เครื่องคอมพิวเตอร์เช่าบน cloud
SSH วิธีเข้าไปสั่งงานเครื่องระยะไกลอย่างปลอดภัย
DNS / A record ระบบแปลงชื่อเว็บเป็นเลข IP
subdomain ชื่อย่อยหน้าโดเมน เช่น learn.
reverse proxy ด่านหน้ารับ request แล้วส่งต่อให้เว็บข้างใน (Caddy)
TLS / HTTPS การเข้ารหัสระหว่างเบราว์เซอร์กับ server
Let's Encrypt ผู้ออกใบรับรอง HTTPS ฟรี (Caddy ขอให้อัตโนมัติ)
health check ยิงเข้าเว็บจริงหลัง deploy เช็คว่ายังหายใจ
rollback ย้อนกลับเวอร์ชันก่อนหน้าเมื่อของใหม่พัง
secret ค่าลับ (กุญแจ/รหัส) เก็บใน GitHub Secrets ห้ามอยู่ในโค้ด
.env ไฟล์ค่าลับในเครื่อง ห้ามขึ้น repo
mock ข้อมูลปลอมไว้สร้าง UI ก่อนต่อระบบจริง
ADR บันทึกการตัดสินใจเชิงเทคนิค 1 ไฟล์/1 เรื่อง
AGENTS.md ไฟล์กติกาที่ AI (และคน) อ่านก่อนทำงานทุกครั้ง

ปัญหาที่เจอบ่อย

อาการ ทางแก้
npm run dev ไม่ขึ้น / error แปลก ลอง rm -rf node_modules .next && npm install แล้วรันใหม่ — ล้างของค้าง
CI แดงที่ typecheck แต่เครื่องเราผ่าน rm -rf .next && npx next typegen && npx tsc --noEmit ทำเครื่องให้สะอาดเหมือน CI
CI แดงที่ npm ci (lock file out of sync) rm -rf node_modules package-lock.json && npm install แล้ว commit lock ใหม่
push ไม่ขึ้น rejected git pull มารวมก่อน แล้ว push ใหม่
PR ขึ้น conflict git pull origin develop ใน branch ตัวเอง แก้จุดชน commit แล้ว push
เผลอ commit ใส่ develop (ยังไม่ push) git branch feat/กู้งาน แล้ว git reset --hard origin/develop
เผลอ commit ไฟล์ลับ ถือว่ารั่วแล้ว — เปลี่ยนรหัส/กุญแจจริงทันที แล้วค่อยลบออกจากประวัติ
เว็บ uat ไม่อัปเดตหลัง merge เปิดแท็บ Actions ดูว่า workflow แดงตรงไหน อ่าน log ด่านที่ล้ม
เว็บจริงล่ม ย้อนเวอร์ชัน (บทที่ 11) ให้ฟื้นก่อน แล้วค่อยหาสาเหตุจาก log
SSH เข้า server ไม่ได้ เช็คว่าใช้ key ถูกไฟล์ (-i ~/.ssh/...) และ IP ถูกต้อง

แผนที่เอกสารของ repo

อยากรู้เรื่องอะไร เปิดไฟล์ไหน (คลิกดู)

กติกา

ตัวระบบ

การทำงาน

คลิกกล่องด้านบนเพื่อดูคำอธิบาย

ลิงก์ของจริง

จบคู่มือ — ถ้าเจอจุดที่อธิบายไม่ชัดหรืออยากเพิ่มบท แก้ไฟล์ใน docs/learning/ แล้วเปิด PR ได้เลย ถือเป็นการฝึกครบวงจรไปในตัว