Tối ưu Slow Query PostgreSQL: Khi một dòng code cứu cả hệ thống

Bối cảnh

Trong một dự án e-commerce gần đây, tôi gặp một bài toán rất quen thuộc:
trên trang chi tiết đơn hàng, cần có nút:

• “Đơn tiếp theo” (Next)
• “Đơn trước đó” (Previous)

Yêu cầu tưởng đơn giản, nhưng có một constraint quan trọng:
không được load toàn bộ danh sách lên RAM.

Giải pháp hiển nhiên là dùng Keyset Pagination (cursor-based), thay vì offset pagination.

Cách triển khai ban đầu

Dữ liệu được sort theo:

• paid_at (thời điểm thanh toán)
• id (để break tie)

Code Laravel Eloquent ban đầu của tôi cho “Next Order” trông như sau:

->where(function (Builder $q) use ($order) {
    $q->where('paid_at', '>', $order->paid_at)
        ->orWhere(function (Builder $q1) use ($order) {
            $q1->where('paid_at', $order->paid_at)
                ->where('id', '>', $order->id);
        });
})
->orderBy('paid_at')
->orderBy('id')

Nếu đọc bằng “tiếng người”, logic này hoàn toàn đúng:

Lấy các đơn có paid_at lớn hơn,
hoặc nếu cùng thời điểm thì id phải lớn hơn.

Vấn đề thực tế xảy ra

Khi dữ liệu tăng lên vài triệu bản ghi, hệ thống bắt đầu:

• xuất hiện slow query
• query plan chuyển sang:
  • Bitmap Heap Scan
  • hoặc tệ hơn là Seq Scan

Trong khi đó, database đã có composite index:

(paid_at, id)

=> Về lý thuyết phải chạy rất nhanh.

Nguyên nhân cốt lõi

Thủ phạm nằm ở mệnh đề OR.

PostgreSQL Query Planner khi gặp OR thường:

• tách điều kiện thành nhiều nhánh
• không tận dụng được composite index một cách hiệu quả
• dẫn tới scan nhiều hơn cần thiết

Nói đơn giản:
Index có, nhưng không được dùng đúng cách.

Cách giải quyết (và là điểm “aha moment”)

Thay vì viết điều kiện dạng boolean phức tạp,
ta sử dụng Tuple Comparison (Row Value Syntax) của PostgreSQL.

Thay đổi duy nhất:

->whereRaw('(paid_at, id) > (?, ?)', [$order->paid_at, $order->id])

Với “Previous”:

->whereRaw('(paid_at, id) < (?, ?)', [$order->paid_at, $order->id])

Vì sao cách này hiệu quả?

Composite index (paid_at, id) trong PostgreSQL được sắp xếp theo kiểu:

từ điển (lexicographical order)

Tức là:

1. So sánh paid_at
2. Nếu bằng nhau → so sánh id

Khi bạn viết:

(paid_at, id) > (x, y)

PostgreSQL có thể:

• map trực tiếp vào B-Tree index
• nhảy đúng vị trí (x, y)
• thực hiện Index Scan tuyến tính

=> Không cần phân nhánh logic như OR nữa.

Kết quả

Sau khi thay đổi:

• Query Plan chuyển thành Index Scan
• Slow query biến mất
• Thời gian response ổn định lại

Ngoài ra còn một lợi ích “không ngờ”:

Code gọn hơn rất nhiều

Từ:

• nhiều closure lồng nhau
• logic khó đọc

=> còn:

->whereRaw('(paid_at, id) > (?, ?)', [...])

Bài học rút ra

1. Tránh OR khi làm keyset pagination

Đặc biệt khi:

• sort theo nhiều cột
• đã có composite index

2. Hiểu cách database tổ chức index quan trọng hơn ORM

ORM giúp code “đẹp”, nhưng:

không đảm bảo query tối ưu

Đôi khi, quay về RAW SQL đúng chỗ lại là lựa chọn tốt hơn.

3. Tận dụng Tuple Comparison trong PostgreSQL

Đây là một feature rất mạnh nhưng ít được dùng:

(col1, col2) > (val1, val2)

Rất phù hợp cho:

• keyset pagination
• multi-column sorting

Kết luận

Một thay đổi nhỏ:

• bỏ OR
• dùng tuple comparison

=> có thể:

• giảm load database
• tránh slow query
• đơn giản hoá code

Đây là một ví dụ điển hình cho việc:

tối ưu performance không phải lúc nào cũng cần rewrite lớn — đôi khi chỉ cần hiểu đúng cách database hoạt động.

The post Tối ưu Slow Query PostgreSQL: Khi một dòng code cứu cả hệ thống appeared first on Tomoshare.

Một hướng dẫn thực tế dành cho các dự án Laravel + Inertia.js + Vue 3 chạy trong Docker với Nginx, tập trung vào SEO kỹ thuật (technical SEO) và hiệu năng.

1. Tổng quan kiến trúc

Một stack phổ biến hiện nay:

• Backend: Laravel
• Frontend: Vue 3 thông qua Inertia.js (SPA-like)
• Web server: Nginx
• Môi trường: Docker / Docker Compose

Vấn đề lớn nhất với SEO trong mô hình này:

• Nội dung render phía client (CSR)
• Bot Google có thể crawl được JS nhưng chậm và không ổn định
• Thiếu metadata động
• TTFB cao nếu cấu hình Docker/Nginx chưa tối ưu

Mục tiêu:

Làm cho website crawl được – index đúng – load nhanh – metadata đầy đủ.

2. Hiểu đúng về SEO với Inertia.js

Inertia.js không phải SPA thuần, mà là:

• Server vẫn trả HTML gốc
• Vue render phía client

Tuy nhiên:

• Nội dung chính vẫn xuất hiện sau khi JS chạy
• SEO chấp nhận được, nhưng chưa tối ưu nếu không cấu hình thêm

3. Thiết lập metadata động (cực kỳ quan trọng)

3.1 Dùng Head API của Inertia

import { Head } from '@inertiajs/vue3';

<template>
  <Head>
    <title>{{ title }}</title>
    <meta name="description" :content="description" />
    <meta property="og:title" :content="title" />
    <meta property="og:description" :content="description" />
  </Head>
</template>

3.2 Truyền dữ liệu từ Laravel Controller

return Inertia::render('Post/Show', [
    'title' => $post->title,
    'description' => Str::limit($post->content, 160),
]);

4. Render HTML ban đầu đầy đủ hơn (Preload data)

Kích hoạt SSR (Server Side Rendering) cho Inertia

Đây là bước giúp SEO nhảy vọt.

Cài SSR (tham khảo chi tiết ở phần 1)

npm install @inertiajs/server

php artisan inertia:start-ssr

Laravel sẽ:

• Render HTML phía server
• Bot Google thấy ngay nội dung

Lợi ích

5. Cấu hình Nginx chuẩn SEO + hiệu năng

5.1 Bật gzip / brotli

gzip on;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript;

5.2 Cache static files

location ~* \.(js|css|png|jpg|jpeg|gif|svg|webp)$ {
    expires 30d;
    access_log off;
}

5.3 HTTP Headers SEO

add_header X-Content-Type-Options nosniff;
add_header X-Frame-Options SAMEORIGIN;
add_header X-XSS-Protection "1; mode=block";

6. Docker tối ưu cho SEO (TTFB thấp)

6.1 Sử dụng PHP-FPM production

FROM php:8.2-fpm-alpine

6.2 OPcache

opcache.enable=1
opcache.memory_consumption=256
opcache.max_accelerated_files=20000

6.3 Docker Compose network nội bộ

Tránh expose không cần thiết, giảm latency.

7. Sitemap & robots.txt tự động trong Laravel

7.1 Cài package

composer require spatie/laravel-sitemap

7.2 Tạo sitemap

SitemapGenerator::create(config('app.url'))
    ->writeToFile(public_path('sitemap.xml'));

7.3 robots.txt

User-agent: *
Allow: /
Sitemap: https://domain.com/sitemap.xml

8. Schema.org (Rich snippets)

Thêm JSON-LD trong Inertia Head:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "{{ title }}"
}
</script>

9. Kiểm tra SEO

Công cụ nên dùng

• Google Search Console
• PageSpeed Insights
• Lighthouse
• Screaming Frog

KPI nên theo dõi

• LCP < 2.5s
• CLS < 0.1
• TTFB < 500ms
• Index coverage

10. Checklist nhanh

✅ Inertia Head metadata

✅ SSR enabled

✅ Gzip + cache static

✅ Sitemap.xml

✅ robots.txt

✅ JSON-LD

✅ Docker optimized

✅ OPcache

11. Kết luận

Laravel + Inertia.js + Vue 3 hoàn toàn SEO tốt nếu:

• Có SSR
• Metadata đúng
• Server nhanh
• Cấu hình Nginx & Docker chuẩn

SEO không chỉ là content – mà là kiến trúc hệ thống.

Nếu bạn đang chạy dự án Laravel Inertia trên Docker và muốn audit SEO chuyên sâu (TTFB, crawlability, SSR setup), bạn có thể mở rộng thêm:

• Redis cache
• Full page cache cho bot
• Edge caching (Cloudflare)
• Prerender.io cho bot

Chúc bạn tối ưu SEO thành công

The post Tối ưu SEO cho Laravel Inertia.js với Vue 3 + Docker + Nginx (Phần 2) appeared first on Tomoshare.

Bạn có đang “đau đầu” vì một câu query SQL, dù rất đơn giản, lại chạy mãi không xong trên một bảng dữ liệu ngày càng “béo phì”? Bạn là dev đang săn lùng từng mili giây hiệu suất, là tester đang vật lộn với những bài test performance, hay đơn giản là người mới tò mò về thế giới dữ liệu?

Nếu câu trả lời là “có”, thì đây chính là “liều thuốc” bạn cần.

Hãy quên đi những định nghĩa khô khan. Hôm nay, chúng ta sẽ khám phá SQL Partitioning – một kỹ thuật “chia để trị” đầy quyền năng – qua những ví dụ đời thường và những bí kíp thực chiến mà bạn sẽ không tìm thấy trong sách vở.

1. SQL Partitioning Là Gì?

Trước hết, Hãy tưởng tượng database của bạn là một cái nhà kho khổng lồ, chứa hàng triệu món đồ (dữ liệu). Khi cần tìm một món đồ, bạn phải chạy khắp cái nhà kho đó. Rất mất thời gian!

Tuy nhiên, nếu bạn chia nhà kho thành các gian nhỏ có nhãn rõ ràng, mọi thứ sẽ khác.

SQL Partitioning chính là việc bạn thông minh sắp xếp nhà kho đó thành các gian hàng nhỏ hơn, được dán nhãn rõ ràng (gọi là các partition – phân vùng):

• Gian hàng “Hóa đơn năm 2023”
• Gian hàng “Hóa đơn năm 2024”
• Gian hàng “Hóa đơn năm 2025”

CREATE TABLE invoice (
    invoice_id INT,
    invoice_date DATE,
    amount DECIMAL(10,2)
)
PARTITION BY RANGE (YEAR(invoice_date)) (
    PARTITION p2022 VALUES LESS THAN (2023),
    PARTITION p2023 VALUES LESS THAN (2024),
    PARTITION p2024 VALUES LESS THAN (2025),
    PARTITION p_future VALUES LESS THAN MAXVALUE
);

Khi sếp yêu cầu bạn tìm hóa đơn tháng 12/2024, bạn chỉ việc đi thẳng đến gian hàng “Hóa đơn năm 2024” để tìm. Nhanh hơn gấp bội!

Quan trọng hơn, dù dữ liệu được chia nhỏ ra bên dưới, đối với ứng dụng của bạn nó vẫn là một bảng duy nhất. Đó chính là sự “thần kỳ” của partition.

Lợi ích VÀNG của Partitioning:

