Orkestr Guide / Playbookorkestr-guide.aila.vn
XỬ LÝ SỰ CỐ & TÌNH HUỐNG

Khoanh vùng đúng.
Khôi phục có căn cứ.

Các kịch bản theo dấu hiệu thực tế: lỗi đăng nhập, queue bị đứng, provider chưa rõ kết quả và website lỗi sau triển khai. Mỗi bước đều có cách kiểm lại.

Bắt đầu khoanh vùng Tra cứu dấu hiệu
Developer & operator · PlaybookCập nhật
01

Một quy trình chung

Tiếp nhận & khoanh vùng

Mỗi kịch bản đi từ dấu hiệu đến kiểm tra, khôi phục và xác nhận. Chọn theo lỗi quan sát được, giữ nguyên dữ liệu khi chưa biết kết quả của thao tác trước.

  1. Ghi nhận: môi trường, hostname, build đang chạy, thời điểm và bước tái hiện. Thu mã lỗi/request ID nếu có; không gửi token hoặc nội dung ENV vào báo cáo.
  2. Xác định phạm vi: chỉ Portal, chỉ Console, cả hai frontend, API, database hay provider bên ngoài. Kiểm health và một request lỗi trong Network.
  3. Chọn kịch bản: đăng nhập/quyền, queue/runner, provider chưa rõ kết quả hoặc sau triển khai.
  4. Khôi phục có bằng chứng: sửa cấu hình hoặc tiến trình liên quan; dùng thao tác retry/reconcile đúng trạng thái. Không xóa queue, volume hoặc lịch sử để làm mất triệu chứng.
  5. Xác nhận: lặp lại bước từng lỗi bằng user đúng quyền và một user bị giới hạn; ghi hành động và kết quả vào bản bàn giao.
02

Kịch bản 01 · Identity

Đăng nhập hoặc quyền truy cập lỗi

REDIRECT_URI · 401 · 403

Dùng khi Keycloak từ chối redirect, đăng nhập xong API trả 401, hoặc Console từ chối một user tưởng là admin.

1. Kiểm đúng môi trường

Local mặc định dùng orkestr-e2e. POC/dev dùng auth-dev realm orkestr. Kiểm URL đăng nhập và file ENV của process API; domain frontend không tự quyết định issuer backend.

2. Phân loại bằng dấu hiệu

redirect_uri: so client ID và origin. 401: kiểm issuer, audience, JWKS và thời hạn. 403: kiểm quyền server, realm role admin hoặc membership của project.

3. Sửa cấu hình đúng chỗ

Đối chiếu hai client Keycloak. Thêm audience mapper cho cả hai. Gán orkestr-admin cho user cần Console và đảm bảo claim role có trong access token; không cấp quyền project bằng realm role.

4. Xác nhận phục hồi

Đăng xuất/đăng nhập lại để lấy token mới. Kiểm /api/v1/me, mở đúng màn hình và thử logout. User không có role admin vẫn phải bị từ chối API quản trị.

Không bỏ kiểm tra JWT hoặc mở wildcard để chữa lỗi.

Giữ xác minh issuer/audience/chữ ký và khai báo origin chính xác. Nếu cần cung cấp bằng chứng, chỉ gửi tên claim và kết quả kiểm; giữ token trên máy vận hành.

03

Kịch bản 02 · Background jobs

Planning, sync hoặc run bị đứng

QUEUED · PLANNING · EXECUTION

API vẫn mở được nhưng thao tác sau đó không tiến triển. Tách công việc của worker khỏi công việc của runner để kiểm đúng tiến trình.

  1. Đọc trạng thái thật: planning/sync thuộc worker, execution thuộc runner. Nếu run đang Waiting for approval, hoàn tất approval cần thiết thay vì restart.
  2. Kiểm nền tảng: health/database, log của process, cùng DATABASE_URL và phiên bản giữa ba process. Kiểm có process cũ dùng ENV khác còn hoạt động hay không.
  3. Nếu execution: xác nhận Docker đang chạy, RUNNER_IMAGE dùng được, DATA_DIR có quyền và đường dẫn bind mount tồn tại trên host. Xem log timeout/resource limit trước khi thay giá trị.
  4. Khôi phục: khởi động process bị dừng bằng cấu hình của môi trường. Với lỗi đã rõ, dùng Retry được UI cung cấp. Nếu provider có thể đã ghi, chuyển sang kịch bản đối soát bên dưới.
  5. Kiểm lại: chạy planning hoặc ticket test trên resource được phép; xác nhận log SSE, trạng thái cuối và report. Không xóa queue hoặc chạy migration revert để mở khóa job.
04

Kịch bản 03 · External mutation

Provider timeout hoặc dữ liệu xung đột

CONFLICT · NEEDS_RECONCILIATION

Request timeout không đủ kết luận rằng provider chưa ghi. Ưu tiên xác nhận remote trước khi tạo thêm issue, page hoặc MR.

1. Giữ lại bằng chứng

Ghi project, provider, target, version và trạng thái attempt. Không đổi site/cloud/project identity qua ENV trong khi hàng đợi cũ chưa được xử lý.

2. Nếu là conflict

Owner/người có quyền mở snapshot remote, chọn Keep remote hoặc Overwrite. Remote đổi tiếp sau snapshot thì đọc lại và quyết định lại; không tự sửa hash/marker.

3. Nếu cần reconciliation

Owner mở Publish result/Version history, tìm theo marker hoặc nhập ID chính xác. Backend đọc remote, kiểm target, marker và payload hash. Chỉ một kết quả khớp mới được liên kết.

4. Xác nhận liên kết

