Tính năng này được phát triển bởi ayaka-notes/ayakaleaf-pro. Tính năng được giới thiệu trong v6.3.2 dưới dạng bản xem trước sớm (early preview) và sẽ được phát hành chính thức trong v6.4.0, vì vậy cấu hình và hành vi của tính năng vẫn có thể thay đổi. Nếu gặp bất kỳ vấn đề nào, chúng tôi rất mong nhận được phản hồi của bạn.
Thiết lập đồng bộ hóa Gitea
Tạo một ứng dụng OAuth2 trên phiên bản Gitea của bạn, trong Settings → Applications → Manage OAuth2 applications (hoặc Site Administration → Integrations → Applications đối với ứng dụng dùng cho toàn bộ phiên bản):- Application name: ví dụ
Overleaf, người dùng sẽ thấy tên này khi họ cấp quyền cho ứng dụng - Redirect URIs:
${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback - Confidential client: được chọn
config/variables.env
Gitea hiển thị các scope này khi người dùng cấp quyền cho ứng dụng, và giới hạn token trong phạm vi các scope đó.
Access token của Gitea hết hạn sau một giờ (
[oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf làm mới chúng bằng refresh token mà Gitea cấp kèm theo, kể cả khi Gitea vô hiệu hóa refresh token sau khi sử dụng (INVALIDATE_REFRESH_TOKENS = true), vì vậy người dùng vẫn được liên kết cho đến khi họ hủy liên kết hoặc thu hồi ứng dụng trong Gitea.
Phiên bản Gitea của bạn
ĐặtGITEA_SYNC_URL thành địa chỉ web của phiên bản của bạn, tức là ROOT_URL của nó, địa chỉ bạn dùng để mở các kho lưu trữ trong trình duyệt. REST API được suy ra từ địa chỉ này:
Gitea được phục vụ dưới một đường dẫn con cũng hoạt động, ví dụ
GITEA_SYNC_URL=https://example.com/gitea. Chỉ đặt GITEA_SYNC_API_URL khi phiên bản của bạn phục vụ API ở một địa chỉ khác, ví dụ phía sau một API gateway.
Nếu phiên bản của bạn sử dụng chứng chỉ từ một CA riêng, hãy mount chứng chỉ CA vào container và trỏ
NODE_EXTRA_CA_CERTS tới chứng chỉ đó, ví dụ NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitea-ca.pem.Các tài khoản và dự án đã liên kết thuộc về phiên bản mà chúng được liên kết. Trước khi chuyển
GITEA_SYNC_URL sang một phiên bản khác, hãy yêu cầu người dùng hủy liên kết tài khoản Gitea và các dự án của họ.GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808. Đây phải là một proxy chuyển tiếp HTTP/HTTPS tiêu chuẩn và không được sử dụng 127.0.0.1.
Ai có thể liên kết và đồng bộ
Giống như trên Overleaf Cloud, chỉ chủ sở hữu dự án mới có thể liên kết dự án với một kho lưu trữ Gitea. Sau khi đã liên kết, mọi cộng tác viên có quyền chỉnh sửa đều có thể đồng bộ dự án.- Overleaf giao tiếp với Gitea bằng tài khoản Gitea của người dùng thực hiện đồng bộ, vì vậy mỗi cộng tác viên thực hiện đồng bộ cần liên kết tài khoản Gitea của riêng mình và phải được phép push lên nhánh mặc định của kho lưu trữ.
- Cộng tác viên chỉ có quyền xem không thể sử dụng đồng bộ hóa Gitea cho dự án.
- Việc hủy liên kết tài khoản trong Overleaf sẽ xóa token của tài khoản đó; Gitea không có API để thu hồi token, vì vậy nếu muốn, bạn hãy thu hồi quyền đã cấp trong Settings → Applications của Gitea.
Cách đồng bộ hoạt động với Gitea
- Quyền: người dùng cần được phép push lên nhánh mặc định của kho lưu trữ đã liên kết. Khi một quy tắc bảo vệ nhánh không cho phép người dùng push lên đó, Overleaf sẽ yêu cầu họ liên hệ với chủ sở hữu dự án, giống như với một kho lưu trữ mà họ đã mất quyền truy cập.
- Hợp nhất: khi một dự án có thay đổi cả trong Overleaf và trong Gitea, Overleaf commit các thay đổi của mình vào một nhánh tạm thời có tên
overleaf-YYYY-MM-DD-HHMMSSvà hợp nhất nhánh đó thông qua một pull request với kiểu hợp nhất mặc định của kho lưu trữ, vì Gitea không có API để hợp nhất các nhánh mà không cần pull request. Sau khi hợp nhất, Overleaf xóa nhánh tạm thời; pull request đã hợp nhất vẫn được giữ lại trong kho lưu trữ như một bản ghi. - Quy tắc hợp nhất: Overleaf không bao giờ bỏ qua cơ chế bảo vệ nhánh của kho lưu trữ. Khi pull request có xung đột, hoặc cần được phê duyệt hay cần các status check chạy thành công, nó sẽ vẫn mở và Overleaf sẽ yêu cầu người dùng hợp nhất nó trong Gitea, sau đó tiếp tục đồng bộ.
- CI workflow: Overleaf không hiển thị các dotfile như
.gitea/workflows/và giữ nguyên chúng trong kho lưu trữ. Các commit từ Overleaf khởi chạy Gitea Actions như mọi commit khác.
Q&A
Tôi có thể force push lên nhánh mặc định không?
Tôi có thể force push lên nhánh mặc định không?
Trả lời: Vui lòng giữ tính năng force push lên nhánh mặc định ở trạng thái tắt, ví dụ bằng một quy tắc bảo vệ nhánh. Overleaf có thể tiếp quản một nhánh đã bị viết lại, nhưng đồng bộ hóa Gitea được thiết kế cho một nhánh mặc định mà lịch sử chỉ tăng thêm.
Tôi có thể đổi tên nhánh mặc định của một dự án đã liên kết không?
Tôi có thể đổi tên nhánh mặc định của một dự án đã liên kết không?
Trả lời: Không. Overleaf tiếp tục đồng bộ với nhánh mà dự án đã được liên kết, vì vậy việc đồng bộ sẽ thất bại khi nhánh đó bị đổi tên hoặc bị xóa. Để đồng bộ với một nhánh khác, hãy hủy liên kết dự án, sau đó nhập kho lưu trữ vào một dự án mới, dự án này sẽ sử dụng nhánh mặc định hiện tại.
Đồng bộ hóa Gitea có hỗ trợ Git LFS không?
Đồng bộ hóa Gitea có hỗ trợ Git LFS không?
Trả lời: Không. Các dự án Overleaf không hỗ trợ Git Large File Storage. Các tệp được Git LFS theo dõi sẽ xuất hiện trong Overleaf dưới dạng tệp con trỏ LFS, chứ không phải nội dung của chúng. Thay vào đó, hãy commit trực tiếp hình ảnh và tệp PDF vào kho lưu trữ.
Tính năng này có hoạt động với kho lưu trữ SHA-256 không?
Tính năng này có hoạt động với kho lưu trữ SHA-256 không?
Trả lời: Chưa. Overleaf so sánh các tệp theo ID SHA-1 của chúng, vì vậy trong một kho lưu trữ được tạo với định dạng đối tượng SHA-256, mỗi lần pull sẽ ghi lại toàn bộ tệp, kể cả những tệp không thay đổi. Không có gì bị mất, nhưng vui lòng sử dụng định dạng SHA-1 mặc định.
Tính năng này có hoạt động với Forgejo không?
Tính năng này có hoạt động với Forgejo không?
Trả lời: Đồng bộ hóa Gitea chỉ được xây dựng và kiểm thử với Gitea.