Chương 38: Cấu Hình GitHub Sync

GitHub Sync biến workspace SeaMeet của bạn thành một cây Markdown riêng tư, được kiểm soát phiên bản sống trong kho GitHub riêng của bạn. Mỗi lần bạn chỉnh sửa một ghi chú, đổi tên một bản ghi hoặc tinh chỉnh một trang wiki, SeaMeet âm thầm commit thay đổi ở chế độ nền và đẩy nó lên GitHub. Mở SeaMeet trên một laptop khác và các ghi chú của bạn được tải xuống khi khởi chạy lần đầu — không có Dropbox ở giữa, không có máy chủ Seasalt trong vòng lặp. Kho là của bạn, dữ liệu là của bạn và bạn có thể duyệt nó trực tiếp trên github.com nếu bạn muốn.

Mô hình rất đơn giản: kho GitHub của bạn là nơi lưu trữ. SeaMeet không chạy một dịch vụ đồng bộ. Nó cài đặt một GitHub App nhỏ trên tài khoản của bạn, nhận một token OAuth theo người dùng, và sử dụng token đó để đẩy và kéo các commit Git trực tiếp. Vì lưu trữ là gói miễn phí của GitHub — cung cấp cho bạn không giới hạn kho riêng tư — đồng bộ thực tế là miễn phí. Và vì mỗi workspace SeaMeet là kho riêng của nó, bạn có thể giữ workspace công việc và cá nhân hoàn toàn riêng biệt.

Mục Tiêu Chương

Sau khi đọc chương này, bạn sẽ có thể:

Cài đặt SeaMeet GitHub App trên tài khoản hoặc tổ chức của bạn
Cho phép SeaMeet qua OAuth và để nó tạo một kho đồng bộ riêng tư cho bạn
Đọc thanh trạng thái đồng bộ và hiểu mỗi trạng thái trong sync state machine
Nhận diện khi nào OAuth đã tự động làm mới ở chế độ nền và khi nào bạn cần ủy quyền lại thủ công
Giải quyết một xung đột đồng bộ khi cùng một ghi chú đã được chỉnh sửa trên hai thiết bị
Điều chỉnh bảng Cài đặt Sync (tự động đồng bộ, khoảng thời gian đồng bộ, đồng bộ khi khởi động)
Khắc phục các chế độ thất bại phổ biến nhất

Điều Kiện Tiên Quyết

Trước khi bắt đầu, hãy đảm bảo bạn có:

Một tài khoản GitHub — gói miễn phí là ổn; bạn không cần GitHub Pro
Quyền đồng bộ đang hoạt động — bao gồm trong các gói BYOK Pro và Sync Pro. Nếu gói thanh toán của bạn không bao gồm đồng bộ, màn hình Cài đặt Sync sẽ hiển thị một banner "Subscribe to enable sync". Xem Chương 35: Đăng ký & Thanh toán để biết chi tiết gói.
Một workspace mở trong SeaMeet — đồng bộ gắn vào workspace đang hoạt động, không phải toàn bộ ứng dụng. Nếu bạn có nhiều workspace, mỗi workspace là kho GitHub riêng của nó.
Truy cập internet hoạt động — luồng cấu hình mở GitHub trong trình duyệt mặc định của bạn

Một kho cho mỗi workspace. SeaMeet tạo một kho riêng tư riêng biệt cho mỗi workspace bạn kết nối. Điều này giữ cho ghi chú công việc và ghi chú cá nhân được cô lập sạch sẽ và có nghĩa là bạn có thể ngắt kết nối một mà không chạm vào cái khác.

Cấu Hình Từng Bước

Cấu hình lần đầu mất khoảng 90 giây: ủy quyền SeaMeet trên GitHub, để nó tạo kho của bạn, chờ tải lên ban đầu và bạn đã xong.

Bước 1: Mở Cài đặt Sync

Nhấp vào biểu tượng bánh răng Cài đặt
Mở tab Sync trong thanh trái
Bạn sẽ thấy thẻ tiêu đề "Sync with GitHub"

Nếu bạn không thấy tab Sync, gói đăng ký của bạn không bao gồm đồng bộ — xem Chương 35 để nâng cấp.

