Zero and Seven · Hệ thương hiệu nội dung số

Sổ tay vận hành (runbook) cho hệ site: viết sao để người sau làm được không cần hỏi

Cách viết sổ tay vận hành cho hệ nhiều site: khuôn một mục việc, bản đồ máy và thư mục, mục bẫy đã trả giá, ghi ngày và đính chính, thử sổ bằng người mới.

Vận hành nhiều siteĐăng 8 phút đọcNhóm biên tập 0n7

Sổ tay vận hành tốt là sổ mà người chưa từng làm việc đó đọc xong làm được đúng, không phải nhắn hỏi ai. Muốn vậy, mỗi mục việc phải có cùng một khuôn: khi nào dùng, cần gì trước, các bước theo thứ tự với lệnh cụ thể, cách kiểm kết quả, cách quay lui nếu sai. Kèm theo là một bản đồ hệ (máy nào, tài khoản nào, thư mục nào chứa site nào) và một mục bẫy ghi những lần đã trả giá.

Với hệ nhiều site, sổ tay quan trọng hơn hẳn vì không ai nhớ hết mấy chục tên miền nằm ở đâu, chạy mã gì. Và nó có một rủi ro riêng: sổ sai còn tệ hơn không có sổ, vì người đọc tin và làm theo. Phần lớn bài này nói về cách giữ sổ đúng theo thời gian.

Khuôn của một mục việc

Mỗi việc lặp lại hoặc mỗi tình huống sự cố nên có một mục riêng theo cùng khuôn. Khuôn giống nhau giúp người đọc biết tìm thông tin ở đâu, kể cả lúc đang căng thẳng.

  • Tên việc và khi nào dùng. "Thêm một tên miền vào site đang chạy" chứ không phải "tên miền". Một câu nói rõ tình huống nào thì mở mục này.
  • Điều kiện trước. Cần quyền gì, cần khoá nào, cần chạy từ máy nào. Hầu hết lần làm theo sổ mà thất bại là vì thiếu một điều kiện không ai ghi.
  • Các bước có thứ tự, kèm lệnh chép được. Lệnh viết đầy đủ đường dẫn, không viết tắt kiểu "vào thư mục site". Bước nào có chế độ chạy thử thì ghi chạy thử trước.
  • Cách kiểm đã xong. Kết quả mong đợi trông như thế nào: mã trả về, số dòng, nội dung trang. "Chạy xong không báo lỗi" không phải cách kiểm.
  • Đường quay lui. Sai thì làm gì để về trạng thái trước.
  • Bẫy riêng của việc này. Những chỗ đã có người vấp, viết ngắn, kèm lý do.
  • Ngày kiểm gần nhất và người kiểm. Mục không ai làm theo trong một năm có thể đã sai.

Một mẹo nhỏ nhưng hiệu quả: nếu việc đã có kịch bản tự động, mục trong sổ chỉ cần chỉ ra kịch bản, cách chạy thử và cách chạy thật. Đừng chép lại logic của kịch bản vào sổ, vì hai bản sẽ lệch nhau sau lần sửa đầu tiên. Và ghi rõ trong sổ: đừng bảo người khác làm tay việc mà kịch bản đã làm được.

Một mục mẫu viết theo khuôn, rút gọn: "Thêm tên miền phụ cho một site đang chạy. Dùng khi có tên miền mới cần trỏ vào site có sẵn. Cần: khoá bảng điều khiển, chạy từ máy build. Bước một chạy kịch bản thêm tên miền ở chế độ thử, đọc kết quả bốn bước. Bước hai chạy thật. Kiểm: gọi tên miền mới qua đường người đọc, trang trả nội dung của đúng site, không phải trang mặc định. Quay lui: chạy kịch bản ở chế độ gỡ. Bẫy: quên nạp lại máy chủ web là tên miền trả trang mặc định dù mọi bước khác đã xong. Kiểm lần cuối: tháng trước." Mục như vậy người mới đọc trong một phút và làm được.

Bản đồ hệ: trang đầu tiên của sổ

Trước mọi mục việc là bản đồ. Đây là trang người mới cần đọc đầu tiên và người cũ tra nhiều nhất. Ví dụ giả định một phần bản đồ:

MáyTài khoảnThư mục gốcChứa gìKho mãLưu ý
Máy Atài khoản 1Thư mục site chínhMã chung cho nhiều site, các tên miền trỏ vàokho chungĐẩy kèm xoá tệp thừa
Máy Atài khoản 2Thư mục site XSite kiến thứckho XKhông xoá tệp thừa: thư mục gốc chứa dữ liệu cũ
Máy Atài khoản 2Tên miền phụ của site XỨng dụng riêng, mã khác hẳnkho ứng dụngCùng tài khoản với site X, dễ đẩy nhầm
Máy Btài khoản 3Thư mục site mớiSite chỉ có ở máy nàykho YSao lưu kéo ngược về máy build