• Tăng tốc độ truy vấn “tên lửa”: Khi bạn lọc dữ liệu theo “nhãn” của gian hàng (ví dụ: WHERE OrderDate BETWEEN '2024-01-01' AND '2024-12-31'), hệ thống sẽ chỉ quét gian hàng “2024”, bỏ qua toàn bộ các gian hàng khác. Đây gọi là kỹ thuật Partition Pruning (cắt tỉa phân vùng).
• Quản lý dữ liệu dễ như trở bàn tay: Muốn xóa toàn bộ dữ liệu năm 2020? Thay vì chạy lệnh DELETE hàng triệu dòng và chờ “dài cổ”, bạn chỉ cần “dỡ” cả gian hàng 2020 đi. Xong!
• Bảo trì nhẹ nhàng hơn: Việc bảo trì (như rebuild index) trên một gian hàng nhỏ sẽ nhanh và ít ảnh hưởng đến hệ thống hơn là làm trên cả cái nhà kho.

2. Các “Loại Vũ Khí” Phân Vùng Phổ Biến: Chọn Đúng, Thắng To

Có 3 loại partitioning chính. Việc chọn đúng loại sẽ quyết định sự thành bại của bạn.

RANGE Partitioning (Phân vùng theo Khoảng)

• Ý tưởng: Chia dữ liệu theo một khoảng giá trị liên tục.
• Ví dụ Kinh điển: Phân vùng bảng Sales theo cột OrderDate. Mỗi phân vùng chứa dữ liệu của một tháng hoặc một quý.
• Khi nào dùng: Cực kỳ hoàn hảo cho dữ liệu chuỗi thời gian (time-series) như logs, giao dịch, dữ liệu cảm biến IoT.

LIST Partitioning (Phân vùng theo Danh sách)

• Ý tưởng: Chia dữ liệu theo một danh sách các giá trị cụ thể.
• Ví dụ Kinh điển: Phân vùng bảng Customers theo cột Region (Vùng miền). Một phân vùng cho ‘Miền Bắc’, một cho ‘Miền Trung’, một cho ‘Miền Nam’.
• Khi nào dùng: Phù hợp khi cột phân vùng có một tập hợp các giá trị hữu hạn và rõ ràng (như Tỉnh/Thành, Trạng thái, Loại sản phẩm).

HASH Partitioning (Phân vùng theo Hàm băm)

• Ý tưởng: Tự động phân bổ đều dữ liệu vào một số lượng phân vùng đã định trước.
• Ví dụ Kinh điển: Phân vùng bảng Users theo user_id. Hệ thống sẽ dùng một thuật toán để đảm bảo dữ liệu người dùng được chia đều vào các phân vùng.
• Khi nào dùng: Dùng khi bạn không có cột nào phù hợp cho RANGE hay LIST, và mục tiêu chính là phân tán đều dữ liệu để tránh “điểm nóng”.

3. Bí Kíp Thực Chiến & Những “Cú Lừa” Cần Tránh

Lý thuyết màu hồng, nhưng thực tế thì… không phải lúc nào cũng vậy. Đây là những kinh nghiệm xương máu giúp bạn tránh đi vào “vết xe đổ”.

Hỏi & Đáp Nhanh: Các Lỗi Sai Kinh Điển Khi Dùng Partitioning

Câu hỏi: Tôi đã phân vùng rồi mà query vẫn chậm như rùa. Tôi đã làm sai ở đâu?

Trả lời: Rất có thể bạn đã mắc phải một trong những lỗi sau:

• Chọn sai “Chìa Khóa” (Partition Key): Đây là sai lầm chết người nhất. Nếu các query của bạn không lọc theo cột mà bạn dùng để phân vùng (partition key), thì việc phân vùng hoàn toàn vô dụng. Hệ thống vẫn phải quét tất cả các “gian hàng”.
• “Tham Lam” Chia Quá Nhiều Phân Vùng: Chia nhỏ quá không tốt! Quá nhiều phân vùng sẽ làm tăng gánh nặng quản lý cho database, khiến việc lên kế hoạch truy vấn chậm đi. Vài chục đến vài trăm phân vùng thường là con số hợp lý.
• Dữ Liệu Phân Bổ Không Đều: Nếu 90% dữ liệu của bạn bị dồn vào chỉ một phân vùng, thì lợi ích gần như bằng không. Hãy phân tích dữ liệu trước khi chọn cột phân vùng.
• “Bỏ quên” Index: Partitioning và Indexing là “cặp bài trùng” chứ không phải kẻ thù. Phân vùng giúp giới hạn số lượng dữ liệu cần quét, còn index giúp tìm kiếm nhanh chóng bên trong phân vùng đó.
• Đừng chia quá nhỏ (Over-partitioning)
  Đừng chia mỗi ngày 1 partition nếu bạn có dữ liệu 10 năm (sẽ ra 3650 partitions). Khi partitions quá nhiều:
  • Hệ điều hành quá tải vì mở quá nhiều file.
  • Database tốn tài nguyên để quản lý metadata.
  • Query có thể chậm hơn cả không partition.
  • Lời khuyên: Giữ số lượng partition ở mức hợp lý (dưới 100 thường là con số an toàn cho MySQL, Oracle thì có thể nhiều hơn).
• Cẩn thận với Primary Key: Hầu hết các DB engine (như MySQL) yêu cầu cột dùng để Partition phải nằm trong Primary Key. Điều này có nghĩa là PK của bạn sẽ phải đổi từ (id) sang (id, order_date). Dev team cần lưu ý chỗ này kẻo code logic bị sai.

Kết Luận: Partitioning Là Một Tư Duy, Không Chỉ Là Công Cụ

SQL Partitioning không phải là viên đạn bạc cho mọi vấn đề. Nó là một công cụ quản lý dữ liệu cực kỳ mạnh mẽ ở quy mô lớn, với “tác dụng phụ” tuyệt vời là cải thiện hiệu suất.

Lời khuyên cuối cùng: Đừng vội vàng phân vùng mọi bảng bạn có. Hãy luôn bắt đầu bằng việc tối ưu query và index. Chỉ khi bảng dữ liệu đã thực sự phình to (hàng trăm triệu dòng) và các phương pháp khác đã “bó tay”, đó mới là lúc bạn rút “thanh bảo kiếm” Partitioning ra.

Chúc bạn thành công trên con đường chinh phục dữ liệu!

The post SQL Partitioning: “Chia Để Trị” Dữ Liệu Khổng Lồ appeared first on Tomoshare.

Trong những năm đầu đi làm và có cơ hội làm việc các dự án Nhật, tôi được tham gia vào nhiều dự án phát triển hệ thống quản lý sản xuất.

Qua quá trình đó, tôi nhận ra cách người Nhật tổ chức tài liệu thiết kế phần mềm

— gồm Basic Design và Detail Design

— là nền tảng cốt lõi của toàn bộ quy trình phát triển. Mọi thứ được mô tả chi tiết, có quy tắc, và giúp đội dự án hiểu cùng một ngôn ngữ.

Bài viết này chia sẻ cách hiểu, cấu trúc và phương pháp viết tài liệu thiết kế phần mềm trong môi trường dự án Nhật Bản, dựa trên kinh nghiệm thực tế triển khai nhiều module sản xuất khác nhau.

(Lưu ý: các ảnh trong bài đăng được tham khảo từ nhiều nguồn kỹ thuật trang web Nhật để giúp minh họa rõ hơn cho nội dung)

1. Phân biệt Basic Design và Detail Design

Basic Design (基本設計書) là tài liệu mô tả tổng quan hệ thống: định nghĩa phạm vi, quy tắc nghiệp vụ, và luồng xử lý chính.

Đây là giai đoạn “thiết kế khung”.

Detail Design (詳細設計書) là tài liệu triển khai chi tiết, mô tả rõ cách hệ thống hoạt động bên trong: logic xử lý, cấu trúc dữ liệu, và cách các thành phần giao tiếp với nhau.

Đây là bước “thiết kế chi tiết kỹ thuật”.

Basic Design giúp toàn bộ nhóm hiểu “hệ thống cần làm gì”,

Detail Design giúp kỹ sư nắm rõ “hệ thống sẽ làm như thế nào”.

Hai giai đoạn này gắn liền với nhau và quyết định trực tiếp đến chất lượng dự án.

2. Cấu trúc của Basic Design

Trong dự án Nhật, Basic Design thường có cấu trúc tiêu chuẩn như sau:

• Tên hệ thống và module: ví dụ “生産管理システム (Production Management System)”.
• Tên màn hình hoặc chức năng: ví dụ “P_I201 – 生産指示登録画面 (Màn hình đăng ký lệnh sản xuất)”.
• Mục tiêu: mô tả mục đích nghiệp vụ của chức năng (ví dụ: đăng ký, sửa, xóa lệnh sản xuất theo mã sản phẩm).
• Luồng xử lý tổng quan: trình bày sơ đồ xử lý từ nhập dữ liệu đến lưu trữ và phản hồi.
• Dữ liệu chính: mô tả các bảng liên quan như ProductionOrder, ProductMaster, LineMaster…
• Quy tắc nghiệp vụ: mô tả ràng buộc (ví dụ: ngày chỉ thị không nhỏ hơn ngày hiện tại, số lượng > 0).

3. Cấu trúc chi tiết của Detail Design

Detail Design cụ thể hóa từng nội dung của Basic Design để lập trình viên có thể triển khai chính xác. Dưới đây là cấu trúc thông thường trong dự án Nhật:

3.1. Thông tin chung về màn hình / chức năng

Ví dụ:

Mã chức năng: P_I201

Tên chức năng: 生産指示登録画面 (Màn hình đăng ký lệnh sản xuất)

Người dùng: Bộ phận kế hoạch sản xuất

Mục tiêu: Tạo lệnh sản xuất mới hoặc chỉnh sửa lệnh đã có.

Điều kiện truy cập: Người dùng có quyền “製造指示管理”.

3.2. Mô tả các trường dữ liệu (Field Definition)

Các trường trong màn hình được mô tả chi tiết:

• Tên hiển thị: “生産指示番号 (Mã chỉ thị sản xuất)”
• Kiểu dữ liệu: String
• Bắt buộc: Có
• Giá trị mặc định: Tự sinh theo format YYYYMMDD-nnn
• Nguồn dữ liệu: Sequence từ bảng ProductionOrder
• Mô tả: Mã duy nhất của lệnh sản xuất trong hệ thống

3.3. Mapping dữ liệu (Data Mapping)

Ví dụ:

ProductionOrderNo → ProductionOrder.OrderNo

ProductCode → ProductMaster.ProductCode

PlanDate → ProductionOrder.PlanDate

3.4. Logic xử lý (Processing Logic)

Ví dụ:

Khi người dùng nhấn “登録 (Đăng ký)”

→ kiểm tra dữ liệu đầu vào

→ ghi vào bảng ProductionOrder

→ hiển thị thông báo “登録が完了しました” (Đăng ký thành công).

3.5. Xử lý lỗi và thông báo (Error Handling)

Ví dụ:

ERR201 – Ngày sản xuất nhỏ hơn ngày hiện tại → “生産日が本日より前です。”

ERR202 – Mã sản phẩm không tồn tại → “製品コードが存在しません。”

3.6. Giao diện người dùng (UI Layout) – tham khảo

Mô tả bố cục màn hình:

– Vùng nhập thông tin lệnh sản xuất (sản phẩm, ngày, số lượng)

– Bảng danh sách lệnh đã tạo

– Nút chức năng: Đăng ký / Xóa / Tìm kiếm / Reset

– Điều kiện hiển thị: chỉ bật nút Xóa khi chọn một dòng hợp lệ.

4. Mối liên hệ giữa Basic Design và Detail Design

Ví dụ:

Basic quy định “Ngày chỉ thị không nhỏ hơn ngày hiện tại”

→ Detail cụ thể hóa điều kiện kiểm tra “PlanDate < Today → ERR201”。

5. Kết luận

Việc viết tài liệu Basic Design và Detail Design là kỹ năng quan trọng giúp dự án Nhật Bản duy trì tính chính xác và khả năng bảo trì.

Một tài liệu rõ ràng, thống nhất và có cấu trúc giúp tất cả các bên

— từ kỹ sư, tester, đến quản lý

— phối hợp hiệu quả và hạn chế sai sót.

Nếu Basic Design giúp mọi người hiểu “cái gì cần làm”, thì Detail Design hướng dẫn chi tiết “làm như thế nào”.