Nếu bạn thấy một banner ghi "Back up your notes to a private GitHub repo with BYOK Pro", bạn có một tài khoản miễn phí. Nhấp vào banner để mở paywall, hoặc bỏ qua phần còn lại của chương này cho đến khi bạn đã đăng ký.

Bước 2: Nhấp "Set Up GitHub Sync"

Trạng thái trống của Cài đặt Sync hiển thị ba ô lợi ích ("Free & private", "Effectively unlimited", "One repo per workspace") và một nút chính Set Up GitHub Sync ở dưới cùng.

Nhấp vào nó. Trình duyệt mặc định của bạn mở trang ủy quyền GitHub.

Bước 3: Cài đặt SeaMeet GitHub App (một lần)

Lần đầu tiên bạn ủy quyền SeaMeet, GitHub sẽ yêu cầu bạn cài đặt SeaMeet GitHub App trên tài khoản của bạn. Đây là một bước một lần cho mỗi tài khoản GitHub (hoặc cho mỗi tổ chức, nếu bạn muốn đồng bộ với một kho thuộc sở hữu của tổ chức).

Trên trang cài đặt GitHub:

Chọn tài khoản hoặc tổ chức bạn muốn SeaMeet ghi vào
Chọn "All repositories" hoặc "Only select repositories" — SeaMeet App cần quyền contents: write và administration: write để nó có thể tạo kho đồng bộ thay mặt bạn
Nhấp Install & Authorize

GitHub đưa bạn trở lại SeaMeet. Bảng Cài đặt Sync bây giờ hiển thị:

┌──────────────────────────────────────────────────────┐
│   ✓ Đã ủy quyền                                      │
│   ⟳ Đang tạo kho & tải lên...                        │
└──────────────────────────────────────────────────────┘

Tại sao một GitHub App và không phải token OAuth thông thường? GitHub Apps có quyền chi tiết theo từng kho và refresh token quay vòng. SeaMeet chỉ có quyền ghi vào các kho bạn đã chọn rõ ràng, và token truy cập OAuth hết hạn sau mỗi 8 giờ — ngay cả khi nó bị rò rỉ, cửa sổ sẽ nhỏ. (Xem phần Tự Động Làm Mới OAuth bên dưới để xem SeaMeet giữ điều đó vô hình với bạn như thế nào.)

Bước 4: Tạo kho (tự động)

SeaMeet bây giờ gọi GitHub API thay mặt bạn và:

Tạo một kho riêng tư được đặt tên theo workspace của bạn (ví dụ: seameet-work-notes)
Khởi tạo một kho Git cục bộ bên trong thư mục workspace của bạn nếu chưa có
Chạy git init, viết một .gitignore loại trừ các tệp âm thanh/video/ảnh chụp màn hình, và thực hiện commit ban đầu
Thêm kho GitHub mới làm origin
Đẩy commit ban đầu

Bạn sẽ thấy thanh trạng thái ở dưới cùng của sidebar chuyển qua:

Đang tạo kho...  →  Đang đồng bộ...  →  Đã đồng bộ · vừa xong

Vậy thôi. Workspace của bạn bây giờ được sao lưu bởi GitHub.

Bước 5: Đồng bộ đầu tiên chạy tự động

Từ giờ trở đi, SeaMeet tự động commit mỗi 5 phút (theo mặc định) bất cứ khi nào bạn có thay đổi chưa được lưu, và đẩy lên GitHub ngay sau mỗi commit. Lần khởi chạy tiếp theo của SeaMeet, ứng dụng kéo từ GitHub trước khi bạn bắt đầu chỉnh sửa — vì vậy các thay đổi được thực hiện trên thiết bị khác xuất hiện vào thời điểm ứng dụng mở.

Sync State Machine

