Bỏ qua, đến phần nội dung

Cài thông báo email ​

Hướng dẫn này nối kit kit-notify-email vào một máy chủ SMTP. Xong rồi, Tara, Ryoma hoặc Bandum gửi cảnh báo và sự kiện duyệt bài bằng email tới một danh sách cố định và tới những người liên quan. Bạn mất chừng mười phút và không có token nào phải gia hạn.

Về hình

Các hình là hình minh họa, chỉ cho bạn thấy cần bấm vào đâu. Google và Portal thỉnh thoảng đổi giao diện nên màn hình thật có thể hơi khác. Tên nút thì không đổi.

Dành cho ai ​

  • Quản trị viên cài kit thông báo lên máy chủ (xem Thông báo).
  • Người quản lý tài khoản mail hoặc relay dùng để gửi cảnh báo.

Trước khi bắt đầu ​

  • Một máy chủ SMTP và một tài khoản được phép gửi thư: tên máy chủ, cổng, tên tài khoản và mật khẩu.
  • Một địa chỉ gửi (from) mà máy chủ chấp nhận.
  • Lệnh ph trên máy của bạn, để thử kit trước khi đụng vào máy chủ.
  • Version và sha256 của kit trên trang tài nguyên kit-notify-email của Tara. Bạn dùng chúng dưới dạng kit-notify-email@<version>:<sha256>.

Chọn máy chủ ​

Máy chủhostportsecurityTài khoản và mật khẩu
Gmail hoặc Google Workspacesmtp.gmail.com587starttlsĐịa chỉ của bạn, và một App password (cần bật xác minh 2 bước)
SendGrid, hoặc dịch vụ gửi thư giao dịch tương tựsmtp.sendgrid.net587starttlsUsername apikey, mật khẩu là API key
Relay nội bộRelay của bạnCổng của relaynone, chỉ trong mạng của bạnThường không cần đăng nhập: để trống username

Với Microsoft 365, hộp thư phải bật SMTP AUTH bằng mật khẩu, và Microsoft đang dần bỏ xác thực cơ bản. Bạn nên chọn dịch vụ gửi thư giao dịch hoặc relay.

Máy chủ đòi TLS ngay từ byte đầu thì dùng security là tls với cổng 465. Mặc định là starttls ở cổng 587.

1. Tạo mật khẩu ứng dụng (Gmail) ​

Dùng máy chủ khác thì bạn bỏ qua bước này.

  1. Bật xác minh 2 bước cho tài khoản gửi tại https://myaccount.google.com/security.
  2. Mở https://myaccount.google.com/apppasswords.
  3. Nhập một tên, ví dụ PhillipCLI, rồi chọn Create.
  4. Chép mật khẩu mà Google hiện ra. Mật khẩu chỉ hiện một lần. Bạn dùng nó làm mật khẩu SMTP.
Hình minh họa, màn hình thật có thể hơi khác. Nhập tên ứng dụng rồi bấm Create (1). Chép mật khẩu 16 ký tự Google hiện ra (2), vì nó chỉ hiện một lần.

2. Quyết định các settings ​

SettingMặc địnhÝ nghĩa
host(bắt buộc)Máy chủ SMTP
from(bắt buộc)Địa chỉ gửi
securitystarttlsstarttls, tls hoặc none
port587, hoặc 465 khi dùng tlsCổng của máy chủ
usernametrốngTài khoản đăng nhập. Để trống nghĩa là không đăng nhập
recipientstrốngCác địa chỉ luôn nhận thư, cách nhau bằng dấu phẩy
sendToPersontrueGửi thêm cho người liên quan. Đặt false để chỉ gửi cho recipients
helolocalhostTên trong lệnh EHLO

Mật khẩu không phải setting. Nó chỉ nằm trong biến bí mật.

3. Thử kit bằng ph kit check ​

Bạn đưa mật khẩu qua biến PHILLIP_KIT_TOKEN, không bao giờ đưa qua tham số. Lệnh ph kit check nhận thư mục kit hoặc tên[@version], các --set key=value (lặp được), --live và --send <text> kèm --to tùy chọn.

bash
PHILLIP_KIT_TOKEN=<SMTP password> ph kit check kit-notify-email \
  --set host=smtp.gmail.com --set username=alerts@example.com --set from=alerts@example.com \
  --send "test" --to you@example.com
  • Có --live, lệnh kết nối, mã hóa và đăng nhập mà không gửi gì. Kết quả có dạng smtp host:587 (starttls), from ….
  • Có --send, lệnh gửi một email thật tới --to và tới recipients.

4. Cấu hình dịch vụ ​

Tara, Ryoma và Bandum dùng chung một kit. Mỗi dịch vụ có tiền tố biến riêng. Ví dụ dưới đây là cho Ryoma. Bạn lấy <version> và <sha256> trên trang tài nguyên của Tara.

