Cho tới tuần này, cách duy nhất để tôi biết ứng dụng của tôi bị sập là có ai đó nhắn cho tôi. Mà phần lớn mọi người không nhắn. Họ mở lại ứng dụng, và nếu nó sập thêm lần nữa thì họ thôi không mở nữa. Phía API thì đã có giám sát: mọi log mức ERROR đều được đẩy vào một kênh chat của đội. Nhưng một lần sập trên điện thoại thì không để lại dấu vết gì ở bất cứ chỗ nào tôi nhìn thấy được.

Thật ra ứng dụng đã có sẵn một cơ chế báo lỗi. Mỗi khi ứng dụng hiện một thông báo lỗi cho người dùng, nó gửi nội dung thông báo đó lên một endpoint nhỏ của API. Máy chủ ghi lại ở mức ERROR, nên lỗi đó cũng tới được kênh chat. Tôi thêm cơ chế này sau một lần thao tác xoá thực ra đã thành công, nhưng dòng đó vẫn nằm trong danh sách; người dùng bấm vào lần nữa và nhận được thông báo “No Item matches the given query”. Phía máy chủ chỉ ghi hai lỗi 404 bình thường và không báo gì cả. Cơ chế đó bao quát được những lỗi mà ứng dụng bắt được và hiện ra cho người dùng. Còn sập ứng dụng (crash) thì khác hẳn: chính đoạn JavaScript lẽ ra sẽ gửi báo cáo lại là thứ vừa chết.

Cách sửa hiển nhiên là dùng Sentry. Tôi rất thích SDK của Sentry; nhờ nó mà báo cáo sự cố trên React Native gần như là bài toán đã có lời giải. Điều tôi không muốn là thêm một nhà cung cấp nữa giữ dữ liệu người dùng, thêm một dòng trong chính sách quyền riêng tư, và thêm một hoá đơn cho một thứ mà với quy mô của chúng tôi thì nhiều lắm cũng chỉ vài báo cáo mỗi ngày. Vì vậy tôi giữ SDK và thay phần dịch vụ: DSN của ứng dụng trỏ về API của chính chúng tôi, và một phần nhỏ trong ứng dụng Django ở đó nhận những gì SDK gửi lên, gom nhóm, gửi cảnh báo và lưu lại.

Bài này kể cách hệ thống đó hoạt động, và cách tôi kiểm tra để chắc rằng một lần sập gốc (native crash) thật sự đi được tới máy chủ.

Mẹo với DSN

#

Một DSN của Sentry có dạng https://<public-key>@<host>/<project-id>. SDK biến nó thành một yêu cầu POST tới https://<host>/api/<project-id>/envelope/, với khoá nằm trong header X-Sentry-Auth. Không có chi tiết nào trong đó gắn riêng với sentry.io. Vì vậy DSN được đóng gói sẵn trong ứng dụng là:

https://<CRASH_REPORT_KEY>@api.example.com/1

và phía Django có một route khớp đúng với địa chỉ mà SDK sẽ gọi:

path("api/<int:project_id>/envelope/", crash_envelope, name="crash_envelope"),

Khoá này nằm trong mọi bản build của ứng dụng, nên nó không phải bí mật. Nó tồn tại vì hai lý do: nếu một ngày endpoint bắt đầu hứng rác thì tôi có thể đổi khoá, và nếu máy chủ chưa cấu hình khoá thì endpoint sẽ từ chối tất cả thay vì nhận bừa mọi thứ:

def crash_envelope(request, project_id):
    expected = settings.CRASH_REPORT_KEY
    if not expected:
        return Response({"detail": "Crash reporting is not configured"}, status=503)
    if not hmac.compare_digest(_key(request).encode(), expected.encode()):
        return Response({"detail": "Unknown key"}, status=401)
    ...

Hàm _key đọc giá trị sentry_key= trong header X-Sentry-Auth; nếu không có thì lấy từ query string, vì một số SDK đặt khoá ở đó.

SDK gửi gì lên: envelope

#

Định dạng truyền dữ liệu của Sentry là envelope: một dòng JSON làm header, sau đó là bao nhiêu mục (item) cũng được, mỗi mục gồm một dòng JSON header rồi tới phần nội dung (payload). Nếu header của mục có trường length thì payload dài đúng bằng số byte đó; nếu không thì payload kéo dài tới ký tự xuống dòng kế tiếp.

{"event_id":"9ec79c33...","dsn":"https://...@api.example.com/1"}
{"type":"event","length":4123}
{ ...the event JSON, 4123 bytes... }
{"type":"client_report"}
{"timestamp":1791400000.5,"discarded_events":[]}

Có hai chi tiết khiến tôi vấp:

• SDK gốc (native) nén gzip phần thân yêu cầu, còn SDK JavaScript thì không. Một lỗi JS mà @sentry/react-native bắt được sẽ tới dưới dạng văn bản thường, trong khi một lần sập gốc từ sentry-cocoa hoặc sentry-android tới kèm Content-Encoding: gzip. Bộ giải mã xử lý được gzip, deflate có bọc zlib và deflate thô, và dừng giải nén ở mức 1MB, vì một sự kiện sập chỉ nặng vài kilobyte, thứ gì lớn hơn thế thì không phải báo cáo sự cố.
• Payload có tiền tố độ dài có thể chứa ký tự xuống dòng. Nếu bạn tách theo \n thì sẽ làm hỏng mọi sự kiện mà SDK gốc gửi lên. Khi có length thì bắt buộc phải tôn trọng nó.

Bộ phân tích cú pháp (parser) khá ngắn. Nó chỉ giữ các mục event; session, transaction, tệp đính kèm và client report đều được nhận rồi bỏ đi.

Trả lời theo cách SDK hiểu được

#

Phần này quan trọng hơn tôi tưởng. SDK giữ một hàng đợi trên đĩa và gửi lại bất cứ thứ gì nó không chắc là đã tới nơi, nên câu trả lời của máy chủ quyết định SDK có tiếp tục thử lại hay không:

• 200 khi đã lưu, hoặc khi cố ý bỏ đi. Nếu tôi trả 4xx cho một mục session, SDK sẽ giữ nó lại và thử gửi mãi mãi.
• 429 kèm Retry-After khi bị giới hạn tần suất. Endpoint có giới hạn theo từng IP (120 lần mỗi giờ), vì một chiếc điện thoại bị sập liên tục sẽ gửi một báo cáo mỗi lần khởi động, và SDK lùi lại khi gặp 429 đúng như mình mong.
• 400 cho envelope sai định dạng, ghi log ở mức cảnh báo (warning) chứ không phải lỗi: một báo cáo hỏng chỉ cho biết có một client đang hỏng, và báo cáo tốt tiếp theo sẽ nói cái gì đã sập.

SDK cũng gửi lại cùng một sự kiện nếu nó không chắc lần gửi đầu đã tới nơi, nên event_id có ràng buộc duy nhất (unique constraint) và một bản trùng lặp sẽ được bỏ qua lặng lẽ.

Gom nhóm khi không có source map

#

Đây là chỗ một bộ nhận tự viết phải đưa ra lựa chọn mà Sentry vốn làm sẵn cho bạn. Sentry gom nhóm các lần sập theo stack trace. Nhưng bundle Hermes ở bản phát hành đã bị rút gọn (minify), nên tên các frame chỉ còn một chữ cái và vị trí dòng/cột thay đổi sau mỗi lần build. Nếu gom theo frame, cùng một lỗi sẽ mở ra một issue mới ở mỗi bản phát hành.

Khi chưa có source map (phần cuối bài sẽ nói thêm), thứ ổn định nhất trong một lỗi JavaScript là kiểu lỗi và thông điệp lỗi. Vì vậy dấu vân tay (fingerprint) là kiểu exception cộng với thông điệp, trong đó những phần thay đổi giữa các lần xuất hiện được che đi:

_MASKS = [
    (re.compile(r"0x[0-9a-fA-F]+"), "<addr>"),
    (re.compile(r"\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b"), "<uuid>"),
    (re.compile(r"\b[0-9a-fA-F]{16,}\b"), "<hex>"),
    (re.compile(r"\d+"), "<n>"),
]

Cannot read property 'title' of undefined (reading index 3) và (reading index 17) sẽ thành cùng một issue. Nếu SDK tự gửi kèm fingerprint mà không có {{ default }} bên trong thì giá trị đó được ưu tiên, nhờ vậy tôi có thể ép cách gom nhóm từ phía client khi cách mặc định chưa đúng. Sự kiện nào không có exception thì dùng thông điệp log đã che làm dấu vân tay, còn nếu không có cả hai thì dùng frame đầu tiên thuộc mã của ứng dụng (in-app). Với một lần sập do tín hiệu (signal) ở tầng gốc, thông điệp thường kiểu Signal 6, Code 0, nên các lần sập này được gom theo tín hiệu. Cách đó hơi thô, nhưng trung thực cho tới khi có giải mã ký hiệu (symbolication).

Cảnh báo mà không làm ngập kênh

#

Mỗi dấu vân tay ứng với một issue, và mỗi báo cáo được lưu thành một sự kiện nằm dưới issue đó. Issue chỉ ghi log ở mức ERROR (đó là thứ cảnh báo trên kênh chat lắng nghe) đúng trong những trường hợp sau:

• một issue mới
• một issue đã đánh dấu xử lý xong (resolved) nhưng quay lại, khi đó issue được mở lại
• lần xuất hiện thứ 10, 100, 1.000 và 10.000

Một lần lặp lại bình thường chỉ tăng bộ đếm. Issue bị đánh dấu ignored vẫn tiếp tục được đếm nhưng không bao giờ cảnh báo. Cộng thêm giới hạn tần suất riêng của handler gửi lên kênh chat, một vòng lặp sập trên một bản phát hành lỗi chỉ hiện ra thành vài tin nhắn chứ không thành một bức tường chữ.

Dung lượng lưu trữ cũng được giới hạn theo cùng cách: mỗi issue chỉ giữ 50 sự kiện gần nhất và xoá các sự kiện cũ hơn khi có sự kiện mới. Điều này làm hỏng biểu đồ đầu tiên của tôi, vì 50 sự kiện không thể cho bạn biết tuần trước lỗi đó xảy ra bao nhiêu lần. Vì vậy mỗi issue giữ thêm số đếm theo từng ngày trong 90 ngày, được cập nhật trong cùng giao dịch (transaction) với bộ đếm. Biểu đồ vẽ từ các số đếm này; các sự kiện chỉ để đọc chi tiết.

Nếu bạn tự làm một hệ thống như vậy, có hai tình huống tranh chấp (race) nhỏ đáng xử lý. Khi một lần sập hoàn toàn mới xảy ra trên nhiều điện thoại cùng lúc, hai báo cáo có thể cùng cố tạo issue, nên hãy đặt ràng buộc duy nhất cho dấu vân tay và để báo cáo chậm chân hơn đọc lại dòng đã có. Ngoài ra, khung 90 ngày nên tính từ ngày hôm nay theo đồng hồ của máy chủ, chứ không tính từ báo cáo mới nhất, vì một chiếc điện thoại cài sai đồng hồ có thể ghi ngày cho báo cáo là bất kỳ ngày nào, kể cả năm sau.

Payload bị giới hạn ở 128KB. Sự kiện nào vượt quá thì bị bỏ breadcrumb và siêu dữ liệu gỡ lỗi (debug metadata) trước; nếu vẫn còn quá lớn thì chỉ giữ exception, thông điệp, phiên bản phát hành và nền tảng, kèm một dấu đánh dấu để tôi biết nó đã bị cắt.

Lọc bỏ dữ liệu cá nhân

#

SDK chạy với sendDefaultPii: false, nên về nguyên tắc không có địa chỉ IP, cookie hay nội dung yêu cầu nào được gửi lên. Máy chủ không dựa vào điều đó: trước khi lưu bất cứ thứ gì, nó chỉ giữ id và username trong user và bỏ hẳn request, phòng khi một phiên bản SDK hoặc một thiết lập sau này bắt đầu gửi chúng.

Kiểm thử trên thiết bị thật làm lộ ra thêm hai thứ cần loại bỏ:

• Breadcrumb ghi lại URL đầy đủ, kể cả query string. Các yêu cầu tìm kiếm của ứng dụng đặt từ khoá ngay trong query string, nên một lần sập ngay sau khi tìm kiếm sẽ lưu luôn từ khoá người dùng đã gõ. Giờ máy chủ cắt mọi URL trong breadcrumb tại dấu ?.
• Breadcrumb từ console mang theo nguyên các đối số đã truyền vào console.log, mà đó có thể là bất kỳ object nào ứng dụng tình cờ ghi log. Phần văn bản thông điệp được giữ (vì nó hữu ích), còn các đối số thì bị bỏ.

Tôi chỉ phát hiện ra hai điều đó khi nhìn vào một báo cáo thật, và đó cũng là lý do chính cho phần tiếp theo.

Phía client

#

Trong ứng dụng, mọi thứ đều đi qua một module nhỏ duy nhất, cùng lý do với việc tôi bọc SDK cập nhật qua mạng (OTA) lại: một bundle OTA cũng chạy trên các bản build được tạo ra trước khi module gốc tồn tại. Một câu import * as Sentry from "@sentry/react-native" ở cấp cao nhất trên bản build không có RNSentry sẽ ném lỗi ngay khi import, và kết quả là màn hình trắng. Vì vậy SDK được nạp lười (lazy require), và chỉ sau khi đã kiểm tra module gốc thực sự có mặt:

import { NativeModules, Platform, TurboModuleRegistry } from "react-native";
import Constants from "expo-constants";

const DSN = process.env.EXPO_PUBLIC_CRASH_DSN;

function nativeModulePresent(): boolean {
  try {
    return Boolean(TurboModuleRegistry.get("RNSentry") ?? NativeModules.RNSentry);
  } catch {
    return false;
  }
}

export function initCrashReporting(): boolean {
  if (!DSN || Platform.OS === "web" || !nativeModulePresent()) return false;
  const Sentry = require("@sentry/react-native");
  Sentry.init({
    dsn: DSN,
    release: Constants.expoConfig?.version ?? "unknown",
    sendDefaultPii: false,
    tracesSampleRate: 0,
    enableAutoSessionTracking: false,
    // ...turn off the other tracing options the same way
    maxBreadcrumbs: 50,
    beforeSend(event) { /* tag the OTA bundle */ return event; },
  });
  return true;
}

Chỉ báo lỗi. Máy chủ không lưu trace, session, profile hay bản ghi phát lại (replay), nên không tính năng nào trong số đó được bật. Không có DSN (khi phát triển, khi chạy kiểm thử E2E) thì SDK không bao giờ khởi động. Các cấu hình build (build profile) đặt sẵn DSN và một môi trường (staging hoặc production), nên cả hai loại bản build đều báo về cùng một endpoint mà vẫn phân biệt được với nhau. Người dùng đã đăng nhập được gắn bằng ID tài khoản, không bao giờ bằng tên hay email.

Các error boundary cần được gọi báo lỗi một cách tường minh. ErrorBoundary gốc của Expo Router bắt lỗi khi render và hiện màn hình của riêng nó, nên lỗi đó không bao giờ tới được handler toàn cục mà SDK móc vào. Cách sửa là một lớp bọc nhỏ: gọi captureException trong một useEffect rồi render boundary của router như cũ, dùng chung cho cả boundary gốc lẫn boundary của từng route. Lời gọi được đặt trong effect chứ không nằm trong hàm render, để nó chỉ báo một lần thay vì báo lại sau mỗi lần render lại. Component gốc cũng được bọc bằng Sentry.wrap, và nếu việc bọc ném lỗi thì quay về dùng component trần.

Trên web có một phiên bản .web.ts của module, trong đó mọi hàm đều bị tắt. Metro chọn tệp theo nền tảng, nên SDK hoàn toàn không lọt vào bundle web. Ứng dụng web vốn không có module gốc nào để SDK chạy trên đó.

Chứng minh một lần sập gốc thật sự về tới nơi

#

Các unit test gửi những envelope viết tay, tức là chỉ chứng minh parser xử lý được thứ mà tôi nghĩ SDK sẽ gửi. Hai ngày sau khi phát hành, trên production chưa có báo cáo sự cố nào. Lúc đó mới có ba người cập nhật, nên con số 0 là hợp lý, nhưng nhìn từ phía máy chủ thì “chưa ai bị sập” và “báo cáo sập không về tới” trông giống hệt nhau. Tôi muốn thấy một báo cáo thật.

Vì vậy tôi build một bản Release cho simulator, với DSN trỏ về một Django chạy cục bộ ở cổng 8000 cùng một khoá dùng một lần:

EXPO_PUBLIC_CRASH_DSN=http://localcrashtestkey0000@localhost:8000/1 \
EXPO_PUBLIC_CRASH_ENVIRONMENT=local-verify \
xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp -configuration Release \
  -destination 'platform=iOS Simulator,id=<udid>' -derivedDataPath /tmp/iosbuild

(Dùng Release chứ không phải Debug: bản Debug có liên kết dev launcher và hoạt động khác đi, còn Release mới là thứ người dùng thật sự chạy.) Sau đó tôi cài, mở ứng dụng, chờ vài giây, rồi giết tiến trình theo đúng cách một lỗi thật sẽ làm:

xcrun simctl install booted /tmp/iosbuild/Build/Products/Release-iphonesimulator/MyApp.app
xcrun simctl launch booted com.example.myapp      # prints the pid
kill -ABRT <pid>

Ứng dụng trong simulator là các tiến trình macOS bình thường, nên tín hiệu tới được handler của SentryCrash y như trên thiết bị thật. Handler ghi báo cáo xuống đĩa; trong lúc tiến trình đang chết thì không có gì được gửi đi. Ở lần khởi động tiếp theo, SDK tìm thấy báo cáo đó và gửi lên. Tôi mở lại ứng dụng, và một giây sau nhật ký mạng của simulator cho thấy có kết nối tới :8000.

Rồi trong log của Django chẳng có gì, khiến tôi bối rối mất một phút: ở mức log tôi đang đặt, máy chủ phát triển chỉ ghi lại các phản hồi không phải 2xx. Nhưng trong cơ sở dữ liệu thì có:

SIGABRT: Signal 6, Code 0 | cocoa 1.4.0 iOS 27.1 iPhone19,4 handled=False
received 09:19:53, crashed 09:19:38
contexts: app, device, os, ota_updates, trace · 24 breadcrumbs

Mười lăm giây từ lúc sập tới lúc được lưu, mà phần lớn thời gian đó là tôi mở lại ứng dụng. Và chính việc nhìn vào payload thật đã dạy tôi những điều mà kiểm thử không thể:

• ID người dùng không phải ID tài khoản. Bản build thử nghiệm không thật sự đăng nhập, nên sentry-cocoa dùng ID riêng cho từng lượt cài đặt của nó. Điều này đáng biết, và đáng ghi vào phần lưu ý quyền riêng tư: một báo cáo mang ID tài khoản nếu bạn đã đăng nhập, và một ID cài đặt ngẫu nhiên nếu chưa.
• Không có múi giờ. Tôi đã cho rằng sẽ có context về ngôn ngữ và vùng (culture). Context thiết bị có locale, bộ nhớ, kích thước màn hình, chế độ tiết kiệm pin và phiên bản kernel, nhưng không có múi giờ.
• Sập gốc bỏ qua beforeSend. Hàm beforeSend phía JS của tôi gắn thêm tag ota ghi bundle OTA đang chạy, nhưng một lần sập gốc được SDK gốc lắp ráp ở lần khởi động sau và không bao giờ đi qua hook JS này. Muốn gắn tag cho sập gốc thì phải đặt tag trên scope bằng setTag ngay khi biết bundle, để nó được đồng bộ xuống tầng gốc.
• Breadcrumb cho thấy ứng dụng đang làm gì. Cảnh báo trên console, vòng đời của view controller, và các lệnh gọi HTTP, kể cả các yêu cầu của chính SDK phân tích (analytics) tới endpoint thu thập dữ liệu của nó. Đó là lời nhắc tốt về việc ứng dụng còn nói chuyện với những ai khác. Và các URL có kèm query string, đó là cách tôi phát hiện ra vấn đề từ khoá tìm kiếm ở trên.

Đọc báo cáo

#

Báo cáo được đọc trong trang quản trị Django, trên một trang issue mô phỏng đại khái theo Sentry: phần đầu có các con số đếm và các nút Resolve / Ignore / Reopen, tiếp theo là biểu đồ cột theo ngày, tỷ lệ theo phiên bản phát hành, hệ điều hành, thiết bị và bundle OTA, rồi tới từng sự kiện một với exception, các frame (frame của ứng dụng được tô nổi, frame của thư viện được thu gọn), breadcrumb và context thiết bị. Không cần thêm thư viện phụ thuộc nào.

Trong lúc làm trang này có một chỗ phải sửa: với một lần sập gốc, frame “thủ phạm” (culprit) là đường dẫn của tệp thực thi trên thiết bị, trong đó có một UUID riêng cho mỗi lượt cài đặt, nên cùng một lần sập lại trông khác nhau trên mỗi điện thoại. Giờ nó chỉ hiện địa chỉ và tên tệp thực thi, kiểu 0x1000a1b2c (MyApp).

Chính sách quyền riêng tư, toàn bộ

#

Báo cáo sự cố gần như chắc chắn là thông tin cá nhân: một ID tài khoản, một mẫu điện thoại, và những gì một người đã làm trong phút cuối trước khi ứng dụng sập. Vì vậy chính sách quyền riêng tư cần thêm một đoạn. Viết cho đàng hoàng nghĩa là phải nói chính xác một báo cáo mang theo những gì, nên tôi liệt kê dựa trên payload vừa xem: lỗi, phiên bản ứng dụng và bản cập nhật OTA, mẫu điện thoại, hệ điều hành và ngôn ngữ, bộ nhớ trống và kích thước màn hình, vài chục bước gần nhất (các màn hình, địa chỉ web đã bỏ mọi thứ sau dấu ?, các dòng log của chính ứng dụng), và ID tài khoản hoặc một ID cài đặt ngẫu nhiên. Chính sách cũng nói rõ báo cáo được gửi về máy chủ của chúng tôi, không gửi tới Sentry hay bất kỳ công ty báo cáo sự cố nào khác. Thời hạn lưu giữ có một dòng riêng trong bảng: 50 báo cáo gần nhất cho mỗi vấn đề, cộng với số đếm theo ngày trong 90 ngày.

Một khi đã đối chiếu một đoạn với mã nguồn, thật khó mà không đối chiếu phần còn lại. Và chính sách hiện có không đứng vững. Trang xoá tài khoản ghi rằng token thông báo đẩy (push notification) và passkey bị xoá ngay khi bạn đóng tài khoản, và log máy chủ sẽ biến mất trong vòng 90 ngày. Không điều nào trong số đó đúng. Đóng tài khoản sẽ gỡ liên kết các phương thức đăng nhập và ẩn danh hoá hồ sơ, nhưng token thông báo đẩy và passkey vẫn còn đó cho tới khi có người xoá bằng tay, và kho lưu log hiện chưa có hạn xoá. Vì vậy toàn bộ chính sách được viết lại dựa trên bản kiểm kê những gì mã nguồn thực sự làm, và những dòng đó giờ ghi “chưa được xoá tự động; hãy email cho chúng tôi”. Nghe kém yên tâm hơn, nhưng đúng sự thật.