SyncManager của SeaMeet chạy một máy trạng thái nhỏ và phát trạng thái hiện tại của nó đến renderer. Sidebar SyncStatusBar và bảng Cài đặt Sync đều đọc từ trạng thái này. Hiểu các trạng thái giúp bạn đọc UI chính xác.

                      ┌─────────────┐
                      │    idle     │ ◄──────┐
                      └──────┬──────┘        │
                             │ file change   │
                             ▼               │
                      ┌─────────────┐        │
                ┌────►│   pending   │        │
                │     └──────┬──────┘        │
       file     │            │ commit timer  │
       change   │            ▼               │
                │     ┌─────────────┐        │
                │     │ committing  │        │
                │     └──────┬──────┘        │
                │            ▼               │
                │     ┌─────────────┐        │
                │     │   pushing   │        │
                │     └──────┬──────┘        │
                │            ▼               │
                │     ┌─────────────┐        │
                │     │   synced    │── 5s ──┘
                │     └─────────────┘
                │
                │     ┌─────────────┐
                ├─────┤   pulling   │  (khởi động hoặc đẩy bị từ chối)
                │     └─────────────┘
                │
                │     ┌─────────────┐
                ├─────┤  conflict   │  → người dùng giải quyết → syncing → synced
                │     └─────────────┘
                │
                │     ┌─────────────┐
                ├─────┤   offline   │  → mạng trở lại → thử lại
                │     └─────────────┘
                │
                │     ┌─────────────┐
                ├─────┤   timeout   │  → người dùng nhấp Retry
                │     └─────────────┘
                │
                │     ┌────────────────┐
                └─────┤ token-expired  │ → thẻ ủy quyền lại
                      └────────────────┘

Đây là ý nghĩa của mỗi trạng thái trong UI:

Trạng thái	Nhãn thanh trạng thái	Ý nghĩa
idle	"Đã đồng bộ · 2 phút trước"	Không có gì đang chờ, commit cuối cùng sạch sẽ
pending	"Đang chờ..."	Bạn có các thay đổi chưa được lưu; commit timer sẽ kích hoạt vào khoảng tiếp theo
committing	"Đang đồng bộ..."	Một commit Git đang diễn ra cục bộ
pushing	"Đang đẩy..."	Commit cục bộ hoàn tất; đang đẩy lên GitHub
pulling	"Đang kéo..."	Đồng bộ khởi động, hoặc đẩy bị từ chối và chúng tôi đang kéo trước
syncing	"Đang đồng bộ..."	Đang hoàn thành rebase sau giải quyết xung đột
synced	"Đã đồng bộ · vừa xong"	Thành công vừa hoàn thành; hiển thị trong 5 giây, sau đó trở về idle
conflict	"Xung đột đồng bộ"	Cục bộ và remote đều chỉnh sửa cùng một tệp. UI hiển thị luồng giải quyết xung đột.
error	"Lỗi đồng bộ"	Một lỗi không phải mạng, không phải xung đột (ví dụ: lỗi git). Tự động thử lại với exponential backoff đến 5 lần.
offline	"Ngoại tuyến"	Mạng không thể tiếp cận. Sẽ thử lại khi có thay đổi tệp tiếp theo hoặc sau 60 giây.
timeout	"Đồng bộ hết thời gian"	Một lệnh git mất nhiều hơn 60 giây (xem Bảo Vệ Hết Thời Gian Đồng Bộ bên dưới)
token-expired	"Ủy quyền lại"	Làm mới OAuth thất bại và người dùng phải ủy quyền lại thủ công
installing-app	"Đang cài đặt GitHub App..."	Đang chờ người dùng hoàn thành bước cài đặt GitHub App trong trình duyệt của họ
creating-repo	"Đang tạo kho..."	Luồng cấu hình đang tạo kho GitHub và đẩy commit ban đầu

Nếu thanh trạng thái đang hiển thị spinner, đó là hoạt động nền bình thường. Nếu nó là màu hổ phách hoặc đỏ, xem phần Khắc phục sự cố bên dưới.

Tự Động Làm Mới OAuth

GitHub Apps phát hành token truy cập người dùng hết hạn sau mỗi 8 giờ, cộng với refresh token hợp lệ trong 6 tháng. SeaMeet quản lý điều này cho bạn nên bạn hầu như không bao giờ phải nghĩ về nó.

Cách hoạt động:

Khi SeaMeet sắp đẩy hoặc kéo, SyncManager._refreshTokenIfNeeded() kiểm tra liệu token hiện tại có hết hạn trong 5 phút tiếp theo không.
Nếu có, SeaMeet gọi endpoint /login/oauth/access_token của GitHub với refresh token được lưu trữ. GitHub trả về một token truy cập mới và quay vòng refresh token. SeaMeet ghi cả hai trở lại tệp token được mã hóa trên đĩa.
Lệnh Git sau đó chạy với token vừa được làm mới. Bạn không thấy gì trên màn hình — toàn bộ làm mới mất dưới một giây.