Đối chiếu issue/page ID và version, bảo đảm không có bản trùng. Với delivery GitLab, retry PRReady đối chiếu SHA, branch và marker MR; thiếu bằng chứng thì tiếp tục giữ trạng thái chặn.

Chưa xác định được thì giữ trạng thái cần đối soát.

Không blind retry, xóa marker hay sửa database để bỏ qua. Kiểm quyền provider và dữ liệu remote trước; hướng dẫn cấu hình ở Runbook tích hợp.

05

Kịch bản 04 · Deploy & routing

Website lỗi sau triển khai

DNS · TLS · CORS · SPA ROUTING

Xác định lỗi nằm ở DNS/TLS, static output, API proxy hay cấu hình build trước khi thay phiên bản.

  1. DNS/TLS: kiểm hostname trỏ đúng hosting và chứng chỉ đúng tên. Nếu chưa đúng, đối chiếu target được hạ tầng cung cấp; không đoán IP.
  2. Static output: Portal dùng frontend/dist/portal/browser, Console dùng frontend/dist/console/browser. Kiểm hai site không phục vụ nhầm bundle/client ID.
  3. API: response phải là JSON từ /api/v1, không là HTML của fallback. Kiểm API base trong build và CORS của hai origin frontend.
  4. Deep link: Portal/Console cần SPA fallback cho route Angular. Guide có các thư mục HTML thật /setup, /runbook, /playbook; URL không tồn tại phải giữ 404.
  5. Phục hồi: sửa route/config và deploy đúng output. Nếu quay frontend về build trước, xác nhận tương thích API hiện tại. Backend/database dùng kế hoạch phục hồi có backup; không tự revert migration đã có dữ liệu.
  6. Xác nhận: mở trực tiếp route con, refresh, đăng nhập/đăng xuất, gọi health và kiểm một thao tác trong app. Với Guide, kiểm ba mục và một URL 404.
06

Tìm nguyên nhân theo dấu hiệu

Tra cứu nhanh theo dấu hiệu

Keycloak: Invalid parameter: redirect_uri

Xem client_id và redirect_uri trong request đăng nhập. Portal phải dùng orkestr-portal, Console dùng orkestr-console. So khớp scheme, hostname, cổng và path với Valid redirect URIs của đúng client/realm. POC thêm localhost vào realm dev; local mặc định dùng realm Docker.

Đăng nhập thành công nhưng API trả 401

Kiểm iss trùng hoàn toàn OIDC_ISSUER, aud chứa orkestr-api, token chưa hết hạn/quá OIDC_MAX_TOKEN_AGE và JWKS truy cập được từ host API. Cả hai client cần audience mapper. Đăng nhập lại sau khi sửa mapper.

Console báo không có quyền dù user là Owner

Owner là quyền project. Gán realm role orkestr-admin trong đúng realm, xác nhận role xuất hiện trong realm_access.roles, đăng nhập lại và kiểm GET /api/v1/me. Nếu API lỗi, UI không được dùng quyền cũ để mở trang quản trị.

Đăng xuất lỗi hoặc quay về nhầm ứng dụng

Kiểm Valid post logout redirect URIs của đúng client. Portal quay về origin Portal, Console quay về origin Console. Không dùng domain dev trong client production. Kiểm build đang phục vụ và cache nếu URL không đúng cấu hình mới.

CORS, API trả HTML hoặc refresh route bị 404

CORS: điền cả hai origin frontend trong ENV backend và Web origins tương ứng trên Keycloak. API base phải trỏ API đúng /api/v1. HTML thay JSON thường do proxy/fallback bắt nhầm API. Route Angular cần SPA fallback riêng của từng ứng dụng; Guide giữ 404 thật.

Không thấy project được mời hoặc dữ liệu POC

Kiểm email đăng nhập trùng email được mời và email_verified là true. User thuộc realm local và realm auth-dev có sub khác nhau. Xác nhận API đang dùng đúng database/ENV, rồi tạo project test hoặc mời đúng user; không sửa quyền trực tiếp trong database để bỏ qua kiểm tra.

Run đứng ở Queued hoặc Analyze không tạo plan

Queued execution: kiểm runner còn chạy, Docker sẵn sàng, image đã có và storage mount đúng. Planning/sync: kiểm worker. Cả ba process phải cùng database và cấu hình. Xem lỗi trong UI/log đã loại secret trước khi retry.

CLI chưa kết nối, phiên hết hạn hoặc model không chạy

Kiểm AI_AUTH_ENABLED, executable path, quyền service account và DATA_DIR. Windows dùng native .exe. Sau restart hoặc hết TTL, tạo lại phiên. Trạng thái CLI connected và grant model chưa nối vào execution; kiểm cấu hình OpenAI-compatible nếu workflow cần AI thật.

Provider chưa cấu hình, 403 hoặc needs_reconciliation

Kiểm nhóm ENV đầy đủ, allowlist có ID số đúng, quyền tài khoản và cloud ID khớp loại token. Đảm bảo cả ba process đã restart sau xoay secret. Với needs_reconciliation, Owner đối soát remote; không gửi lại mutation khi chưa biết lần trước đã ghi hay chưa.

EADDRINUSE hoặc cấu hình cũ vẫn có hiệu lực

Dừng process cũ đang giữ cổng 3300/4200/4300 trước khi đổi local ↔ POC. Kiểm biến môi trường trong process cha vì chúng ưu tiên hơn --env-file. Chạy lại đúng script và kiểm issuer bằng request đăng nhập mới.

Khi cần chuyển giao sự cố

Ghi môi trường, phiên bản build, hostname, thời điểm, bước tái hiện và mã lỗi. Chia sẻ log đã redaction; giữ token, mã đăng nhập, secret và nội dung ENV ngoài bản gửi hỗ trợ.