Giờ repo có hẳn một quy tắc cho việc này: chính sách mô tả những gì mã nguồn làm, chứ không phải những gì chúng tôi dự định, và mọi thay đổi khiến dữ liệu cá nhân được thu thập, gửi đi hay lưu giữ ở một chỗ mới đều phải cập nhật chính sách trong cùng commit. Việc cập nhật đó bao gồm cả màn hình tóm tắt trong ứng dụng, trang xoá tài khoản, và các biểu mẫu quyền riêng tư trên cửa hàng ứng dụng, vốn chỉ nằm trong bảng điều khiển của cửa hàng. Báo cáo sự cố chính là thay đổi khiến tôi phải viết quy tắc đó ra.

Còn thiếu gì

#

Giải mã ký hiệu (symbolication). Đây là khoảng trống thật sự, và là thứ duy nhất sentry.io làm mà tôi chưa thay thế được. Stack của JavaScript thì đã bị rút gọn, còn của mã gốc thì chưa được giải mã ký hiệu:

• JavaScript: các frame trỏ vào bundle Hermes. Muốn sửa thì phải giữ source map Hermes đã ghép (composed) cho mọi bản build lên cửa hàng và mọi bundle OTA, đánh khoá theo phiên bản phát hành và bundle, rồi áp vào các frame JS khi render trang. Đó là phần làm tiếp theo, vì phần lớn các lần sập của chúng tôi sẽ là JavaScript.
• iOS gốc: địa chỉ lệnh cần dSYM của bản build.
• Android: frame Java bị R8 làm rối (obfuscate) khi bật rút gọn mã (cần mapping.txt), còn frame C++ cần ký hiệu NDK.

Còn một khoảng trống nhỏ hơn mà tôi đã nhắc ở trên: các lần sập gốc chưa mang tag OTA, vì tag này mới chỉ được đặt trong beforeSend. Đặt nó trên scope ngay khi bundle đang chạy được xác nhận chỉ mất vài dòng, nhưng tôi chưa viết.

Hiện tại, một issue cho tôi biết cái gì đã sập, trên phiên bản phát hành, bundle OTA và thiết bị nào, và người dùng đang làm gì ngay trước đó. Nó chưa cho tôi biết lỗi nằm ở đâu trong mã nguồn. Với một ứng dụng nhỏ phát hành vài lần mỗi tuần, cho tới giờ kiểu lỗi, thông điệp và breadcrumb vẫn đủ để tìm ra vấn đề.

Bộ nhận, trang quản trị và phần kiểm thử cộng lại cũng không nhiều mã, và nó không tốn thêm đồng nào ngoài chi phí của API vốn đã chạy sẵn. SDK làm phần khó nhất: bắt được lần sập trên điện thoại và gửi báo cáo đi ở lần khởi động kế tiếp.

Minh bạch. Codemagic đã trả tiền để tôi thực hiện đợt di chuyển này và viết về nó. Họ được đọc duyệt một lượt để kiểm tra tính chính xác về mặt sự kiện, chứ không phải về giọng văn, và không có chi tiết nào trong bài bị sửa theo yêu cầu của họ. Chỗ nào tôi gặp vấn đề và đã báo cáo, tôi nói rõ; nếu tới lúc bạn đọc bài này mà vấn đề đó đã được sửa, thì bài cũng ghi là đã sửa.

Cập nhật, ngày 23 tháng 9 năm 2026. Đội ngũ phát triển của Codemagic đã lần lượt xử lý những vấn đề tôi báo cáo. Phần lớn giờ đã được sửa, trong đó có lỗi phát hiện phiên bản trên iOS, các lượt cài bị đếm trùng, lần chạy đầu tiên im lặng và lệnh gỡ lỗi ồn ào; tài liệu giờ cũng đã đề cập tới dự án native đã commit và ngân sách số lần mở trước khi khôi phục khi sập. Ở từng chỗ trong bài, tôi đều ghi chú lại vấn đề nào đã được sửa, còn vài vấn đề vẫn chưa xử lý xong thì tôi giữ nguyên như cũ.

Cập nhật, ngày 16 tháng 10 năm 2026. Lần nâng cấp native đầu tiên kể từ khi chuyển sang Patch (Expo SDK 58) đã dựng ra một bản release Android không hề có cấu hình Patch nào bên trong, và không có gì báo lỗi cả. Chuyện gì đã xảy ra và cách sửa chỉ bằng một tệp nằm ở phần Lần nâng cấp native đầu tiên.

Hồi tháng Hai, tôi có viết về chuyện tự dựng máy chủ cập nhật cho Expo. Hệ thống đó vẫn chạy tốt. maru, ứng dụng cộng đồng tôi đang vận hành, từ đó tới nay nhận mọi bản sửa lỗi qua mạng (over the air) thông qua nó, trên cả hai nền tảng, với chi phí khoảng một đô mỗi tháng.

Nhưng điều đó cũng có nghĩa là tôi phải tự gánh từng mảnh của nó: các bảng cơ sở dữ liệu, một endpoint API, một lệnh quản trị, một script phát hành, một khóa bí mật dùng chung, và một loạt cái bẫy mà tôi học được qua từng bản cập nhật hỏng. Khi ngồi xuống lên kế hoạch cho đợt di chuyển này, tôi mới phát hiện là script kia đã in ra dòng “Sent 0 push notifications” sau mỗi lần phát hành lên production, ngay từ ngày tôi viết nó, vì nó đọc một trường mà máy chủ này chưa bao giờ trả về. Chẳng ai để ý, và người ít để ý nhất chính là tôi. Tự vận hành một thứ gì đó thì đại khái là sẽ thành ra như vậy.

Nên khi Codemagic hỏi tôi có muốn thử Patch, phiên bản mã nguồn mở, tự vận hành được (self-hosted) của họ theo mô hình CodePush, tôi đồng ý với một điều kiện: phải là một ứng dụng thật chứ không phải bản demo. Ký mã (signing) thật, quy trình phát hành thật, dự án native đã commit sẵn với những chỗ sửa tay bên trong, đủ cả. Phần lớn những người rời EAS Update đều đang mang theo một ứng dụng như thế, chứ không phải một template mới tinh.

Dưới đây là toàn bộ quá trình, giữ nguyên cả những chỗ còn xù xì.

Patch là gì

#

Patch gồm một máy chủ do bạn tự vận hành và một SDK bạn nhúng vào ứng dụng. Phía máy chủ có một API, một tiến trình chạy nền (worker), Postgres, kho lưu trữ đối tượng (object storage) tương thích S3, và một bảng điều khiển (dashboard) trên web, tất cả được đóng gói thành một bộ Docker Compose. Phía máy khách là @codemagic/react-native-patch, một TurboModule cho iOS và Android kèm plugin cấu hình cho Expo, cộng thêm một công cụ dòng lệnh (CLI) tên cmpatch để đóng gói (bundle) JavaScript của bạn và phát hành nó.

Sau khi đọc mã nguồn, có hai quyết định thiết kế khiến tôi chú ý.

Thứ nhất, ứng dụng không bao giờ hỏi API xem có bản cập nhật hay không. Khi một bản phát hành được công bố, worker ghi các manifest dạng JSON thuần vào kho lưu trữ đối tượng, và ứng dụng chỉ việc tải chúng về. Một lần kiểm tra cập nhật chỉ là hai yêu cầu GET tĩnh tới kho lưu trữ hoặc CDN; API chỉ nhận số liệu (metrics). Endpoint cũ của tôi trước đây nằm ngay trên đường đi của mọi lần mở ứng dụng. Với Patch thì chuyện đó không thể xảy ra.

Thứ hai, mỗi bản phát hành đều ghi rõ phiên bản nhị phân (binary) chính xác mà nó dành cho, và CLI tính ra một dấu vân tay (fingerprint) của dự án native rồi từ chối phát hành JavaScript lên một bản nhị phân có mã native không khớp. Máy chủ của tôi thì chỉ có một chuỗi phiên bản và rất nhiều hy vọng.

Chạy thử trên laptop trước đã

#

Tài liệu hướng dẫn bắt đầu bằng một bộ đánh giá chạy cục bộ (local evaluation stack), và đó đúng là chỗ nên bắt đầu.

npm install -g @codemagic/patch-cli
cmpatch selfhost local-eval up

CLI cài xong trong hai giây. Còn cả bộ thì lần đầu mất 3 phút 14 giây, phần lớn là để dựng image của máy chủ và bảng điều khiển ngay trên máy, và ở chế độ không tương tác thì nó không in ra bất cứ thứ gì trong suốt quãng đó, trông y hệt như bị treo. (Chỗ này nay đã được sửa: mỗi bước giờ in ra một dòng tiến độ.) Rồi bốn container khỏe mạnh hiện lên, tất cả đều gắn vào localhost: bảng điều khiển ở cổng 8080, API ở 3000, Postgres, và MinIO ở 9100. Nó khéo léo tránh những cổng mà bộ công nghệ của tôi đang dùng sẵn.

Ở chế độ này, đăng nhập bị tắt, và trang nào cũng có một cảnh báo là đừng đưa nó ra ngoài Internet.

localhost:8080

Bộ này có sẵn dữ liệu mẫu cho một ứng dụng tên Example Data, rất đáng xem trước khi bạn phát hành bất cứ thứ gì, vì nó cho thấy bảng điều khiển dùng để làm gì. Các con số trong hai ảnh chụp màn hình tiếp theo là dữ liệu mẫu đó, không phải người dùng thật.

localhost:8080

localhost:8080

Để so sánh, bảng điều khiển của tôi trước đây là một danh sách các bản cập nhật trong trang quản trị, kèm một ô đánh dấu “đang bật”. Tôi hoàn toàn không biết có bao nhiêu điện thoại đã thật sự nhận được bản cập nhật.

Đăng nhập cho CLI là một luồng trên trình duyệt đàng hoàng, dùng PKCE và một callback về localhost, và trang phê duyệt cho bạn biết tài khoản nào đang yêu cầu, cùng với việc mã sẽ hết hạn sau chừng một phút.

localhost:8080

Trỏ nó vào một ứng dụng thật

#

Patch muốn mỗi nền tảng là một ứng dụng riêng, mỗi ứng dụng được tạo sẵn hai môi trường triển khai (deployment) Staging và Production. Tôi tạo maru-ios trên bảng điều khiển và maru-android bằng cmpatch app create, chủ yếu để thử cả hai cách. Hộp thoại hiện ra sau khi tạo ứng dụng là màn hình hữu ích nhất của cả sản phẩm cho một đợt di chuyển: cả hai khóa triển khai (deployment key), hai URL mà SDK cần, và một ghi chú rằng khóa triển khai không phải là thông tin bí mật.

localhost:8080

Hai điểm nhỏ. Hồi đó cmpatch init chỉ liên kết dự án với những ứng dụng đã tồn tại, nên nó không thể là lệnh đầu tiên, dù hướng dẫn di chuyển có ngụ ý thế nào đi nữa. Điểm này nay đã được sửa: ở chế độ tương tác, lệnh này giờ tự tạo sẵn một ứng dụng cho mỗi nền tảng. Và hộp thoại đưa URL của API là http://localhost:8080, trong khi tài liệu và CLI thì nói 3000. Cả hai đều chạy được, vì mỗi cổng đều phục vụ cả hai thứ, nhưng bạn sẽ thắc mắc đấy.

Sau đó tôi chạy cmpatch doctor trên ứng dụng còn nguyên chưa sửa gì, và nó tìm ra một vấn đề thật sự trong ba giây. Nó báo phiên bản nhị phân iOS là 2.0.0. Trong khi ứng dụng đang ở 2.5.1.

CLI tìm mọi tệp Info.plist bên dưới ios/, và nếu không tệp nào có chữ “test” trong đường dẫn, nó lấy tệp đầu tiên theo thứ tự bảng chữ cái. maru có một tiện ích mở rộng WidgetKit mà thư mục của nó lại xếp trước thư mục của chính ứng dụng, nên CLI lấy nhầm Info.plist của tiện ích mở rộng. Tệp plist đó đã cũ, vẫn còn ghi 2.0.0, đây là lỗi của tôi, nhưng hậu quả thì rất khó chịu: cơ chế tự phát hiện sẽ nhắm mọi bản phát hành iOS vào một phiên bản mà không điện thoại nào đang chạy, và sẽ chẳng có lỗi nào bắn ra. Bản cập nhật đơn giản là không bao giờ tới nơi, đúng kiểu thất bại mà tôi đã cảnh báo trong bài về chuyện tự dựng máy chủ. Trên Android thì versionName được đọc đúng. Cách khắc phục là truyền --target-binary-version hoặc --plist-file, và script phát hành của tôi giờ truyền phiên bản một cách tường minh, sau khi kiểm tra rằng app.config.js và cả hai dự án native đều thống nhất với nhau. Về sau, cũng chính lỗi này khiến bước kiểm tra manifest của doctor thất bại trên một môi trường triển khai đang chạy hoàn toàn bình thường, vì nó đi tìm manifest của phiên bản 2.0.0. Sau khi tôi sửa tệp plist cũ kia, doctor vượt qua cả 24 bước kiểm tra.

Codemagic đã sửa lỗi này. Giờ CLI đọc phiên bản từ tệp Info.plist của target ứng dụng chứ không phải của tiện ích mở rộng, và nếu có nhiều hơn một target có thể là ứng dụng chính, cmpatch sẽ hỏi bạn chọn cái nào.

Phía JavaScript

#

Gỡ expo-updates ra và thêm SDK vào chỉ là thay đổi hai dòng. Còn thay thế những gì ứng dụng vốn làm với các bản cập nhật thì phải suy nghĩ nhiều hơn.

maru kiểm tra cập nhật khi mở ứng dụng và mỗi khi quay lại từ chế độ nền (foreground), tối đa mười lăm phút một lần. Nếu có bản mới, nó tải về rồi đề nghị khởi động lại; bạn từ chối thì bản đó sẽ được áp dụng ở lần khởi động nguội (cold start) tiếp theo. Trong phần Cài đặt còn có nút kiểm tra thủ công, cho biết bạn đang chạy gói mã (bundle) nào, và trình báo cáo lỗi gắn nhãn mọi báo cáo bằng bản cập nhật mà nó xuất phát.

Điều đầu tiên tôi học được từ mã nguồn SDK là nó tra cứu mô-đun native ngay lúc import bằng TurboModuleRegistry.getEnforcing, hàm này sẽ ném lỗi nếu mô-đun không tồn tại. maru còn có cả bản web, và một lệnh import ở cấp cao nhất sẽ làm sập luôn ứng dụng web. Nên mọi thứ đi qua một mô-đun nhỏ nạp SDK theo kiểu lười (lazy), kèm một bản song sinh .web.ts trả về rỗng, cách này cũng giữ SDK hoàn toàn nằm ngoài gói mã web.

// ota.ts (ota.web.ts exports a patchSdk() that always returns null)
import { Platform } from "react-native";

type PatchSdk = typeof import("@codemagic/react-native-patch");
let sdk: PatchSdk | null | undefined;

export function patchSdk(): PatchSdk | null {
  if (sdk !== undefined) return sdk;
  if (Platform.OS === "web") return (sdk = null);
  try {
    sdk = require("@codemagic/react-native-patch") as PatchSdk;
  } catch {
    sdk = null;
  }
  return sdk;
}

Bản thân bước kiểm tra tự động thì chủ yếu là sync(), hàm này không bao giờ ném lỗi mà trả về một trạng thái:

const status = await patch.sync({
  installMode: "ON_NEXT_RESTART",
  mandatoryInstallMode: "ON_NEXT_RESUME",
});
if (status === "update-installed") offerRestart();

Mặc định của SDK cho các bản phát hành bắt buộc (mandatory) là IMMEDIATE, tức là nạp lại JavaScript ngay bất kể người dùng đang ở đâu. Tôi đổi thành áp dụng vào lần ứng dụng quay lại từ chế độ nền tiếp theo, vì mất một bài viết đang gõ dở là một lỗi còn tệ hơn lợi ích của hầu hết các bản sửa. Vào thời điểm đó, InstallMode là một kiểu hợp chuỗi (string union), chứ không phải đối tượng enum như ví dụ trong tài liệu gợi ý; giờ nó đã được export dưới dạng một đối tượng hằng, nên InstallMode.ON_NEXT_RESTART chạy đúng như tài liệu viết.

Phía native, khi bạn đã commit ios/ và android/

#

Hướng dẫn di chuyển bảo chạy npx expo prebuild --clean sau khi thêm plugin cấu hình. Tôi chạy nó trong một bản checkout riêng, và nó xóa các ảnh đi kèm, tệp cấu hình bảo mật mạng của Android, tệp kê khai quyền riêng tư (privacy manifest) của iOS và Podfile.lock, đồng thời hoàn tác một bản sửa cho công cụ chạy kiểm thử trong build.gradle cùng vài trăm dòng của Info.plist. Bỏ --clean đi thì Expo vẫn dọn sạch cả hai thư mục.

Đây không phải lỗi của Patch. maru khởi đầu là một ứng dụng Expo dạng quản lý (managed) rồi dần có thêm những tùy biến native, nên ios/ và android/ được commit vào kho và EAS dựng chúng nguyên trạng. Nhưng có rất nhiều ứng dụng trông giống như vậy, và hồi đó hướng dẫn không hề cảnh báo bạn. Giờ thì có rồi: hướng dẫn di chuyển cho Expo tách thành hai hướng, chạy prebuild cho dự án có thư mục native được sinh tự động, và liệt kê chính xác những thay đổi cần áp dụng bằng tay cho dự án đã commit thư mục native.

Hóa ra những gì plugin thật sự thay đổi lại đủ nhỏ để làm bằng tay. Trên iOS, một dòng import và một dòng trong AppDelegate.swift:

return CodemagicPatch.bundleURL() ?? Bundle.main.url(forResource: "main", withExtension: "jsbundle")

Trên Android, một dòng import và một tham số trong MainApplication.kt (đây là dạng của React Native 0.82 trở lên; các phiên bản cũ hơn thì ghi đè getJSBundleFile()):