bash
RYOMA_NOTIFY_PLUGINS=kit-notify-email@<version>:<sha256>
RYOMA_NOTIFY_SECRET_KIT_NOTIFY_EMAIL=<SMTP password>
RYOMA_NOTIFY_SETTINGS={"kit-notify-email":{"host":"smtp.gmail.com","username":"alerts@example.com","from":"alerts@example.com","recipients":"pm@example.com"}}
Dịch vụKitSettings mặc địnhBí mật
TaraTARA_NOTIFY_PLUGINSTARA_NOTIFY_SETTINGSTARA_NOTIFY_SECRET_KIT_NOTIFY_EMAIL
RyomaRYOMA_NOTIFY_PLUGINSRYOMA_NOTIFY_SETTINGSRYOMA_NOTIFY_SECRET_KIT_NOTIFY_EMAIL
BandumBANDUM_NOTIFY_PLUGINSBANDUM_NOTIFY_SETTINGSBANDUM_NOTIFY_SECRET_KIT_NOTIFY_EMAIL

Tara còn cần TARA_NOTIFY_TOKEN, token Tara chỉ đọc để tải gói kit. Đổi biến xong, bạn khởi động lại dịch vụ. Các biến còn lại có trong trang Thông báo.

5. Chọn kênh cho từng tổ chức ​

Mật khẩu chỉ có một cho mỗi kit trên máy chủ, nên mọi tổ chức gửi qua cùng một tài khoản. Mỗi tổ chức tự đặt recipients của mình.

  1. Đăng nhập Portal bằng tài khoản owner hoặc admin của tổ chức. Mở menu tài khoản, chọn Admin, rồi Notifications, rồi thêm một kênh.
  2. Chọn Organization và Plugin là kit-notify-email.
  3. Trong Organization-specific settings, nhập mỗi dòng một cặp name=value, ví dụ recipients=pm@acme.example. Đừng nhập mật khẩu ở đây: Tara từ chối tên setting giống bí mật.
  4. Chọn các sự kiện muốn nhận rồi lưu.
  5. Ở menu thao tác của dòng, chọn Send test.
Nhập recipients=… vào Organization-specific settings (1), chọn sự kiện (2), rồi bấm Save (3). Gửi thử bằng menu thao tác ở dòng của kênh.

Bạn cũng làm được việc này bằng dòng lệnh:

bash
ph tara notify set <org> kit-notify-email --set recipients=pm@acme.example --events submission.pending,version.yanked
ph tara notify test <org> kit-notify-email

Xử lý lỗi ​

Nội dung lỗiNguyên nhânCách sửa
settings.host (SMTP server) is missingChưa có hostThêm host
settings.from must be an email addressfrom trống hoặc không phải địa chỉDùng địa chỉ đầy đủ như alerts@example.com
settings.security must be "starttls", "tls" or "none"Giá trị saiDùng một trong ba giá trị
settings.username is set but the SMTP password is missingCó username mà thiếu bí mậtĐặt <PREFIX>_NOTIFY_SECRET_KIT_NOTIFY_EMAIL rồi khởi động lại
SMTP AUTH: 535 …Sai tài khoản hoặc mật khẩu. Với Gmail, có thể bạn dùng mật khẩu thường thay vì App passwordTạo App password, hoặc chép lại mật khẩu
<host> does not support STARTTLS (set settings.security = "tls" or "none")Máy chủ không có STARTTLS ở cổng nàyDùng security=tls với cổng 465, hoặc none trong mạng nội bộ
could not connect to SMTP <host>:<port> (…)Sai host hoặc cổng, hoặc tường lửa chặnKiểm tra địa chỉ và đường mạng
STARTTLS with <host> failed (…)Bắt tay TLS thất bạiKiểm tra chứng chỉ của máy chủ và cổng
the SMTP server did not respondKhông có phản hồi trong 20 giâyKiểm tra máy chủ và đường mạng
SMTP RCPT: 550 …Máy chủ từ chối một người nhận hoặc người gửiSửa địa chỉ, hoặc cho phép người gửi trên máy chủ

Khi không có người nhận hợp lệ nào, kit không gửi gì và cũng không báo lỗi. Nếu không thấy email, bạn kiểm tra recipients trước.

Giới hạn ​

  • Chỉ gửi văn bản thuần, thân thư UTF-8.
  • Người nhận gồm recipients và những người liên quan (trừ khi sendToPerson là false). Địa chỉ sai định dạng bị bỏ qua.
  • Mọi tổ chức gửi qua cùng một tài khoản gửi, vì mật khẩu chỉ có một cho mỗi kit trên máy chủ.
  • Tin chỉ chứa siêu dữ liệu và liên kết, không bao giờ có nội dung công việc.

Đọc thêm ​