Khi hai phần này được liên kết chặt chẽ, dự án sẽ đạt độ ổn định, chính xác và phản ánh đúng tinh thần kỹ lưỡng của kỹ sư Nhật.

The post Basic Design và Detail Design trong dự án Nhật (Giới thiệu) appeared first on Tomoshare.

Trong thế giới thực, điều này thật nực cười. Nhưng trong thế giới lập trình Web và API, tình huống này xảy ra thường xuyên đến mức nó trở thành “cơn đau đầu” kinh niên của giới bảo mật. Nó được gọi là IDOR (Insecure Direct Object Reference) hay BOLA (Broken Object Level Authorization).

Nếu bạn là một Backend Developer, và bạn tin rằng chỉ cần có Authentication (Đăng nhập) là hệ thống đã an toàn, thì bài viết này sẽ thay đổi tư duy lập trình của bạn. Chúng ta sẽ không chỉ nói về bề nổi, mà sẽ đi sâu vào bản chất kiến trúc của lỗi này.

1. Bản chất kỹ thuật của IDOR

IDOR (Insecure Direct Object Reference) không chỉ là một lỗi code, nó là một lỗi về thiết kế Logic (Business Logic Flaw).

Trong danh sách OWASP API Security Top 10, IDOR chính là bản chất của lỗ hổng số 1: API1: 2023 Broken Object Level Authorization (BOLA).

Hiểu sâu hơn, IDOR xảy ra khi 3 điều kiện sau hội tụ:

1. Direct Reference: Ứng dụng để lộ mã định danh nội bộ (Internal Identifier) của đối tượng (như Database Primary Key, Filename) trực tiếp ra ngoài URL hoặc Body request.
2. User Input: Ứng dụng tin tưởng và sử dụng trực tiếp đầu vào này để truy vấn dữ liệu.
3. Missing Authorization: Ứng dụng bỏ qua bước kiểm tra quyền truy cập tại thời điểm truy xuất đối tượng.

Sai lầm phổ biến: Nhiều Dev nhầm lẫn giữa Authentication (Bạn là ai?) và Authorization (Bạn được làm gì?). IDOR xảy ra khi bạn đã qua cửa Authentication, nhưng hệ thống quên kiểm tra Authorization ở mức độ đối tượng (Object-level).

2. Giải phẫu cơ chế tấn công

Hãy mổ xẻ một HTTP Request để thấy IDOR có thể lẩn trốn ở đâu. Không chỉ ở URL Parameter, nó có thể nằm ở Header hoặc Body.

Kịch bản: Ứng dụng Chat cho phép người dùng tải lại lịch sử chat.

Request bình thường:

GET /api/v1/messages/history HTTP/1.1
Host: example.com
Cookie: session_id=abc123xyz...
X-User-ID: 1005  <-- IDOR tiềm ẩn ở Header

1. Hacker quan sát: Thấy Header X-User-ID: 1005 được gửi kèm mỗi request.
2. Thử nghiệm: Hacker dùng Postman hoặc Burp Suite để chặn request, sửa X-User-ID thành 1006.
3. Kết quả: Server, thay vì lấy ID từ session an toàn (Server-side), lại tin tưởng lấy ID từ Header (Client-side) để query database SELECT * FROM messages WHERE user_id = 1006.
4. Hậu quả: Hacker đọc được toàn bộ tin nhắn của người dùng 1006.

IDOR có thể xuất hiện ở:

• URL Path: /users/100/profile
• Query Params: /invoices?id=100
• Body (JSON/XML): POST /api/change-password với body {"user_id": 100, "new_pass": "..."}

3. Tại sao IDOR lại là “Sát thủ thầm lặng”?

IDOR nguy hiểm vì tính “hợp lệ” về mặt cú pháp của nó.

• Vượt mặt WAF (Web Application Firewall): Các tường lửa thường chặn các ký tự lạ như ' OR 1=1 -- (SQL Injection) hay <script> (XSS). Nhưng với IDOR, payload chỉ là một con số: id=1006. Đối với WAF, đây là một con số hoàn toàn sạch và hợp lệ.
• Khó phát hiện bằng Automation Tool: Các máy quét (Scanner) không hiểu ngữ cảnh nghiệp vụ. Nếu máy quét gửi id=1006 và nhận về 200 OK, nó đánh dấu là “Thành công”. Nó không biết rằng dữ liệu trả về đó không thuộc về người đang gửi request. Chỉ có con người (Pentesters) hoặc Unit Test được viết kỹ lưỡng mới phát hiện ra.
• Hệ quả dây chuyền: IDOR thường là bước đệm để leo thang đặc quyền (Privilege Escalation), dẫn đến việc chiếm đoạt toàn bộ hệ thống (Account Takeover).

Sự nguy hiểm của IDOR nằm ở chỗ nó là một lỗ hổng logic, không phải lỗ hổng cú pháp. Các công cụ quét bảo mật tĩnh (SAST) truyền thống thường thất bại trong việc phát hiện IDOR vì chúng không thể hiểu ngữ cảnh “ai sở hữu cái gì” trong một ứng dụng cụ thể. Điều này dẫn đến một nghịch lý: trong khi các lỗ hổng kỹ thuật như SQL Injection đang giảm dần nhờ các framework hiện đại, IDOR vẫn tồn tại dai dẳng và chiếm tỷ lệ cao trong các chương trình săn lỗi nhận thưởng (Bug Bounty), đặc biệt là trong các lĩnh vực y tế, chính phủ và dịch vụ chuyên nghiệp.

4. Phân loại IDOR chuyên sâu.

4.1. Leo thang đặc quyền ngang (Horizontal Escalation)

Đây là dạng phổ biến nhất. Người dùng A truy cập dữ liệu của Người dùng B có cùng vai trò.

• Ví dụ: Xem đơn hàng, tải hóa đơn, xem ảnh riêng tư.
• Rủi ro: Rò rỉ thông tin cá nhân (PII Breach), vi phạm GDPR/CCPA.

4.2. Leo thang đặc quyền dọc (Vertical Escalation)

Người dùng thường (User) tìm cách gọi các API dành riêng cho Quản trị viên (Admin/Manager).

• Ví dụ:
  • Hacker tìm thấy API: POST /api/users/1001/roles.
  • Hacker gửi request với body: {"role": "ADMIN"}.
  • Nếu Backend không check xem “người gọi API này có phải là Super Admin không”, Hacker lập tức trở thành Admin.

4.3. IDOR trên File tĩnh (Static File IDOR)

Tên file thường dễ đoán.

• Ví dụ: https://example.com/uploads/receipts/receipt_001.pdf.
• Hacker viết script lặp từ 001 đến 9999 để tải toàn bộ hóa đơn của hệ thống.

5. Dẫn chứng thực tế: Khi “Ông lớn” cũng mắc sai lầm

5.1. McDonald’s & sự cố McHire (7/2025)

Link: https://research.cgu.edu/icdc/2025/07/01/mcdonalds-july-2025-breach/

Bối cảnh: Hệ thống bị ảnh hưởng là McHire, nền tảng tuyển dụng toàn cầu của McDonald’s, được vận hành bởi đối tác công nghệ bên thứ ba là Paradox.ai. Paradox.ai cung cấp giải pháp chatbot AI tên là “Olivia” để tự động hóa quy trình phỏng vấn, thu thập thông tin ứng viên và lên lịch làm việc. Sự phụ thuộc vào bên thứ ba này đã mở rộng bề mặt tấn công của McDonald’s ra ngoài hạ tầng kiểm soát trực tiếp của họ.   

Nguyên nhân chính
Sự cố xảy ra do kết hợp 2 lỗi nghiêm trọng:

1. Xác thực yếu (Weak Authentication)
   • Một tài khoản admin thử nghiệm của Paradox.ai dùng mật khẩu “123456”, không có MFA.
   • Tài khoản này tồn tại từ 2019, không bị vô hiệu hóa dù có quyền truy cập production.
2. Lỗ hổng IDOR (Missing Object Level Authorization)
   • API backend cho phép truy xuất hồ sơ ứng viên bằng applicant_id.
   • Không kiểm tra quyền truy cập → chỉ cần đổi ID là đọc được dữ liệu của bất kỳ ứng viên nào.
   • Từ 1 tài khoản → mở rộng ra 64 triệu hồ sơ toàn cầu.

Tác động

• Rò rỉ PII: tên, email, số điện thoại, địa chỉ nhà.
• Lộ dữ liệu nhạy cảm: log chat với AI (tính cách, sở thích, thông tin cá nhân).
• Lộ token phiên → có thể giả danh ứng viên.
• Nguy cơ cao cho social engineering, lừa đảo, chiếm tài khoản.

Sự kết hợp giữa quản lý tài khoản kém (tài khoản ma, không MFA) và thiếu kiểm soát quyền API (IDOR) tạo ra “cơn bão hoàn hảo” cho rò rỉ dữ liệu quy mô toàn cầu – một xu hướng cực kỳ đáng báo động trong năm 2025

5.2. Mozilla Firefox Accounts – Lỗ hổng xóa tài khoản (5/2025)

Link: https://hackerone.com/reports/3154983

Bản chất sự cố

• Lỗ hổng IDOR nghiêm trọng trong API xóa tài khoản (/v1/account/destroy).
• Cho phép xóa vĩnh viễn tài khoản người khác mà không cần tương tác từ nạn nhân (zero-click).
• Ảnh hưởng trực tiếp đến Integrity (toàn vẹn) và Availability (sẵn sàng) của dữ liệu.

Nguyên nhân kỹ thuật

• Lỗi Session Misbinding: backend không kiểm tra phiên làm việc có khớp với tài khoản bị xóa hay không.
• API tin vào payload JSON (email, authPW) thay vì session của người gửi request.
• Đây là dạng IDOR ghi/xóa, nguy hiểm hơn IDOR đọc dữ liệu.

Kịch bản khai thác

1. Kẻ tấn công tạo tài khoản Firefox, đăng nhập bằng SSO (Google).
2. Chặn request xóa tài khoản của chính mình.
3. Đổi email trong payload thành email nạn nhân (cũng dùng SSO, chưa set mật khẩu).
4. Gửi request → hệ thống xóa tài khoản nạn nhân.

Tác động

• Mất vĩnh viễn dữ liệu: mật khẩu đã lưu, lịch sử duyệt web, tab, sync data.
• Không thể khôi phục, không cần nạn nhân click hay xác nhận.
• Được đánh giá Critical trên HackerOne.

Bài học cốt lõi: IDOR không chỉ gây rò rỉ dữ liệu (read) mà còn có thể phá hủy dữ liệu (write/delete) nếu backend không ràng buộc chặt chẽ giữa session và đối tượng tài nguyên.

5.3. GitLab – Lỗ hổng Machine Learning Model Registry (2024–2025)

Link: https://hackerone.com/reports/2528293

Bối cảnh

• GitLab triển khai Machine Learning Model Registry để quản lý phiên bản mô hình AI.
• Lỗ hổng được báo cáo từ 5/2024, vá và công bố kéo dài sang 2025, cho thấy độ phức tạp của bảo mật trên nền tảng lớn.
• Sự cố ảnh hưởng trực tiếp đến tài sản trí tuệ AI (model weights, biases).

Nguyên nhân kỹ thuật

• GitLab dùng ID tịnh tiến (1,2,3,…) cho model_id thay vì UUID ngẫu nhiên.
• API tải/xem mô hình không kiểm tra quyền truy cập dự án (Missing Object Level Authorization).
• Đây là IDOR điển hình + thiết kế API kém an toàn.

Cách khai thác

• Kẻ tấn công chỉ cần tài khoản GitLab miễn phí.
• Lặp ID từ 1 → hàng triệu để liệt kê và tải mô hình của dự án khác.
• Không cần brute-force, không cần quyền dự án.

Tác động

• Rò rỉ mô hình ML độc quyền của doanh nghiệp.
• Nguy cơ mất bí mật thương mại, thiệt hại kinh tế lớn trong bối cảnh AI là tài sản cốt lõi.
• Lỗ hổng có thể bị khai thác tự động, quy mô lớn (enumeration).