ExpoReactHostFactory.getDefaultReactHost(
  jsBundleFilePath = CodemagicPatch.getJSBundleFile(applicationContext),
  // ...

Cộng thêm ba giá trị cấu hình cho mỗi nền tảng và việc gỡ bỏ các thiết lập expo-updates cũ: 13 dòng thêm vào và 20 dòng xóa đi trên cả hai dự án.

Plugin ghi những giá trị cấu hình đó dưới dạng hằng (literal) vào lúc prebuild, mà với dự án native đã commit thì điều đó có nghĩa là mọi bản dựng (build) đều bị gắn cứng vào một môi trường triển khai duy nhất. Tôi muốn bản dựng xem trước (preview) đi vào Staging và bản dựng cho cửa hàng đi vào Production từ cùng một dự án, nên các giá trị này được lấy từ môi trường dựng thay vì ghi cứng. Trong Info.plist, Xcode tự mở rộng các thiết lập dựng:

<key>CodemagicPatchDeploymentKey</key>
<string>$(PATCH_IOS_DEPLOYMENT_KEY)</string>

Và trong android/app/build.gradle:

def patchEnv = { name -> System.getenv(name) ?: (findProperty(name) ?: "") }
resValue "string", "CodemagicPatchDeploymentKey", patchEnv("PATCH_ANDROID_DEPLOYMENT_KEY")

Các khóa sau đó nằm trong từng hồ sơ dựng (build profile) của eas.json, ngay cạnh các giá trị EXPO_PUBLIC_. Giá trị rỗng nghĩa là SDK lặng lẽ không làm gì cả, với bản dựng cục bộ thì không sao, nhưng với bản dựng cho cửa hàng thì là thảm họa, nên app.config.js giờ sẽ ném lỗi nếu một bản dựng EAS preview hoặc production thiếu chúng, hoặc vẫn còn trỏ về localhost.

Bản cập nhật đầu tiên

#

Cho bản phát hành đầu tiên, tôi đổi dòng tiêu đề của màn hình onboarding, thứ bạn thấy được mà không cần đăng nhập, rồi phát hành:

./scripts/publish-update.sh ios --notes "Onboarding headline over the air"

Mất 30 giây, phần lớn là Metro và Hermes. Worker của máy chủ công bố manifest 0.6 giây sau khi tải lên xong. Bản cập nhật là một tệp tarball nén 7.3 MB, so với 11 MB gồm gói mã Hermes cộng tài nguyên mà cách kết xuất (export) cũ của tôi tạo ra.

Có một chỗ phải làm cho đúng ở đây: gói mã JavaScript nhúng thẳng các giá trị EXPO_PUBLIC_ vào lúc dựng, nên bản cập nhật phải được dựng với đúng những giá trị của bản nhị phân mà nó sẽ đáp xuống, nếu không bạn sẽ đẩy đi một đoạn JavaScript nói chuyện với sai backend. Script của tôi nạp chúng từ đúng hồ sơ eas.json đã dùng để dựng bản nhị phân đó. Tài liệu về CI của Patch giờ cũng đã nói rõ điểm này, kèm theo lưu ý rằng bản thân release-react không đọc hồ sơ EAS.

Rồi tôi mở lại ứng dụng. Nhật ký (log) của thiết bị cho thấy toàn bộ lần kiểm tra cập nhật chỉ là hai yêu cầu tới kho lưu trữ đối tượng, meta.json và 2.5.1/manifest.json. SDK ghi một sự kiện Downloaded ba giây sau khi mở, xếp bản cập nhật vào hàng chờ, và ứng dụng đề nghị khởi động lại.

Lỗi là của tôi

#

Sau đó tôi nhìn vào bảng điều khiển. Một trình giả lập (simulator) đã cài bản phát hành v1, mà nó lại hiện hai lượt cài thành công và hai người dùng đang hoạt động.

localhost:8080

SDK lưu trạng thái và các sự kiện số liệu đang chờ gửi dưới dạng tệp trong container của ứng dụng, nên việc truy vết khá dễ. Có hai sự kiện Success với dấu thời gian (timestamp) giống hệt nhau nhưng id khác nhau. Hook của tôi xác nhận gói mã đang chạy bằng notifyAppReady() ngay khi được gắn (mount), rồi gọi sync() ngay sau đó, mà sync() thì tự gọi notifyAppReady() bên trong. Hai lời gọi chồng lên nhau, mỗi lời gọi đều thấy bản phát hành đang ở trạng thái chờ, và mỗi lời gọi đều ghi lại sự kiện. Máy chủ có khử trùng lặp theo id sự kiện, nhưng hai sự kiện này có id khác nhau, nên cả hai đều được đếm, và những bản ghi trùng đó nằm lại vĩnh viễn.

Cách sửa ở phía tôi là chỉ có một lần xác nhận dùng chung cho mỗi lần mở ứng dụng, mọi thứ khác đều phải chờ nó. SDK cũng có thể tự phòng ngừa các lời gọi chồng chéo, và tôi đã đề xuất điều đó. Giờ SDK đã làm vậy: các lời gọi notifyAppReady() chồng lên nhau, kể cả lời gọi nằm bên trong sync(), sẽ dùng chung một lần xác nhận, nên mỗi lượt cài chỉ được ghi nhận một lần. Tài liệu tham khảo của SDK giờ cũng ghi rõ rằng sync() tự xác nhận trạng thái sẵn sàng, nên ứng dụng nào đã dùng nó thì không cần gọi notifyAppReady() riêng nữa.

Phần thú vị là chuyện đẩy bản sửa đi. Đây là thay đổi thuần JavaScript, nên nó được phát hành thành bản v2, và vì thiết bị đang ở v1 có thể nhận một bản vá nhị phân (binary diff), v2 tải về dưới dạng bản vá 543 KB thay vì gói 7.3 MB, tức khoảng 7% kích thước. Sau khi khởi động lại: một lượt tải, một lượt cài, một lượt thành công, một thiết bị hoạt động.

localhost:8080

Cố tình làm hỏng

#

Khôi phục (rollback) là tính năng tôi quan tâm nhất, vì hệ thống cũ của tôi không có cơ chế nào trên thiết bị cả. Một bản cập nhật hỏng sẽ làm sập mọi lần mở ứng dụng cho tới khi tôi để ý và bỏ đánh dấu một ô.

Nên tôi phát hành bản v3 ném lỗi trước lần kết xuất giao diện (render) đầu tiên, nghĩa là nó không bao giờ gọi được notifyAppReady(). Ứng dụng tải về, đề nghị khởi động lại, rồi chết ngay về màn hình chính.

Lần mở tiếp theo lại khởi động v3 và lại sập, điều này làm tôi bất ngờ, vì tài liệu nói rằng gói mã nào sập trước khi gọi notifyAppReady() sẽ được khôi phục. Mã nguồn giải thích: SDK cho phép ba lần mở chưa được xác nhận trước khi kết luận là sập, vì một lần mở chưa xác nhận có thể chỉ là iOS đã diệt một tiến trình khỏe mạnh trước khi JavaScript kịp chạy. Lần mở thứ tư thì ứng dụng quay lại v2.

Thiết bị sau đó tự báo cáo thất bại này dưới dạng crash_rollback, và bảng điều khiển ghi nhận nó cho v3. Đó là một thiết kế hợp lý, nhưng cần nói thẳng ý nghĩa của nó: một bản phát hành hỏng khiến mỗi người dùng phải chịu ba lần mở ứng dụng bị sập trước khi hồi phục, và vào thời điểm đó tài liệu không nhắc tới con số này. Giờ thì tài liệu đã ghi, và ngân sách này cũng cấu hình được, qua CodemagicPatchMaxLaunchAttempts ở phía native hoặc tùy chọn maxLaunchAttempts của plugin Expo. Đó chính là lý do nên đẩy lên Staging trước, rồi mới phát hành theo từng đợt (rollout) nhỏ lên Production.

Chặn một bản phát hành hỏng cho tất cả những người còn lại chỉ là một lệnh, và mất chưa tới một giây:

cmpatch release rollback --app maru-ios --deployment Staging

Nó không viết lại lịch sử. Nó công bố lại bản phát hành trước đó thành một bản mới (v4, được đánh dấu là bản khôi phục của v2), nên bản đang gây sập vẫn nằm trong danh sách với số lượt thất bại của nó, đây là cách ghi chép trung thực. Bảng điều khiển làm điều tương tự qua một hộp thoại.

localhost:8080

Android

#

Android có hai bất ngờ, đều không phải do Patch. Quy tắc keep cho R8 mà tôi thêm cho SDK nằm trong app.config.js, thứ chỉ tới được dự án native thông qua prebuild, nên bản dựng release đầu tiên của tôi vô tình trở thành bài kiểm thử xem SDK có sống sót qua R8 mà không cần quy tắc đó hay không. Kết quả là có: R8 đổi tên toàn bộ các lớp của nó, mà bản cập nhật vẫn tải, cài và khôi phục bình thường. Còn trình giả lập (emulator), vừa khởi động nguội xong trong khi Gradle vẫn đang chiếm bộ nhớ, chậm đến mức bài kiểm thử đầu tiên của tôi bỏ cuộc 45 giây trước khi SDK tải xong bản cập nhật mà nó đã bắt đầu tải.

Bản v1 được áp dụng, với một lượt thành công và một thiết bị hoạt động, còn bản v2 gây sập thì được khôi phục sau cùng một ngân sách ba lần mở như trên.

Vượt ra ngoài kịch bản suôn sẻ

#

Bản cập nhật tới nơi và khôi phục được là phần lõi, nhưng một đội (team) sống với những tính năng còn lại, nên tôi đi qua từng cái một.

Phát hành theo từng đợt là tất định (deterministic), điểm này tôi thích. Một thiết bị được nhận bản mới nếu tám chữ số hex đầu của md5(deviceId + "-" + releaseLabel), lấy modulo 100, nhỏ hơn tỷ lệ phát hành, nên với một bản phát hành nhất định, cùng một chiếc điện thoại sẽ luôn được nhận hoặc luôn không được nhận. Tôi tính ra trình giả lập của mình rơi vào nhóm 91 cho bản phát hành kế tiếp, công bố nó ở mức 25%, và trình giả lập đúng là không nhận được gì. Nâng lên 95% bằng cmpatch release patch, mất chưa tới một giây, thì nó cập nhật ở lần mở tiếp theo.

Rồi bản phát hành tiếp theo của tôi thất bại với mã 409: “deployment has an active rollout below 100 percent”. Mỗi môi trường triển khai chỉ được phép có một đợt phát hành một phần tại một thời điểm, nên bạn phải hoàn tất, tắt hoặc khôi phục bản canary trước khi đẩy bất cứ thứ gì khác. Điều đó hợp lý, và có ghi trong tài liệu, nhưng một quy trình (pipeline) tự phát hành sau mỗi lần merge sẽ đâm phải nó ngay giữa một đợt canary. Từ sau khi tôi báo cáo, CLI đã giải thích rõ ở chỗ này: nếu bạn đang bị chặn bởi một đợt phát hành một phần còn dang dở, nó cho biết chờ cũng vô ích và hướng dẫn cách hoàn tất hoặc tắt đợt đó; còn nếu có một tác vụ phát hành khác vẫn đang chạy, nó bảo bạn chờ bằng release inspect --wait. Tài liệu giờ cũng có riêng một phần về việc thực hiện các thay đổi phát hành theo tuần tự.

Bản phát hành bắt buộc dùng mandatoryInstallMode của SDK. Với thiết lập của tôi là áp dụng vào lần quay lại tiếp theo, ứng dụng tải bản cập nhật về và hiện hộp thoại, và khi tôi lờ hộp thoại đi, đưa ứng dụng xuống nền rồi mở lại, phiên bản mới đơn giản là đã ở đó.

Tắt một bản phát hành không chỉ là ngừng cung cấp nó. Ngay khi tôi tắt bản mới nhất, các manifest trỏ về bản phát hành mới nhất còn đang bật, và các thiết bị đang chạy bản bị tắt được đề nghị một bản vá để quay về đó. Tắt hết mọi bản cho một phiên bản nhị phân thì đích của manifest trở thành null, và SDK đưa ứng dụng về gói mã đi kèm ban đầu. Hook cập nhật của tôi lúc đầu không hiện hộp thoại cho trường hợp này, nên giờ tôi đã bổ sung.

Chuyển (promote) từ Staging lên Production mất chưa tới một giây và dùng lại đúng gói đã được kiểm thử, cùng mã băm (hash) và ghi chú, thay vì dựng lại. Lệnh này cũng nhận tỷ lệ phát hành, nên “chuyển lên 10% của Production” chỉ là một lệnh.

Dựng và phát hành cũng có thể tách thành hai bước riêng. cmpatch bundle tạo ra một tệp .cmpatch, và tùy chọn “Bundle upload” trên bảng điều khiển sẽ đọc nó trước khi tải lên: nền tảng, phiên bản đích, dấu vân tay, trạng thái ký, kích thước và công cụ đóng gói. Cách này hợp với mô hình CI dựng tệp, còn một người khác quyết định khi nào phát hành.

Đó cũng là chỗ tôi thật sự va phải cơ chế bảo vệ bằng dấu vân tay. Sau khi sửa tệp plist cũ của widget, máy chủ từ chối bản phát hành tiếp theo với mã 409, vì dấu vân tay của dự án native không còn khớp với cái nó đã ghi nhận cho 2.5.1. Trên Android, chỉ sửa một dòng chú thích (comment) trong app.config.js cũng đủ, vì Expo đưa cả cấu hình ứng dụng vào dấu vân tay. Bảng điều khiển hiện cùng kiểm tra đó dưới dạng cảnh báo với cả hai dấu vân tay và một nút “Upload anyway”. Trong cả hai trường hợp, phần native trên bản nhị phân đã cài không hề thay đổi, nên bỏ qua cảnh báo là đúng. Nhưng trong thực tế, câu trả lời trung thực gần như luôn là tăng phiên bản và dựng bản mới cho cửa hàng, và script phát hành của tôi giờ nói đúng như vậy khi chuyện này xảy ra.

Ký mã dùng RS256: CLI ký mã băm của gói bằng một khóa riêng RSA, và SDK đối chiếu với khóa công khai được biên dịch sẵn vào bản nhị phân. Khóa được đưa vào dưới dạng một dòng base64 duy nhất, khớp với cách tiếp cận qua thiết lập dựng của tôi, và tôi đã kiểm thử trên cả hai nền tảng. Khi ứng dụng đã có khóa, một bản phát hành chưa ký bị từ chối trước cả khi tải về. Khi bật “require code signing” cho ứng dụng, máy chủ từ chối một lần phát hành chưa ký với thông báo lỗi nêu rõ cách sửa và dẫn liên kết tới hướng dẫn. Bản phát hành đã ký thì cài được, và SDK ghi nhận chữ ký là đã xác minh. Nó cũng từ chối một bản phát hành cũ chưa ký mà máy chủ quay về khi tôi tắt bản đã ký. Điểm cần lưu ý là khóa công khai phải có mặt trong bản nhị phân đầu tiên bạn phát hành, vì bản cập nhật không thể thêm nó vào được.

localhost:8080

Phần đội nhóm và CI cũng được lo. Thành viên nhận một trong bốn vai trò áp dụng toàn đội (owner, admin, developer, viewer), và lời mời sẽ chờ cho tới khi người đó đăng nhập lần đầu. Token truy cập cá nhân (personal access token) chạy được với thư mục home trống, truyền qua --token hoặc qua biến môi trường, và danh sách token cho biết mỗi token được dùng lần cuối khi nào. Tôi cũng đã viết một workflow CI chạy thủ công, chạy cùng script phát hành đó trên một runner Linux với khóa ký lấy từ secret, dù tôi chưa chạy nó, vì nó cần máy chủ thật.

Một công cụ mà hồi đó tôi sẽ bỏ qua là cmpatch debug ios. Nó phát trực tiếp nhật ký hệ thống được lọc theo chữ “OTA” không phân biệt hoa thường, mà chuỗi này khớp cả với “Rotation”, nên một lần mở ứng dụng kéo dài hai mươi giây cho ra cả màn hình thông điệp của SpringBoard mà không có dòng nào từ ứng dụng. Lỗi này đã được sửa: giờ nó chỉ hiện những dòng mang dấu hiệu nhận biết của SDK. Bản thân SDK cũng không ghi nhật ký nhiều, chủ yếu là lỗi và cảnh báo trong bản dựng phát triển, nên đừng ngạc nhiên nếu luồng nhật ký khá im ắng. Còn cảnh báo getpwuid_r mà bạn có thể thấy là đến từ xcrun simctl, không phải từ Patch.

Rốt cuộc thì khó tới mức nào

#

Codemagic hỏi ý kiến của tôi, nên đây là ý kiến đó, nói thẳng nhất có thể.

Chạy thử thì dễ. Hai lệnh, vài phút, và bạn có máy chủ thật, một bảng điều khiển với dữ liệu demo, và một CLI trỏ được vào ứng dụng của chính bạn. Tôi đánh giá đây là phần tốt nhất trong giờ đầu tiên.

Tích hợp SDK là việc ở mức vừa phải, và phần lớn cái khó nằm ở dự án của chính bạn chứ không phải ở Patch. Với một ứng dụng Expo mới tinh có thư mục native được sinh tự động, thì đúng là chỉ cần plugin cộng vài dòng thay thế các lời gọi expo-updates. Với một ứng dụng như maru, có dự án native đã commit, một tiện ích mở rộng widget, một bản web, R8 và các hồ sơ dựng, thì công việc nằm ở những chỗ rìa. Tôi phải áp dụng các thay đổi native bằng tay để tránh prebuild, đưa cấu hình về lúc dựng để bản Staging và Production có thể khác nhau, và giữ SDK tránh xa bản web. Tôi cũng phải đảm bảo JavaScript trong bản cập nhật được dựng với cùng môi trường như bản nhị phân. Không việc nào khó khi đã hiểu. Lúc tôi làm thì phần lớn những điều đó chưa có trong tài liệu, dù giờ hướng dẫn cho dự án native đã commit và chuyện môi trường lúc đóng gói đều đã được bổ sung.

Dùng hằng ngày thì tốt. Phát hành là một lệnh và chừng nửa phút. Phát hành theo từng đợt, chuyển môi trường, tắt và khôi phục đều dưới một giây từ CLI hoặc bảng điều khiển, và thông báo lỗi nói rõ đã sai gì và phải làm gì. Các cơ chế bảo vệ của máy chủ (kiểm tra dấu vân tay, mỗi lần chỉ một canary, ký mã) nghiêm ngặt theo cách đã hơn một lần ngăn tôi làm sai.

Vận hành nó trên production là cam kết lớn hơn. Đó là một bộ Docker Compose với Postgres và kho lưu trữ đối tượng mà bạn phải tự lưu trữ, sao lưu và nâng cấp, cộng thêm hai tên miền và một ứng dụng OAuth. Với một đội đã quen vận hành máy chủ thì đó là một buổi chiều yên ả. Với một đội dùng EAS chính vì không muốn dính tới máy chủ, đây mới là chi phí thật của việc chuyển đổi, hơn cả phần việc với SDK.

Tính theo thời gian thực, tôi cài CLI lúc 12:29 và có bản cập nhật đầu tiên áp dụng trên trình giả lập lúc 13:34, trong đó nửa tiếng là một lần dựng Xcode bị treo vì lý do không liên quan tới Patch. Mọi thứ trong bài này, trên cả hai nền tảng, đều xong trước giữa buổi chiều, chưa tính máy chủ thật.

Những thứ ngốn của tôi nhiều thời gian nhất, theo thứ tự: expo prebuild --clean xóa sạch dự án native đã commit, rồi việc tìm cách nối mọi thứ bằng tay; lỗi phát hiện phiên bản trên iOS, thứ suýt gửi bản cập nhật tới một phiên bản không ai chạy; các lượt cài bị đếm trùng, lỗi do chính tôi gây ra nhưng ai cũng dễ lặp lại, vì sync() tự gọi notifyAppReady(); và ngân sách ba lần mở khi sập chưa được ghi trong tài liệu, thứ làm tôi bất ngờ giữa chừng một bài kiểm thử. Sau đó là những thứ đúng nhưng cần lên kế hoạch: cơ chế bảo vệ dấu vân tay kích hoạt sau những chỉnh sửa vô hại gần với native, mỗi môi trường triển khai chỉ một canary tại một thời điểm, và các tác vụ vòng đời không được chồng lên nhau, điều này quan trọng ngay khi một script làm nhiều việc liên tiếp. Phần còn lại đều nhỏ: lần thiết lập đầu tiên chạy im lặng, một lệnh gỡ lỗi ồn ào, và vài ví dụ trong tài liệu hồi đó không khớp với mã.

Tôi đã viết toàn bộ những điều này, kèm chi tiết, gửi cho Codemagic, và tới ngày 23 tháng 9 thì phần lớn đã được sửa: phát hiện phiên bản, các lần xác nhận chồng lên nhau, cảnh báo về prebuild, ngân sách số lần mở khi sập, lần thiết lập im lặng, lệnh gỡ lỗi, các ví dụ về InstallMode, và thông báo lỗi khi bị một tác vụ phát hành hoặc một bản canary chặn đường. Những gì còn tồn đọng thì nhỏ hơn: bảng điều khiển hiển thị API ở :8080 trong khi mọi chỗ khác đều ghi :3000, SDK ném lỗi ngay lúc import trên web và trong Jest, và vài chỗ còn thiếu trong tài liệu.

Đưa lên production

#

Mọi thứ ở trên đều chạy trên bộ đánh giá. Production là cùng ứng dụng và cùng script đó trỏ vào một máy chủ thật, và đây là kế hoạch cho maru.

Cách vận hành máy chủ được hỗ trợ chính thức là cài bằng Docker Compose: một máy Linux mở cổng 80 và 443, hai tên miền (một cho API và bảng điều khiển, một cho tải xuống), và một ứng dụng GitHub OAuth để đăng nhập, không có nó thì máy chủ không chịu khởi động. Trình cài đặt lo phần còn lại, kể cả TLS:

scripts/selfhost/install.sh \
  --api-domain updates.example.com \
  --storage-domain storage.updates.example.com \
  --email you@example.com \
  --github-oauth-client-id <id> --github-oauth-client-secret <secret>

Nó ghi ra một tệp .env.selfhost chứa các khóa bí mật của cơ sở dữ liệu và kho lưu trữ, thứ nên nằm trong trình quản lý mật khẩu của bạn.

Nhưng bạn không bắt buộc phải dùng cơ sở dữ liệu và kho lưu trữ đi kèm, và đó chính là điểm khiến nó vừa với một bộ công nghệ như của tôi. API của maru đã chạy trên Fly.io và tệp của nó nằm trên Tigris, mà Patch chạy được trên cả hai. Bên dưới tệp Compose, máy chủ là một container chạy ở MODE=all (API và worker phát hành gộp chung) cần một cơ sở dữ liệu Postgres, kho lưu trữ tương thích S3 và một URL HTTPS công khai cho các tệp. Tức là một ứng dụng Fly dựng từ Dockerfile trong kho mã (chưa có image được công bố, nên fly deploy sẽ tự dựng), một cơ sở dữ liệu Fly Postgres, và một bucket Tigris:

MODE=all
DATABASE_URL=postgresql://…            # Fly Postgres
STORAGE_ADAPTER=s3
S3_ENDPOINT=https://fly.storage.tigris.dev
S3_REGION=auto
S3_BUCKET=myapp-patch
S3_FORCE_PATH_STYLE=true
PUBLIC_BASE_URL=https://myapp-patch.fly.storage.tigris.dev/codemagic-patch

Hai điều cần lưu ý. Chạy ngoài Compose được ghi trong kho mã như tài liệu tham khảo, chứ không phải cách được hỗ trợ trong bản mã nguồn mở đầu tiên này, nên trên Fly bạn phải tự lo nâng cấp và sao lưu. Tôi cũng chưa triển khai theo cách đó; đây là kế hoạch, chưa phải báo cáo. Và nếu bạn đã đọc bài của tôi về cơ chế thu về 0 của Fly, hãy giữ ít nhất một máy luôn chạy. Điện thoại không bao giờ phải chờ API khi kiểm tra cập nhật, vì manifest lấy thẳng từ kho lưu trữ, nhưng nếu không thì mọi lần tải số liệu lên và mọi tác vụ phát hành sẽ bắt đầu bằng một lần khởi động nguội.

Tigris là phần tôi hào hứng nhất. Đó là nơi tệp của maru vốn đã nằm, và nó đặt một CDN phía trước cái URL mà mọi lần mở ứng dụng đều gọi tới. Nếu làm theo cách này, hãy để ý việc lưu đệm (cache) manifest: với bộ điều hợp (adapter) phân phối theo URL gốc đơn giản, Patch trả manifest với no-cache, vì nó không thể xóa bộ nhớ đệm trên CDN, và một manifest bị lưu đệm theo TTL riêng sẽ tiếp tục phục vụ một bản phát hành mà bạn vừa khôi phục xong. Tài liệu tham khảo cấu hình giờ đã ghi rõ điều này ở mục MANIFEST_CACHE_CONTROL, và trang tài liệu cũng đã có phần về kho lưu trữ tương thích S3.

Trên máy chủ thật, bạn tạo lại các ứng dụng, đưa khóa mới vào hồ sơ preview và production trong eas.json (khóa Staging và khóa Production), và tạo một token để phát hành:

cmpatch token create --name ci

Nếu muốn ký mã, hãy quyết định ngay từ bây giờ: tạo cặp khóa cho production, giữ khóa riêng làm secret trong CI, đưa khóa công khai vào các hồ sơ dựng, và bật “require code signing” cho cả hai ứng dụng. Bản nhị phân đầu tiên có Patch cũng cần một số phiên bản mới, vì các bản nhị phân đang nằm trên cửa hàng vẫn chạy expo-updates. Dựng nó bằng hồ sơ preview cho TestFlight và kiểm thử nội bộ trên Play trước, rồi kiểm tra xem các khóa có thật sự vào được Info.plist đã dựng và tài nguyên Android hay chưa, trước khi đưa cho bất kỳ ai. Đó là mắt xích duy nhất mà các bài kiểm thử cục bộ của tôi chưa chạm tới, vì tôi đã xuất biến môi trường bằng tay. Sau đó phát hành lên Staging, xác nhận mỗi người thử nghiệm có một lượt tải và một lượt thành công, rồi mới dựng bản cho cửa hàng.

Bản phát hành lên production thì bắt đầu nhỏ rồi tăng dần:

./scripts/publish-update.sh ios --production --rollout 10
cmpatch release patch --app maru-ios --deployment Production --label v1 --rollout-percentage 100

Trong lúc đó, máy chủ cũ vẫn giữ nguyên. Mọi bản 2.5.1 mà người dùng chưa cập nhật vẫn kiểm tra ở đó, và bản sửa nóng (hotfix) cho họ vẫn đi qua script cũ. Khi nhật ký cho thấy những yêu cầu đó đã dừng hẳn, thì máy chủ cũ, script phát hành và khóa bí mật của nó đều có thể bỏ đi.

Lần nâng cấp native đầu tiên

#

Bổ sung ngày 16 tháng 10 năm 2026.

Từ đầu tháng 10, Patch đã đảm nhận việc phân phối các bản cập nhật production của maru. Bản phát hành native đầu tiên kể từ đó là đợt chuyển lên Expo SDK 58: React Native 0.88, và trên Android là một phiên bản chính (major) mới của plugin Gradle. Thay đổi native không thể gửi qua mạng, nên đó là một bản nhị phân mới, 2.6.0, và script phát hành của tôi từ chối gửi bản cập nhật cho 2.6.0 cho tới khi bản nhị phân đó tồn tại. Cả hai nền tảng đều dựng trơn tru ngay lần đầu.

Phần production ở trên dặn hãy kiểm tra xem các khóa có thật sự vào được Info.plist đã dựng và tài nguyên Android hay chưa, trước khi đưa bản dựng cho bất kỳ ai. Lần này tôi đã kiểm tra thật, và chính bước kiểm tra đó là lý do phần này tồn tại. Bản dựng iOS có đủ bốn thiết lập của Patch. Bản dựng Android thì không có cái nào:

bundletool dump resources --bundle=build.aab --values | grep -A1 "string/Codemagic"

Lệnh đó in ra bốn khóa với bản dựng 2.5.11 và không in gì với 2.6.0. Vấn đề không nằm ở biến môi trường: tác vụ generateReleaseResValues của Gradle ghi đủ cả bốn. Chúng bị xóa ở bước sau bởi bộ thu gọn tài nguyên (resource shrinker) của bản release, thứ mà trong Android Gradle Plugin 9 đã trở nên mạnh tay hơn nhiều. Cùng một ứng dụng mà số tài nguyên giảm từ 9,240 xuống 7,116. SDK đọc cấu hình theo tên bằng getIdentifier, thứ mà bộ thu gọn không nhìn thấy, nên nó coi bốn chuỗi đó là không dùng tới và xóa đi. Một chuỗi bị thiếu được đọc thành rỗng, và rỗng nghĩa là “không có cập nhật”. Sẽ không có gì thất bại cả. Android 2.6.0 sẽ cài được, chạy bình thường và không bao giờ nhận được bản cập nhật nào, và dấu hiệu duy nhất là trên bảng điều khiển không có thiết bị Android 2.6.0 nào.

Cách sửa là một tệp tài nguyên bảo bộ thu gọn giữ lại bốn chuỗi đó:

<!-- android/app/src/main/res/raw/codemagic_patch_keep.xml -->
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@string/CodemagicPatch*" />

Đừng đặt tên nó là keep.xml: tác vụ đóng gói của React Native đã tự sinh một tệp raw/keep.xml cho các tài nguyên JavaScript của bạn (đó là lý do hình ảnh và phông chữ vẫn sống sót), và hai tệp sẽ đụng nhau. Chỗ hợp lý hơn cho quy tắc này là chính SDK, vì tệp keep của một thư viện được gộp vào ứng dụng một cách tự động, và chỉ cần một cảnh báo khi bản dựng release khởi động mà không có khóa triển khai là trường hợp im lặng này sẽ trở nên dễ thấy. Đây là cùng kiểu thất bại với lỗi phát hiện phiên bản trên iOS ở phần trước: không có gì báo lỗi, và bản cập nhật cứ thế không bao giờ tới.

Cũng bước kiểm tra đó còn lộ ra vấn đề thứ hai chẳng liên quan gì tới Patch, và nó đáng biết vì một lý do khác. Bản dựng release Android sập ngay khi mở, tới hai lần, vì hai lý do riêng biệt nằm trong chính các mô-đun của Expo. Đầu tiên, mô-đun widget của Expo không đăng ký được các lớp native của nó, nên ứng dụng chết trước khi bất kỳ dòng JavaScript nào kịp chạy. Sửa xong lỗi đó, ứng dụng chạy được tới lúc khởi động JavaScript rồi dừng lại, vì ba mô-đun đã chuyển sang hệ thống mô-đun mới của Expo chưa bao giờ được đăng ký. Cơ chế khôi phục khi sập của Patch không giúp được gì trong cả hai trường hợp, vì không có bản cập nhật nào để khôi phục. Nó bảo vệ bạn khỏi một bản cập nhật hỏng, chứ không phải khỏi một bản nhị phân hỏng. Có Patch hay không thì một lần nâng cấp native vẫn phải được cài và mở thử trên một thiết bị thật hoặc trình giả lập trước khi lên cửa hàng.

Cũng từ đợt thử nghiệm đó còn một chuyện nhỏ hơn. Khi sync() thất bại, nó trả về "error" và giữ kín lý do, trừ khi ứng dụng đang chạy ở chế độ phát triển, nên một bản dựng release chỉ có thể ghi vào nhật ký rằng đã có gì đó trục trặc. Giờ hook của tôi gọi checkForUpdate() một lần sau mỗi lần sync thất bại và ghi lại lỗi mà nó ném ra, và nhờ vậy tôi mới biết một bản dựng cho trình giả lập cục bộ có các URL Patch rỗng (unsupported URL), chứ không phải máy chủ bị hỏng. Sẽ có ích nếu lỗi gần nhất cũng đọc được trong bản dựng release.

Danh sách kiểm tra cho một bản phát hành native của tôi giờ có thêm ba dòng mà trước đây không có: trích xuất các thiết lập Patch từ tệp .ipa và .aab đã dựng, so sánh khóa triển khai với hồ sơ dựng, và chạy chính bản dựng release, không phải bản dựng debug, trước khi nộp.

Điều tôi muốn nói với ai đang trả hóa đơn cho Expo

#

Nếu bạn đang trả tiền cho EAS Update vì thấy tự dựng máy chủ có vẻ quá nhiều việc, thì Patch là một câu trả lời thật sự: bạn vẫn phải vận hành một máy chủ, nhưng đó là một bộ Compose và một trình cài đặt, chứ không phải mã mà bạn phải tự bảo trì. So với thứ tôi đã xây, bạn có thêm phát hành theo từng đợt, số lượt cài và thất bại của từng bản, bản vá nhị phân, cơ chế bảo vệ bằng dấu vân tay, ký mã, khôi phục khi sập ngay trên thiết bị, và một nút khôi phục. Tôi chưa từng xây được cái nào trong số đó.

Cái giá phải trả: một bản nhị phân mới trước khi bất kỳ ai nhận được bản cập nhật qua Patch, vì SDK phải có trong ứng dụng; một máy chủ phải giữ cho luôn được nâng cấp và sao lưu; mặc định là ba lần mở ứng dụng bị sập cho mỗi người dùng khi một bản phát hành hỏng đủ nặng; và một ít việc làm tay nếu dự án native của bạn đã commit. Nó cũng còn non. Đây là phiên bản 0.3.0, và tôi gặp một lỗi phát hiện phiên bản, một lệnh gỡ lỗi ồn ào và vài chỗ thiếu trong tài liệu, cộng thêm một lỗi do chính tôi gây ra mà SDK lẽ ra có thể ngăn được. Từ đó tới nay, lỗi phát hiện phiên bản và lệnh gỡ lỗi đều đã được sửa, phần lớn chỗ thiếu trong tài liệu đã được lấp, và SDK giờ đã tự phòng ngừa đúng cái sai mà tôi mắc phải. Không điều nào trong số đó cản trở đợt di chuyển, và tất cả đều nhìn thấy được, trên CLI, trên bảng điều khiển, hoặc ngay trong các tệp của SDK trên thiết bị, điều mà tôi không thể nói về hệ thống cũ của mình.

Ứng dụng chợ (marketplace) mà tôi đang làm là một ứng dụng trang đơn (single-page app) viết bằng React Native Web. Trước khi JavaScript chạy, trang tin đăng (listing) nào cũng chỉ có đúng một thẻ script và một thẻ div rỗng. Với người dùng thì chẳng sao, nhưng với công cụ tìm kiếm thì coi như xong: Google thỉnh thoảng chạy được JS, Bing thì không, còn trình thu thập dữ liệu (crawler) của Naver — thứ quan trọng nhất với một trang web mà gần như toàn bộ tin đăng đều bằng tiếng Hàn — thì chắc chắn là không.

Bài này kể lại quá trình tôi làm cho các trang đó hiện ra với công cụ tìm kiếm, rồi chuyện một quy tắc lưu đệm (cache rule) phá hỏng tất cả theo cách tôi không hề lường trước.

Kết xuất động, chứ không phải che giấu nội dung

#

Cách sửa thì chẳng có gì mới, và được chính Google chấp nhận dưới cái tên kết xuất động (dynamic rendering), khác hẳn với che giấu nội dung (cloaking): nhận diện trình thu thập dữ liệu, rồi trả cho nó HTML đã kết xuất (render) sẵn ở máy chủ, chứa đúng nội dung mà SPA lẽ ra sẽ vẽ lên màn hình. Không phải nội dung khác. Vẫn nội dung ấy, chỉ là có sớm hơn.

Vì vậy, một URL tin đăng như /listings/view?id=... được tách làm hai nhánh. Trình duyệt nhận phần khung (shell) của SPA. Trình thu thập dữ liệu nhận một tài liệu HTML thật sự: tiêu đề, các thông tin chính của tin đăng, mỗi ảnh một thẻ ảnh kèm văn bản thay thế (alt text), một đoạn trích nội dung, và liên kết sang vài tin đăng liên quan để trang không bị mồ côi.

Phần cuối này hoá ra quan trọng hơn tôi nghĩ. Trước khi có mấy liên kết nội bộ đó, khoảng một nghìn trang tin đăng nằm trơ trọi, không có liên kết nào trỏ tới, và Search Console cho thấy lượng thu thập chững lại ở mức bảy đến mười một yêu cầu mỗi ngày. Trình thu thập dữ liệu mà không tìm thấy trang của bạn thì trang có hay đến mấy cũng vô nghĩa.

Cái bẫy: tên công ty không phải là tên bot

#

Nhận diện trình thu thập dữ liệu thực chất là so khớp chuỗi user-agent, và tôi dính đòn đúng ở bước này.

Các nền tảng Hàn Quốc cho trình thu thập dữ liệu chạy dưới những cái tên chẳng liên quan gì tới tên công ty. Trình thu thập của Naver tên là Yeti. Của Daum là Daumoa. Còn công cụ cào dữ liệu (scraper) lấy bản xem trước liên kết của Kakao là kakaotalk-scrap. Không cái nào mang đúng tên công ty.

Trong khi đó, cũng chính mấy công ty này làm ứng dụng có trình duyệt nhúng bên trong, và trình duyệt đó gửi user-agent y như trình duyệt thật, chỉ gắn thêm tên ứng dụng ở cuối. Trình duyệt trong ứng dụng KakaoTalk ghi KAKAOTALK/10.5.1. Công cụ cào dữ liệu của Kakao thì ghi kakaotalk-scrap/1.0.

Cứ so khớp theo kakao là bạn tóm luôn cả hai. Tôi đã làm đúng như vậy, thế là người dùng KakaoTalk, ứng dụng Naver hay ứng dụng Daum nào mở liên kết cũng nhận về trang dành cho trình thu thập: không JavaScript, không điều hướng, không đăng nhập. Một tài liệu hoàn toàn chuẩn chỉnh, nhưng với con người thì vô dụng.

Cách sửa là một quy tắc về thứ tự kiểm tra, và đáng để viết hẳn ra thành quy tắc:

import re

# In-app browsers append the app's name to an ordinary browser UA.
INAPP_BROWSER_RE = re.compile(r"kakaotalk/|naver\(inapp|daumapps", re.I)

# Name the bot, never the vendor: Naver crawls as Yeti, Daum as Daumoa,
# Kakao's link-preview scraper as kakaotalk-scrap.
CRAWLER_RE = re.compile(r"googlebot|bingbot|yeti/|daumoa|kakaotalk-scrap", re.I)


def is_crawler(user_agent: str) -> bool:
    # An in-app browser is never a crawler, so that check comes first.
    if not user_agent or INAPP_BROWSER_RE.search(user_agent):
        return False
    return bool(CRAWLER_RE.search(user_agent))

Trình duyệt trong ứng dụng được kiểm tra trước, và luôn thắng. Còn token nhận diện trình thu thập nào cũng phải là tên của một bot, tuyệt đối không phải tên công ty.

Rồi tôi đặt Cloudflare đứng trước

#

Máy chủ gốc (origin) chỉ là một máy shared-cpu duy nhất đặt ở Sydney, chịu tải ổn định được khoảng hai mươi đến ba mươi yêu cầu mỗi giây. Googlebot có chừng 995 URL cần đi qua. URL nào cũng chạy thẳng về Sydney, vì cf-cache-status ở tất cả đều là DYNAMIC: Cloudflare không lưu đệm HTML trừ khi có quy tắc bảo nó làm vậy. Cả vùng (zone) chỉ khoảng 16% được lưu đệm, và phần quan trọng thì không nằm trong số đó.

Vậy thì thêm một quy tắc lưu đệm cho các trang dành cho trình thu thập. Đơn giản. Có điều, một URL tin đăng không chỉ có một phần thân (body). Nó có tới ba.

• Trình thu thập dữ liệu xin HTML thì nhận trang kết xuất ở máy chủ.
• Người dùng thật thì nhận phần khung của SPA.
• Tác tử AI (AI agent) gửi Accept: text/markdown thì nhận markdown dựng từ cơ sở dữ liệu, vì đem một khung HTML rỗng đi chuyển đổi thì cũng chỉ ra một tài liệu rỗng.

Máy chủ gốc có trả Vary: Accept, còn Vary theo user-agent thì đằng nào cũng vô vọng. Và đây là điều tôi không hề biết:

Cloudflare bỏ qua Vary với HTML. Cả ba phần thân dùng chung một khoá lưu đệm (cache key).

Phần thân nào tới trước sẽ chiếm luôn URL đó cho mọi lượt truy cập sau ở điểm biên (edge location) ấy, trong suốt một tiếng mà s-maxage của máy chủ gốc cho phép, cộng thêm một ngày stale-while-revalidate.

Tôi được tận mắt thấy chuyện này trên môi trường production, theo cả hai chiều:

• Một người dùng ứng dụng Naver mở một URL tin đăng trước, bộ nhớ đệm giữ lại trang dành cho trình thu thập, rồi sau đó Safari bình thường trên iPhone nhận đúng trang ấy dưới dạng HIT. Một con người ngồi nhìn một tài liệu không có tí JavaScript nào.
• Một người dùng thật mở một URL trước, bộ nhớ đệm giữ lại phần khung của SPA, và Googlebot nhận về cái khung rỗng. Đúng cái lỗi mà cả nỗ lực SEO sinh ra để ngăn chặn, giờ lại còn được phục vụ nhanh hơn, ngay từ máy chủ biên.

Cái quy tắc sửa lỗi bằng cách thu hẹp phạm vi

#

Bạn không thể bắt Cloudflare tôn trọng Vary với HTML. Cái bạn làm được là đảm bảo trong ba phần thân đó, chỉ đúng một cái có cửa vào bộ nhớ đệm:

(starts_with(http.request.uri.path, "/listings/")
 and not any(http.request.headers["accept"][*] contains "text/markdown")
 and (lower(http.user_agent) contains "googlebot" or ...)
 and not (lower(http.user_agent) contains "kakaotalk/" or ...))

Chỉ khớp user-agent của trình thu thập, và loại trừ yêu cầu xin markdown. Giờ yêu cầu của người dùng thật không khớp quy tắc nào cả, nên nó là DYNAMIC và đi về máy chủ gốc như trước. Chỉ yêu cầu của trình thu thập mới được đọc hoặc ghi bộ nhớ đệm, nên phần thân duy nhất có thể nằm trong đó là phần thân dành cho trình thu thập.

Edge TTL để là respect_origin, nên thời gian sống của dữ liệu đệm vẫn do chính phần mã kết xuất trang quyết định, chứ không bị đóng cứng trong một bảng điều khiển nào đó.

Có một chi tiết vận hành rất dễ bỏ sót: thu hẹp quy tắc không xoá những gì đã nằm sẵn trong bộ nhớ đệm. Bạn phải xoá bộ nhớ đệm (purge), không thì vẫn tiếp tục trả ra những mục nhiễm độc mà mình vừa ngừng tạo ra.

Hai danh sách, và vì sao sai lệch giữa chúng không đối xứng

#

Quy tắc này cần một danh sách user-agent của trình thu thập, mà Django thì đã có sẵn một danh sách như vậy. Cùng một kiến thức mà nằm hai bản ở hai hệ thống thường là dấu hiệu có vấn đề. Nhưng ở đây, điều thú vị là chuyện gì xảy ra khi hai bản lệch nhau, vì hậu quả không đối xứng:

• Danh sách bot trong Cloudflare phải luôn là tập con của danh sách trong Django. Nếu có token mà Cloudflare coi là bot còn Django thì không, phần khung SPA sẽ bị lưu đệm dưới khoá chỉ dành cho trình thu thập, rồi bị trả cho một trình thu thập thật.
• Danh sách loại trừ trình duyệt trong ứng dụng phải luôn là tập cha của danh sách trong Django. Loại trừ thừa thì cùng lắm bạn mất một lần trúng bộ nhớ đệm (cache hit).

Sai theo chiều an toàn, dù ở danh sách nào, thì bạn chỉ mất một ít dữ liệu đệm. Nhưng sai danh sách đầu theo chiều ngược lại là bạn quay về cảnh trả cho Googlebot một trang trống. Nhân tiện, cũng vì sự bất đối xứng đó mà hai danh sách dùng contains chứ không dùng biểu thức chính quy (regex): matches đòi gói Business, còn contains là đủ cho một danh sách được phép xấp xỉ, miễn là lệch về phía đã biết là an toàn.

Một bất biến làm hỏng bản dựng thay vì làm hỏng trang

#

Các trang dành cho trình thu thập nhúng URL ảnh dạng ký sẵn (presigned), có hiệu lực bảy ngày. Còn bản thân các trang thì được lưu đệm ở máy chủ biên một tiếng, cộng thêm một ngày stale-while-revalidate.

Hai con số này dính dáng tới nhau. Nếu có ngày thời gian lưu đệm vượt quá thời hạn của ảnh, máy chủ biên sẽ bắt đầu trả ra những trang mà ảnh nào cũng dính lỗi 403. Sẽ chẳng có cảnh báo nào kêu cả, vì HTML vẫn hoàn toàn bình thường.

Nên đoạn mã định nghĩa mấy con số đó sẽ từ chối nạp (import) nếu quan hệ này bị phá vỡ:

CRAWLER_IMAGE_TTL = 7 * 24 * 3600  # presigned image URLs
EDGE_S_MAXAGE = 3600
EDGE_STALE_WHILE_REVALIDATE = 24 * 3600

# Fail at import time if the edge cache could outlive the image URLs.
if EDGE_S_MAXAGE + EDGE_STALE_WHILE_REVALIDATE >= CRAWLER_IMAGE_TTL:
    raise RuntimeError("edge cache lifetime must stay below the image URL lifetime")

Một ràng buộc giữa hai hằng số nằm ở hai tệp khác nhau thì gần như vô hình khi rà soát mã, nhưng lộ ra ngay khi tiến trình khởi động. Vậy thì cứ đặt phép kiểm tra ở chỗ tiến trình khởi động.

Hai thứ Cloudflare làm mà tôi phải gỡ lại

#

Vary: Origin khiến gói JavaScript không vào được bộ nhớ đệm. django-cors-headers đóng dấu Vary: Origin lên mọi phản hồi mà nó đi qua, còn Cloudflare thì không lưu đệm bất cứ thứ gì vary theo nhiều hơn Accept-Encoding. Thế là gói JavaScript (bundle) 1.6 MB — thứ nặng nhất trên đường tải quan trọng (critical path) — lặng lẽ bị loại hẳn khỏi máy chủ biên. Cách sửa là một middleware đặt đầu tiên trong danh sách, để nó chạy sau cùng lúc phản hồi đi ra, và viết lại Vary cho các đường dẫn tài nguyên tĩnh.

Nén ở máy chủ biên còn tệ hơn nén ở máy chủ gốc. Để Cloudflare tự nén Brotli tức thời thì ra 2,041,742 byte, trong khi gzip của chính máy chủ gốc chỉ ra 1,658,115. To hơn hai mươi ba phần trăm, chỉ để đổi lấy cái sướng là không phải nghĩ ngợi gì. Nén tức thời tối ưu cho CPU chứ không tối ưu cho tỉ lệ nén; tài nguyên nén sẵn từ máy chủ gốc vẫn thắng.

Báo cho công cụ tìm kiếm mà không cần chờ được thu thập

#

Có hai giao thức, nhưng gộp cả hai lại thì phạm vi phủ vẫn ít đến đáng thất vọng.

IndexNow chỉ cần một cú ping là phủ được Bing, Yandex và Seznam. Google và Naver thì không tham gia. Mỗi khi một tin đăng được lưu, tôi gửi ping ở chế độ nền với thời gian chờ ngắn, và bỏ qua tin đăng đã bán hoặc đã đóng. Gặp lỗi mạng thì nó ghi một dòng cảnh báo vào nhật ký và không bao giờ làm hỏng lần lưu đã kích hoạt nó. Với một kênh phụ kiểu làm được đến đâu hay đến đó (best-effort), đó là cách hành xử duy nhất chấp nhận được.

Indexing API của Google chỉ nhận đúng hai loại schema, và một trong hai là JobPosting, thứ mà tôi lại có. Tin tuyển dụng còn mở thì gửi URL_UPDATED, tin đã đóng thì gửi URL_DELETED. Lệnh xoá đó chỉ trung thực vì tin đăng đã đóng cũng trả noindex, và mã nguồn có ghi chú rõ chuyện này, để lỡ ai gỡ noindex đi thì cũng biết mình còn làm hỏng thêm thứ gì.

Có hai chỗ làm tôi mất thời gian. Thứ nhất, hạn mức (quota) là 200 URL mỗi ngày, mà một lần nhập hàng loạt tin đăng sẽ gọi nó hàng trăm lần — nên tin đăng nhập vào phải được bỏ qua, không thì một lần nhập đốt sạch hạn mức của cả ngày. Thứ hai, endpoint là urlNotifications:publish, dùng dấu hai chấm. Dùng dấu gạch chéo là Google trả về một trang HTML 404 trơn, trông y hệt như API đang bị tắt.

Dữ liệu có cấu trúc dạy tôi những gì

#

Ba quy tắc về dữ liệu có cấu trúc (structured data), cái nào cũng học được sau khi bị Search Console phàn nàn:

1. Không phân tích được thì bỏ ra. Mức lương gửi đến dưới dạng văn bản tự do. Trước đây tôi nhét nguyên chuỗi đó vào baseSalary.value, vốn không hợp lệ, thế là tin tuyển dụng nào cũng bị gắn cờ thiếu đơn vị. Giờ lương nào không phân tích (parse) được thì đơn giản là không có.
2. Đừng bao giờ bịa ra một trường chỉ để chiều schema. Tin tuyển dụng hiếm khi ghi địa chỉ cụ thể đến tên đường. Rất dễ bị cám dỗ bịa ra một địa chỉ nghe hợp lý cho PostalAddress. Nhưng một địa chỉ bịa trên tin tuyển dụng còn tệ hơn một địa chỉ thiếu, nên tôi chỉ đưa vào khu vực (locality) và quốc gia.
3. Ngày hết hạn không phải là tuỳ chọn. Google bỏ qua JobPosting nào không có validThrough, nên tôi tự suy ra một giá trị, kèm mức sàn để một tin đăng cũ không tự nhận là đã hết hạn từ hôm qua.

Còn quy tắc thứ tư, về sơ đồ trang web (sitemap): đừng khai changefreq: daily cho mọi thứ. Bảo Googlebot thu thập lại một nghìn tin đăng mỗi ngày thì trong mắt nó, máy chủ của bạn đang quá tải, và nó sẽ đáp lại bằng cách giảm tốc độ thu thập cho cả trang web. Hãy suy ra giá trị này từ lần gần nhất nội dung thực sự thay đổi.

Sơ đồ trang web cũng có một mức sàn về chất lượng: tiêu đề và nội dung cộng lại phải đủ bốn mươi ký tự. Search Console từng báo khoảng một nghìn tin đăng ở trạng thái “Crawled – currently not indexed”, và có một trang đồ cũ mà toàn bộ nội dung riêng của nó chỉ gồm một tiêu đề đúng một chữ và một số điện thoại. Bốn mươi ký tự là tôi cố tình đặt thấp, vì 471 trên 484 tin đăng viết bằng tiếng Hàn, mà tiếng Hàn chứa được nhiều ý hơn trên mỗi ký tự; một ngưỡng canh theo tiếng Anh sẽ loại mất một nửa sàn mua bán. Tin đăng nào nội dung mỏng thì vẫn được thu thập qua các trang danh mục, và sẽ tự động quay lại sơ đồ trang web khi có người sửa chúng.

Tôi rút ra được gì

#

• Trả nhiều phần thân khác nhau ở cùng một URL trước hết là bài toán khoá lưu đệm, rồi mới đến chuyện khác. Hãy tìm hiểu xem CDN của bạn lấy khoá theo những gì, và cứ giả định nó bỏ qua Vary cho đến khi bạn chứng minh được điều ngược lại với đúng kiểu nội dung (content type) đó.
• Khi hai hệ thống phải thống nhất về một danh sách, hãy xác định chiều sai nào là an toàn, rồi ghi điều đó ngay cạnh cả hai bản. Nói thẳng “hai bản này có thể lệch nhau, và đây là cách duy nhất chúng được phép lệch” vẫn hơn là giả vờ chúng không bao giờ lệch.
• So khớp bot theo tên bot, đừng bao giờ theo tên công ty. Nhất là ở ngoài thế giới nói tiếng Anh, nơi chính công ty làm bot cũng làm luôn cái trình duyệt mà người dùng của bạn đang cầm trên tay.
• Bất biến giữa những hằng số nằm xa nhau thì hãy đặt ở chỗ nào hỏng thật to. Kiểm tra lúc nạp mô-đun chẳng tốn gì, và không ai lách qua được.

Hiện tại, với vai trò là một lập trình viên độc lập (solo developer), tôi đang vận hành đồng thời hai sản phẩm:

• một ứng dụng ước tính và báo giá tại hiện trường (field estimation) dành cho các kỹ thuật viên/thợ dịch vụ, giúp họ tính chi phí và báo giá công việc ngay tại chỗ;
• và một ứng dụng chợ mua bán kiêm cộng đồng (marketplace), với các tính năng như đăng tin và nhắn tin thời gian thực.

Hai sản phẩm khác nhau, nhóm người dùng cũng khác nhau, nhưng bộ công nghệ (tech stack) gần như giống hệt nhau — và cả hai đều đang chạy hoàn toàn trên các máy shared-cpu-1x, gói rẻ nhất mà Fly.io cung cấp.

Đây là một giới hạn được tôi chủ động lựa chọn.

Thay vì chọn cấu hình máy chủ theo mức tải đỉnh (peak load), tôi cố gắng khai thác tối đa hiệu năng của một máy nhỏ, đo chính xác ngưỡng mà hệ thống bắt đầu gặp điểm nghẽn (bottleneck) hoặc sụp đổ khi tải cao, rồi để bộ tự động co giãn (autoscaler) của Fly.io tự mở rộng hoặc thu hẹp theo chiều ngang (scale out / scale in), thêm hoặc bớt máy dựa trên chính ngưỡng đã đo đó.

Bài viết này sẽ đi vào các kỹ thuật tối ưu hóa giúp mô hình đó khả thi, các số liệu kiểm thử tải (load testing) dùng để xác định ngưỡng mở rộng (scaling threshold), và cách việc tăng, giảm số máy thực tế diễn ra trên Fly.io.

Triết lý: đo một máy, rồi nhân lên

#

Chiến lược mở rộng quy mô của cả hai ứng dụng đều gồm ba bước giống nhau:

1. Tối ưu một máy nhỏ cho nhanh nhất trong khả năng hợp lý.
2. Kiểm thử tải cho đến khi máy gãy, rồi ghi lại số yêu cầu đồng thời (concurrency) mà tại đó độ trễ (latency) bắt đầu vọt lên.
3. Cấu hình bộ tự động co giãn của Fly để bật máy thứ hai ngay trước điểm đó, và dừng các máy đang rảnh khi lưu lượng truy cập (traffic) giảm.

Khi đó, năng lực xử lý tăng gần như tuyến tính theo số máy, còn chi phí nền chỉ là một máy ảo (VM) nhỏ cho mỗi ứng dụng. Mọi thứ trong phần còn lại của bài đều phục vụ một trong ba bước này.

Tối ưu cho một máy nhỏ chạy nhanh

#

Granian: WSGI cho API, ASGI với uvloop cho WebSocket

#

Phía máy chủ (backend) của cả hai sản phẩm đều là Django 6 + Django REST Framework. API chạy trên Granian, một máy chủ viết bằng Rust, nhưng dùng WSGI với nhóm luồng chặn (blocking thread pool) chứ không phải ASGI:

granian --interface wsgi myapp.wsgi:application \
    --workers 1 --blocking-threads 16 \
    --workers-max-rss 1400 \
    --workers-kill-timeout 15 --respawn-failed-workers

Lúc đầu tôi dùng --interface asgi --loop uvloop, và đó là một quyết định sai. Mọi view HTTP trong hai ứng dụng này đều là đồng bộ (sync), mà trình xử lý ASGI của Django lại chạy view đồng bộ ở chế độ thread_sensitive, tức mỗi tiến trình worker chỉ xử lý được một view tại một thời điểm. Kết quả là với ASGI, mỗi worker chỉ xử lý được khoảng một yêu cầu đồng thời, lại còn phải nạp nguyên bộ asyncio/uvloop/Channels vào RAM mà chẳng được lợi gì. Còn WSGI với --blocking-threads thì chạy chính những view đồng bộ đó trong một nhóm luồng thực thụ: một worker × 16 luồng = 16 yêu cầu nặng về I/O chạy đồng thời (đọc cơ sở dữ liệu, tạo URL ký trước (presigned URL) cho S3), mà bộ nhớ thường trú lại còn thấp hơn bản bất đồng bộ.

Tại sao chỉ dùng một worker? Vì máy ảo là shared-cpu-1x, tức chỉ có một nhân. Thêm worker thứ hai cũng không chạy Python song song được trên một nhân (GIL cộng với chỉ một CPU), nhưng lại tốn thêm nguyên một tiến trình Django thường trú trong bộ nhớ; chính Granian cũng cảnh báo đúng chuyện này. Với các tác vụ nặng về I/O, mười sáu luồng trên một worker là mức trần thực tế của một máy 1 vCPU. Tham số --workers-max-rss 1400 sẽ khởi động lại worker nếu nó phình quá giới hạn bộ nhớ, nên nếu một tác vụ tạo PDF hay xử lý ảnh chạy mất kiểm soát thì worker sẽ được thay mới, thay vì kéo cả máy đến chỗ cạn bộ nhớ (OOM).

WebSocket được tách ra chạy trong một tiến trình Granian riêng: một ứng dụng ASGI dùng uvloop và --ws, với một worker chuyên giữ các kết nối dài hạn. Phần API đồng bộ hoàn toàn không cần tới ASGI: khi một view cần đẩy dữ liệu xuống socket, nó gọi async_to_sync(channel_layer.group_send) qua Redis, và thông điệp vẫn đến được tiến trình WebSocket. Hai máy chủ, mỗi cái chạy đúng giao diện (interface) mà nó làm tốt nhất. Docker trên máy cục bộ cũng chạy cùng nhóm luồng WSGI đó, nên khi kiểm thử, laptop của tôi mô phỏng khá sát một máy trong môi trường production.

Dùng Rust ở các đường xử lý nóng

#

Ở đường xử lý nóng (hot path) nào của Python mà có sẵn một thư viện viết bằng Rust thay thế được ngay, tôi đều dùng:

• orjson qua drf-orjson-renderer: mọi phản hồi của API đều được tuần tự hóa bằng Rust thay vì bộ mã hóa JSON của thư viện chuẩn.
• blurhash-rs: tạo ảnh giữ chỗ (placeholder) ngay lúc ảnh được tải lên.
• uuid-utils: sinh UUID bằng Rust.
• psycopg 3 (binary): trình điều khiển (driver) Postgres được tăng tốc bằng C.

Không thư viện nào trong số này làm thay đổi kiến trúc; chúng chỉ nâng mức trần của một vCPU lên, để bạn chưa phải thêm máy thứ hai sớm.

Loại bỏ những độ trễ ẩn

#

Cải thiện lớn nhất trong mã nguồn của cả hai ứng dụng không đến từ thuật toán nào cả, mà từ việc tái sử dụng kết nối. Trong nhóm luồng của Granian, mỗi luồng mới lại tạo một đối tượng client S3 của boto3 mới toanh, và endpoint nào trả về ảnh hay PDF cũng phải gánh chi phí đó. Tôi viết một lớp lưu trữ (storage) nhỏ tùy chỉnh để lưu đệm (cache) client theo từng tiến trình:

Thời gian tạo URL có chữ ký trên các luồng mới giảm từ ~150ms xuống ~1ms.

Với cơ sở dữ liệu cũng vậy: Postgres trên Fly nằm sau PgBouncer, nên ứng dụng chạy với conn_max_age=0 và để bộ gộp kết nối (pooler) lo phần tái sử dụng kết nối, kèm connect_timeout 5 giây để khi gặp kết nối SSL đã chết thì báo lỗi ngay, chứ không làm treo cả worker.

Đặt bộ nhớ đệm đúng chỗ đang thực sự nghẽn

#

Đợt kiểm thử tải phía chợ mua bán cho tôi một bài học đáng nhớ: mức trần nằm ở số kết nối Postgres, không phải CPU. Phần lớn lưu lượng duyệt tin đến từ người dùng ẩn danh, và nội dung họ xem giống hệt nhau. Khi tải lên cao, những truy vấn danh sách giống hệt nhau đó làm đầy nhóm kết nối, trong khi CPU vẫn ngồi chơi.

Cách sửa là thêm một lớp bộ nhớ đệm Redis cho các trang danh sách mà người dùng ẩn danh xem, và vô hiệu hóa bộ nhớ đệm bằng bộ đếm phiên bản theo từng không gian tên (namespace): mỗi thao tác ghi chỉ cần tăng một bộ đếm (O(1), không phải theo dõi từng khóa), thế là mọi trang đã lưu đệm của tài nguyên đó lập tức hết hiệu lực. Một thời gian sống (TTL) ngắn làm lưới an toàn cho những trường hợp bị sót. Trả trang duyệt tin thẳng từ Redis gỡ được đúng điểm nghẽn thật, và để cái máy nhỏ dành kết nối cơ sở dữ liệu cho người dùng đã đăng nhập.

Chạy tác vụ nền mà không cần trình trung gian

#

Cả hai ứng dụng đều dùng django-tasks-db, framework tác vụ của Django lưu hàng đợi trong cơ sở dữ liệu, thay cho Celery. Một tiến trình db_worker riêng liên tục thăm dò cơ sở dữ liệu để lấy việc: xử lý ảnh, tạo PDF, dịch máy, gửi nhắc nhở. Không cần trình trung gian thông điệp (broker), không phải dựng và giám sát thêm dịch vụ nào, và tiến trình API không bao giờ bị những việc nặng chặn lại. Worker còn kết nối thẳng tới Postgres, bỏ qua PgBouncer, vì các tác vụ chạy lâu không hợp với chế độ gộp kết nối theo giao dịch (transaction pooling).

Bộ nhớ: jemalloc và bộ nhớ hoán đổi để dự phòng

#

Xử lý ảnh và PDF làm bộ nhớ tăng vọt theo những cách mà khi tính toán cấu hình cho trạng thái ổn định bạn không lường trước được. Tôi dùng hai cách giảm thiểu rẻ tiền: nạp sẵn jemalloc trong Docker image để giảm phân mảnh bộ nhớ, và bật bộ nhớ hoán đổi (swap) trên mọi máy (2GB trên máy API, 1GB trên máy WebSocket), để khi bộ nhớ tăng vọt thì dữ liệu được đẩy xuống đĩa chứ tiến trình không bị hệ thống buộc dừng vì cạn bộ nhớ. Bộ nhớ hoán đổi không phải tính năng giúp tăng hiệu năng; nó là một khoản bảo hiểm, cho phép tôi giữ mức cấp phát bộ nhớ ở mức nhỏ.

Kiểm thử tải Django: tìm điểm gãy

#

Một ngưỡng chỉ đáng tin khi nó đã được đo thực tế. Mỗi dự án có bộ công cụ kiểm thử riêng:

• Ứng dụng báo giá tại hiện trường có một script kiểm thử sức chịu tải nhỏ viết bằng Python, chạy lần lượt qua các mức yêu cầu đồng thời và báo cáo số yêu cầu mỗi giây (RPS), p50/p95/p99 cùng tỉ lệ lỗi. Script chạy trên vài trăm bản ghi mẫu được sinh sẵn, để các endpoint danh sách được truy vấn trên khối lượng dữ liệu sát thực tế.
• Chợ mua bán dùng Locust với kiểu tải bậc thang, tăng từ 50 → 500 người dùng theo từng bậc 30 giây để tìm điểm bão hòa, với trọng số các endpoint khớp với lưu lượng thực tế (phần lớn là duyệt tin). Ngoài ra còn một bộ kiểm thử nhỏ hơn, tăng từ 5 → 50 người dùng ảo, chạy thẳng vào môi trường production với ngưỡng p95 < 2s.

Vài con số tiêu biểu từ lượt đo của ứng dụng báo giá tại hiện trường (một worker Granian × 16 luồng chặn, chạy Docker trên máy phát triển của tôi):

Còn con số quyết định mọi thứ khác đến từ đợt kiểm thử tải chợ mua bán trên một máy shared-cpu-1x duy nhất. Với bản ASGI cũ, đây là một bức tường cứng: các view đồng bộ bị xếp hàng tuần tự, chỉ còn khoảng ba suất xử lý (slot) dùng được, nên p95 giữ dưới 300ms cho đến khoảng 5 yêu cầu đồng thời, rồi sụp hẳn khi vượt ~8–10, vì mọi yêu cầu đều phải xếp hàng sau cái khóa thread-sensitive. Chính việc chuyển API sang nhóm luồng WSGI đã đẩy điểm gãy đó ra xa: 16 suất đồng thời thực sự trên mỗi máy thay vì ~3, và mức trần mới này là nền tảng cho toàn bộ cấu hình tự động co giãn.

Cơ chế co giãn trên Fly.io

#

Mô hình của Fly khá đơn giản: ứng dụng của bạn là một nhóm máy giống hệt nhau đứng sau một proxy, và proxy đếm tải trên từng máy. Bạn chỉ cần khai báo hai con số:

[http_service.concurrency]
  type = 'requests'
  soft_limit = 12   # past this, start another machine
  hard_limit = 24   # past this, shed load instead of queueing

auto_stop_machines = 'stop'
auto_start_machines = true
min_machines_running = 1

Khi tải tăng: khi số yêu cầu đang xử lý trên một máy vượt giới hạn mềm (soft limit), proxy sẽ bật một máy đang dừng và chuyển lưu lượng mới sang đó. Nhóm luồng WSGI cho mỗi máy 16 suất đồng thời thực sự, nên tôi đặt giới hạn mềm ở 12, tức khoảng 75% nhóm luồng, để máy số 2 khởi động khi các luồng vẫn còn dư sức, thay vì đợi đến lúc người dùng phải chờ tới vài giây. Giới hạn cứng (hard limit) đặt ở 24, gấp 1.5 lần nhóm luồng, đóng vai trò cầu dao: những đợt tăng vọt ngắn thì xếp hàng chờ luồng, còn vượt quá mức đó thì proxy sẽ từ chối bớt tải, thay vì để một máy bị quá tải tới mức sập. (Bản ASGI cũ chạy 8/20, tính theo ~3 suất thực của nó; chính việc nới rộng nhóm luồng mới cho phép nâng cả hai con số lên.)

Khi tải giảm: khi lưu lượng giảm, Fly tự động dừng các máy đang rảnh, xuống tới min_machines_running = 1. Máy đã dừng không tốn đồng tiền tính toán nào, chỉ tốn phần lưu trữ rootfs, nên chi phí nền của mỗi ứng dụng đúng nghĩa đen là một máy ảo nhỏ, mà lúc nào cũng có sẵn năng lực dự phòng cho những đợt tăng tải.

Ban đầu, ở đoạn này tôi có viết rằng một máy đã dừng “khởi động nguội (cold start) mất chưa tới một giây”. Câu đó sai, và cái sai ấy khá đắt. Đến khi chịu đo thực tế thay vì đoán, tôi mới thấy một lần khởi động nguội mất 25 đến 33 giây, và yêu cầu nào rơi vào một máy còn đang khởi động thì phải chờ trọn khoảng thời gian đó. Lúc đầu tôi đổ cho chính những lần khởi động nguội này tỉ lệ lỗi 22% trên bảng điều khiển của CDN, trong khi mọi lần kiểm tra tình trạng (health check) vẫn báo xanh. Hóa ra con số đó là các yêu cầu thăm dò Early Hints của chính CDN bị lỗi ở máy chủ gốc (origin); không có client thật nào nhận lỗi 504 cả. Dù vậy, chuyện khởi động nguội thì vẫn là thật.

Cách sửa không nằm ở mấy con số co giãn phía trên; chúng vẫn ổn. Vấn đề nằm ở những gì máy làm trong lúc khởi động, và ở việc yêu cầu Fly tạm ngưng (suspend) máy thay vì dừng hẳn (stop), để mỗi lần đánh thức máy chỉ còn là một lần khôi phục bộ nhớ mất khoảng 3 giây. Tôi đã viết riêng một bài về chuyện này: Thu về 0, và mỗi lần khởi động lại là một lần sập 30 giây, nói về cách tôi chẩn đoán và những gì cần thay đổi. Nếu bạn đang chạy bất cứ thứ gì trên Fly với auto_stop_machines, hãy đọc bài đó trước khi tin vào đoạn này.

Có một điểm tinh tế: kiểu đếm tải là requests, không phải connections. Máy khách hiện đại giữ kết nối duy trì (keep-alive) luôn mở, nên nếu đếm theo kết nối thì con số gần như đứng yên dù tải thực tế tăng, và bộ tự động co giãn sẽ không bao giờ được kích hoạt. Đếm số yêu cầu đang xử lý mới phản ánh đúng khối lượng công việc thực.

WebSocket co giãn theo một trục khác

#

Chợ mua bán tách máy chủ WebSocket ra thành một ứng dụng Fly thứ hai, dùng chung Docker image. Ứng dụng API chạy một worker × 16 luồng chặn dưới WSGI và đếm theo yêu cầu (giới hạn mềm 12). Ứng dụng WebSocket thì chạy 1 worker dưới ASGI với uvloop, trên một máy 512MB, và đếm theo kết nối:

[http_service.concurrency]
  type = 'connections'
  soft_limit = 1500
  hard_limit = 2000

Giữ một socket sống lâu gần như không tốn gì, nhưng nó chiếm một suất hàng giờ liền, trong khi một yêu cầu HTTP chỉ chiếm suất vài mili giây, nên không thể dùng chung một tín hiệu co giãn cho cả hai. Tách riêng ra thì mỗi nhóm máy co giãn theo đúng thước đo phản ánh tải thật của nó, và năng lực WebSocket lúc rảnh chỉ tốn 512MB chứ không phải 2GB. Về phía Channels, lớp Redis chạy với capacity: 1500, thông điệp hết hạn sau 60 giây, cộng thêm cơ chế duy trì kết nối cho socket mỗi 30 giây, vì proxy Redis của Fly sẽ tự đóng các socket BRPOP sống lâu mà Channels cần tới khi chúng không hoạt động.

Đẩy việc tính toán ra tầng biên và sang phía máy khách

#

Việc rẻ nhất cho máy chủ là việc máy chủ không bao giờ phải làm:

• Tệp tĩnh và tệp đa phương tiện (media) nằm trên dịch vụ lưu trữ đối tượng tương thích S3 của Fly, được phân phối qua CDN, với URL có chữ ký cho tệp đa phương tiện riêng tư. Không một byte ảnh nào phải đi qua các máy Django.
• Suy luận AI chạy trên điện thoại của người dùng. Cả hai ứng dụng đều nhúng một LLM nhỏ chạy cục bộ ngay trên thiết bị (mô hình 4B đã lượng tử hóa, khoảng 2.7GB). Phía máy chủ không tốn đồng nào cho suy luận, và tính năng này chạy được cả khi ngoại tuyến.
• Ứng dụng di động ưu tiên ngoại tuyến (offline-first) (SQLite trên thiết bị và một hàng đợi đồng bộ có cơ chế thử lại) giúp ứng dụng gom các thao tác ghi lại thành từng đợt và chịu được những vùng mất sóng, thay vì dội vào API hàng loạt yêu cầu lắt nhắt theo từng lần gõ phím.

Phần còn lại của bộ công nghệ, điểm nhanh

#

Xác thực dùng một dịch vụ định danh (identity provider) có sẵn cộng với khóa truy cập (passkey) WebAuthn, và kết nối WebSocket được xác thực trước khi nâng cấp giao thức. Postgres cho môi trường production, SQLite khi phát triển, cùng vài gói Django có sẵn cho trang quản trị và lịch sử kiểm toán (audit trail). Phía di động là React Native và TypeScript chạy trên Expo, với Expo Router và Tailwind, cập nhật OTA qua một máy chủ Expo Updates tự vận hành, còn gói thuê bao trong ứng dụng thì giao cho một dịch vụ quản lý thuê bao. Khâu kiểm soát chất lượng: pytest và mypy ở phía máy chủ, kiểm thử đơn vị và kiểm thử đầu-cuối (end-to-end) ở phía máy khách.

Những gì bạn nên “học lỏm”

#

Điều đáng mang về không nằm ở một thư viện cụ thể nào, mà ở cả vòng lặp. Tối ưu cho một máy rẻ tiền chạy thật nhanh (dùng Rust ở đường xử lý nóng, tái sử dụng kết nối, đặt bộ nhớ đệm chắn trước điểm nghẽn thật, đẩy được gì sang CDN và máy khách thì đẩy). Kiểm thử tải cho đến khi tìm ra chính xác mức yêu cầu đồng thời mà máy gãy. Đặt giới hạn mềm của bộ tự động co giãn ngay tại điểm gãy đó, để các máy rảnh tự dừng, và giữ tối thiểu một máy luôn chạy. Hai ứng dụng đang chạy production, có tính năng thời gian thực, có trợ lý AI, mà hóa đơn hằng tháng lúc bình thường chỉ là vài máy ảo rẻ nhất trên nền tảng.

Ứng dụng lập báo giá tôi đang làm có một yêu cầu không thể thương lượng: mất sóng vẫn phải chạy được. Báo giá được lập ngay trong lúc đi khảo sát tận nơi, mà khảo sát thì toàn ở nhà mới xây hoặc dưới tầng hầm, chỗ sóng điện thoại chỉ có trong lời đồn. Chính ràng buộc này buộc tôi phải trả lời nghiêm túc một câu hỏi mà phần lớn dự án React thường cho qua loa: loại trạng thái (state) nào thì nên để ở đâu?

Sai lầm hay gặp nhất là dồn mọi thứ vào một store. Dữ liệu API lưu đệm, tuỳ chọn của người dùng, trạng thái biểu mẫu, token xác thực, tất cả nhét chung vào một cục Redux. Nhưng đây là những loại trạng thái khác nhau, có vòng đời khác nhau, và mỗi loại hợp với một công cụ riêng. Zustand, React Query và AsyncStorage, mỗi cái giải quyết tốt đúng một trong các bài toán đó. Chỉ cần vạch rõ ranh giới giữa chúng là kiến trúc phần lớn sẽ tự vào khuôn.

Ba loại trạng thái

#

Trước khi tranh luận nên dùng thư viện nào, hãy gọi cho đúng tên thứ mình đang quản lý đã.

Trạng thái phía máy khách (client state) chỉ tồn tại khi ứng dụng đang chạy: các nút bật/tắt trên giao diện, tab đang chọn, dữ liệu người dùng nhập vào biểu mẫu, hộp thoại (modal) đang mở hay đóng. Không có ai ở phía máy chủ sở hữu nó, và tiến trình (process) kết thúc thì nó cũng mất theo.

Trạng thái phía máy chủ (server state) thì khác. Máy chủ mới là chủ sở hữu, ứng dụng của bạn chỉ giữ một bản sao trên thiết bị. Ví dụ như hồ sơ người dùng, danh sách sản phẩm, thông báo, dữ liệu bảng tin (feed). Bản sao của bạn sẽ dần cũ đi, cần được tải lại, và ngay lúc này rất có thể một máy khách khác đang thấy một phiên bản khác của cùng dữ liệu đó.

Trạng thái lưu bền (persistent state) là những gì phải còn nguyên sau khi khởi động lại ứng dụng: token xác thực, cờ đánh dấu người dùng đã xong phần làm quen ban đầu (onboarding), các tuỳ chọn đã lưu, dữ liệu dùng khi ngoại tuyến (offline). Loại trạng thái này nằm ngay trên thiết bị.

Ứng dụng nào cũng có đủ cả ba loại. Và phần lớn mớ bòng bong đều bắt nguồn từ việc dùng một công cụ để xử lý cả ba.

Zustand: trạng thái phía máy khách

#

Zustand là một thư viện quản lý trạng thái nhỏ gọn cho React, không có mấy thủ tục rườm rà. Không cần provider, không có mã rập khuôn (boilerplate), không phải bọc năm lớp context chồng lên nhau. Bạn tạo một store, dùng nó trong component, vậy là xong bài học.

Nó là lựa chọn đúng khi nhiều component cần dùng chung một trạng thái giao diện (thanh bên đang mở hay đóng, bộ lọc đang bật, các mục đang chọn), khi trạng thái ở cấp ứng dụng không đến từ API (chế độ sáng/tối, ngôn ngữ, các cờ tính năng đọc lúc khởi động), hoặc khi có logic phía máy khách thật sự cần quản lý, như tính tiền giỏ hàng hay một trình hướng dẫn nhiều bước (wizard). Nói chung là những thứ cần cập nhật đồng bộ và dễ đoán.

Một store cơ bản trông như thế này:

import { create } from 'zustand'

interface AppState {
  theme: 'light' | 'dark'
  sidebarOpen: boolean
  selectedFilters: string[]
  setTheme: (theme: 'light' | 'dark') => void
  toggleSidebar: () => void
  setFilters: (filters: string[]) => void
}

const useAppStore = create<AppState>((set) => ({
  theme: 'light',
  sidebarOpen: false,
  selectedFilters: [],
  setTheme: (theme) => set({ theme }),
  toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
  setFilters: (filters) => set({ selectedFilters: filters }),
}))

Còn đây là cách dùng trong component:

function Sidebar() {
  const { sidebarOpen, toggleSidebar } = useAppStore()

  if (!sidebarOpen) return null

  return (
    <div className="sidebar">
      <button onClick={toggleSidebar}>Close</button>
      {/* sidebar content */}
    </div>
  )
}

Những thứ tôi không bỏ vào Zustand

#

Chủ yếu là dữ liệu phản hồi từ API. Tôi từng gặp nhiều dự án mà lời gọi API nào cũng ghi kết quả vào một store Zustand, còn component thì đọc từ store thay vì dùng truy vấn (query). Rốt cuộc bạn phải tự tay viết lại toàn bộ phần vô hiệu hóa bộ nhớ đệm (cache invalidation), trạng thái đang tải, xử lý lỗi, tải lại và phân trang, trong khi đó lại đúng là những việc React Query sinh ra để làm thay bạn.

Thứ hai là bất cứ thứ gì phải còn lại sau khi khởi động lại. Trạng thái của Zustand nằm trong bộ nhớ, đóng ứng dụng là mất. Middleware persist có thể nối Zustand với AsyncStorage (phần sau sẽ nói kỹ hơn), nhưng dùng nó phải là một quyết định có cân nhắc, đừng để thành thói quen.

React Query: trạng thái phía máy chủ

#

React Query (giờ đã đổi tên thành TanStack Query) quản lý toàn bộ vòng đời của dữ liệu từ xa: tải về (fetch), lưu đệm, đồng bộ, cập nhật và dọn rác. Điểm cần đổi tư duy là nó xem dữ liệu từ máy chủ như một bộ nhớ đệm cần giữ cho mới, chứ không phải trạng thái của riêng bạn. Máy chủ mới là chủ. Bạn chỉ đang cầm một bản sao.

Tôi dùng nó cho mọi thứ lấy từ API. Chẳng hạn dữ liệu mà nhiều component cùng cần từ một endpoint (các yêu cầu trùng nhau được tự động gộp lại), danh sách phân trang hoặc cuộn vô hạn, dữ liệu cần tải lại ngầm khi người dùng quay lại ứng dụng, và cập nhật lạc quan (optimistic update), tức là giao diện đổi ngay lập tức rồi khôi phục lại nếu máy chủ từ chối.

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'

function useUser(userId: string) {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: () => fetch(`/api/users/${userId}`).then(res => res.json()),
    staleTime: 5 * 60 * 1000, // Consider fresh for 5 minutes
  })
}

