Bài này đi theo thứ tự ngược lại. Dịch vụ vẫn chạy trên chính cái máy đã dựng nên nó, và một Cloudflare Tunnel cho nó một tên miền HTTPS công khai. Không có gì trên laptop lắng nghe Internet: không chuyển tiếp cổng (port forwarding), không chỉnh router, không lộ địa chỉ IP. Máy chủ động gọi ra Cloudflare, và Cloudflare gửi request ngược xuống qua chính kết nối đó. Tunnel thì miễn phí, còn chứng chỉ TLS, chống DDoS và cache đi kèm với zone Cloudflare mà có lẽ bạn đã có sẵn.

Ví dụ ở đây là thật. Một sản phẩm của tôi chạy trên Fly.io, và ứng dụng di động của nó nhận bản cập nhật JavaScript qua mạng (OTA) từ backend (Expo Updates tự host). Tôi muốn có một bản sao thứ hai của máy chủ cập nhật đó chạy trên Mac cho các bản build phát triển, còn production thì giữ nguyên. Các kết quả bên dưới lấy từ buổi chiều hôm đó, kể cả đoạn nó không chạy.

Cloudflare Tunnel thực ra là gì

#

Một máy chủ bình thường ngồi chờ kết nối. Muốn chạm tới laptop từ Internet, bạn phải mở một cổng trên router, chuyển tiếp nó về laptop, rồi cầu mong nhà mạng cấp cho bạn một địa chỉ IPv4 công khai (ở nhiều nơi, kể cả chỗ tôi, thì không). Sau đó mọi thứ lắng nghe trên cổng ấy đều bị mọi máy quét trên Internet chạm tới, cả ngày.

Tunnel đảo ngược chuyện đó. cloudflared chạy cạnh ứng dụng của bạn và mở các kết nối đi ra tới edge của Cloudflare, bốn kết nối tới hai trung tâm dữ liệu gần nhất. Một bản ghi DNS trong zone của bạn trỏ một tên miền vào tunnel. Khi có request tới tên miền đó, Cloudflare kết thúc TLS rồi chuyển request xuống một trong các kết nối ấy. cloudflared sau đó giao nó cho dịch vụ cục bộ mà cấu hình của bạn chỉ định.

Về bảo mật, điểm quan trọng là router của bạn không có quy tắc chiều vào nào và địa chỉ IP của bạn không bao giờ xuất hiện trong DNS. Ai quét đường mạng nhà bạn cũng chẳng thấy gì, vì không có gì trên đó đang lắng nghe.

Thiết lập, từ đầu đến cuối

#

Bạn cần một tên miền trên Cloudflare (gói miễn phí là đủ) và cài cloudflared (brew install cloudflared trên Mac).

1. Đăng nhập một lần. Lệnh này mở trình duyệt, bạn chọn zone, và nó lưu một chứng chỉ cho phép máy này tạo tunnel và bản ghi DNS trong zone đó:

cloudflared tunnel login

2. Tạo tunnel. Tôi để mọi thứ của dự án này trong một thư mục riêng, vì tệp credentials chính là danh tính của tunnel: ai có nó đều phục vụ được lưu lượng cho các tên miền của bạn.

mkdir -p ~/.cloudflared/myapp && cd ~/.cloudflared/myapp
cloudflared tunnel create --credentials-file ./creds.json myapp-local
chmod 600 creds.json

Tunnel credentials written to ./creds.json. Keep this file secret. To revoke these credentials, delete the tunnel.
Created tunnel myapp-local with id 1ade030c-…

3. Trỏ tên miền vào nó. Mỗi tên miền một lệnh, tạo một CNAME có proxy tới <tunnel-id>.cfargotunnel.com:

cloudflared tunnel route dns myapp-local ota.example.com
cloudflared tunnel route dns myapp-local checkin-local.example.com

4. Viết các quy tắc ingress. Đây là phần quyết định về bảo mật, nên nó có hẳn một mục riêng bên dưới.

5. Chạy nó. Ứng dụng của tôi vốn đã chạy bằng Docker Compose, nên cloudflared chỉ là thêm một container trên cùng mạng. Nó gọi ứng dụng bằng tên service, và ứng dụng hoàn toàn không cần publish cổng nào ra máy host:

# compose.tunnel.yml, used alongside the project's docker-compose.yml
services:
  cloudflared:
    image: cloudflare/cloudflared:2026.10.7
    command: tunnel --config /etc/cloudflared/config.yml run
    volumes:
      - ${HOME}/.cloudflared/myapp:/etc/cloudflared:ro
    restart: unless-stopped
    depends_on: [api, edge]

docker compose -f docker-compose.yml -f ~/.cloudflared/myapp/compose.tunnel.yml up -d cloudflared

INF Registered tunnel connection connIndex=0 … location=icn06 protocol=quic
INF Registered tunnel connection connIndex=1 … location=icn07 protocol=quic
INF Registered tunnel connection connIndex=2 … location=icn07 protocol=quic
INF Registered tunnel connection connIndex=3 … location=icn06 protocol=quic

Bốn kết nối tới Seoul, và laptop đã có mặt trên Internet, nhìn từ ngoài vào. restart: unless-stopped đưa nó trở lại sau khi khởi động lại máy, ngay khi Docker chạy.

Mở đường dẫn, đừng mở cả máy chủ

#

Đây là lỗi tôi suýt mắc, và tôi đoán là lỗi phổ biến nhất. Cấu hình dễ nhất chỉ có một dòng: hostname → http://localhost:8000. Như thế là công khai toàn bộ máy chủ phát triển.

Máy chủ phát triển không được làm ra cho việc đó. Máy của tôi chạy với DEBUG=True, hiện đầy đủ traceback và settings mỗi khi có lỗi. Nó còn chạy với xác thực bị tắt (AUTH_MODE=disabled), nên bearer token nào cũng đăng nhập bạn thành một user test. Trên localhost thì vậy là đúng ý, còn trên một tên miền công khai thì là thảm họa. Máy của bạn chắc cũng có thứ tương tự: một trang admin với mật khẩu mặc định, một endpoint nạp dữ liệu mẫu, một debug toolbar, hay một API tin người gọi vì xưa nay chỉ có bạn gọi nó.

Vì vậy cấu hình tunnel là một danh sách cho phép (allowlist). cloudflared so mỗi request với các quy tắc ingress theo thứ tự, theo tên miền và theo một biểu thức chính quy trên đường dẫn. Quy tắc khớp đầu tiên thắng, và quy tắc cuối cùng hứng mọi thứ còn lại:

tunnel: myapp-local
credentials-file: /etc/cloudflared/creds.json

ingress:
  # OTA: the two read-only endpoints the phone calls, and the files they link.
  - hostname: ota.example.com
    path: ^/api/expo-updates/(manifest|status)/$
    service: http://api:8000
  - hostname: ota.example.com
    path: ^/media/
    service: http://api:8000
  # Device check-ins, authenticated by each device's own key.
  - hostname: checkin-local.example.com
    path: ^/c/$
    service: http://edge:8081
  # Everything else, including /admin/ and the publish endpoint: 404 at the edge.
  - service: http_status:404

Endpoint phát hành nằm trên cùng máy chủ, dưới cùng tiền tố (/api/expo-updates/import-update/), và nó không có trong danh sách. Trang admin hay phần còn lại của API cũng không. Những request đó không bao giờ ra khỏi Cloudflare.

Bạn không cần phải tin regex của mình; cloudflared sẽ cho bạn biết một URL khớp quy tắc nào:

cloudflared tunnel --config config.yml ingress rule https://ota.example.com/admin/

https://ota.example.com/api/expo-updates/manifest/        service: http://api:8000
https://ota.example.com/api/expo-updates/import-update/   service: http_status:404
https://ota.example.com/admin/                            service: http_status:404
https://ota.example.com/media/expo-updates/x.js           service: http://api:8000
https://checkin-local.example.com/c/                      service: http://edge:8081
https://checkin-local.example.com/health                  service: http_status:404

Tôi sẽ đưa bước kiểm tra này vào một script và chạy mỗi lần cấu hình thay đổi. Nó mất vài giây, còn một regex khớp rộng hơn ý bạn là kiểu lỗi mà bạn chỉ biết được qua người khác.

Thêm hai nguyên tắc nữa:

• Thứ bạn mở ra phải tự xác thực. Các endpoint OTA phục vụ dữ liệu công khai, chỉ đọc. Check-in của thiết bị được ký bằng khóa riêng của từng thiết bị. Không cái nào dựa vào mạng để giữ an toàn. Nếu muốn cho ai đó xem một trang không có đăng nhập, hãy đặt Cloudflare Access trước tên miền đó (miễn phí tới 50 người dùng) thay vì tự dựng trang đăng nhập.
• Đừng để tunnel chạy ngầm như một phần quen thuộc của quy trình dev. Chạy nó có chủ đích, cho đúng tên miền bạn cần, và tắt khi xong việc. docker compose stop cloudflared gỡ mọi thứ khỏi Internet chỉ bằng một lệnh.

Cú redirect nuốt mất tên miền của tôi

#

Tunnel đã kết nối, các quy tắc đã kiểm tra, tôi thử từ bên ngoài:

https://ota.example.com/api/expo-updates/status/?…   301
https://ota.example.com/api/expo-updates/manifest/   301
https://ota.example.com/admin/                       301
https://checkin-local.example.com/c/                 301

Đường dẫn nào cũng trả về cùng một mã 301, kể cả những đường dẫn mà tunnel lẽ ra phải trả 404. Nghĩa là request chưa bao giờ tới được cloudflared. Header Location ghi https://www.example.com/, và header server: cloudflare chốt lại: chính Cloudflare đang tự trả lời.

Tôi tự gây ra chuyện này. Mấy tháng trước tôi thêm một redirect rule ở cấp zone, “mọi subdomain khác → www”, làm hố chặn cho các máy quét dò những subdomain bịa ra. Redirect rule chạy trong pipeline xử lý request của Cloudflare trước khi request được gửi tới origin, mà tunnel thì cũng chỉ là một origin. Chính quy tắc đó đã tóm các môi trường preview của tôi trước khi Workers kịp thấy chúng. Cách sửa vẫn như lần trước: thêm một ngoại lệ vào biểu thức của quy tắc.

… and not http.host in {"ota.example.com" "checkin-local.example.com"}

Nếu tên miền tunnel của bạn trả về một redirect hay một trang lỗi của Cloudflare thay vì ứng dụng của bạn, hãy kiểm tra Rules → Redirect Rules, Page Rules và mọi WAF custom rule của zone trước khi đi debug tunnel. cloudflared ghi log mọi request nó chuyển tiếp, nên log trống nghĩa là request chưa đi được tới đó.

Những gì nó không làm được

#

• UDP từ Internet công khai. Tên miền tunnel công khai chỉ mang HTTP(S) (cùng WebSocket và gRPC). Thiết bị của sản phẩm tôi bình thường check-in bằng CoAP trên UDP, và thứ đó không đi qua tunnel được; các thiết bị trên bản sao cục bộ chuyển sang check-in qua HTTPS, mỗi lần tốn thêm vài giây. Nếu ý tưởng của bạn là game server hay VoIP, tunnel không phải công cụ phù hợp.
• Uptime. Đây là laptop của bạn. Gập máy là site sập; Cloudflare hiện trang lỗi 530. Với một bản demo, một bản beta mười người, hay một bản staging thì không sao. Với thứ gì có người phụ thuộc vào thì không ổn.
• Những thứ đã đóng cứng vào bản build. URL cập nhật của ứng dụng di động là cấu hình native, nên chỉ những bản build tạo với URL của tunnel mới dùng nó. Các bản build trên store của tôi vẫn nói chuyện với production, và đó là lý do thử cách này là an toàn.

Chi phí: Cloudflare Tunnel có miễn phí không?

#

Một zone Cloudflare gói miễn phí, tunnel, chứng chỉ của nó và các bản ghi DNS: 0 đô. Máy thì vốn đã chạy sẵn. Chi phí thật duy nhất là giờ bạn chính là đội lo uptime.

Thứ nó tiết kiệm cho bạn là giai đoạn giữa “chạy được trên máy tôi” và “đáng bỏ tiền ra host”. Ngay chiều hôm đó bạn đã có thể gửi link cho một tester, một designer hay khách hàng đầu tiên. Nếu không ai quan tâm, bạn chẳng mất gì. Nếu có, chuyển sang một host thật chỉ là một thay đổi: trỏ CNAME sang chỗ khác.

Tôi gặp chúng lần đầu vào tháng 9, khi bảng điều khiển Cloudflare báo 22% request bị lỗi trong khi mọi health check vẫn xanh; tôi tắt Early Hints và chuyển sang việc khác. Đến tháng 11, cũng zone đó lại có thêm 2.600 lỗi 504 trong một ngày, Early Hints lại đang bật, và lần này tôi muốn biết chính xác chúng là gì, cũng như cách đúng là tắt tính năng thêm lần nữa hay làm cho nó thực sự làm đúng việc. Zone này đứng trước một origin trên Fly.io, phục vụ một Django API, một web app viết bằng Expo và một trang marketing dựng bằng Hugo.

Câu trả lời ngắn

#

• Những lỗi 504 này được ghi bởi bộ cache Early Hints của Cloudflare, không phải bởi khách truy cập. Trong log của Cloudflare, chúng có ClientRequestSource = earlyHintsCache.
• Ở đây, 504 nghĩa là cache miss: Cloudflare không có gợi ý nào được lưu cho URL đó. Một lần hit được ghi là 2xx.
• Chúng không bao giờ chạm tới origin của bạn. OriginResponseStatus là 0.
• Early Hints chạy bằng response header HTTP Link. Các thẻ <link rel="preload"> trong HTML không cung cấp dữ liệu cho nó.
• Gửi header đó đi, và trên những trang có thứ cần preload, các lần miss sẽ chuyển thành hit và bắt đầu có phản hồi 103 Early Hints thật.

Có thêm ba điều đáng biết ngay từ đầu. Chỉ gợi ý CSS, script và font quan trọng cho việc render, và giữ crossorigin cho font. Kiểm tra bằng curl -sv --http2: bạn sẽ thấy 103 trước 200. Và dù quyết định thế nào, hãy để earlyHintsCache ra ngoài hệ thống cảnh báo; nếu bạn sẽ không bao giờ gửi header, hãy tắt Early Hints thay vì trả giá bằng tiếng ồn trong log.

Cách phân biệt 504 Cloudflare giả với 504 thật

#

Nếu bạn dùng Logpush hoặc Instant Logs, hãy xem hai trường trước tiên. ClientRequestSource là eyeball với request của khách truy cập thật, và là earlyHintsCache với các lượt tra cứu Early Hints. OriginResponseStatus bằng 0 nghĩa là origin chưa từng được liên hệ.

Trong GraphQL Analytics API, sự phân tách đó chính là dimension requestSource. Đây là truy vấn tôi luôn chạy trước khi tin vào bất kỳ đợt tăng vọt 5xx nào:

query ($zone: String!, $since: Time!) {
  viewer {
    zones(filter: { zoneTag: $zone }) {
      httpRequestsAdaptiveGroups(
        limit: 20
        filter: { datetime_geq: $since, edgeResponseStatus: 504 }
        orderBy: [count_DESC]
      ) {
        count
        dimensions { requestSource userAgent clientRequestPath }
      }
    }
  }
}

Nhóm theo User-Agent cũng cho ra cùng một câu chuyện. Vào tháng 9, các lượt tra cứu Early Hints hiện lên dưới dạng bastion early hints và nginx-ssl early hints. Đến tháng 11 thì là fl2 early hints và nginx-ssl early hints (FL2 là thế hệ proxy mới của Cloudflare). Trong 24 giờ, toàn bộ 2.631 lỗi 504 của zone đều đến từ những User-Agent này. Không có lỗi nào đến từ trình duyệt, ứng dụng, curl hay crawler của công cụ tìm kiếm.

Một lỗi 504 thật mà khách truy cập nhìn thấy thì hầu như luôn đến từ phía bạn, sau Cloudflare: một proxy hay load balancer đứng trước ứng dụng đã chờ quá lâu và bỏ cuộc. Đó có thể là nginx, một load balancer trên cloud, hoặc proxy của nền tảng đang chờ một máy đang ngủ khởi động. Các timeout của chính Cloudflare dùng mã khác: 522 nghĩa là không kết nối được tới origin, còn 524 nghĩa là đã kết nối nhưng không nhận được phản hồi trong vòng 125 giây (mặc định trên các gói dưới Enterprise).

Vậy nếu bạn tìm đến đây vì muốn tăng timeout của Cloudflare do lỗi 504: timeout đứng sau một lỗi 504 gần như không bao giờ là của Cloudflare. Hãy kiểm tra proxy_read_timeout trong nginx, idle timeout của load balancer, hoặc thời gian nền tảng của bạn cần để đánh thức một máy. Một manh mối hữu ích: nếu request thất bại ở một con số tròn thấp hơn hẳn 125 giây, như 30 hay 60, thì đó là giới hạn của proxy của bạn, không phải của Cloudflare. (Chỉ gói Enterprise mới nâng được giới hạn 125 giây của Cloudflare, tối đa 6.000 giây, và chính Cloudflare cũng coi đó là giải pháp tạm thời.)

Bản chất thật của những lỗi 504 này

#

Trên một zone đã bật Early Hints, mỗi request tới một trang HTML hoặc một URL không có phần mở rộng (trên một zone nặng về API thì phần lớn lời gọi API đều thuộc diện này) đều kèm thêm một lượt tra cứu nội bộ: Cloudflare kiểm tra cache của chính nó xem có gợi ý nào để gửi không. Lượt tra cứu đó được ghi thành một dòng riêng, với ClientRequestSource = earlyHintsCache. Nó không phải request của người dùng cuối, và không bao giờ được gửi tới origin của bạn.

Mã trạng thái trên dòng đó là kết quả tra cứu cache, không phải lỗi:

• 2xx là hit. Cloudflare có lưu header Link cho URL đó và đã gửi chúng tới trình duyệt dưới dạng 103. Trên zone của tôi, hit xuất hiện dưới cả hai mã 200 và 204.
• 504 là miss. Không có gì được lưu, nên không có gì để gửi sớm.

Nếu origin không bao giờ gửi header mà Early Hints dựa vào, mọi lượt tra cứu đều miss và mọi request đều ghi một dòng 504. Trong ba giờ trước khi tôi thay đổi bất cứ điều gì, zone ghi nhận 173 lượt tra cứu Early Hints và cả 173 đều là miss. Kể từ khi được bật, tính năng này chưa từng gửi đi một gợi ý nào.

Một điều chỉnh cho bài viết tháng 9 của tôi: khi đó tôi mô tả chúng là các probe “không nhận được phản hồi từ origin trên Fly”. Điều đó không hoàn toàn đúng. Chúng hoàn toàn không đi tới origin. Mã 504 ghi lại một lần cache miss, không phải một lần timeout.

Cloudflare có nói ngắn gọn về chuyện này trong tài liệu Early Hints: một lượt tra cứu Early Hints được ghi với ClientRequestSource: earlyHintsCache là “expected and benign” (nằm trong dự kiến và vô hại), 200 là cache hit còn 504 là cache miss, và trong Log Explorer bạn lọc chúng ra bằng ClientRequestSource != "earlyHintsCache". Cache Analytics vốn đã bỏ chúng ra ngoài. Còn biểu đồ lưu lượng HTTP làm tôi hoảng thì không.

Lỗi 504 giả đã khiến tôi nâng cấp máy chủ

#

Đây là lý do việc tách bạch quan trọng. Ngày 3 tháng 11, một ngày trước khi tôi bắt tay vào bài này, Cloudflare ghi nhận 3.292 lỗi 504 trên khoảng 13.300 request của khách truy cập: tỷ lệ lỗi bề ngoài là 25%. API chạy trên máy shared-cpu-1x của Fly.io, loại máy hoạt động theo burst credit: nó chỉ được bảo đảm một phần nhỏ của CPU và phải tiêu credit để chạy nhanh hơn. Một bài kiểm thử tải hồi tháng 8 cho thấy khi tải kéo dài, máy bị bóp xuống khoảng 20 đến 30 request mỗi giây. “Một phần tư số request bị timeout vào giờ cao điểm” trông đúng y như kiểu bóp CPU đó, nên tôi chuyển API sang shared-cpu-2x.

Nhưng tất cả những lỗi 504 đó đều là các lần miss của cache Early Hints. Khi tách theo requestSource và xem lại log của chính origin:

• Mọi lỗi 5xx của Cloudflare từ 28/10 đến 4/11 đều là lượt tra cứu earlyHintsCache, trừ khoảng một lỗi 525 mỗi ngày (lỗi 525 tôi lần ra đến từ một trình quét bảo mật).
• Log truy cập của origin từ 24/10 đến 4/11 không có lỗi 5xx nào, và chỉ có một request chậm hơn 10 giây.
• Số liệu của Fly cho thấy lúc cao nhất cũng chỉ khoảng 7 request mỗi giây, và máy chưa bao giờ dùng quá một phần năm của một lõi CPU. Nó chưa bao giờ tiến gần mức trần bị bóp.

Máy lớn hơn chẳng sửa được gì, vì vốn không có gì hỏng. API đã quay lại shared-cpu-1x.

Đừng ra quyết định về năng lực xử lý dựa trên một biểu đồ 5xx chưa được tách theo request source. Hãy đối chiếu cả với log của chính origin: nếu Cloudflare báo một phần tư số request thất bại mà máy chủ của bạn không ghi nhận lỗi nào, hãy tìm hiểu Cloudflare đang đếm cái gì trước khi động vào máy chủ.

Cập nhật ngày 5/11/2026: phiên bản đầu của phần này viết rằng tuần đó API thực sự đã sập trên shared-cpu-1x. Thực ra không phải vậy. Các số liệu ở trên là những gì tôi tìm thấy khi kiểm tra lại.

HTTP 103 có phải là lỗi không?

#

Không. Các mã trạng thái trong dải 1xx là phản hồi thông tin: những phản hồi tạm thời mà máy chủ có thể gửi trước phản hồi thật. 103 Early Hints, được định nghĩa trong RFC 8297, mang theo header Link để trình duyệt có thể bắt đầu tải CSS, JavaScript và font quan trọng, hoặc mở sẵn kết nối tới các origin khác, trong khi máy chủ vẫn đang dựng trang. Mã 200 cuối cùng sẽ đến sau trên cùng một request.

Mức hỗ trợ không đồng đều nhưng an toàn. Các trình duyệt dựa trên Chromium (Chrome từ phiên bản 103, và Edge) cùng Firefox bản mới xử lý cả gợi ý preload lẫn preconnect. Safari (từ phiên bản 17) chỉ dùng preconnect. Trình duyệt chỉ xử lý 103 qua HTTP/2 và HTTP/3. Trình duyệt nào không hiểu nó thì đơn giản là chờ 200 như mọi khi, nên 103 là một lợi thế xuất phát sớm cho phần lớn khách truy cập và không ảnh hưởng gì tới số còn lại.

Vì sao của tôi trống trơn: header Link so với <link rel=preload>

#

Đây là chỗ tôi mất nhiều thời gian nhất, vì trông nó như thể lẽ ra đã hoạt động rồi.

Early Hints chỉ cache đúng một thứ: response header HTTP Link có quan hệ rel=preload hoặc rel=preconnect. Cloudflare đọc nó từ các phản hồi thông thường của bạn (mã 200, 301 hoặc 302, trên URL HTML hoặc không có phần mở rộng), lưu lại, rồi phát lại cho khách truy cập tiếp theo dưới dạng 103 trước khi phản hồi đầy đủ sẵn sàng.

Các trang của tôi vốn đã có preload, nhưng ở dạng thẻ trong <head> của HTML:

<link rel="preload" href="/_expo/static/css/global-7d77bd.css" as="style">
<link rel="preload" href="/_expo/static/js/web/entry-fd7fa4.js" as="script">
<link rel="preload" href="/fonts/manrope-latin.woff2" as="font" type="font/woff2" crossorigin>

Những thẻ này vẫn có tác dụng: trình duyệt hành động theo chúng. Nhưng trình duyệt chỉ thấy chúng sau khi đã nhận HTML và bắt đầu phân tích, mà đó lại chính là khoảnh khắc Early Hints muốn đi trước. Bản export của Expo và theme Hugo tôi dùng đều tự viết các thẻ này, nhưng không cái nào đặt header. Vậy là tính năng đã bật, preload cũng đã khai báo, nhưng hai thứ chưa bao giờ gặp nhau.

Cách sửa: gửi header từ dữ liệu bạn vốn đã có

#

Cách sạch nhất không phải là tự tay duy trì một danh sách tài nguyên quan trọng, thứ sẽ lỗi thời mỗi khi hash của bundle thay đổi. Mỗi trang đã tự khai báo những gì nó muốn preload, trong chính các thẻ đó. Vậy chỉ cần chép chúng sang header Link khi phục vụ trang. html.parser trong thư viện chuẩn xử lý được cả thuộc tính có và không có dấu ngoặc kép (minifier của Hugo bỏ dấu ngoặc đi), nên không có regex nào để viết sai:

from html.parser import HTMLParser


class PreloadLinks(HTMLParser):
    def __init__(self):
        super().__init__()
        self.hints = []

    def handle_starttag(self, tag, attrs):
        a = dict(attrs)
        if tag != "link" or "preload" not in (a.get("rel") or "").split() or not a.get("href"):
            return
        hint = f"<{a['href']}>; rel=preload"
        if a.get("as"):
            hint += f"; as={a['as']}"
        if a.get("as") == "font" or "crossorigin" in a:
            hint += "; crossorigin"
        self.hints.append(hint)


def link_header(html: str, limit: int = 12) -> str | None:
    parser = PreloadLinks()
    parser.feed(html)
    return ", ".join(list(dict.fromkeys(parser.hints))[:limit]) or None

Và gắn nó vào phản hồi HTML trong Django:

response = HttpResponse(html, content_type="text/html")
if (link := link_header(html)) and "Link" not in response:
    response["Link"] = link

Có một chi tiết đã làm tôi vấp, và đáng để nhớ: giữ crossorigin cho font. Một preload font thiếu nó sẽ bị coi là một request khác, font bị tải về hai lần, và trang chậm đi chứ không nhanh hơn.

Bạn không cần tự viết 103. Không có đoạn mã phản hồi tạm thời nào phải thêm vào ASGI, Granian hay uvicorn. Cloudflare dựng 103 từ header của bạn; việc duy nhất của bạn là gửi header đó.

Trên các stack khác

#

Quy tắc ở đâu cũng vậy: đặt header Link lên phản hồi HTML và để Cloudflare lo phần còn lại.

• nginx, trong location phục vụ HTML:

  location = / {
      add_header Link "</css/app.css>; rel=preload; as=style" always;
      add_header Link "</fonts/inter.woff2>; rel=preload; as=font; crossorigin" always;
  }

• Laravel dùng Vite đã có sẵn middleware cho việc này, AddLinkHeadersForPreloadedAssets, chuyển các preload của Vite thành header Link. Hai vấn đề từng được báo cáo với nó cũng chính là những cái bẫy ở trên: các gợi ý modulepreload của nó từng được gửi đi mà không có crossorigin, khiến trình duyệt có thể bỏ qua chúng và tải script hai lần, và trên các trang lớn, header từng vượt quá giới hạn header khoảng 8 KB của Apache. Hãy kiểm tra cả hai trên phiên bản bạn đang dùng.

