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

Thông báo ​

Tara gửi thông báo qua kit notify, không viết cứng Telegram, email hay Slack. Muốn thêm một kênh mới thì bạn phát hành một kit mới rồi ghim vào cấu hình, không phải sửa Tara. Trang này dành cho quản trị viên: cài kit lên máy chủ, rồi để owner và admin của từng tổ chức chọn kênh riêng.

Tara thông báo những gì? ​

Tara phát năm sự kiện, mỗi sự kiện đi tới kênh của một tổ chức.

Sự kiệnKhi nàoKênh củaNgười nhận
submission.pendingBài gửi vào kho chính thức qua kiểm tra và chờ duyệt (các kho khác không có bước duyệt)Nền tảng PhillipCLITài khoản staff của admin console đang hoạt động, có role moderator hoặc super_admin và có email
submission.approvedBài được duyệt và phát hànhTổ chức sở hữuTác giả
submission.returnedBài bị trả lại, không tính khi tác giả tự rútTổ chức sở hữuTác giả
version.publishedVersion mới của tài nguyên của một tổ chức ra mắtTổ chức sở hữuKênh chung
version.yankedVersion bị thu hồi, do admin hoặc moderator của staff thu hồi, hoặc bị gỡ vì mã độc khi quét lạiTổ chức sở hữuTác giả

Tara chưa lưu ai đang theo dõi tài nguyên nào, nên version.published và version.yanked chỉ đi vào kênh chung của tổ chức. Tài nguyên cộng đồng thuộc về tổ chức của người đã gửi bài.

Nội dung chỉ gồm siêu dữ liệu và liên kết về Portal: tên, version, tác giả, người thao tác. Lý do trả lại và nội dung bài gửi ở lại trên Portal.

Sự kiện từ Bandum và Ryoma ​

Ngoài năm sự kiện của chính mình, Tara còn chuyển sự kiện do Bandum và Ryoma gửi tới cùng các kênh đó, nên hai dịch vụ này không cần kênh riêng. Owner và admin của tổ chức chọn chúng ở Settings, Notifications, trong hai nhóm: Bandum (testing and releases) và Ryoma (usage and delivery).

  • Bandum: bandum.awaiting_test, bandum.rejected, bandum.test_overdue, bandum.ready_for_release, bandum.release_succeeded, bandum.release_failed.
  • Ryoma: ryoma.quota, ryoma.telemetry_gap, ryoma.task_risks, ryoma.digest, ryoma.guardrails.

Bên gửi gọi POST /v1/orgs/{org}/notify/events bằng tài khoản dịch vụ có scope scm (cùng loại token Ryoma dùng cho scm/token). Phiên đăng nhập, token cá nhân hay owner đều bị 403.

json
{"kind":"bandum.rejected","key":"rejected:o/r#12@1731990000","subject":"[Bandum] GH-12 was sent back","text":"...","link":"https://bandum.example/acme/tasks/o/r/12","to":["a@x.com"]}
  • kind và key bắt buộc, kind phải là một trong các sự kiện trên. key (1 đến 300 ký tự) chống gửi trùng: cùng key trong cùng tổ chức trong 30 ngày thì trả 202 với {"queued":0,"duplicate":true} và không gửi gì.
  • subject (tối đa 200 ký tự, một dòng), text (tối đa 4000) và link tùy chọn (URL http hoặc https) được gửi nguyên văn, không thêm tiền tố [Tara].
  • to (tối đa 50 email) được lọc còn thành viên của tổ chức, không phân biệt hoa thường. Địa chỉ khác bị bỏ âm thầm, nên không dùng Tara để gửi thư rác được. Người nhận chỉ có ý nghĩa với kênh gửi tới từng người, như email.
  • Kết quả là 202 với {"queued":N,"duplicate":false}, N là số kênh nhận sự kiện. N bằng 0 khi không kênh nào nhận loại này, hoặc máy chủ chưa ghim kit notify nào.

Tổ chức nền tảng không nhận các sự kiện này.

Kênh có sẵn ​

Tara có sẵn bốn kit thông báo.

KitKênhSettings chính
kit-notify-telegramNhóm Telegram qua Bot APIchatId, apiUrl
kit-notify-emailSMTP (STARTTLS, TLS, AUTH PLAIN)host, from, recipients, sendToPerson, security
kit-notify-slackKênh Slack, qua Incoming Webhook hoặc token botchannel, apiUrl
kit-notify-zaloZalo Official Account, tin tư vấn tới từng ngườiuserIds, apiUrl

Zalo có giới hạn riêng của Zalo OA: tin chỉ gửi được trong 7 ngày sau lần tương tác gần nhất của người nhận với OA và khi họ chưa chặn OA (miễn phí trong 48 giờ đầu, sau đó có phí), còn access token sống ngắn nên người vận hành phải gia hạn trước khi hết expires_in. Vì vậy bạn nên coi Zalo là kênh phụ.

