Tự động triển khai

Cách hoạt động của tự động triển khai

Tự động triển khai sẽ triển khai lại một ứng dụng GitHub mỗi khi GitHub gửi push event cho nhánh mà ứng dụng theo dõi. Server Compass cài đặt một gateway luôn hoạt động và một deployment worker riêng tư trên máy chủ của bạn, tạo webhook cho repository, xác minh signed test delivery của GitHub, và đưa đúng commit đó vào hàng đợi để triển khai.

Sau khi thiết lập, ứng dụng desktop Server Compass không cần phải luôn mở. Runtime phía máy chủ khởi động lại cùng Docker và tiếp tục nhận webhook, build ứng dụng và ghi lại lịch sử triển khai. Cổng SSH của bạn có thể vẫn ở chế độ riêng tư; chỉ hostname của webhook mới cần được GitHub tiếp cận qua HTTPS.

Yêu cầu

Trước khi bắt đầu, hãy xác nhận rằng bạn có:

• Một ứng dụng Docker đã được triển khai từ một repository GitHub
• Build on VPS được chọn làm vị trí build; các bản build bằng GitHub Actions không được webhook Auto Deploy v1 hỗ trợ
• Một bản Git checkout được quản lý bên trong thư mục Server Compass của ứng dụng
• Một tài khoản GitHub đã liên kết và có quyền tạo webhook cho repository
• Docker Engine và Docker Compose trên máy chủ
• Một hostname HTTPS công khai riêng, ví dụ deploy.example.com
• Một tuyến đường từ hostname đó tới webhook gateway

Tự động triển khai đi theo nhánh được lưu trên ứng dụng đã triển khai. Mỗi lần push lên đúng nhánh đó sẽ đưa commit có trong event GitHub vào hàng đợi; các lần push lên nhánh khác sẽ bị bỏ qua.

Thiết lập ứng dụng

1. Trong Server Compass, triển khai repository dưới dạng một ứng dụng GitHub.
2. Chọn Build on VPS trong quá trình triển khai.
3. Mở ứng dụng đã triển khai và vào Deployments.
4. Tìm thẻ Tự động triển khai và nhấp Set up Auto Deploy.
5. Nhập một hostname webhook công khai. Chỉ dùng hostname hoặc HTTPS origin, ví dụ deploy.example.com hoặc https://deploy.example.com. Đừng thêm path, query string hay cổng tùy chỉnh.

Hostname là cửa vào công khai cho GitHub. Chỉ một tên miền thôi là chưa đủ: DNS, TLS, các quy tắc firewall hoặc NAT, và proxy hoặc tunnel của bạn phải tạo thành một tuyến đường hoàn chỉnh tới gateway trên máy chủ.

Chọn cách GitHub tiếp cận máy chủ

Cả ba lựa chọn tuyến đường đều dùng cùng một signed webhook và deployment worker riêng tư. Chỉ tuyến đường công khai là khác nhau.

Server Compass-managed Traefik

Dùng lựa chọn này khi Server Compass-managed Traefik đã là reverse proxy công khai trên máy chủ. Trỏ bản ghi DNS của hostname tới máy chủ và đảm bảo các cổng inbound 80 và 443 tiếp cận được nó. Server Compass gắn webhook gateway vào mạng Docker traefik-public hiện có và cấu hình tuyến host HTTPS.

Đây thường là lựa chọn đơn giản nhất cho một VPS công khai. Nó cũng có thể hoạt động với máy chủ LAN khi router chuyển tiếp cổng 80 và 443 tới máy chủ đó và hostname phân giải về IP công khai của router.

Existing reverse proxy

Dùng lựa chọn này khi Nginx, Caddy, Traefik, HAProxy hoặc một proxy khác đã xử lý hostname. Nhấp Check server để lấy loopback target được tạo, rồi định tuyến hostname webhook tới địa chỉ được hiển thị, ví dụ http://127.0.0.1:42315.

Proxy phải giữ nguyên raw request body và các header webhook của GitHub để gateway có thể xác minh HMAC signature. Đừng đặt login middleware, Cloudflare Access hay một trang xác thực tương tác khác trước tuyến đường này.

Nếu proxy chạy trong Docker, hãy nhớ rằng 127.0.0.1 bên trong container proxy trỏ tới chính container đó. Thay vào đó hãy dùng host networking, một địa chỉ host-gateway, hoặc một mạng Docker dùng chung phù hợp.

Stable tunnel

Dùng lựa chọn này cho máy chủ LAN, VPS riêng tư, kết nối CGNAT, hoặc bất kỳ máy chủ nào mà bạn không muốn mở cổng inbound. Tạo một named Cloudflare Tunnel bền bỉ hoặc một tunnel tương đương, chạy connector của nó trên máy chủ, và ánh xạ hostname công khai tới loopback target được Check server hiển thị, chẳng hạn http://127.0.0.1:42315.