• Mọi môi trường khác: dùng một header Link phân tách bằng dấu phẩy, hoặc gửi nhiều header Link. Cách nào cũng được.

Chỗ mọi người hay làm quá tay là chọn gợi ý những gì. Chỉ gợi ý CSS quan trọng cho việc render, script đầu vào và một hai font dùng ở màn hình đầu tiên, đừng nhét mọi chunk vào. Danh sách dài khiến trình duyệt đi tải những thứ chưa cần trước cả những thứ đang cần. Tôi giới hạn ở mười hai mục, và đó là vì bản export của Expo đã chọn lọc sẵn danh sách preload.

Nếu bạn không đứng sau Cloudflare, hoặc CDN của bạn không hỗ trợ Early Hints, header Link vẫn giúp được một chút: trình duyệt có thể bắt đầu tải các tài nguyên đó ngay khi header phản hồi tới nơi, trước khi phân tích phần thân. Nhưng sẽ không có 103 nào trừ khi máy chủ hoặc CDN của bạn tự gửi.

Cách kiểm tra xem nó đã hoạt động chưa

#

curl cho bạn thấy 103 trực tiếp. Gửi request bằng HTTP/2 và chỉ giữ lại các dòng trạng thái cùng header Link:

$ curl -sv --http2 -o /dev/null https://example.com/register 2>&1 | grep -E '^< (HTTP|link)'
< HTTP/2 103
< link: </_expo/static/css/reset-f5d396.css>; as=style; rel=preload, …
< HTTP/2 200
< link: </_expo/static/css/reset-f5d396.css>; rel=preload; as=style, …

103 đến trước, rồi mới tới 200. Cloudflare sắp xếp lại thứ tự các thuộc tính trong gợi ý, điều này vô hại. Đừng kỳ vọng mọi request đều nhận được 103. Trong ba lần đầu của tôi, chỉ có hai lần nhận được. Lần truy cập đầu tiên sau khi thay đổi chỉ lưu header lại, và Cloudflare bỏ qua 103 khi header của phản hồi cuối cùng đã sẵn sàng.

Sau đó quay lại truy vấn phân tích ở trên, lọc theo requestSource: "earlyHintsCache", nhóm theo mã trạng thái và đường dẫn. Trên những trang bạn đã sửa, hit sẽ dần thay thế miss.

Điều gì đã thay đổi, và điều gì còn lại

#

Vài phút sau khi header được đưa lên production, zone ghi nhận những lần hit Early Hints đầu tiên trong lịch sử, và curl cho thấy phản hồi 103 thật trên các trang web. Một header giải quyết cùng lúc hai vấn đề: tính năng bắt đầu hoạt động, và một phần các “lỗi 504” biến mất.

Điều còn lại là một JSON API chẳng có gì để preload. Các endpoint API tiếp tục miss và tiếp tục ghi các dòng 504, và trên một zone nặng về API thì phần này vẫn chiếm đa số. Bạn có ba lựa chọn hợp lý. Gửi header trên những trang có lợi và chấp nhận các đường dẫn API tiếp tục ghi miss; tính năng hoạt động, các biểu đồ yên tĩnh hơn nhưng không hoàn toàn im lặng. Loại earlyHintsCache khỏi cảnh báo 5xx và dashboard, dù bạn quyết định gì đi nữa, vì một lượt tra cứu cache nội bộ không bao giờ nên đánh thức ai dậy. Hoặc tắt Early Hints (Speed → Settings → Content Optimization trong dashboard, hoặc thiết lập early_hints của zone qua API) nếu bạn sẽ không bao giờ gửi header Link; một ứng dụng một trang có HTML rất nhỏ có thể không được lợi gì nhiều, và khi tắt thì mọi lượt tra cứu dừng lại, tiếng ồn cũng biến mất theo.

Tôi giữ nó bật. Các trang web giờ đã được xuất phát sớm hơn, các lần miss của API đã bị lọc khỏi mọi thứ có thể kích hoạt cảnh báo, và đó mới là điều lẽ ra tôi phải làm vào tháng 9 thay vì tắt tính năng đi.

Nếu bạn vào đây để tìm cách chạy Docker Compose trong GitHub Actions: tôi đã làm thế suốt hai năm rồi bỏ. Giờ CI khai báo cùng các image Postgres và Valkey đó dưới dạng services: và chạy thẳng trên runner đúng các lệnh uv run … và npm run …; Compose quay về làm thứ lập trình viên chạy ở máy mình. Phần còn lại là lý do, kèm các tệp.

Năm 2024 tôi có viết bài Dùng Docker Compose cho CI/CD thay vì YAML riêng của từng nền tảng, với ý chính là để logic dựng trong Compose, còn công cụ CI chỉ việc gọi nó. Hai năm sau, tôi xem lại toàn bộ các kho mã mà tôi đang dùng để phát hành. Có bốn kho có workflow, kho nào cũng chỉ có một người commit là tôi, và trong số các workflow đó không còn cái nào gọi docker compose nữa. Nguyên tắc thì vẫn đứng vững, còn cách làm thì không. Dưới đây là những thứ đã thay thế nó: phiên bản ví dụ đã cắt gọn của các tệp, thời gian từng bước mà GitHub ghi lại, và cả những phần ít tự động hơn so với mong đợi của mấy sơ đồ CI/CD.

Mọi quy trình tôi đang chạy, gói trong một bảng

#

Nói theo sách vở thì hai trang Hugo là triển khai liên tục, còn ứng dụng kia (một ứng dụng chợ kiêm cộng đồng mà tôi đang làm) là tích hợp liên tục cộng với phát hành bằng đúng một lệnh, tức là chuyển giao liên tục: phần kiểm tra báo cho tôi biết khi có gì sai, nhưng không chặn tôi triển khai. Tôi cố ý chia như vậy. Một bản cập nhật OTA sẽ đến mọi điện thoại đang dùng phiên bản ứng dụng mà nó nhắm tới, nên việc phát hành phải là một quyết định, chứ không phải tác dụng phụ của một lần merge. Còn API là nơi chạy migration cơ sở dữ liệu. Hai ứng dụng Django còn lại của tôi thì hoàn toàn không có workflow nào.

Phần CI: một workflow, hai job

#

Toàn bộ CI của ứng dụng nằm trong một tệp, .github/workflows/checks.yml. Trước ngày 11 tháng 10, ngay cả tệp này cũng chưa có. Đây là một ví dụ đã cắt gọn cho thấy hình dạng của nó:

# Lint, types and tests on every push and pull request to main.
# Nothing here deploys.
name: Checks

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: checks-${{ github.ref }}
  cancel-in-progress: true

jobs:
  python:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_USER: myapp
          POSTGRES_PASSWORD: myapp
          POSTGRES_DB: myapp
        ports: ["5432:5432"]
        options: >-
          --health-cmd "pg_isready -U myapp"
          --health-interval 5s --health-timeout 5s --health-retries 20
      valkey:
        image: valkey/valkey:8-alpine
        ports: ["6379:6379"]
    env:
      DEBUG: "True"
      DATABASE_URL: postgresql://myapp:myapp@localhost:5432/myapp
      REDIS_URL: redis://localhost:6379
      PYTHON_JIT: "0"   # match production
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10
        with:
          enable-cache: true
          prune-cache: true
      - run: uv sync --locked
      - run: uv run ruff check .
      - run: uv run mypy myapp/
      - run: uv run python manage.py test --parallel 4 --noinput

  app:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults:
      run:
        working-directory: frontend
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: frontend/package-lock.json
      - run: npm ci
      # Expo writes this on `expo start` and it is gitignored,
      # so a fresh checkout doesn't have it.
      - run: printf '/// <reference types="expo/types" />\n' > expo-env.d.ts
      - run: npm run typecheck
      - run: npx jest --ci

Hai job chạy song song. Trong 35 lần chạy thành công tính đến giờ, trung vị của job ứng dụng là khoảng bảy phút, còn job Python là khoảng mười hai phút rưỡi.

Khối services: chính là chỗ tệp Compose đã chuyển tới, phần sau sẽ nói rõ. Môi trường chỉ có vài biến và một cờ. Mọi thứ còn lại đều rơi về giá trị mặc định cho môi trường phát triển mà lập trình viên có được khi chạy docker compose up, nên bộ kiểm thử không cần bí mật (secret) nào. Để chắc chắn, tôi đã chạy thử một phần bộ kiểm thử với đúng môi trường đó và không có gì khác.

CI chạy cùng trình thông dịch với laptop của tôi và với image production, tức là bản Python 3.15.0 do chính uv dựng, vì uv sync đọc .python-version và tải về đúng bản đó. (Tệp thật của tôi còn truyền cho setup-uv một tham số python-version-file, thật ra chẳng làm gì cả: setup-uv v6 không có tham số nào như vậy, và lần chạy nào cũng kèm một cảnh báo nói đúng điều đó. Viết bài này tôi mới để ý.)

Việc dùng chung trình thông dịch đã chứng minh giá trị chỉ tám ngày sau khi workflow ra đời. Ngày 19 tháng 10, tôi bật trình biên dịch JIT của 3.15, và ngay lần chạy đầu tiên có JIT, một bài kiểm thử đã thất bại: một câu yield from rất bình thường, nằm trên đoạn code mà lần lưu dữ liệu nào của ứng dụng cũng đi qua, lại ném ra AttributeError: 'list' object has no attribute 'send'. Cùng commit đó mà tắt JIT thì qua. Máy Mac của tôi là arm64 nên chưa bao giờ gặp lỗi này; còn máy chạy CI (runner) là x86_64, giống các máy production. JIT giờ đã được tắt lại, cả trong CI lẫn trong Dockerfile, và lỗi này chưa bao giờ lọt lên production. Đó là lỗi python/cpython#155823, đã được sửa ở upstream vào ngày 13 tháng 10, sau khi 3.15.0 phát hành.

Thật ra ngay lần chạy đầu tiên cũng đã thất bại, nhưng vì một lý do tẻ nhạt hơn. Expo tạo tệp expo-env.d.ts khi bạn chạy expo start, mà tệp này lại nằm trong gitignore. Vì vậy bản làm việc nào tôi từng dùng cũng có nó, còn một bản checkout mới tinh thì không. TypeScript báo năm lỗi chưa từng xuất hiện trên máy tôi. Bước tạo tệp đó chính là cách sửa.

concurrency sẽ hủy lần chạy cũ khi có một lần push mới hơn lên cùng nhánh. Cả mười hai lần chạy bị hủy tính đến giờ đều kết thúc theo cách này. Một hook trước commit (pre-commit) chạy công cụ lint, và chạy thêm bộ kiểm tra kiểu khi có tệp Python hoặc TypeScript được stage, nên phần lớn lỗi không đi được tới lúc push.

Tệp Docker Compose đã đi đâu

#

Đây là phần trong tệp docker-compose.yml của ứng dụng mà CI quan tâm, viết lại dưới dạng ví dụ. Tệp thật còn nhiều dịch vụ hơn và nhiều biến môi trường hơn hẳn.

services:
  valkey:
    image: valkey/valkey:8-alpine
    ports:
      - "6379:6379"

  # Host port 55432, not 5432, so it can't collide with a local Postgres.
  postgres:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=myapp
      - POSTGRES_PASSWORD=myapp
      - POSTGRES_DB=myapp
    ports:
      - "55432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp -d myapp"]
      interval: 5s
      retries: 10

  api:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://myapp:myapp@postgres:5432/myapp
      - REDIS_URL=redis://valkey:6379
    depends_on:
      postgres:
        condition: service_healthy
      valkey:
        condition: service_started

volumes:
  postgres_data:

Đặt nó cạnh khối services: trong checks.yml thì thấy đó là cùng hai image: Postgres 17 (ở đây là bản Alpine, trong CI là bản Debian) và valkey/valkey:8-alpine. Quan hệ giữa hai bên bây giờ là vậy. Tệp Compose là thứ lập trình viên chạy; còn CI khai báo cùng các image đó dưới dạng service container, rồi chạy thẳng trên runner đúng những lệnh mà lập trình viên vẫn chạy, uv run … và npm run ….

So với bài năm 2024, phần tôi quan tâm nhất vẫn đứng vững: công cụ CI vẫn mỏng, và các bước kiểm tra lẫn triển khai đều là những lệnh tôi tự chạy được. Thứ không trụ lại được là để CI gọi Compose.

CI của ứng dụng hoàn toàn không dựng Docker image. Image được dựng đúng một lần, lúc triển khai, trên máy dựng (builder) của Fly, còn CI chỉ cần trả lời code có ổn không, và khi bộ công cụ đã có sẵn trong bộ nhớ đệm (cache) thì việc đó chỉ tốn sáu giây cài đặt. Ngoài ra, tệp Compose còn bind-mount bản làm việc và nạp dữ liệu mẫu, những việc một lần chạy kiểm thử không nên làm. Vậy nên CI sẽ cần một tệp Compose riêng, tức là một bản mô tả thứ hai cho cùng các dịch vụ, phải giữ cho khớp nhau bằng tay.

Thêm nữa, ví dụ năm 2024 có một lỗi mà lúc đó tôi không để ý. docker compose build chỉ dựng image, chứ không bao giờ chạy command của dịch vụ. Thế nên lệnh npm test trong tệp đó chưa từng chạy trong CI, và workflow vẫn xanh dù kiểm thử có qua hay không.

Rủi ro mà bài đó lo nhất, tức là đổi nhà cung cấp CI, rốt cuộc chưa bao giờ xảy ra. Cuộc chuyển dịch thật sự lại diễn ra ở đầu bên kia: blog này và trang của khách hàng kia đã đổi nơi lưu trữ sang Cloudflare Pages, và với blog thì chỉ cần viết mới một workflow dài 45 dòng, vì khâu dựng vốn đã chỉ là một lệnh. Còn cái workflow ba trăm dòng mà tôi từng cảnh báo? Tôi có đúng một cái, của pyhtml2text. Nó dài vì wheel phải được dựng trên runner Linux, macOS và Windows, mỗi loại cho nhiều kiến trúc, và cũng vì vậy mà đây là việc duy nhất mà YAML riêng của nền tảng là công cụ đúng.

Bộ nhớ đệm: đọc thời gian từng bước trước đã

#

GitHub ghi lại thời gian của từng bước, và gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobs sẽ trả về cho bạn. Đây là số liệu từ lần chạy thành công gần nhất của ứng dụng, ngày 20 tháng 10:

Cả hai bộ nhớ đệm cho thư viện phụ thuộc đều đang bật, và cả hai đều là phần rẻ. Bộ nhớ đệm uv mà GitHub giữ cho kho này chỉ khoảng 200 KB, vì setup-uv dọn đi những gì uv chỉ cần tải lại là xong; còn của npm thì gần 400 MB. Thời gian nằm ở bộ kiểm thử, mà bộ kiểm thử thì đã chạy song song bốn luồng rồi. Muốn chạy nhanh hơn, tôi sẽ sửa bộ kiểm thử chứ không phải bộ nhớ đệm.

Blog thì ngược lại. Ảnh đã được Hugo xử lý nằm trong thư mục resources/_gen vốn bị gitignore, nên runner mới nào cũng phải mã hóa lại toàn bộ ảnh bìa, ảnh trong bài và ảnh giữ chỗ. Workflow ở phía dưới khôi phục chúng bằng actions/cache, với khóa là mã băm của chính các bức ảnh; nếu khóa không khớp thì dùng bản cache cũ mới nhất, vì Hugo chỉ xử lý phần còn thiếu. Trong tám lần chạy cuối cùng trước khi có cache, bước dựng mất từ 33 đến 76 giây; trong 26 lần kể từ đó là 6 đến 20 giây, chỉ một lần ngoại lệ là 94 giây, dù chính commit đó còn thêm ảnh giữ chỗ và một cỡ thẻ thứ hai.

Image của ứng dụng được dựng trên builder của Fly: các tệp khai báo thư viện phụ thuộc được chép vào trước code, còn bộ nhớ đệm tải về của uv nằm trong một cache mount của BuildKit (RUN --mount=type=cache,target=/root/.cache/uv). Nhưng cải thiện lớn nhất ở đây lại không phải là bộ nhớ đệm. Tệp .dockerignore cũ là danh sách chặn (blocklist), và nó bỏ sót một thư mục chứa các git worktree phụ, mỗi worktree lại có thư viện phụ thuộc và sản phẩm dựng của riêng nó. Kết quả là 7,7 GB với 277.000 tệp bị đẩy lên builder mỗi lần triển khai. Viết lại thành danh sách cho phép (allowlist), ngữ cảnh dựng giờ chỉ còn khoảng 40 MB. Một ví dụ cho cách làm này:

# Exclude everything, then let back in only what the Dockerfile COPYs.
*

!pyproject.toml
!uv.lock
!manage.py
!myapp
!static

# Rules match the whole relative path and the last match wins,
# so these re-excludes apply inside the allowed directories too.
**/__pycache__/
**/*.pyc
**/.DS_Store
**/*.log

Bí mật, đặt ở càng ít chỗ càng tốt

#

Bí mật nằm ở ba nơi. Bí mật của GitHub Actions dành cho những việc workflow làm, và hai kho Hugo mỗi kho chỉ có đúng một cái, CLOUDFLARE_API_TOKEN. Bí mật của Fly là cấu hình lúc chạy của ứng dụng, được đặt bằng flyctl secrets set, và không bao giờ đi qua Actions. Cuối cùng là tệp .env bị gitignore trên laptop của tôi, chứa token mà script triển khai dùng để xóa cache của Cloudflare.

PyPI thì hoàn toàn không cần bí mật. pyhtml2text dùng cơ chế trusted publishing: PyPI chấp nhận token OIDC ngắn hạn mà GitHub cấp cho workflow, nên job phát hành chỉ xin quyền id-token: write, và trang bí mật của kho thì trống trơn. Không có gì để rò rỉ, cũng không có gì phải xoay vòng.

Token chỉ được cấp đúng quyền cần thiết. Token Fly của ứng dụng trên GitHub phục vụ một bước kiểm tra định kỳ chỉ liệt kê máy, nên nó được tạo bằng fly tokens create readonly. Các lần triển khai lên Pages chỉ xin contents: read và deployments: write, không hơn.

Dữ liệu đầu vào luôn đi qua env:, không bao giờ nhét thẳng vào script. Workflow OTA nhận ghi chú phát hành dạng văn bản tự do. Nếu viết ${{ inputs.notes }} ngay trong run:, đoạn văn bản sẽ được dán thẳng vào script trước khi bash đọc, nên một ghi chú có dấu nháy và dấu chấm phẩy sẽ biến thành code. Truyền qua biến môi trường thì nó vẫn chỉ là dữ liệu. Một ví dụ cho cách làm này:

      - name: Publish
        env:
          OTA_API_TOKEN: ${{ secrets.OTA_API_TOKEN }}
          INPUT_PLATFORM: ${{ inputs.platform }}
          INPUT_ROLLOUT: ${{ inputs.rollout }}
          INPUT_NOTES: ${{ inputs.notes }}
        run: |
          args=("$INPUT_PLATFORM")
          [ -n "$INPUT_ROLLOUT" ] && args+=(--rollout "$INPUT_ROLLOUT")
          [ -n "$INPUT_NOTES" ] && args+=(--notes "$INPUT_NOTES")
          ./scripts/publish-ota.sh "${args[@]}"

Có những khóa tôi để hẳn bên ngoài GitHub. Một bản báo cáo định kỳ cần một khóa có quyền quản trị phần đăng nhập của ứng dụng, nên nó đã chuyển từ một workflow định kỳ sang một tác vụ định kỳ trên máy Mac của tôi. Workflow vẫn còn đó làm phương án dự phòng chạy tay, và bỏ qua những mục cần đến khóa đó.

Triển khai: mỗi lần push, bằng script, và theo tag

#

Các trang Hugo được triển khai mỗi lần push

#

Đây là phiên bản ví dụ của workflow cho blog, đã lược bỏ bước tạo dự án Pages ở lần chạy đầu tiên:

name: Deploy to Cloudflare Pages

on:
  push:
  workflow_dispatch:

env:
  HUGO_VERSION: "0.165.0"
  PAGES_PROJECT: my-site

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v7
        with:
          submodules: true

      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      # Processed images are gitignored; restore them so Hugo only
      # re-encodes what is new. An older cache still helps.
      - uses: actions/cache@v6
        with:
          path: resources/_gen
          key: hugo-resources-${{ hashFiles('content/**/*.jpg', 'content/**/*.png', 'assets/img/**') }}
          restore-keys: |
            hugo-resources-

      # A multilingual site has no root 404.html; without one, Pages
      # answers unknown paths with index.html and a 200.
      - name: Build
        run: |
          hugo --gc
          cp public/en/404.html public/404.html

      # ...

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy public --project-name=${{ env.PAGES_PROJECT }} --branch=${{ github.ref_name }}

--branch=${{ github.ref_name }} làm cho main thành production và cho mọi nhánh khác một URL xem trước. Workflow cho trang của khách hàng có cùng cấu trúc, chỉ thêm một dòng rm -rf public trước khi dựng, vì bên đó thư mục public/ được commit, nếu không thì các trang đã xóa sẽ cứ nằm lại trong bản tải lên.

Phiên bản Hugo chỉ được ghim ở đây, không ở đâu khác. Tháng 10, một lần cập nhật của trình quản lý gói đã nâng Hugo trên laptop của tôi lên 0.168, cao hơn một bậc so với bản mới nhất mà theme hỗ trợ. Các lần triển khai vẫn ở 0.165 và chẳng hề hấn gì.

Và bước dựng chính là bài kiểm thử. Ngày 14 tháng 9, bản triển khai xem trước của một nhánh thất bại ba lần liên tiếp: một bài viết trên nhánh đó dùng ref của Hugo để liên kết tới một bài vẫn còn là bản nháp. CI dựng đúng như production dựng, tức là bỏ bản nháp ra, nên liên kết trỏ vào hư không và Hugo dừng lại với lỗi REF_NOT_FOUND. Trong lúc đó, main vẫn triển khai bình thường.

API của ứng dụng được triển khai bằng script

#

Phần cốt lõi của script triển khai, viết dưới dạng ví dụ:

IMAGE_LABEL="deploy-$(git rev-parse --short HEAD)-$(date +%Y%m%d%H%M%S)"

# Build first, then wake a spare machine, then roll out exactly that image.
flyctl deploy --config fly.toml --build-only --push --image-label "$IMAGE_LABEL"
curl -fsS --retry 5 https://myapp.fly.dev/health > /dev/null
flyctl deploy --config fly.toml --image "registry.fly.io/myapp:$IMAGE_LABEL"

Và các dòng tương ứng trong fly.toml:

[deploy]
  # max_unavailable only counts machines that are running,
  # which is why the script wakes one first.
  strategy = "rolling"
  max_unavailable = 1

Image được dựng đúng một lần, đẩy lên registry của Fly với một nhãn ghép từ commit và thời điểm, rồi được triển khai theo đúng nhãn đó, nên thứ được tung ra chính xác là thứ đã được dựng.

Thứ giúp triển khai không gián đoạn (zero-downtime) là việc đánh thức một máy dự phòng trước. max_unavailable = 1 chỉ đếm những máy đang chạy, mà ứng dụng lại không giữ máy nào chạy khi rảnh (một máy đang tạm dừng chỉ mất khoảng một giây để tỉnh lại). Vì vậy, trước đây cái máy duy nhất đang thức bị thay cùng đợt với các máy đang ngủ, và đằng sau nó không còn máy nào sẵn sàng. Ngày 28 tháng 9, tôi cho một đầu dò gửi yêu cầu liên tục tới origin: khi chạy flyctl deploy trơn thì có 7 lần hết thời gian chờ và một khoảng trống 7,3 giây, còn với script triển khai, vốn dựng trước và có sẵn một máy đang thức trước khi bắt đầu tung ra, thì không có lỗi nào trong 2.514 yêu cầu.

Phần còn lại của script đánh dấu lần triển khai trên kênh chat của đội, nơi các cảnh báo lỗi gửi về, để khi lỗi dồn dập thì có thể đối chiếu với thứ vừa thay đổi, rồi xóa cache Cloudflare và làm nóng các máy. Giao diện web thì hoàn toàn không đi qua image; chuyện đó tôi đã viết trong Triển khai frontend và backend riêng biệt, không cần triển khai lại API.

Migration không phải là một bước trong quy trình. release_command của Fly bị treo trong trường hợp của tôi, nên máy đầu tiên khởi động với image mới sẽ giữ khóa và chạy migration, trong khi các máy khác chờ. Vì thế, migration nào cũng phải tương thích với code vẫn đang chạy: thêm cột ở lần triển khai này, ngừng dùng nó ở lần sau, và xóa nó ở lần thứ ba.

Script này không có chỗ nào bắt buộc phải là laptop của tôi, nhưng có vài tệp chỉ nằm trên máy đang giữ nó ở đó: thông tin đăng nhập Cloudflare, và một bản ghi về thứ đã được triển khai lần gần nhất, thứ mà một runner mới tinh sẽ không có. Nó còn triển khai cả những thay đổi chưa commit, và có báo điều đó trên kênh chat, trong khi script phát hành web thì từ chối một cây làm việc chưa sạch.

Trong bài Môi trường xem trước cho từng nhánh, tôi viết rằng làm những việc này bằng tay thì ổn khi chỉ có một mình bạn làm, nhưng từ lập trình viên thứ hai trở đi thì nó phải xảy ra vì có gì đó xảy ra trong git. Ứng dụng vẫn chỉ có một lập trình viên. Các workflow môi trường theo nhánh trong bài đó vẫn nằm trên chính nhánh mà tôi đã dựng chúng.

Workflow OTA chỉ chạy tay, vì việc phát hành phải là một quyết định, và vì dịch vụ cập nhật từ chối bản phát hành mới khi đang có một đợt tung ra từng phần (partial rollout) còn mở, nên nếu kích hoạt theo push thì đợt canary nào cũng sẽ vướng. Workflow này chưa từng chạy lần nào. Mọi bản cập nhật OTA cho đến nay đều được đẩy đi từ laptop của tôi, qua chính script mà workflow gọi. Lý do nên giữ workflow mỏng gói gọn trong một câu: phát hành bắt đầu bằng cách nào thì cũng là cùng một script.

pyhtml2text phát hành theo tag

#

Job phát hành, với tên gói đã được đổi thành tên chung chung:

  release:
    runs-on: ubuntu-latest
    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
    needs: [linux, macos, windows, sdist]
    environment:
      name: pypi
      url: https://pypi.org/p/mypackage
    permissions:
      id-token: write       # trusted publishing and signing
      contents: write
      attestations: write
    steps:
      - uses: actions/download-artifact@v8
      - uses: actions/attest@v4
        with:
          subject-path: 'wheels-*/*'
      - uses: astral-sh/setup-uv@v10
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        with:
          prune-cache: true
      - name: Publish to PyPI
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        run: uv publish --trusted-publishing always 'wheels-*/*'

Job phát hành chờ mọi job dựng xong, và chỉ khi có tag mới thật sự xuất bản; chạy tay thì chỉ dựng và tạo chứng thực (attestation) chứ không tải gì lên. actions/attest ghi lại workflow nào đã dựng từng wheel, còn uv publish --trusted-publishing always tải chúng lên bằng token OIDC thay vì mật khẩu. Bản thân gói thư viện này tôi đã viết trong Một pull request bị đóng, một bản fork và một gói PyPI.

