VẬN HÀNH THƯỜNG NGÀY

Vận hành nhất quán.
Thay đổi có kiểm chứng.

Kiểm dịch vụ, quản lý database và migration, kết nối provider và cấp model. Những thao tác lặp lại có thứ tự, cấu hình và kết quả cần xác nhận.

Checklist vận hành Kiểm tra triển khai

Developer & operator · RunbookCập nhật 05.11.2026

Kiểm tra đầu phiên vận hành

Nhịp vận hành thường ngày

Bắt đầu từ sức khỏe dịch vụ, sau đó kiểm queue và các kết nối đang sử dụng. Theo dõi đúng môi trường và đúng phiên bản đang phục vụ.

Việc cần kiểm	Thực hiện	Kết quả mong đợi
API & database	Mở `/api/v1/health` của môi trường.	Database up; không có HTML hoặc lỗi proxy thay JSON.
Process	Kiểm API, worker và runner trong service manager đang dùng.	Cùng phiên bản, ENV và database; không restart liên tục.
Queue	Xem publish/sync, planning và run đang chờ trong Portal.	Công việc tiến triển; lỗi có nguyên nhân và thao tác khôi phục rõ ràng.
Storage & Docker	Kiểm dung lượng, quyền DATA_DIR và Docker của runner.	Đọc/ghi được; workspace và artifact đang dùng còn nguyên.
Tích hợp	Connect/Check khi thay cấu hình/quyền; xem attempt lỗi.	Target đúng allowlist, không có mutation chưa được đối soát.
AI	Console xem tài khoản đã kết nối và grant theo project.	Phân biệt authorization với trạng thái inference thực tế.

Khởi động lại đúng bộ tiến trình.

Khi đổi ENV hoặc phiên bản, xử lý API, worker và runner như cùng một backend. Phiên CLI đang chờ sẽ mất khi API restart; tài khoản đã kết nối được giữ trong DATA_DIR. Hướng dẫn lỗi cụ thể nằm trong Playbook.

Dữ liệu trước, tiến trình sau

Database & migration

Mỗi môi trường có database và thư mục dữ liệu riêng. Ba tiến trình trong cùng môi trường phải chạy cùng phiên bản backend, cùng ENV và cùng storage.

Tạo database/user PostgreSQL, cấp quyền cần thiết để chạy migration. Điền DATABASE_URL trong đúng file ENV; không dùng database test cho dữ liệu thật.
Tạo DATA_DIR bền vững, cấp quyền cho service account. Nếu runner gọi Docker trên host, đường dẫn bind mount phải tồn tại đúng trên host.
Trước nâng cấp: sao lưu PostgreSQL và DATA_DIR, dừng API/worker/runner đang ghi. Giữ bản build cũ và thông tin phiên bản để phục hồi.
Build, kiểm cấu hình và chạy migration một lần trên đúng database. Sau đó khởi động lại cả ba process.

Terminal · từ thư mục backend/ · ví dụ dev

npm ci
npm run build
node --env-file=../.env.dev -e "require('./dist/common/config/env.js').loadConfig(); process.stdout.write('Configuration OK\n')"
node --env-file=../.env.dev dist/database/cli.js run

Configuration OK chỉ xác nhận cấu trúc ENV, không xác nhận network, secret, quyền provider hay model. Với main, thay file bằng ../.env.main.

Từ backend/ · mỗi dòng một service hoặc terminal

node --env-file=../.env.dev dist/main.js
node --env-file=../.env.dev dist/worker.js
node --env-file=../.env.dev dist/runner.js

Migration liên quan

1792594860000-gitlab-atlassian-integrations.ts bổ sung bindings và operation intents cho provider. ProjectAiAccess1793145600000 bổ sung grant/selection AI theo project. Chạy toàn bộ migration pending bằng CLI.

Khôi phục có chủ đích

migration:revert có thể xóa dữ liệu và không phải rollback triển khai mặc định. Khi đã có provider history, migration down có thể từ chối. Dừng writers và lập phương án restore backup thay vì ép xóa lịch sử.

Code · Story · PRD

GitLab, Jira & Confluence

Chọn độc lập nơi chứa code, nơi nhận Story và nơi nhận PRD. Operator điền secret trên server; Project Owner chọn target trong Portal.

GitLab Repository + Merge RequestJira Story → IssueConfluence PRD → Page

GitLab self-hosted — repository, issue và Merge Request

GITLAB_BASE_URL: HTTPS URL gốc; có thể có installation subpath, không thêm /api/v4.
GITLAB_ACCESS_TOKEN: Service/project token có quyền API và Git repository đọc/ghi.
GITLAB_ALLOWED_PROJECT_IDS: Project ID số, ngăn bằng dấu phẩy. Allowlist rỗng không cho chọn target.

