-
Notifications
You must be signed in to change notification settings - Fork 0
Feature Accounts vi
Từ 0.1.0: nhiều tài khoản IMAP, cộng thêm Gmail và Outlook qua OAuth. Đây là thứ cơ bản nhất SkimMail làm — đọc nhiều hộp thư từ nhiều provider khác nhau trong một unified inbox — và trang này là tài liệu tham khảo cho nó.
Mail của một người self-host hiếm khi nằm một chỗ: một Gmail cá nhân, một Outlook công việc, vài mailbox IMAP trên domain bạn tự chạy. SkimMail kết nối tới từng cái độc lập, qua đường mạng riêng của từng tài khoản nếu bạn gán một đường (xem Connections), và giữ một cache header cục bộ, đọc-trước (và tuỳ chọn cả nội dung — xem Cache nội dung thư) để unified inbox nhanh mà không cần mọi provider hỗ trợ cùng một tập mở rộng giao thức.
Chạy cho nhiều hơn một người? Đọc mục phân quyền theo từng user ở Security — nút Sync now từng cho một operator hành động thay tài khoản của người khác trong mọi bản từ 1.10.0 tới 1.17.0, đã sửa ở 1.18.0.
Settings ▸ Accounts. Xem danh sách tài khoản mở cho mọi người đã đăng nhập (viewer trở lên); thêm, sửa, sync, re-authenticate và test một kết nối là hành động của operator; xoá một tài khoản chỉ dành cho owner. Xem Người dùng và phân quyền để biết mỗi vai nghĩa là gì.
Host, port, security (tls / starttls / none), username (mặc định là
địa chỉ email nếu để trống) và password, cộng thêm hai override tuỳ chọn
theo từng tài khoản: một egress (proxy, VPN hay relay nào lưu lượng tài
khoản này dùng — xem Connections) và một sync
depth tính bằng ngày.
Thêm một tài khoản là một lượt kết nối thật, không chỉ lưu form. SkimMail quay số vào server và liệt kê mailbox của nó trước khi tài khoản được ghi vào cơ sở dữ liệu — qua đúng egress đã gán nếu bạn chọn một, nên một proxy cấu hình sai bị bắt ngay lập tức thay vì lộ ra sau này như một lượt sync lỗi âm thầm. Xác thực thất bại thì từ chối lưu tài khoản hoàn toàn.
Chưa biết chọn cái nào? App password hay OAuth? so sánh hai đường bằng lời dễ hiểu. Trang này là phần thao tác sau khi đã chọn.
Có hai lý do dùng OAuth thay vì app password, và chỉ một trong hai là chuyện sở thích:
- Outlook.com và Hotmail không còn lựa chọn nào khác. Microsoft không cấp app password cho tài khoản cá nhân và đã tắt hẳn xác thực cơ bản. Với những hộp thư đó, OAuth là đường duy nhất.
- Gmail thì có lựa chọn khác, và nó đơn giản hơn. App password chỉ tốn hai cú bấm, không cần Cloud project. OAuth đáng bỏ công khi quản trị Workspace đã chặn app password, hoặc khi bạn không muốn cất một mật khẩu mở được toàn bộ tài khoản Google.
SkimMail không kèm sẵn OAuth client dùng chung nào, và đây là chủ ý chứ
không phải làm dở. https://mail.google.com/ là scope bị hạn chế: Google
chỉ cấp cho ứng dụng đã qua một đợt thẩm định bảo mật độc lập (CASA Tier 2), và
phải thẩm định lại hàng năm. Ứng dụng đạt chuẩn thì gắn với người sở hữu nó, còn
một client secret nằm trong repo mã nguồn mở chỉ cần bị thu hồi một lần là mọi
cài đặt hỏng cùng lúc. Thunderbird có client đã verify của riêng họ, và ghi ngay
trong file đó: "Don't copy these values for your own application — register one
for yourself!" Roundcube và Nextcloud Mail cũng theo đúng mô hình tự-mang-client
như SkimMail.
Vậy: đăng ký một ứng dụng — xem
Register the OAuth application để biết
các bước cụ thể trên console của Google và Microsoft — rồi dán client id và
secret vào Settings ▸ About ▸ Setup health ▸ OAuth. Biến môi trường
(GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET,
MICROSOFT_CLIENT_ID/MICROSOFT_CLIENT_SECRET) vẫn dùng được và vẫn thắng
giá trị lưu trong DB, khi đó ô nhập hiện trạng thái khoá kèm tên biến cần gỡ.
Thiếu một trong hai giá trị thì nút của provider đó bị từ chối
(oauth_not_configured) chứ không hiện ra rồi hỏng.
Scope SkimMail xin:
| Provider | Scope |
|---|---|
https://mail.google.com/, userinfo.email, openid
|
|
| Microsoft |
https://outlook.office.com/IMAP.AccessAsUser.All, offline_access, openid, email, profile
|
Microsoft được nối lần đầu tiên ngày 18/09/2026 — mới đây, và chưa trọn vẹn. Một tài khoản Outlook cá nhân đã được nối đầu-cuối: đăng nhập xong, liệt kê 13 thư mục, thư về bình thường. Trước ngày đó chưa ai trong dự án chứng kiến bất kỳ phần nào của nó chạy. Đợt gia hạn đầu tiên giờ cũng đã được chứng kiến, và nó đi qua sạch sẽ — đây mới là phần đáng báo, vì Microsoft thay thế lần đăng nhập đã lưu mỗi lần gia hạn, và sai ở đó là mất kết nối vĩnh viễn chứ không phải mất một giờ. Thứ chưa được chứng kiến: tài khoản Microsoft 365 cơ quan hoặc trường học có hành xử y như vậy không — đó là một registration khác, dưới quyền một quản trị viên có thể chặn thẳng ứng dụng — và bất cứ điều gì quá vài giờ đầu. Gmail đã kiểm ngày 17/09/2026 và đã đi qua một lần gia hạn. Nếu bạn nối một hộp thư Microsoft — thành công hay không — xin báo lại kết quả; mấy câu này chỉ ngắn đi theo cách đó.
Cả hai đều là scope mà chính nhà cung cấp tài liệu hoá cho IMAP. Engine sync của
SkimMail nói IMAP, nên một scope cấp quyền REST API — gmail.modify của Gmail,
hay Mail.ReadWrite của Microsoft Graph — không được máy chủ thư chấp nhận,
dù token trông hợp lệ đến đâu. Đừng thêm scope Microsoft Graph cạnh scope
Outlook: một access token chỉ mang một audience, và trộn chúng thì hoặc lỗi
thẳng, hoặc tệ hơn là âm thầm cấp token cho resource được nhắc trước.
Đăng ký cả hai redirect URI dưới đây trên cùng một ứng dụng. Mỗi cái chỉ tốn
một dòng trong console của nhà cung cấp, và màn Setup health ▸ OAuth hiện cả hai
kèm nút Copy — gõ tay là nguyên nhân phổ biến nhất của redirect_uri_mismatch.
| Redirect URI | Dùng cho |
|---|---|
<BASE_URL>/api/oauth/callback |
Cách thường. Nhà cung cấp đưa trình duyệt thẳng về SkimMail. Cần địa chỉ HTTPS công khai. |
http://localhost:8642 |
Cách dán tay. Không có gì chạy ở đó cả. |
Cách thường là cách đa số cài đặt dùng: bấm Continue with Google, cấp
quyền, rồi được đưa về SkimMail. Nó đòi BASE_URL trỏ tới một địa chỉ mà nhà
cung cấp với tới được.
Cách dán tay sinh ra cho mọi trường hợp còn lại — một máy trong mạng nhà hay mạng công ty, không địa chỉ công khai, không domain, không TLS. Bấm No public address? Connect by pasting the sign-in result instead, SkimMail sẽ hiện ra URL đăng nhập kèm một nút Copy bên cạnh.
Chép nó rồi mở bằng đúng trình duyệt đang đăng nhập tài khoản đó — đó chính là lý do chỗ này đưa hẳn URL ra chứ không chỉ một cái link. Một máy chủ headless thường được quản trị từ một máy khác, và phiên đăng nhập Google hay Microsoft hay nằm trên laptop hoặc điện thoại chứ không nằm trên cái máy đang chạy SkimMail. Hãy dán vào đó. (Nếu trình duyệt bạn đang đọc dòng này chính là cái đúng, thì link "hoặc mở ngay trong tab mới tại đây" ngay cạnh URL đỡ cho bạn một vòng.)
Cấp quyền xong, trình duyệt đó sẽ đáp xuống http://localhost:8642/?code=…&state=…
và không tải được. Lỗi đó là thiết kế chứ không phải hỏng: không có gì lắng
nghe ở cổng ấy. Chép nguyên địa chỉ trên thanh địa chỉ dán lại vào SkimMail, nó
tự đọc code ra và hoàn tất.
Dòng bạn dán được bảo vệ bằng hai ổ khoá độc lập, và nên biết cái nào là cái nào. Client secret của bạn — nhà cung cấp không đổi code đó lấy token nếu thiếu nó, và nó không bao giờ rời máy chủ của bạn. PKCE — một giá trị dùng một lần mà máy chủ giữ riêng và nhà cung cấp kiểm lại. Riêng client secret đã đủ làm dòng code bị copy trở nên vô dụng với người nhìn thấy; PKCE khiến điều đó vẫn đúng ngay cả khi một nhà cung cấp xử lý PKCE cẩu thả. Lần đăng nhập hết hạn sau mười lăm phút; quá thì bắt đầu lại.
Bẫy bảy ngày. Màn hình consent của Google để ở trạng thái Testing sẽ cấp refresh token mà Google thu hồi sau bảy ngày, với mọi scope ngoài name, email và profile — tức là gồm cả scope mail. Tài khoản khi đó ngừng sync và phải nối lại, mỗi tuần một lần. Chuyển ứng dụng sang In production là hết. Cái giá là một cảnh báo "ứng dụng chưa được xác minh" trên màn consent và trần 100 người dùng — cả hai đều chấp nhận được với một instance tự vận hành.
Cảnh báo "chưa xác minh" là bình thường. https://mail.google.com/ là scope
bị hạn chế, nên tới khi ứng dụng qua thẩm định thì màn consent còn cảnh báo. Đó
là chuyện dự kiến, không phải dấu hiệu cấu hình sai. Không được "sửa" nó bằng
cách xin scope hẹp hơn — scope hẹp hơn chính là thứ làm IMAP không chạy.
Một tunnel cho instance mạng nội bộ một địa chỉ HTTPS công khai thật, biến nó
thành trường hợp thường: Cloudflare Tunnel và Tailscale Funnel đều làm được mà
không phải mở cổng. Sau đó đặt BASE_URL thành địa chỉ nó cấp và dùng cách
thường. Riêng với Gmail, app password vẫn là đường ngắn nhất và tránh được toàn
bộ những thứ trên.
Mỗi trường được patch độc lập — một request bỏ qua một trường thì giữ nguyên trường đó, không bao giờ bị reset về mặc định. Những gì sửa được sau khi tạo: tên hiển thị, thuộc group nào (xem Account groups), gán lại egress, bind address, sync depth, và tạm dừng/tiếp tục sync của riêng tài khoản đó (việc này cũng xoá luôn trạng thái tự-dừng, giống một lần re-auth thành công).
Tài khoản IMAP có một hành động Re-authenticate nhận mật khẩu mới, xác thực lại y hệt lúc thêm tài khoản, và — nếu sync của tài khoản đó từng bị tự động dừng do lỗi liên tiếp (xem Sync và Sync Health) — tiếp tục ngay lập tức.
Tài khoản OAuth có đúng nút đó, và nó làm đúng việc. Với tài khoản Gmail hay Outlook, Re-authenticate đưa bạn về màn hình đồng ý của provider thay vì hỏi mật khẩu. Quay lại là có token mới và cập nhật đúng tài khoản đang có — nó khớp theo provider và địa chỉ, nên bạn không bị đẻ ra tài khoản trùng.
Đừng xoá tài khoản để sửa một token hết hạn. Xoá đi là mất luôn thiết lập, lối ra egress đã gán và thư đã cache, mà chẳng được gì; cái nút ở trên đã là toàn bộ cách sửa.
Panel chi tiết của tài khoản OAuth hiện access token hết hạn lúc nào, kèm nút Làm mới ngay bên cạnh. Access token sống khoảng một tiếng và tự được gia hạn ở lần kết nối kế tiếp, nên đồng hồ ghi hết hạn là chuyện bình thường và được vẽ bằng chữ thường chứ không phải cảnh báo. Nút Làm mới ở đó cho lúc bạn muốn thấy đồng hồ nhảy ngay — hoặc hữu ích hơn, để biết grant còn sống hay không mà không phải đợi một lượt sync hỏng.
Chỉ một tín hiệu nghĩa là phải hành động: badge đỏ Cần kết nối lại trên tài khoản. Nó xuất hiện khi chính việc xác thực đã hỏng — grant bị thu hồi, hết hạn, hoặc bị xoay mất — và chỉ nối lại mới sửa được, thử lại thì không. SkimMail bật nó ngay ở lần đăng nhập hỏng ĐẦU TIÊN chứ không đợi hết số lần thử, để lời cảnh báo tới lúc hộp thư còn đang chạy chứ không phải sau khi nó đã dừng.
Nếu kênh cảnh báo oauth_expiring được bật (xem Thông
báo), cùng sự kiện đó cũng được gửi tới đấy.
Mỗi tài khoản có sync_depth_days của riêng nó, và con số nó bắt đầu với là
instance default lấy từ Settings ▸ Sync ▸ Default sync depth (nếu không
có thì lấy biến môi trường SYNC_DEPTH_DAYS, và cuối cùng là 30 ngày nếu cả
hai đều không đặt). Gõ một con số vào form Add Account sẽ override nó cho tài
khoản đó, vì câu trả lời cụ thể nhất luôn thắng.
Trước 1.17.0, default đó bị bỏ qua. Việc tạo tài khoản đóng cứng 30 ngày, nên một operator chọn 90 — hay toàn bộ lịch sử — vẫn nhận được một tài khoản sync 30 ngày, không có gì trong log và màn hình Settings vẫn hiện đúng con số họ đã chọn. Nếu bạn từng đặt trường đó trên một bản cũ và thắc mắc vì sao không có gì thay đổi, đó là lý do.
Đổi default không dịch chuyển các tài khoản đã có. Nó chỉ áp dụng cho tài khoản tạo sau khi đổi. Một hộp thư đã tồn tại giữ nguyên con số trên dòng của riêng nó, có chủ ý: một cửa sổ bạn đã chọn cho một tài khoản không nên bị ghi đè chỉ vì instance default đổi sau đó. Muốn đổi một tài khoản, hãy sửa chính tài khoản đó.
Chỉ owner, và nó làm một việc quan trọng hơn cả xoá dòng: nội dung thư đã cache của tài khoản bị đánh dấu để dọn trong cùng một transaction (xem Cache nội dung thư), nên một hộp thư đã xoá không tiếp tục tính vào thanh đo storage mãi mãi. Việc này chỉ xoá bản sao cục bộ của SkimMail — chính mail vẫn nguyên vẹn ở phía provider, và thêm lại đúng tài khoản đó sẽ sync lại mọi thứ từ IMAP, header và tất cả, từ đầu.
Thứ tự tài khoản hiển thị (cả ở danh sách hợp nhất lẫn view theo từng tài
khoản) là một sort_order đã lưu, đổi bằng kéo-thả và lưu bằng một lệnh gọi
— nó thuần tuý là một sở thích hiển thị và không ảnh hưởng tới sync hay
egress.
| Có từ | 0.1.0 (IMAP), OAuth thêm cùng chu kỳ phát hành |
| Vai | viewer xem được danh sách; operator thêm/sửa/sync/reauth/test; owner xoá |
| Giới hạn theo gói | Community 10 · Sponsor 25 · Pro không giới hạn — xem Plan và license |
| Đếm theo | instance, không theo user |
| Provider | mọi server IMAP; Gmail và Outlook qua ứng dụng OAuth của chính operator |
- Không có ứng dụng OAuth dùng chung/mặc định nào. Nút connect Gmail và Outlook vẫn tắt cho tới khi operator tự đăng ký app của mình với provider — đây là một bước setup thật, không phải tính năng thiếu.
- Xác thực khi thêm tài khoản chỉ kiểm khả năng truy cập, không kiểm khả năng gửi. SkimMail quay số vào server và liệt kê mailbox; nó không bao giờ gửi một thư thử, vì SkimMail là trình đọc read-first.
- Xoá một tài khoản không bao giờ chạm vào mail ở phía provider. Nó chỉ xoá thứ SkimMail đã cache cục bộ.
- Đổi sync depth không hồi tố theo nghĩa hoàn tác những gì một cửa sổ hẹp hơn đã bỏ qua — nó chỉ đổi cửa sổ mà lượt sync tiếp theo dùng, tính từ đây trở đi.
- Account groups — tổ chức tài khoản, và những cài đặt một group có thể truyền xuống thành viên của nó
- Connections — egress theo từng tài khoản (proxy, WireGuard, relay) và điều gì xảy ra khi cái đã gán bị tắt hay bị xoá
- Sync và Sync Health — tự động dừng, bảng trạng thái, và "Default sync depth" mà tài khoản mới bắt đầu từ đó
- Plan và license — giới hạn tài khoản theo gói Community/Sponsor/Pro
-
Cấu hình — các biến môi trường OAuth client và
BASE_URL - Register the OAuth application — các bước cụ thể trên console của Google và Microsoft
- Người dùng và phân quyền — viewer/operator/owner làm được gì ở đây
SkimMail · skimmail@base101.app · 2026-09-18 · commit f525934