Workflow định kỳ chỉ là “cố gắng hết sức”

#

Ứng dụng có một workflow chạy định kỳ, kiểm tra xem Fly có bật nhiều máy hơn mức cơ bản hay không, chuyện mà nếu không kiểm tra thì sẽ chỉ lộ ra trên hóa đơn. Nó cảnh báo bằng cách cố ý thất bại, vì GitHub sẽ gửi email cho chủ kho khi một lần chạy định kỳ thất bại.

Lịch được đặt là cron: '*/15 * * * *', tức 96 lần một ngày. Vậy mà trong hai tuần qua, mỗi ngày nó chỉ chạy từ ba đến tám lần, với khoảng cách trung vị giữa các lần chạy khoảng ba tiếng bốn mươi phút. Lời giải thích duy nhất trong tài liệu của GitHub là tải: lần chạy định kỳ có thể bị trễ khi Actions bận, và bị bỏ qua khi bận đến một mức nào đó. Với một đợt mở rộng quy mô kéo dài, vài tiếng là đủ. Còn với thứ gì cần báo trong vòng vài phút, cron của GitHub không phải là công cụ giám sát.

Những câu tôi sẽ hỏi về một quy trình CI/CD

#

Dù bạn đang dựng một quy trình mới hay xem lại quy trình đang có:

1. Nếu GitHub Actions ngừng hoạt động cả một ngày, bạn có còn phát hành được không? Nếu không, logic phát hành của bạn đang nằm trong YAML, và bài năm 2024 vẫn còn đúng.
2. CI có chạy cùng trình thông dịch, cùng kiến trúc CPU và cùng phiên bản chính của cơ sở dữ liệu với production không? CI của tôi bắt được một lỗi trình biên dịch chỉ vì runner và production đều là x86_64, còn laptop của tôi thì không.
3. Một bản checkout mới tinh có qua được không? Nếu không, thủ phạm thường là các tệp được sinh tự động và bị gitignore.
4. Thời gian của một lần chạy thật ra tiêu vào đâu? Hãy đọc thời gian từng bước trước khi thêm bộ nhớ đệm.
5. Mỗi bí mật đang nằm ở bao nhiêu chỗ, và nó có thật sự cần nằm trên GitHub không?

Không có APM thuê ngoài, không có truy vết (tracing) trên production, cũng không có bảng điều khiển (dashboard) nào mà tôi phải nhớ để mở ra xem. Thứ duy nhất tốn thêm tiền là kho nhật ký, khoảng 2 đô la Mỹ mỗi tháng. Dưới đây là danh sách đầy đủ, cùng những thứ tôi đã bỏ hoặc thôi tin tưởng, trong đó có một thứ khiến tôi mất mấy ngày đuổi theo một sự cố mà chưa từng có người dùng nào gặp phải.

Giám sát ở đây nghĩa là gì, và quy mô nhỏ đến mức nào

#

Khi nói giám sát DevOps, ý tôi là hai việc: biết có gì đó hỏng trước khi có người báo cho mình, và tìm ra nguyên nhân mà không phải đoán mò. Mọi công cụ dưới đây đều được đánh giá theo đúng hai tiêu chí đó.

Năm ngoái tôi có viết bài Dựng hệ thống giám sát mà lập trình viên thật sự dùng tới, chủ yếu nghĩ cho các đội: đội nhỏ thì dùng công cụ giám sát có sẵn của nhà cung cấp đám mây, khi đã có hàng trăm dịch vụ thì dùng một APM thuê ngoài. Bài này là đầu nhỏ nhất của cùng một cách nghĩ. Cả hai sản phẩm đều là Django chạy trên máy shared-cpu-1x của Fly, như tôi đã kể trong Bộ công nghệ hiện tại của tôi, và cả hai đều chỉ có một lập trình viên là tôi. Nếu coi giám sát là một sản phẩm và lập trình viên là người dùng của nó, thì hệ thống của tôi chỉ có đúng một người dùng: người đọc cảnh báo cũng chính là người sửa lỗi. Khi tôi lấy số liệu nền từ chỉ số của Fly vào tháng Chín, API của sàn giao dịch dùng trung bình 1% CPU. Đây không phải bộ công nghệ cho doanh nghiệp lớn, và tôi cũng không định tô vẽ nó thành như vậy.

Trong ba trụ cột quen thuộc là chỉ số, nhật ký và truy vết, tôi có hai. Cả hai sản phẩm đều không có truy vết phân tán (distributed tracing), vì mỗi sản phẩm chỉ là một codebase Django và một cơ sở dữ liệu, không có ranh giới dịch vụ nào để một trace phải đi qua. Dữ liệu truy vết duy nhất tôi xem là của reverse proxy trên máy trạm của tôi.

Danh sách

#

Những dòng không ghi “cả hai ứng dụng” đều là của sàn giao dịch. Ứng dụng báo giá có ít hơn: health check, nhật ký và chỉ số của Fly, phân tích ứng dụng trên iOS, và một tác vụ xuất cơ sở dữ liệu ra tệp Parquet mỗi ngày để tôi truy vấn bằng DuckDB. Nó chưa có báo cáo crash, cũng chưa có kênh cảnh báo, và đó là chỗ hổng lớn nhất trong bài này. (Xin nói rõ về dòng dịch vụ cập nhật: công ty làm ra dịch vụ đó trả tiền cho tôi để viết bài trên blog của họ.)

Lỗi: một logging handler gửi vào kênh chat

#

Trước tháng Chín, một lỗi 500 chưa được xử lý, một thông báo đẩy (push notification) gửi thất bại hay một frame WebSocket bị hỏng chỉ xuất hiện ở đúng một chỗ là flyctl logs, mà luồng đó thì chẳng ai tự giác ngồi đọc. Giờ đây một logging handler gửi mọi bản ghi từ mức ERROR trở lên vào một kênh chat, dù nó đến từ API, máy chủ WebSocket hay worker chạy nền. Cảnh báo mức WARNING thì tôi cố ý không gửi.

Handler gửi tin từ một luồng nền, nên không bao giờ làm chậm một yêu cầu. Bên trong nó không ghi nhật ký gì, nên không thể tự gọi đệ quy. Và cùng một lỗi chỉ được gửi tối đa mười phút một lần, giới hạn 30 cảnh báo mỗi giờ, nên khi có sự cố bạn chỉ đọc một tin nhắn chứ không phải một nghìn.

Kênh này cũng chứa những thứ tôi muốn đặt cạnh lỗi để đối chiếu: các lần triển khai đều báo lúc bắt đầu, lúc chạy xong và chỗ bị hỏng, kèm commit và người chạy; các bản cập nhật OTA và các lần phát hành giao diện web cũng vậy. Khi một tài khoản bị nhập sai mã đăng nhập dồn dập, hệ thống cũng ghi ở mức ERROR, nên ai đó đang dò mã sẽ hiện ra ngay cạnh các sự cố.

Hồi tháng Mười có một cảnh báo đến mà không khớp với dòng nào trong bất kỳ nhật ký nào. Từ đó, mỗi cảnh báo mang theo một id ngẫu nhiên ngắn, tên máy và lệnh khởi động tiến trình, đồng thời ghi đúng dòng đó vào nhật ký của tiến trình. Nếu tôi không tìm thấy id ở đâu cả, thì cảnh báo đến từ một tiến trình không ghi nhật ký vào đó, chẳng hạn một phiên SSH. Mọi thứ vào kênh cũng được đẩy vào một luồng dữ liệu mà agent lập trình tôi làm việc cùng đọc được, nên agent đang làm việc với code cũng thấy lỗi cùng lúc với tôi.

Nhật ký: log shipper của Fly đẩy lên S3, truy vấn bằng DuckDB

#

Bộ đệm nhật ký của Fly chỉ giữ vài phút đầu ra, khoảng một trăm dòng gần nhất, đủ để theo dõi một lần triển khai nhưng vô dụng với chuyện của ngày hôm qua. Vì vậy một ứng dụng Fly thứ ba chạy log shipper của Fly, tức là Vector đăng ký nghe luồng nhật ký của cả tổ chức, và tôi chỉ đổi một chỗ ở sink S3 của nó:

[sinks.aws_s3]
  type = "aws_s3"
  bucket = "myapp-logs"
  compression = "gzip"
  key_prefix = "logs/{{fly.app.name}}/%F/"   # one folder per app per day
  batch.timeout_secs = 300                  # a quiet app still lands its lines

Mọi dòng nhật ký của các ứng dụng thuộc sàn giao dịch đều được ghi vào một bucket tương thích S3 dưới dạng JSON nén gzip. Shipper chạy trên một máy shared-cpu-1x 256 MB, khoảng 2 đô la mỗi tháng, phí lưu trữ chỉ vài xu. DuckDB đọc thẳng các tệp tại chỗ thông qua một macro, và dữ liệu của một ngày trả về trong khoảng một giây:

CREATE MACRO logs(app, day := '*') AS TABLE
  SELECT * FROM read_json_auto('s3://myapp-logs/logs/' || app || '/' || day || '/*.log.gz',
                               union_by_name := true);

SELECT timestamp, message FROM logs('myapp-api', '2026-09-06') WHERE message LIKE '% 500 %';

Tôi đã dùng chính macro này để đo thời gian khởi động nguội (cold start) trong bài về scale to zero: script khởi động báo từng giai đoạn, dòng nào cũng mang id của máy, phần còn lại chỉ là một câu GROUP BY.

Nói gọn lại, đó là ba tầng của cùng một luồng, chia theo người đọc: kho lưu trữ giữ mọi thứ từ INFO trở lên (cũng là lý do các ứng dụng ghi nhật ký ở mức INFO trên production), một script xem trực tiếp chỉ hiện cảnh báo và lỗi, còn kênh chat nhận mức ERROR. Có điều, cả ba đều không biết ai là người gọi. Nhật ký truy cập không có IP hay user agent của client, nên muốn biết điều đó tôi phải sang Cloudflare.

Chỉ số: Prometheus có sẵn của Fly

#

Fly chạy sẵn một Prometheus được quản lý cho mỗi tổ chức, nên tôi không phải vận hành hệ thống chỉ số riêng. Khi có câu hỏi, tôi gọi thẳng API của nó: bộ nhớ, CPU và hạn mức burst theo từng máy (trên CPU dùng chung thì fly_instance_cpu_balance rất quan trọng), số phản hồi và số yêu cầu đồng thời theo từng ứng dụng. Có hai điều tôi ước mình biết sớm hơn. Token tạo bằng fly tokens create phải gửi dưới dạng Authorization: FlyV1 <token>; Bearer chỉ dùng được với token cá nhân từ flyctl auth token, còn token chỉ đọc sẽ nhận về “something went wrong resolving organization”. Và dữ liệu chỉ được giữ khoảng hai tuần (Fly nói là khoảng 15 ngày).

Nó chứng minh giá trị của mình vào tháng Chín, khi nhật ký xuất hiện “Could not open a database connection” vài lần mỗi ngày, trông y hệt một lỗi của ứng dụng. Cụm Postgres được quản lý cũng nằm trong cùng Prometheus đó, và ở mỗi phút có lỗi, thời gian scrape của máy chủ chính (primary) nhảy từ khoảng 80 mili giây lên một đến mười giây, trong khi bản sao (replica) vẫn bình thường và thời điểm khởi động của Postgres không hề đổi. Tức là Postgres không khởi động lại; chính máy chủ vật lý bên dưới bị treo. Tôi gửi các mốc thời gian cho bộ phận hỗ trợ của Fly, và sau một lần khởi động lại để bảo trì vào đầu tháng Mười đưa primary sang máy khác, tình trạng treo hằng ngày đã chấm dứt.

Báo cáo crash: SDK của Sentry, trỏ về API của chính tôi

#

Trước đây, khi ứng dụng crash trên điện thoại thì tôi không thấy dấu vết gì ở bất cứ đâu. Câu trả lời hiển nhiên là Sentry, và tôi lấy một nửa của nó: ứng dụng dùng SDK mã nguồn mở của Sentry, nhưng DSN trỏ vào một endpoint trong chính API Django của tôi. Endpoint này nhận định dạng envelope của Sentry, gom nhóm các lần crash và cảnh báo qua đúng handler gửi vào kênh chat ở trên. Truy vết, phiên (session) và replay đều tắt; chỉ nhận lỗi.

Tôi không đăng ký sentry.io vì với vài báo cáo mỗi ngày, làm vậy nghĩa là thêm một nhà cung cấp nắm 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 hóa đơn. Cái giá phải trả là symbolication (giải mã stack trace về mã nguồn), thứ tôi vẫn chưa thay thế được. Stack trace hoặc là JavaScript đã bị rút gọn (minify), hoặc là địa chỉ native thô, nên một issue cho tôi biết cái gì crash, trên bản phát hành và thiết bị nào, người dùng vừa làm gì ngay trước đó, nhưng không cho biết lỗi nằm ở đâu trong mã nguồn.

Bảng điều khiển duy nhất là một tin nhắn

#

Tôi không dựng bảng điều khiển cho ứng dụng nào cả. Bài năm ngoái có một phép thử cho dashboard: nếu không ai tự mở nó ra, nó chưa chứng minh được giá trị. Một tin nhắn tự gửi đến thì không cần ai mở, nên thứ gần với dashboard nhất mà tôi có là một bài đăng trong kênh chat của đội mỗi sáng.

Phần đầu là các lỗi production trong 24 giờ qua, đọc từ kho nhật ký chứ không phải từ kênh chat, vì cảnh báo đã bị giới hạn tần suất nên không thể cho biết một chuyện xảy ra bao nhiêu lần. Số, id và địa chỉ được che đi trước khi gom nhóm, nên một trăm lần cùng một lỗi chỉ là một dòng kèm số lần, và không địa chỉ email nào lọt vào kênh.

Tiếp theo là các lần health check thất bại, mức sử dụng hôm qua so với cùng thứ đó của tuần trước (Chủ nhật thì không bao giờ giống thứ Hai), lượt truy cập từ tìm kiếm của tuần gần nhất, các cuộc trò chuyện đang chờ trả lời, bảng công việc và khoản chi tiêu. Phần nào không tải được thì ghi rõ như vậy, còn bài đăng vẫn được gửi đi.

Đọc số liệu phân tích ứng dụng qua API dạy bạn nghi ngờ con số một chút. Tháng Tám có 121 lượt mở ứng dụng Android lần đầu từ Azerbaijan, kéo theo 119 lượt gỡ cài đặt, và tôi đọc tổng số Android của tháng đó sau khi đã trừ chúng ra.

Các bản phát hành có màn hình riêng. Hồi bản cập nhật OTA còn được phát từ máy chủ của tôi, cách duy nhất để xem một bản phát hành là một danh sách trong trang quản trị có ô “is active”, và tôi hoàn toàn không biết có bao nhiêu điện thoại đã nhận bản cập nhật. Dashboard của dịch vụ mới cho thấy các thiết bị thật sự đang chạy bản nào, việc cài đặt diễn ra ra sao, và cả lần quay lui khi một bundle lỗi bị crash và SDK đưa bản trước đó quay lại. Tôi đã viết riêng về việc chuyển sang một dịch vụ cập nhật thuê ngoài.

Những thứ tôi đã bỏ, hoặc thôi tin

#

Không có thứ nào trong số này là công cụ trả phí. Phần lớn là những thứ tôi vẫn coi là tín hiệu nhưng hóa ra không phải, và một tác vụ chạy sai chỗ.

Tỷ lệ 504 của Cloudflare, cho tới khi tôi gom nhóm theo user agent

#

Tháng Chín, dashboard của Cloudflare cho thấy có vẻ như 22% số yêu cầu trong một ngày thất bại với lỗi 504, dồn vào các endpoint mà ứng dụng thăm dò (poll) mỗi 30 giây, trong khi health check vẫn xanh hết và nhật ký của chính ứng dụng cho thấy các yêu cầu đó được xử lý rất nhanh. Tôi mất mấy ngày với nó, phát hiện máy cần 25 đến 33 giây để khởi động nguội và phải làm thế 92 lần mỗi ngày, sửa xong, rồi viết trong bài về scale to zero rằng đó là nguyên nhân.

Sáng hôm sau tôi gom nhóm chính những lỗi 504 đó theo user agent. Toàn bộ 7,344 lỗi từ ngày 5 đến ngày 9 tháng Chín đều đến từ các lượt tra cứu cache Early Hints của chính Cloudflare (user agent là bastion early hints và nginx-ssl early hints); chúng không bao giờ đi tới origin, và mã 504 trên những dòng đó ghi lại một lần cache miss chứ không phải timeout. Chúng bắt chước đường dẫn của yêu cầu thật, nên rơi đúng vào những endpoint bận nhất và trông y như người dùng đang gặp lỗi. Ứng dụng, trình duyệt, curl và trình thu thập dữ liệu của công cụ tìm kiếm không có lấy một lỗi nào. Origin khi đó không gửi header Link, nên Early Hints thực ra chẳng làm được gì, và tôi đã tắt nó; về sau tôi làm cho nó hoạt động thật sự.

Công sức tối ưu khởi động nguội vẫn có ích, vì triển khai và đánh thức máy đều nhanh hơn, nhưng sự cố mà tôi tưởng mình đang sửa thì chưa từng chạm tới người dùng nào.

Vì thế, quy tắc tôi muốn chia sẻ nhất là: trước khi tin vào tỷ lệ lỗi của CDN, hãy gom nhóm theo user agent và kiểm tra xem đó có phải do chính cơ chế của CDN sinh ra không. Trên gói miễn phí của Cloudflare, đó là một truy vấn GraphQL vào httpRequestsAdaptiveGroups, mỗi lần một ngày. Lần hoảng tiếp theo cũng được giải quyết bằng đúng truy vấn đó, khi một endpoint thăm dò tăng từ 70–260 yêu cầu mỗi ngày lên 2,880. Không phải công cụ cào dữ liệu (scraper) nào cả. Đó là chính máy Mac của tôi, với ứng dụng vẫn đang chạy trong trình giả lập iOS sau khi kiểm thử.

Một health check báo xanh

#

Fly kiểm tra /api/health/ của cả hai ứng dụng mỗi 30 giây và dùng kết quả để quyết định máy nào được nhận lưu lượng, và nó làm việc này tốt. Nhưng health check chạy trên một máy đã khởi động xong, nên nó không thấy những gì xảy ra trước đó: một lần khởi động nguội, một hàng đợi ở proxy, một yêu cầu không bao giờ tới nơi. Giờ tôi chỉ nhờ nó định tuyến.

Khi triển khai, tôi dùng script thăm dò thay thế: nó gọi vào origin suốt quá trình và thoát với mã 1 nếu có bất kỳ yêu cầu nào lỗi. Script này đã bắt được một lần flyctl deploy thông thường để lại khoảng hở 7.3 giây, rồi ghi nhận không lỗi nào trong 2,514 yêu cầu khi chạy qua script triển khai, vốn đánh thức một máy dự phòng trước.

Bản thân health check cũng từng gây ra hai sự cố. Tháng Bảy, thiết lập SECURE_SSL_REDIRECT của Django trả lời yêu cầu thăm dò HTTP thường của Fly bằng mã 301, mọi máy đều trượt kiểm tra, và ai cũng nhận về lỗi 503. Tháng Tám, việc thu hẹp một except Exception trong view health check khiến lỗi “connection already closed” lọt ra thành 500, và Fly gỡ máy ra đúng trong trường hợp mà cơ chế thử lại của view được viết ra để xử lý. Giờ health check chỉ hỏi một câu: tiến trình này có phục vụ được yêu cầu không, và khi cơ sở dữ liệu bị treo thì cả hai ứng dụng không còn bị gỡ khỏi định tuyến nữa.

Bản tóm tắt buổi sáng cũng phải học bài học tương tự về cách đếm. Sàn giao dịch tạm ngưng (suspend) các máy đang rảnh, nên một máy bị đánh thức bởi yêu cầu sẽ trượt lần kiểm tra đầu tiên vài trăm mili giây sau khi khởi động và qua ở lần kế tiếp. Đếm cả những lần đó khiến sáng nào đọc cũng như có sự cố, nên giờ lỗi nào qua lại được trong vòng một phút sẽ được liệt kê riêng, ghi là máy thức dậy và các lần triển khai.

Một tác vụ định kỳ trên CI

#

Bản tóm tắt buổi sáng ban đầu là một workflow CI chạy theo lịch cron, và chỉ trong vòng một ngày đã phải chuyển đi. Khi nó cần đọc số liệu phân tích và tìm kiếm, khóa cần dùng là khóa tài khoản dịch vụ (service account) của dự án phân tích, thứ làm được mọi việc trong dự án đó, và tôi không muốn để nó trong secrets của CI. Giờ một trình lập lịch trên máy Mac của tôi chạy nó mỗi 20 phút, và nó chỉ đăng bài khi đã qua tám giờ sáng theo giờ Auckland mà bài của hôm nay chưa được gửi, nên một chiếc Mac đang ngủ lúc tám giờ sẽ đăng khi nó thức dậy. Workflow vẫn được giữ làm phương án dự phòng chạy tay, chỉ thiếu hai phần phân tích và tìm kiếm.

Nếu được bắt đầu lại

#

Tôi sẽ dựng ba thứ trước khi có người dùng đầu tiên, chứ không đợi tới sau sự cố đầu tiên: gửi lỗi vào một kênh chat mà đội vốn đã đọc, có giới hạn tần suất; một kho nhật ký trên object storage truy vấn được bằng SQL; và những chỉ số mà nền tảng vốn đã thu thập sẵn. Tất cả chỉ tốn vài đô la mỗi tháng. Báo cáo crash thì thêm vào đúng tuần ứng dụng lên điện thoại, vì nếu không, một lần crash trên điện thoại chẳng báo cho ai biết điều gì. Bản tóm tắt buổi sáng thì thêm vào khi số chỗ phải kiểm tra đã nhiều tới mức tôi sắp chẳng buồn kiểm tra chỗ nào nữa.

Truy vết thì tôi để dành cho tới khi có dịch vụ thứ hai để một yêu cầu phải đi qua, còn APM dạng dịch vụ thuê ngoài thì đợi tới khi có một đội cần dashboard dùng chung, lịch trực (on-call) và ngân sách để trả hóa đơn cho người khác. Đó là lúc những công cụ trong bài năm ngoái bắt đầu đáng đồng tiền. Trước lúc đó, thói quen hữu ích nhất lại miễn phí: khi một con số trông đáng sợ, hãy tìm xem cái gì tạo ra nó trước khi kết luận cái gì bị hỏng. Không ít lần hoảng hốt trong bài này đến từ chính hệ thống giám sát, chứ không phải từ sản phẩm.

Bộ đồ nghề làm việc của tôi gồm ba cỗ máy hiếm khi ở cùng một chỗ. Thứ nhất là chiếc MacBook Air, tôi đi đâu nó theo đó. Thứ hai là một máy trạm ở văn phòng tên devbox, có GPU thật, chạy Ollama, mấy công cụ fine-tuning, một cụm Kubernetes nhỏ kèm container registry riêng, và bất kỳ agent nào tôi để lại đang cày một tác vụ dài. Thứ ba là điện thoại, nơi các ứng dụng tôi làm ra thật sự được dùng, và phần lớn thời gian trong ngày nó chạy bằng dữ liệu di động chứ không phải wifi.

Suốt một thời gian dài, ba thiết bị này gần như không nói chuyện được với nhau. Laptop chỉ kết nối được tới devbox khi đang ở trong mạng LAN văn phòng, ra ngoài là chịu. Điện thoại truy cập được dev server trên laptop khi cả hai cùng một mạng wifi, mà cũng chỉ khi tôi nhớ bind vào 0.0.0.0 và gõ đúng địa chỉ mà DHCP cấp cho chiếc Mac sáng hôm đó. Mọi thứ hay ho trên máy trạm, từ API của Ollama, các dashboard của cụm, dữ liệu trace, đến registry, đều được bind vào localhost hoặc mạng nội bộ của cụm, và tôi cố ý làm vậy, vì không thứ nào trong số đó nên nằm trên internet.

Bài này kể cách tôi nối chúng lại bằng Cloudflare WARP và một cặp Cloudflare Tunnel, điều đó đã thay đổi cách tôi làm tính năng AI và ứng dụng di động ra sao, và vài thứ đã hỏng mà chẳng hề báo cho tôi biết.

Điều tôi thật sự muốn

#

Nếu viết thành yêu cầu thì danh sách khá ngắn:

1. Laptop chỉ nên là máy khách mỏng (thin client). Việc gì cần GPU, cần nhiều RAM hay phải chạy hàng giờ thì để devbox lo, và laptop phải kết nối tới nó theo cùng một cách, dù đang ở văn phòng, ở nhà hay ở quán cà phê.
2. Điện thoại phải truy cập được dev server và shell của tôi từ bất cứ đâu, qua dữ liệu di động, mà không cần một cái VPN tôi phải nhớ bật tắt.
3. Những công cụ tôi dùng để xem hệ thống đang chạy thế nào, như dashboard, trace, docker info, danh sách mô hình, chỉ mình tôi truy cập được, và không bao giờ có URL công khai.
4. Không mở cổng vào (inbound port) nào. Không trên router văn phòng, không trên router ở nhà, không ở đâu cả.

Yêu cầu thứ tư loại bỏ luôn lời giải cũ, tức là chuyển tiếp cổng (port forward) cộng với một tên miền DNS động. Nó cũng loại bỏ khá nhiều mẹo khôn lỏi khác: cả devbox lẫn laptop đều nằm sau NAT mà tôi không kiểm soát, và cứ vài tiếng laptop lại nằm sau một NAT khác.

Trước đây: một repo toàn đường hầm SSH

#

Phiên bản đầu tiên là một repo nhỏ tôi tự viết, và đến giờ nó vẫn là lớp nền. Nó giải quyết đúng một bài toán trên laptop: đặt tên gọn gàng cho những thứ tôi truy cập qua SSH, không hơn. dnsmasq trả lời *.test bằng 127.0.0.1, Caddy định tuyến theo hostname tới một cổng cục bộ với tls internal để trình duyệt không kêu ca, còn một loạt launch agent chạy autossh giữ cho các đường hầm chuyển tiếp SSH (SSH forward) luôn mở và tự kết nối lại khi bị rớt. Chỉ cần nhìn hostname là biết thứ đó nằm ở đâu:

Vậy nên https://devbox-ollama.ssh.test/api/tags liệt kê các mô hình trên máy trạm, còn https://api.local.test là API của ứng dụng tôi đang làm, chạy ngay trên máy tôi.

Tôi dùng tên miền con của .test, chứ không tạo tên miền cấp cao mới như .ssh hay .cloud, và cũng không dùng .local. RFC 6761 dành riêng .test cho đúng mục đích này, còn .local thuộc về mDNS; chiếm nó là tính năng dò tìm Bonjour trên Mac ngừng hoạt động. dnsmasq vốn đã bắt wildcard toàn bộ *.test, nên thêm một nhãn nữa chẳng tốn gì: chỉ một tệp /etc/resolver/test trỏ vào 127.0.0.1, và từ đó về sau không phải chỉnh DNS thêm lần nào.

HTTPS trên những cái tên không hề tồn tại

#