Bài học cốt lõi: Không dùng ID tịnh tiến cho API công khai. Nó biến IDOR từ lỗ hổng tiềm ẩn thành thảm họa có thể khai thác hàng loạt, đặc biệt nguy hiểm với tài sản AI.

6. Ngăn chặn IDOR hiệu quả (Best Practices)

Khi một tài khoản test có thể mở khóa 64 triệu hồ sơ, một email có thể xóa tài khoản người khác, và một con số tăng dần có thể làm bay cả mô hình AI, thì rõ ràng vấn đề không nằm ở “hacker quá giỏi” — mà ở chỗ chúng ta cần chặn IDOR cho đúng cách.

“Đừng bao giờ tin tưởng Client”. Dưới đây là chiến lược phòng thủ đa lớp (Defense in Depth).

Lớp 1: Kiểm soát truy cập tại tầng Data (Data-Layer Authorization)

Đây là chốt chặn cuối cùng và quan trọng nhất. Mọi câu lệnh truy vấn liên quan đến dữ liệu người dùng phải kèm theo điều kiện về chủ sở hữu.

❌ Code rủi ro (Spring Data JPA):

// Controller
public Order getOrder(@PathVariable Long id) {
    return orderRepo.findById(id); // Chỉ tìm theo ID đơn hàng
}

✅ Code an toàn (Repository Pattern):

// Repository
// Luôn gắn kèm userId vào câu query
@Query("SELECT o FROM Order o WHERE o.id = :id AND o.owner.id = :currentUserId")
Optional<Order> findByIdAndOwner(@Param("id") Long id, @Param("currentUserId") Long userId);

// Service Layer
public Order getOrder(Long id, User currentUser) {
    return orderRepo.findByIdAndOwner(id, currentUser.getId())
        .orElseThrow(() -> new ResourceNotFoundException("Order not found or access denied"));
}

Lớp 2: Kiểm soát truy cập tại tầng Controller (Method-Level Security)

Sử dụng các Annotation bảo mật của Framework (như Spring Security) để chặn ngay từ cửa vào.

✅ Ví dụ với Spring Security (@PreAuthorize):

@GetMapping("/invoices/{id}")
// SpEL: Chỉ cho phép nếu user hiện tại là chủ sở hữu của invoice có id này
@PreAuthorize("@securityService.isOwner(authentication, #id)") 
public Invoice getInvoice(@PathVariable Long id) {
    return invoiceRepo.findById(id);
}

Cách này giúp code business logic sạch hơn, tách biệt logic bảo mật ra khỏi logic nghiệp vụ.

Lớp 3: Làm khó Hacker bằng UUID (Obfuscation)

Thay vì dùng Auto-Increment Integer (1, 2, 3), hãy dùng UUID (Random String: a0eebc99-9c0b...) hoặc các thuật toán băm ID (như Hashids).

• Lợi ích: Chặn đứng tấn công kiểu liệt kê (Enumeration Attack). Hacker không thể viết vòng lặp for (i=0; i<1000; i++) để quét dữ liệu.
• Cảnh báo: UUID KHÔNG THỂ THAY THẾ được Lớp 1 và Lớp 2. Nếu hacker bằng cách nào đó biết được UUID của nạn nhân, IDOR vẫn xảy ra nếu thiếu Authorization check. UUID chỉ là “lớp sương mù”, không phải “bức tường thép”.

Lớp 4: Kiểm thử tự động (Automated Security Testing)

Đừng đợi Pentester tìm lỗi. Hãy viết Test Case cho IDOR.

• Unit Test: Tạo 2 user (Alice, Bob). Đăng nhập bằng Alice, cố gắng request dữ liệu ID của Bob. Assert rằng kết quả trả về phải là 403 Forbidden hoặc 404 Not Found.

7. Kết luận

IDOR không phải là một lỗi kỹ thuật phức tạp, nhưng nó phản ánh sự thiếu sót trong tư duy thiết kế hệ thống.

Hãy nhớ nguyên tắc vàng: Mọi request truy cập dữ liệu đều phải trả lời được hai câu hỏi:

1. Người dùng này là ai? (Authentication)
2. Dữ liệu này có phải của họ không? (Authorization)

Nếu thiếu câu hỏi số 2, chúng ta đang mở toang cánh cửa “phòng 102” cho bất kỳ ai cầm chìa khóa “phòng 101”.

The post IDOR – Lỗ hổng “ngây thơ” nhưng chí mạng trong kiến trúc phần mềm? appeared first on Tomoshare.

Bài này chia sẻ theo góc nhìn hệ thống lớn: ra quyết định kỹ thuật khi số job tăng nhanh, dữ liệu lớn, nhiều worker, CI/CD liên tục, thậm chí realtime.

1. Nguyên tắc số 1: Scheduler phải “nhẹ” — việc nặng đẩy qua queue

Tư duy: Scheduler là “orchestrator”, không phải “executor”.

Scheduler chỉ làm 2 việc:

• Quyết định “đúng giờ thì trigger cái gì”
• Dispatch nhanh, ghi dấu vết (batch metadata)

Việc nặng (DB scan, gọi API, gửi notify hàng loạt, reconcile, billing…) → chạy trong queued jobs + nhiều worker.

Trade-off:

• ✅ Ưu: Scale bằng worker, retry/backoff chuẩn, tách tải khỏi scheduler
• ⚠️ Nhược: Job có thể chạy trễ → phải thiết kế theo “batch time” (xem phần 4)

Sai lầm thường gặp: Nhét logic nặng vào scheduler (closure/command) rồi “đỡ nghẽn” bằng cách tăng CPU. Đến lúc 100 lịch/ngày thì scheduler thành single-point bottleneck.

Ví dụ:

<?php

// routes/console.php
use Illuminate\Support\Facades\DB;
use Illuminate\Support\Facades\Schedule;

// ❌ SAI: Logic nặng trực tiếp trong scheduler
Schedule::call(function () {
    DB::table('recent_users')->chunk(100, function ($users) {
        foreach ($users as $user) {
            // Process payment, send email, update DB...
            // Nếu có 1000 users, scheduler sẽ bị block rất lâu
        }
    });
})->dailyAt('09:00');

// ✅ ĐÚNG: Scheduler chỉ dispatch job
Schedule::job(new ProcessRecentUsersJob)
    ->dailyAt('09:00');

Scheduler chỉ trigger đúng giờ, không bao giờ chạy logic business trực tiếp. Worker sẽ xử lý job trong queue.

2. “Đúng một lần” theo nghĩa business > “đúng một lần” theo nghĩa kỹ thuật

Ở hệ thống lớn, “at least once” là mặc định. Scheduler/queue/worker/retry/deploy đều có thể làm job chạy lại.

Best practice: Thiết kế job theo idempotent:

• Chạy 2 lần vẫn ra kết quả đúng
• Side-effect (charge/send/update) phải có khóa logic hoặc unique key

Dùng lock ở đúng tầng:

• Tầng scheduler: Chống chồng / chạy một server (khi HA)
• Tầng job/business: Lock theo entity/time-window (mới là thứ bảo vệ cuối)

Trade-off:

• Lock nhiều quá → Giảm throughput, dễ nghẽn nếu lock sai granularity
• Lock ít quá → Trùng dữ liệu/side-effect

Sai lầm thường gặp: Tin tuyệt đối vào “chống chồng” của scheduler rồi bỏ qua idempotency. Một ngày deploy “đúng lúc”, bạn sẽ hiểu.

Ví dụ:

Job có idempotency key dựa trên entity_id + batch_time. Concept này áp dụng cho mọi job có side-effect quan trọng. Trong scheduler, bạn chỉ dispatch job với metadata:

<?php

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::job(new ProcessOrdersJob)
    ->dailyAt('09:00');

Job sẽ tự implement idempotency check trong handle() method để đảm bảo không xử lý trùng.

3. Khi nào dùng runInBackground() và khi nào “bắt buộc” dùng queue?

Tôi coi runInBackground() là giải pháp tactical, không phải chiến lược lâu dài.

Dùng runInBackground() khi:

• Task là command/exec tương đối ngắn
• Không cần scale theo tải
• Bạn chỉ cần tránh scheduler bị giữ process quá lâu

Bắt buộc đưa qua queue khi:

• Task có thể chạy vài chục giây/phút
• Task có thể “nở” theo dữ liệu (data grows)
• Task có side-effect quan trọng (payment/notify hàng loạt)
• Cần retry/backoff, rate-limit, phân ưu tiên

Sai lầm thường gặp: “Task đang lâu → thêm runInBackground()” và coi như xong. Thực tế bạn chỉ chuyển nghẽn từ scheduler sang CPU/DB/connections của cùng máy.

Ví dụ:

<?php

// routes/console.php
use Illuminate\Support\Facades\Schedule;

// ✅ Dùng runInBackground cho command nhẹ, không cần scale
Schedule::command('cache:clear')
    ->hourly()
    ->runInBackground();

Schedule::command('emails:send')
    ->dailyAt('02:00')
    ->runInBackground();

// ✅ Bắt buộc dùng queue cho job có side-effect quan trọng
Schedule::job(new SendOrderConfirmationJob)
    ->dailyAt('09:00'); // Không có runInBackground, vì đã là queued job

Chỉ có 2 loại command dùng runInBackground():

1. Maintenance commands (cleanup, cache) — không ảnh hưởng business
2. Monitoring commands — cần chạy nhanh, không cần retry

Tất cả job business đều qua queue để có retry/backoff/scale.

4. Bài toán lớn nhất của hệ queue: Job chạy trễ → lệch cửa sổ dữ liệu

Đây là điểm phân biệt hệ “chạy được” và hệ “chạy đúng”.

Vấn đề:

• Scheduler trigger 09:00, worker chạy 09:04
• Nếu job query theo now() lúc 09:04, bạn vừa:
  • Miss dữ liệu 09:00–09:04 (tùy window)
  • Hoặc duplicate với batch trước

Giải pháp: Scheduler đóng dấu batch time ngay lúc dispatch (tôi hay gọi scheduledAt/batchAt). Job luôn dùng scheduledAt để:

• Tính window dữ liệu
• Log/audit theo batch
• Tạo idempotency key

Trade-off:

• Tốn thêm metadata, thêm “kỷ luật” trong code
• Đổi lại: Batch chạy trễ vẫn đúng cửa sổ, dễ đối soát, dễ replay theo batch

Ví dụ — Pattern batch timestamp:

Concept: Scheduler đóng dấu batch time ngay lúc dispatch. Job nhận batch time và dùng để tính time window, không dùng now().

Sử dụng trong Laravel 12:

<?php

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::job(new ProcessOrdersJob)
    ->dailyAt('09:00');

Job sẽ nhận scheduledAt từ scheduler event và dùng để query đúng time window.

Ví dụ với sub-minute scheduling trong Laravel 12:

Theo Laravel 12.x Sub-Minute Scheduled Tasks:

<?php

// routes/console.php
use Illuminate\Support\Facades\Schedule;

// Laravel 12 hỗ trợ sub-minute scheduling
Schedule::call(function () {
    // Process tasks every 30 seconds
})->everyThirtySeconds();

Lợi ích:

• Job chạy trễ 3 phút vẫn query đúng cửa sổ 09:00–09:01
• Dễ đối soát: “Batch 09:00 đã xử lý bao nhiêu records?”
• Dễ replay: “Chạy lại batch 09:00” → chỉ cần tạo job với jobCreatedAt = 09:00

5. Tách “workload shape”: Phân queue theo ưu tiên, tránh job “rác” ăn tài nguyên job “sống còn”

Một hệ thống lớn sẽ có job kiểu:

• Critical: Billing, payment, cancel, inventory, security
• Default: Vận hành
• Low: Marketing, remind, digest

Best practice: Tách queue theo priority, scale worker theo queue. Đặt rule: Job low không bao giờ được làm chậm job critical.

Trade-off:

• Nhiều queue → Config vận hành phức tạp hơn (supervisor/horizon)
• Nhưng nếu không tách, bạn sẽ gặp kiểu “19h campaign bắn notify” làm nghẽn payment