Tunnel phải ổn định và tự khởi động sau khi reboot. Một Quick Tunnel tạm thời hoặc một URL ngrok thay đổi khi khởi động lại là không phù hợp vì GitHub lưu URL của webhook. Nếu connector chạy trong Docker, hãy cấp cho nó host networking hoặc một tuyến đường khác thực sự có thể tiếp cận gateway trên host.

Kiểm tra máy chủ và kích hoạt

1. Nhấp Check server.
2. Xác nhận rằng Docker Engine, Docker Compose và cổng gateway được đề xuất vượt qua kiểm tra mức độ sẵn sàng.
3. Nếu bạn đã chọn managed Traefik, hãy xác nhận rằng mạng traefik-public cũng vượt qua.
4. Nếu bạn đã chọn proxy hiện có hoặc stable tunnel, hãy hoàn tất tuyến đường bên ngoài tới đúng cổng loopback được hiển thị trong kết quả.
5. Nhấp Activate Auto Deploy.

Server Compass cài đặt gateway và worker, tạo một URL webhook riêng tư, lưu signing secret trên máy chủ, tạo webhook trong GitHub, gửi một ping GitHub, và chờ một signed delivery thành công. Trạng thái tiến qua Installed, Routed, Hooked, Verified, và Active.

Nếu quá trình thiết lập dừng ở Awaiting route, runtime đã được cài đặt nhưng GitHub chưa thể tiếp cận nó. Hãy hoàn tất hoặc sửa tuyến đường DNS, TLS, firewall/NAT, proxy hoặc tunnel, rồi nhấp Continue setup. Bạn không cần cài đặt lại ứng dụng.

Xác minh tự động triển khai

Trước tiên hãy xác nhận rằng health endpoint công khai tiếp cận được gateway của Server Compass:

curl -fsS https://deploy.example.com/healthz

Sau đó xác minh toàn bộ luồng triển khai:

1. Trong GitHub, mở repository và vào Settings > Webhooks.
2. Mở webhook do Server Compass tạo và xác nhận rằng lần delivery gần nhất trả về phản hồi 2xx.
3. Push một commit nhỏ lên nhánh được theo dõi.
4. Trong Server Compass, mở lịch sử triển khai của ứng dụng và xác nhận rằng job webhook đã dùng commit vừa push.
5. Xác nhận rằng ứng dụng đã triển khai chứa thay đổi đó.

Với bài kiểm tra cuối cùng, hãy thoát hoàn toàn Server Compass, push thêm một commit lên nhánh được theo dõi, và xác minh lại ứng dụng. Việc triển khai vẫn sẽ hoàn tất vì gateway, hàng đợi và worker chạy trên máy chủ.

Quản lý một webhook đang hoạt động

Thẻ Tự động triển khai cung cấp các thao tác sau:

• Test webhook gửi thêm một test delivery của GitHub và làm mới trạng thái của nó.
• Rotate secret thay thế signing secret ở cả trên máy chủ lẫn trên webhook GitHub.
• Pause giữ lại target và lịch sử nhưng dừng các lần triển khai tự động; Resume bật lại chúng.
• Remove xóa webhook GitHub và remote target policy của nó trong khi vẫn giữ lịch sử triển khai.

Để thay đổi repository hoặc nhánh được theo dõi, hãy Remove tự động triển khai trước, cập nhật và triển khai lại ứng dụng với repository hoặc nhánh mới, rồi thiết lập lại tự động triển khai.

Khắc phục sự cố và bảo mật

• Health endpoint thất bại hoặc trả về 502/404: hãy xác minh DNS và TLS, xác nhận rằng proxy hoặc tunnel trỏ tới cổng loopback hiện tại, và đảm bảo container gateway đang chạy.
• Delivery của GitHub không phải 2xx: hãy kiểm tra lần delivery gần đây của webhook, xác nhận rằng không có lớp xác thực nào chặn GitHub, và đảm bảo proxy không thay đổi raw body hoặc gỡ bỏ các header của GitHub.
• Push không triển khai: hãy xác nhận rằng tự động triển khai đang ở trạng thái Active, không phải Paused, và rằng lần push được thực hiện lên đúng nhánh được theo dõi.
• Tunnel hoạt động cho tới khi reboot: hãy cấu hình named tunnel connector như một system service hoặc một container có thể khởi động lại. Đừng dùng một URL tạm thời.
• Desktop đã đóng và việc triển khai thất bại: hãy kiểm tra rằng máy chủ đang trực tuyến và các container gateway và worker của Server Compass đang chạy.

URL webhook chứa một private route token và không nên công bố. Các lần delivery của GitHub được xác thực bằng một HMAC signing secret được tạo và lưu trên máy chủ và không bao giờ hiển thị trong UI. Bạn không cần phơi bày SSH, Docker socket, hay worker riêng tư ra internet.