Tất cả các tên đó đều chạy HTTPS với chứng chỉ mà trình duyệt tin tưởng, nghe thì có vẻ bất khả thi với một hostname chỉ tồn tại trên laptop của tôi. Caddy làm được nhờ tổ chức cấp chứng chỉ (CA) nội bộ của riêng nó. Khai báo tls internal cho một site nghĩa là bảo Caddy cấp chứng chỉ cho site đó từ một CA cục bộ thay vì xin Let’s Encrypt, còn caddy trust, được trình cài đặt chạy một lần, đưa chứng chỉ gốc của CA vào System keychain của macOS (Chrome và Safari đọc từ đây) và vào kho chứng chỉ riêng của Firefox. Từ lúc đó, https://anything.test mở ra mà không có cảnh báo chứng chỉ nào, http:// thường thì tự chuyển hướng sang, và không có gì rời khỏi máy.

Đây không chỉ là chuyện cho đẹp. Ngày càng nhiều tính năng của nền tảng web từ chối chạy trên HTTP thường: secure cookie, service worker, clipboard API, bất cứ thứ gì có SameSite=None. Kiểm thử một bản web build trên http://localhost thường sẽ che mất những lỗi chỉ lộ ra trên tên miền HTTPS thật. Kiểm thử trên https://app.local.test thì các lỗi ấy hiện ra ngay trên laptop của tôi.

Một khối cấu hình site, dịch vụ nào cũng giống hệt, chỉ khác số cổng:

devbox-ollama.ssh.test, devbox-ollama.test {
	tls internal
	import cors
	reverse_proxy 127.0.0.1:11435 {
		import proxyhdr
		transport http {
			keepalive off
			dial_timeout 5s
		}
	}
}

Hai snippet kia gánh những phần lắt nhắt. cors phản chiếu lại đúng Origin của bên gọi thay vì gửi *, vì * không được phép khi có dính tới thông tin xác thực (credentials), và nó tự trả lời các yêu cầu preflight OPTIONS bằng mã 204 để phía upstream không bao giờ phải lo. proxyhdr ghi đè header Host thành địa chỉ đích. Một số backend khó tính, trong đó có trang quản trị router và endpoint remote-debugging của Chrome, kiểm tra Host, và nếu không ghi đè thì chúng sẽ từ chối devbox-ollama.ssh.test như một cái tên chưa từng nghe tới. Cơ chế kiểm tra origin của chính Ollama chấp nhận loopback ở mọi cổng, nên ghi đè Host thành 127.0.0.1:11435 là lọt qua.

keepalive off là dòng mà nếu tự làm thì tôi đã sai. Phía upstream là các đường chuyển tiếp SSH mà autossh phá đi dựng lại mỗi khi mạng thay đổi. Nếu bật keep-alive, Caddy sẽ giữ một kết nối trong pool tới một đường hầm đã chết từ lâu, và cứ trả về những lỗi 404 khó hiểu cho tới khi được reload. Tắt đi thì mỗi yêu cầu đều kết nối mới, mà trên loopback thì chi phí đó không đo được.

Mỗi dịch vụ cũng trả lời ở tên phẳng cũ của nó (devbox-ollama.test), để các bookmark từ trước khi có hệ hậu tố vẫn dùng được.

Thanh menu

#

Khi đã có cả chục đường chuyển tiếp do launchd giữ mở, câu tôi cứ hỏi mãi là “nó có đang chạy không?”, và câu trả lời thì nằm ở ba chỗ: launchctl list, lsof và một lệnh curl. Thế nên tôi viết một plugin nhỏ cho thanh menu để gom về một chỗ, mỗi hostname có một chấm màu bên cạnh:

• 🟢 dịch vụ đã trả lời một yêu cầu đi qua đường hầm
• 🟡 đường hầm đang mở nhưng dịch vụ phía sau im lặng
• 🔴 không có gì lắng nghe ở cổng cục bộ, tức là chính đường hầm đã sập

Trạng thái vàng mới là cái hữu ích. Một phép kiểm tra chỉ có xanh/đỏ không phân biệt được “đường chuyển tiếp SSH đã chết” với “Ollama bị crash ở đầu bên kia”, mà hai chuyện đó có cách sửa hoàn toàn khác nhau. Plugin không giữ danh sách dịch vụ riêng mà đọc chính cấu hình proxy và cấu hình SSH mà mọi thứ khác đang dùng, nên thêm một dịch vụ ở đó là nó tự xuất hiện trên menu.

Phiên bản đầu tiên hơi tham. Nó làm mới mỗi mười giây và gọi vài tiến trình cho mỗi dịch vụ, khoảng bảy mươi tiến trình mỗi lượt, và macOS lập tức liệt nó vào danh sách “apps using significant energy”. Chỉ chụp trạng thái một lần mỗi lượt và làm mới cách vài phút là đủ kéo nó xuống còn khoảng 0.1% một nhân. Một đèn trạng thái mà ngốn pin thì chẳng giúp được ai, nên đáng tính chi phí của nó ngay từ đầu.

Nó có đúng một lỗ hổng, và lại là lỗ hổng quan trọng nhất. devbox không có tên công khai. Đường chuyển tiếp SSH tới nó kết nối vào một địa chỉ 192.168.x, nên nó chỉ chạy được khi laptop đang ở trong LAN văn phòng. Ra khỏi văn phòng là thanh menu chuyển đỏ và đỏ luôn, và mọi thứ tôi đã dời sang máy trạm để đỡ tải cho laptop đều nằm ngoài tầm với, đúng vào những lúc tôi không ngồi cạnh nó.

Hai đường hầm, quay đúng hướng

#

Cách sửa gồm ba phần, và hai phần đầu là Cloudflare Tunnel.

Một Cloudflare Tunnel là cloudflared giữ một kết nối đi ra (outbound) tới edge của Cloudflare. Cloudflare đẩy các yêu cầu ngược xuống theo chính kết nối đó, nên một máy nằm sau bao nhiêu lớp NAT cũng truy cập được mà không cần thứ gì lắng nghe trên router. Laptop mang ra wifi khách sạn nó vẫn theo, và nó sống sót được cả CGNAT.

Tôi chạy hai đường hầm, mỗi máy một cái, và lý do đáng để nói một câu. Lối tắt dễ thấy là chỉ một đường hầm trên laptop, thêm một quy tắc ingress trỏ tới cổng SSH của devbox trong LAN văn phòng. Cách đó không cần cài gì lên devbox cả. Nhưng nó cũng đi vòng qua laptop, mà laptop lại chính là cái máy rời khỏi văn phòng. Nó sẽ hỏng đúng trong trường hợp mà nó được tạo ra để xử lý. devbox thì đứng yên một chỗ, nên devbox tự giữ kết nối riêng của mình tới edge.

# config.yml on devbox (runs as a systemd service)
protocol: auto        # prefer QUIC, fall back to HTTP/2 over TCP 443
ha-connections: 4     # mains-powered, its job is to stay reachable

warp-routing:
  connectTimeout: 5s

ingress:
  - hostname: ssh-devbox.example.com
    service: tcp://127.0.0.1:22
  - service: http_status:404

Dùng tcp:// thay vì ssh:// là chỗ rất dễ làm sai. ssh:// chọn chế độ terminal hiển thị trên trình duyệt của Cloudflare, vốn bọc luồng dữ liệu lại cho một trang web; một client ssh bình thường đi qua đó sẽ nhận được banner rồi chết ngay ở bước trao đổi khóa. tcp:// mới là đường ống byte thuần mà cloudflared access ssh cần, và được thêm cái lợi là nó mang được cả scp, rsync, git qua SSH lẫn port forward.

Chính phần sau cùng ấy đã vá lỗ hổng ở lớp SSH. Cấu hình SSH giờ chọn đường đi cho từng kết nối:

Match originalhost devbox !exec "nc -z -G 1 <office-lan-ip> 22 >/dev/null 2>&1"
    ProxyCommand cloudflared access ssh --hostname ssh-devbox.example.com ...

Khi ở trong LAN văn phòng, phép thăm dò thành công và SSH đi thẳng, một bước nhảy. Ở bất kỳ đâu khác, phép thăm dò thất bại và SSH đi qua Cloudflare, xác thực bằng một service token của Access nên không có bước đăng nhập trên trình duyệt nào chắn đường. Phải là Match originalhost, không phải Match host: host so khớp sau khi HostName đã được thay vào, nên lúc đó tên đã thành IP và khối cấu hình không bao giờ kích hoạt. Kết quả là devbox-ollama.ssh.test chạy được ở văn phòng, ở nhà và trên tàu, và chấm trên thanh menu cứ xanh mãi.

Đường hầm của laptop thì đi theo chiều ngược lại. Nó cấp cho các dev server trên Mac những hostname HTTPS công khai thật: với mỗi ứng dụng tôi đang làm, đó là API, WebSocket server và bản web build của nó. Tất cả đều nằm sau Cloudflare Access, phần này tôi sẽ quay lại sau, vì chính nó biến cách làm này từ liều lĩnh thành an toàn.

Thanh menu cũng phải học cách nhận biết cả hai đường hầm, và nó không làm được bằng cách thăm dò. Một đường hầm chiều vào không có cổng cục bộ nào để kiểm tra, một trong hai connector thậm chí không chạy trên laptop, còn phép thử dễ thấy nhất, curl tới ssh-devbox.example.com, lại luôn nhận được câu trả lời từ edge của Cloudflare dù có connector nào gắn vào hay không, nên nó sẽ báo xanh cho một đường hầm đã chết. launchd cũng chẳng khá hơn: cloudflared cứ nằm đó ở trạng thái “loaded, exit 0” trong khi mọi kết nối tới edge đã rớt hết. Vậy nên với các đường hầm, menu hỏi Cloudflare API xem mỗi đường hầm có connector nào khỏe mạnh không, vì chính điều đó quyết định một lệnh ssh có tới nơi hay không. Nếu không liên lạc được với API, cả phần đó bị bỏ qua luôn thay vì vẽ màu đỏ. Thanh menu là thứ nhìn lướt qua, và một báo động giả ở đó tốn kém hơn một dòng bị thiếu.

Phần thứ ba: WARP biến nó thành một mạng

#

Đường hầm có hostname rất tuyệt cho mọi thứ nói HTTPS, và cho SSH từ một máy chạy được cloudflared. Điện thoại thì không chạy được. Hơn nữa, hostname của đường hầm không phải là một endpoint TCP: edge của Cloudflare chỉ kết thúc (terminate) HTTPS và WebSocket trên đó, nên cổng 22 tại ssh.example.com đóng, và loay hoay với Access đến mấy cũng không mở được.

Đó là việc của WARP. Cloudflare One Agent (tức client WARP bản doanh nghiệp, không phải ứng dụng “1.1.1.1” cho người dùng phổ thông, vốn không tham gia tổ chức được) được đăng ký trên laptop và điện thoại vào tổ chức Zero Trust của tôi. Mỗi đường hầm quảng bá các tuyến riêng (private route), và một thiết bị đang chạy WARP có thể mở một socket bình thường tới những địa chỉ đó và tới đúng máy. Nó không còn là “truy cập dịch vụ này qua tên” nữa, mà thành “những cỗ máy này đang ở chung một mạng với tôi”:

Những địa chỉ này là alias loopback trên từng máy, được tạo lúc khởi động, nên chúng không phụ thuộc vào DHCP hay router nào tôi đang đứng sau. 198.18.42.2 là devbox, dù đang ở văn phòng, ở nhà hay từ điện thoại dùng 5G. Địa chỉ LAN thật của chiếc Mac đổi mỗi lần tôi di chuyển; địa chỉ này thì không bao giờ đổi.

Chế độ chia tách đường hầm (split tunnel) đặt ở include mode, chỉ chứa những tuyến đó (cộng các dải của Cloudflare mà bản thân WARP cần). Chính điều này khiến client dễ sống cùng. Mặc định là exclude mode, khi đó WARP mang mọi thứ trừ một danh sách các dải riêng, nên từng byte điện thoại gửi đi đều đi vòng qua Cloudflare. Cái giá về pin và độ trễ là có thật, đủ để rốt cuộc tôi sẽ chỉ bật nó khi cần, mà như thế thì mất hết ý nghĩa. Ở include mode, lưu lượng tới ba máy của tôi đi qua WARP, còn mọi thứ khác đi theo đường bình thường, không bị động tới. Thế là client cứ bật suốt. warp-cli status trên laptop báo Connected cả ngày và tôi chẳng phải nghĩ đến nó.

Về giao thức truyền tải, tôi dùng MASQUE, tức HTTP/3 trên UDP 443 với HTTP/2 làm phương án dự phòng, thay vì WireGuard trên UDP 2408. Một số nhà mạng và mạng dành cho khách chặn 2408; gần như chẳng ai chặn 443. Chính sách của tổ chức tôi còn bật sẵn thỏa thuận khóa hậu lượng tử (post-quantum key agreement) cho MASQUE, thứ tôi không đi tìm nhưng cũng chẳng dại gì từ chối.

Vì sao là 198.18, và vì sao lại có địa chỉ IPv6

#

Các địa chỉ này trông hơi lạ, và những địa chỉ đầu tiên tôi chọn đã sai theo một cách khá bổ ích.

Lần đầu tôi thử 10.10.0.1, vì đó là thứ ai cũng nghĩ tới đầu tiên. Nó thất bại ở cả hai chế độ split tunnel. Ở exclude mode, danh sách mặc định của WARP loại trừ mọi dải RFC 1918 cộng 100.64.0.0/10, nên client sẽ bỏ lưu lượng tới địa chỉ đó trước khi nó kịp rời thiết bị. Ở include mode, nó sẽ đụng với bất kỳ mạng 10.x thật nào tôi tình cờ tham gia; quán cà phê, không gian làm việc chung và rất nhiều văn phòng dùng đúng dải đó. 198.18.0.0/15 là dải dành cho đo kiểm hiệu năng (benchmarking) theo RFC 2544. Nó được dành riêng, không bao giờ được định tuyến trên internet công cộng, không nằm trong danh sách loại trừ của WARP, và không mạng thông thường nào dùng tới nó. Các địa chỉ IPv6 là ULA (fd00::/8) cũng vì lý do đó.

Còn vì sao lại có IPv6 thì mới là câu chuyện thú vị hơn. Khi địa chỉ v4 đã chạy, tôi thử từ điện thoại qua wifi, mọi thứ ổn, và tôi coi như xong. Dùng 5G thì không chạy. Agent báo connected, đường hầm khỏe mạnh, Access cũng ổn; phép thử qua wifi đã chứng minh tất cả những điều đó. Vấn đề là mạng di động bây giờ phần lớn chỉ có IPv6. Điện thoại hoàn toàn không có IPv4 gốc, và nó truy cập địa chỉ v4 kia qua bộ chuyển đổi 464XLAT của nhà mạng, thứ nằm bên ngoài đường hầm khi danh sách include chỉ chứa một tiền tố v4. Lưu lượng đi ra internet công cộng, nơi 198.18.0.0/15 không được định tuyến, và bị bỏ đi không một tiếng động. Không có lỗi nào trên điện thoại, không có gì trong log của connector.

Cách sửa là cấp cho mỗi máy một địa chỉ thứ hai mà điện thoại truy cập được trực tiếp qua IPv6, rồi thêm nó vào các tuyến và vào danh sách include. Giờ các địa chỉ fd12:3456:789a:: chính là thứ mà client SSH trên điện thoại thật sự dùng khi chạy dữ liệu di động.

Giảm tải: laptop chỉ còn là một cái terminal

#

Đây mới là phần mà cả hệ thống này tồn tại để phục vụ.

Mô hình và fine-tuning. Ollama chạy trên devbox và bind vào 127.0.0.1:11434. Phần còn lại của LAN văn phòng không nhìn thấy nó, huống gì internet. Trên laptop, nó xuất hiện ở https://devbox-ollama.ssh.test, hoặc dưới dạng một cổng trần cho những công cụ cần thế:

OLLAMA_HOST=127.0.0.1:11435 ollama list

Là 11435 chứ không phải 11434, và tôi cố ý: 11434 là cổng mặc định của chính Ollama, nên nếu có ngày laptop cũng chạy một Ollama cục bộ, hai bên sẽ tranh nhau cổng đó, và tùy cái nào khởi động trước mà tôi có thể âm thầm nhận câu trả lời của devbox từ cái Ollama “cục bộ”.

Hiệu quả thực tế là khi tôi làm một tính năng AI, mô hình mà nó gọi chạy trên GPU của máy trạm chứ không phải của laptop, dù tôi đang ở đâu. Các lượt đánh giá (evaluation), việc tạo embedding cho cả đống tài liệu, một lần fine-tune: tất cả chạy trên devbox, và quạt laptop thì cứ im. Khi đang làm prototype một agent, tôi có thể trỏ nó tới một mô hình cục bộ trên máy trạm và cho nó chạy hết vòng gọi công cụ này đến vòng khác (tool calling) mà không tốn hóa đơn API nào, rồi chuyển sang mô hình được host khi vòng lặp đã đúng.

Agent chạy dài. Một phiên agent chạy cả tiếng đồng hồ không nên phụ thuộc vào việc nắp laptop có mở hay không. Chạy nó trên devbox thì laptop chỉ còn là một ô cửa sổ nhìn vào: gập máy lại, lát sau ssh devbox từ bất cứ đâu tôi đang ở, hay từ điện thoại, và nó vẫn còn đó. Trước khi có đường hầm, điều này chỉ làm được ở văn phòng, mà đó lại chính là nơi tôi không cần đến nó.

Build và cụm máy. Cụm trên devbox có registry riêng, nên image có thể được build và push ngay trên máy trạm, cạnh nơi chúng sẽ chạy, thay vì upload từ laptop qua wifi khách sạn. Dashboard của cụm, dashboard của ingress và giao diện của registry đều là các hostname *.ssh.test trên laptop.

Vòng lặp phát triển di động. Điện thoại ở cùng mạng riêng với laptop, và các dev server trên laptop cũng có hostname công khai nằm sau Access. Vậy nên tôi có thể mang một bản build native của ứng dụng ra khỏi tòa nhà, dùng 5G, và nó vẫn nói chuyện với API đang chạy trên bàn làm việc của tôi. Hoặc với API trên devbox, nếu tôi để nó chạy ở đó. Trước đây, vòng phản hồi trên thiết bị thật qua mạng di động thật đồng nghĩa với việc triển khai lên một staging server dùng chung. Giờ nó chỉ còn là lưu một tệp.

Có một cái bẫy ở đây, nên biết trước khi bạn đi debug nó như lỗi của ứng dụng. Access cũng bảo vệ cả hostname WebSocket, mà client WebSocket native thì không phải trình duyệt. Nó không mang cookie CF_Authorization, nên kết nối từ bản build native tới WebSocket server bị chặn ngay ở edge với mã 403, trông chẳng giống lỗi do server của bạn trả về chút nào. Các tab trình duyệt thì không sao vì chúng đã giữ cookie từ lúc đăng nhập. Với mọi thứ không phải trình duyệt (ứng dụng native, một script, một agent gọi API dev), lời giải là một service token của Access, gửi dưới dạng hai header:

CF-Access-Client-Id:     <client_id>
CF-Access-Client-Secret: <client_secret>

Bản thân token không cấp quyền gì. Access chỉ chấp nhận nó ở những ứng dụng có policy nêu tên nó, nên phạm vi của nó đúng bằng danh sách hostname dev, không rộng hơn. Tôi xếp policy của nó vào quyết định non_identity thay vì allow, để trong audit log nó vẫn hiện ra là một bí mật dạng bearer, chứ không phải một người đã đăng nhập.

Những chỉ số internet không bao giờ thấy

#

Nửa còn lại của điều tôi muốn là khả năng quan sát. Phần lớn những thứ cho bạn biết một hệ thống đang chạy thế nào, một cách đúng đắn, đều không công khai. Trên devbox, đó là:

• dashboard của ingress proxy, và giao diện tracing chứa trace của nó
• một dashboard cho cụm Kubernetes
• giao diện của container registry (chỉ đọc)
• danh sách mô hình của Ollama và những gì đang được nạp lúc này
• docker info và số liệu thống kê của container

Không thứ nào trong số đó có hostname công khai, và sẽ không bao giờ có. Chúng được bind vào loopback hoặc IP dịch vụ của cụm, truy cập qua một đường chuyển tiếp SSH mà bản thân nó lại chạy trên đường hầm. Một ứng dụng giám sát trên điện thoại đọc docker info --format '{{json .}}' qua SSH xuyên WARP, nên từ đâu tôi cũng xem được các container của mình có đang chạy không, hay có thứ gì đã ngốn hết bộ nhớ.

Chính ứng dụng đó giúp tôi tìm ra một lỗi nhỏ đáng kể lại. sshd dành cho đường hầm trên Mac vẫn đang để LogLevel DEBUG2 từ hồi tôi debug nó. Với -e, sshd ghi log ra stderr, và với một phiên SSH thì stderr đó chính là stderr của kênh SSH. Output của mọi lệnh đều trả về kèm thêm dòng debug2: do_setup_env: set TMPDIR ở cuối, và ứng dụng trên điện thoại, vốn gộp hai luồng lại, nhận được JSON hợp lệ theo sau là một dòng log, parse thất bại, rồi hiển thị toàn bộ như một lỗi. Đổi sang LogLevel INFO là xong. Debug xong nhớ trả log level về như cũ.

Cũng có chủ đích không kém là những thứ tôi không đưa lên mạng này. Các đường hầm autossh cũ còn truy cập tới vài router trên mạng của người khác mà tôi giúp trông coi. Những router đó không có hostname công khai và không có tuyến WARP. Một trang quản trị router nằm trên internet là một rủi ro, dù có đăng nhập chắn phía trước, và đó cũng không phải mạng của tôi để mà mở rộng.

Access là bắt buộc

#

Hostname của một Cloudflare Tunnel nằm trên internet công cộng ngay khi bản ghi DNS của nó tồn tại. Không có tường lửa nào đứng trước nó; không mở cổng chính là mục đích của cả việc này. Lớp bảo vệ phải đến từ edge của Cloudflare, và đó là việc Access làm. Nó từ chối chuyển tiếp bất kỳ yêu cầu nào cho tới khi người truy cập chứng minh được mình là ai, nên một công cụ quét chưa xác thực không bao giờ chạm tới được laptop. Điều đó quan trọng, vì đây là các dev server: một traceback ở chế độ debug kèm cả settings, một JavaScript bundler mở toang. Không thứ gì đằng sau các hostname này được làm ra để đối mặt với internet.

Policy chỉ cho phép chính các địa chỉ email của tôi, không gì khác, với hai cách chứng minh là mã PIN dùng một lần gửi qua email và đăng nhập một lần (SSO). Phiên đăng nhập kéo dài tám tiếng, vì mối đe dọa thực tế là một chiếc laptop bỏ mở ở quán cà phê với cookie có hạn cả ngày, chứ không phải ai đó dò mã PIN bằng brute-force.

SSH được xác thực hai lần, bởi hai hệ thống không hề biết đến nhau. Access quyết định một luồng TCP có được phép tới sshd hay không; sshd thì vẫn đòi khóa của tôi. Mất một trong hai cũng không mở được máy. sshd dành cho đường hầm trên Mac còn tin tưởng SSH CA của Cloudflare, nên Access có thể đăng nhập cho tôi bằng một chứng chỉ ngắn hạn được cấp từ phiên SSO, trong khi authorized_keys vẫn chạy song song, để một cấu hình Access bị hỏng không thể khóa tôi ra khỏi chính laptop của mình.

Phần tôi hài lòng nhất lại là một chi tiết nhỏ. Việc lộ ra ngoài xảy ra khi ba thứ cùng khớp: một bản ghi DNS, một connector đang chạy và một zone đang hoạt động. Chúng trở thành đúng vào những thời điểm khác nhau, theo thứ tự tôi không kiểm soát được; zone tự chuyển sang active, vào một lúc nào đó sau khi nameserver được đổi, rất có thể trong lúc chiếc Mac đang ngủ. Vậy nên launch agent không chạy cloudflared trực tiếp. Nó chạy một bước kiểm tra trước (preflight): đọc các hostname từ chính cấu hình của đường hầm, hỏi Access API xem hostname nào đã được bảo vệ, và từ chối khởi động nếu còn cái nào chưa:

HOSTNAMES=$(grep -E '^\s*-\s*hostname:' "$CONFIG" | sed -E 's/.*hostname:\s*//' | sort -u)
PROTECTED=$(curl -fsS -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
    "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/access/apps?per_page=100" \
    | python3 -c 'import sys,json; print("\n".join(a.get("domain","") for a in json.load(sys.stdin)["result"]))') \
    || { echo "could not reach the Access API. refusing (fail closed)."; exit 1; }

for h in $HOSTNAMES; do
    grep -qxF "$h" <<<"$PROTECTED" || { echo "NOT starting: $h has no Access app"; exit 1; }
done
exec cloudflared tunnel --config "$CONFIG" run

Launch agent có KeepAlive, nên một lần từ chối sẽ tự thử lại sau mỗi 30 giây, và đường hầm tự lên khi các Access app đã tồn tại. Thất bại theo hướng đóng (fail closed) thì cái giá là một lần gián đoạn. Thất bại theo hướng mở (fail open) thì cái giá là bị lộ. Tôi biết mình thà phải giải thích chuyện nào hơn.

Bốn chỗ khiến tôi vấp

#

Mọi thứ ở trên giờ đều chạy. Nhưng trên đường tới đây, ba trong bốn chỗ có cùng một kiểu: thứ bị hỏng không sinh ra lỗi ở bất cứ đâu, còn những phần tôi nhìn thấy được thì đều báo khỏe mạnh.

Tuyến và danh sách include là hai danh sách khác nhau. Một tuyến của đường hầm khiến Cloudflare sẵn lòng mang một địa chỉ tới đúng connector. Danh sách include của WARP mới là thứ khiến client gửi nó đi ngay từ đầu. devbox không truy cập được từ điện thoại vì các tuyến của nó đã có, nhưng danh sách include vẫn chỉ chứa địa chỉ của chiếc Mac. Điện thoại bỏ gói tin ngay tại máy, connector không hề thấy luồng nào, và dashboard nào cũng xanh. Mỗi máy mới đồng nghĩa với việc thêm địa chỉ của nó vào cả hai nơi.

Địa chỉ IPv4 viết cứng trên mạng di động chỉ có IPv6. Đã kể ở trên: chạy trên wifi, hỏng trên 5G, không có lỗi. Nếu một tuyến WARP chạy trên wifi mà không chạy trên dữ liệu di động, trong khi Agent vẫn báo connected, thì vấn đề nằm ở định tuyến, không phải ở đường hầm.

sshd của macOS đằng sau cloudflared. macOS khởi động sshd bằng cơ chế kích hoạt qua socket của launchd, mỗi kết nối một tiến trình sshd -i sống ngắn. Đằng sau cloudflared, banner tới được client rồi luồng bị cắt trước khi chuỗi nhận dạng của client kịp gửi ngược lại, nên mọi lần đăng nhập đều chết ở kex_exchange_identification. Tôi đã xác nhận từ cả hai đầu và tái hiện được bằng một bộ chuyển tiếp TCP thuần, qua đó loại trừ Cloudflare. Cách sửa là chạy thêm một sshd -D độc lập thứ hai trên 127.0.0.1:2222 và các địa chỉ loopback của WARP, chạy dưới user của tôi, chỉ để làm origin cho đường hầm. Remote Login trong System Settings không bị đụng tới. devbox chạy Linux với một sshd sống lâu bình thường, nên chưa bao giờ gặp vấn đề này.