Xử lý lỗi tạm thời: Nếu cuộc gọi làm mới thất bại vì mạng không ổn định hoặc GitHub trả về 5xx (một REFRESH_NETWORK_ERROR), SeaMeet không vứt bỏ token hiện có. Thay vào đó, đồng bộ chuyển sang trạng thái offline và thử lại sau. Điều này quan trọng vì token hiện có có thể vẫn còn hợp lệ trong vài phút nữa — vứt bỏ nó vì một sự cố mạng tạm thời sẽ đăng xuất bạn khỏi đồng bộ không cần thiết.

Coalescing làm mới đồng thời: GitHub quay vòng refresh token mỗi lần bạn sử dụng nó, vì vậy hai làm mới đồng thời sẽ chạy đua và một sẽ làm vô hiệu hóa cái kia. SeaMeet thu gọn các cuộc gọi làm mới đồng thời thành một Promise duy nhất đang xử lý (_refreshPromise) để khởi động-đồng bộ và đẩy-với-thử-lại không bao giờ chiến đấu trên token đang quay vòng.

Khi làm mới thực sự thất bại: Nếu GitHub trả về REFRESH_TOKEN_EXPIRED — có nghĩa là refresh token 6 tháng đã hết hạn hoặc bị thu hồi — SeaMeet:

Xóa tệp token được mã hóa khỏi đĩa
Đi vào trạng thái cuối token-expired
Hiển thị một thẻ màu hổ phách trong Cài đặt Sync:

┌──────────────────────────────────────────────────────┐
│ ⚠  Ủy quyền GitHub đã hết hạn. Vui lòng              │
│    ủy quyền lại để tiếp tục đồng bộ.                  │
│                                                       │
│  [ ↻ Ủy quyền lại GitHub ]                            │
└──────────────────────────────────────────────────────┘

Nhấp Ủy quyền lại GitHub. Bạn được gửi qua luồng OAuth — nhưng vì GitHub App đã được cài đặt, đó là một cú nhấp duy nhất để xác nhận và bạn xong trong khoảng 10 giây. SeaMeet sau đó loại bỏ bất kỳ token cũ nào khỏi git config cục bộ của bạn (token cũ có thể được nhúng trong URL của origin) trước khi đẩy tiếp theo, để bạn không bị lặp trên một thông tin xác thực đã chết.

Bảo Vệ Hết Thời Gian Đồng Bộ

Các lệnh Git có thể bị treo mãi mãi nếu mạng im lặng giữa chừng truyền — một TCP socket có thể ngồi trong trạng thái nửa mở mà không bao giờ phát sinh lỗi. SeaMeet bọc mỗi đẩy và kéo Git trong một timeout AbortController 60 giây.

Nếu một đẩy hoặc kéo không hoàn thành trong 60 giây, SeaMeet:

Hủy bỏ tiến trình con git
Đi vào trạng thái timeout
Hiển thị một thẻ màu hổ phách trong Cài đặt Sync:

┌──────────────────────────────────────────────────────┐
│ ⚠  Đồng bộ hết thời gian. Điều này có thể do vấn đề  │
│    mạng hoặc ủy quyền GitHub đã hết hạn.              │
│                                                       │
│  [ ↻ Thử lại đồng bộ ]   [ Ủy quyền lại GitHub ]      │
└──────────────────────────────────────────────────────┘

Thử lại đồng bộ chạy lại commitNow. Đây là nút đúng để nhấp nếu bạn nghĩ mạng của bạn vừa bị rớt một chút. Ủy quyền lại GitHub chạy luồng OAuth lại; nhấp vào điều này nếu timeout tiếp tục xảy ra, điều này thường có nghĩa là token của bạn là vấn đề chứ không phải mạng.

Trạng thái trở về idle tự động sau khoảng 30 giây ngay cả khi bạn không nhấp vào bất cứ điều gì — đồng bộ sẽ thử lại vào thay đổi tệp tiếp theo.

Giải Quyết Xung Đột