Lưu ý: Trong scheduler, bạn có thể chỉ định queue khi schedule job:

Theo Laravel 12.x Scheduling Queued Jobs, method job() nhận queue name làm tham số thứ 2:

<?php

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::job(new SendOrderConfirmationJob, 'critical')
    ->dailyAt('09:00');

Hoặc nếu job class đã có property $queue, scheduler sẽ tự động dùng queue đó.

6. “Thundering herd” lúc tròn giờ: Kẻ thù của DB và API

Hệ thống lớn rất hay bị “dồn lịch” vào 00:00, 09:00, 12:00, 19:00…

Best practice:

• Stagger: Dàn đều theo phút/giây
• Nếu bắt buộc tròn giờ: Chia nhỏ thành nhiều job chunk, có rate-limit/backoff
• Không quét toàn bảng: Dùng cursor/chunk theo index, watermark theo batch

Sai lầm thường gặp: Một job “tổng hợp cuối ngày” chạy 00:00 quét cả bảng 50 triệu dòng. Đêm đó DB chết, sáng không ai biết vì không có alert.

Ví dụ — Stagger pattern trong scheduler:

<?php

// routes/console.php
use Illuminate\Support\Facades\Schedule;

// Dàn đều theo phút để tránh thundering herd
$times = ['9:03', '10:03', '11:03', '12:03', '13:03', '14:03', '15:03', '16:03', '17:03', '18:03', '19:03', '20:03', '21:03'];

foreach ($times as $time) {
    Schedule::job(new ProcessHourlyTaskJob)
        ->at($time);
}

7. Observability là bắt buộc: “Không ai biết scheduler fail” = thất bại hệ thống

Scheduler fail nguy hiểm vì nó âm thầm.

Best practice:

• Log theo batch (scheduledAt, job name, duration, result)
• Có alert khi fail (hook/event/ping tùy hệ)
• Có “schedule inventory”: Định kỳ audit lịch chạy (ít nhất kiểm lịch sau deploy)

Trade-off:

• Thêm log/metrics → Tốn công + tốn storage
• Nhưng thiếu nó thì khi sự cố xảy ra, bạn mất nhiều giờ “đào mộ”

Ví dụ — Scheduler hooks trong Laravel 12:

Theo Laravel 12.x Task Hooks:

<?php

// routes/console.php
use Illuminate\Support\Facades\Schedule;

Schedule::command('emails:send')
    ->daily()
    ->before(function () {
        // The task is about to execute...
    })
    ->after(function () {
        // The task has executed...
    })
    ->onSuccess(function () {
        // The task succeeded...
    })
    ->onFailure(function () {
        // The task failed...
    });

Scheduler setup:

# Cron entry
* * * * * cd /path-to-app && php artisan schedule:run >> /dev/null 2>&1

Kiểm tra lịch chạy:

# Laravel 12: Xem tất cả scheduled tasks
php artisan schedule:list

8. CI/CD & Deploy: Đừng để deploy tạo ra double-run / half-run

Ở môi trường deploy liên tục, scheduler/worker cần “graceful”:

Best practice:

• Tránh chạy song song 2 version job logic cho cùng một batch
• Worker restart có kiểm soát; job quan trọng có idempotency key để chịu được retry/duplicate
• Nếu hệ HA nhiều scheduler node: Phải có chiến lược “one server” + shared lock store

Sai lầm thường gặp: Deploy xong “mọi thứ xanh”, nhưng lịch 09:00 bị chạy 2 lần vì 2 scheduler node cùng tick.

Ví dụ — Laravel 12 onOneServer():

Theo Laravel 12.x Running Tasks on One Server:

<?php

// routes/console.php
use Illuminate\Support\Facades\Schedule;

// Nếu có nhiều scheduler server, dùng onOneServer() để chạy chỉ trên 1 server
Schedule::command('emails:send')
    ->daily()
    ->onOneServer(); // Chỉ chạy trên 1 server, dùng cache để lock

Lưu ý: Job vẫn phải idempotent vì:

• Retry khi fail
• Deploy có thể làm job chạy lại
• Worker restart có thể làm job chạy lại

9. Tổ chức code: Khi Kernel.php “phình to”

Khi số lượng lịch tăng, Kernel.php sẽ rất dài (có thể lên 300+ lines).

Best practice — Laravel 12: Tách helper functions theo domain để dễ maintain:

Theo Laravel 12.x Defining Schedules, bạn có thể định nghĩa trong routes/console.php và tách thành helper functions:

<?php

// routes/console.php
use Illuminate\Support\Facades\Schedule;

// Tách theo domain để dễ maintain
schedulePaymentTasks();
scheduleNotificationTasks();
scheduleCleanupTasks();

function schedulePaymentTasks(): void
{
    Schedule::command('payments:process')
        ->dailyAt('09:00');

    Schedule::command('payments:retry')
        ->dailyAt('14:00');
}

function scheduleNotificationTasks(): void
{
    Schedule::command('notifications:send')
        ->hourly();

    Schedule::command('notifications:digest')
        ->dailyAt('20:00');
}

function scheduleCleanupTasks(): void
{
    Schedule::command('cache:clear')
        ->hourly()
        ->runInBackground();
}

Hoặc dùng withSchedule trong bootstrap/app.php và tách thành methods:

<?php

// bootstrap/app.php
use Illuminate\Console\Scheduling\Schedule;

->withSchedule(function (Schedule $schedule) {
    schedulePaymentTasks($schedule);
    scheduleNotificationTasks($schedule);
    scheduleCleanupTasks($schedule);
});

function schedulePaymentTasks(Schedule $schedule): void
{
    $schedule->command('payments:process')->dailyAt('09:00');
    $schedule->command('payments:retry')->dailyAt('14:00');
}

Lợi ích:

• Dễ review: Mỗi function = 1 domain
• Dễ test: Có thể test từng domain riêng
• Dễ ownership: Team có thể own từng domain
• Tránh Kernel.php phình to: Code nằm trong routes/console.php hoặc helper functions

Schedule Groups — Laravel 12:

Theo Laravel 12.x Schedule Groups, bạn có thể nhóm các tasks có cùng cấu hình để tránh lặp lại code:

<?php

// routes/console.php
use Illuminate\Support\Facades\Schedule;

// ❌ SAI: Lặp lại cấu hình cho từng task
Schedule::command('emails:send')
    ->daily()
    ->onOneServer()
    ->timezone('America/New_York');

Schedule::command('emails:prune')
    ->daily()
    ->onOneServer()
    ->timezone('America/New_York');

// ✅ ĐÚNG: Dùng Schedule Groups để nhóm tasks có cùng cấu hình
Schedule::daily()
    ->onOneServer()
    ->timezone('America/New_York')
    ->group(function () {
        Schedule::command('emails:send');
        Schedule::command('emails:prune');
    });

Lợi ích của Schedule Groups:

• Giảm lặp lại code: Không cần lặp lại onOneServer(), timezone(), withoutOverlapping() cho từng task
• Dễ maintain: Thay đổi cấu hình một lần áp dụng cho cả nhóm
• Tăng tính nhất quán: Đảm bảo tất cả tasks trong nhóm có cùng cấu hình

10. Timezone handling: Luôn nhất quán

Best practice: Cố định timezone theo business, không dùng server timezone. Nguyên tắc: Tất cả scheduled tasks phải dùng cùng một business timezone để đảm bảo tính nhất quán.

Ví dụ — Laravel 12 timezone:

Theo Laravel 12.x Scheduling Timezones, có 2 cách set timezone:

Cách 1: Set timezone trong config (khuyến nghị):

Khi tất cả tasks dùng cùng business timezone, thêm schedule_timezone vào config/app.php:

<?php

// config/app.php
return [
    'timezone' => 'UTC', // Application timezone

    'schedule_timezone' => 'Asia/Tokyo', // Business timezone cho scheduled tasks
];

Với cấu hình này, tất cả scheduled tasks sẽ tự động dùng timezone Asia/Tokyo trừ khi được ghi đè bởi method timezone() trong từng task cụ thể.

Cách 2: Set timezone cho từng task riêng:

Chỉ định timezone cho task cụ thể bằng method timezone():

<?php

// routes/console.php
use Illuminate\Support\Facades\Schedule;

// Set timezone cho task cụ thể (ghi đè config)
Schedule::command('report:generate')
    ->timezone('America/New_York')
    ->at('2:00');

Lưu ý quan trọng về DST (Daylight Saving Time):

Theo Laravel 12.x Scheduling Timezones, một số timezone sử dụng DST có thể ảnh hưởng đến thời gian thực thi. Khi DST thay đổi, task có thể chạy 2 lần hoặc không chạy. Nên tránh dùng timezone có DST khi có thể.

Nguyên tắc áp dụng:

• ✅ Nên: Set timezone một lần trong config/app.php với key schedule_timezone nếu tất cả tasks dùng cùng business timezone
• ⚠️ Tránh: Set timezone cho từng task riêng lẻ → dễ quên, dễ sai, khó maintain
• ⚠️ Tránh: Dùng timezone có DST → có thể ảnh hưởng đến thời gian thực thi khi DST thay đổi

Kết luận: Framework cho quyết định kỹ thuật

Khi thêm một scheduled task mới, tôi tự hỏi 6 câu:

1. Task này có side-effect quan trọng không? → Nếu có → Idempotent + audit batch
2. Dữ liệu tăng thì task tăng theo tuyến nào? → Nếu O(N) theo bảng lớn → Phải có watermark/chunk/index
3. Chạy trễ có làm sai cửa sổ dữ liệu không? → Nếu có → Cần scheduledAt/batchAt
4. Có được phép chạy song song không? → Nếu không → Overlap guard + lock theo business key
5. Nó thuộc priority nào? → Nếu không critical → Đừng để nó chạy chung queue với critical
6. Fail thì ai biết, trong bao lâu? → Nếu câu trả lời mơ hồ → Bổ sung observability trước

Checklist áp dụng

•  Scheduler chỉ dispatch queued jobs, không chạy logic nặng
•  Tất cả job có side-effect đều idempotent
•  Job dùng batchTime/scheduledAt để tính time window, không dùng now()
•  Job dùng chunkById hoặc cursor pagination cho data lớn
•  Job có stagger/rate-limit khi gọi external API
•  Job log theo batch time để dễ đối soát
•  Scheduler có helper methods theo domain, không phình to schedule()
•  Timezone nhất quán: Business timezone, không dùng server timezone
•  Queue được phân priority (critical/default/low)
•  Có alert khi scheduler/job fail

Tài liệu tham khảo: Laravel 12.x Task Scheduling

The post Laravel Scheduler: Tư duy thiết kế, trade-off và best practices cho hệ thống lớn appeared first on Tomoshare.

Yêu cầu
・Docker đã cài đặt
・Docker Compose đã cài đặt
・Quyền quản trị hệ thống
・Domain đã trỏ về IP server
・Port 80 và 443 mở và trỏ về server

Thiết lập Nginx Webserver với Let’s Encrypt trên Docker
Quy trình thiết lập gồm các bước sau:・Tạo Docker Compose file
・Cấu hình Nginx server
・Tạo script setup SSL
・Chạy Certbot client
・Tự động gia hạn certificate

Bước 1: Tạo cấu trúc thư mục và .env

Tạo các thư mục cần thiết trong dự án:

mkdir -p docker/nginx/etc/nginx/templates
mkdir -p docker/nginx/etc/nginx/conf
mkdir -p docker/nginx/certs

Cấu trúc thư mục:

docker/
└── nginx/
    ├── setup-ssl.sh
    ├── entrypoint.sh
    ├── etc/nginx/
    │   ├── nginx.conf
    │   ├── conf/
    │   └── templates/
    │       ├── default.conf.template
    │       ├── https.conf.template
    │       └── upstream.conf.template
    └── certs/              # Thư mục chứa certificates (gitignored)

File Structure
・entrypoint.sh: Script tự động generate nginx configs từ templates
・setup-ssl.sh: Script tạo SSL certificate trên host (chạy ngoài container)
・templates/: Nginx config templates
・https.conf.template: HTTPS config cho domain
・upstream.conf.template: PHP-FPM upstream config
・certs/: Thư mục chứa Let’s Encrypt certificates trên host (gitignored, mounted vào container)