Mỗi kênh có một hướng dẫn từng bước kèm hình. Bạn chọn kênh ở bên dưới.

Cài kit lên máy chủ ​

Máy chủ tải kit từ Tara theo sha256 bạn đã ghim, kiểm chữ ký số và danh sách thu hồi, rồi chạy kit trong một tiến trình Node.js riêng với node --permission. Kit chỉ đọc được thư mục của chính nó, không ghi file, không chạy tiến trình con và không thấy biến môi trường của Tara. Bạn cần Node.js 22.13 trở lên trên máy chủ.

Việc gửi nằm ngoài thao tác của người dùng. Tara xếp thông báo vào hàng đợi cùng giao dịch với thay đổi, nên giao dịch bị hủy thì không có thông báo. Lỗi tạm thời như mạng hay kênh chưa lên được thử lại tối đa 8 lần với khoảng cách tăng dần. Lỗi cấu hình như sai token hay thiếu settings thì dừng ngay và ghi log để admin sửa. Gửi lỗi không bao giờ làm hỏng thao tác duyệt hay gửi bài.

Bạn cấu hình máy chủ bằng các biến sau.

BiếnGhi chú
TARA_NOTIFY_PLUGINSDanh sách tên@version:sha256, cách nhau bằng dấu phẩy. Lấy sha256 trên trang tài nguyên. Để trống thì Tara không gửi gì
TARA_NOTIFY_TOKENToken Tara chỉ đọc để tải gói kit. Bắt buộc khi ghim kit từ Tara
TARA_NOTIFY_URLNơi tải gói kit, mặc định là TARA_PUBLIC_URL. Đặt địa chỉ nội bộ nếu API không tự gọi được địa chỉ công khai
TARA_NOTIFY_KEYSKhóa công khai ed25519:<base64> để kiểm chữ ký kit, mặc định là khóa ký của chính Tara
TARA_NOTIFY_SETTINGSJSON settings mặc định cho từng kit, ví dụ host và địa chỉ gửi của email
TARA_NOTIFY_SECRET_<TÊN_KIT>Bí mật dùng chung của nền tảng cho kit, ví dụ TARA_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM cho token bot. Tổ chức chưa có bí mật riêng sẽ dùng cái này
TARA_NODE_BIN, TARA_PLUGIN_CACHELệnh Node.js (mặc định node) và thư mục giải nén kit

Các bí mật dùng chung chỉ nằm trong môi trường của máy chủ. Trên Kubernetes bạn đặt chúng trong Secret của chart, và các biến không bí mật đi qua config.* hoặc api.extraEnv. Cả tara-api (gửi thử) lẫn worker (gửi thật) đều đọc cùng cấu hình này.

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

Owner hoặc admin của tổ chức chọn kênh riêng cho tổ chức mình, sau khi đăng nhập bằng phiên trình duyệt. Trên Portal, bạn mở menu tài khoản, chọn Admin, mở Notifications, chọn kit đã ghim, nhập cấu hình riêng như chatId, chọn các sự kiện muốn nhận rồi bấm gửi thử. Kênh của kho chính thức (tổ chức nền tảng) do super_admin quản lý ở trang Notifications của admin console, không ở Portal.

Bằng dòng lệnh, bạn xem kênh hiện có bằng ph tara notify, đặt kênh bằng ph tara notify set, và gửi thử hay gỡ bằng ph tara notify test và ph tara notify remove.

bash
ph tara notify set acme kit-notify-telegram --set chatId=-1001234567890 --events submission.pending,version.yanked
ph tara notify test acme kit-notify-telegram

Muốn kênh có bí mật riêng (token bot, webhook), thêm --secret-stdin: Phillip đọc một dòng từ stdin, hoặc hỏi ẩn ký tự khi chạy trong terminal. Bí mật không nhận qua đối số và không bao giờ được in ra.

bash
printf %s "$BOT_TOKEN" | ph tara notify set acme kit-notify-telegram --set chatId=-1001234567890 --secret-stdin

Không có --secret-stdin thì giữ bí mật hiện có. --clear-secret xoá bí mật riêng, kênh sẽ dùng bí mật dùng chung của máy chủ nếu có (hai cờ không dùng chung được). ph tara notify list cho thấy nguồn bí mật của từng kênh: own secret, platform hoặc missing, cùng tên các sự kiện dùng cho --events.

Settings của tổ chức ghi đè settings mặc định của máy chủ. Tara từ chối tên setting giống bí mật như token, secret hay password: bí mật có ô riêng, nói ở phần sau. Mọi thay đổi kênh được ghi vào nhật ký, nhưng không kèm giá trị settings. Endpoint tương ứng của API chứa cấu hình kênh nên không công bố trong tham chiếu API.

