Chuyển tới nội dung chính

Vận hành hằng ngày

Trang này hướng dẫn giữ sống 11 container production, cấu hình biến môi trường bắt buộc và thứ tự bật cờ an toàn. Đọc khi bạn trực vận hành và cần checklist hằng ngày sau mọi lần deploy.

Đối tượng: SRE / deployer / Arkon admin — người dựng và giữ sống 11 containers production. Phạm vi: hạ tầng + Employee.role=admin (ALL_PERMISSIONS), org:settings:manage, org:employees:manage, org:audit:read. Nguồn chi tiết: Cài đặt · Vận hành & backup.

Trách nhiệm của bạn​

  • Giữ sống: agentjira_server (127.0.0.1:8080, loopback only) + agentjira_client nginx (:8081, mặt tiền duy nhất) + agentjira_db + arkon_api (:5055) + arkon_frontend (:3119) + arkon_postgres (pgvector) + arkon_redis + arkon_minio (:9002/:9003) + workers.
  • Giữ 3 chốt an toàn: Cloudflare Access JWT (server verify RS256, bỏ qua x-forwarded-role) · nginx strip X-Forwarded-* ở client · server bind loopback.
  • Quản trị Arkon hệ thống: Employees + MCP token, Model Catalog, audit log, backup 3 stores.
Không bao giờ republish 8080 ra 0.0.0.0

Từng là lỗ hổng approve giả mạo (P0-A/B): ai chạm được port đó kèm header giả là approve được. Chi tiết: Kiến trúc tổng thể.

Đọc log [preflight] WARN sau MỌI deploy

Các lỗi cấu hình ở đây đều chết âm thầm: Wiki tắt lặng, Planner lỗi, provisioning 500.

Ba biến bắt buộc ở MỌI môi trường có Arkon trong container​

BiếnVì sao
ARKON_SSO_SHARED_SECRET (AgentJira) = SSO_SHARED_SECRET (Arkon)POST /api/auth/sso chỉ tin loopback hoặc secret này; ngay cả npm run dev trên host qua cổng published cũng thành IP gateway bridge — thiếu → provisioning 403 → tạo Space 500
ARKON_ENCRYPTION_KEYMã hoá MCP token persona at-rest; production thiếu thì từ chối boot
MINIO_ENDPOINT không dấu _Dấu _ vào Host header → MinIO InvalidRequest, mọi upload/ảnh wiki chết; dùng alias minio:9000

./scripts/dev.sh init sinh + đồng bộ 2 giá trị đầu; deps up/up tự kiểm tra mỗi lần chạy.

Cấu hình bắt buộc production​

Server từ chối boot nếu thiếu:

  • ARKON_ENCRYPTION_KEY;
  • ARKON_SSO_SHARED_SECRET (+ SSO_SHARED_SECRET bên Arkon);
  • CF_ACCESS_AUD + CF_ACCESS_TEAM_DOMAIN hoặc TRUST_PROXY_IDENTITY=1 + TRUSTED_PROXY_IPS.

Nên đặt thêm:

BiếnThiếu thì sao
ALLOWED_HOSTSWS 403 → Board mất realtime
ARKON_API_URLMặc định về loopback = chính server → Wiki chết lặng
AGENTBOARD_LLM_MODE=live + key + modelPlanner lỗi mọi ý tưởng
AGENTBOARD_BOOTSTRAP_OWNERSKhông ai quản trị được Space nào (fail-closed)
ALLOWED_REPO_ROOTSAgent chạm được $HOME, /tmp

Thứ tự bật cờ 0B/0C trên production​

Bật từng cái một và xác minh, đừng bật cả loạt ở lần deploy đầu:

  1. Trước: AGENTBOARD_COMMAND_PALETTE + AGENTBOARD_MENTION_SUBTASK (chỉ client/sinh task, rủi ro thấp nhất).
  2. Sau khi quan sát ổn: AGENTBOARD_WS_TOPICS (đòi thêm AGENT_BOARD_PUBLIC_URL + host trong ALLOWED_HOSTS, sai là server từ chối boot) và AGENTBOARD_AUTO_RETRO (mỗi Epic là một lần gọi LLM).
  3. Sau mọi sửa env, verify từ trong container — không tin file .env:
docker exec agentjira_server printenv | grep AGENTBOARD_
curl -s localhost:8081/api/features   # phải phản ánh đúng ý định
  1. Sau đổi role Space (khi AGENTBOARD_ARKON_RBAC_SYNC=1), đợi 1 nhịp reconciler (AGENTBOARD_ARKON_RBAC_RECONCILE_MS, mặc định 15 phút) trước khi kết luận đồng bộ hỏng.

Mã preflight bạn sẽ gặp (chỉ in khi NODE_ENV=production):

  • LLM_REPLAY_IN_PRODUCTION — Planner đang replay, mọi ý tưởng thật đều lỗi cache miss.
  • LLM_LIVE_WITHOUT_KEY / LLM_LIVE_WITHOUT_MODEL — bật live nhưng thiếu key hoặc model.
  • LLM_OPENROUTER_MODEL_UNVERIFIED — model OpenRouter chưa nằm trong allowlist structured outputs.
  • ARKON_URL_UNSET / ARKON_URL_LOOPBACK — Wiki chết lặng, xem Sự cố & checklist go-live.
  • ALLOWED_HOSTS_LOCALHOST_ONLY — WS 403, Board mất realtime.
  • WS_TOPICS_WITHOUT_PUBLIC_URL / PUBLIC_URL_NOT_IN_ALLOWED_HOSTS — fatal khi AGENTBOARD_WS_TOPICS=1, server từ chối boot.
  • ARKON_ENCRYPTION_KEY_UNSET — vault token coi như không mã hoá.

Gặp lỗi? Xem Sự cố & checklist go-live và Xử lý sự cố.

Deploy / rollback / backup (tóm tắt)​

  • Deploy app: CI (cd.yml, push main) hoặc tay (ssh, docker compose.prod.yml up -d). Rollback theo runbook.
  • Deploy docs độc lập: site :8082 chạy docker-compose.docs.yml riêng — sửa docs → merge main → CD tự build-push + pull/up chỉ file docs, không restart stack app. Tay: docker compose -f docker-compose.docs.yml pull && up -d + curl -fsS :8082. Chi tiết: Cài đặt.
  • Sau deploy: đọc [preflight] → kiểm health 4 mặt (:8081, :8080 loopback, :3119, :5055) → thử approve 1 task mẫu.
  • Backup 3 stores độc lập: agentjira_db + arkon_postgres + arkon_minio. Lệnh đầy đủ ở runbook §5. Nhớ luân chuyển secret và git locking theo runbook.

Quản trị người dùng, token, audit​

  • Board: bootstrap owner qua AGENTBOARD_BOOTSTRAP_OWNERS (idempotent — vừa init vừa break-glass). Space không member → inaccessible + warn (chủ ý).
  • Arkon: POST /api/employees {name,email,password,role,global_role,department_ids[]} (cần org:employees:manage); reconcile dept qua PUT /api/employees/{id}, POST/DELETE /{id}/departments; cấp token POST/DELETE /api/employees/{id}/token; user tự phục vụ ở /profile. Token HMAC-SHA256, MCP_TOKEN_PEPPER bắt buộc.
  • Audit: GET /api/audit/log (filter principal/action/decision/resource) + riêng mcp_query_log. Theo dõi audit.denied tăng đột biến trên Dashboard.

Đọc tiếp: Model Catalog & OpenRouter · Sự cố & checklist go-live.

Gặp lỗi? Xem Xử lý sự cố.

Đi tiếp: Model Catalog & OpenRouter · Sự cố & checklist go-live · Vận hành & backup

Cập nhật lần cuối vào