function useUpdateUser() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: (data: { id: string; name: string }) =>
      fetch(`/api/users/${data.id}`, {
        method: 'PATCH',
        body: JSON.stringify(data),
      }),
    onSuccess: (_, variables) => {
      queryClient.invalidateQueries({ queryKey: ['user', variables.id] })
    },
  })
}

Dùng trong component:

function UserProfile({ userId }: { userId: string }) {
  const { data: user, isLoading, error } = useUser(userId)
  const updateUser = useUpdateUser()

  if (isLoading) return <Spinner />
  if (error) return <ErrorMessage error={error} />

  return (
    <div>
      <h1>{user.name}</h1>
      <button
        onClick={() => updateUser.mutate({ id: userId, name: 'New Name' })}
        disabled={updateUser.isPending}
      >
        Update Name
      </button>
    </div>
  )
}

Những thứ có sẵn mà bạn không phải tự viết

#

Tôi kiên quyết để dữ liệu từ máy chủ ở đây vì số cơ chế được tặng kèm miễn phí nhiều đến choáng ngợp. Năm component cùng lấy một người dùng thì chỉ tạo ra đúng một yêu cầu mạng. Dữ liệu tự tải lại khi cửa sổ được chọn lại (focus) hoặc khi có mạng lại. Bộ nhớ đệm cũ tự được dọn. Truy vấn nào cũng trả sẵn isLoading, isError, data cùng các trường liên quan, nên giao diện cho trạng thái đang tải và lỗi không còn phải làm thủ công từng chỗ. Yêu cầu thất bại được tự động thử lại với thời gian chờ tăng theo cấp số nhân (exponential backoff). Còn cập nhật lạc quan kèm khôi phục khi lỗi là cơ chế có sẵn, chứ không phải mất nguyên buổi chiều tự đi dây.