Những trường cấu hình không còn tồn tại. Các ví dụ cũ vẫn ghi warp-routing: enabled: true trong cấu hình đường hầm. cloudflared 2026.8 từ chối thẳng trường đó. WARP routing được bật hễ khối cấu hình tồn tại và có một tuyến trỏ tới đường hầm. Ít ra cái này còn báo lỗi, mà sau ba vụ kia thì như thế đã là hào phóng lắm rồi.

Những gì đã thay đổi

#

Tóm lại một cách thành thật: tôi không còn chọn chỗ làm việc dựa trên chỗ đặt phần cứng nữa. Laptop là một bàn phím tốt, một màn hình tốt với thời lượng pin dài, và nó không cần phải hơn thế. Máy trạm gánh phần việc nặng dù tôi đang ở đâu. Điện thoại là một thiết bị kiểm thử thật trên một mạng thật, chứ không phải thứ bị buộc vào wifi văn phòng. Và những phần của hệ thống mà tôi dùng để xem nó đang làm gì thì chỉ cách tôi một cú bấm, còn với người khác thì chúng không hề tồn tại.

Ở quy mô này, mọi thứ nằm gọn trong gói Zero Trust miễn phí của Cloudflare. Cái giá tôi phải trả là thời gian, và một tệp README mà tôi mừng vì đã viết, vì nếu không thì mỗi lỗi ở trên đều sẽ lại là một bí ẩn mới ở lần gặp thứ hai.

Nếu bạn đang tính làm điều gì đó tương tự, đây là những câu tôi sẽ hỏi về hệ thống của bạn:

1. Thứ gì đang chạy trên laptop của bạn chỉ vì laptop là cái máy duy nhất bạn luôn truy cập được?
2. Điện thoại của bạn có truy cập được dev server qua dữ liệu di động không, chứ không chỉ qua wifi văn phòng? Hãy thử trên 5G, đừng thử trên wifi.
3. Dashboard nào của bạn đang công khai chỉ vì đó là cách dễ nhất để xem nó từ bên ngoài? Mỗi cái như thế đều là ứng viên để chuyển sang một tuyến riêng.
4. Nếu ngày mai một hostname của đường hầm được bật lên mà chưa có Access app, thứ gì sẽ chặn nó lại? Nếu câu trả lời là “tôi sẽ nhớ”, hãy viết bước preflight.
5. Các địa chỉ riêng của bạn có nằm trong một dải mà những mạng bạn ghé qua sẽ không bao giờ dùng không?

Hãy hình dung một đội nhỏ làm chung một ứng dụng. Hai lập trình viên, hay năm, cũng được. Không phải các chuyên gia mỗi người một mảng, mà là những người mỗi người trên nhánh riêng của mình, ôm trọn một tính năng từ migration cơ sở dữ liệu, qua API, đến màn hình trên ứng dụng di động. Đó là cách vận hành hay cho một đội, và kể từ khi có lập trình viên thứ hai, nó có một lỗi lặp đi lặp lại: tin nhắn “Có ai đang dùng staging không?”

Đằng sau tin nhắn ấy là một lập trình viên đã làm xong tính năng, muốn tester hoặc designer xem, mà không được, vì staging đang chạy nhánh của người thứ hai, còn dev đang chạy nhánh của người thứ ba, cái nhánh đã làm hỏng đăng nhập hai ngày trước và từ đó chưa được triển khai lại. Vài người, hai môi trường dùng chung, và một luồng chat làm việc xếp lịch.

Đó không phải vấn đề con người. Đó là vấn đề topology. Mỗi lập trình viên đều coi môi trường là nơi nhánh của mình trở thành thật, nên môi trường đang làm thay việc mà merge đáng lẽ phải làm, mỗi lần một nhánh, và những người còn lại xếp hàng chờ.

Tôi đã mô tả hình dạng production của stack mình trong My Current Stack: Django chạy trên những máy rẻ nhất của Fly.io, Postgres đứng sau một bộ gộp kết nối (connection pooler), Redis cho cache và tầng Channels, một ứng dụng WebSocket riêng, một worker chạy việc nền, một bucket tương thích S3 cho tệp, một dịch vụ xác thực bên ngoài, Cloudflare đứng trước, và một ứng dụng di động nói chuyện với tất cả. Bài này kể tôi đã biến stack ấy thành thứ mà với bất kỳ nhánh nào, lập trình viên chỉ cần gắn một nhãn lên PR là vài phút sau có ngay bản sao công khai, có HTTPS, của toàn bộ hệ thống, không phải nhờ ai khác và không ai phải cấp phát (provision) cho, mà cũng không cần cụm Postgres thứ hai, Redis thứ hai hay bucket thứ hai. Hạ tầng vẫn dùng chung. Điều thay đổi là mọi tài nguyên dùng chung học cách bị cắt lát theo một cái tên, và cái tên ấy đến từ nhánh. Không có gì trong đó giả định quy mô đội: thiết kế này giống hệt nhau cho hai lập trình viên hay hai mươi, thứ duy nhất tăng lên là danh sách ứng dụng, và việc đó đã có bộ dọn dẹp (sweeper) lo. Tôi dựng nó, chạy ba nhánh cùng lúc, làm hỏng ở hai chỗ không lường trước, rồi dỡ đi, tất cả trong một buổi chiều; các kết quả bên dưới lấy từ lần chạy đó.

Vì sao một môi trường dùng chung không chịu nổi quá một lập trình viên

#

Một môi trường dev dùng chung có sẵn một giả định: chỉ có một “phiên bản code hiện tại” mà ai cũng muốn xem. Điều đó đúng với một lập trình viên, hoặc với một nhóm cùng bước trên một dòng thay đổi duy nhất. Nó hết đúng ngay khi người thứ hai bắt đầu một tính năng theo lịch khác, và với kiểu sở hữu trọn gói thì tính năng nào cũng thế. Từ đó, mọi thứ môi trường nắm giữ đều thành thứ bị tranh:

• Code đã triển khai. Ai triển khai sau cùng thì thắng. Công việc của những người còn lại vô hình cho đến khi họ triển khai lại, và việc đó xóa của người trước.
• Schema cơ sở dữ liệu. Đây là chỗ cắn đau nhất khi mỗi người sở hữu mô hình dữ liệu của tính năng mình. Nhánh thứ nhất thêm một cột. Nhánh thứ hai, triển khai một giờ sau, không biết về cột đó và ORM bắt đầu lỗi khi insert. Hoặc cả hai nhánh cùng có migration 0042_*, cơ sở dữ liệu dùng chung rơi vào trạng thái không khớp lịch sử migration của ai, rồi ai đó reset nó, xóa luôn dữ liệu test mà người thứ ba mất cả buổi chiều chuẩn bị.
• Cache. Thay đổi serializer của một nhánh bị cache dưới đúng những khóa Redis mà code nhánh khác đọc. Các báo cáo lỗi sinh ra từ đó khó hiểu và ngốn mỗi cái một buổi sáng.
• Tích hợp bên thứ ba. Một OAuth callback, một URL webhook, một chứng chỉ push. Nhánh của ai đang được triển khai thì nhánh ấy nhận sự kiện.
• Tester. Họ chỉ test được thứ đã triển khai, nên họ test từng tính năng theo thứ tự môi trường tình cờ bị chiếm, chứ không theo thứ tự tính năng sẵn sàng.

Nhóm ứng phó bằng hệ thống đặt chỗ: một luồng chat, một tin nhắn ghim, một bot /claim staging. Đó là một cái khóa, và khóa đặt lên nơi duy nhất công việc của bạn có thể được nhìn thấy là khóa đặt lên tốc độ giao hàng. Với hai người thì chỉ hơi khó chịu. Với ba người thì tuần thuận lợi còn chịu được. Thêm người thứ tư, hoặc có một tính năng giữ staging ba ngày để qua lại với designer, là hết chịu nổi.

Cách sửa đầu tiên người ta với tới là môi trường dùng chung thứ ba, “dev2” hay “uat”. Nó mua được vài tuần. Hàng chờ chỉ có thêm một làn.

Cách sửa thật sự là nhận ra dev và staging chưa bao giờ là môi trường. Chúng là trạng thái hiện tại của nhánh ai đó, kèm một URL. Nếu chúng là thế, thì số lượng đúng là số nhánh mà cả đội đang quan tâm lúc này, và vòng đời đúng là vòng đời của nhánh.

Mô hình: nhánh chính là môi trường

#

Đây là trạng thái đích.

Hãy nhìn lại trong bảng xem ai tạo và ai hủy: mục nào cũng là một sự kiện git hoặc một cái đồng hồ. Git chính là mặt phẳng điều khiển (control plane). Tập hợp môi trường cần tồn tại được suy thẳng từ tập hợp nhánh đang tồn tại, và việc duy nhất của tự động hóa là giữ cho thực tế khớp với nó: nhãn trên PR thì tạo, mỗi lần push sau đó thì cập nhật, đóng hay merge PR thì hủy, và một job chạy hằng đêm dọn nốt những gì ba bước trước bỏ sót. Cũng không phải nhánh nào cũng có môi trường: nhãn chính là cái cổng, một cú bấm của lập trình viên, nên một lần push để sao lưu hay bản cập nhật thư viện của bot không tốn gì. Không ai cấp phát môi trường cả. Không phải kỹ sư DevOps nhận ticket, không phải bot bạn gọi trong kênh chat, không phải AI agent bạn phải nhắc (prompt) mỗi lần. Nhánh đầu tiên của lập trình viên thứ mười có môi trường theo đúng cách nhánh của người thứ nhất đã có: vì PR của nó được gắn nhãn. Nếu vẫn phải nhờ đến một người, thì hệ thống chưa mở rộng được; hàng đợi chỉ đổi chỗ thôi.

Và quy tắc khiến nó vận hành: mọi tài nguyên mà một môi trường chạm vào đều được đặt tên theo nhánh, một cách tất định. Không theo lập trình viên, không theo ticket, không theo số PR vốn không tồn tại cho đến khi ai đó mở. Theo nhánh, vì nhánh là thứ lập trình viên thật sự làm việc cùng, và vì tên tất định nghĩa là lần chạy ./scripts/env up thứ hai trên cùng nhánh sẽ tìm thấy môi trường đã tạo thay vì tạo thêm cái mới.

Tên gồm một slug cho người đọc và một mã băm ngắn để đảm bảo duy nhất:

branch=$(git rev-parse --abbrev-ref HEAD)              # feature/payments-retry
slug=$(printf '%s' "$branch" | tr '[:upper:]/_ ' '[:lower:]---' | tr -cd 'a-z0-9-' | cut -c1-20)
hash=$(printf '%s' "$branch" | sha256sum | cut -c1-6)
ENV="${slug%-}-${hash}"                                 # feature-payments-retr-3f9a1c

feature-payments-retr-3f9a1c là môi trường. Chuỗi đó trở thành tên ứng dụng Fly, tên cơ sở dữ liệu Postgres (gạch ngang đổi thành gạch dưới), tiền tố khóa Redis, tiền tố đối tượng trong bucket, environment trên công cụ theo dõi lỗi, và nhãn ngoài cùng bên trái của tên miền. Ai biết tên nhánh đều tính ra được. Không phải tra cứu ở đâu.

Câu cuối ấy chính là thiết kế. Không có sổ đăng ký môi trường và không có người điều phối. env up, env down, Cloudflare Worker định tuyến tên miền, và trình quét hằng đêm, mỗi thứ tự tính lại tên từ nhánh một cách độc lập và khớp nhau nhờ cấu trúc. Riêng Cloudflare không điều phối gì cả: Worker là một hàm thuần từ tên miền sang ứng dụng Fly, và nó không bao giờ biết một môi trường vừa được tạo hay hủy. Ứng dụng tồn tại thì yêu cầu đến nơi; không thì Fly trả lời bằng lỗi của chính nó.

Ba điều rút ra từ đây.

Thứ nhất, “ai đang dùng staging” không còn là câu hỏi. Có feature-payments-retr-3f9a1c-dev.example.com và có fix-login-redirect-8b21e0-dev.example.com, mỗi cái thuộc về người đang ở nhánh đó.

Thứ hai, staging trở thành buổi tổng duyệt trung thực của prod thay vì bãi rác. Nó được dựng từ chính image sẽ lên prod, trên cơ sở dữ liệu nhân bản vài phút trước từ snapshot có hình dạng prod. Chạy được ở đó thì biến số duy nhất còn lại trên prod là dữ liệu của prod.

Thứ ba, mỗi lập trình viên có quyền lực mà không cần root trên bất cứ thứ gì dùng chung. Bán kính nổ của một môi trường nhánh là chính môi trường nhánh đó. Người thứ tư vào ngày đầu có thể triển khai gì tùy thích lên nhánh mình, và kết cục tệ nhất là nhánh của họ hỏng.

fly.io/dashboard/my-org

Dùng chung về vật lý, tách biệt về logic

#

Phiên bản cám dỗ của “mỗi nhánh một môi trường” là sao chép toàn bộ: mỗi cái một cụm Postgres, một Redis, một bucket. Sạch sẽ, và là một cuộc đổi chác sai. Một cụm Fly Postgres là một máy cộng một volume cộng một lần khôi phục; một Redis là thêm một máy nữa; bạn sẽ chờ vài phút cho mỗi môi trường và trả tiền cho hàng chục cơ sở dữ liệu nằm không. Trình quét sẽ phải dọn bốn loại thứ thay vì một.

Thay vào đó, mỗi dịch vụ dùng chung được cấp phát một lần cho cả tổ chức preview, cỡ như một prod nhỏ, và mỗi môi trường nhận một lát cắt khóa theo $ENV. Đây là bảng tôi muốn dán lên tường:

Hai dòng trong đó đáng nói thêm một câu.

Postgres: cơ sở dữ liệu, không phải schema. Cách khác để cắt lát một cụm là mỗi môi trường một schema, đặt search_path theo từng kết nối. Django làm được nếu bạn nhét -c search_path=... qua options của kết nối, nhưng bộ gộp kết nối ở chế độ transaction bỏ qua tham số khởi động trừ khi bạn bảo nó đừng, và dù có thế thì mọi kết nối trong pool rốt cuộc cũng phải thuộc về một môi trường. Đó là nguồn của những lỗi kiểu “sao truy vấn của tôi lại chạm bảng khác”, thứ mà mỗi môi trường một cơ sở dữ liệu đơn giản là không có. Cơ sở dữ liệu là ranh giới cứng, CREATE DATABASE ... TEMPLATE tạo một cái trong vài giây, và DROP DATABASE xóa nó không để lại gì. Các môi trường nhánh kết nối thẳng vào Postgres qua cổng 5433 thay vì qua bộ gộp kết nối, giống như worker chạy nền làm trên prod; pooler chỉ đáng giá ở mức đồng thời của production, thứ mà một môi trường nhánh không bao giờ thấy.

Bí mật: sinh mới, không dùng chung. Sẽ dễ nếu có một bộ bí mật dev rồi chép vào mọi môi trường. Đừng. Script env up sinh SECRET_KEY (ký phiên), ENCRYPTION_KEY (mọi thứ mã hóa khi lưu) và ENV_TOKEN (bearer token mà ứng dụng di động xuất trình, nói thêm bên dưới) mới cho mỗi môi trường và chỉ lưu trong kho bí mật của ứng dụng Fly đó. Nghĩa là cookie phiên của nhánh này vô giá trị trên nhánh khác, một token preview bị lộ chỉ mở được một preview, và lập trình viên không bao giờ thấy giá trị trừ khi cố tình tìm. Nếu bạn giữ bí mật trong một trình quản lý bí mật (secrets manager) riêng thay vì chỉ trong Fly, quy tắc vẫn vậy: đường dẫn là myapp/preview/$ENV/, và trình quét xóa đường dẫn cùng với môi trường. Những bí mật thật sự dùng chung giữa các môi trường chỉ là thông tin đăng nhập của chính hạ tầng dùng chung (URL quản trị Postgres, URL Redis, khóa truy cập bucket), và chúng nằm trong CI, không nằm trong môi trường nào.

Dòng Redis là dòng dễ nghi ngờ nhất, nên đây là bài kiểm tra. Đặt một khóa cache từ bên trong một môi trường, đọc từ môi trường kia, rồi liệt kê mọi khóa trong Redis dùng chung:

$ fly ssh console -a myapp-feature-profile-tagl-fa8832 -C "python manage.py shell -c \"from django.core.cache import cache; cache.set('who-am-i', 'tagline-branch', 600)\""
$ fly ssh console -a myapp-feature-profile-webs-dcb2e7 -C "python manage.py shell -c \"from django.core.cache import cache; print(cache.get('who-am-i'))\""
None

$ # every key in the shared Redis
  feature-profile-tagl-fa8832:1:who-am-i
  ...

Cùng một Redis, cùng tên khóa, môi trường kia không thấy gì.

Phần còn lại của bài là script đóng dấu $ENV lên tám dòng ấy, và các quy tắc giữ cho nó trung thực.

./scripts/env up

#

Đây là toàn bộ ý tưởng, dưới dạng một script lập trình viên chạy từ nhánh của mình. CI chạy cùng script; không có đường riêng cho CI để lệch đi. Trên laptop chỉ cần fly và git, không gì khác: SQL đi tới ứng dụng Postgres qua fly ssh, còn khóa Redis và đối tượng trong bucket của môi trường được chính máy của môi trường xóa trước khi nó bị hủy, nên laptop không giữ thông tin đăng nhập Redis hay bucket dùng chung ngoài một tệp env đã gitignore. Dưới đây là bản rút gọn, chỉ giữ những dòng quan trọng:

#!/usr/bin/env bash
# scripts/env up|down|name|url: one environment per branch on shared preview infrastructure
set -euo pipefail
ORG=${PREVIEW_ORG:-myapp-preview}; PG_APP=${PREVIEW_PG_APP:-myapp-preview-pg}; DOMAIN=${BASE_DOMAIN:-example.com}

branch=${BRANCH:-$(git rev-parse --abbrev-ref HEAD)}
[[ "$branch" == "main" ]] && { echo "main has staging, not a branch environment" >&2; exit 1; }
slug=$(printf '%s' "$branch" | tr '[:upper:]/_ ' '[:lower:]---' | tr -cd 'a-z0-9-' | cut -c1-20); slug=${slug%-}
ENV=${ENV_OVERRIDE:-${slug}-$(printf '%s' "$branch" | shasum -a 256 | cut -c1-6)}   # the sweeper passes the name
APP="myapp-${ENV}"; DB="env_${ENV//-/_}"; HOST="${ENV}-dev.${DOMAIN}"

pg() { fly ssh console -a "$PG_APP" -q -C "psql postgres://postgres:${PG_PASSWORD}@localhost:5433/postgres -At -c \"$1\""; }
exists() { fly apps list --org "$ORG" --json | grep -q "\"Name\": *\"$APP\""; }

up() {
  echo "== $branch -> $ENV"
  exists || fly apps create "$APP" --org "$ORG"                         # idempotent
  [[ "$(pg "SELECT 1 FROM pg_database WHERE datname='$DB'")" == "1" ]] || pg "CREATE DATABASE $DB TEMPLATE seed_template"

  have=$(fly secrets list -a "$APP" --json | grep -o '"Name": *"[^"]*"' | cut -d'"' -f4 || true)
  gen() { grep -qx "$1" <<<"$have" || echo "$1=$(openssl rand -hex 32)"; }   # generated once, never rotated by a later `up`
  { gen SECRET_KEY; gen ENCRYPTION_KEY; gen ENV_TOKEN
    echo "ENV_NAME=$ENV"; echo "ALLOWED_HOSTS=$HOST,$APP.fly.dev"
    echo "DATABASE_URL=postgres://postgres:${PG_PASSWORD}@${PG_APP}.flycast:5432/${DB}"
    # ... plus the shared Redis URL and bucket credentials
  } | fly secrets import -a "$APP" --stage

  fly deploy -a "$APP" --config fly.preview.toml --remote-only --ha=false \
    --build-arg GIT_SHA="$(git rev-parse --short HEAD)" --build-arg GIT_BRANCH="$branch"
  echo "https://$HOST"
}

down() {
  [[ "$APP" =~ ^myapp-[a-z0-9-]+-[0-9a-f]{6}$ ]] || { echo "refusing to destroy $APP" >&2; exit 1; }
  if exists; then
    fly machine start -a "$APP" >/dev/null 2>&1 || true                 # it may be suspended
    fly ssh console -a "$APP" -q -C "python manage.py teardown_env" || echo "warning: cleanup failed; the sweeper will catch it" >&2
    fly apps destroy "$APP" --yes
  fi
  pg "DROP DATABASE IF EXISTS $DB WITH (FORCE)" || true
}

case "${1:-}" in up) up ;; down) down ;; name) echo "$ENV" ;; url) echo "https://$HOST" ;; esac

Trong bản demo tôi chạy nó từ laptop thay vì push, vì ba nhánh này là đồ dùng một lần tôi không muốn để lại trong lịch sử kho, và tôi muốn nhìn output chạy ra từng dòng. Khi cả đội dùng thì không ai gõ lệnh này cả: workflow gắn nhãn ở phần dưới chạy đúng script này, và những gì bạn thấy tiếp theo là thứ sẽ nằm trong log của Actions. Đây là những gì nó in ra lần đầu, trên chính nhánh chứa bộ công cụ:

$ ./scripts/env up
== feature/branch-environments -> feature-branch-envir-c65cb4
New app created: myapp-feature-branch-envir-c65cb4
CREATE DATABASE
Secrets have been staged, but not set on VMs. Deploy or update machines in this app for the secrets to take effect.
==> Building image
image size: 139 MB
✔ Machine 1a2b3c4d5e6f78 [app] update finished: success
https://feature-branch-envir-c65cb4-dev.example.com

$ curl -s https://feature-branch-envir-c65cb4-dev.example.com/api/version/
{"environment": "feature-branch-envir-c65cb4", "branch": "feature/branch-environments", "commit": "a1b2c3d4", "region": "syd"}

Khoảng hai phút rưỡi từ lệnh đến URL, phần lớn là build image. Lần up thứ hai trên cùng nhánh, sau một commit nữa, không in “New app created” hay “CREATE DATABASE”, stage đúng các tên bí mật cũ mà không sinh lại những cái được sinh, rồi build lại: cùng URL, commit mới.

Vài lựa chọn trong đó xứng đáng mỗi cái một câu.

fly.preview.toml không phải fly.toml. Prod chạy API, máy chủ WebSocket và worker chạy nền như các ứng dụng Fly và nhóm tiến trình riêng để mỗi thứ mở rộng theo chỉ số của mình, đó là toàn bộ lập luận của bài về stack. Một môi trường nhánh không cần mở rộng; nó cần là một máy. Nên cấu hình preview chỉ có một tiến trình: script khởi chạy (entrypoint) của container có thêm một chế độ preview, chạy migration rồi khởi động một máy chủ ASGI có bật WebSocket. Channels vốn đã định tuyến cả lưu lượng HTTP lẫn WebSocket trong cùng một ứng dụng ASGI, nên một tiến trình phục vụ cả ứng dụng. Ở chế độ đó các view đồng bộ chạy kiểu thread-sensitive, gần như mỗi lần một yêu cầu, chính là cuộc đổi chác tôi đã rời bỏ trên prod và lại đúng ở đây, vì không ai test một nhánh mà nhận ra.

# fly.preview.toml (the app name comes from `fly deploy -a`)
app = 'placeholder'
primary_region = 'syd'

[processes]
  app = "/app/entrypoint.sh preview"   # migrate, then one ASGI server for HTTP and WebSockets

[env]
  DJANGO_SETTINGS_MODULE = 'myapp.settings'
  DEBUG = 'False'

[http_service]
  internal_port = 8000
  force_https = true
  auto_stop_machines = 'suspend'
  auto_start_machines = true
  min_machines_running = 0
  [[http_service.checks]]
    path = '/healthz'
    [http_service.checks.headers]
      Host = '127.0.0.1'               # the app's own hostname isn't known to a static file

[[vm]]
  size = 'shared-cpu-1x'
  memory = '1gb'

auto_stop_machines = "suspend", min_machines_running = 0. Một môi trường nhánh không ai mở từ sau bữa trưa nên tốn số không. Suspend thay vì stop cho ra khoảng 3 giây khôi phục mà tôi đạt được sau khi đuổi theo lỗi 504 thay vì 30 giây khởi động lạnh, và ở đây ngay cả 30 giây cũng chấp nhận được. Hai trong ba môi trường demo đã suspended trong fly apps list chỉ một phút sau khi triển khai xong.

fly.io/apps/myapp-feature-profile-tagl-fa8832

DEBUG = False, cùng module settings với prod. Môi trường nhánh là một URL công khai. Nó nên hành xử như prod ở mọi mặt quan trọng cho việc test (HTTPS thật, cookie thật, cùng health check) và khác prod ở mọi mặt có thể làm ai đó bị hại. Thay vì một tệp settings riêng cho preview, sự khác biệt được mang bởi các bí mật mà env up đặt: khóa thanh toán sandbox, không có thông tin quản trị của dịch vụ xác thực, và ENV_NAME bật mọi tiền tố bên dưới.

Một cấu hình cắt lát mọi thứ. ENV_NAME là núm vặn mới duy nhất trong settings, và được áp ở bốn chỗ:

ENV_NAME = os.getenv("ENV_NAME", "")
_prefix = f"{ENV_NAME}/" if ENV_NAME else ""

CACHES["default"]["KEY_PREFIX"] = ENV_NAME                           # every cache key
CHANNEL_LAYERS["default"]["CONFIG"]["prefix"] = f"{ENV_NAME}:asgi"  # Channels group and channel names
STORAGES["default"]["OPTIONS"]["location"] = f"{_prefix}media"      # uploads
STORAGES["staticfiles"]["OPTIONS"]["location"] = f"{_prefix}static"

Bỏ sót chỗ channels thì máy chủ WebSocket của hai nhánh dùng chung tên nhóm, và tin nhắn gửi ở môi trường này hiện ra ở môi trường kia. Đó là loại lỗi tốn cả ngày.

Còn chỗ thứ năm tôi chỉ tìm thấy khi đọc Redis dùng chung sau đó. Cái khóa lúc khởi động từ bài về 504, thứ cho phép mỗi image chỉ một máy chạy migration trong khi các máy khác chờ, vốn đặt tên khóa theo tham chiếu image. Hai môi trường nhánh dựng từ cùng một commit có cùng image. Cái thứ hai sẽ thấy dấu “done” của cái thứ nhất và bỏ qua migration của chính nó trên cơ sở dữ liệu chưa migration của chính nó. Giờ tên môi trường là một phần của tên khóa, và khóa nằm dưới tiền tố. Đó là loại chuyện mà thiết kế hạ tầng dùng chung cứ sinh ra mãi: mọi thứ ngầm là “theo lần triển khai” phải được làm rõ thành theo môi trường, và bạn không biết cái gì là ngầm cho đến khi nhìn vào.

Cơ sở dữ liệu được nhân bản, không migration từ rỗng. Đó là mục tiếp theo.

Cơ sở dữ liệu: một mẫu, nhân bản trong vài giây

#

Cơ sở dữ liệu của một môi trường nhánh có thể là một trong ba thứ. Dùng chung với mọi người, thứ đưa chúng ta đến đây. Rỗng, migration từ số không rồi đổ fixture: tất định, nhưng fixture chưa bao giờ tốt bằng dữ liệu có hình dạng thật và luôn cũ mười tám tháng. Hoặc một bản nhân bản từ snapshot có hình dạng prod: số dòng thực tế, những giá trị null thực tế trong các cột mà fixture cứ tưởng luôn có dữ liệu, cái migration tức thì trên bảng rỗng nhưng mất bốn mươi phút trên bảng thật sẽ lộ mặt.