Bí mật riêng của tổ chức ​

Trên Tara đặt sẵn, mỗi tổ chức tự dán token bot, webhook, access token hay mật khẩu SMTP của mình vào form Notifications, không phụ thuộc vào bot dùng chung của nền tảng.

  • Bí mật được mã hóa bằng cùng khóa với secret SSO (TARA_SECRET_KEY, hoặc Vault Transit) rồi lưu trong cơ sở dữ liệu. Máy chủ không có khóa thì lưu bí mật báo lỗi "This server has no key to store secrets (TARA_SECRET_KEY)". Bản mã gắn với tổ chức và kit, chép sang chỗ khác không dùng được.
  • Bí mật chỉ ghi. API không bao giờ trả về (chỉ báo hasSecret), nó không xuất hiện trong log hay nhật ký, và không nằm trong dữ liệu tổ chức xuất ra. Để trống ô nhập là giữ bí mật đã lưu; Remove xóa nó. Xóa tổ chức thì dòng kênh bị xóa theo.
  • Với mỗi kit, máy chủ báo có TARA_NOTIFY_SECRET_<TÊN_KIT> hay không (không lộ giá trị). Kit cần bí mật mà không có cả bí mật riêng lẫn bí mật dùng chung thì không lưu được.
  • Nếu không giải mã được bí mật đã lưu (ví dụ khóa đã đổi), việc gửi báo lỗi cấu hình và không thử lại. Bạn dán lại bí mật.

Setting về đích kết nối cần bí mật riêng ​

Những setting nói gửi tới đâu hay kết nối thế nào chỉ đặt được ở kênh có bí mật riêng. Nếu không, một tổ chức có thể trỏ apiUrl hay host về máy của mình và nhận được bí mật dùng chung của nền tảng. Một tên được tính là setting về đích khi chứa url, uri, host, port, endpoint, server, security, tls, from, helo hoặc proxy (không phân biệt hoa thường), hoặc kết thúc bằng user hay username. Các tên như recipients, chatId, channel, userIds, sendToPerson không bị ảnh hưởng.

  • Kênh dùng bí mật của nền tảng không đặt được các setting này. Lưu sẽ báo "apiUrl can only be set together with your own secret", và dòng cũ còn chúng thì bị bỏ qua khi gửi (ghi log một lần). Máy chủ mail và địa chỉ gửi lấy từ TARA_NOTIFY_SETTINGS.
  • Kênh có bí mật riêng đặt được, nhưng giá trị không được trỏ tới localhost, mạng nội bộ, địa chỉ link-local hay metadata của đám mây, CGNAT, hoặc tên kết thúc bằng .local hay .internal. TARA_NOTIFY_SETTINGS do bạn đặt nên không bị kiểm, vì vậy Mailpit local vẫn chạy khi phát triển.
  • Tara chỉ kiểm giá trị lúc lưu. Một tên miền công khai về sau trả về địa chỉ nội bộ (DNS rebinding) thì không bắt được, nên bạn cũng cần giới hạn lưu lượng đi ra của API và worker ở tầng mạng.

Kiểm tra kit bằng ph kit check ​

Trước khi ghim một kit vào máy chủ, bạn thử nó từ máy của mình. Token đưa qua biến PHILLIP_KIT_TOKEN, không đưa qua tham số.

bash
PHILLIP_KIT_TOKEN=... ph kit check kit-notify-telegram --set chatId=-1001234567890 --send "test"

Lệnh kiểm hợp đồng và settings bắt buộc. Thêm --send thì lệnh gửi một thông báo thật tới kênh, và --live gọi check() để xác nhận token và đích gửi mà không gửi gì. Webhook của Slack không có API kiểm tra mà không gửi, nên với kênh này check() chỉ kiểm định dạng, và bạn cần --send để thử thật.

Cảnh báo từ Bandum ​

Bandum cũng gửi cảnh báo qua kit notify và không chứa mã của nhà cung cấp nào. Khi chưa cấu hình, Bandum chỉ ghi cảnh báo vào log. Bạn khai kit bằng biến môi trường, và mỗi môi trường chọn kit cùng version riêng:

sh
BANDUM_NOTIFY_PLUGINS=kit-notify-telegram@<version>:<sha256 của gói> # cả hai lấy trên trang tài nguyên Tara
BANDUM_NOTIFY_SETTINGS={"kit-notify-telegram":{"chatId":"-100123"}}
BANDUM_NOTIFY_SECRET_KIT_NOTIFY_TELEGRAM=<token bot>

Bandum tải gói bằng BANDUM_TARA_TOKEN, rồi kiểm sha256, chữ ký và danh sách thu hồi trước khi chạy.

Cài từng kênh ​

Đọc thêm ​