Environment Variables

Bước 2: Tạo Dockerfile cho Nginx

Tạo file docker/Dockerfile với multi-stage build:

FROM nginx:1.28.0-alpine as nginx

WORKDIR /var/www/html
COPY docker/nginx/ /
COPY docker/nginx/entrypoint.sh /usr/local/bin/entrypoint.sh
RUN chmod +x /usr/local/bin/entrypoint.sh

EXPOSE 80 443

ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]
CMD ["nginx", "-g", "daemon off;"]

Bước 3: Tạo Docker Compose file

Tạo file docker-compose.yml để chạy Nginx với HTTPS:

services:
  nginx:
    build:
      context: .
      dockerfile: docker/Dockerfile
      target: nginx
    environment:
      ENABLE_BASIC_AUTH: "${ENABLE_BASIC_AUTH-false}"
      PHP_FPM_HOST: app
      PHP_FPM_PORT: 9000
      ENABLE_HTTP_LOCALHOST: "false"
      ENABLE_HTTPS: "true"
      HTTPS_DOMAIN: "${HTTPS_DOMAIN-example.com}"
    ports:
      - "${DOCKER_NGINX_EXTERNAL_PORT-8000}:80"
      - "${DOCKER_NGINX_HTTPS_PORT-8443}:443"
    depends_on:
      - app
      - certbot
    volumes:
      - ".:/var/www/html"
      - "./docker/nginx/certs:/etc/letsencrypt"

  certbot:
    image: certbot/certbot:latest
    volumes:
      - "./docker/nginx/certs:/etc/letsencrypt"
    entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done;'"

  app:
    build:
      context: .
      dockerfile: docker/Dockerfile
      target: app
    volumes:
      - ".:/var/www/html"
    environment:
      PHP_OPCACHE_VALIDATE_TIMESTAMPS: 1
    command: ["development"]

Giải thích:
webserver (nginx): container Nginx với HTTPS
certbot: container tự động gia hạn certificate
app: container Laravel application
Volume ./docker/nginx/certs:/etc/letsencrypt: chia sẻ certificates giữa containers

Bước 4: Tạo file cấu hình Nginx

4.1. Tạo template HTTP (cho Let’s Encrypt validation)
Tạo file docker/nginx/etc/nginx/templates/default.conf.template:

server {
    listen 80;
    server_name _;

    root /var/www/html/public;
    index index.php;

    client_max_body_size 40m;

    access_log /dev/stdout;
    error_log /dev/stderr;

    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    proxy_hide_header X-Powered-By;

    charset utf-8;

    location = /health {
        return 200 'OK!';
        add_header Content-Type text/plain;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location / {
        auth_basic $basic_auth;
        auth_basic_user_file /etc/nginx/.htpasswd;
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location ~ \.php$ {
        set $path_info $fastcgi_path_info;
        fastcgi_index index.php;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        fastcgi_pass php-fpm;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

Lưu ý: Block location ~ /\.(?!well-known).* chặn các file ẩn nhưng cho phép .well-known để Let’s Encrypt validate.

4.2. Tạo template HTTPS
Tạo file docker/nginx/etc/nginx/templates/https.conf.template:

# HTTPS server for ${HTTPS_DOMAIN}
server {
    listen 443 ssl;
    http2 on;
    server_name ${HTTPS_DOMAIN};

    root /var/www/html/public;
    index index.php;

    # SSL configuration
    ssl_certificate /etc/letsencrypt/live/${HTTPS_DOMAIN}/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/${HTTPS_DOMAIN}/privkey.pem;

    client_max_body_size 40m;

    access_log /dev/stdout;
    error_log /dev/stderr;

    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    proxy_hide_header X-Powered-By;

    charset utf-8;

    location = /health {
        return 200 'OK!';
        add_header Content-Type text/plain;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;

    location / {
        auth_basic $basic_auth;
        auth_basic_user_file /etc/nginx/.htpasswd;
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location ~ \.php$ {
        set $path_info $fastcgi_path_info;
        fastcgi_index index.php;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        fastcgi_pass php-fpm;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

        include fastcgi_params;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

# Redirect HTTP to HTTPS for ${HTTPS_DOMAIN}
server {
    listen 80;
    server_name ${HTTPS_DOMAIN};

    location / {
        return 301 https://$host$request_uri;
    }
}

Giải thích:
Server block đầu: HTTPS trên port 443 với HTTP/2
Server block thứ hai: redirect HTTP → HTTPS
Security headers: HSTS, X-Frame-Options, X-Content-Type-Options

Bước 5: Tạo Entrypoint script

Tạo file docker/nginx/entrypoint.sh để tự động generate config từ template:

#!/bin/sh
set -e

# Set BASIC_AUTH_VALUE based on ENABLE_BASIC_AUTH
if [ "$ENABLE_BASIC_AUTH" = "true" ]; then
    export BASIC_AUTH_VALUE="Administrator's Area"
else
    export BASIC_AUTH_VALUE="off"
fi

# Generate map config from template
envsubst '$$BASIC_AUTH_VALUE' < /etc/nginx/templates/map.conf.template > /etc/nginx/conf.d/map.conf

# Generate upstream config
envsubst '$$PHP_FPM_HOST $$PHP_FPM_PORT' < /etc/nginx/templates/upstream.conf.template > /etc/nginx/conf.d/upstream.conf

# Generate nginx configs from templates
if [ "$ENABLE_HTTP_LOCALHOST" = "true" ]; then
    envsubst '$$PHP_FPM_HOST $$PHP_FPM_PORT' < /etc/nginx/templates/localhost.conf.template > /etc/nginx/conf.d/server-localhost.conf
fi

# Handle HTTPS setup
if [ "$ENABLE_HTTPS" = "true" ] && [ -n "$HTTPS_DOMAIN" ]; then
    # Create directories if they don't exist
    mkdir -p /etc/letsencrypt/live/${HTTPS_DOMAIN}

    if [ -f "/etc/letsencrypt/live/${HTTPS_DOMAIN}/fullchain.pem" ]; then
        envsubst '$$PHP_FPM_HOST $$PHP_FPM_PORT $$HTTPS_DOMAIN' < /etc/nginx/templates/https.conf.template > /etc/nginx/conf.d/server-https.conf
    fi
fi

# Execute the main command
exec "$@"

Script này:
・Tạo config từ template dựa trên biến môi trường
・Chỉ tạo HTTPS config nếu certificate tồn tại
・Dùng envsubst để thay thế biến

Bước 6: Tạo script setup SSL

Tạo file docker/nginx/setup-ssl.sh để tạo certificate trên host:

#!/bin/bash
set -e

# Get script directory and project root
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "${SCRIPT_DIR}/../.." && pwd)"

# Configuration
DOMAIN="${HTTPS_DOMAIN:-example.com}"
CERT_DIR="${PROJECT_ROOT}/docker/nginx/certs"

echo "Setting up SSL certificate for ${DOMAIN} on host..."
echo "Certificate will be saved to: ${CERT_DIR}"

# Create directories on host
mkdir -p "${CERT_DIR}"

# Check if certificate already exists
if [ -f "${CERT_DIR}/live/${DOMAIN}/fullchain.pem" ]; then
    echo "Certificate already exists for ${DOMAIN}"
    echo "Location: ${CERT_DIR}/live/${DOMAIN}/"
    exit 0
fi

cd "${PROJECT_ROOT}"

# Request certificate using docker (certificate saved on host, mounted into container)
echo "Requesting certificate (port 80 must be available)..."
docker run --rm \
    -v "${CERT_DIR}:/etc/letsencrypt" \
    -p 80:80 \
    certbot/certbot certonly \
    --standalone \
    --agree-tos \
    -d "${DOMAIN}"

echo ""
echo "Certificate created successfully on host!"
echo "Location: ${CERT_DIR}/live/${DOMAIN}/"
echo "Files: fullchain.pem, privkey.pem"
echo ""
echo "Certificate will be automatically mounted into nginx container."
echo "You can now run: docker-compose up -d"

Lưu ý: Script này chạy trên host, không trong container. Certificate được lưu trên host và mount vào container.

Bước 7: Chạy Certbot để lấy certificate

7.1. Test với dry-run (khuyến nghị)
Trước khi lấy certificate thật, test với --dry-run:

chmod +x docker/nginx/setup-ssl.sh

# Test với dry-run
docker run --rm \
    -v "$(pwd)/docker/nginx/certs:/etc/letsencrypt" \
    -p 80:80 \
    certbot/certbot certonly \
    --standalone \
    --dry-run \
    --agree-tos \
    -d your-domain.com

Lưu ý: Thay your-domain.com bằng domain của bạn.

7.2. Lấy certificate thật

Nếu dry-run thành công, chạy script để lấy certificate:

HTTPS_DOMAIN=your-domain.com ./docker/nginx/setup-ssl.sh

Hoặc dùng domain mặc định:

./docker/nginx/setup-ssl.sh

Quá trình:

1. Script kiểm tra certificate đã tồn tại chưa
2. Nếu chưa, chạy Certbot với –standalone mode
3. Certbot bind port 80 để Let’s Encrypt validate
4. Certificate được lưu tại ./docker/nginx/certs/live/your-domain.com/
   
   Lưu ý:
   ・Đảm bảo port 80 mở và trỏ về server.
   ・Nếu Nginx đang chạy trên port 80, tạm dừng trước khi chạy script.

Bước 8: Khởi động Docker Compose

Sau khi có certificate, khởi động services:

docker-compose up -d

Kiểm tra containers đang chạy:

docker-compose ps

Kiểm tra logs:

docker-compose logs nginx
docker-compose logs certbot

Bước 9: Kiểm tra HTTPS

Truy cập domain qua HTTPS:

curl -I https://your-domain.com:8443

Hoặc mở trình duyệt và truy cập: https://your-domain.com:8443

Bạn sẽ thấy:

・Certificate hợp lệ (không có cảnh báo)

・Tự động redirect HTTP → HTTPS

・Security headers được áp dụng

Bước 10: Gia hạn certificates

Let’s Encrypt certificates có thời hạn 90 ngày. Có 2 cách gia hạn:

10.1. Tự động gia hạn (đã cấu hình)

Service certbot trong docker-compose.yml tự động gia hạn mỗi 12 giờ:

certbot:
  image: certbot/certbot:latest
  volumes:
    - "./docker/nginx/certs:/etc/letsencrypt"
  entrypoint: "/bin/sh -c 'trap exit TERM; while :; do certbot renew; sleep 12h & wait $${!}; done;'"

Certbot chỉ gia hạn khi certificate sắp hết hạn (trong vòng 30 ngày).

10.2. Gia hạn thủ công

Nếu cần gia hạn ngay:

docker run --rm \
    -v "$(pwd)/docker/nginx/certs:/etc/letsencrypt" \
    certbot/certbot renew

Hoặc trong container:

docker-compose exec certbot certbot renew

Sau khi gia hạn, reload Nginx để áp dụng certificate mới:

docker-compose exec nginx nginx -s reload

Hoặc restart container:

docker-compose restart nginx

Troubleshooting

Lỗi: “Port 80 is already in use”

Nguyên nhân: Port 80 đang được sử dụng bởi service khác.

Giải pháp:

# Kiểm tra process đang dùng port 80
sudo lsof -i :80

# Tạm dừng Nginx nếu đang chạy
docker-compose down

# Sau đó chạy lại setup-ssl.sh
./docker/nginx/setup-ssl.sh

Lỗi: “Failed to obtain certificate”

Nguyên nhân:
・Domain chưa trỏ về IP server
・Port 80 bị firewall chặn
・Let’s Encrypt không thể truy cập domain

Giải pháp:

# Kiểm tra DNS
nslookup your-domain.com

# Kiểm tra port 80
curl -I http://your-domain.com

# Kiểm tra firewall
sudo ufw status

Lỗi: “Nginx không load HTTPS config”

Nguyên nhân:
・Certificate chưa tồn tại
・Biến môi trường chưa đúng
・Volume mount sai

Giải pháp:

# Kiểm tra certificate
ls -la docker/nginx/certs/live/your-domain.com/

# Kiểm tra biến môi trường
docker-compose config

# Kiểm tra volume mount trong container
docker-compose exec nginx ls -la /etc/letsencrypt/live/

Tổng kết

Sau khi hoàn thành các bước trên, bạn đã:
・Thiết lập Nginx với HTTPS trên Docker
・Cấu hình Let’s Encrypt SSL/TLS certificates
・Tự động gia hạn certificates
・Redirect HTTP → HTTPS
・Áp dụng security headers

The post Hướng dẫn từng bước thiết lập Let’s Encrypt SSL/TLS cho Nginx trên Docker. appeared first on Tomoshare.

Bảo mật luôn là yếu tố cốt lõi trong quá trình phát triển ứng dụng, đặc biệt khi bạn phải xử lý việc xác thực và phân quyền cho nhiều người dùng khác nhau.

Dù các developer hoàn toàn có thể tự xây dựng hệ thống quản lý danh tính từ con số 0, nhưng việc này tốn rất nhiều thời gian, công sức và dễ phát sinh lỗi – nhất là khi phải hỗ trợ các giao thức tiêu chuẩn như OAuth2 hay OpenID Connect.

Keycloak xuất hiện như một giải pháp giúp đơn giản hóa toàn bộ quá trình này. Nó không chỉ giảm tải việc triển khai xác thực mà còn mang đến sự đồng nhất, bảo mật cao và khả năng tùy biến mạnh mẽ. Bạn có thể tích hợp đăng nhập bằng Google, Facebook hoặc thiết lập SSO chỉ trong vài bước cấu hình mà không cần viết lại cả hệ thống.

1. What? Keycloak là gì?

Keycloak là một nền tảng mã nguồn mở mạnh mẽ, cung cấp giải pháp đăng nhập một lần (SSO) cùng hệ thống quản lý danh tính và quyền truy cập cho các ứng dụng và dịch vụ.

Nền tảng này được thiết kế nhằm đơn giản hóa toàn bộ bài toán bảo mật, giúp developer dễ dàng tích hợp cơ chế đăng nhập, phân quyền và xác thực vào ứng dụng mà không phải xây dựng mọi thứ từ đầu. Tất cả đều được Keycloak cung cấp sẵn dưới dạng các tính năng linh hoạt, dễ tùy chỉnh để phù hợp với nhu cầu của từng doanh nghiệp hay tổ chức.

Keycloak cho phép bạn tùy chỉnh giao diện người dùng cho các trang đăng nhập, đăng ký, quản lý tài khoản hay trang quản trị. Bên cạnh đó, nó còn hỗ trợ tích hợp với các hệ thống quản lý danh tính sẵn có như LDAP hoặc Active Directory, và cho phép xác thực thông qua các nhà cung cấp bên thứ ba như Google hay Facebook.

Tóm lại: đối với developer, Keycloak giống như một “bộ công cụ all-in-one” để giải quyết toàn bộ vấn đề liên quan đến đăng nhập và phân quyền. Thay vì tự xây các tính năng như login, role-based access hay kết nối với các nền tảng bên ngoài, bạn chỉ cần cấu hình và sử dụng những gì Keycloak đã cung cấp.

Luồng hoạt động:
+ Spring Boot kiểm tra Token và cho phép truy cập nếu hợp lệ.
+ User đăng nhập vào Keycloak.
+ Keycloak trả về Token.
+ User gửi request kèm Token đến Spring Boot.

2. Why? Tại sao lại là Keycloak?

Thay vì tự xây dựng module đăng nhập (Login) trong Spring Boot, việc sử dụng Keycloak mang lại các lợi ích:

a. Quản lý tập trung: Admin có thể khóa user, đổi password, cấp quyền ngay trên giao diện Keycloak mà không cần sửa code hay database của ứng dụng.

b. Bảo mật chuyên sâu (Delegated Authentication): Việc xử lý mật khẩu, mã hóa, 2FA (xác thực 2 bước) được Keycloak đảm nhận. Spring Boot không cần lo về lộ mật khẩu.

c. Single Sign-On (SSO): Nếu bạn có 10 ứng dụng (Microservices), user chỉ cần đăng nhập 1 lần tại Keycloak là vào được cả 10 ứng dụng.

d. Chuẩn hóa (Standardization): Sử dụng giao thức OAuth2 và OpenID Connect chuẩn quốc tế. Dễ dàng tích hợp với Frontend (React, Angular, Mobile App).

3. Các thành phần chính trong Keycloak

3.1. Realm (Không gian quản lý)

Định nghĩa: Realm là một không gian quản lý định danh hoàn toàn độc lập. Dữ liệu (user, role, client) của Realm A hoàn toàn tách biệt với Realm B.

Master Realm: Khi cài đặt xong, Keycloak có sẵn realm tên là Master. Đây là realm dùng để quản trị hệ thống Keycloak. Không nên dùng realm này để quản lý user cho ứng dụng của bạn.

Ví dụ: Bạn có thể tạo Realm Users cho người dùng cuối và Realm Admins cho site quản trị.

3.2. Client (Ứng dụng khách)

Định nghĩa: Client là các ứng dụng hoặc dịch vụ muốn sử dụng Keycloak để xác thực. Client đại diện cho các ứng dụng hoặc dịch vụ được bảo mật bởi Keycloak. Mỗi client có cấu hình riêng, bao gồm giao thức (OAuth2, OpenID Connect), URL callback, và thông tin bảo mật như client secret.

3.3. User (Người dùng)

Định nghĩa: Thực thể có thể đăng nhập vào hệ thống.

Thuộc tính: User có Username, Password, Email, và các thuộc tính tùy chỉnh (Attributes) như số điện thoại, mã nhân viên, phòng ban…

Keycloak hỗ trợ các phương thức xác thực đa dạng:
– Đăng nhập bằng email/mật khẩu.
– Đăng nhập qua các nhà cung cấp bên thứ ba (Google, Facebook).
– Xác thực hai yếu tố (2FA).

3.4. Role (Vai trò)

Role dùng để phân quyền (Authorization). Có 2 loại Role trong Keycloak:
– Realm Role: Role toàn cục. Ví dụ: Global_Admin, User. Có hiệu lực trên toàn bộ Realm.
– Client Role: Role gắn liền với một Client cụ thể. Ví dụ: Client Inventory-App có role stock-keeper. Role này chỉ có ý nghĩa với app kho, không có ý nghĩa với app nhân sự.

3.5. Group (Nhóm)

Định nghĩa: Dùng để gom nhóm các User lại.

Đặc điểm: Group có thể lồng nhau (Parent – Child). Ví dụ: IT Department -> Dev Team.

Tác dụng: Bạn có thể gán Role cho Group, tất cả User trong Group đó sẽ tự động kế thừa Role. Giúp quản lý quyền hạn dễ dàng hơn gán lẻ tẻ.

4. How? Làm thế nào để tích hợp Keycloak vào 1 ứng dụng Spring Boot chỉ trong vài bước đơn giản.

Phần A: Cấu hình Keycloak (Docker)
Bước 1: Khởi chạy Keycloak Mở terminal và chạy lệnh Docker (bản developer):

docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:24.0.1 start-dev

Bước 2: Thiết lập Realm và Client

1. Truy cập http://localhost:8080 -> Vào Administration Console (Login: admin/admin).
2. Tạo Realm: Bấm vào dropdown menu góc trái -> Create Realm -> Tên: springboot-demo.
3. Tạo Client:
   – Vào menu Clients -> Create client.
   – Client ID: my-backend-api.
   – Capability config: Bật Client authentication (để có Client Secret) và Authorization.
   – Lưu lại.
4. Tạo Roles:
   – Vào menu Realm roles -> Create role.
   – Tạo 2 role: USER và ADMIN.

Phần B: Lập trình Spring Boot (Resource Server)
Bước 1: Dependencies (pom.xml) Cần Java 17+ và Spring Boot 3.x.

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <!-- Thư viện quan trọng nhất để biến App thành Resource Server -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

Bước 2: Cấu hình (application.yml) Khai báo địa chỉ của Keycloak để Spring Boot biết nơi xác thực token.

server:
  port: 5000 # Chạy port khác Keycloak

spring:
  application:
    name: keycloak-integration-demo
  security:
    oauth2:
      resourceserver:
        jwt:
          # Đường dẫn Issuer của Realm (Quan trọng)
          # Cấu trúc: http://<host>:<port>/realms/<realm-name>
          issuer-uri: http://localhost:8080/realms/springboot-demo
          # jwk-set-uri sẽ được tự động cấu hình từ issuer-uri

Bước 3: Class SecurityConfig.java (Quan trọng nhất) Mặc định Keycloak trả về role trong JSON phức tạp, ta cần convert nó về dạng ROLE_ABC để Spring Security hiểu.

package com.example.demo.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import 
org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;
import org.springframework.security.web.SecurityFilterChain;

import java.util.Collection;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

@Configuration
@EnableWebSecurity
@EnableMethodSecurity // Cho phép dùng @PreAuthorize ở Controller
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable()) // Tắt CSRF cho API
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/public/**").permitAll() // API public không cần token
                .anyRequest().authenticated() // Các API còn lại yêu cầu phải login
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt.jwtAuthenticationConverter(jwtAuthenticationConverter()))
            );
        
        return http.build();
    }

    // Converter: Biến đổi thông tin từ JWT Keycloak sang Spring Security Authority
    @Bean
    public JwtAuthenticationConverter jwtAuthenticationConverter() {
        JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
        converter.setJwtGrantedAuthoritiesConverter(source -> {
            // Lấy map roles từ claim "realm_access" của Keycloak
            Map<String, Object> realmAccess = source.getClaimAsMap("realm_access");
            
            if (realmAccess == null || !realmAccess.containsKey("roles")) {
                return List.of();
            }

            List<String> roles = (List<String>) realmAccess.get("roles");
            
            // Convert: [USER, ADMIN] -> [ROLE_USER, ROLE_ADMIN]
            return roles.stream()
                    .map(role -> new org.springframework.security.core.authority.SimpleGrantedAuthority("ROLE_" + role))
                    .collect(Collectors.toList());
        });
        return converter;
    }
}

Bước 4: Class DemoController.java

package com.example.demo.controller;

import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class DemoController {

    @GetMapping("/public/hello")
    public String hello() {
        return "Public: Xin chào, ai cũng xem được!";
    }

    @GetMapping("/user/profile")
    @PreAuthorize("hasRole('USER')")
    public String userProfile() {
        return "Secured: Đây là trang dành cho User có role USER.";
    }

    @GetMapping("/admin/dashboard")
    @PreAuthorize("hasRole('ADMIN')")
    public String adminDashboard() {
        return "Secured: Đây là trang quản trị (ADMIN ONLY).";
    }
}

4. RESULT: Kiểm thử hoạt động

Sử dụng Postman để demo luồng OAuth2.

Bước 1: Lấy Token từ Keycloak (Login)
– URL: http://localhost:8080/realms/springboot-demo/protocol/openid-connect/token
– Body (x-www-form-urlencoded):
+ client_id: my-backend-api
+ client_secret: (Lấy trong Keycloak: Clients -> my-backend-api -> Credentials)
+ grant_type: password
+ username: testuser
+ password: 123
– Kết quả: Bạn nhận được JSON chứa access_token. Copy chuỗi này.

Bước 2: Gọi API bảo mật
– URL: http://localhost:8081/user/profile
– Authorization Tab: Chọn type Bearer Token và dán access token vào.
– Kết quả:
+ Nếu token hợp lệ: Trả về Secured: Đây là trang dành cho User... (Status 200).
+ Nếu không gửi token: 401 Unauthorized.

Kết luận: Bạn đã xây dựng thành công một hệ thống bảo mật hiện đại, tách biệt hoàn toàn Resource Server và Authorization Server, tuân thủ chuẩn OAuth2.

The post Keycloak: Giải pháp IAM toàn diện cho ứng dụng hiện đại appeared first on Tomoshare.

Mở đầu: Nỗi đau của Developer

Bạn đang phát triển một ứng dụng local, mọi thứ chạy mượt mà ở localhost:3000. Nhưng vấn đề nảy sinh khi:

• Bạn cần test Webhook từ các dịch vụ bên ngoài như ZaloPay, Stripe, Telegram (các bên này bắt buộc phải có HTTPS).
• Khách hàng muốn xem demo ngay lập tức, nhưng bạn chưa kịp deploy lên server.
• Bạn chán ngấy cảnh dùng Ngrok bản free vì tên miền bị đổi liên tục sau mỗi lần restart.

Giải pháp tối ưu nhất hiện nay chính là Cloudflare Tunnel.

1. Cloudflare Tunnel là gì?

Cloudflare Tunnel (trước đây là Argo Tunnel) là công cụ giúp bạn kết nối máy chủ local (hoặc máy ảo) ra internet mà không cần mở port (port forwarding) trên router.

Thay vì cho phép người lạ truy cập trực tiếp vào IP của bạn (rất rủi ro), Tunnel tạo một đường hầm bảo mật (outbound connection) từ máy bạn đến mạng lưới Cloudflare Edge. Từ đó, Cloudflare sẽ “public” ứng dụng của bạn ra ngoài bằng một tên miền HTTPS xịn xò.

Tại sao nên dùng Cloudflare Tunnel thay vì Ngrok?

2. Mô hình hoạt động

Hãy tưởng tượng luồng dữ liệu sẽ đi như sau:

User Browser -> Cloudflare Edge (HTTPS) -> Cloudflared (trên máy bạn) -> Localhost (3000, 8080…)

Bạn có thể chạy nhiều dịch vụ cùng lúc qua một đường hầm duy nhất:

• api.domain.com -> trỏ về localhost:3000
• admin.domain.com -> trỏ về localhost:8080

3. Chuẩn bị “đồ nghề”

Trước khi bắt đầu, bạn cần:

1. Tài khoản Cloudflare (đăng ký miễn phí).
2. Một tên miền (Domain) đã thêm vào Cloudflare.
   • Lưu ý: Freenom hiện tại không ổn định. Bạn nên mua các domain giá rẻ như .xyz, .dev, .click (chỉ khoảng 1-2$/năm) tại Namecheap hoặc Hostinger để dùng lâu dài.
3. Máy tính (Linux/Mac/Windows) để chạy tool.

4. Hướng dẫn triển khai chi tiết (Step-by-step)

Bước 1: Cài đặt cloudflared

Công cụ cloudflared là cầu nối giữa máy bạn và Cloudflare.

Trên Linux (Ubuntu/Debian):codeBash

curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb

Trên Windows:
Tải file .msi mới nhất từ GitHub chính chủ: Cloudflare Downloads
(Mở PowerShell dưới quyền Administrator để chạy các lệnh sau này).

Bước 2: Đăng nhập Cloudflare

Chạy lệnh sau để xác thực:codeBash

cloudflared tunnel login

Trình duyệt sẽ bật lên, bạn hãy chọn tên miền muốn sử dụng và bấm Authorize.

Bước 3: Tạo Tunnel

Đặt tên cho tunnel của bạn (ví dụ: my-local-server):codeBash

cloudflared tunnel create my-local-server

Sau khi tạo xong, Cloudflare sẽ sinh ra một Tunnel ID và file credentials (thường nằm ở ~/.cloudflared/).

Bước 4: Cấu hình định tuyến (Routing)

Đây là bước quan trọng nhất để map domain về localhost.
Tạo file config.yml trong thư mục ~/.cloudflared/ (hoặc cùng thư mục chạy tool) với nội dung:codeYaml

tunnel: <TUNNEL-NAME-HOẶC-ID>
credentials-file: /duong/dan/den/file/json/credentials.json

ingress:
  # Service 1: API Backend
  - hostname: api.namdevlabs.com
    service: http://localhost:3000

  # Service 2: Webhook test (ZaloPay, Stripe)
  - hostname: hook.namdevlabs.com
    service: http://localhost:5678

  # Service 3: Dashboard Admin
  - hostname: admin.namdevlabs.com
    service: http://localhost:8080

  # Rule cuối cùng bắt buộc: Trả về 404 nếu không khớp domain nào
  - service: http_status:404

Bước 5: Gắn DNS cho Subdomain

Bạn cần báo cho Cloudflare biết subdomain nào sẽ đi vào tunnel này.codeBash

# Cú pháp: cloudflared tunnel route dns <TUNNEL_NAME> <SUBDOMAIN>
cloudflared tunnel route dns my-local-server api.namdevlabs.com
cloudflared tunnel route dns my-local-server hook.namdevlabs.com

Lệnh này sẽ tự động tạo bản ghi CNAME trên Cloudflare Dashboard.

Bước 6: Kích hoạt Tunnel

Chạy tunnel với file config vừa tạo:codeBash

cloudflared tunnel run my-local-server

Mẹo: Nếu file config không nằm ở vị trí mặc định, dùng flag –config:
cloudflared tunnel –config /path/to/config.yml run

 Xong! Bây giờ bạn có thể truy cập https://api.namdevlabs.com và thấy nó trỏ thẳng về localhost:3000 của bạn với HTTPS xanh mượt.

5. Mẹo nâng cao cho Pro Developer

• Chạy ngầm (Service Mode): Để tunnel tự chạy khi khởi động máy (dành cho server home lab):codeBashsudo cloudflared service install sudo systemctl start cloudflared
• Bảo mật Zero Trust: Bạn sợ người lạ vào link demo? Vào Cloudflare Dashboard -> Zero Trust, bật tính năng yêu cầu đăng nhập bằng Email/Google trước khi truy cập vào domain.
• Debug lỗi: Nếu không truy cập được, hãy thêm flag –loglevel debug khi chạy để xem log chi tiết.

6. Tổng kết

Cloudflare Tunnel thực sự là một vũ khí lợi hại trong bộ công cụ của developer. Nó giúp bạn:

1. Tiết kiệm tiền: Không tốn phí server staging.
2. Tiết kiệm thời gian: Không cần deploy để demo.
3. An toàn: Không mở port, hạn chế tấn công DDoS.

Hy vọng bài viết giúp bạn giải quyết được bài toán đau đầu về Webhook và Demo. Chúc bạn code vui!

The post Đưa Localhost lên Internet miễn phí với Cloudflare Tunnel: Giải pháp thay thế Ngrok để Test Webhook & Demo App appeared first on Tomoshare.

1. Vì sao phải viết Cursor Rule?

1.1. Để AI hiểu đúng cách bạn muốn nó làm việc

Khi không có rule, AI đoán phong cách, chất lượng và mục tiêu theo thói quen chung → dễ sai, mơ hồ, hoặc không phù hợp với dự án.
Rule giúp cố định cách AI hành động, không bị lệch dù prompt thay đổi.

1.2. Để giữ chất lượng đầu ra ổn định

Khi làm team, nhiều người dùng AI cho chung một dự án. Không có rule → mỗi người cho ra một kiểu.
Có rule → kết quả ổn định, “giống một người viết”.

1.3. Để tiết kiệm thời gian

Không phải lặp lại các yêu cầu cố định như coding style, cấu trúc file, cấm/tắt tính năng…
Rule giúp giảm 50–80% thời gian bạn cần để “định hướng” AI.

1.4. Để chống lỗi và giảm rủi ro

AI không tự biết giới hạn của dự án.
Rule giúp chặn:

• Sai kiến trúc
• Viết sai chuẩn coding
• Phát sinh thư mục rác
• Tự ý tạo file không có trong dự án
• Sử dụng công nghệ dự án không hỗ trợ

2. Cấu trúc cần có của một Cursor Rule

2.1. Mục “alwaysApply”: để rule luôn được kích hoạt

alwaysApply: true

Nếu không bật, rule chỉ hoạt động khi bạn chọn thủ công → vô dụng. Bật lên để toàn bộ dự án luôn tuân theo một chuẩn.

2.2. Mục mô tả (description): để ghi rõ mục đích

description: |
  Quy tắc dùng khi làm việc với dự án X.

Đây là phần giúp AI hiểu bối cảnh tổng quát. Nếu không có, AI dễ “đi lạc” sang phong cách khác.

2.3. Danh sách rules (rules[]): để kiểm soát từng hành vi

Một rule có các thành phần cơ bản:

rules:
  - name: "Quy tắc đặt tên file"
    pattern: "*.js"
    description: |
      Tất cả file phải dùng camelCase.
    examples:
      good: ["userService.js"]
      bad: ["User_service.JS"]

Giải thích từng phần:

2.4. Mục cấm / hạn chế (do/dont)

Ví dụ:

intent:
  - "Không tự tạo file mới nếu người dùng không yêu cầu."

AI hay tự sinh file → gây rác → ảnh hưởng cấu trúc dự án → không kiểm soát được.
Rule này khóa hành vi đó.

2.5. Định nghĩa style coding (coding conventions)

  - name: "Code style"
    description: |
      Viết code theo chuẩn PSR-12.

Nếu không chốt style → mỗi lần AI tạo code là mỗi lần thay đổi format → khó review, khó merge.

3. Quy trình viết một Cursor Rule chuẩn

Bước 1 — Xác định mục tiêu dự án

Bạn phải trả lời: “Tôi muốn AI hỗ trợ cái gì?”

Không biết mục tiêu → rule lan man, dài, không hiệu quả → AI rối.

Bước 2 — Ghi rõ giới hạn dự án

Ví dụ:

• PHP version: 7.4
• Framework: Laravel 8
• Không dùng TypeScript
• Không tạo file migration mới

Giới hạn càng rõ → AI càng ít sai.
Không có giới hạn → AI rất hay dùng công nghệ mới, sai version, sai API.

Bước 3 — Xác định những hành vi AI hay sai nhất

Ví dụ:

• Tự sinh file linh tinh
• Viết import sai
• Sử dụng syntax của version mới
• Tạo code không phù hợp folder structure

Đây là những điểm tạo ra rule quan trọng nhất. Tập trung 20% rule để sửa 80% lỗi.

Bước 4 — Viết rule bằng ngôn ngữ đơn giản, không mơ hồ

Ví dụ sai: “Viết code sạch” → AI không hiểu.
Ví dụ đúng: “Không dùng biến một ký tự như i, j, k.”

AI không hiểu từ trừu tượng.
Muốn AI làm đúng → phải mô tả hành vi cụ thể.

Bước 5 — Bổ sung ví dụ tốt/xấu

Đây là phần cực quan trọng nhưng rất nhiều người bỏ qua.

AI học theo ví dụ mạnh hơn theo mô tả.
Chỉ 2–3 ví dụ tốt/xấu đã giúp giảm lỗi 60–70%.

Bước 6 — Test rule bằng một tác vụ thật

Ví dụ: “Tạo controller UserController.”

Rule chỉ có giá trị khi được test trong thực tế.
Không test → rule chỉ là lý thuyết.

4. Mẫu Cursor Rule đơn giản cho người mới

alwaysApply: true

description: |
  Quy tắc hỗ trợ viết mã PHP, Laravel 8 cho dự án cũ.

rules:
  - name: "Không dùng syntax Laravel mới"
    description: |
      Laravel trong dự án là bản 8. Không dùng các API của Laravel 9+.
    examples:
      bad: ["Route::controller(...)"]
      good: ["Route::get(...)", "Route::post(...)"]

  - name: "Không tự tạo file"
    description: |
      Chỉ tạo file khi người dùng yêu cầu.

  - name: "Style code"
    description: |
      Tất cả code phải tuân theo PSR-12.

Kết luận

Viết Cursor Rule không phải để “làm màu”, mà để:

• Giữ AI chạy đúng đường.
• Giảm lỗi.
• Tăng tốc độ phát triển.
• Chuẩn hóa output trong team.
• Tạo ra môi trường làm việc ổn định.

Muốn viết rule tốt → phải hiểu vấn đề, hiểu dự án, và hiểu AI dễ sai ở đâu.

The post Hướng dẫn viết Cursor Rule cho người mới bắt đầu appeared first on Tomoshare.