Những việc không nên dùng React Query

#

Trạng thái thuần tuý phía máy khách. Nếu dữ liệu không bao giờ đi qua máy chủ thì React Query chỉ thêm rườm rà. Trạng thái mở/đóng của một hộp thoại đâu cần vô hiệu hóa bộ nhớ đệm hay tải lại định kỳ.

React Query cũng không phải tầng lưu trữ lâu dài. Bộ nhớ đệm chỉ nằm trong RAM, nên mỗi lần khởi động lại là trống trơn và phải tải lại một loạt. Bạn có thể lưu bộ nhớ đệm xuống thiết bị (trên React Native thì nên làm, xem phần ngoại tuyến bên dưới), nhưng nguồn dữ liệu gốc (source of truth) lúc nào cũng là máy chủ.

AsyncStorage: những gì cần giữ lại sau khi khởi động lại

#

AsyncStorage là kho lưu trữ dạng khóa-giá trị (key-value) của React Native. Trên web, thứ tương đương là localStorage (đồng bộ) hoặc IndexedDB (bất đồng bộ, làm được nhiều việc hơn). Dù dùng cái nào thì ý tưởng cũng như nhau: dữ liệu được ghi xuống thiết bị nên vẫn còn sau khi tiến trình kết thúc.

Bên dưới mỗi nền tảng thực chất là gì

