# 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.

Source: https://zopanel.net/vi/docs/app-gitea  
Updated: 2026-10-09

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

| Mục | Giá trị |
| --- | --- |
| Image | `gitea/gitea:28` |
| Giới hạn RAM | 512 MB, 1 CPU |
| Đĩa trống để cài | Khoảng 1,3 GB trên ổ của Docker ở lần cài đầu (image cộng 1 GB chừa lại cho máy chủ), cộng thêm chỗ cho repository |
| Docker | Đã cài trên máy chủ (**Kho ứng dụng → Cài Docker**) |
| Tên miền | Tên miền hoặc tên miền phụ có bản ghi A trỏ về máy chủ, ví dụ `git.example.com` |

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:

| Biến | Giá trị | Tác dụng |
| --- | --- | --- |
| `GITEA__server__ROOT_URL` | `https://<tên miền>/` | Địa chỉ công khai dùng cho link và URL clone HTTPS |
| `GITEA__server__DOMAIN` | tên miền của bạn | Tên miền máy chủ |
| `GITEA__server__DISABLE_SSH` | `true` | Tắt SSH server của Gitea, nên chỉ hiển thị URL clone HTTPS (xem mục Clone và push) |
| `GITEA__database__DB_TYPE` | `sqlite3` | Gitea dùng database SQLite tích hợp sẵn |

### 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](/vi/docs/packages-limits).

## 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:

```bash
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

| Đích | Được phép? |
| --- | --- |
| Máy chủ Git và API trên internet (migrate, mirror, webhook) | Có |
| Website trên máy chủ này qua tên miền công khai (80/443) | Có |
| Mail trên máy chủ này (25, 465, 587) | Có |
| MariaDB, PostgreSQL, Redis, SSH hoặc panel trên máy chủ này | **Không** |
| Mạng nội bộ (10.x, 172.16–31.x, 192.168.x, 100.64.x), loopback | **Không** |

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>`.

| Đường dẫn trên máy chủ | Nội dung |
| --- | --- |
| `…/<instance>/data/git/repositories/` | Các repository Git (bare) |
| `…/<instance>/data/gitea/gitea.db` | Database SQLite: người dùng, issue, pull request, thiết lập |
| `…/<instance>/data/gitea/conf/app.ini` | Cấu hình của Gitea |
| `…/<instance>/data/` (phần còn lại) | File đính kèm, avatar, object LFS, package |

**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):

```bash
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](/vi/docs/updating).

## Xử lý sự cố

| Hiện tượng hoặc thông báo | Cách xử lý |
| --- | --- |
| Khách truy cập thấy "This app is being set up" | Bấm **Đã thiết lập xong — mở công khai** trong tab **Docker**. |
| `git push` lỗi `HTTP 413` hoặc "the remote end hung up unexpectedly" khi push lớn | Lần push vượt dung lượng upload của website (mặc định 256 MB). Tăng **Upload tối đa (MB)** trong tab **Công cụ** → **Dung lượng upload** của website (tối đa 10 GB), hoặc push thành nhiều phần nhỏ. |
| `ssh: connect to host … port 22` hỏi mật khẩu máy chủ hoặc bị từ chối | Không clone qua SSH được. Dùng URL HTTPS. |
| Push qua HTTPS hỏi mật khẩu liên tục khi đã bật xác thực hai lớp | Dùng access token làm mật khẩu. |
| URL clone hiện `http://` hoặc sai tên miền | Kiểm tra **Gitea Website URL** (`ROOT_URL`). ZoPanel đặt lại thành `https://<tên miền>/` mỗi lần khởi động. |
| Webhook hoặc mirror tới IP nội bộ bị lỗi | Container không tới được mạng nội bộ. Dùng địa chỉ công khai. |
| `Gitea needs 512 MB of memory; your plan has … MB and your apps use … MB` | Tăng **RAM (MB)** của gói hoặc gỡ một ứng dụng khác. |
| `not enough disk space: this app needs about 1.3 GB free and the server has … GB; free some space first` | Giải phóng dung lượng đĩa rồi cài lại. |
| Mất quyền vào tài khoản quản trị | Bằng root: `docker exec -u git zp-app-<instance> gitea admin user change-password --username <tên> --password '<mật khẩu mới>'`. |

## Xem thêm

- [Kho ứng dụng và lưu trữ S3](/vi/docs/apps)
- [Từng ứng dụng dùng để làm gì](/vi/docs/app-catalog)
- [Git deploy](/vi/docs/git-deploy)
- [Gói hosting và giới hạn](/vi/docs/packages-limits)
- [Tài liệu Gitea](https://docs.gitea.com), [Sao lưu và khôi phục](https://docs.gitea.com/administration/backup-and-restore) và [bảng tham chiếu cấu hình](https://docs.gitea.com/administration/config-cheat-sheet)