Ứng dụng Go

Cài bộ công cụ Go, deploy dịch vụ Go từ Git với lệnh build và chạy tự động, lắng nghe trên PORT, đặt biến môi trường và xử lý lỗi thường gặp.

Cập nhật 09/10/2026 · 5 phút đọc

Ứng dụng Go chạy trên ZoPanel như một ứng dụng server: ZoPanel biên dịch từ mã nguồn bằng bộ công cụ Go chính thức, chạy file thực thi như một dịch vụ của tài khoản hosting phía sau nginx và phát hành bản mới không gián đoạn. Trang này dành cho dịch vụ HTTP và API viết bằng Go; cơ chế chung (cổng, phát hành blue/green, log) được mô tả trong Ứng dụng Node.js và Python.

Cài Go lên máy chủ

Quản trị viên cài Go một lần:

1. Mở Runtime.
2. Trong thẻ Go ("Bộ công cụ Go chính thức."), bấm Cài bản mới nhất.

ZoPanel tải bản ổn định mới nhất cho kiến trúc của máy chủ (amd64 hoặc arm64) từ go.dev, kiểm tra checksum SHA-256 và cài vào /opt/zopanel/runtimes/go/<major.minor>, ví dụ 1.25. Cài lại về sau sẽ thêm phiên bản minor mới bên cạnh bản cũ. Gỡ một phiên bản bằng biểu tượng thùng rác trên nhãn của nó.

Chọn phiên bản: mỗi lần deploy dùng phiên bản đã cài khớp với dòng go trong go.mod (go 1.24 → 1.24), nếu không có thì dùng bản mới nhất đã cài. Khi go.mod yêu cầu Go mới hơn bản đang dùng, Go 1.21 trở lên tự tải toolchain cần thiết trong lúc build (Go toolchains); cài bản mới nhất sẽ tránh được bước tải này.

Chuẩn bị ứng dụng

Chương trình phải lắng nghe tại 127.0.0.1 trên cổng trong biến môi trường PORT. ZoPanel đặt PORT (và HOST=127.0.0.1) cho mỗi bản release; slot blue/green thứ hai dùng cổng khác, vì vậy đừng bao giờ ghi cứng cổng.

package main

import (
	"net/http"
	"os"
)

func main() {
	mux := http.NewServeMux()
	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("Hello from Go"))
	})
	http.ListenAndServe("127.0.0.1:"+os.Getenv("PORT"), mux)
}

nginx xử lý SSL và chuyển mọi request tới ứng dụng kèm các header Host, X-Real-IP, X-Forwarded-For và X-Forwarded-Proto. Hãy lấy địa chỉ khách từ X-Forwarded-For hoặc X-Real-IP, không lấy từ r.RemoteAddr vì giá trị này luôn là 127.0.0.1.

Deploy

1. Ở Website → Thêm website, chọn Git deploy, nhập Địa chỉ repository, Nhánh (và Thư mục gốc nếu go.mod nằm trong thư mục con) rồi bấm Tạo website. Với website có sẵn, dùng tab Deploy.
2. ZoPanel nhận diện Go qua file go.mod và build bản release đầu tiên.
3. Khai báo cấu hình trong Biến môi trường rồi bấm Lưu & deploy lại.

Bạn cũng có thể tải mã nguồn lên domains/<tên-miền>/source và chọn Nguồn là File đã tải lên (Quản lý file) (xem Git deploy).

Lệnh build và chạy được nhận diện

• <tên> là phần cuối của đường dẫn module trong go.mod (github.com/acme/api → api), hoặc app.
• Lệnh cài đặt là go mod download.
• Khi có nhiều lệnh trong cmd/, log deploy ghi "Multiple commands found in cmd/, starting …". Muốn chạy lệnh khác, tắt Tự nhận diện rồi sửa Lệnh chạy, ví dụ ./bin/server.
• bin/ được thêm vào PATH khi ứng dụng khởi động, nên dòng Procfile như web: api vẫn chạy được. Dòng web: trong Procfile luôn được dùng làm lệnh chạy.

Muốn đổi lệnh nào, tắt Tự nhận diện trong thẻ Build & chạy, sửa rồi bấm Lưu & deploy. Nối nhiều bước build bằng && trên một dòng, ví dụ go generate ./... && CGO_ENABLED=0 go build -o bin/api ..

Môi trường build

• Build chạy dưới quyền tài khoản hosting, trong giới hạn CPU và RAM của tài khoản, tối đa 30 phút cho lệnh cài đặt và 30 phút cho lệnh build.
• Module cache (GOPATH) và build cache (GOCACHE) nằm trong thư mục home của tài khoản và được giữ giữa các lần deploy, nên các lần build sau nhanh hơn.
• CGO_ENABLED=0 tạo file thực thi tĩnh. Package cần cgo (ví dụ github.com/mattn/go-sqlite3) phải dùng CGO_ENABLED=1 và cần trình biên dịch C trên máy chủ; nên chọn bản thuần Go như modernc.org/sqlite.

Biến môi trường

Đặt cấu hình và thông tin bí mật trong Biến môi trường ở tab Deploy. Các biến dùng được khi build và khi chạy; Dán .env thêm nhiều biến một lúc (tối đa 200 biến, giá trị trên một dòng). Thành viên chỉ có quyền xem không thấy được giá trị.

Ví dụ với database MariaDB tạo ở Cơ sở dữ liệu:

DATABASE_URL=alice_api:mat-khau@tcp(127.0.0.1:3306)/alice_api?parseTime=true

Định dạng chuỗi kết nối tuỳ driver bạn dùng; host là 127.0.0.1 (xem Cơ sở dữ liệu).

File cần giữ lại giữa các bản release, như thư mục upload hay database SQLite, hãy đưa vào Đường dẫn lưu trữ cố định (ví dụ data). Mọi thứ khác trong thư mục release được thay mới ở mỗi lần deploy.

Release, log và khởi động lại

• Bản mới khởi động ở slot đang rảnh và phải trả lời Đường dẫn health check (mặc định /) với mã dưới 500 trong vòng 90 giây. Chỉ khi đó nginx mới chuyển sang bản mới và tiến trình cũ mới dừng. Nếu chương trình thoát hoặc không trả lời, bản đang chạy được giữ nguyên.
• Các bản release giữ 5 bản build gần nhất để Rollback.
• Log ứng dụng trong tab Deploy hiển thị 400 dòng cuối chương trình ghi ra stdout và stderr; bật Trực tiếp để theo dõi. Hãy ghi log ra stdout thay vì ra file.
• Dịch vụ tự khởi động lại khi tiến trình thoát. Hãy dừng chương trình gọn gàng khi nhận SIGTERM: khi phát hành, tiến trình cũ có 20 giây trước khi bị buộc dừng.

RAM, CPU và số tiến trình được tính vào gói của tài khoản (xem Gói và giới hạn).

Xử lý sự cố

Xem thêm

• Ứng dụng Node.js và Python
• Git deploy
• Cơ sở dữ liệu
• Gói và giới hạn
• Tài liệu Go