Chuyển tới nội dung chính
Phiên bản: 1.1

Vận hành hằng ngày — dành cho SysAdmin

Đố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.

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.