Operations

@nx/asset không được deploy riêng. Nó ship bên trong host application nào mount nó. Các mối quan tâm vận hành dưới đây giới hạn ở bề mặt asset bên trong các host đó.

1. Deployment

Thuộc tính	Giá trị
Image	N/A — đóng gói vào image host (commerce / finance / ledger)
Replicas	N/A — theo deployment của host
Resources	N/A — tính trong host
Probes	N/A — healthcheck của host bao phủ
Snowflake ID range	N/A — không phát sinh ID
Migration mode	Không — không có schema/migration
Build	bun run rebuild (chỉ phụ thuộc @nx/core)

Traefik labels

N/A — route qua router sẵn có của service host. Route asset xuất hiện dưới base path của host (vd /v1/api/commerce/assets).

2. Observability

Signal	Nguồn	Nơi xem
Logs	host stdout (key-value có cấu trúc)	kubectl logs <host-pod> / Loki, scope AssetController / BanksVNController
Metrics	host /metrics (không có metric riêng cho asset)	host Grafana dashboard
Traces	kế thừa từ host	—
Health	host GET /healthz, GET /readyz	Gateway portal

Dòng log quan trọng

Dòng	Nguồn	Ghi chú
Failed to create MetaLink for %s	AssetController UPLOAD	Tạo MetaLink fail nhưng object đã lưu — bắt vào response, không throw
Failed to delete MetaLink for %s/%s	AssetController DELETE_OBJECT	Object đã xóa nhưng dọn MetaLink fail (async, best-effort)
banks-vn.logo.not_found	BanksVNController	PNG được yêu cầu thiếu trên đĩa → 404

3. Security

Mối quan tâm	Biện pháp
AuthN	Các route /assets ghi (upload/delete/list) + /meta-links yêu cầu BASIC hoặc JWT (verifier của host); route đọc/download + banks-vn là public
AuthZ	MetaLinkController đặt authorize: { skip: true } trên mọi route hiện tại — kiểm tra Casbin tắt cho MetaLink
Path traversal	isValidPath/isValidName (độ sâu tối đa 2) trên tên object; regex logo ngân hàng ^[A-Za-z0-9]+\.png$
Content sniffing	x-content-type-options: nosniff trên mọi stream object/logo
Secrets	S3 creds qua host env (APP_ENV_S3_*); không bao giờ trong code
Caching	registry ngân hàng max-age=3600; logo ngân hàng max-age=604800, immutable
Đặt tên object	Tên object UUID8 ngẫu nhiên ngăn key do client kiểm soát (trừ i18n.json)

4. Runbook

4.1 Lớp Alert

Alert	Trigger	Check	Fix	Escalate
Upload 5xx spike	host 5xx trên /assets/upload	log Failed to create MetaLink / lỗi S3	xác minh S3 reachable + credentials	on-call backend
Object mồ côi	object có mặt, không có MetaLink	dòng log Failed to create MetaLink	tạo lại MetaLink hoặc upload lại	on-call backend
Logo ngân hàng 404	banks-vn.logo.not_found	filename vs resources/banks-vn/*.png	thêm PNG thiếu vào bundle + redeploy host	platform

4.2 Thao tác thường gặp

Thao tác	Lệnh / hành động
Tail log asset	kubectl logs -n <ns> -f deploy/<host> và lọc AssetController
Kiểm tra kết nối S3	check APP_ENV_S3_ENDPOINT reachable từ host pod
Inspect một MetaLink	GET <host>/meta-links?filter=... (JWT/Basic)
List object trong bucket	GET <host>/assets/objects?prefix=... (JWT/Basic)

5. Trang liên quan

• Configuration
• /runbook/ — runbook trung tâm cho sự cố cross-service
• Decisions