Chọn cách thứ ba, giữ cách thứ hai làm một kiểm tra chỉ chạy trên CI. Và thứ khiến cách thứ ba đủ nhanh để làm cho từng nhánh là một tính năng Postgres mà hầu hết mọi người quên là có tồn tại:

-- Nightly, on the preview cluster. Restore last night's prod backup into seed_raw,
-- run the anonymiser, then freeze it as a template nobody can connect to.
ALTER DATABASE seed_raw RENAME TO seed_template;
UPDATE pg_database SET datistemplate = true, datallowconn = false WHERE datname = 'seed_template';

-- Per branch, in the time it takes to copy the files:
CREATE DATABASE env_feature_payments_retr_3f9a1c TEMPLATE seed_template;

CREATE DATABASE ... TEMPLATE là sao chép ở mức tệp trong cụm. Vài gigabyte là vài giây, không phải vài phút như pg_restore. Mẫu không được có kết nối mở trong khi đang nhân bản, đó là điều datallowconn = false đảm bảo, và cũng là lý do tác vụ đêm dựng vào seed_raw rồi đổi tên ở cuối thay vì khôi phục đè lên mẫu đang sống.

Trong demo, mẫu được dựng bằng tay thay vì từ dump prod: một đường hầm tới cụm preview bằng fly proxy, manage.py migrate, rồi các lệnh seed sẵn có của repo để tạo một bộ dữ liệu nhỏ nhưng sát với thực tế. Mười chín megabyte. Ba bản nhân bản của nó xuất hiện trong cụm khi ba nhánh khởi lên, mỗi cái 19 MB, mỗi cái chưa tới một giây:

$ fly ssh console -a myapp-preview-pg -C "psql ... -c '\l'"
             datname             | template | size
---------------------------------+----------+-------
 env_feature_branch_envir_c65cb4 | f        | 19 MB
 env_feature_profile_tagl_fa8832 | f        | 19 MB
 env_feature_profile_webs_dcb2e7 | f        | 19 MB
 seed_template                   | t        | 19 MB

Cụm preview là một node Fly Postgres không quản lý, shared-cpu-1x với volume 1 GB, khoảng hai đô la một tháng. Các môi trường nhánh kết nối tới nó qua .flycast trên mạng riêng; không có gì công khai.

Bộ ẩn danh hóa không phải tùy chọn. Khoảnh khắc dữ liệu prod có thể truy cập trên một tên miền -dev, nó phải không còn là dữ liệu prod: tên, email, số điện thoại, địa chỉ, văn bản tự do, tham chiếu thanh toán, token, tất cả bị ghi đè trước khi đổi tên. Nếu bộ ẩn danh hóa thất bại, mẫu của đêm trước được giữ lại và ai đó nhận tin nhắn. Đó là một việc nhỏ và là thứ khiến toàn bộ cách tiếp cận này chấp nhận được với người trả lời bảng câu hỏi về quyền riêng tư.

Script khởi chạy chạy migrate ở lần khởi động đầu của mỗi image, nên migration của chính nhánh được áp lên trên mẫu. Đó là bài kiểm tra trung thực đầu tiên cho câu “migration của tôi có chạy trên dữ liệu có hình dạng prod không”, và nó xảy ra trước khi ai đó mở URL.

Tên miền: một wildcard, một Worker, và hai điều tài liệu không nói

#

Mỗi môi trường cần một tên miền HTTPS công khai, và “công khai” chính là điểm mấu chốt: tester cầm điện thoại, designer ở mạng khác, product manager không chịu cài VPN. Fly cho mỗi ứng dụng myapp-$ENV.fly.dev miễn phí, và chỉ thế cũng chạy được. Nhưng tên miền *.fly.dev có ba vấn đề: gửi đi trông xấu, Cloudflare không đứng trước nên không có lớp bảo vệ nào của prod được áp dụng, và nếu muốn đặt chúng dưới tên miền của mình thì phải tạo mỗi môi trường một bản ghi DNS và một chứng chỉ, thêm một thứ nữa cho trình quét.

Phiên bản loại bỏ tất cả những thứ ấy là một wildcard và một Cloudflare Worker. Tôi đã định dùng *.dev.example.com. Hai điều đã chặn lại, và cả hai đều đáng biết trước khi bạn lên kế hoạch tương tự.

Universal SSL chỉ phủ một tầng wildcard. Chứng chỉ miễn phí của Cloudflare được cấp cho example.com và *.example.com. Nó không phủ *.dev.example.com; wildcard tầng hai cần Advanced Certificate Manager giá 10 đô la một tháng. Yêu cầu đầu tiên tới feature-branch-envir-c65cb4.dev.example.com chết vì lỗi bắt tay SSL trước khi bất cứ thứ gì của tôi kịp chạy. Cách sửa là giữ môi trường ở nhãn đầu tiên: feature-branch-envir-c65cb4-dev.example.com. Nó được chứng chỉ sẵn có phủ, và được bản ghi *.example.com đã proxy sẵn có phủ, chính bản ghi tôi dựng làm hố đen cho các trình quét lần mò những tên miền con bịa đặt. Vậy nên một môi trường hoàn toàn không cần DNS.

Redirect Rules chạy trước Workers. Với route đã đặt, mọi tên miền -dev đều trả 301 về trang chủ www mà Worker không hề chạy. Hố đen là một quy tắc chuyển hướng cấp zone, “mọi tên miền con khác → www”, và pha chuyển hướng của Cloudflare thực thi trước pha Workers. Quy tắc cần thêm một mệnh đề: and not ends_with(http.host, "-dev.example.com"). Script triển khai thêm nó khi up và gỡ khi down, vì một quy tắc ai đó sửa tay chính là thứ bị quên.

dash.cloudflare.com/…/example.com/rules/redirect-rules/…/edit

Phía DNS là bản ghi vốn đã có sẵn:

dash.cloudflare.com/…/example.com/dns/records

