Gitea

Cài Gitea từ Kho ứng dụng, hoàn tất Initial Configuration sau khoá thiết lập, clone và push qua HTTPS, sao lưu repository và cập nhật Gitea.

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

Gitea là dịch vụ Git tự host, gọn nhẹ, tương tự GitHub hay GitLab: repository riêng tư và công khai, issue, pull request, wiki, release và kho package, có giao diện web. Hãy chọn Gitea khi một nhóm hoặc lập trình viên cá nhân muốn tự quản lý nơi lưu mã nguồn mà không trả phí theo người dùng. Trang này hướng dẫn cài Gitea từ Kho ứng dụng, cấu hình lần đầu, cách clone và push với container của ZoPanel, sao lưu và cập nhật.

Yêu cầu

Repository được lưu trên đĩa của máy chủ, ngoài thư mục home của tài khoản hosting, nên không tính vào quota đĩa của tài khoản. Hãy theo dõi dung lượng trống.

Cài Gitea

Với quản trị viên

1. Mở Kho ứng dụng. Nếu thấy Cần cài Docker, bấm Cài Docker trước.

2. Trên thẻ Gitea, bấm Cài đặt.

3. Điền hộp thoại:

   Trường	Nội dung
   Tên miền	Tên miền ứng dụng chạy, không gồm http://. Hệ thống tạo một website mới cho tên miền này.
   Chủ sở hữu	Tài khoản hosting sở hữu ứng dụng. Giới hạn của gói tài khoản áp dụng cho container.
   SSL miễn phí (Let's Encrypt)	Để bật. Chứng chỉ được cấp ở cuối quá trình cài nếu tên miền đã trỏ về máy chủ.

4. Bấm Cài đặt và theo dõi log tác vụ tới dòng Gitea is available at http://<tên miền>.

5. Nếu log báo SSL could not be issued yet, trỏ tên miền về máy chủ rồi bấm Cấp chứng chỉ trong tab SSL của website.

Gitea không có trường cài đặt bổ sung. ZoPanel đặt các biến sau, Gitea ghi chúng vào app.ini mỗi lần khởi động:

Với khách hàng

Khách tự cài từ Kho ứng dụng trong panel của mình khi gói cho phép. Gitea cần 512 MB trong RAM (MB) của gói và một suất trong Gói hosting → Ứng dụng Docker. Xem Gói hosting và giới hạn.

Thiết lập lần đầu

Bản cài mới nằm sau khoá thiết lập: khi Gitea chưa được cấu hình, người truy cập đầu tiên có thể tạo tài khoản quản trị, nên ZoPanel hiển thị trang "đang được thiết lập" cho mọi người khác tới khi bạn làm xong.

Giao diện Gitea không có bản tiếng Việt; tên mục bên dưới giữ nguyên tiếng Anh.

1. Mở website và vào tab Docker. Chờ trạng thái là running.
2. Trong thẻ Đang khoá thiết lập, bấm Mở ứng dụng (chỉ mình tôi). Trang Initial Configuration mở ra.
3. Database Settings đã điền sẵn SQLite3. Giữ nguyên.
4. Trong General Settings, đặt Site Title. Kiểm tra Server Domain là tên miền của bạn và Gitea Website URL là https://<tên miền>/.
5. SSH Server Port: không cần thay đổi. ZoPanel đã tắt SSH server của Gitea, nên Gitea chỉ hiển thị URL clone HTTPS.
6. Tuỳ chọn, trong Email Settings: nhập máy chủ SMTP để Gitea gửi thông báo và email đặt lại mật khẩu. Hộp mail tạo trên panel dùng được: SMTP Host = tên máy chủ mail của bạn, SMTP Port 587 hoặc 465, Send Email As, SMTP Username (địa chỉ đầy đủ) và SMTP Password.
7. Trong Server and Third-Party Service Settings, tích Only administrators can create user accounts (no self-registration) trừ khi bạn muốn cho đăng ký công khai. Tích Require sign-in to view pages nếu dùng nội bộ.
8. Trong Administrator Account Settings, nhập Administrator Username, Email Address, Password và Confirm Password.
9. Bấm Install Gitea. Gitea ghi cấu hình và đăng nhập cho bạn.
10. Quay lại tab Docker, bấm Đã thiết lập xong — mở công khai.

Thiết lập cần thiết

• Xác thực hai lớp: ảnh đại diện → Settings → Security → Two-Factor Authentication (TOTP).
• Người dùng: Site Administration → User Accounts để tạo tài khoản khi đã tắt tự đăng ký.
• Access token: Settings → Applications → Generate New Token. Khi bật xác thực hai lớp, Git qua HTTPS cần token thay cho mật khẩu.
• Để đổi thiết lập không có trên giao diện web, sửa /var/lib/zopanel-apps/<instance>/data/gitea/conf/app.ini bằng root rồi bấm Khởi động lại trong tab Docker. Bốn biến ở trên được áp lại mỗi lần khởi động và ghi đè các khoá tương ứng trong app.ini.

Clone và push

Dùng HTTPS:

git clone https://git.example.com/alice/website.git

Git hỏi tên người dùng và mật khẩu Gitea (hoặc access token). Để khỏi nhập mỗi lần, dùng credential helper, ví dụ git config --global credential.helper store trên máy riêng.

Các giới hạn cần biết:

• Không dùng được SSH. Cổng 22 của máy chủ là dịch vụ SSH của chính máy chủ, không phải của Gitea, nên ZoPanel tắt SSH server của Gitea và URL clone dùng HTTPS. Gitea cài trước khi ZoPanel có thiết lập này vẫn giữ thiết lập cũ cho tới khi cài lại (Cập nhật bản mới dùng lại thiết lập lúc cài); nếu giao diện hiện URL clone SSH, đặt DISABLE_SSH = true trong mục [server] của app.ini rồi khởi động lại để ẩn chúng.
• Mỗi lần push bị giới hạn bởi dung lượng upload của website (mặc định 256 MB). Lần push lớn hơn sẽ lỗi HTTP 413. Khi cần push lớn, tăng Upload tối đa (MB) trong tab Công cụ → thẻ Dung lượng upload của website Gitea (tối đa 10 GB). Hoặc push lịch sử lớn thành nhiều lần (ví dụ từng nhánh hoặc từng khoảng commit), và giữ file nhị phân lớn trong Git LFS với mỗi file nhỏ hơn mức đó.

Container kết nối được tới đâu

Với Gitea, điều này nghĩa là:

• Migrate Repository và pull mirror từ GitHub, GitLab hay máy chủ công khai khác hoạt động bình thường.
• Webhook tới URL công khai, kể cả website của bạn trên máy chủ này qua tên miền, hoạt động. Webhook tới địa chỉ nội bộ sẽ lỗi.
• Gitea Actions cần một runner riêng (act_runner) có Docker của nó. ZoPanel không cung cấp runner; runner trên máy khác có thể kết nối tới Gitea qua HTTPS.

Dữ liệu nằm ở đâu và sao lưu

Dữ liệu ứng dụng nằm trong /var/lib/zopanel-apps/<instance>/, với <instance> là tên miền đổi dấu chấm thành gạch ngang (git.example.com → git-example-com). Container có tên zp-app-<instance>.

ZoPanel sao lưu gì và không sao lưu gì: thẻ Sao lưu trong tab Docker của website sao lưu toàn bộ thư mục ứng dụng. Bản sao lưu tài khoản và sao lưu gia tăng gồm thư mục website, database và hộp mail của tài khoản. Chúng không gồm /var/lib/zopanel-apps, nên repository và issue chỉ nằm trong bản sao lưu riêng của ứng dụng. Bản sao lưu cấu hình (.zpb) chỉ chứa bản ghi của panel về ứng dụng, không chứa dữ liệu của nó.

Để sao lưu Gitea, bấm Sao lưu ngay trong thẻ Sao lưu ở tab Docker của website. Quản trị viên còn đặt được Lịch (Tắt, Mỗi ngày hoặc Mỗi tuần; mặc định tắt) và số bản Giữ lại (1–60, mặc định 7), rồi bấm Lưu. Mỗi bản sao lưu nén /var/lib/zopanel-apps/<instance>/ thành /var/backups/zopanel-apps/<instance>/YYYYMMDD-HHMMSS.tar.gz, trong thư mục chỉ root đọc được và không tính vào dung lượng đĩa của tài khoản. Container được tạm dừng (pause, không phải stop) trong vài giây sao chép, nên database SQLite và repository nhất quán. Các bản cũ vượt quá số Giữ lại bị xoá, và khi một lần sao lưu theo lịch thất bại, quản trị viên nhận cảnh báo Sao lưu thất bại.

Để khôi phục, quản trị viên bấm Khôi phục cạnh một bản sao lưu. Gitea được dừng và dữ liệu được thay bằng nội dung file nén; dữ liệu hiện tại được giữ riêng tới khi ứng dụng khôi phục khởi động được, và được đặt lại nếu nó không khởi động. Mọi thay đổi sau thời điểm sao lưu sẽ mất. Mỗi bản sao lưu còn có nút xoá (chỉ quản trị viên), và xoá ứng dụng kèm file của nó cũng xoá luôn các bản sao lưu. Khách hàng có thể bấm Sao lưu ngay và xem danh sách; việc đặt lịch và khôi phục do nhà cung cấp thực hiện.

Các file nén vẫn ở trên cùng máy chủ. Hãy chép những bản quan trọng ra ngoài (ví dụ bằng scp hoặc rclone từ /var/backups/zopanel-apps/<instance>/) và lưu ở dạng mã hoá, vì chúng chứa database và các bí mật của Gitea. Để khôi phục trên máy chủ khác, cài Gitea với cùng tên miền ở đó, chép file nén vào /var/backups/zopanel-apps/<instance>/ trên máy chủ mới rồi bấm Khôi phục trong thẻ Sao lưu của nó.

Bản lưu trữ di động bằng lệnh gitea dump của Gitea (database dạng SQL, repository, dữ liệu và cấu hình):

docker exec -u git zp-app-git-example-com /usr/local/bin/gitea dump -c /data/gitea/conf/app.ini --file /tmp/gitea-dump.zip
docker cp zp-app-git-example-com:/tmp/gitea-dump.zip /root/gitea-dump-$(date +%F).zip
docker exec zp-app-git-example-com rm /tmp/gitea-dump.zip

Tài liệu Gitea khuyên tạm ngừng hoạt động khi dump để có kết quả nhất quán hoàn toàn; hãy chạy lúc ít người dùng. Mỗi bản clone cũng là bản sao đầy đủ lịch sử của repository, nhưng không gồm issue, pull request hay dữ liệu wiki trên Gitea.

Cập nhật Gitea

1. Sao lưu trước (Sao lưu ngay trong thẻ Sao lưu). Gitea chuyển đổi database khi khởi động; không hỗ trợ quay về phiên bản cũ.
2. Trong tab Docker, bấm Cập nhật bản mới (chỉ quản trị viên; khách hàng nhờ nhà cung cấp).
3. Tác vụ kéo image trong danh mục và tạo lại container. Repository và thiết lập được giữ.

Tag 28 của danh mục đi theo dòng 28.x của Gitea, nên Cập nhật bản mới mang về bản 28.x mới nhất. Phiên bản lớn tiếp theo sẽ đến cùng bản cập nhật ZoPanel.

Xử lý sự cố

Xem thêm

• Kho ứng dụng và lưu trữ S3
• Từng ứng dụng dùng để làm gì
• Git deploy
• Gói hosting và giới hạn
• Tài liệu Gitea, Sao lưu và khôi phục và bảng tham chiếu cấu hình