#

Cùng một API, nhưng bên dưới là ba cơ chế lưu trữ khá khác nhau (giả sử bạn dùng @react-native-async-storage/async-storage).

Trên Android, bên dưới là SQLite, thông qua RKStorage, lưu trong một cơ sở dữ liệu nằm ở thư mục lưu trữ nội bộ của ứng dụng. Nhanh, ổn định, lại được cô lập trong môi trường riêng (sandbox) nên ứng dụng khác không đụng vào được. Lưu ý giới hạn dung lượng mặc định trong bảng bên dưới.

Trên iOS, giá trị nhỏ được lưu bằng NSUserDefaults, còn giá trị lớn hơn thì được tuần tự hóa (serialise) rồi ghi ra tệp, cũng nằm trong sandbox của ứng dụng. Apple không đặt giới hạn cứng cho NSUserDefaults, nhưng thông lệ hợp lý là giữ mỗi giá trị dưới vài trăm KB. Nếu dữ liệu của bạn lớn hơn thế thì có lẽ bạn nên dùng hẳn một cơ sở dữ liệu đàng hoàng như WatermelonDB hay Realm.

Trên web (React Native Web hoặc Expo Web), AsyncStorage chuyển sang dùng localStorage, dung lượng tối đa khoảng 5-10 MB tuỳ trình duyệt. Ứng dụng React chỉ chạy trên web thì có thể dùng thẳng localStorage, hoặc dùng IndexedDB qua một thư viện bọc (wrapper) như idb-keyval nếu dữ liệu lớn hơn.

Tôi lưu gì trong đó

#

Token xác thực và dữ liệu phiên đăng nhập, các tuỳ chọn cần giữ lại (ngôn ngữ, chế độ sáng/tối, cài đặt thông báo), cờ đã xong phần làm quen ban đầu, dữ liệu lưu đệm để dùng khi ngoại tuyến. Tóm lại là những mẩu dữ liệu khóa-giá trị nho nhỏ cần giữ lại sau khi khởi động lại, chỉ vậy thôi.

API của nó đơn giản hết mức mà một kho lưu trữ có thể có:

import AsyncStorage from '@react-native-async-storage/async-storage'

// Store a value
await AsyncStorage.setItem('auth_token', token)

// Read a value
const token = await AsyncStorage.getItem('auth_token')

// Store an object (must serialize)
await AsyncStorage.setItem('user_preferences', JSON.stringify({
  theme: 'dark',
  language: 'en',
  notifications: true,
}))

// Read an object
const prefs = JSON.parse(await AsyncStorage.getItem('user_preferences') ?? '{}')

// Remove a value
await AsyncStorage.removeItem('auth_token')

// Clear everything (careful with this)
await AsyncStorage.clear()

Phiên bản cho web

#

Ứng dụng React chỉ chạy trên web thì không cần đến AsyncStorage. Các trường hợp đơn giản dùng localStorage là đủ:

// Synchronous  - blocks the main thread, but fine for small data
localStorage.setItem('theme', 'dark')
const theme = localStorage.getItem('theme')

// For structured data
localStorage.setItem('user', JSON.stringify({ name: 'Jared', role: 'admin' }))
const user = JSON.parse(localStorage.getItem('user') ?? '{}')

Còn dữ liệu lớn hơn thì dùng IndexedDB:

import { get, set, del } from 'idb-keyval'

await set('large-dataset', hugeArray)
const data = await get('large-dataset')
await del('large-dataset')

Những việc không nên dùng AsyncStorage

#

AsyncStorage là kho khóa-giá trị, không phải cơ sở dữ liệu. Dữ liệu quan hệ, mảng hàng nghìn phần tử, bất cứ thứ gì cần đánh chỉ mục hay truy vấn thì hãy để cho SQLite (qua expo-sqlite), WatermelonDB hoặc Realm.

Nó cũng không phải kho lưu trữ bảo mật. Trên thiết bị đã root hoặc jailbreak, ai cũng đọc được nội dung AsyncStorage. Token nhạy cảm phải để trong expo-secure-store hoặc react-native-keychain.

Kết hợp cả ba với nhau

#

Ứng dụng thực tế thường dùng cả ba cùng lúc. Dưới đây là vài mẫu (pattern) tôi dùng thường xuyên.

Luồng đăng nhập

#

// 1. AsyncStorage: persist the auth token
import AsyncStorage from '@react-native-async-storage/async-storage'

async function saveToken(token: string) {
  await AsyncStorage.setItem('auth_token', token)
}

async function getToken(): Promise<string | null> {
  return AsyncStorage.getItem('auth_token')
}

// 2. Zustand: track auth state in memory
import { create } from 'zustand'

interface AuthState {
  isAuthenticated: boolean
  token: string | null
  setAuth: (token: string) => void
  clearAuth: () => void
}

const useAuthStore = create<AuthState>((set) => ({
  isAuthenticated: false,
  token: null,
  setAuth: (token) => set({ isAuthenticated: true, token }),
  clearAuth: () => set({ isAuthenticated: false, token: null }),
}))

// 3. React Query: fetch user profile using the token
function useCurrentUser() {
  const token = useAuthStore((s) => s.token)

  return useQuery({
    queryKey: ['currentUser'],
    queryFn: () =>
      fetch('/api/me', {
        headers: { Authorization: `Bearer ${token}` },
      }).then(res => res.json()),
    enabled: !!token, // Only fetch when we have a token
  })
}

Còn lúc ứng dụng khởi động:

// App initialization
async function initializeApp() {
  const token = await getToken() // Read from AsyncStorage
  if (token) {
    useAuthStore.getState().setAuth(token) // Put in Zustand for quick access
    // React Query will automatically fetch the user profile
  }
}

AsyncStorage giữ token qua các lần khởi động lại, Zustand giúp đọc token ở bất cứ đâu mà không tốn kém, còn React Query tải hồ sơ người dùng ngay khi có token. Mỗi công cụ chỉ làm đúng một việc mà nó giỏi nhất.

Chế độ sáng/tối vẫn giữ nguyên sau khi khởi động lại

#

import { create } from 'zustand'
import { persist, createJSONStorage } from 'zustand/middleware'
import AsyncStorage from '@react-native-async-storage/async-storage'

// Zustand with persistence middleware bridges the gap
const useThemeStore = create(
  persist(
    (set) => ({
      theme: 'light' as 'light' | 'dark',
      toggleTheme: () =>
        set((state) => ({
          theme: state.theme === 'light' ? 'dark' : 'light',
        })),
    }),
    {
      name: 'theme-storage',
      storage: createJSONStorage(() => AsyncStorage), // React Native
      // storage: createJSONStorage(() => localStorage), // Web
    }
  )
)

Zustand quản lý trạng thái trong lúc ứng dụng chạy, còn middleware persist âm thầm đồng bộ trạng thái đó xuống AsyncStorage (hoặc localStorage trên web). Component của bạn không biết, mà cũng chẳng cần biết, là có một tầng lưu trữ nằm bên dưới.

Đọc dữ liệu theo hướng ưu tiên ngoại tuyến

#

import { useQuery } from '@tanstack/react-query'
import AsyncStorage from '@react-native-async-storage/async-storage'

function useProducts() {
  return useQuery({
    queryKey: ['products'],
    queryFn: async () => {
      try {
        const res = await fetch('/api/products')
        const data = await res.json()

        // Cache in AsyncStorage for offline use
        await AsyncStorage.setItem('cached_products', JSON.stringify(data))

        return data
      } catch (error) {
        // Network failed  - try cached data
        const cached = await AsyncStorage.getItem('cached_products')
        if (cached) return JSON.parse(cached)
        throw error
      }
    },
    staleTime: 10 * 60 * 1000,
  })
}

React Query lo việc tải và lưu đệm trong bộ nhớ, còn AsyncStorage là phương án dự phòng khi mất mạng.

Làm chế độ ngoại tuyến, từng bước một

#

Đây mới là phần tôi thật sự quan tâm. Người ta hay nói người dùng mở ứng dụng trên tàu điện ngầm, trong thang máy, trên máy bay, và đúng là vậy. Nhưng trường hợp của tôi thì yêu cầu thẳng thừng hơn nhiều: báo giá được lập ngay tại công trình, và tôi không thể mặc định là công trình có sóng. Một biểu tượng đang tải cứ quay mãi dưới tầng hầm đồng nghĩa với mất một đơn báo giá.

Điều bất ngờ dễ chịu là chỉ với ba thư viện này, bạn đã dựng được một hệ thống chạy ngoại tuyến thật sự vững vàng mà không cần đến framework cồng kềnh nào.

Bước 1: biết lúc nào đang mất mạng

#

Thiết bị cần báo cho ứng dụng biết tình trạng mạng, và ứng dụng cần một chỗ để lưu thông tin đó. @react-native-community/netinfo cung cấp các sự kiện, còn một store Zustand bé xíu giúp đọc được trạng thái đó từ bất cứ đâu.

import { create } from 'zustand'
import NetInfo from '@react-native-community/netinfo'

interface NetworkState {
  isOnline: boolean
  setOnline: (online: boolean) => void
}

const useNetworkStore = create<NetworkState>((set) => ({
  isOnline: true,
  setOnline: (online) => set({ isOnline: online }),
}))

// Subscribe once at app startup
NetInfo.addEventListener((state) => {
  useNetworkStore.getState().setOnline(state.isConnected ?? false)
})

Từ giờ, component nào cũng có thể gọi useNetworkStore((s) => s.isOnline) để hiện dải thông báo mất mạng, vô hiệu hoá nút gửi, hoặc báo cho người dùng biết thay đổi sẽ được đồng bộ sau.

Bước 2: cấu hình React Query cho chế độ ngoại tuyến

#

React Query có sẵn cơ chế xử lý ngoại tuyến thông qua networkMode, quyết định truy vấn và thao tác ghi (mutation) sẽ làm gì khi mất mạng.

import { QueryClient } from '@tanstack/react-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      networkMode: 'offlineFirst',
      // Return cached data immediately, then refetch in background when online
      staleTime: 5 * 60 * 1000,
      gcTime: 24 * 60 * 60 * 1000, // Keep cache for 24 hours
      retry: (failureCount, error) => {
        // Don't retry if we're offline  - it'll just fail again
        if (!useNetworkStore.getState().isOnline) return false
        return failureCount < 3
      },
    },
    mutations: {
      networkMode: 'offlineFirst',
    },
  },
})

Có ba chế độ:

Với phần lớn ứng dụng di động, offlineFirst là lựa chọn phù hợp: dữ liệu lưu đệm hiện ra ngay, còn dữ liệu mới sẽ về khi có mạng.

Bước 3: lưu bộ nhớ đệm truy vấn xuống thiết bị

#

Mặc định, bộ nhớ đệm chỉ nằm trong RAM, nên mỗi lần khởi động lại là biểu tượng đang tải quay khắp màn hình. Muốn dùng được khi ngoại tuyến thì bạn lưu nó xuống AsyncStorage:

import { QueryClient } from '@tanstack/react-query'
import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'
import { createAsyncStoragePersister } from '@tanstack/query-async-storage-persister'
import AsyncStorage from '@react-native-async-storage/async-storage'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      gcTime: 24 * 60 * 60 * 1000, // 24 hours  - must be >= maxAge
    },
  },
})

const asyncStoragePersister = createAsyncStoragePersister({
  storage: AsyncStorage,
  key: 'react-query-cache',
})

// In your App component
function App() {
  return (
    <PersistQueryClientProvider
      client={queryClient}
      persistOptions={{
        persister: asyncStoragePersister,
        maxAge: 24 * 60 * 60 * 1000, // Don't restore data older than 24 hours
        dehydrateOptions: {
          shouldDehydrateQuery: (query) => {
            // Only persist successful queries
            return query.state.status === 'success'
          },
        },
      }}
    >
      <YourApp />
    </PersistQueryClientProvider>
  )
}

Giờ thì dù mở ứng dụng ở chỗ không có sóng, người dùng vẫn thấy ngay dữ liệu tải về lần gần nhất thay vì một màn hình trắng, và khi có mạng lại thì React Query lặng lẽ tải dữ liệu mới.

Bước 4: xếp hàng các thao tác ghi khi mất mạng

#

Đọc là phần dễ. Ghi mới là chỗ chế độ ngoại tuyến trở nên thú vị: người dùng thêm bình luận, gửi đơn hàng hay sửa hồ sơ lúc không có mạng, và thay đổi đó phải được xếp vào hàng đợi để gửi lại sau.

React Query giải quyết chuyện này bằng useMutation kèm cập nhật lạc quan trong onMutate:

import { useMutation, useQueryClient } from '@tanstack/react-query'
import AsyncStorage from '@react-native-async-storage/async-storage'

interface Comment {
  id: string
  text: string
  postId: string
  createdAt: string
  pending?: boolean
}

function useAddComment(postId: string) {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: async (text: string) => {
      const res = await fetch(`/api/posts/${postId}/comments`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ text }),
      })
      return res.json()
    },

    // Optimistic update  - show the comment immediately
    onMutate: async (text) => {
      await queryClient.cancelQueries({ queryKey: ['comments', postId] })

      const previous = queryClient.getQueryData<Comment[]>(['comments', postId])

      const optimisticComment: Comment = {
        id: `temp-${Date.now()}`,
        text,
        postId,
        createdAt: new Date().toISOString(),
        pending: true, // Show a "sending..." indicator in the UI
      }

      queryClient.setQueryData<Comment[]>(
        ['comments', postId],
        (old) => [...(old ?? []), optimisticComment]
      )

      return { previous }
    },

    // Roll back on failure
    onError: (err, text, context) => {
      if (context?.previous) {
        queryClient.setQueryData(['comments', postId], context.previous)
      }
    },

    // Refetch to get the real data from the server
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['comments', postId] })
    },
  })
}

Khi đặt networkMode: 'offlineFirst' cho thao tác ghi, mutationFn sẽ tạm dừng cho tới khi có mạng trở lại. Cập nhật lạc quan đưa bình luận lên màn hình ngay lập tức, còn lời gọi API thật sẽ chạy khi kết nối lại.

Nếu cần một hàng đợi nghiêm túc hơn, chẳng hạn có vài chục thay đổi đang chờ và phải gửi lại đúng thứ tự, bạn có thể lưu luôn cả hàng đợi thao tác ghi xuống thiết bị:

import { MutationCache } from '@tanstack/react-query'

// Save pending mutations to AsyncStorage
const mutationCache = new MutationCache({
  onError: async (error, variables, context, mutation) => {
    // Log failed mutations for debugging
    const pending = JSON.parse(
      await AsyncStorage.getItem('pending_mutations') ?? '[]'
    )
    pending.push({
      key: mutation.options.mutationKey,
      variables,
      timestamp: Date.now(),
    })
    await AsyncStorage.setItem('pending_mutations', JSON.stringify(pending))
  },
})

Bước 5: đồng bộ lại khi có mạng

#

Phần lớn việc xử lý khi kết nối lại thì React Query tự lo: thao tác ghi đang tạm dừng sẽ chạy tiếp, truy vấn đã cũ sẽ được tải lại. Bạn chỉ cần nối các trình quản lý (manager) của nó với sự kiện của React Native.

import NetInfo from '@react-native-community/netinfo'
import { onlineManager, focusManager } from '@tanstack/react-query'
import { AppState } from 'react-native'

// Tell React Query about network state changes
onlineManager.setEventListener((setOnline) => {
  return NetInfo.addEventListener((state) => {
    setOnline(!!state.isConnected)
  })
})

// Refetch when the app comes back to foreground
focusManager.setEventListener((setFocused) => {
  const subscription = AppState.addEventListener('change', (status) => {
    setFocused(status === 'active')
  })
  return () => subscription.remove()
})

Khi người dùng để ứng dụng chạy nền một tiếng rồi mở lại, focusManager sẽ kích hoạt việc tải lại để họ thấy dữ liệu mới. Khi họ ra khỏi đường hầm và có sóng trở lại, onlineManager cho những thao tác đang tạm dừng chạy tiếp.

Bước 6: thông báo rõ trên giao diện

#

Dù làm gì thì cũng đừng lẳng lặng nuốt lỗi mạng. Hãy cho người dùng biết họ đang ngoại tuyến và thay đổi nào vẫn đang chờ gửi.