Project cần default branch. Tài khoản cần quyền Developer trở lên cho code, push nhánh ai/* và mở MR. Bật Issues nếu Story dùng GitLab Issues. Orkestr không tự merge MR hay push default branch.

CA nội bộ: mount PEM và đặt NODE_EXTRA_CA_CERTS trước khi Node khởi động trên cả ba process; cấu hình CA cho Git HTTPS tương ứng. Không tắt xác minh TLS. Tài liệu token GitLab ↗

Jira Cloud — xuất Story thành issue

JIRA_BASE_URL: Origin site HTTPS, ví dụ https://example.atlassian.net; không thêm API path.
JIRA_EMAIL / JIRA_API_TOKEN: Tài khoản dịch vụ và token theo môi trường.
JIRA_ALLOWED_PROJECT_IDS: Project ID số, không dùng project key.
JIRA_CLOUD_ID: Điền khi loại token yêu cầu Atlassian gateway; để trống khi gọi trực tiếp site.

Cấp Browse Projects, Create Issues, Edit Issues. Chọn issue type thường, chuẩn bị issue type ID và default cho các field bắt buộc ngoài summary/description/project/issuetype. Tài liệu xác thực Jira ↗

Confluence Cloud — xuất PRD thành page

CONFLUENCE_BASE_URL: Origin site HTTPS; không thêm /wiki.
CONFLUENCE_EMAIL / CONFLUENCE_API_TOKEN: Secret riêng cho Confluence, không tự kế thừa Jira.
CONFLUENCE_ALLOWED_SPACE_IDS: Space ID số, không dùng space key.
CONFLUENCE_CLOUD_ID: Điền khi token yêu cầu gateway; để trống khi gọi trực tiếp site.

Cấp quyền đọc space/page, tạo page và sửa page Orkestr quản lý. Parent page tùy chọn phải đang current và thuộc đúng space. Tài liệu Confluence REST v2 ↗

Thao tác trên Portal

Operator điền ENV, chạy migration rồi restart API/worker/runner cùng cấu hình.
Owner vào Settings → Integrations, nhập project/space/issue type/parent page ID và chọn Connect/Check. Bước này đọc metadata, kiểm quyền; không tạo issue, page hay MR.
Chọn Work-item destination cho Story. Bật PRD → Confluence riêng nếu cần.
Thêm repository GitLab từ project đã kết nối. Chạy smoke trên resource test được chỉ định.

Khi publish bị conflict hoặc needs_reconciliation

Conflict: xem nội dung remote rồi chọn Keep remote hoặc Overwrite. Nếu remote tiếp tục đổi sau snapshot, phải đọc và quyết định lại.

needs_reconciliation: provider có thể đã ghi dù request timeout. Owner mở Publish result/Version history và đối soát bằng marker hoặc ID chính xác. Backend chỉ liên kết khi target, marker và hash khớp duy nhất. Không blind retry hoặc sửa database để bỏ qua trạng thái.

Đổi destination chỉ ảnh hưởng lần publish tiếp theo. Binding đã có lịch sử không được đổi sang ID/issue type/parent khác. Xoay token cùng identity: thay secret rồi restart cả ba process; đổi site/target cần cấu hình mới.

Phạm vi hiện tại: GitLab self-hosted, Jira/Confluence Cloud; chưa có Data Center, OAuth tương tác hay webhook đồng bộ ngược. Kiểm thử fixture không chứng minh live provider đã hoạt động.

Console quản trị · Portal lựa chọn

Tài khoản & model AI

System Admin kết nối tài khoản Claude/Codex dùng chung và cấp danh sách model. Project Owner chọn provider/model trong phạm vi được cấp.

Đăng nhập CLI ≠ chạy workflow bằng CLI.

Hiện lưu trạng thái authorization, quyền model và lựa chọn project. Các tài khoản này chưa được nối vào inference của Model Gateway. One Nexus đang chờ thông tin dịch vụ.

Chuẩn bị máy API

Cài CLI chính thức của Claude Code và Codex trên host chạy API. Windows trỏ tới executable native .exe, không dùng npm shim .cmd/.ps1. Linux dùng executable hợp lệ trên PATH hoặc đường dẫn tuyệt đối.

ENV backend · đường dẫn là mẫu, thay theo máy

AI_AUTH_ENABLED=true
CLAUDE_CLI_PATH=/usr/local/bin/claude
CODEX_CLI_PATH=/usr/local/bin/codex
AI_AUTH_SESSION_TTL_SECONDS=600
DATA_DIR=/srv/orkestr-dev/data

Chạy API bằng service account riêng. Giới hạn quyền thư mục DATA_DIR/ai-auth; không đưa credential vào Git, static hosting, artifact download hoặc container chạy mã repository. Chức năng giữ phiên đăng nhập đang chờ trong bộ nhớ API; restart sẽ yêu cầu tạo lại phiên. Nếu nhiều API instance, cần session affinity và credential storage chung.

Kết nối và cấp quyền

Admin vào Console /ai-connections. Với Claude, mở URL đăng nhập chính thức, cấp quyền rồi gửi mã một lần về Orkestr. Với Codex, mở trang device authorization và nhập mã hiển thị; CLI tự kiểm tra hoàn tất.
Hủy phiên nếu không tiếp tục; phiên hết hạn cần tạo lại. Chỉ người bắt đầu phiên được xem URL/mã hoặc gửi mã.
Admin vào /project-access, chọn project, nhập model ID được tài khoản cho phép và lưu. Tối đa 50 cặp provider/model cho mỗi project; danh sách không tự quét hoặc xác minh inference.
Owner mở Portal → Project Settings → AI Providers & Models, chọn provider/model mặc định từ danh sách được cấp. Thành viên khác chỉ xem.
Thu hồi một grant sẽ xóa lựa chọn tương ứng nếu project đang dùng; hệ thống không tự chọn model thay thế. Khi gặp 409 AI_ACCESS_CHANGED, tải lại cấu hình rồi lưu lại.

Chạy AI thật qua OpenAI-compatible Model Gateway

Đây là cấu hình execution riêng trên backend. Chọn endpoint hỗ trợ Chat Completions và structured outputs response_format: json_schema, strict: true. Điền đủ các key sau:

ENV backend · thay toàn bộ placeholder

MODEL_PROVIDER_DEFAULT=openai-compatible
OPENAI_COMPAT_BASE_URL=<HTTPS_API_BASE_WITH_PREFIX>
OPENAI_COMPAT_API_KEY=<SERVER_SIDE_API_KEY>
OPENAI_COMPAT_MODEL_REQUIREMENT=<MODEL_ID>
OPENAI_COMPAT_MODEL_PLANNING=<MODEL_ID>
OPENAI_COMPAT_MODEL_CODING=<MODEL_ID>
OPENAI_COMPAT_MODEL_REVIEW=<MODEL_ID>

Adapter thêm /chat/completions vào base URL. Thiếu model theo task có thể khiến gateway dùng deterministic cho task đó; kiểm đủ bốn model và kết quả smoke. Kết nối Claude/Codex trong Console không thay thế cấu hình này.

Nguồn vận hành CLI: Claude authentication · Codex authentication. Trạng thái “Đã đăng nhập” không xác nhận model access, quota hoặc inference thành công.

Bằng chứng thay cho giả định

Kiểm tra sau triển khai

Thực hiện trên đúng môi trường vừa triển khai. HTTP 200 ở trang chủ chưa chứng minh đăng nhập, quyền hay queue hoạt động.

DNS & HTTPS: cả ba site và API trỏ đúng target, chứng chỉ đúng hostname, không có mixed content.
Health: /api/v1/health trả trạng thái database up. API không trả HTML của frontend.
Portal: đăng nhập, mở project đúng membership, refresh trực tiếp một route project và đăng xuất.
Console: admin mở tổng quan/AI Connections/Project Access. User không có orkestr-admin bị từ chối cả UI và API quản trị.
Chuyển ứng dụng: liên kết Portal ↔ Console về đúng hostname; mỗi app sử dụng đúng client ID và post-logout origin.
Queue & runner: publish/sync, tạo plan, approve rồi chạy ticket test; kiểm log SSE, report và nhánh/PR/MR đúng target.
Provider: Connect/Check rồi smoke trên resource test; ghi riêng kết quả fixture và live. Kiểm grant/lựa chọn AI không bị mô tả là inference CLI.
Guide: ba đường dẫn /setup, /runbook, /playbook, anchor, tìm kiếm không dấu, sao chép code, menu mobile và in PDF hoạt động; URL không tồn tại trả 404.

PowerShell · kiểm DNS và HTTP, không gửi credential

Resolve-DnsName orkestr-guide.aila.vn
curl.exe -I https://orkestr-guide.aila.vn/
curl.exe -I https://orkestr-guide.aila.vn/khong-ton-tai
curl.exe https://orkestr-api-dev.aila.vn/api/v1/health

Kiểm tra source trước khi publish

Terminal · repo root

node guide/validate.mjs
npm --prefix frontend run build:apps

Validator Guide kiểm cấu trúc và tài nguyên nội bộ, không kiểm DNS, Keycloak hay provider live. Browser E2E dùng database test và có thể reset dữ liệu; không chạy song song các bộ integration/E2E cùng database.