Một xung đột xảy ra khi cùng một tệp đã được chỉnh sửa trên hai thiết bị kể từ lần đồng bộ cuối. Ví dụ: bạn đã viết một đoạn trong meetings/2026-06-03-standup.md trên laptop của bạn, sau đó sau đó đã chỉnh sửa cùng đoạn trên máy của một người bạn. Khi thiết bị thứ hai đẩy, GitHub từ chối đẩy vì các lịch sử phân kỳ.

SeaMeet xử lý điều này bằng cách:

Kéo các thay đổi remote với rebase
Phát hiện các marker xung đột hợp nhất
Đi vào trạng thái conflict
Hiển thị xung đột trong thanh trạng thái sidebar (trở nên có thể nhấp) và trong bảng xung đột Cài đặt Sync

Hộp Thoại Giải Quyết Xung Đột

Nhấp vào thanh trạng thái khi đồng bộ ở conflict mở Hộp Thoại Giải Quyết Xung Đột:

┌──────────────────────────────────────────────────────────┐
│  ⚠  Xung Đột Đồng Bộ                  1 / 2          [×]  │
├──────────────────────────────────────────────────────────┤
│                                                          │
│  "2026-06-03-standup.md" đã được thay đổi trên thiết bị khác.│
│                                                          │
│  ┌────────────────────────┐  ┌────────────────────────┐  │
│  │ ✎  Chỉnh sửa thủ công  │  │ ✦  Hợp nhất bằng Agent │  │
│  └────────────────────────┘  └────────────────────────┘  │
│                                                          │
└──────────────────────────────────────────────────────────┘

Bạn có hai tùy chọn:

Chỉnh sửa thủ công — mở tệp xung đột trong trình biên tập mặc định của hệ thống của bạn với các marker <<<<<<< / ======= / >>>>>>> tiêu chuẩn của Git tại chỗ. Chỉnh sửa tệp để giải quyết chúng, lưu, sau đó quay lại SeaMeet và nhấp Done. SeaMeet stage tệp đã giải quyết và tiếp tục rebase.

Hợp nhất bằng Agent (chỉ BYOK Pro, yêu cầu cấu hình Trợ lý AI) — gửi cả hai phiên bản đến Trợ lý AI được cấu hình của bạn (GitHub Copilot hoặc Claude Code, xem Chương 36: Hướng Dẫn Cấu Hình BYOK) và yêu cầu nó tạo ra một phiên bản hợp nhất giữ ý định của cả hai bên. Đầu ra của agent được stage tự động; bạn sẽ thấy một spinner "Đang hoàn thành đồng bộ..." trong khi rebase hoàn thành.

Nếu có nhiều xung đột cùng một lúc, hộp thoại hiển thị một bộ đếm (1 / 2, 2 / 2) và mũi tên chevron trong bảng xung đột Cài đặt Sync để bạn có thể bước qua từng cái một.

"Giữ của tôi" / "Giữ của họ" / "Giữ cả hai" là các lựa chọn tự nhiên xuất hiện khi bạn ở trong trình biên tập thủ công: chỉ để lại văn bản phiên bản của bạn giữa các marker, chỉ văn bản phiên bản remote, hoặc xen kẽ cả hai. Nút Hợp nhất Agent về cơ bản làm "giữ cả hai, một cách thông minh."

Nếu bạn mắc lỗi thì sao? Xung đột đồng bộ không phá hủy. Git giữ nội dung "của chúng tôi" và "của họ" gốc trong index, và getConflictVersions(filePath) có thể truy xuất một trong hai vào bất kỳ điểm nào trong quá trình giải quyết. Bạn sẽ không vô tình mất công việc.

Bảng Cài Đặt Sync

Khi bạn được kết nối, Cài đặt Sync (Cài đặt → Sync) cho bạn một màn hình duy nhất với mọi thứ ở một nơi:

┌─────────────────────────────────────────────────────────────┐
│  ✓ Sync & Sao lưu                                           │
│  Ghi chú và wiki của bạn được tự động đồng bộ với GitHub.   │
│  Bản ghi âm thanh, bản ghi video và ảnh chụp màn hình       │
│  không được đồng bộ.                                        │
├─────────────────────────────────────────────────────────────┤
│  ⓘ  https://github.com/you/seameet-work-notes                │
│  🕒 Đồng bộ cuối: 4 phút trước                              │
├─────────────────────────────────────────────────────────────┤
│  Tự động đồng bộ                                 [ BẬT  ◉ ]  │
│  Khoảng thời gian đồng bộ                       [ 5 phút ▾ ] │
│  Branch                                              main   │
│  Đồng bộ cuối                                4 phút trước │
├─────────────────────────────────────────────────────────────┤
│  Tự động đồng bộ khi thay đổi                    [ BẬT  ◉ ]  │
│  Đồng bộ khi khởi động                           [ BẬT  ◉ ]  │
├─────────────────────────────────────────────────────────────┤
│  [ ⤓ Đồng bộ ngay ]                                         │
├─────────────────────────────────────────────────────────────┤
│  [ ↗ Xem trên GitHub ]    [ Ngắt kết nối ]                  │
└─────────────────────────────────────────────────────────────┘

Các điều khiển, từ trên xuống dưới:

Tự động đồng bộ — toggle chính cho commit timer nền. Tắt có nghĩa là SeaMeet chỉ commit khi bạn nhấp Đồng bộ ngay.
Khoảng thời gian đồng bộ — commit timer kích hoạt mỗi bao lâu. Các lựa chọn là 1 / 5 / 10 / 30 phút. Mặc định là 5 phút. Khoảng 1 phút ổn cho việc ghi chú tích cực; 30 phút tốt cho các workspace ít chỉnh sửa nơi bạn thích batch commits.
Branch — nhánh Git SeaMeet đồng bộ. Hầu như luôn là main. Chỉ đọc trong UI.
Đồng bộ cuối — dấu thời gian tương đối của lần đẩy thành công cuối cùng.
Tự động đồng bộ khi thay đổi — khi bật, các đẩy xảy ra ngay sau mỗi commit cục bộ (trường hợp điển hình). Khi tắt, SeaMeet commit cục bộ nhưng chỉ đẩy khi bạn nhấp Đồng bộ ngay. Hữu ích nếu bạn muốn batch đẩy (ví dụ: trên kết nối tính cước).
Đồng bộ khi khởi động — khi bật, SeaMeet kéo từ GitHub vào thời điểm ứng dụng khởi chạy. Được khuyến nghị trừ khi bạn có kết nối rất chậm.
Đồng bộ ngay — buộc một chu kỳ commit-và-đẩy ngay lập tức. Không chờ timer. Hữu ích trước khi đóng laptop của bạn.
Xem trên GitHub — mở kho trong trình duyệt của bạn.
Ngắt kết nối — xóa token OAuth được lưu trữ, xóa tệp token được mã hóa và xóa origin khỏi kho Git cục bộ của bạn. Các tệp Markdown cục bộ và lịch sử Git của bạn không bị động đến — chỉ liên kết với GitHub bị cắt đứt.

Những Gì Được Đồng Bộ (Và Những Gì Không)

Điều này được ghi chép trong chỉ mục phần, nhưng nó đáng để nhắc lại ở đây:

Được đồng bộ	Không đồng bộ
Ghi chú (tệp `.md`)	Bản ghi âm thanh (`.webm`, `.mp3`)
Trang wiki (tệp `.md`)	Bản ghi video (`.webm`, `.mp4`)
Manifest bản ghi (siêu dữ liệu JSON)	Ảnh chụp màn hình (`.png`, `.jpg`)
Tóm tắt AI và bản phiên âm	Các lần tạo AI được lưu cache
Đồ thị wikilink	Cài đặt ứng dụng
`.gitignore`	Trạng thái scratch của trình biên tập

.gitignore SeaMeet ghi loại trừ tất cả các danh mục nhị phân lớn. Điều này là cố ý: kho riêng tư miễn phí của GitHub giới hạn ở 1 GB, và một video 30 phút sẽ ăn hết một mình. SeaMeet giữ phương tiện trên đĩa cục bộ của bạn và chỉ đồng bộ Markdown nhẹ.

Nếu bạn muốn đồng bộ phương tiện đầy đủ, đó là gói Sync Pro — xem Chương 35.

Khắc Phục Sự Cố

"Authorization failed" ngay sau khi nhấp Set Up GitHub Sync

Nguyên nhân và khắc phục:

Trình chặn pop-up — nếu không có cửa sổ trình duyệt nào mở, OS hoặc trình duyệt của bạn có thể đã chặn việc khởi chạy. Nhấp Set Up GitHub Sync lại và xác nhận bất kỳ lời nhắc pop-up nào.
Bạn đã từ chối quyền GitHub App — quay lại qua luồng và chấp nhận các phạm vi contents: write + administration: write. Không có administration: write SeaMeet không thể tạo kho cho bạn.
Lỗi state mismatch — đóng bất kỳ cửa sổ SeaMeet nào khác có thể đang chạy đua trên cùng luồng OAuth, sau đó thử lại.

Lỗi "Repo permissions" trong quá trình cấu hình

Lỗi đọc một cái gì đó như "GitHub App has 'contents: read' permission, but needs 'contents: write'." Điều này có nghĩa là bạn đã cài đặt một phiên bản cũ hơn của App.

Khắc phục:

Mở github.com/settings/installations
Tìm SeaMeet trong danh sách và nhấp Configure
Dưới Repository permissions, thay đổi Contents và Administration thành Read and write
Lưu, sau đó gỡ cài đặt và cài đặt lại ứng dụng — GitHub chỉ áp dụng các quyền mới khi cài đặt lại
Chạy lại Set Up GitHub Sync trong SeaMeet

"Could not reach GitHub" / đồng bộ kẹt ở "Offline"

Lỗi mạng. SeaMeet sẽ thử lại tự động khi:

Bạn thực hiện bất kỳ thay đổi tệp nào (kích hoạt một nỗ lực thử lại ngay lập tức)
60 giây trôi qua từ lần thử lại cuối cùng

Nếu mạng của bạn trở lại và đồng bộ vẫn hiển thị Offline sau vài phút:

Nhấp Đồng bộ ngay để buộc thử lại
Nếu nó hết thời gian: kiểm tra firewall của bạn không chặn github.com
Như một giải pháp cuối cùng, khởi động lại SeaMeet — đồng bộ khởi động sẽ kích hoạt khi khởi chạy

Đồng bộ kẹt ở "Pending"

Điều này thường có nghĩa là auto-commit timer chưa kích hoạt. Theo mặc định nó kích hoạt mỗi 5 phút. Không muốn chờ? Nhấp Đồng bộ ngay.

Nếu Đồng bộ ngay không di chuyển đồng bộ vượt qua Pending, kiểm tra:

Bạn có ở gói thanh toán bao gồm đồng bộ không? Mở Cài đặt Sync — nếu bạn thấy banner subscribe, đồng bộ bị tắt ở lớp quyền.
Có các thay đổi chưa commit ngoài cây Markdown không? Auto-commit timer chỉ kích hoạt khi _pendingChanges không trống.

"Tôi thấy thẻ token-expired"

Đây là kết thúc dự kiến của vòng đời làm mới OAuth — refresh token 6 tháng của bạn đã hết hạn, hoặc bạn đã thu hồi GitHub App, hoặc bạn đã thay đổi mật khẩu GitHub của mình (làm vô hiệu hóa tất cả các token OAuth).

Khắc phục: nhấp Ủy quyền lại GitHub trong thẻ. Luồng giống như cấu hình ban đầu nhưng bỏ qua bước cài đặt GitHub App (bạn đã có nó được cài đặt). Mất khoảng 10 giây.

Bảng giải quyết xung đột không đóng

Bảng chỉ đóng khi tất cả xung đột trong danh sách được giải quyết. Nếu bạn thấy bộ đếm (1 / 3), sử dụng các mũi tên chevron trong bảng xung đột Cài đặt Sync để bước qua các tệp còn lại. Mỗi tệp cần một giải quyết rõ ràng (chỉnh sửa thủ công + Done, hoặc Hợp nhất Agent).

Nếu bảng khẳng định có xung đột nhưng bạn không thấy bất kỳ marker nào trong các tệp của mình, nhấp Đồng bộ ngay — một trạng thái conflict cũ sẽ bị xóa vào lần thử đồng bộ thành công tiếp theo.

Vòng lặp "Push rejected"