import { useNetworkStore } from './stores/network'

function OfflineBanner() {
  const isOnline = useNetworkStore((s) => s.isOnline)

  if (isOnline) return null

  return (
    <View style={styles.banner}>
      <Text>You're offline. Changes will sync when you reconnect.</Text>
    </View>
  )
}

function CommentItem({ comment }: { comment: Comment }) {
  return (
    <View style={[styles.comment, comment.pending && styles.pending]}>
      <Text>{comment.text}</Text>
      {comment.pending && (
        <Text style={styles.pendingLabel}>Sending...</Text>
      )}
    </View>
  )
}

Bức tranh toàn cảnh

#

┌─────────────────────────────────────────────────┐
│                   Components                     │
│  useQuery() for reads    useMutation() for writes│
└──────────┬──────────────────────┬────────────────┘
           │                      │
     ┌─────▼──────┐        ┌─────▼──────┐
     │ React Query │        │ React Query │
     │   Cache     │        │  Mutation   │
     │ (in-memory) │        │   Queue     │
     └─────┬──────┘        └─────┬──────┘
           │                      │
     ┌─────▼──────────────────────▼──────┐
     │     AsyncStorage Persister         │
     │  (survives app restart)            │
     └─────┬──────────────────────┬──────┘
           │                      │
     ┌─────▼──────┐        ┌─────▼──────┐
     │   Zustand   │        │   Network  │
     │ (isOnline,  │◄───────│   NetInfo  │
     │  UI state)  │        │            │
     └────────────┘        └────────────┘

Khi nào cần một công cụ đồng bộ thực thụ

#

Tất cả những gì ở trên đều giả định máy chủ là nguồn dữ liệu gốc và việc mất mạng chỉ là tạm thời. Nếu bạn cần ưu tiên ngoại tuyến (offline-first) thật sự, có cả giải quyết xung đột (hình dung một ứng dụng ghi chú mà hai thiết bị cùng sửa một tài liệu lúc ngoại tuyến), thì bộ công nghệ này không kham nổi, và bạn cần một công cụ đồng bộ (sync engine) đúng nghĩa. WatermelonDB được làm riêng cho React Native, chạy trên SQLite và có sẵn giao thức đồng bộ để giải quyết xung đột. Realm kết hợp Atlas Device Sync là một cơ sở dữ liệu ưu tiên ngoại tuyến đầy đủ, tự động giải quyết xung đột qua MongoDB Atlas. PowerSync là một tầng đồng bộ dựa trên SQLite, chạy được với cơ sở dữ liệu Postgres sẵn có ở phía máy chủ của bạn. Còn nếu muốn toàn quyền kiểm soát thì bạn luôn có thể dùng Expo SQLite và tự viết logic đồng bộ.

Bộ ba Zustand + React Query + AsyncStorage đáp ứng được khoảng 80% ứng dụng di động. 20% còn lại, như các trình soạn thảo cộng tác hay những quy trình làm việc phụ thuộc nhiều vào chế độ ngoại tuyến trên nhiều thiết bị, thì cần một cơ sở dữ liệu có đồng bộ chuyên dụng.

Một mẩu trạng thái nên để ở đâu?

#

Khi phân vân không biết một thứ nên để ở đâu, tôi lần lượt hỏi mấy câu sau:

Các trường hợp thường gặp

#

Cài đặt theo từng nền tảng

#

React Native (Android + iOS)

#

Cài cả ba một lượt:

npm install zustand @tanstack/react-query @react-native-async-storage/async-storage

Thêm kho lưu trữ bảo mật cho những dữ liệu nhạy cảm:

npx expo install expo-secure-store
# or
npm install react-native-keychain

Expo

#

Với Expo, AsyncStorage chạy được ngay, không cần bước liên kết mã native (native linking).

npx expo install @react-native-async-storage/async-storage

React chỉ chạy trên web

#

Bỏ hẳn AsyncStorage, dùng thẳng localStorage hoặc IndexedDB.

npm install zustand @tanstack/react-query
# Optional for IndexedDB
npm install idb-keyval

Middleware persist của Zustand vốn đã dùng localStorage làm mặc định trên web:

persist(storeConfig, {
  name: 'my-store',
  // localStorage is the default on web  - no extra config needed
})

Những lỗi tôi gặp đi gặp lại

#

Bỏ dữ liệu API vào Zustand. Nếu trong action của bạn có dòng setUsers(apiResponse.users) thì dừng lại. Đó là việc của React Query, và chỉ một sprint nữa thôi là bạn sẽ tự chế lại cơ chế vô hiệu hóa bộ nhớ đệm, mà còn chế dở.

Dùng React Query cho trạng thái phía máy khách. Nếu queryFn không hề gửi yêu cầu mạng nào thì bạn đang dùng sai công cụ.

Dùng AsyncStorage như cơ sở dữ liệu. Tuần tự hóa một mảng 10,000 phần tử rồi nhét vào kho khóa-giá trị thì kết cục chỉ có khóc. Hãy dùng SQLite hoặc một cơ sở dữ liệu thật sự.

Lưu token mà không mã hoá. AsyncStorage không phải kho lưu trữ bảo mật. Token xác thực, API key và thông tin đăng nhập phải để trong expo-secure-store hoặc keychain của nền tảng.

Tự viết tay phần lưu trạng thái xuống thiết bị. Nếu bạn đang đọc AsyncStorage lúc component được gắn vào (mount) và ghi xuống mỗi khi trạng thái thay đổi, thì middleware persist của Zustand đã làm sẵn việc đó, lại lo luôn cả khâu nạp lại trạng thái (hydration) và tuần tự hóa, mã ít hơn mà lỗi cũng ít hơn.

Tóm lại: dữ liệu từ máy chủ đi qua React Query. Trạng thái phía máy khách nằm trong Zustand. Thứ gì cần giữ lại sau khi khởi động lại thì cho vào AsyncStorage, còn thứ gì nhạy cảm thì cho vào kho lưu trữ bảo mật.

Những kiến trúc tệ nhất tôi từng làm đều có một store khổng lồ mà mọi dữ liệu đều chảy qua. Những kiến trúc tốt nhất thì phân định rõ ràng giữa trạng thái phía máy chủ, trạng thái phía máy khách và những gì cần lưu lại lâu dài. Vạch sẵn các ranh giới đó từ sớm thì mọi thứ về sau sẽ dễ thở hơn nhiều.

Cập nhật, ngày 13 tháng 9 năm 2026. Sau khi bài này lên, Codemagic đã ra mắt Patch, một máy chủ OTA mã nguồn mở, tự vận hành được (self-hosted), theo mô hình CodePush. Nếu bạn tìm tới đây vì không muốn tự viết máy chủ, thì giờ đã có một lựa chọn thật sự: tôi đã chuyển một ứng dụng từ hệ thống bên dưới sang Patch và viết lại quá trình đó, ngoài ra còn có một ghi chú ngắn ở phần Tổng kết. Minh bạch: Codemagic đã trả tiền để tôi thực hiện đợt di chuyển đó và viết về nó, và họ đề nghị nhắc tới ở đây. Phần mã trong bài sau đó đã được rút gọn thành các ví dụ ngắn.

Với ứng dụng báo giá mà tôi đang làm, các bản sửa lỗi được đẩy thẳng qua mạng (over the air): phần mã JavaScript mới về tận điện thoại người dùng mà không phải chờ App Store duyệt. Thật ra EAS Update, dịch vụ do chính Expo vận hành, sẵn sàng lo việc này giúp bạn. Nhưng tôi vẫn tự làm một bản riêng bằng Django REST Framework và Tigris S3, và từ đó tới giờ, mọi bản cập nhật cho cả iOS lẫn Android đều đi qua hệ thống này.

Cơ chế cập nhật OTA của Expo như sau: thư viện expo-updates trong ứng dụng gửi yêu cầu lấy manifest tới một máy chủ cập nhật, kèm theo nền tảng (platform) và phiên bản runtime (runtime version) trong header. Máy chủ trả về bản cập nhật mới nhất còn tương thích, cùng URL của gói mã (bundle) JavaScript và các tài nguyên đi kèm; ứng dụng tải chúng về và chạy gói mã mới ở lần khởi động kế tiếp. EAS Update là máy chủ do Expo vận hành cho giao thức đó, nhưng thực ra máy chủ nào nói đúng giao thức cũng dùng được, và tôi đã tự làm một cái như thế.

Trong bài này, tôi sẽ đi qua toàn bộ hệ thống: các mô hình dữ liệu (model), endpoint trả về manifest, quy trình phát hành (publish), và cả những cái bẫy mà phải tự vận hành thì bạn mới gặp.

Vì sao lại tự vận hành?

#

Với tôi thì lý do chính là tiền. EAS Update tính phí theo mức sử dụng, nên khi bạn đẩy bản cập nhật thường xuyên cho một lượng người dùng ngày càng đông, chi phí sẽ cộng dồn lên. Trong khi đó, dịch vụ lưu trữ tương thích S3 như Tigris thì gần như miễn phí. Cũng có vài lý do khác, biết đâu còn quan trọng hơn với bạn. Một số ngành bắt buộc mọi tài nguyên (asset) của ứng dụng phải nằm trong hạ tầng của chính công ty. Tự nắm máy chủ cũng có nghĩa là tự nắm luồng cập nhật: nếu sản phẩm cần, bạn có thể phát hành dần cho từng nhóm người dùng, hay thử nghiệm A/B với các gói mã (bundle) khác nhau. Và quy trình cập nhật của bạn không còn phụ thuộc vào chuyện dịch vụ của Expo có ổn định hay không, hay lần tới họ sẽ đổi bảng giá ra sao.

Các thành phần kết nối với nhau thế nào

#

Hệ thống gồm bốn thành phần: một máy chủ Django trả về manifest của bản cập nhật và lưu siêu dữ liệu (metadata); Tigris chứa các tệp gói mã và tài nguyên thật; một script phát hành lo phần kết xuất (export), tải lên và đăng ký bản cập nhật; và cuối cùng là chính ứng dụng di động, được cấu hình trỏ về máy chủ của tôi thay vì máy chủ của Expo.

┌─────────────────┐
│   Mobile App    │
│  (expo-updates) │
└────────┬────────┘
         │ 1. Request manifest
         │    (with headers: platform, runtime-version)
         ↓
┌─────────────────┐
│  Django Server  │
│  /api/expo-     │◄─── 2. Query DB for latest update
│   updates/      │
│   manifest/     │
└────────┬────────┘
         │ 3. Generate presigned URLs
         │
         ↓
┌─────────────────┐
│   Tigris S3     │
│  (Asset Files)  │◄─── 4. App downloads bundles directly
└─────────────────┘

Bắt tay vào làm

#

Hai mô hình dữ liệu

#

Mọi thứ đều xoay quanh hai mô hình ExpoUpdate và ExpoUpdateAsset. Mô hình thứ nhất lưu siêu dữ liệu của từng bản cập nhật:

