Cài đặt và sử dụng — Audit Logger

Tổng quan

Plugin cung cấp engine ghi nhật ký kiểm toán phía server. Đây là phần backend (không có giao diện) — ghi lại mọi thao tác dữ liệu (create, update, delete) vào database. Sử dụng kết hợp với plugin-audit-logs để xem log qua giao diện.

Yêu cầu hệ thống

Server Digiforce đang chạy
Database PostgreSQL hoặc MySQL (để lưu audit logs)

Bước 1: Kích hoạt plugin

Vào Settings → Plugin Manager, tìm plugin-audit-logger và bật. Khởi động lại server.

TIP

Nếu bạn muốn xem log qua giao diện, cần bật thêm plugin-audit-logs. Audit Logger chỉ là engine ghi log, không có UI.

Bước 2: Tự động hoạt động

Sau khi bật, plugin tự động đăng ký middleware ghi lại các thao tác dữ liệu:

Thao tác	Dữ liệu ghi lại	Ví dụ
Create	Bản ghi mới và tất cả giá trị	Tạo đơn hàng mới
Update	Giá trị cũ (before) và mới (after) cho mỗi field thay đổi	Sửa trạng thái đơn hàng
Delete	Toàn bộ bản ghi bị xoá	Xoá khách hàng

Cơ chế ghi log

Cấu hình

Tham số	Mặc định	Mô tả
Enabled	`true`	Bật/tắt ghi log toàn cục
Collections	`*` (tất cả)	Danh sách collections cần ghi — dùng `*` để ghi tất cả
Exclude Fields	`password`, `token`	Các field không bao giờ ghi vào log (dữ liệu nhạy cảm)

Bảo mật

Field nhạy cảm như password, token, apiKey tự động bị loại khỏi log. Nếu collection có thêm field nhạy cảm khác (ví dụ: creditCardNumber), hãy thêm vào danh sách Exclude Fields.

Tích hợp vào plugin riêng

Plugin khác có thể gọi audit logger để ghi log cho hành động tuỳ chỉnh:

typescript

const auditLogger = this.app.pm.get('audit-logger');

auditLogger.log({
  action: 'approve-order',
  userId: ctx.state.currentUser.id,
  collectionName: 'orders',
  recordId: orderId,
  changes: {
    status: { from: 'pending', to: 'approved' },
    approvedBy: { from: null, to: currentUser.name },
  },
});

Ghi log cho thao tác batch

Plugin hỗ trợ ghi log cho cả thao tác hàng loạt:

typescript

auditLogger.log({
  action: 'bulk-update',
  userId: ctx.state.currentUser.id,
  collectionName: 'products',
  recordIds: [1, 2, 3, 4, 5],
  changes: {
    status: { from: 'draft', to: 'published' },
  },
});

Mối quan hệ với plugin-audit-logs

Plugin	Vai trò	Có giao diện?
`plugin-audit-logger`	Engine ghi log (backend middleware)	Không
`plugin-audit-logs`	Giao diện xem và quản lý log	Có

Hai plugin bổ trợ nhau — audit-logger ghi dữ liệu, audit-logs hiển thị dữ liệu.

Dữ liệu audit log entry

Mỗi log entry chứa thông tin theo mô hình 5W:

Câu hỏi	Field	Ví dụ
Who (Ai?)	`userId`, `username`	User ID 5, "admin"
What (Làm gì?)	`action`, `changes`	`update`, `{ status: pending → approved }`
When (Khi nào?)	`createdAt`	`2024-03-15T10:30:00Z`
Where (Ở đâu?)	`collectionName`, `recordId`	`orders`, ID 1234
How (Bằng cách nào?)	`ip`, `userAgent`	`192.168.1.100`, Chrome

Lưu ý quan trọng

Plugin này là engine ghi log — không có giao diện xem. Dùng kết hợp với plugin-audit-logs
Trường nhạy cảm (password, token) tự động bị loại khỏi log
Hỗ trợ ghi log cho cả thao tác batch (bulk update/delete)
Audit log chiếm dung lượng database — cấu hình retention và cleanup job phù hợp
Thao tác trực tiếp trên database (SQL query) không được ghi log — chỉ ghi log cho thao tác qua API