Nếu đồng bộ thay phiên giữa pushing và pulling liên tục, GitHub đang từ chối các đẩy của bạn vì remote liên tục di chuyển trước. Điều này có thể xảy ra nếu:

Một instance SeaMeet khác đang chạy đối với cùng kho và đẩy nhanh hơn cái này có thể bắt kịp — đóng instance khác.
Ai đó (hoặc một công cụ nào đó) đang commit vào kho GitHub từ bên ngoài SeaMeet — tạm dừng công cụ bên ngoài cho đến khi bản sao cục bộ của bạn bắt kịp.

Ghi Chú Bảo Mật

Nơi token OAuth được lưu trữ: trong OS keychain của bạn qua API safeStorage của Electron. Trên Windows đó là DPAPI, trên macOS là Keychain Services, trên Linux là libsecret. Blob được mã hóa được ghi vào <userData>/github-token.enc với chế độ tệp 0o600. Tệp giữ token truy cập, refresh token, dấu thời gian hết hạn và client ID, client secret và slug của GitHub App.

Những gì không được lưu trữ trong argv: token OAuth không bao giờ được truyền dưới dạng đối số -c http.extraHeader=... cho git, vì argv hiển thị cho người dùng khác qua ps aux. Thay vào đó tiêu đề Authorization được tiêm qua biến môi trường GIT_CONFIG_PARAMETERS, là riêng tư đối với tiến trình. Người dùng khác trên cùng máy không thể thấy token của bạn.

Những gì kết thúc trên đĩa trong kho: các tệp Markdown đơn giản. Không có token, không có secrets, không có thông tin xác thực. .gitignore loại trừ các tệp phương tiện, nhưng bạn vẫn nên tránh dán secrets vào nội dung ghi chú — chúng sẽ đồng bộ.

Thu hồi truy cập: để cắt ngay quyền truy cập của SeaMeet vào một kho, gỡ cài đặt SeaMeet GitHub App tại github.com/settings/installations. Nỗ lực đồng bộ tiếp theo sẽ thất bại với token-expired và SeaMeet sẽ xóa token cục bộ của nó. Các ghi chú cục bộ của bạn không bị động đến.

Tham Khảo Nhanh

┌─────────────────────────────────────────────────────────────┐
│                   GITHUB SYNC                               │
│                   Tham khảo nhanh                           │
├─────────────────────────────────────────────────────────────┤
│  Mở Cài đặt Sync       │ Cài đặt → Sync                     │
│  Cấu hình lần đầu      │ Nhấp "Set Up GitHub Sync"          │
│  Phạm vi bắt buộc      │ contents: write, admin: write      │
│  Đặt tên kho           │ Một kho riêng tư cho mỗi workspace │
├─────────────────────────────────────────────────────────────┤
│  Khoảng đồng bộ mặc định│ 5 phút (1 / 5 / 10 / 30)          │
│  Buộc đồng bộ          │ Nút "Đồng bộ ngay"                 │
│  Tự động đồng bộ khi đẩy│ Bật (toggle trong Cài đặt Sync)   │
│  Đồng bộ khi khởi động │ Bật (toggle trong Cài đặt Sync)    │
├─────────────────────────────────────────────────────────────┤
│  Biên độ làm mới OAuth │ 5 phút trước khi hết hạn           │
│  Timeout lệnh Git      │ 60 giây (AbortController)          │
│  Giới hạn tự động thử  │ 5 lần thử, exp. backoff            │
│  Lưu trữ token         │ OS keychain (safeStorage)          │
├─────────────────────────────────────────────────────────────┤
│  UI xung đột           │ Nhấp thanh trạng thái khi xung đột │
│  Giải quyết thủ công   │ Chỉnh sửa marker → Done            │
│  Hợp nhất bằng Agent   │ BYOK Pro + Trợ lý AI đã cấu hình   │
├─────────────────────────────────────────────────────────────┤
│  Ngắt kết nối          │ Cài đặt Sync → Ngắt kết nối        │
│  Thu hồi từ GitHub     │ github.com/settings/installations  │
│  Xem kho               │ Liên kết "Xem trên GitHub"         │
└─────────────────────────────────────────────────────────────┘

Last updated: 2026-06-04

← Chương 37: Nhà cung cấp GitHub Copilot | (cuối hướng dẫn — quay lại Chỉ mục)