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
phtrê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-emailcủa Tara. Bạn dùng chúng dưới dạngkit-notify-email@<version>:<sha256>.
Chọn máy chủ
| Máy chủ | host | port | security | Tài khoản và mật khẩu |
|---|---|---|---|---|
| Gmail hoặc Google Workspace | smtp.gmail.com | 587 | starttls | Đị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.net | 587 | starttls | Username apikey, mật khẩu là API key |
| Relay nội bộ | Relay của bạn | Cổng của relay | none, chỉ trong mạng của bạn | Thườ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.
- Bật xác minh 2 bước cho tài khoản gửi tại
https://myaccount.google.com/security. - Mở
https://myaccount.google.com/apppasswords. - Nhập một tên, ví dụ
PhillipCLI, rồi chọn Create. - 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.
2. Quyết định các settings
| Setting | Mặc định | Ý nghĩa |
|---|---|---|
host | (bắt buộc) | Máy chủ SMTP |
from | (bắt buộc) | Địa chỉ gửi |
security | starttls | starttls, tls hoặc none |
port | 587, hoặc 465 khi dùng tls | Cổng của máy chủ |
username | trống | Tài khoản đăng nhập. Để trống nghĩa là không đăng nhập |
recipients | trống | Các địa chỉ luôn nhận thư, cách nhau bằng dấu phẩy |
sendToPerson | true | Gửi thêm cho người liên quan. Đặt false để chỉ gửi cho recipients |
helo | localhost | Tê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.
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ạngsmtp host:587 (starttls), from …. - Có
--send, lệnh gửi một email thật tới--tovà tớirecipients.
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.
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ụ | Kit | Settings mặc định | Bí mật |
|---|---|---|---|
| Tara | TARA_NOTIFY_PLUGINS | TARA_NOTIFY_SETTINGS | TARA_NOTIFY_SECRET_KIT_NOTIFY_EMAIL |
| Ryoma | RYOMA_NOTIFY_PLUGINS | RYOMA_NOTIFY_SETTINGS | RYOMA_NOTIFY_SECRET_KIT_NOTIFY_EMAIL |
| Bandum | BANDUM_NOTIFY_PLUGINS | BANDUM_NOTIFY_SETTINGS | BANDUM_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.
- Đă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.
- Chọn Organization và Plugin là
kit-notify-email. - 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. - Chọn các sự kiện muốn nhận rồi lưu.
- Ở menu thao tác của dòng, chọn Send test.
Bạn cũng làm được việc này bằng dòng lệnh:
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-emailXử lý lỗi
| Nội dung lỗi | Nguyên nhân | Cách sửa |
|---|---|---|
settings.host (SMTP server) is missing | Chưa có host | Thêm host |
settings.from must be an email address | from 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ị sai | Dùng một trong ba giá trị |
settings.username is set but the SMTP password is missing | Có 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 password | Tạ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ày | Dù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ặn | Kiểm tra địa chỉ và đường mạng |
STARTTLS with <host> failed (…) | Bắt tay TLS thất bại | Kiểm tra chứng chỉ của máy chủ và cổng |
the SMTP server did not respond | Không có phản hồi trong 20 giây | Kiể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ửi | Sử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
recipientsvà những người liên quan (trừ khisendToPersonlà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.