Gỡ xong hai thứ đó, việc định tuyến là một Worker duy nhất trên *-dev.example.com/*:

// dev-router.js: <env>-dev.example.com -> myapp-<env>.fly.dev
const DEV_SUFFIX = "-dev.example.com";
const ENV_NAME = /^[a-z0-9-]+-[0-9a-f]{6}$/;   // slug-hash, as scripts/env names them

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (!url.hostname.endsWith(DEV_SUFFIX)) return new Response("not a dev hostname", { status: 404 });
    const env = url.hostname.slice(0, -DEV_SUFFIX.length);
    if (!ENV_NAME.test(env)) return new Response(`no such environment: ${env}`, { status: 404 });

    url.hostname = `myapp-${env}.fly.dev`;
    const upstream = new Request(url, request);
    upstream.headers.set("X-Forwarded-Host", request.headers.get("host") ?? "");

    const res = await fetch(upstream);
    const out = new Response(res.body, res);
    out.headers.set("X-Robots-Tag", "noindex, nofollow");   // a half-finished branch is not for search engines
    out.headers.set("X-Dev-Environment", env);
    return out;
  },
};

Cloudflare kết thúc TLS trên wildcard, Worker tính tên miền Fly từ nhãn, và chứng chỉ *.fly.dev của chính Fly phủ chặng tới máy. Nâng cấp WebSocket đi qua fetch không đổi. Và vì route nằm trên zone, mọi thứ Cloudflare làm cho prod đều dùng được: quy tắc WAF, giới hạn tốc độ, chế độ chống bot, và Access.

dash.cloudflare.com/…/example.com/workers

Ba nhánh cùng chạy, một Worker, và câu trả lời của từng tên miền:

Mọi phản hồi 200 đều kèm X-Robots-Tag: noindex, nofollow và X-Dev-Environment: <env> do Worker thêm vào. Cái 404 là của chính Worker, trước cả khi hỏi Fly.

Cloudflare Access là thứ biến “công khai” thành “đến được với những người nên đến”. Một ứng dụng trên *-dev.example.com với chính sách “bất kỳ ai có email @example.com” và người dùng trình duyệt thấy trang đăng nhập một lần rồi không bao giờ phải nghĩ tới nữa. Designer, PM và tester dùng laptop đều được phủ. Tôi không thêm nó cho demo; các môi trường chạy một giờ với noindex và không có gì ngoài dữ liệu seed.

Nó không phủ được ứng dụng di động, vì ứng dụng native không hoàn tất được chuyển hướng đăng nhập của Access. Hai lối đi. Access hỗ trợ service token (cặp header CF-Access-Client-Id / CF-Access-Client-Secret) bỏ qua đăng nhập, và menu dev của ứng dụng di động có thể mang một cặp cho các tên miền dev. Hoặc đơn giản hơn, thêm một bypass Access cho /api/ và để Django từ chối mọi yêu cầu không có người dùng đã đăng nhập hoặc ENV_TOKEN của môi trường, chính cái token env up đã sinh cho đúng môi trường này. Dù cách nào, phía ứng dụng di động là một màn hình menu dev với hai trường, URL gốc và token, và ứng dụng tester đã cài sẵn giờ nói chuyện với nhánh đó. Không cần build mới. Kênh cập nhật qua mạng (OTA) vẫn trỏ về thứ ứng dụng được build cùng; URL gốc của API là cấu hình lúc chạy, không phải lúc build, và vốn nên như thế từ đầu.

Xác thực là dịch vụ dùng chung duy nhất được cố ý dùng chung. Danh tính không thuộc về môi trường nào; tester muốn đăng nhập bằng cùng tài khoản trên mọi nhánh. Một dự án dev trên dịch vụ xác thực, với example.com trong danh sách tên miền được ủy quyền phủ mọi tên miền -dev, và mọi môi trường xác minh ID token với nó. Bảng người dùng trong cơ sở dữ liệu mỗi môi trường là bản sao người dùng của mẫu, nên tài khoản của tester tồn tại ở mọi nơi mẫu có.

Tự động hóa môi trường xem trước bằng GitHub Actions: sự kiện vào, môi trường ra

#

Mọi thứ ở trên làm bằng tay thì ổn khi chỉ có bạn làm. Từ khi có lập trình viên thứ hai, nó phải xảy ra vì có gì đó xảy ra trong git, chứ không phải vì ai đó nhớ. Toàn bộ tự động hóa là bốn workflow, một cài đặt kho, một ruleset và một GitHub environment, và mỗi thứ ánh xạ một sự kiện git thành một lời gọi tới chính scripts/env mà lập trình viên chạy bằng tay. Không có đường riêng cho CI để lệch đi.

Workflow nhãn, push và delete

#

# .github/workflows/branch-env.yml
name: branch environment
on:
  pull_request:
    types: [labeled, unlabeled, synchronize, closed]
  delete:
  workflow_dispatch:
    inputs:
      branch: { description: branch to bring up without a PR, required: true }

concurrency:
  group: env-${{ github.head_ref || github.event.ref || inputs.branch }}
  cancel-in-progress: true

env:
  FLY_API_TOKEN: ${{ secrets.FLY_PREVIEW_TOKEN }}   # org-scoped deploy token; a separate preview org keeps it away from prod
  PG_PASSWORD: ${{ secrets.PREVIEW_PG_PASSWORD }}
  # ... the shared Redis URL and bucket credentials, the same way

jobs:
  up:
    # the gate: a PR carrying the `env` label, or someone asking for a branch by hand
    if: >-
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'pull_request' && github.event.action != 'closed'
        && contains(github.event.pull_request.labels.*.name, 'env'))
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { ref: "${{ github.head_ref || inputs.branch }}" }
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - id: env
        env: { BRANCH: "${{ github.head_ref || inputs.branch }}" }
        run: scripts/env up && echo "url=$(scripts/env url)" >> "$GITHUB_OUTPUT"
      - if: github.event_name == 'pull_request'
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: env
          message: "Branch environment: ${{ steps.env.outputs.url }}"

  down:
    # label removed, labelled PR closed or merged, or the branch itself deleted
    if: >-
      (github.event_name == 'pull_request' &&
        ((github.event.action == 'closed' && contains(github.event.pull_request.labels.*.name, 'env')) ||
         (github.event.action == 'unlabeled' && github.event.label.name == 'env'))) ||
      (github.event_name == 'delete' && github.event.ref_type == 'branch')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: BRANCH="${{ github.head_ref || github.event.ref }}" scripts/env down

Cái cổng là nhãn env, và đây là phần tôi sẽ bảo vệ mạnh nhất. Không có cổng, mỗi nhánh đều tốn một ứng dụng và một bản nhân bản cơ sở dữ liệu: nhánh ai đó push lên chỉ để sao lưu laptop, spike ngày mai sẽ bị squash, bản cập nhật thư viện mà bot mở lúc 3 giờ sáng. Nên chỉ push thì không có gì xảy ra, và chỉ mở PR cũng không có gì xảy ra. Gắn nhãn env lên PR thì môi trường được dựng lên, mỗi lần push khi nhãn còn đó thì nó được cập nhật, còn gỡ nhãn, đóng PR hay merge thì nó bị hạ xuống. Việc chọn tham gia vẫn là một sự kiện trên GitHub chứ không phải lời nhờ vả một ai, và đó là một cú bấm của đúng người biết có ai sẽ xem hay không. Bình luận ghim là giao diện người dùng: gắn nhãn cho PR, một bình luận hiện ra với URL có thể gửi cho bất kỳ ai, và nó cập nhật tại chỗ sau mỗi lần push thay vì chồng lên nhau. workflow_dispatch lo cho nhánh bạn muốn dựng trước khi có PR, còn ./scripts/env up từ laptop lo phần còn lại.

Có hai kiểu cổng khác đáng biết. Bộ lọc theo tên nhánh (branches: ['feature/**', 'fix/**']) không cần PR nhưng khiến mọi nhánh tính năng đều phải trả tiền. “Mọi PR không phải bản nháp” là kiểu tự động nhất, và là lựa chọn đúng nếu đội bạn mở PR muộn, chỉ khi đã sẵn sàng. Tôi chọn nhãn vì nó đặt quyết định chi phí vào tay người có ngữ cảnh, và vì có thể rút lại mà không phải đóng gì cả. Một tác dụng phụ tôi thích: các lần chạy pull_request từ fork không nhận được secret, nên fork không thể dựng môi trường.

concurrency quan trọng hơn vẻ ngoài. Một loạt push nhanh vào một nhánh sẽ hủy các lần triển khai trước thay vì để chúng chạy đua; hai fly deploy cùng lúc vào cùng ứng dụng kết thúc bằng việc một cái thua.

closed lo việc dỡ bỏ cho mọi thứ từng có PR, merge hay không. Sự kiện delete là lưới an toàn cho nhánh dựng bằng workflow_dispatch mà rốt cuộc không có PR, và nó chỉ kích hoạt nếu nhánh thật sự bị xóa. Đó là một cài đặt kho, Automatically delete head branches, mặc định tắt. Bật lên, bấm Merge sẽ đóng PR và xóa nhánh, và chỉ một trong hai sự kiện ấy cũng đủ để chạy env down. Nút merge chính là việc dỡ bỏ.

gh api -X PATCH repos/org/myapp -f delete_branch_on_merge=true

FLY_PREVIEW_TOKEN là dòng nguy hiểm trong tệp. Nó tạo và hủy được ứng dụng, và nếu $APP có lúc nào là thứ gì ngoài môi trường nhánh, nó có thể hủy prod. Hai lớp bảo vệ, và tôi giữ cả hai: token giới hạn trong một tổ chức Fly riêng để nó theo đúng nghĩa đen không nhìn thấy tổ chức production (trong demo tôi dùng tổ chức production để khỏi phải gắn thanh toán cho tổ chức mới, và chỉ dựa vào lớp thứ hai); và down() từ chối mọi tên ứng dụng không khớp mẫu slug-hash.

Kiểm tra mà môi trường nhánh không tự làm được

#

Một nhánh chỉ thấy migration của chính nó, nên kiểm tra quan trọng chạy trên pull request đối với trạng thái đã merge main, và đó là kiểm tra trạng thái duy nhất main yêu cầu:

# .github/workflows/migrations-check.yml
name: migrations
on:
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:18
        env: { POSTGRES_PASSWORD: ci, POSTGRES_DB: ci }
        ports: ['5432:5432']
        options: --health-cmd pg_isready --health-interval 5s --health-retries 10
    env:
      DATABASE_URL: postgres://postgres:ci@localhost:5432/ci
      SECRET_KEY: ci-only
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-python@v5
        with: { python-version: '3.14' }
      - run: pip install -r requirements.txt
      - name: Merge main into the branch (a conflict here fails the check too)
        run: |
          git config user.email ci@example.com && git config user.name ci
          git merge --no-edit origin/main
      - name: One leaf in the migration graph
        run: python manage.py makemigrations --check --dry-run
      - name: The full chain applies from nothing
        run: python manage.py migrate --noinput

Ba mươi giây. Chính nó biến va chạm 0042 / 0042 từ bất ngờ ngày phát hành thành một dấu đỏ trên PR của lập trình viên thứ hai; mục migration bên dưới cho thấy nó nổ thật.

Quy tắc trên main

#

Không gì trong đây trụ được nếu nhánh sống một tháng hay ai đó push thẳng lên main. Các quy tắc thiên về giữ môi trường nhỏ và migration mới hơn là bảo vệ:

• main được bảo vệ và luôn triển khai được. Chỉ merge qua PR với kiểm tra migrations xanh đối với main hiện tại (kiểm tra trạng thái nghiêm ngặt, nên PR xanh tuần trước phải chạy lại khi main tiến lên). Lịch sử tuyến tính, không force-push, không xóa.
• Nhánh tính năng phải ngắn. Nhánh mở hai tuần có môi trường tụt sau main hai tuần và migration có thêm hai tuần khả năng va với của người khác. Tính năng kéo dài một tháng thì merge vào main từng phần sau feature flag. Thứ sống lâu là flag, không phải nhánh.
• Một nhánh, một môi trường, một cơ sở dữ liệu. Cách đặt tên đã đảm bảo.
• Chỉ tag phát hành mới lên prod. Image được build một lần từ tag; staging và prod chạy image đó, không build lại.
• PR chạm vào migrations/ được một trong hai người còn lại review. Bên dưới.

Dưới dạng ruleset, áp một lần bằng gh api -X POST repos/org/myapp/rulesets --input ruleset-main.json:

{
  "name": "main", "target": "branch", "enforcement": "active",
  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    { "type": "required_linear_history" },
    { "type": "pull_request",
      "parameters": { "required_approving_review_count": 1, "dismiss_stale_reviews_on_push": true,
                      "required_review_thread_resolution": true } },
    { "type": "required_status_checks",
      "parameters": { "strict_required_status_checks_policy": true,
                      "required_status_checks": [ { "context": "check" } ] } }
  ]
}

Một nếp gấp thành thật. Kho này là kho riêng tư trên gói GitHub Free, và trên Free, bảo vệ nhánh và ruleset chỉ có cho kho công khai; API trả lời 403 Upgrade to GitHub Pro or make this repository public. Cài đặt delete_branch_on_merge, các environment và workflow đều chạy trên Free. Vậy nên với một đội nhỏ trên kho riêng tư Free, ruleset ở trên là một quy ước: workflow migrations vẫn chạy và vẫn đỏ, nhưng không gì làm xám nút merge. Đó là quyết định 4 đô la một tháng, và tôi sẽ quyết ngay khoảnh khắc có người thứ hai được phép merge.

Không có nhánh develop và không có nhánh release/*. Git-flow được thiết kế quanh giả định rằng tích hợp đắt đỏ và phải gom theo đợt. Môi trường nhánh làm tích hợp rẻ đi, nên việc gom đợt biến mất.

Staging là môi trường của một tag, và prod là một lần thăng cấp

#

Staging tái sử dụng toàn bộ bộ máy. Một tag v* trên main chạy scripts/env up với tên nhánh staging/v1.42.0, cách đặt tên biến nó thành staging-v1-42-0-<hash>: cùng cơ sở dữ liệu nhân bản từ mẫu, cùng máy suspend khi rảnh, cùng sơ đồ tên miền. Khác biệt là chuyện xảy ra sau đó:

# .github/workflows/release.yml (abridged)
on:
  push:
    tags: ['v*']
jobs:
  staging:
    steps:
      - run: BRANCH="staging/${GITHUB_REF_NAME}" scripts/env up
      - run: echo "image=$(fly image show -a "myapp-$(BRANCH=staging/$GITHUB_REF_NAME scripts/env name)" --json | jq -r '…')" >> "$GITHUB_OUTPUT"
  production:
    needs: staging
    environment: production        # required reviewer on this environment = the promotion gate
    steps:
      - run: fly deploy --config fly.api.toml --image "${{ needs.staging.outputs.image }}"
      - run: fly deploy --config fly.ws.toml  --image "${{ needs.staging.outputs.image }}"
      - run: BRANCH="staging/${GITHUB_REF_NAME}" scripts/env down

Job production chờ một GitHub environment có người duyệt bắt buộc. Ai đó xem staging, bấm Approve, và prod nhận cùng image staging đã chạy, theo tham chiếu, không build lại. Bước cuối hủy staging vì nó đã xong việc. Nếu không ai duyệt, ứng viên phát hành bị từ chối, và trình quét gỡ staging khi “nhánh” của nó (staging/v1.42.0 chưa bao giờ tồn tại trên origin) rớt kiểm tra còn sống. Không thứ gì được tồn tại mà không có lý do trình quét kiểm chứng được.

Trình quét hằng đêm

#

# .github/workflows/sweep-envs.yml
on:
  schedule:
    - cron: '0 14 * * *'     # 02:00 NZST
  workflow_dispatch:
jobs:
  sweep:
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: scripts/sweep-envs

fetch-depth: 0 vì trình quét cần mọi nhánh từ xa và ngày commit cuối của chúng, chứ không phải một commit Actions checkout mặc định. workflow_dispatch để có thể chạy tay sau sự cố.

Lập trình viên thật sự làm gì

#

Push một nhánh, mở PR, và gắn nhãn env khi muốn ai đó xem. Danh sách chỉ có thế. Một URL xuất hiện trên PR trong vòng ba phút, cập nhật sau mỗi lần push, và biến mất khi PR được merge hoặc đóng. Kiểm tra migration báo cho họ trước bất kỳ ai nếu họ va với đồng đội. Không ai giành staging vì không có staging để giành, và không ai dỡ gì cả vì dỡ bỏ chính là merge.

Còn người đã dựng hệ thống này, sau đó phải làm gì cho mỗi nhánh? Không gì cả. Postgres, Redis và bucket dùng chung được cấp phát một lần, các bí mật được đưa vào Actions một lần, và từ đó việc lặp lại duy nhất là đọc log của trình quét vào sáng thứ Hai. Không hàng đợi ticket, không bot để gọi, không ai để nhắc.

Dỡ bỏ không tin vào việc dỡ bỏ

#

env down là trường hợp thông thường, và phần thú vị là ai dọn. Khóa Redis và đối tượng trong bucket thuộc về các dịch vụ dùng chung, và laptop chạy down không cần thông tin đăng nhập của cả hai, vì chính máy của môi trường đã có chúng và đã biết tiền tố của mình. Nên down khởi động máy nếu nó đang suspend, chạy một lệnh dọn dẹp nhỏ trên đó, rồi mới hủy ứng dụng và xóa cơ sở dữ liệu. Môi trường tự dọn dẹp sau mình:

$ BRANCH=feature/profile-website ./scripts/env down
redis: deleted 0 keys under feature-profile-webs-dcb2e7:*
bucket: deleted 278 objects under feature-profile-webs-dcb2e7/
Destroyed app myapp-feature-profile-webs-dcb2e7
DROP DATABASE

$ curl -s -o /dev/null -w '%{http_code}\n' https://feature-profile-webs-dcb2e7-dev.example.com/api/version/
530

Cái 530 lại là điểm về điều phối: Worker vẫn định tuyến tên miền, Fly không có gì ở đó, và không ai phải báo cho Cloudflare.

Lệnh dọn dẹp từ chối chạy khi không có ENV_NAME, vì với tiền tố rỗng nó sẽ xóa sạch cả bucket dùng chung. Lớp bảo vệ ấy là toàn bộ lý do nó tồn tại như một lệnh bên trong ứng dụng thay vì ba dòng trong shell script.

Môi trường vẫn rò rỉ. Một nhánh bị xóa khi GitHub Actions đang gặp sự cố. Một lập trình viên chạy env up từ laptop cho một thử nghiệm và không bao giờ push. Một fly apps destroy thất bại thoáng qua và || true nuốt mất. Ba tháng sau có bốn mươi ứng dụng và một hóa đơn khiến ai đó hỏi chuyện gì đã xảy ra.

Nên có cơ chế thứ hai không tin cơ chế thứ nhất: trình quét hằng đêm trong bảng ở trên. Nó liệt kê mọi ứng dụng myapp-*, tìm ra mỗi cái thuộc nhánh nào, và hủy mọi cái có nhánh đã mất hoặc không được push trong bảy ngày. Một nhánh nằm không một tuần không cần URL sống; lần push tiếp theo dựng lại nó trong hai phút. Mã băm không đảo ngược được, nên trình quét tính tên môi trường cho mọi nhánh còn sống và hủy mọi ứng dụng không nằm trong tập đó, rồi xóa mọi cơ sở dữ liệu env_* không có ứng dụng đứng sau:

#!/usr/bin/env bash
# scripts/sweep-envs: nightly
set -euo pipefail
ORG=${PREVIEW_ORG:-myapp-preview}; TTL_DAYS=${TTL_DAYS:-7}
cutoff=$(( $(date +%s) - TTL_DAYS*86400 ))

git fetch --prune --quiet origin
live=""
while IFS=$'\t' read -r ts branch; do
  [[ "$branch" == "main" ]] && continue
  (( ts >= cutoff )) || continue
  live+="$(BRANCH="$branch" scripts/env name)"$'\n'
done < <(git for-each-ref --format='%(committerdate:unix)%09%(refname:short)' refs/remotes/origin | sed 's#^\([0-9]*\)\torigin/#\1\t#')

apps=$(fly apps list --org "$ORG" --json | grep -o '"Name": *"myapp-[^"]*"' | cut -d'"' -f4)
for app in $apps; do
  env="${app#myapp-}"
  [[ "$env" =~ ^[a-z0-9-]+-[0-9a-f]{6}$ ]] || continue       # not a branch environment (e.g. myapp-preview-pg)
  grep -qx "$env" <<<"$live" && continue
  echo "sweeping $app: branch gone or idle > ${TTL_DAYS}d"
  ENV_OVERRIDE="$env" scripts/env down || true
done
# ...then any env_* database with no app: DROP DATABASE.

Không nhánh demo nào từng được push (lần chạy từ laptop ở trên), nên dưới mắt trình quét tất cả đều đã mất; đó cũng chính là trạng thái mà một spike ai đó dựng từ laptop rồi không bao giờ push sẽ rơi vào sau một tuần. Nó tháo dỡ hai cái còn lại, gồm cả các khóa Redis mà môi trường tagline đã ghi:

$ ./scripts/sweep-envs
sweeping myapp-feature-branch-envir-c65cb4: branch gone or idle > 7d
redis: deleted 0 keys under feature-branch-envir-c65cb4:*
bucket: deleted 322 objects under feature-branch-envir-c65cb4/
Destroyed app myapp-feature-branch-envir-c65cb4
DROP DATABASE
sweeping myapp-feature-profile-tagl-fa8832: branch gone or idle > 7d
redis: deleted 3 keys under feature-profile-tagl-fa8832:*
bucket: deleted 278 objects under feature-profile-tagl-fa8832/
Destroyed app myapp-feature-profile-tagl-fa8832
DROP DATABASE

$ fly apps list --org myapp-preview | grep myapp-
 myapp-preview-pg │ myapp-preview │ deployed

(Một thứ nhỏ đã cắn: macOS đi kèm bash 3, không có mảng kết hợp. Phiên bản đầu của trình quét dùng nó và chết ở declare -A trên laptop của tôi. Phiên bản trên dùng danh sách phân cách bằng xuống dòng và chạy được ở mọi nơi.)

Chi phí là phần dễ chịu. Một máy suspend chỉ tốn rootfs, vài xu một tháng. Một cơ sở dữ liệu là 19 MB trên volume đã trả tiền. Redis chạy trên một gói trả theo mức dùng, hai mươi xu cho một trăm nghìn lệnh, ở mức test nhánh thì làm tròn thành không. Một tiền tố trong bucket tốn đúng phần nó lưu. Node Postgres dùng chung là khoản cố định duy nhất, khoảng hai đô la một tháng. Hai mươi nhánh đang hoạt động tốn cỡ một shared-cpu-1x chạy liên tục, và trình quét giữ ở hai mươi thay vì hai trăm. Cả buổi demo, ba môi trường trong một giờ cộng các phần dùng chung, rẻ hơn ly cà phê tôi uống trong lúc đó.

Migration qua nhiều nhánh, không có cơ sở dữ liệu dùng chung để cảnh báo

#

Khi mỗi lập trình viên sở hữu trọn một tính năng, mỗi nhánh đều có một migration. Điều đó khiến mục này là mục quan trọng.

Đây là điều người ta bỏ lỡ khi rời thế giới môi trường dùng chung. Khi cả đội cùng triển khai vào một cơ sở dữ liệu dev, xung đột migration nổi lên ngay lập tức và đau đớn, nhưng chúng nổi lên. Một migration chạy, lần triển khai tiếp theo thất bại, ai đó sửa ngay chiều đó. Với mỗi nhánh một cơ sở dữ liệu, mỗi migration chạy hoàn hảo trong môi trường của mình, và hai cái gặp nhau lần đầu khi cái thứ hai merge vào main. Làm cẩu thả, việc này chuyển xung đột từ dev, nơi nó rẻ, sang phát hành, nơi nó không rẻ.

Bốn quy tắc, tất cả CI ép được nên không ai phải nhớ.

1. CI thất bại khi đồ thị migration có hai lá, đối với trạng thái đã merge main. makemigrations --check bắt được model lệch với migration, nhưng xung đột đáng kể là hai nhánh cùng thêm 0042_*. Kiểm tra trên nhánh đã merge vào main, không phải nhánh đơn lẻ:

git fetch origin main
git merge --no-commit --no-ff origin/main || { echo "merge conflict"; exit 1; }
python manage.py makemigrations --check --dry-run
python manage.py migrate --plan 2>&1 | grep -q "Conflicting migrations" && exit 1

Cái này tôi cố ý gây ra. Hai trong ba nhánh demo, feature/profile-tagline và feature/profile-website, mỗi cái thêm một trường vào model hồ sơ người dùng bằng một migration, và mỗi môi trường áp migration của mình khi khởi lên. Các cột mới chỉ ở đúng chỗ nên có:

env_feature_branch_envir_c65cb4      (no new column)
env_feature_profile_tagl_fa8832      tagline
env_feature_profile_webs_dcb2e7      website

Cả hai migration đều là 0042_*. Nhánh nào cũng không thấy của nhánh kia, nên môi trường nào cũng không báo được có vấn đề. Merge cái này vào cái kia, kiểm tra sẽ báo:

$ git merge --no-commit --no-ff feature/profile-tagline
$ python manage.py makemigrations --check --dry-run
CommandError: Conflicting migrations detected; multiple leaf nodes in the migration graph:
  (0042_profile_tagline, 0042_profile_website in accounts).
To fix them run 'python manage.py makemigrations --merge'

$ python manage.py makemigrations --merge --noinput
Created new merge migration accounts/migrations/0043_merge_20260919_0324.py
    dependencies = [
        ('accounts', '0042_profile_tagline'),
        ('accounts', '0042_profile_website'),
    ]

Tác giả thứ hai chạy --merge đó trên nhánh mình, trong môi trường mình, không làm phiền ai, và lần env up tiếp theo áp 0043 lên bản nhân bản của họ. (Trong trường hợp này git còn báo xung đột văn bản trước, vì cả hai trường được thêm vào cùng một dòng của tệp model. Thực tế, và đáng biết rằng xung đột văn bản che mất xung đột migration cho đến khi được giải quyết.)

2. Migration tương thích ngược với code của bản phát hành trước. Trong lúc triển khai có một khoảng thời gian schema mới và code cũ cùng tồn tại, hoặc ngược lại nếu một máy rollback. Thêm cột nullable hoặc có giá trị mặc định, không bao giờ đổi tên trong một bước, không bao giờ xóa thứ bản phát hành hiện tại vẫn đọc: thêm, triển khai, backfill, đổi code, xóa ở bản phát hành sau. Expand and contract. Lý do nó quan trọng hơn ở đây là môi trường dùng một lần khiến triển khai thường xuyên hơn, nên bạn ở trong khoảng đó nhiều hơn. Staging theo tag là nơi tổng duyệt điều này.

3. CI cũng migration từ số không vào cơ sở dữ liệu rỗng. Nhân bản mẫu kiểm tra “migration của tôi có áp được lên dữ liệu thực tế không”. Chạy rỗng kiểm tra “cả chuỗi còn chạy từ số không không”, bắt được migration giả định một data migration trước đó đã điền gì đó. Ba mươi giây, và nó bắt được một lớp lỗi mà nếu không sẽ chờ đến chiếc laptop mới tiếp theo.

4. Thay đổi schema có cặp mắt thứ hai. Trong một đội nhỏ không cần tệp CODEOWNERS, nhưng cần một quy tắc: PR chạm vào migrations/ được một đồng đội review trước khi merge, và việc của người review không phải kiểm tra SQL. Là biết rằng họ, hoặc ai đó khác trong đội, đang chạm vào cùng bảng trong hai tuần này và nói ra. Quá mười mấy lập trình viên thì kiến thức ấy không còn nằm gọn trong đầu một người nữa, và lúc đó một dòng CODEOWNERS cho migrations/ mới đáng có. Không công cụ nào thay được. Với công cụ bắt hết phần cơ học, đó là việc hai phút, và là phần duy nhất của thế giới môi trường dùng chung cũ đáng giữ lại: khoảnh khắc hai người phát hiện họ sắp va nhau.

Phiên bản, để một URL nói nó đang chạy gì

#

Với một môi trường dùng chung, “staging đang có gì” là câu hỏi trong kênh chat. Với nhiều môi trường, nó phải là thuộc tính của môi trường, nếu không mọi báo cáo lỗi đều bắt đầu bằng khảo cổ.

• Mỗi image mang SHA commit và ứng dụng lộ nó ra. fly deploy --build-arg GIT_SHA=... --build-arg GIT_BRANCH=... đóng chúng vào image dưới dạng biến môi trường, và /api/version/ trả chúng về kèm tên môi trường và vùng (xem output ở trên). Việc đầu tiên ai cũng làm với “nó hỏng trên feature-profile-tagl-fa8832” là kiểm tra nó đang chạy commit mà họ nghĩ. Môi trường demo đầu tiên được triển khai từ working tree một commit trước khi bộ công cụ được commit, và endpoint nói đúng thế: nó báo commit trước đó, không phải SHA tôi mong đợi.
• ENVIRONMENT=$ENV có trong mọi dòng log và thẻ environment trên công cụ theo dõi lỗi. Lỗi của nhánh không làm bẩn theo dõi lỗi của prod và lọc được bằng một cú bấm.
• Nhánh có SHA, bản phát hành có tag. feature-payments-retr-3f9a1c không bao giờ có số phiên bản; nó có commit. Staging và prod có v1.42.0.
• Ứng dụng di động mang phiên bản API tối thiểu, không phải URL. Trường URL trong menu dev là cách tester trỏ điện thoại thật vào một nhánh, và endpoint phiên bản mang phiên bản schema API là cách ứng dụng biết nó đang nói chuyện với thứ nó hiểu được.

Điều này không giải quyết được gì

#

Nó không giải quyết hai tính năng chỉ có nghĩa khi đi cùng nhau. Một môi trường nhánh hiện một nhánh. Câu trả lời là merge cả hai sau feature flag rồi nhìn vào main, làm được bằng một môi trường thường trực bám theo main (main-dev.example.com, triển khai lại sau mỗi lần merge). Đó là môi trường phi production sống lâu duy nhất tôi giữ, và không ai triển khai lên nó; nó để xem bản phát hành tiếp theo sẽ là gì.

Nó không giải quyết các nhà cung cấp đòi callback đã đăng ký và không chấp nhận wildcard. Dịch vụ xác thực tôi dùng chấp nhận tên miền cha, nên example.com phủ mọi tên miền nhánh -dev. Một số nhà cung cấp OAuth và thanh toán thì không, và với họ bạn giữ một tên miền dùng chung mà Worker định tuyến tới môi trường nào vừa giành nó gần nhất. Đó là cái khóa nhỏ lên một thứ nhỏ, và tốt hơn nhiều so với cái khóa lên mọi thứ.

Nó không giải quyết phía con người của migration. Công cụ bắt xung đột cơ học. Nó không bắt được hai người trong các bạn mô hình hóa cùng một khái niệm theo cách không tương thích trong cùng hai tuần, và cách sửa duy nhất là buổi review migration mà một người trong hai nhận ra.

Tôi sẽ kiểm tra gì trong hệ thống của bạn

#

Nếu bạn có dev hoặc staging dùng chung và một luồng chat để đặt chỗ:

1. Một nhánh đã xong phải chờ bao lâu để ai đó ngoài tác giả thấy nó chạy? Quá một giờ là bạn đang trả giá cho cái khóa bằng thời gian giao hàng, và với một đội nhỏ thì đó là một phần lớn của đội đang chờ.
2. Cơ sở dữ liệu dùng chung bị reset bao lâu một lần, và khi đó ai mất việc đã làm?
3. Một lập trình viên mới, ngày đầu, có thể có URL công khai chạy nhánh của mình mà không phải xin ai bất cứ thứ gì không? Thứ họ phải xin chính là thứ cần tự động hóa trước tiên.
4. Môi trường mới có bắt đầu từ dữ liệu thực tế không? Nếu bắt đầu rỗng, lỗi đầu tiên nó không bắt được là migration ổn trên bảng rỗng nhưng mất bốn mươi phút trên bảng thật.
5. Trong hạ tầng phi production của bạn có thứ gì vẫn tồn tại một tháng sau khi mọi người quên nó không? Nếu có, hãy viết trình quét trước mọi thứ khác. Rò rỉ bắt đầu từ ngày đầu tiên.

Câu hỏi trong kênh chat biến mất không phải vì người ta thôi hỏi, mà vì câu trả lời luôn là “có, đang dùng cái của tôi.”

Lượng truy cập từ công cụ tìm kiếm vào blog này đã đứng yên vài năm nay, và tôi cũng thôi mong nó nhúc nhích. Nên thay vào đó tôi đi xem khách đến từ đâu, và trong số đó có các trợ lý AI (AI assistant) hay không. Có, nhưng chỉ vừa đủ để gọi là có. Trong mười hai tháng tính đến ngày 16 tháng 9 năm 2026, công cụ phân tích truy cập của tôi đếm được 5,372 phiên truy cập (session) ở đây. Hai mươi bảy phiên trong số đó đến từ một trợ lý AI: mười hai từ chatgpt.com, chín từ gemini.google.com, sáu từ Perplexity, và không có phiên nào từ claude.ai. Nửa phần trăm. Nhưng khách đến từ ChatGPT lại là loại khách tốt. Họ ở lại trung bình năm phút, so với 27 giây của lượt truy cập trực tiếp và ba phút của khách từ Google, vì họ đã đọc xong câu trả lời rồi và muốn xem chi tiết.

Nên tôi đã dành thời gian tìm hiểu xem một blog nhỏ làm thế nào để được chọn làm nguồn cho những câu trả lời đó. Bài này là những gì tôi đã làm trên trang này, cùng với những gì log nói về chuyện đó. Chỗ nào có số thì tôi đưa số, chỗ nào đang đoán thì tôi nói rõ là đoán. Có ba câu trong bản nháp đầu hóa ra sai khi tôi thực sự nhìn vào số liệu, và tôi để nguyên các chỗ sửa trong bài.

Hai loại bot, và chỉ một loại trích dẫn bạn

#

Điều đầu tiên cần phân định rõ là “bot AI” thực ra là hai công việc khác nhau với hai bộ user agent khác nhau, và chặn loại này chẳng ảnh hưởng gì đến loại kia.

Trình thu thập dữ liệu (crawler) huấn luyện kéo trang về hàng loạt để xây mô hình tiếp theo. Của OpenAI là GPTBot, của Anthropic là ClaudeBot, của Google được điều khiển qua token Google-Extended, của Apple qua Applebot-Extended, còn CCBot của Common Crawl thì cấp dữ liệu cho phần lớn các bộ dữ liệu mở. Những gì chúng lấy đi cuối cùng trở thành trọng số (weights) của mô hình, không có đường dẫn nào trỏ ngược về bạn. Chặn những bot này là có lý, và tôi không cho đó là chuyện vớ vẩn.

Bot truy xuất (retrieval bot) là loại còn lại. Khi ai đó hỏi ChatGPT, Claude hay Perplexity một câu, trợ lý sẽ chạy một lượt tìm kiếm, tải về ngay lúc đó một nhúm trang, đọc chúng, rồi viết câu trả lời kèm trích dẫn (citation). Những lượt tải đó đến dưới tên OAI-SearchBot và ChatGPT-User, Claude-SearchBot và Claude-User, PerplexityBot và Perplexity-User. AI Overviews của Google thì dùng Googlebot thường, nên chẳng có công tắc riêng nào cho chúng cả. Đây mới là những bot đưa người đọc quay lại với bạn. Nếu mục tiêu là được trích dẫn thì đây là những bot bạn đang tối ưu cho, và cũng nên biết rằng chặn GPTBot không ảnh hưởng gì đến kết quả tìm kiếm của ChatGPT, theo cả hai chiều.

robots.txt của trang này là bản mặc định của Hugo, tức là cho phép tất cả:

User-agent: *
Allow: /
Sitemap: https://jared.lynskey.co.nz/sitemap.xml

Tôi đã cân nhắc tách nó ra, cho bot truy xuất vào và giữ bot huấn luyện ở ngoài, rồi quyết định là không đáng làm với một blog mà mục đích duy nhất là để được đọc. Nếu tôi muốn vậy thì nó sẽ trông như khối bên dưới. Lý do đưa nó ra đây cũng là bài học trong bài Cloudflare trả về cho Googlebot một trang trống: danh sách phải gọi tên bot, không phải tên hãng. Không có dòng nào bạn viết ra được để nói “OpenAI”.

User-agent: GPTBot
User-agent: ClaudeBot
User-agent: Google-Extended
User-agent: Applebot-Extended
User-agent: CCBot
Disallow: /

User-agent: *
Allow: /

Một điều cần kiểm tra nếu trang nằm sau Cloudflare. Từ giữa năm 2025, các zone mới ở đó chặn trình thu thập dữ liệu AI theo mặc định, và có một nút bật một chạm trong phần cài đặt bot làm điều tương tự với các zone cũ. Nó chặn cả hai loại. Blog này vừa chuyển sang Cloudflare Pages tuần trước, nên việc đó có trong danh sách của tôi. Nếu bạn bật nó lên vì “bot AI” nghe như thứ nên chặn ở ngoài, thì bạn cũng vừa tắt luôn việc được trích dẫn. Cloudflare sau đó đã bắt đầu ghi một dòng Content-Signal vào các tệp robots.txt mà họ quản lý, với ba cờ riêng search, ai-input và ai-train. Không ai bị bắt buộc phải tuân theo, nhưng đó là đúng bộ từ vựng: cùng cách phân chia như trên, diễn đạt như một nguyện vọng thay vì một bức tường.

Thực sự thì ai đang gõ cửa

#

Việc chuyển sang Cloudflare có một tác dụng phụ: lần đầu tiên tôi nhìn thấy được từng request theo user agent. Dưới đây là những gì đã ghé vào trong bốn ngày từ ngày 13 đến ngày 16 tháng 9 năm 2026, sau khi đã loại bỏ các bot giả mạo (spoof), phần này tôi sẽ nói ngay sau đây.

Có hai điều nổi bật. Các bot huấn luyện (training crawler) đọc hết mọi thứ, tới hai lần, trong khoảng thời gian mà các bot truy xuất chỉ đọc vài chục trang. Và bot truy xuất không tải về một cách ngẫu nhiên: cả ChatGPT-User lẫn Claude-User đều nhắm vào bài về máy chủ cập nhật, là bài cụ thể nhất trên trang này, còn bài về khởi động nguội bản tiếng Nhật thì được tải về đúng bằng tiếng Nhật.

Giờ đến phần giả mạo. Trong 20 request tự xưng là GPTBot, có 18 đến từ những địa chỉ nằm ngoài dải địa chỉ IP (IP range) mà OpenAI công bố, và chúng đòi /.env, /.git/HEAD và /firebase-adminsdk.json. Mười lăm trong 36 request “ChatGPT-User” cũng là kiểu đó. Phần lớn lưu lượng “PerplexityBot” thì muốn lấy /id_ed25519. User agent chỉ là một chuỗi ký tự mà ai cũng gửi được, và các công cụ quét lỗ hổng đã nhận ra rằng cứ mang tên bot AI là được cho qua. OpenAI, Anthropic và Perplexity đều công bố dải địa chỉ IP của mình. Nếu bạn định đối xử đặc biệt với một bot, dù là cho vào hay chặn lại, hãy kiểm tra địa chỉ chứ đừng tin cái tên. Các con số 20, 59 và 8 ở trên là những request đến từ đúng địa chỉ.

Trang phải đọc được mà không cần trình duyệt

#

Bot truy xuất tải trang ngay lúc trả lời, có giới hạn thời gian chờ (timeout), và phần lớn không chạy JavaScript. Một trang chỉ là cái div rỗng cho đến khi bundle tải xong là một trang chúng không đọc. Hugo xuất ra HTML hoàn chỉnh, nên blog này có sẵn điều đó mà không phải làm gì, và đó là lý do chính tôi chưa bao giờ bị cám dỗ chuyển nó sang thứ gì đó thông minh hơn. Sàn mua bán tôi đang vận hành là trường hợp ngược lại, một ứng dụng web React Native, và để trình thu thập dữ liệu nhận được một tài liệu thực sự ở đó, tôi đã phải làm một nhánh dựng trang động (dynamic rendering), rồi dính một lỗi bộ nhớ đệm (cache) lặng lẽ phá hỏng nó. Bài Cloudflare ở trên chính là câu chuyện đó.

Tốc độ cũng được tính theo cách tương tự, và ở chỗ này log đã sửa lưng tôi. Tôi vẫn đinh ninh một trang tĩnh nằm sau Cloudflare thì được phục vụ từ máy chủ biên (edge) gần nhất. Không phải vậy. Blog này chạy trên Cloudflare Pages, HTML được trả ra mà không qua bộ nhớ đệm, và từ Seoul thì phản hồi quay về từ Los Angeles mất khoảng nửa giây. Với một bot có thời gian chờ vài giây thì vẫn ổn, nhưng nó không phải vài chục mili giây như tôi suýt viết ra, và tôi biết được chỉ vì đã đo. Một trợ lý đang ghép câu trả lời từ sáu trang sẽ bỏ cái trang mất ba giây, và nó không nói cho bạn biết là nó đã bỏ.

Viết sao cho nhấc nguyên một đoạn ra được

#

Cách các hệ thống này dùng một trang không giống cách một người đọc dùng. Chúng cắt trang thành từng khúc (chunk), chấm điểm từng khúc so với câu hỏi, rồi trích những khúc điểm cao. Một bài dẫn dắt suốt tám trăm chữ mới đến ý chính thì khúc nào điểm cũng thấp. Một bài mà mỗi phần nêu luận điểm ngay câu đầu rồi mới chứng minh thì phần khớp với câu hỏi sẽ ghi điểm.

Điều đó thay đổi cách tôi viết ở đây nhiều hơn bất cứ thứ gì thuộc về kỹ thuật. Phần description trong front matter giờ là tóm tắt bài nói gì, không phải câu mồi để bạn bấm vào đọc, vì description thường là phần duy nhất trợ lý hiển thị. Tiêu đề mục nói thẳng mục đó kết luận gì. Con số đi kèm đơn vị ngay trong câu thay vì nằm trong biểu đồ. Ngày tháng được viết ra đầy đủ, vì “tuần trước” chẳng có nghĩa gì với một mô hình đọc trang này một năm sau. Và một bài chỉ nói về một chuyện.

Nửa còn lại là phải có thứ đáng để trích, và ở chỗ này số liệu lại không thuận một chiều. Trong log, những trang mà bot tải về lúc trả lời là những bài cụ thể: khởi động nguội, máy chủ cập nhật, gỡ lỗi iOS. Trình thu thập dữ liệu của Naver tên là Yeti và của Daum là Daumoa, một lần khởi động lại máy ở nhà cung cấp hosting của tôi là một khoảng ba mươi giây trả lỗi 504, Cloudflare nén Brotli tại chỗ đo trên bundle của tôi còn tệ hơn gzip. Những dữ kiện đó không được ghi lại ở nhiều nơi, nên câu hỏi nào cần đến một trong số chúng sẽ rơi vào đây. Nhưng những người bấm từ trợ lý sang thì phần lớn lại rơi vào các bài về quản lý từ năm 2023 và 2024, mỗi bài một hai phiên. Bài cụ thể thì máy đọc. Bài chung chung thì người bấm. Tôi không có lời giải thích gọn gàng nào cho chuyện đó, và tôi thà kể lại đúng như vậy còn hơn bịa ra một lý do. Đòn bẩy, nếu có, vẫn là viết ra cái điều cụ thể bạn vừa phát hiện tuần này mà lúc tìm kiếm bạn không thấy đâu, vì đó rõ ràng là thứ máy đang đọc.

Nói rõ ai viết, và lần nào cũng nói như nhau

#

Một trợ lý khi cân nhắc có trích dẫn một trang hay không đang làm gần giống một người đọc cẩn thận: ai viết cái này, viết khi nào, và nó có khớp với mọi thứ khác tôi đã tìm thấy không? Phần cơ chế của việc đó trên trang này chủ yếu là do theme làm. Mỗi bài đều mang dữ liệu có cấu trúc (structured data) kiểu Article với tác giả, ngày đăng và ngày sửa, và tác giả là một Person với liên kết đến cùng các hồ sơ công khai. Đó là vài dòng trong template, và là khác biệt giữa “một trang” với “một trang của một người có tên tuổi và có quá trình”.

Phần không phải theme làm là sự nhất quán. Trang giới thiệu, llms.txt, các hồ sơ công khai của tôi và dòng ở đầu mỗi bài đều mô tả cùng một người với cùng một quá trình làm việc. Khi có gì thay đổi thì tất cả cùng đổi, nếu không, cái tôi quên sẽ thành cái sai. Nghe có vẻ tỉ mẩn, nhưng một trang nói tôi là quản lý kỹ thuật (engineering manager) còn trang khác nói tôi làm tự do chính là kiểu mâu thuẫn khiến mô hình trả lời nước đôi, hoặc chọn người khác.

Ngày sửa cũng phải thành thật. Nó đổi khi nội dung đổi, ngoài ra tôi không đụng vào. Đẩy ngày lên cho trông có vẻ mới là kiểu chiêu dùng được một lần, rồi cả tên miền của bạn bị hạ tín nhiệm.

llms.txt là gì, và sự thật là chẳng ai đọc nó

#

llms.txt là một đề xuất từ tháng Chín năm 2024 về một tệp Markdown đặt ở gốc trang, cung cấp cho mô hình ngôn ngữ một bản tóm tắt về trang cùng một danh sách liên kết chọn lọc. Tôi thêm một tệp như vậy vào tháng Hai năm nay. Nó gồm một đoạn về tôi là ai, rồi các mục cho quản lý, hạ tầng, di động và cộng đồng, mỗi bài một dòng: tiêu đề, URL, và một câu nói bài đó kết luận gì. Đọc nó giống như một mục lục viết cho người đang vội.

Điều đáng nói là chẳng ai đọc nó. Trong bốn ngày log tôi có, những request duy nhất tới /llms.txt là của chính tôi. Common Crawl đã lấy 76 trang của site này trong đợt thu thập tháng 8 năm 2026 mà chưa lần nào đụng đến tệp đó. Chưa có trợ lý lớn nào nói rằng họ đọc nó. Nên nó không phải lý do bất cứ thứ gì ở đây được trích dẫn, và tôi sẽ không khuyên ai làm nó vì lý do đó. Tôi giữ nó vì hai lý do. Nó tốn một tiếng, và việc viết cho mỗi bài một câu nói bài đó thực sự kết luận gì còn đáng giá hơn bản thân cái tệp, vì nó cho tôi thấy bài nào chẳng kết luận được gì. Nó cũng là trang duy nhất trên site nói cho máy biết trang này để làm gì, và tôi thà có mà không cần đến. Từ đó nó đã lệch đi, vì tôi viết tay và hay quên, và đó là lý do nên sinh nó từ front matter như một định dạng đầu ra (output format) của Hugo thay vì viết tay. Việc đó đang nằm trong danh sách.

Feed, sitemap và năm ngôn ngữ

#

Phần đường ống nhàm chán vẫn có giá trị. Sitemap là cách trình thu thập dữ liệu tìm thấy bài mới ngay ngày nó lên. RSS là cách nó biết một bài đã thay đổi. Cả hai đều là mặc định của Hugo và tôi chưa bao giờ phải nghĩ đến. ClaudeBot đọc sitemap 36 lần trong hai ngày, và đó là cách nó tìm ra 1,380 trang nhanh đến vậy.

Ngôn ngữ là phần tôi không ngờ lại quan trọng. Mọi thứ ở đây có bản tiếng Anh, Nhật, Hàn, Trung giản thể và Việt, với các liên kết thay thế (alternate link) để trình thu thập dữ liệu biết chúng là cùng một bài. Các trình thu thập dữ liệu coi chúng như năm site riêng: lượt thu thập của ClaudeBot chia gần như đều cho cả năm, và trong 73 trang bài viết mà Common Crawl lấy hồi tháng 8, chỉ có bốn trang là bản tiếng Anh. Trợ lý trả lời bằng ngôn ngữ được hỏi và nghiêng về nguồn bằng chính ngôn ngữ đó, nên một câu hỏi tiếng Hàn về khởi động nguội có thể được trả lời từ trang tiếng Hàn thay vì từ một bản dịch tại chỗ của trang tiếng Anh, và trang tiếng Nhật chính là trang mà ChatGPT thực sự đã tải về. Điều kiện là bản dịch phải đọc như thể được viết bằng chính ngôn ngữ đó. Lượt rà soát tôi làm đầu năm nay, có người bản ngữ kiểm tra, là dành cho người đọc, nhưng nó cũng là thứ khiến trang tiếng Việt trở thành một nguồn thay vì một món lạ.

Những gì tôi đo được

#

Nhiều hơn tôi tưởng, một khi tôi thôi đoán mò. Gói miễn phí của Cloudflare cho xem log request theo user agent và đường dẫn, mỗi lần truy vấn được một ngày, và bảng bot ở trên là từ đó mà ra; còn muốn xem referrer thì phải lên gói trả phí. Công cụ phân tích truy cập thì có referrer, và kéo chúng ra qua API báo cáo của nó thay vì căng mắt nhìn dashboard chính là cách tôi có được các con số ở đầu bài. Ghép hai nguồn lại thì thấy được hình dạng của câu chuyện. Trong bốn ngày, các bot truy xuất tải về khoảng chín mươi trang từ các địa chỉ của OpenAI và Anthropic. Trong tháng vừa rồi, có hai người đến từ ChatGPT. Đọc nhiều, thỉnh thoảng trích dẫn, hiếm khi bấm vào. Vẫn chưa có cách nào tôi biết để xem những câu trả lời đã dùng một trang mà không được bấm vào. Cách kiểm tra hữu ích nhất vẫn là làm bằng tay: hỏi trợ lý đúng câu hỏi mà bài của bạn trả lời, rồi xem nó trích trang của ai.

Nếu phải giữ lại một thứ từ tất cả những điều này thì đó là quy tắc viết. robots.txt, dữ liệu có cấu trúc và llms.txt là công việc của một buổi chiều, xong là xong. Viết sao cho mỗi phần nêu luận điểm trước, và viết về điều cụ thể thay vì điều chung chung, là một thói quen, và chính thói quen đó quyết định một trang có đáng trích dẫn hay không. Điều thứ hai là hãy đo trước rồi hãy khẳng định. Hóa ra được máy tin cậy trông rất giống được người tin cậy: nói bạn là ai, nói bạn biết gì, và lần nào cũng nói theo cùng một cách.

Cho tới gần đây, mọi thay đổi ở phần web của ứng dụng chợ mà tôi đang làm đều được đưa lên theo đúng cách của một thay đổi trên API Django: build Docker image, đẩy lên, rồi triển khai lần lượt (rolling) lên từng máy trên Fly.io. Giao diện web (bản xuất web của ứng dụng di động, cộng với các trang giới thiệu do một trình tạo trang tĩnh (static site generator) build ra) được sao chép vào image ngay cạnh API, nên không có cách nào khác để đưa nó ra. Sửa một dòng CSS mất khoảng bảy phút và khởi động lại 11 máy. Có một ngày trong tháng Tám tôi làm việc đó sáu lần.

Bài này đi lần lượt qua thứ tôi đã thay vào đó: một script triển khai build cả hai cây giao diện, tải chúng lên object storage dưới một tiền tố có phiên bản, đổi một đối tượng con trỏ, đợi đến khi mọi máy đều đang phục vụ phiên bản mới, rồi xóa bộ nhớ đệm của Cloudflare qua API. Ở phía bên kia, Django đọc con trỏ ở mỗi yêu cầu và phục vụ đúng phiên bản được ghi trong đó. API không khởi động lại chút nào.

Vì sao cách cũ có vấn đề

#

Chi phí lớn nhất là việc khởi động lại. Mười một máy triển khai lần lượt nghĩa là mười một lần khởi động nguội (cold start), và trên CPU dùng chung thì Django mất khoảng mười ba giây để lên, trong đó bảy giây chỉ để import Django. Tôi có thêm một bước làm nóng ở cuối script triển khai, gọi vào từng máy một để người dùng thật không phải là người trả cái giá đó, và hệ quả là mỗi lần phát hành web đều kết thúc bằng việc ngồi đợi máy chậm nhất. Những lần khởi động nguội đó tốn kém thế nào trên Fly.io, tôi đã viết trong bài Thu về 0 (scale to zero), và mỗi lần khởi động lại là một lần sập 30 giây. Nói ngắn gọn, mỗi lần khởi động lại là một khoảng thời gian người dùng có thể nhận lỗi 504, nên một đường triển khai không khởi động lại gì cả sẽ đóng hẳn khoảng đó cho các lần phát hành web.

Vấn đề thứ hai là đầu ra của trang tĩnh bị tách đôi. HTML thì vào image, nhưng RSS feed và chỉ mục tìm kiếm thì lên thẳng bucket. Chúng được build từ cùng một nguồn, chỉ là không cùng thời điểm, nên có thể lệch nhau mà chẳng ai nhận ra cho đến khi lệch thật.

Vấn đề thứ ba thiên về thói quen. Khi một lần phát hành tốn bảy phút cộng một lần khởi động lại, bạn sẽ thôi làm những lần phát hành nhỏ. Tôi để ba bốn bản sửa chất đống thay vì đưa lên từng cái, và đó chính xác là cách một thay đổi một dòng bị đưa lên cùng với thứ gì đó đang hỏng.

Bố cục trong bucket

#

Mọi thứ nằm trong một bucket tương thích S3, dưới tiền tố web/:

web/current                              ← a text file containing one version string
web/a1b2c3d-20260914021500/manifest.json ← every file in this version
web/a1b2c3d-20260914021500/app/...       ← the app's web export
web/a1b2c3d-20260914021500/site/...      ← the static site's output
web/9f8e7d6-20260912093012/...           ← the previous version, still there

Phiên bản là mã git SHA ngắn cộng với dấu thời gian UTC, nên nhìn vào là biết commit nào và đưa lên lúc nào. web/current là thứ duy nhất thay đổi khi một bản phát hành lên sóng.

Script triển khai làm gì

#

Toàn bộ là một script, chạy từ thư mục gốc của repo. Theo thứ tự:

1. Từ chối cây git chưa sạch. Việc đầu tiên nó làm là git status --porcelain, và nếu có bất kỳ dòng nào trả về thì thoát. Cái gì nằm trên đĩa là cái được tải lên, và script triển khai cũ của trang giới thiệu từng đưa lên nội dung chưa commit đúng theo cách đó. Có một cờ để bỏ qua bước này cho lúc bạn biết rõ mình đang làm gì, nhưng tôi chưa dùng. Sau đó nó tính chuỗi phiên bản từ git rev-parse --short HEAD và thời điểm hiện tại.

2. Build cả hai cây. Với ứng dụng, nó chạy bản xuất web với địa chỉ API và WebSocket của production được nhúng sẵn, tiếp theo là một lượt nén trước bằng Brotli. Việc nén trước đáng để giải thích: Cloudflare có nén Brotli tại chỗ, nhưng ở mức chất lượng thấp, và trên bundle này đo ra còn tệ hơn gzip (2,04MB so với 1,66MB). Nén một lần lúc build với chất lượng 11 đưa nó xuống 1,28MB, nên script ghi một tệp .br song sinh cạnh mỗi tệp JS, CSS và JSON trên 1KB. Với trang giới thiệu, nó chạy trình tạo trang tĩnh với chế độ rút gọn (minify) bật.

3. Tải lên. Nó duyệt cả hai thư mục build, rồi tải mọi tệp lên web/<version>/app/... và web/<version>/site/... bằng mười sáu luồng. Mỗi đối tượng được gán Content-Type đoán từ tên tệp (bỏ .br trước), và các tệp Brotli song sinh có thêm Content-Encoding: br. Chỉ khi mọi tệp đã lên hết, nó mới ghi manifest.json, một đối tượng JSON với hai danh sách đường dẫn tương đối. Thứ tự này quan trọng: phía Django coi một phiên bản không có tệp kê khai là không tồn tại, nên một phiên bản tải dở dang không bao giờ có thể được đặt làm hiện tại. Hiện giờ là vài trăm tệp và tải lên mất khoảng sáu giây.

4. Đổi con trỏ. Một lệnh put_object ghi chuỗi phiên bản vào web/current. Đó là phát hành.

5. Đợi các máy. Mỗi máy API đệm con trỏ năm giây, nên trong chốc lát sau khi đổi, vài máy vẫn còn ở phiên bản cũ. Script thăm dò một endpoint báo phiên bản trên API mỗi nửa giây và đếm số câu trả lời liên tiếp mang phiên bản mới. Fly cân bằng tải qua tất cả các máy, nên một chuỗi mười sáu câu trả lời khớp liên tiếp (nhiều hơn số máy) là cách nó biết mọi máy đều đã đọc lại con trỏ. Một câu trả lời cũ là đếm lại từ đầu. Sau 90 giây nó bỏ cuộc và bảo bạn kiểm tra bằng tay; lần đổi thật đầu tiên mất hơn 30 giây một chút, nên giới hạn không đặt thấp hơn.

6. Xóa bộ nhớ đệm Cloudflare. Một lời gọi API, nói ở dưới. Nếu thất bại, script in cảnh báo rồi đi tiếp.

7. Báo lên kênh chat của đội. Cùng webhook mà cảnh báo lỗi lúc chạy dùng nhận một dòng với phiên bản và người chạy, để một loạt lỗi có thể được đọc đối chiếu với thứ vừa thay đổi. Quay lui đăng bằng màu hổ phách.

Từ đầu đến cuối, một lần phát hành mất hơn một phút một chút, phần lớn là thời gian xuất bản web.

Phía Django

#

Django vốn đã là thứ phục vụ giao diện. Mọi URL không phải API đều được trả lời bằng trang đã dựng sẵn (prerender) trong bản xuất web cho route đó, còn các trang giới thiệu, chính sách bảo mật và hỗ trợ lấy từ đầu ra của trang tĩnh. Trước đây những view này mở tệp trên đĩa. Giờ chúng đọc qua một lớp nhỏ biết cách lấy dữ liệu từ bucket.

Với mỗi yêu cầu, nó xác định ba thứ: phiên bản hiện tại (đọc từ web/current, đệm năm giây), tệp kê khai của phiên bản đó (đệm chừng nào phiên bản đó còn là hiện tại), và bản thân tệp (một LRU nhỏ trong bộ nhớ chứa nội dung tệp, nên HTML của trang và bundle chính luôn nằm sẵn trong bộ nhớ). Tệp kê khai là thứ khiến 404 rẻ: đường dẫn không có trong danh sách thì trả lời không luôn, không cần hỏi bucket. Nếu client chấp nhận Brotli, nó đọc tệp .br song sinh thay thế và đặt header mã hóa tương ứng. Tài nguyên tĩnh đi ra với header cache immutable một năm, vì tên tệp đã gắn hash theo nội dung. Những gì suy ra từ danh sách tệp, chẳng hạn bảng ánh xạ route sang trang dựng sẵn, cũng được đệm theo phiên bản, nên một bản triển khai mới sẽ dựng lại chúng ở yêu cầu đầu tiên chứ không sớm hơn.

Rồi đến endpoint mà script triển khai thăm dò:

def web_version(request):
    # bundle: the layer that reads web/current and the manifest
    response = JsonResponse({"source": bundle.source(), "version": bundle.version()})
    response["Cache-Control"] = "no-store"
    return response

Nó trả về bucket:<version> trên production, hoặc filesystem khi đang phục vụ từ image. Mỗi máy Fly chỉ trả lời cho chính nó, nên gọi chừng chục lần là biết cả cụm đã đồng bộ chưa. Đây cũng là cách nhanh nhất để xem một máy đang nghĩ cái gì là bản chạy khi có gì đó trông không ổn.

Xóa bộ nhớ đệm Cloudflare qua API

#

HTML trên trang được đệm ở biên của Cloudflare trong năm phút. Nếu không xóa, bản triển khai đã chạy trên máy nhưng hầu hết người dùng vẫn nhận trang cũ tới tận năm phút, thế thì mất hết ý nghĩa.

Việc xóa chỉ là một lời gọi API:

urllib.request.Request(
    f"https://api.cloudflare.com/client/v4/zones/{zone}/purge_cache",
    data=json.dumps({"hosts": ["example.com", "www.example.com"]}).encode(),
    headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)

Tôi xóa theo host thay vì theo URL để khỏi phải liệt kê từng trang. Các tài nguyên tĩnh (asset) thì không cần xóa: tên tệp đã gắn hash theo nội dung, nên bản build mới trỏ tới tên tệp mới và các tệp cũ đơn giản là không còn được tham chiếu. Chỉ phần HTML tham chiếu tới chúng là cần làm mới.

Script đợi các máy trước khi xóa đệm là có chủ ý. Nếu xóa trước, Cloudflare có thể nạp lại bộ nhớ đệm từ một máy vẫn còn ở phiên bản cũ, và trang đó sẽ nằm ở biên thêm năm phút nữa.

Nếu xóa đệm thất bại, script in một cảnh báo rồi vẫn chạy cho xong. Bộ nhớ đệm tự hết hạn trong vòng năm phút, nên trường hợp xấu nhất là một lần phát hành chậm chứ không phải một lần phát hành hỏng. Tôi thà như vậy còn hơn để việc triển khai bị hủy ở bước cuối.

Kiểm tra một bản build trước khi lên sóng

#

Chế độ không đổi con trỏ (no-flip) làm đến hết bước 3 rồi dừng. Phiên bản đã nằm trong bucket nhưng chưa có gì phục vụ nó. Để xem, tôi đặt một biến môi trường trên một máy để ghim máy đó vào bản build ấy, bất kể web/current nói gì. Khi thấy ổn, lệnh rollback sẽ đặt nó làm hiện tại. Lệnh tên là rollback nhưng thực chất là “trỏ current vào phiên bản này”, và tiến lên hay lùi lại đều là cùng một thao tác.

Quay lui

#

Các phiên bản cũ vẫn nằm trong bucket, nên quay lui (rollback) là chạy đúng lệnh đó với một phiên bản trước, và một lệnh liệt kê cho thấy có những gì, mới nhất trước. Nó cũng đợi máy và xóa đệm y như một lần triển khai tiến lên. Tôi chưa cần dùng tới. Hiện chưa có gì dọn các phiên bản cũ; chúng nhỏ và tôi thà giữ còn hơn không.

Những gì vẫn như cũ

#

API vẫn triển khai theo cách cũ, qua script triển khai riêng của nó, và nên như vậy: nó có trạng thái và là nơi migration chạy. Dockerfile cũng vẫn sao chép cả hai bản build giao diện vào image. Đó là chủ ý. Khi không cấu hình bucket (phát triển cục bộ, bộ kiểm thử) hoặc không đọc được bucket, lớp phục vụ tệp lùi về những thư mục đó trên đĩa, nên sự cố lưu trữ nghĩa là người dùng nhận được giao diện đi kèm image gần nhất thay vì một trang lỗi. Chỉ một biến môi trường là ép được hành vi đó trên production, nếu có lúc cần tạm gạt bucket ra khỏi luồng.

Giao diện thay đổi thường xuyên hơn API nhiều, và giờ mỗi lần phát hành mất khoảng một phút thay vì bảy. Tôi đã thôi dồn lại mà chẳng cần cố.

Ứ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.

Cập nhật ngày 4/11/2026: thêm một điều chỉnh nữa. Những lỗi 504 này không phải là các yêu cầu thăm dò mà máy chủ gốc không trả lời được. Chúng là các lượt tra cứu cache Early Hints của chính Cloudflare, hoàn toàn không đi tới máy chủ gốc, và mã 504 ở đó chỉ có nghĩa là chưa có gì được cache cho URL ấy. Tắt Early Hints cũng không phải cách sửa tốt nhất: khi gửi response header Link, tính năng bắt đầu hoạt động và các lần miss chuyển thành hit. Toàn bộ câu chuyện có trong bài Lỗi 504 Cloudflare không phải sự cố thật: Early Hints và HTTP 103.

Nói ngắn gọn: khi bật auto_stop_machines để thu về 0 (scale to zero), yêu cầu nào rơi vào một máy Fly.io đang dừng đều phải chờ máy khởi động xong. Máy của tôi mất 25 đến 33 giây cho mỗi lần khởi động nguội (cold start), vì mỗi lần máy bật lên, entrypoint lại chạy migration của Django và collectstatic, còn bytecode thì chưa từng được lưu đệm. Khi chỉ chạy những việc đó một lần cho mỗi image (bằng một khóa Redis đặt theo FLY_IMAGE_REF) và thêm compileall vào bước build, khởi động nguội giảm còn khoảng 9 giây. Đổi auto_stop_machines từ 'stop' sang 'suspend' (muốn vậy phải bỏ swap, vì Fly không cho tạm ngưng máy có swap) thì đánh thức máy chỉ còn khoảng 3 giây.

Tôi mở bảng điều khiển (dashboard) của Cloudflare để tìm hiểu một đợt lưu lượng truy cập (traffic) tăng đột biến, và phát hiện bên dưới nó là một chuyện tệ hơn nhiều: trong một ngày, 22% tổng số yêu cầu (request) gửi tới ứng dụng của tôi đã bị lỗi. Không có cảnh báo nào bắn ra. Lượt kiểm tra tình trạng (health check) nào cũng báo xanh. Nhật ký (log) trông hoàn toàn bình thường, vì những yêu cầu bị lỗi chưa bao giờ tới được ứng dụng.

Hóa ra thủ phạm lại là chính script khởi động container của tôi: nó làm những việc hoàn toàn hợp lý, chỉ có điều là vào đúng thời điểm tệ nhất.

Đợt lưu lượng tăng vọt chỉ là cú đánh lạc hướng

#

Ban đầu tôi chỉ định tìm hiểu một khung giờ nhận khoảng 4,900 yêu cầu, trong khi trung vị chỉ là 121. Có bốn mươi hai khách truy cập khác nhau, tức là 110 yêu cầu cho mỗi khách. Người thật thì không lướt web kiểu đó.

Đó là một công cụ quét (scanner): một con bot duy nhất lần lượt dò qua các tên miền phụ (subdomain) do nó tự bịa ra, và hỏi từng cái xem có để lộ thông tin bí mật (secrets) nào không:

api-stage-asia.example.com/.env.local
api-us-east-1-demo.example.com/.env
api-eu-uat.example.com/wp-config.php~
app-test-us-east-1.example.com/actuator/configprops
prod-api-use2.example.com/.env.local
relay.example.com/.env.production

Khoảng ba mươi tên máy chủ (hostname), đủ mọi biến thể .env bạn nghĩ ra được, thêm cả các endpoint actuator của một framework Java trên một ứng dụng Django. Tất cả đều nhận mã 301 chuyển hướng về tên miền chính, và không có gì bị lộ ra ngoài. Nhàm chán, và thật sự vô hại.

Nhưng nhân tiện đang mở trang phân tích (analytics), tôi thử nhóm số liệu của cùng ngày đó theo mã trạng thái (status code). Vấn đề thật nằm ở đây.

Hai mươi hai phần trăm. Và số lỗi này không rải đều khắp trang, mà dồn vào đúng những chỗ đau nhất:

Đây đều là những endpoint mà ứng dụng di động của tôi gọi định kỳ (poll) mỗi 30 giây. Nên đây không phải một con số tỉ lệ lỗi trừu tượng. Đó là điện thoại của từng người dùng, âm thầm không tải được số tin chưa đọc hiện trên biểu tượng, suốt cả ngày, và nhiều khả năng là đã như vậy mấy tuần liền.

Vì sao log vẫn trông bình thường

#

Phản xạ đầu tiên của tôi là ứng dụng đã bị chậm đi. Nhưng không phải. Tôi lấy từ kho nhật ký ra các dòng nhật ký yêu cầu của chính ứng dụng trong một khung giờ tệ nhất:

[2026-09-08 01:00:29] "GET /api/notifications/unread/" 304 61.615
[2026-09-08 01:00:29] "GET /api/notifications/"        304 63.568
[2026-09-08 01:00:59] "GET /api/notifications/unread/" 304 58.742
[2026-09-08 01:00:59] "GET /api/notifications/"        304 105.438

Từ bốn mươi bốn đến một trăm mili giây, toàn bộ đều là 304. Máy chủ gốc (origin) chạy rất nhanh.

Đó là manh mối quan trọng, và đáng để đúc kết thành một quy tắc: nếu tầng biên (edge) báo lỗi mà máy chủ gốc chưa từng nghe thấy, thì yêu cầu đã chết trước khi tới nơi. Lúc đó, hãy thôi đọc nhật ký ứng dụng và bắt đầu nhìn vào những gì đứng trước nó.

Trong trường hợp của tôi, thứ đứng trước là proxy của Fly.io, và câu trả lời nằm ở cách các máy (machine) của tôi được lên lịch chạy.

Thu về 0 (scale to zero) là lời hứa về tiền, không phải về độ trễ

#

Cấu hình của tôi trông như thế này, và thoạt nhìn thì khá hợp lý:

[http_service]
  auto_stop_machines = 'stop'
  auto_start_machines = true
  min_machines_running = 1

Máy nào rảnh thì tự dừng. Có lưu lượng thì tự bật lại. Dùng bao nhiêu trả bấy nhiêu. Với một ứng dụng nhỏ có lưu lượng lúc lên lúc xuống thất thường, đây đúng là thứ bạn cần, và đó cũng là lý do tôi khai báo mười máy nhưng gần như lúc nào cũng chỉ có một cái đang chạy.

Cái giá bị giấu đi ở đây là độ trễ (latency). Khi một yêu cầu tới một máy đang dừng, sẽ có người phải ngồi chờ máy đó khởi động. Nếu thời gian khởi động lâu hơn sức chờ của proxy, người đó sẽ nhận về lỗi 504.

Vậy máy của tôi mất bao lâu để khởi động? Tôi chưa từng đo. Nhưng kho nhật ký thì biết, vì script khởi động có in ra từng giai đoạn, và dòng nhật ký nào cũng kèm ID của máy:

WITH s AS (
  SELECT instance, timestamp,
         CASE WHEN message ILIKE '%Starting app server%' THEN 'begin'
              WHEN message ILIKE '%Migrations complete%' THEN 'migrated'
              WHEN message LIKE  '%"GET /healthz%'       THEN 'serving' END AS phase
  FROM logs
  WHERE app = 'myapp' AND timestamp::date = '2026-09-08'
)
SELECT instance,
       min(timestamp) FILTER (WHERE phase = 'begin')    AS started,
       min(timestamp) FILTER (WHERE phase = 'migrated') AS migrated,
       min(timestamp) FILTER (WHERE phase = 'serving')  AS first_serve
FROM s GROUP BY instance

Kết quả rất nhất quán trên mọi máy:

Sau đó tôi đếm xem chuyện này xảy ra bao nhiêu lần:

SELECT count(*) AS starts, count(DISTINCT instance) AS machines
FROM logs
WHERE app = 'myapp' AND timestamp::date = '2026-09-08'
  AND message ILIKE '%Starting app server%'
-- starts: 92, machines: 10

Chín mươi hai lần khởi động nguội (cold start) chỉ trong một ngày. Mỗi lần là một khoảng nửa phút, trong đó yêu cầu nào được định tuyến tới máy đó cũng đều hết thời gian chờ (timeout). Đến đây thì con số hai mươi hai phần trăm hết còn bí ẩn.

Thủ phạm nằm ngay trong script khởi chạy (entrypoint) của tôi

#

Đây là những gì mọi máy đều phải chạy trước khi chịu trả lời yêu cầu:

# entrypoint.sh, run on every machine start
echo "Running migrations..."
python manage.py migrate --noinput

echo "Running collectstatic in background..."
python manage.py collectstatic --noinput &

exec "$@"    # then start the app server

Hãy đọc lại đoạn này, lần này nhớ trong đầu con số “92 lần mỗi ngày”.

migrate là một lần khởi động Django trọn vẹn: nạp mọi mô hình, kết nối tới Postgres, truy vấn bảng migrations, rồi kết luận là chẳng có gì phải làm. Trên CPU dùng chung (shared CPU), mất mười giây chỉ để không làm gì cả. collectstatic là lần khởi động Django trọn vẹn thứ hai, sau đó còn tải các tệp tĩnh (static file) lên kho lưu trữ đối tượng (object storage), tranh giành đúng một nhân CPU duy nhất mà máy chủ web đang cố khởi động trên đó. Máy chủ ứng dụng (app server) là lần khởi động thứ ba.

Ba trình thông dịch Python, hai trong số đó làm lại những việc đã xong từ trước, và chuyện này lặp lại mỗi khi một máy thức dậy.

Tôi viết như vậy là có lý do chính đáng, và có lẽ script khởi chạy của bạn trông na ná cũng vì lý do đó: chuyển đổi lược đồ thì phải chạy ở đâu đó, release_command của Fly từng bị treo với tôi, và script khởi chạy là nơi duy nhất chắc chắn được chạy mỗi lần triển khai. Đặt việc của khâu triển khai vào đó là đúng. Có điều, đó không phải chỗ đúng để chạy việc đó mỗi lần máy khởi động, và một khi máy tự dừng rồi tự bật lại, hai sự kiện này không còn là một nữa.

Toàn bộ lỗi chỉ có vậy, và tôi nghĩ nó khá phổ biến:

Những việc thuộc về một lần phát hành lại bị chạy lại mỗi lần máy khởi động. Cơ chế thu về 0 biến một sự kiện thành chín mươi hai sự kiện.

Cách sửa: mỗi bản phát hành chỉ chuẩn bị đúng một lần

#

Bước chuyển đổi lược đồ không cần chạy lại trên chiếc máy thứ tám khởi động từ cùng một image. Nó chỉ cần chạy một lần cho image đó, và mọi máy khác cần biết là việc này đã xong.

Nói cách khác, ta cần một khóa (lock) có tên thay đổi theo từng lần triển khai. Fly cung cấp sẵn cái tên đó trong FLY_IMAGE_REF, còn Redis thì tôi đã có sẵn. Tất cả chỉ là một script nhỏ chạy trước khi Django được nạp, nên trong trường hợp thường gặp, nó chỉ tốn vài mili giây thay vì một lần khởi động cả framework:

# release_gate.py: runs before Django exists. Exit code 0 means "prepare this release".
import os, time

PREPARE, SKIP = 0, 1
LOCK_TTL, WAIT, POLL = 300, 240, 2
_sleep, _monotonic = time.sleep, time.monotonic    # aliases, so tests can replace them


def release_id() -> str:
    """Something that changes exactly when the deployed image does."""
    return os.getenv("FLY_IMAGE_REF") or os.getenv("FLY_MACHINE_VERSION") or ""


def claim(client, release: str) -> int:
    if client is None or not release:   # no Redis, or no idea which release: behave as before
        return PREPARE
    done_key, lock_key = f"release:{release}:done", f"release:{release}:lock"
    if client.get(done_key):            # somebody already did it for this image
        return SKIP

    owner = os.getenv("FLY_MACHINE_ID", "unknown")
    if client.set(lock_key, owner, nx=True, ex=LOCK_TTL):
        return PREPARE                  # we won the race; we do the work

    # Someone else is preparing. Wait for them, because serving requests
    # against a half-migrated schema is worse than starting slowly.
    deadline = _monotonic() + WAIT
    while _monotonic() < deadline:
        _sleep(POLL)
        if client.get(done_key):
            return SKIP
        if client.set(lock_key, owner, nx=True, ex=LOCK_TTL):
            return PREPARE              # the owner died and its lock expired; take over
    return PREPARE                      # waited long enough; do it ourselves

# ... plus `done` (sets done_key) and a main() that treats any Redis error as PREPARE