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ện | Khi nào | Kênh của | Người nhận |
|---|---|---|---|
submission.pending | Bà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 PhillipCLI | Tài khoản staff của admin console đang hoạt động, có role moderator hoặc super_admin và có email |
submission.approved | Bài được duyệt và phát hành | Tổ chức sở hữu | Tác giả |
submission.returned | Bài bị trả lại, không tính khi tác giả tự rút | Tổ chức sở hữu | Tác giả |
version.published | Version mới của tài nguyên của một tổ chức ra mắt | Tổ chức sở hữu | Kênh chung |
version.yanked | Version 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ại | Tổ chức sở hữu | Tá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.
{"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"]}kindvàkeybắt buộc,kindphả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ả202vớ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àlinktù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à
202vớ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.
| Kit | Kênh | Settings chính |
|---|---|---|
kit-notify-telegram | Nhóm Telegram qua Bot API | chatId, apiUrl |
kit-notify-email | SMTP (STARTTLS, TLS, AUTH PLAIN) | host, from, recipients, sendToPerson, security |
kit-notify-slack | Kênh Slack, qua Incoming Webhook hoặc token bot | channel, apiUrl |
kit-notify-zalo | Zalo Official Account, tin tư vấn tới từng người | userIds, 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ến | Ghi chú |
|---|---|
TARA_NOTIFY_PLUGINS | Danh 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_TOKEN | Token Tara chỉ đọc để tải gói kit. Bắt buộc khi ghim kit từ Tara |
TARA_NOTIFY_URL | Nơ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_KEYS | Khó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_SETTINGS | JSON 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_CACHE | Lệ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.
ph tara notify set acme kit-notify-telegram --set chatId=-1001234567890 --events submission.pending,version.yanked
ph tara notify test acme kit-notify-telegramMuố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.
printf %s "$BOT_TOKEN" | ph tara notify set acme kit-notify-telegram --set chatId=-1001234567890 --secret-stdinKhô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.localhay.internal.TARA_NOTIFY_SETTINGSdo 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ố.
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:
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.