Cột lưu ý là cột cứu người. Một tài khoản chứa hai mã khác nhau, một tên tài khoản trùng với tên một dự án khác, một thư mục không được đẩy kèm xoá: những điều này không suy ra được từ tên, và chỉ cần một lần nhầm là mất dữ liệu. Bản đồ cũng nên ghi rõ ngày cập nhật, và mỗi lần thêm site hay chuyển máy thì sửa bản đồ trước khi coi việc là xong.

Ghi ngày, ghi đính chính, không sửa lặng lẽ

Sổ tay sai theo thời gian vì hệ thay đổi mà sổ không theo kịp. Một câu từng đúng như "không có quyền quản trị cao nhất trên máy này" có thể sai từ khi ai đó cài thêm khoá. Người đọc sau tin câu đó, kết luận việc mình cần làm là không thể, rồi đẩy việc cho người khác làm tay. Trong khi chỉ cần một lệnh kiểm mất hai giây là biết sự thật.

Hai thói quen giúp hạn chế việc này. Thứ nhất, câu nào là phát biểu về trạng thái hệ thì ghi kèm ngày đo: "đo ngày này: máy chạy phiên bản đó". Người đọc thấy ngày cũ sẽ biết cần kiểm lại. Thứ hai, khi phát hiện một câu sai, không xoá lặng lẽ mà ghi đính chính ngay tại chỗ: câu cũ nói gì, sự thật là gì, đo ngày nào, và câu cũ đã gây ra hậu quả gì. Đính chính có hậu quả đi kèm là thứ khiến người đọc nhớ.

Kèm theo là một quy tắc cho người dùng sổ: trước khi tuyên bố một việc không làm được vì sổ nói vậy, chạy lệnh kiểm. Sổ là bản đồ, không phải lãnh thổ. Khi bản đồ và lãnh thổ khác nhau, tin lãnh thổ, rồi sửa bản đồ.

Mục bẫy: phần đáng giá nhất của sổ

Ghi bẫy kèm cái giá. "Đừng xoá thư mục cũ trước khi gói ảnh" dễ bị bỏ qua. "Đã có lần xoá thư mục cũ trước khi gói ảnh và mất toàn bộ ảnh gốc, chỉ còn đường dẫn trong cơ sở dữ liệu" thì không ai bỏ qua. Cái giá là thứ làm một dòng cảnh báo có sức nặng.

Ghi cả cách nhận ra. Bẫy tốt có ba phần: tình huống, triệu chứng, cách tránh. Triệu chứng giúp người gặp sự cố tra ngược: thấy trang chủ hiện nội dung site khác thì tìm tới mục khoá đệm trùng.

Đặt bẫy gần mục việc liên quan. Một danh sách bẫy dài ở cuối sổ ít người đọc tới. Bẫy của việc đẩy mã nên nằm ngay trong mục đẩy mã, chỉ giữ ở mục chung những bẫy chạm nhiều việc.

Ghi bẫy của chính công cụ kiểm. Công cụ kiểm báo sạch khi nó không kiểm được gì là loại bẫy nguy hiểm nhất, vì nó tạo cảm giác an toàn. Mỗi lần phát hiện một công cụ như vậy, sửa công cụ để báo lỗi, và ghi lại vào sổ để người sau biết kết quả cũ không đáng tin.

Đừng để mục bẫy phình vô hạn. Bẫy đã được chặn hẳn bằng mã hoặc kịch bản thì rút gọn còn một dòng lịch sử. Sổ quá dài cũng là một cách che thông tin quan trọng.

Thử sổ bằng người chưa từng làm

Cách duy nhất biết sổ dùng được là cho một người chưa làm việc đó làm theo, trong khi người viết ngồi im quan sát.

  1. Chọn một mục việc thật, ví dụ thêm tên miền hay khôi phục một site từ bản lưu, trên môi trường không ảnh hưởng người đọc.
  2. Người thử chỉ được đọc sổ, không được hỏi. Người viết ghi lại mọi chỗ người thử dừng, đoán, hoặc tra ngoài sổ.
  3. Mỗi chỗ dừng là một lỗ của sổ: thiếu điều kiện, lệnh không chép được, kết quả mong đợi không rõ.
  4. Sửa sổ ngay trong buổi đó, khi chi tiết còn nhớ.
  5. Ghi ngày thử và người thử vào mục việc.

Người thử lý tưởng không nhất thiết là người mới vào nhóm. Một trợ lý tự động được giao đọc sổ và làm theo cũng lộ ra rất nhanh những chỗ sổ ngầm định điều người viết biết mà không ghi, ví dụ thư mục nhà của người chạy lệnh khác với thư mục chứa công cụ, nên mọi đường dẫn viết tắt đều trỏ sai chỗ.

Những mục mà sổ của hệ nhiều site nào cũng cần