class ExpoUpdate(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    runtime_version = models.CharField(max_length=50, db_index=True)
    platform = models.CharField(
        max_length=10,
        choices=[("ios", "iOS"), ("android", "Android")],
        db_index=True
    )
    is_active = models.BooleanField(default=True, db_index=True)
    manifest_data = models.JSONField()
    description = models.TextField(blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        indexes = [
            models.Index(fields=["runtime_version", "platform", "is_active", "-created_at"])
        ]

Trong mô hình này có vài chỗ tôi cố ý thiết kế như vậy. runtime_version tương ứng với runtimeVersion trong app.json, và trường này gánh khá nhiều việc: máy khách chỉ tải những bản cập nhật có cùng phiên bản runtime (runtime version) với mình. iOS và Android được lưu thành hai bản ghi riêng, vì gói mã của hai nền tảng khác nhau. is_active chính là cơ chế khôi phục về phiên bản trước (rollback): chỉ cần tắt bản cập nhật bị lỗi là máy khách quay về bản trước đó. Còn manifest_data lưu nguyên manifest theo giao thức Expo Updates v1 dưới dạng JSON, nên về sau muốn trả manifest ra thì chỉ cần tra một lần là xong.

ExpoUpdateAsset thì theo dõi từng tệp riêng lẻ:

class ExpoUpdateAsset(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    update = models.ForeignKey(ExpoUpdate, on_delete=models.CASCADE, related_name="assets")
    hash = models.CharField(max_length=255, db_index=True)
    key = models.CharField(max_length=255)
    content_type = models.CharField(max_length=100)
    file_extension = models.CharField(max_length=10)
    file_path = models.CharField(max_length=500)
    file_size = models.IntegerField(default=0)

Tài nguyên được định danh bằng mã băm (hash) SHA-256, nên nội dung của chúng không bao giờ đổi và có thể lưu đệm (cache) thoải mái. Một tài nguyên dùng chung cho bao nhiêu bản cập nhật cũng được.

Endpoint manifest

#

/api/expo-updates/manifest/ là nơi ứng dụng và máy chủ thật sự trao đổi với nhau. Endpoint này được xây dựng theo giao thức Expo Updates v1:

@action(detail=False, methods=["get"], url_path="manifest")
def manifest(self, request):
    # Extract required headers
    protocol_version = request.META.get("HTTP_EXPO_PROTOCOL_VERSION")
    platform = request.META.get("HTTP_EXPO_PLATFORM")
    runtime_version = request.META.get("HTTP_EXPO_RUNTIME_VERSION")

    # Validate protocol version
    if protocol_version != "1":
        return Response(
            {"error": f"Unsupported protocol version: {protocol_version}"},
            status=400
        )

    # Find latest active update for this runtime + platform
    update = ExpoUpdate.objects.filter(
        runtime_version=runtime_version,
        platform=platform,
        is_active=True,
    ).order_by("-created_at").first()

    # No update available - client uses embedded bundle
    if not update:
        response = Response(status=204)
        response["expo-protocol-version"] = "1"
        return response

    # Generate presigned URLs for all assets
    manifest_data = build_manifest(update)  # fills in presigned asset URLs

    return Response(manifest_data, status=200)

Ở đây có ba chi tiết cần để ý. Thứ nhất, phản hồi (response) 204 nghĩa là “không có bản cập nhật nào”, và ứng dụng cứ thế chạy tiếp với gói mã nhúng sẵn. Thứ hai, URL của tài nguyên trong manifest là URL ký sẵn (presigned URL), nên ứng dụng tải thẳng từ CDN của Tigris chứ không phải truyền mọi thứ qua Django. Thứ ba, header expo-protocol-version trong phản hồi là bắt buộc, vì máy khách sẽ kiểm tra giá trị này.

Phát hành bản cập nhật

#

Phần phát hành là một lệnh quản trị (management command) của Django, bên ngoài bọc thêm một shell script. Lệnh này đọc đầu ra của expo export, tính mã băm SHA-256 cho từng tài nguyên, tải song song gói mã và tài nguyên lên Tigris, ghi bản ghi vào cơ sở dữ liệu, và nếu cần thì đặt thêm vào bucket một tệp JSON dùng để nhập (import) dữ liệu, phục vụ việc đồng bộ lên môi trường production. Rút gọn lại thì phần quan trọng trông như sau:

from concurrent.futures import ThreadPoolExecutor

from django.db import transaction


def publish(platform, runtime_version, manifest, files):
    # Upload the bundle and assets in parallel (keys are content hashes)
    with ThreadPoolExecutor(max_workers=10) as executor:
        list(executor.map(upload_asset, files))

    # Swap the active update in one transaction
    with transaction.atomic():
        ExpoUpdate.objects.filter(
            runtime_version=runtime_version,
            platform=platform,
            is_active=True,
        ).update(is_active=False)

        return ExpoUpdate.objects.create(
            runtime_version=runtime_version,
            platform=platform,
            manifest_data=manifest,
        )

Còn thứ tôi thật sự gõ hằng ngày là script bọc ngoài:

# Publish to local environment
./publish.sh ios

# Publish to production
./publish.sh ios --production

# Dry run to validate
./publish.sh --dry-run

Script này nạp các biến môi trường production trước khi kết xuất, chạy được cho một hoặc cả hai nền tảng, và lo luôn phần đồng bộ lên production mà tôi sẽ nói ngay bên dưới.

Đồng bộ lên production

#

Tôi không muốn để sẵn thông tin đăng nhập (credential) của production trên laptop, nên việc triển khai lên production được chia làm hai bước. Đầu tiên là phát hành từ môi trường cục bộ (local): tài nguyên được đẩy lên Tigris, kèm một bản chụp siêu dữ liệu dạng JSON. Sau đó gọi một endpoint API trên production, kèm theo đường dẫn S3, để máy chủ tự nhập siêu dữ liệu về:

@action(detail=False, methods=["post"], url_path="import-update")
def import_update(self, request):
    # Authenticate via Bearer token
    token = request.META.get("HTTP_AUTHORIZATION", "").removeprefix("Bearer ")
    if not hmac.compare_digest(token, settings.IMPORT_TOKEN):
        return Response({"error": "Invalid token"}, status=401)

    # Download the import JSON from the bucket
    s3_key = request.data.get("s3_key")
    obj = s3_client.get_object(Bucket=bucket_name, Key=s3_key)
    data = json.loads(obj["Body"].read())

    # Import into the production database
    with transaction.atomic():
        update, _ = ExpoUpdate.objects.update_or_create(id=data["id"], defaults={...})
        for asset_data in data["assets"]:
            ExpoUpdateAsset.objects.update_or_create(...)

    # Clean up the import JSON
    s3_client.delete_object(Bucket=bucket_name, Key=s3_key)
    return Response({"update_id": str(update.id)})

Trỏ ứng dụng về máy chủ của bạn

#

Trong app.json, bạn khai báo URL cập nhật và phiên bản runtime:

{
  "expo": {
    "runtimeVersion": "1.0.0",
    "updates": {
      "url": "https://api.example.com/api/expo-updates/manifest/"
    }
  }
}

Chỗ này phải thật chặt chẽ: runtimeVersion ở ứng dụng và ở máy chủ lúc nào cũng phải khớp nhau. Mỗi khi thay đổi phần mã native hoặc nâng cấp Expo SDK, hãy tăng phiên bản runtime rồi phát hành bản cập nhật mới cho phiên bản đó.

Lưu trữ trên Tigris

#

Tigris là dịch vụ lưu trữ đối tượng (object storage) tương thích S3, rẻ hơn AWS S3 khá nhiều, lại có sẵn bộ nhớ đệm tại biên (edge cache) trên toàn cầu. Điểm này rất đáng giá khi người dùng phải tải về những gói mã nặng vài MB. Cấu hình phía Django như sau:

# settings.py
BUCKET_NAME = os.getenv("BUCKET_NAME")
AWS_ENDPOINT_URL_S3 = os.getenv("AWS_ENDPOINT_URL_S3")
AWS_ACCESS_KEY_ID = os.getenv("AWS_ACCESS_KEY_ID")
AWS_SECRET_ACCESS_KEY = os.getenv("AWS_SECRET_ACCESS_KEY")
AWS_REGION = os.getenv("AWS_REGION", "auto")

Còn phần khởi tạo client S3 thì chỉ là boto3 như bình thường:

import boto3

def create_s3_client(endpoint_url, region, access_key, secret_key):
    return boto3.client(
        "s3",
        endpoint_url=endpoint_url,
        region_name=region,
        aws_access_key_id=access_key,
        aws_secret_access_key=secret_key,
    )

Mọi lượt tải đều đi qua URL ký sẵn, nên ứng dụng lấy tệp thẳng từ CDN:

presigned_url = s3_client.generate_presigned_url(
    "get_object",
    Params={"Bucket": bucket_name, "Key": asset.file_path},
    ExpiresIn=3600,  # 1 hour
)

Bảo mật

#

Endpoint manifest được cố ý để không cần xác thực, vì ứng dụng phải nhận được bản cập nhật ngay cả khi chưa có ai đăng nhập. Endpoint nhập dữ liệu thì khác hẳn. Endpoint này ghi được vào cơ sở dữ liệu production, nên bắt buộc phải có một khóa bí mật dùng chung (shared secret), và phép so sánh khóa phải chạy trong thời gian không đổi (constant-time) để chặn tấn công định thời (timing attack):

IMPORT_TOKEN = os.getenv("IMPORT_TOKEN")

# Constant-time comparison prevents timing attacks
if not hmac.compare_digest(token, IMPORT_TOKEN):
    return Response({"error": "Invalid token"}, status=401)

Tính toàn vẹn của tài nguyên thì thiết kế đã lo sẵn: tệp nào cũng được đối chiếu với mã băm SHA-256 của nó, nên tài nguyên nào bị chỉnh sửa sẽ bị loại ngay. Ngoài ra, URL ký sẵn hết hạn sau một giờ, nên không ai dùng liên kết trực tiếp (hotlink) tới gói mã của bạn mãi được.

Giữ cho hệ thống chạy nhanh

#

Nhờ chỉ mục kết hợp (composite index) trên (runtime_version, platform, is_active, -created_at), truy vấn lấy manifest vẫn nhanh dù bản cập nhật có tích lại nhiều đến đâu:

class Meta:
    indexes = [
        models.Index(fields=["runtime_version", "platform", "is_active", "-created_at"])
    ]

Script phát hành tải tài nguyên lên song song:

with ThreadPoolExecutor(max_workers=10) as executor:
    futures = {executor.submit(upload_asset, asset): asset for asset in assets}
    for future in as_completed(futures):
        # Track progress

Với một bản cập nhật điển hình có khoảng 50 tài nguyên, thời gian phát hành giảm từ chừng 2 phút xuống còn 15 giây. Khâu phân phối thì không phải làm gì cả: Tigris tự lưu đệm tài nguyên ở các điểm biên (edge location) gần người dùng của bạn.

Quy trình làm việc hằng ngày

#

Trong lúc phát triển

#

# 1. Make code changes in the app
git commit -am "Fix bug"

# 2. Publish OTA update to local environment
./publish.sh ios

# 3. Test on device
# App automatically downloads and applies update

Đưa lên production

#

# 1. Publish to production
./publish.sh ios --production

# 2. Monitor
# Check Django admin for update records
# Verify assets in Tigris dashboard

Khôi phục về phiên bản trước

#

# Mark problematic update as inactive in Django admin
# or via management shell:
python manage.py shell

>>> from updates.models import ExpoUpdate
>>> bad_update = ExpoUpdate.objects.get(id="uuid-here")
>>> bad_update.is_active = False
>>> bad_update.save()

# Clients will now receive the previous active update

Chi phí thực tế

#

Ứng dụng này hiện có khoảng 500 người dùng hoạt động. Trên Tigris, ~200 MB các bản cập nhật tích lũy từ trước tới giờ tốn chừng $0.02/tháng, còn ~50 GB lưu lượng tải ra (egress) mỗi tháng từ các lượt tải bản cập nhật thì khoảng $1.00. Phần Django chạy ké trên chính máy chủ đang chạy API của tôi, nên không phát sinh thêm đồng nào. Tính tròn thì tổng cộng là một đô mỗi tháng. Với mức sử dụng tương tự, EAS Update sẽ rơi vào khoảng $300–500/năm, nên có thể nói hệ thống này hoàn vốn gần như ngay lập tức.

Giám sát và gỡ lỗi

#

Phần này chẳng có gì cầu kỳ. Viewset ghi nhật ký (log) mọi yêu cầu lấy manifest:

logger.info(f"Manifest request: platform={platform}, runtime={runtime_version}")

Trên thực tế, Django admin chính là bảng điều khiển. Chỉ cần đăng ký các mô hình là bạn xem và lọc được mọi thứ:

@admin.register(ExpoUpdate)
class ExpoUpdateAdmin(admin.ModelAdmin):
    list_display = ["platform", "runtime_version", "is_active", "created_at"]
    list_filter = ["platform", "is_active", "runtime_version"]
    search_fields = ["description"]

Còn ở phía máy khách, expo-updates sẽ cho bạn biết nó đang thấy gì:

import * as Updates from 'expo-updates';

Updates.checkForUpdateAsync().then(update => {
  console.log('Update available:', update.isAvailable);
  console.log('Manifest:', update.manifest);
});

Những cái bẫy

#

Lệch phiên bản runtime

#

Lỗi hay gặp nhất cũng là lỗi khó phát hiện nhất: máy khách chỉ tải những bản cập nhật khớp với phiên bản runtime của mình. Nếu ứng dụng đã cài đang ở runtime 1.0.0 mà bạn lại phát hành cho 1.0.1, thì sẽ chẳng có bản cập nhật nào về máy, mà cũng chẳng có lỗi nào báo ra. Hãy giữ phiên bản runtime đồng bộ với các bản dựng (build), và chỉ tăng nó khi phần mã native thay đổi.

Dấu thời gian createdAt

#

Thư viện expo-updates phía máy khách so sánh createdAt trong manifest với commitTime của gói mã nhúng sẵn, và chỉ áp dụng bản cập nhật nào có createdAt mới hơn. Trong viewset, tôi ghi đè giá trị này bằng dấu thời gian (timestamp) lấy từ cơ sở dữ liệu:

manifest_data["createdAt"] = update.created_at.strftime("%Y-%m-%dT%H:%M:%S.%fZ")

Khi phát triển trên máy cục bộ, nếu bạn dựng lại bản nhị phân của ứng dụng sau khi đã phát hành OTA, hãy phát hành lại bản OTA đó để dấu thời gian của nó mới hơn.

Giá trị key của tài nguyên trong manifest

#

Trường key trên mỗi tài nguyên trong manifest là thứ expo-updates dùng để lưu đệm, và giá trị này phải là một mã băm tất định (MD5 của tên tệp là được), chứ không phải UUID ngẫu nhiên hay một chuỗi tùy ý. Làm sai chỗ này thì máy khách có thể không lưu đệm hoặc không lấy lại được tài nguyên đúng cách, và bản cập nhật sẽ âm thầm hỏng sau lần tải thành công đầu tiên. Cảm ơn bạn đọc Raphael Mutschler đã chỉ ra lỗi này: bản cập nhật bên anh ấy chỉ chạy được đúng một lần, rồi anh mới tìm ra nguyên nhân.

Cấu hình ứng dụng trong expoClient

#

Nếu ứng dụng của bạn dùng Linking, Constants, hay bất cứ thứ gì đọc cấu hình ứng dụng (app config) lúc chạy, thì trường extra.expoClient trong manifest phải chứa cấu hình đó. Thiếu trường này, lúc đầu ứng dụng có thể vẫn mở lên bình thường, nhưng sau khi bị đóng thì bị sập (crash) hoặc không chịu mở lại nữa. Lý do là expo-updates thay manifest nhúng sẵn bằng manifest OTA, và nếu thiếu expoClient thì các API kia mất luôn phần cấu hình mà chúng dựa vào. Lỗi này cũng do Raphael Mutschler phát hiện.

Dọn dẹp tài nguyên

#

Các bản cập nhật cũ cứ thế chất đống trên Tigris. Hiện tại tôi vẫn dọn bằng tay:

# Delete updates older than 30 days
from datetime import timedelta
from django.utils import timezone

cutoff = timezone.now() - timedelta(days=30)
old_updates = ExpoUpdate.objects.filter(created_at__lt=cutoff, is_active=False)

for update in old_updates:
    # Delete assets from S3
    for asset in update.assets.all():
        s3_client.delete_object(Bucket=bucket_name, Key=asset.file_path)
    # Delete DB records
    update.delete()

Rõ ràng đoạn này nên được đưa vào một tác vụ chạy định kỳ (scheduled task). Chỉ là tôi chưa có thời gian làm.

Những thứ tôi muốn làm tiếp

#

(Tháng 9 năm 2026: Patch giờ đã có sẵn cả ba thứ này và hơn thế nữa; xem bài viết về đợt di chuyển.)

Phát hành theo từng đợt

#

Chỉ cần thêm một trường rollout_percentage là có thể phát hành bản cập nhật cho một phần người dùng trước:

rollout_percentage = models.IntegerField(default=100)

# In the manifest view:
if update.rollout_percentage < 100:
    # Hash user ID and check if they're in rollout group
    user_hash = int(hashlib.sha256(user_id.encode()).hexdigest(), 16)
    if (user_hash % 100) >= update.rollout_percentage:
        return Response(status=204)  # No update

Tách riêng bản cập nhật cho staging

#

Thêm một trường environment thì các bản dựng cho môi trường staging có thể nhận bản cập nhật khác với production:

environment = models.CharField(max_length=20, default="production")

# Client sends environment in custom header
environment = request.META.get("HTTP_X_UPDATE_ENVIRONMENT", "production")
update = ExpoUpdate.objects.filter(environment=environment, ...).first()

Thống kê lượt tải

#

Và một mô hình nhỏ nữa sẽ trả lời đàng hoàng câu hỏi “rốt cuộc đã có ai nhận được bản này chưa?”:

class ExpoUpdateDownload(models.Model):
    update = models.ForeignKey(ExpoUpdate, on_delete=models.CASCADE)
    user_id = models.CharField(max_length=255, null=True)
    platform = models.CharField(max_length=10)
    downloaded_at = models.DateTimeField(auto_now_add=True)

Tổng kết

#

Toàn bộ hệ thống chỉ gồm hai mô hình và vài view của Django, một script phát hành, và một đô mỗi tháng tiền hạ tầng. Ít hơn nhiều so với tôi nghĩ lúc bắt đầu, và từ đó tới nay nó vẫn lặng lẽ làm tốt việc của mình cho ứng dụng trên cả hai nền tảng.

Phần mã ở trên là các ví dụ đã được rút gọn từ chính ứng dụng đang chạy production đó, nên bạn cứ điều chỉnh cho hợp với dự án của mình. Còn nếu muốn bắt đầu từ một thứ đã chạy được sẵn, bạn đọc Raphael Mutschler cũng đã công bố một phiên bản độc lập của riêng anh ấy tại expo-ota-server.

Nếu bạn không muốn tự viết máy chủ

#

Từ lúc tôi viết bài này, đã có hai thứ xuất hiện làm được cùng việc mà không cần tới Django. Thứ nhất là expo-ota-server của Raphael ở trên. Thứ hai là Codemagic Patch: mã nguồn mở, chạy trên máy của chính bạn qua một bộ cài Docker Compose, và nói giao thức CodePush thay vì Expo Updates, nên bạn thay expo-updates bằng SDK của nó và thay eas update bằng cmpatch release-react. Nó dùng được kho lưu trữ tương thích S3, nên một bucket Tigris như trong bài này cũng chạy được.

Ngay từ đầu, nó đã có sẵn những thứ tôi liệt kê ở mục “Những thứ tôi muốn làm tiếp” mà chưa bao giờ xây: môi trường triển khai staging và production riêng, phát hành theo tỷ lệ phần trăm, số lượt tải và cài của từng bản, cập nhật bắt buộc, bản vá nhị phân, ký mã (code signing), và khôi phục (rollback) ngay trên thiết bị khi gói mã mới bị sập trước khi ứng dụng kịp báo sẵn sàng. Cái giá phải trả là một bản nhị phân native mới trước khi bất kỳ ai nhận được bản cập nhật qua Patch, vì SDK phải có trong ứng dụng, và một máy chủ phải vận hành thay cho một lệnh quản trị.

Tôi đã chuyển một ứng dụng của chính mình, với dự án native đã commit và quy trình phát hành thật, từ hệ thống trong bài này sang Patch. Bài viết đó kể lại những gì chạy tốt, những gì không, và thật sự thì khó tới mức nào. Codemagic tài trợ cho phần việc đó và có một lượt đọc duyệt về tính chính xác của sự kiện, chứ không phải duyệt biên tập.

Muốn đọc toàn bộ đặc tả, bạn tham khảo tài liệu đặc tả giao thức Expo Updates.

Trong bài này, tôi sẽ kể lại cách mình làm ra nó với llama.rn (thư viện kết nối React Native với llama.cpp) và Qwen 1.7B, một mô hình nhỏ nhưng hóa ra làm được nhiều hơn tôi tưởng.

Tóm tắt nhanh: cài llama.rn, tải một mô hình GGUF 4-bit (khoảng 1 GB) về ở lần đầu mở ứng dụng, nạp nó bằng initLlama, rồi cho nó sinh câu trả lời theo kiểu truyền dần (streaming). Trên iPhone 14 Pro, tốc độ đạt khoảng 15 token mỗi giây mà không cần chút mạng nào. Phần còn lại của bài là những gì tôi phải làm để biến nó thành thứ thực sự dùng được: chọn mô hình, khiến nó gọi công cụ (tool call) một cách ổn định, và giữ mức dùng bộ nhớ trong tầm kiểm soát.

📝 Cập nhật: Bản hiện tại đã chuyển sang Qwen3.5-2B-GGUF thay cho Qwen3-1.7B ban đầu. Tôi cũng bỏ luôn mẹo chèn /no_think vào tin nhắn, giờ thì tắt chế độ suy nghĩ (thinking mode) đúng cách qua tham số chat_template_kwargs:

chat_response = client.chat.completions.create(
    model="Qwen/Qwen3.5-27B",
    messages=messages,
    max_tokens=32768,
    temperature=0.7,
    top_p=0.8,
    presence_penalty=1.5,
    extra_body={
        "top_k": 20,
        "chat_template_kwargs": {"enable_thinking": False},
    },
)

Gọn gàng hơn nhiều so với kiểu lén nhét cờ điều khiển vào prompt.

Vì sao tôi không muốn dùng AI trên đám mây cho việc này

#

Cách làm tính năng AI quen thuộc trong ứng dụng di động là: người dùng gõ tin nhắn, ứng dụng gửi nó sang một nhà cung cấp mô hình trên đám mây, nhận câu trả lời về, và hóa đơn lại nhích lên một chút.

Nhưng với một ứng dụng mà thợ thi công dùng để điều hành việc làm ăn của chính họ, cách làm đó có vấn đề. Tên, địa chỉ, số điện thoại của khách hàng bị gửi cho bên thứ ba. Chi tiết dự án, giá cả và ghi chú thì nằm trên máy chủ của người khác. Rồi còn những câu hỏi về GDPR và nơi lưu trữ dữ liệu mà thật lòng tôi không muốn mất thời gian vào. Chưa kể hóa đơn API cứ tăng dần theo số người dùng.

Cách còn lại là chạy mô hình ngay trên điện thoại của người dùng, và tôi đã chọn cách đó.

Vì sao đến giờ chuyện này mới khả thi

#

Nếu là một năm trước thì tôi đã chẳng buồn thử. Nhưng có ba thứ thay đổi gần như cùng lúc. Thứ nhất, mô hình lượng tử hóa (quantized) đã đủ nhỏ: Qwen 1.7B ở mức Q4_K_M chỉ nặng 1.1 GB, nhẹ hơn phần lớn các game, tải về một lần là nằm luôn trong bộ lưu trữ của ứng dụng. Thứ hai, GPU trên điện thoại đã đủ nhanh: llama.cpp dùng Metal trên iOS và OpenCL trên GPU Qualcomm của các máy Android đời mới, và trên iPhone 14 Pro tôi đo được khoảng 15 token mỗi giây, thừa sức để truyền dần câu trả lời (streaming) theo thời gian thực. Thứ ba, mô hình nhỏ giờ đã thực sự dùng được: Qwen 1.7B làm theo chỉ dẫn có cấu trúc, phân tích được JSON và suy luận qua nhiều bước. Logic nghiệp vụ cần đúng những khả năng đó. Có ai bắt nó làm thơ đâu.

Chọn mô hình

#

Tôi đã thử bốn mô hình nhỏ trước khi chốt Qwen3-1.7B.

TinyLlama 1.1B (637 MB) chạy nhanh nhất, nhưng cứ bịa ra ID khách hàng và bỏ sót các trường bắt buộc, nên đầu ra có cấu trúc thì không tin được. Phi-3-mini (1.8 GB) suy luận tốt nhưng nói nhiều không chịu nổi; hỏi một câu đơn giản, nó trả về cả bài văn 200 chữ trong khi tôi chỉ cần 20. Gemma-2B (1.2 GB) nhanh, phân loại chính xác, nhưng gọi hàm lại yếu: nó không sinh ra đều đặn được các thẻ <action> mà hệ thống công cụ của tôi cần. Qwen3-1.7B (1.1 GB) thì vừa khéo: đầu ra có cấu trúc ổn định, làm theo chỉ dẫn chính xác, lại hỗ trợ chuỗi suy luận (chain-of-thought) qua thẻ <think>.

Q4_K_M là một trong các định dạng “k-quant” của llama.cpp: trọng số được lưu thành giá trị 4-bit theo từng khối, mỗi khối mang hệ số tỉ lệ (scale) riêng, còn biến thể M giữ một vài tensor nhạy cảm ở mức 6-bit. Nhờ vậy tệp mô hình nhỏ hơn khoảng 70% so với trọng số 16-bit, mà chất lượng chỉ giảm chút ít.

Cài đặt llama.rn

#

llama.rn bọc llama.cpp lại để dùng được trong React Native, và cài đặt là phần dễ nhất:

npm install llama.rn
cd ios && pod install

Nếu dùng Expo thì cần lưu ý: llama.rn là một native module, nên không chạy được trong Expo Go. Bạn thêm config plugin của nó vào và dùng bản development build:

// app.config.js
export default {
  expo: {
    plugins: ["llama.rn"],
  },
};

npx expo install llama.rn
npx expo run:ios

Với bản build production, plugin này còn thêm hai entitlement iOS mà llama.rn khuyến nghị cho mô hình lớn: mở rộng vùng địa chỉ ảo (extended virtual addressing) và nâng giới hạn bộ nhớ (increased memory limit).

Còn bản thân mô hình thì được tải xuống ở lần dùng đầu tiên:

const MODEL_URL = "https://huggingface.co/unsloth/Qwen3-1.7B-GGUF/resolve/main/Qwen3-1.7B-Q4_K_M.gguf";
const MODEL_PATH = FileSystem.documentDirectory + "llama-models/Qwen3-1.7B-Q4_K_M.gguf";

const downloadModel = async () => {
  const downloadResumable = FileSystem.createDownloadResumable(
    MODEL_URL,
    MODEL_PATH,
    {},
    (progress) => {
      const pct = progress.totalBytesWritten / progress.totalBytesExpectedToWrite;
      setDownloadProgress(pct);
    }
  );

  await downloadResumable.downloadAsync();
};

Qua WiFi thì mất 2-3 phút, qua LTE thì khoảng 5-8 phút. Khi tệp đã nằm trên máy, bạn nạp nó lên và bật tăng tốc bằng GPU:

const ctx = await initLlama({
  model: MODEL_PATH,
  n_ctx: 8192,      // 8K context window
  n_gpu_layers: 99, // Use GPU for all layers
});

Đừng bỏ qua n_gpu_layers: 99. Đẩy toàn bộ việc tính toán sang Metal hoặc OpenCL thay vì để CPU gánh sẽ giúp tốc độ tăng khoảng 5 lần.

Suy luận và truyền dần kết quả

#

Chẳng ai muốn ngồi nhìn biểu tượng đang tải xoay vòng suốt mười giây, nên quá trình suy luận (inference) trả câu trả lời ra dần từng token một:

let fullResponse = "";

await llamaContext.completion(
  {
    messages: [
      { role: "system", content: systemPrompt },
      { role: "user", content: "Create a job for John Smith" }
    ],
    n_predict: 512,
    temperature: 0.7,
    top_p: 0.8,
  },
  (data) => {
    // Called for each token
    fullResponse += data.token;
    setStreamingText(fullResponse);
  }
);

Trên điện thoại đời mới, token đầu tiên xuất hiện sau khoảng 200ms (đó là thời gian xử lý prompt), sau đó mỗi token mất 50-80ms. So với bất cứ thứ gì phải chờ mạng, cảm giác gần như tức thì.

Gọi hàm theo cách mô hình nhỏ làm được thật

#

Cơ chế gọi hàm (function calling) của các mô hình lớn trên đám mây dựa vào JSON schema, và mô hình nhỏ gặp nó là “ngã”: JSON sai định dạng, thiếu trường, đủ cả. Vì vậy tôi dùng một giao thức đơn giản hơn, dựa trên XML:

const systemPrompt = `You are an AI assistant. When you need to take an action, output:
<action>{"type":"search_customers","query":"Smith"}</action>

Available actions:
- search_customers: {"type":"search_customers","query":"John"}
- create_job: {"type":"create_job","customer_id":5,"alias":"Living Room"}
- update_job: {"type":"update_job","job_id":"J-0042","status":"quoting"}

Rules:
1. ONE action tag per response, at the very end
2. When searching/creating → end with <action>
3. When just chatting → no action tag
`;

Thẻ XML thắng vì mấy lý do rất bình thường: <action> và </action> là dấu phân cách rõ ràng, phân tích chỉ cần một biểu thức chính quy (regex), các ví dụ trong prompt kiêm luôn vai trò tài liệu, và cách này vẫn chạy được khi mô hình nói thêm vài câu lan man quanh thẻ.

Phần phân tích thì đơn giản đúng như vẻ ngoài của nó:

function parseAction(text: string): Action | null {
  const match = text.match(/<action>([\s\S]*?)<\/action>/);
  if (!match) return null;

  try {
    return JSON.parse(match[1].trim());
  } catch {
    return null;
  }
}

Khi mô hình trả về một hành động (action), tôi thực thi nó rồi đưa kết quả ngược lại vào cuộc hội thoại:

const action = parseAction(modelResponse);
if (action) {
  const result = await executeAction(action);

  // Inject result as a system message
  conversationHistory.push({
    role: "user",
    content: `[TOOL_RESULT] ${result.message}\n\n→ NEXT: Tell the user what happened.`
  });

  // Continue generation
  await generateNextResponse();
}

Chừng đó đã đủ để chạy các luồng xử lý nhiều bước đúng nghĩa:

Người dùng: “Create a job for Smith”

1. Mô hình: <action>{"type":"search_customers","query":"Smith"}</action>
2. Hệ thống: [TOOL_RESULT] Found: Jane Smith (id:42), Bob Smith (id:89)
3. Mô hình: “I found two Smiths—Jane and Bob. Which one?”
4. Người dùng: “Jane”
5. Mô hình: <action>{"type":"create_job","customer_id":42}</action>
6. Hệ thống: [TOOL_RESULT] Job J-0073 created
7. Mô hình: “Done! Created job J-0073 for Jane Smith.”

Chuỗi suy luận với thẻ <think>

#

Mô hình nhỏ làm tốt hơn thấy rõ khi bạn bắt nó suy nghĩ thành lời. Qwen có sẵn chế độ suy nghĩ:

const systemPrompt = `Before each response, wrap your reasoning in <think> tags:

<think>
INTENT: what does the user want?
HAVE: what data do I already have?
NEED: what's still missing?
DECISION: call tool | ask user | just respond
</think>

Then output your actual response.`;

Bên trong, mô hình sẽ sinh ra nội dung trông như thế này:

<think>
INTENT: create a job
HAVE: customer query "Smith"
NEED: exact customer_id
DECISION: search first
</think>
<action>{"type":"search_customers","query":"Smith"}</action>

Tôi lọc bỏ các thẻ <think> trước khi hiển thị bất cứ thứ gì lên giao diện, nhưng trong lúc phát triển thì vẫn để chúng hiện ra. Độ ổn định khác nhau một trời một vực: mô hình tự lý luận qua từng bước rồi mới chốt một hành động.

Giữ các cuộc hội thoại dài nằm gọn trong 8K

#

Một khi kết quả từ công cụ bắt đầu dồn vào, cửa sổ ngữ cảnh (context window) 8K đầy nhanh hơn bạn tưởng. Tầm lượt thứ 30 là tôi chạm trần.

Cách tôi xử lý là nén cuộc hội thoại lại, bằng cách nhờ chính mô hình tự tóm tắt:

const compactPrompt = `Summarize this conversation in under 200 words.
Include: user's goal, customers/jobs created (with IDs), and any unfinished tasks.

${conversationHistory.map(m => `${m.role}: ${m.content}`).join('\n\n')}`;

const summary = await chat([{ role: "user", content: compactPrompt }]);

// Replace history with summary
conversationHistory = [
  { role: "user", content: `[CONTEXT SUMMARY]\n${summary}\n[END SUMMARY]` }
];

Một cuộc hội thoại 50 tin nhắn được ép xuống còn khoảng 150 token, mà mô hình vẫn tiếp tục bình thường, không quên mình đã tạo những công việc nào, với ID khách hàng nào.

Lưu phiên trò chuyện

#

Các phiên trò chuyện cũng được lưu xuống máy chủ (backend) của ứng dụng. Điều đáng học ở đây là lưu mỗi tin nhắn của trợ lý thành hai bản: một bản đã làm sạch để hiển thị, và một bản thô còn nguyên thẻ <think> và <action>. Nhờ vậy, lịch sử trò chuyện hiển thị lại gọn gàng trên giao diện, còn khi mở lại một phiên cũ thì mô hình được nạp lại đầy đủ ngữ cảnh, kể cả các hành động. Người dùng chuyển qua lại giữa các cuộc hội thoại bằng một danh sách thả xuống chứa lịch sử, giống như phần lớn các ứng dụng trò chuyện.

Số đo hiệu năng trên môi trường production

#

iPhone 14 Pro (A16 Bionic, 6GB RAM):

• Nạp mô hình: ~3 giây
• Token đầu tiên: 180-220ms
• Tốc độ sinh: 14-16 token/giây
• Bộ nhớ: ~1.8 GB

Samsung Galaxy S23 (Snapdragon 8 Gen 2, 8GB RAM):

• Nạp mô hình: ~4 giây
• Token đầu tiên: 250-300ms
• Tốc độ sinh: 10-12 token/giây
• Bộ nhớ: ~2.1 GB

iPhone 11 (A13, 4GB RAM):

• Nạp mô hình: ~6 giây
• Token đầu tiên: 400-500ms
• Tốc độ sinh: 6-8 token/giây
• Bộ nhớ: ~2.2 GB (thỉnh thoảng bị sập vì thiếu bộ nhớ)

Kinh nghiệm của tôi là cần từ 6GB RAM trở lên thì mới chạy mượt. Máy 4GB vẫn chạy được, nhưng nhiều khả năng bạn sẽ phải giải phóng mô hình mỗi khi ứng dụng chuyển xuống chạy nền.

Quản lý bộ nhớ

#

iOS sẵn sàng buộc đóng ứng dụng của bạn nếu nó ôm quá nhiều bộ nhớ, nên cứ mỗi lần ứng dụng rời khỏi màn hình chính (không còn chạy ở tiền cảnh) là tôi giải phóng mô hình:

useEffect(() => {
  const subscription = AppState.addEventListener("change", (nextAppState) => {
    if (nextAppState === "background") {
      llamaContext?.release(); // Free ~2 GB
    } else if (nextAppState === "active") {
      loadModel(); // Reload when foregrounded
    }
  });

  return () => subscription.remove();
}, []);