Danh sách dưới đây là bộ khung tối thiểu. Mỗi mục là một việc thật sự lặp lại hoặc một tình huống sẽ xảy ra, sớm hay muộn.

  • Thêm một tên miền vào site đang chạy: tạo ở bảng điều khiển hoặc qua giao diện lập trình, trỏ về thư mục chung, nạp lại máy chủ web, thêm vào bảng site của ứng dụng. Thiếu một bước là tên miền trả trang mặc định.
  • Dựng một site mới, kèm chỗ đặt thư mục đúng quy ước. Đặt sai chỗ, ví dụ vào thư mục bị đồng bộ kèm xoá mỗi đêm, là đêm sau mất trắng.
  • Đẩy mã, gồm kiểm lệch, các đợt, cách kiểm sau đẩy.
  • Kéo về khi kiểm lệch báo đỏ, kèm cách giữ quyền ghi tệp cho mọi tài khoản dùng chung kho mã.
  • Khôi phục một site từ bản lưu.
  • Xử lý chứng chỉ sắp hết hạn khi gia hạn tự động thất bại.
  • Xoá đệm đúng thứ tự.
  • Thu hồi quyền khi một người rời nhóm: khoá máy chủ, khoá cơ sở dữ liệu, khoá quản tên miền, tài khoản quản trị site.
  • Khi bị chặn quyền: việc cần quyền mà người làm không có thì chuẩn bị đến đâu, xin ai, xin cái gì.

Mục cuối nghe lạ nhưng hữu ích. Người làm theo sổ, dù là người hay trợ lý tự động, hay gặp bước cần quyền cao hơn mình có. Cách tốt là chuẩn bị trọn mọi thứ có thể (kịch bản, kiểm cú pháp, chạy thử), rồi xin đúng một thao tác cụ thể từ người có quyền, thay vì đưa họ một loạt lệnh rời rạc phải dán nhiều lần.

Sổ nên ngắn tới đâu

Sổ tay có xu hướng phình ra: mỗi phiên làm việc thêm vài dòng, mỗi sự cố thêm một mục, và sau một năm trang đầu là lịch sử mà phần quan trọng nằm tận cuối. Một số công cụ còn chỉ đọc được phần đầu của tệp dài, nên phần cuối, thường là bẫy mới nhất, bị bỏ qua.

Cách giữ gọn là tách tầng. Trang chính chỉ chứa bản đồ hệ, cách đẩy, những bẫy quan trọng nhất, và mục lục trỏ tới các trang chi tiết. Nhật ký bàn giao giữa các phiên, lịch sử sự cố, ghi chép điều tra để ở các tệp riêng có ngày, không ghi nối vào trang chính. Trang chính chỉ sửa khi bản đồ, cách đẩy hoặc một bẫy quan trọng thay đổi.

Một con số giới hạn tự đặt, ví dụ trang chính không vượt quá độ dài đọc được trong mười phút, giúp cả nhóm có lý do để rút gọn thay vì chỉ thêm. Khi vượt, việc đầu tiên là chuyển những gì không phải bản đồ, cách đẩy hay bẫy quan trọng sang trang chi tiết, và để lại ở trang chính một dòng trỏ tới đó.

Hỏi đáp

Sổ tay nên để ở đâu?

Gần mã nhất có thể, tốt nhất ngay trong kho mã của hệ, để mỗi lần sửa mã người sửa thấy và cập nhật sổ. Sổ để ở một công cụ ghi chú riêng thường bị bỏ quên. Phần chứa thông tin nhạy cảm như mật khẩu thì không để trong sổ, chỉ ghi chỗ cất.

Ai chịu trách nhiệm cập nhật sổ?

Người làm thay đổi. Quy tắc đơn giản: thay đổi chưa được ghi vào sổ thì chưa xong. Thêm một người rà sổ định kỳ, ví dụ mỗi quý, để bắt những chỗ đã lệch mà không ai để ý.

Có nên ghi lệnh đầy đủ hay chỉ mô tả?

Ghi lệnh đầy đủ, chép được, với đường dẫn tuyệt đối. Mô tả kiểu "đồng bộ thư mục lên máy chủ" để mỗi người tự diễn giải, và mỗi người sẽ quên một tuỳ chọn khác nhau, ví dụ bộ loại trừ tệp cấu hình. Lệnh nguy hiểm thì ghi bản chạy thử trước bản chạy thật.

Sổ tay khác tài liệu kỹ thuật thế nào?

Tài liệu kỹ thuật giải thích hệ được xây ra sao và vì sao. Sổ tay vận hành trả lời "cần làm việc X thì gõ gì, theo thứ tự nào, kiểm thế nào". Người đọc sổ tay thường đang vội hoặc đang có sự cố, nên câu chữ phải ngắn và hành động được.

Làm sao để mọi người thật sự đọc sổ?

Đưa sổ vào đúng lúc người ta cần: kịch bản đẩy in ra đường dẫn tới mục liên quan khi gặp lỗi, cảnh báo giám sát kèm tên mục xử lý. Và giữ sổ đúng, vì chỉ cần vài lần làm theo sổ mà hỏng, mọi người sẽ thôi tin và quay lại hỏi miệng.

  • sổ tay vận hành
  • runbook
  • tài liệu vận hành website
  • quy trình vận hành
  • bàn giao kỹ thuật
  • hệ nhiều site
  • tài liệu nội bộ
  • xử lý sự cố
  • vận hành nhiều site