Chuyển đến nội dung chính

title: “Hướng dẫn triển khai Kubernetes” description: “Tài liệu hướng dẫn triển khai AgentEye trên Kubernetes.”

Hướng dẫn này triển khai toàn bộ ngăn xếp AgentEye lên một cụm Kubernetes chuyên dụng:
  • ClickHouse 24.8 — kho lưu trữ phân tích chính cho sự kiện và đánh giá (StatefulSet với khối lưu trữ bền vững 100Gi). Bắt buộc: máy chủ từ chối khởi động mà không có nó.
  • PostgreSQL 16 — kho lưu trữ quan hệ/siêu dữ liệu cho tổ chức, khóa API, người dùng, bảng điều khiển, truy vấn đã lưu và xác thực (StatefulSet với khối lưu trữ bền vững 50Gi)
  • Redis 7.2 — bộ nhớ đệm chia sẻ tùy chọn và phần phụ trợ giới hạn tốc độ; máy chủ và bảng điều khiển sẽ hoạt động bình thường nếu nó không khả dụng
  • AgentEye Server — API Rust để thu nhận sự kiện, phân tích và quản lý khóa (2 bản sao)
  • AgentEye Dashboard — UI web Next.js (2 bản sao)
  • AI assistant (dịch vụ agent) — trợ lý chỉ đọc tùy chọn trong bảng điều khiển trên cổng 9100; vô hoạt cho đến khi điểm cuối LLM được cấu hình
  • Traefik (công khai) — bộ điều khiển ingress cho lưu lượng trạm thu thập, được bảo vệ bằng mTLS
  • Traefik (bảng điều khiển) — bộ điều khiển ingress cho bảng điều khiển, chỉ VPN/danh sách cho phép IP
  • cert-manager — chứng chỉ TLS và CA mTLS
  • Backup CronJob — xả khoá hợp nhất hàng ngày của PostgreSQL + ClickHouse lúc 03:00 UTC
  • Cert Renewal Monitor — cảnh báo khi chứng chỉ khách hàng sắp hết hạn
Thời gian ước tính: 60–90 phút cho lần triển khai đầu tiên. Đối với mô hình triển khai được quản lý mà Exosphere xử lý tất cả các điều này thay bạn, hãy xem enterprise-docs/managed-deployment.md.

Điều kiện tiên quyết

Chạy từng lệnh xác minh trước khi bắt đầu. Mọi kiểm tra phải vượt qua.
Yêu cầuTối thiểuLệnh xác minhKết quả dự kiến
Cụm Kubernetes1.27+kubectl versionServer Version >= v1.27
Kustomize (được đóng gói với kubectl)Kustomize v1.14+ (được đóng gói trong kubectl 1.27+)kubectl kustomize --helpIn ra văn bản sử dụng
Helmv3helm versionVersion:"v3.x.x"
RBAC cluster-adminkubectl auth can-i create namespacesyes
StorageClass mặc địnhkubectl get storageclassÍt nhất một hàng được đánh dấu (default)
Hỗ trợ LoadBalancerPhụ thuộc vào đám mây (EKS, GKE, AKS đều hỗ trợ theo mặc định)
GitHub PATecho $AGENTEYE_TOKENKhông trống (xem enterprise-docs/github-token.md)
opensslopenssl versionOpenSSL 1.x hoặc 3.x
Bộ lưu trữ cloudDành cho sao lưu PostgreSQL + ClickHouse (S3, GCS hoặc Azure Blob)
Kích thước cụm: Tối thiểu 3 nút, mỗi nút 4 vCPU / 8 GB RAM. Xem enterprise-docs/managed-deployment.md để xem yêu cầu đầy đủ.

Chạy tất cả các kiểm tra cùng một lúc

Hình dạng triển khai

Điểm cuối tiêu thụ được phục vụ trên tên máy chủ mà bạn kiểm soát (ví dụ: ingest.your-company.example). cert-manager yêu cầu chứng chỉ TLS được tin cậy công khai từ Let’s Encrypt qua HTTP-01, vì vậy trạm thu thập sẽ xác minh chứng chỉ máy chủ so với kho tin cậy hệ thống, không cần ghim CA theo khách hàng. Điểm cuối bảng điều khiển hoạt động theo cách tương tự: nó được phục vụ trên tên máy chủ thứ hai mà bạn kiểm soát (ví dụ: agenteye.your-company.example) chỉ đến bộ cân bằng tải Traefik bảng điều khiển, và cert-manager phát hành chứng chỉ Let’s Encrypt của nó qua bộ cân bằng tải đó. Các trình duyệt nhận được chứng chỉ được tin cậy mà không có cảnh báo.
Cấp phát và gia hạn chứng chỉ xác thực qua HTTP-01, vì vậy cả hai LoadBalancer phải có thể truy cập được từ Internet công khai trên cổng 80. Nếu bạn cần hạn chế IP cho bộ cân bằng tải bảng điều khiển, hãy phối hợp trình giải quyết DNS-01 với hỗ trợ trước — nếu không, việc gia hạn sẽ thất bại im lặng và chứng chỉ hết hạn.

Lấy các tệp kê khai

Kiểm tra nó:
Kết quả dự kiến: tệp tồn tại. Nếu không, bản sao đã thất bại — kiểm tra AGENTEYE_TOKEN của bạn. Cấu trúc thư mục:
base chứa mọi tài nguyên cần thiết cho triển khai đầy đủ, bao gồm chứng chỉ Let’s Encrypt cho hai tên máy chủ công khai mà bạn cấu hình trong Giai đoạn 3.1. overlay sửa chữa cơ sở cho một môi trường cụ thể (ví dụ: thẻ hình ảnh tùy chỉnh, giới hạn tài nguyên, dây nối env). Thư mục third-party chứa các tệp giá trị Helm cho cơ sở hạ tầng bên ngoài.
Giám sát sức khỏe (tùy chọn): bộ thăm dò sẵn sàng của máy chủ đã phản ánh sức khỏe Postgres + ClickHouse, và third-party/robusta/ thêm cảnh báo lỗi pod gốc Kubernetes tùy chọn cho Slack. Xem enterprise-docs/health-monitoring.md.

Giai đoạn 1 — Cơ sở hạ tầng bên thứ ba (~30 phút)

1.1 Cài đặt cert-manager

cert-manager quản lý chứng chỉ TLS cho HTTPS và CA riêng được sử dụng cho chứng chỉ khách hàng mTLS.
Kiểm tra nó:
Kết quả dự kiến: 3 pod đều Runningcert-manager, cert-manager-cainjector, cert-manager-webhook.
Kết quả dự kiến: ít nhất certificates.cert-manager.io, clusterissuers.cert-manager.io, issuers.cert-manager.io. Nếu nó không thành công: Pod ở CrashLoopBackOff thường có nghĩa là CRD không được cài đặt. Chạy lại với --set crds.install=true. Nếu pod webhook không thành công trong kiểm tra sẵn sàng, chờ 30 giây và kiểm tra lại — chúng có thể mất một chút thời gian để khởi động.

1.2 Cài đặt Traefik — Bộ điều khiển tiêu thụ công khai

Thực thể Traefik này xử lý lưu lượng trạm thu thập trên LoadBalancer bên ngoài. Nó chấm dứt TLS và thực thi mTLS (xác minh chứng chỉ khách hàng) trên điểm cuối tiêu thụ.
Kiểm tra nó:
Kết quả dự kiến: 1 pod Running.
Kết quả dự kiến: IngressClass tồn tại (nó không phải là lớp mặc định). Nếu nó không thành công: Kiểm tra kubectl describe pod -n traefik-public <pod-name> để xem lỗi kéo hình ảnh hoặc ràng buộc tài nguyên.

1.3 Cài đặt Traefik — Bộ điều khiển bảng điều khiển

Thực thể Traefik này phục vụ bảng điều khiển trên LoadBalancer chuyên dụng, bị hạn chế bởi danh sách cho phép IP.
Hai cơ chế danh sách cho phép được cung cấp cho thực thể này. Hướng dẫn này sử dụng values-dashboard.yaml, giới hạn quyền truy cập bằng trường service.loadBalancerSourceRanges di động. Một values-internal.yaml song song cũng được cung cấp cho các môi trường AWS thích chú thích service.beta.kubernetes.io/aws-load-balancer-source-ranges thay thế. Chọn một và sử dụng nó một cách nhất quán; các bước dưới đây giả định values-dashboard.yaml.
Trước khi cài đặt, hãy chỉnh sửa third-party/traefik/values-dashboard.yaml để đặt các IP nguồn được phép. Trường loadBalancerSourceRanges kiểm soát IP nào có thể truy cập bảng điều khiển. Theo mặc định, nó được đặt thành 0.0.0.0/0 (tất cả IP); hạn chế nó thành VPN, văn phòng hoặc IP xuất hiện đã biết của bạn.

Danh sách cho phép một IP duy nhất

Danh sách cho phép nhiều IP

Thêm một mục trên mỗi IP hoặc khối CIDR. Hậu tố /32 khớp với một địa chỉ IPv4 duy nhất; một khối CIDR (ví dụ: /24) khớp với một phạm vi. Bạn có thể trộn các IP riêng lẻ và phạm vi tự do:
Mẹo khi duy trì danh sách:
  • Giữ một mục trên mỗi dòng và thêm một bình luận # ngắn để xác định chủ sở hữu hoặc mục đích của mỗi IP; đây là những gì các nhà khai thác trong tương lai sử dụng để quyết định xem mục nhập còn cần thiết hay không.
  • Luôn sử dụng ký hiệu CIDR. Một IP trần như 203.0.113.10 bị nhà cung cấp đám mây từ chối; hãy sử dụng 203.0.113.10/32.
  • Đối với các phạm vi IPv6, hãy sử dụng CIDR tương đương /128 (địa chỉ duy nhất) hoặc lớn hơn, ví dụ: 2001:db8::1/128. Không phải tất cả các nhà cung cấp đám mây đều hỗ trợ phạm vi nguồn IPv6; kiểm tra tài liệu LoadBalancer của nhà cung cấp của bạn.
  • Danh sách là HOẶC: lưu lượng được phép nếu nguồn khớp với bất kỳ mục nhập nào.
Sau khi chỉnh sửa tệp, tiếp tục với helm install dưới đây. Nếu bộ điều khiển đã được cài đặt, hãy chạy helm upgrade với các cờ tương tự hoặc vá Service lúc chạy (phần tiếp theo).

Cập nhật danh sách cho phép lúc chạy

Bạn có thể thay đổi các IP được phép mà không cần nâng cấp Helm bằng cách vá Service trực tiếp. Bản vá thay thế toàn bộ danh sách; luôn bao gồm mọi IP bạn muốn giữ, không chỉ cái mới. Để thay thế danh sách bằng một bộ IP mới:
Để an toàn thêm một IP mà không mất các mục nhập hiện có, trước tiên hãy đọc danh sách hiện tại, sau đó vá bằng bộ kết hợp:
Các bản vá lúc chạy không được giữ lại trong values-dashboard.yaml. Để giữ thay đổi trong các nâng cấp Helm trong tương lai, cũng cập nhật tệp giá trị và cam kết nó.
Sau đó, cài đặt:
Kiểm tra nó:
Kết quả dự kiến: 1 pod Running.
Kết quả dự kiến: IngressClass tồn tại.

1.4 Chờ LoadBalancer

Cả hai thực thể Traefik đều cần các IP bên ngoài trước khi tiếp tục.
Kiểm tra nó: Cả hai dịch vụ đều hiển thị một EXTERNAL-IP (không phải <pending>). Nếu vẫn chưa giải quyết, hãy theo dõi phân công:
Nhấn Ctrl+C sau khi IP xuất hiện. Phân công IP thường mất 2–5 phút. Nếu nó không thành công: <pending> sau 10 phút thường có nghĩa là nhà cung cấp đám mây không thể cấp phát LoadBalancer. Kiểm tra: thẻ con nít (EKS yêu cầu kubernetes.io/role/elb), cấu hình VPC, hạn ngạch dịch vụ và chú thích LB nội bộ chính xác được đặt cho thực thể nội bộ.

Giai đoạn 2 — Tạo bí mật (~10 phút)

Tất cả các bí mật được tạo thủ công trước khi triển khai ứng dụng. Điều này đảm bảo các giá trị nhạy cảm không bao giờ xuất hiện trong các tệp kê khai.

2.1 Tạo không gian tên

Kiểm tra nó:
Kết quả dự kiến: trạng thái Active.

2.2 Bí mật kéo hình ảnh

Bí mật này xác thực với ghcr.io để kéo các hình ảnh vùng chứa AgentEye. Xem enterprise-docs/github-token.md để biết cách tạo PAT của bạn.
Kiểm tra nó:
Kết quả dự kiến: kubernetes.io/dockerconfigjson. Kiểm tra nó (sâu) — xác minh mã thông báo có thể thực sự kéo hình ảnh không: Sử dụng thẻ hình ảnh server được ghim trong kustomization.yaml của overlay của bạn (hiện đang v0.0.1-beta.48 trong cả lớp phủ acme được đóng gói và triển khai cơ sở). Thay thế thẻ bên dưới bằng thẻ bạn đang triển khai để kiểm tra này không trôi dạt qua các bản phát hành:
Kết quả dự kiến: ok in trong nhật ký. Nếu nó không thành công: ErrImagePull hoặc 401 Unauthorized có nghĩa là PAT không hợp lệ hoặc thiếu phạm vi read:packages. Kiểm tra lại enterprise-docs/github-token.md.

2.3 Thông tin đăng nhập PostgreSQL

Quan trọng: Chúng tôi sử dụng -hex (không phải -base64) để tạo mật khẩu. Đầu ra Base64 có thể chứa +, /= khiến chuỗi kết nối DATABASE_URL bị hỏng. Xem enterprise-docs/troubleshooting.md để biết chi tiết.
Lưu trữ POSTGRES_PASSWORD trong trình quản lý bí mật của bạn ngay lập tức. Bạn sẽ cần nó nếu bạn bao giờ khôi phục từ bản sao lưu hoặc kết nối trực tiếp với cơ sở dữ liệu.
Kiểm tra nó:
Kết quả dự kiến: bí mật tồn tại.
Kết quả dự kiến: 48 (24 byte hex = 48 ký tự).

2.4 Khóa API quản trị

Khóa quản trị là thông tin đăng nhập bootstrap. Máy chủ upserts nó ở mỗi lần khởi động với tất cả các quyền. Sử dụng nó để tạo khóa trạm thu thập được xác định phạm vi trong Giai đoạn 7. Xem enterprise-docs/api-keys.md để xem mô hình quyền đầy đủ.
Lưu trữ ADMIN_KEY trong trình quản lý bí mật của bạn ngay lập tức.
Kiểm tra nó:
Kết quả dự kiến: bí mật tồn tại.

2.5 Cấu hình xác thực (đăng nhập bảng điều khiển)

Bảng điều khiển sử dụng email + OTP cho đăng nhập người dùng. Nếu không có bí mật này, máy chủ vẫn khởi động và đường dẫn API ADMIN_KEY tiếp tục hoạt động, nhưng không có người dùng nào có thể đăng nhập thông qua UI. Tất cả các khóa được tham chiếu là optional: true trong bản kê khai cơ sở, vì vậy các bí mật riêng phần (hoặc không có bí mật nào cả) là được; máy chủ quay lại các giá trị mặc định được ghi chép. Gói mọi thứ vào một bí mật agenteye-auth duy nhất giúp bề mặt xác thực có thể xoay trong một địa điểm.
KhóaMục đích
ADMIN_EMAILNgười dùng quản trị bootstrap. Upserted ở mỗi lần khởi động với tất cả các quyền và được bảo vệ khỏi xóa/chỉnh sửa quyền thông qua bảng điều khiển. Nếu không có nó, không có quản trị viên nào được gieo và đăng nhập đầu tiên là không thể.
ALLOWED_EMAILSDanh sách cho phép được phân tách bằng dấu phẩy. Hỗ trợ địa chỉ chính xác (user@example.com) và ký tự đại diện miền (*@example.com). Nếu không có nó, không có người dùng nào có thể đăng nhập hoặc được tạo.
SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_FROMBộ chuyển tiếp SMTP để gửi mã OTP. Nếu SMTP_HOST không được đặt, các mã OTP sẽ được ghi vào stdout của máy chủ thay vì được gửi qua email (hữu ích cho các bài kiểm tra khởi động). Cung cấp tất cả các khóa SMTP cùng nhau để gửi email thực.
SMTP_TLSMột trong starttls (mặc định), tls hoặc none.
DEFAULT_ORG_NAME, DEFAULT_ORG_SLUGTùy chọn. Đặt cho tổ chức default được xây dựng sẵn tên hiển thị thân thiện và slug URL để nó sống ở ví dụ /acme thay vì /default. Được áp dụng chỉ trên lần khởi động đầu tiên; khi bạn đổi tên tổ chức bằng agenteye-orgctl org rename (xem §7.6) những cái này bị bỏ qua. Slug phải là 1–40 chữ cái thường alphanumerics có gạch ngang nội bộ duy nhất. Để trống cả hai để giữ default chung chung.
Lưu trữ thông tin xác thực SMTP trong trình quản lý bí mật của bạn.
Kiểm tra nó:
Kết quả dự kiến: các khóa bạn điền xuất hiện trong đầu ra.

2.6 Khóa cô lập tổ chức đa người thuê (tùy chọn)

Bỏ qua điều này đối với triển khai một người thuê; máy chủ chạy trên một tổ chức mặc định phát triển được xây dựng sẵn và phục vụ tổ chức default duy nhất một cách tốt. Trước khi bạn tạo tổ chức thứ hai, hãy đặt một ORG_CH_SECRET mạnh, ổn định: mật khẩu ClickHouse của mỗi tổ chức được dẫn xuất dưới dạng HMAC(ORG_CH_SECRET, org_id), vì vậy mặc định phát triển được biết công khai sẽ mang lại thông tin xác thực theo tổ chức được dẫn xuất công khai. Lệnh agenteye-orgctl org create (xem §7.6 Cấp phát các tổ chức) từ chối chạy trong khi máy chủ vẫn ở mặc định phát triển được xây dựng sẵn.
Máy chủ đọc điều này qua một optional secretKeyRef, vì vậy một cụm một người thuê không bao giờ tạo nó vẫn khởi động bình thường. Giữ giá trị ổn định và giống nhau trên tất cả các bản sao; quay nó vô hiệu hóa mật khẩu ClickHouse được dẫn xuất của mỗi tổ chức cho đến khi khởi động lại khỏi mục tiêu cấu hình lại các người dùng (một khởi động động với giá trị nhất quán ở khắp nơi chữa nó). Xem deploy/base/server/secret.example.yaml.
Lưu trữ ORG_CH_SECRET trong trình quản lý bí mật của bạn và đừng quay nó một cách tùy tiện.

2.7 Xác minh tất cả các bí mật

Đầu ra dự kiến (trong số bất kỳ bí mật mặc định nào):
Bốn bí mật cốt lõi (agenteye-admin-key, agenteye-auth, agenteye-image-pull, agenteye-postgres) phải có mặt trước khi tiếp tục. agenteye-org-ch-secret chỉ bắt buộc đối với triển khai đa người thuê (xem §2.6).

Giai đoạn 3 — Triển khai ứng dụng (~5 phút)

3.1 Cấu hình các tên máy chủ công khai

cert-manager cần các tên máy chủ tiêu thụ và bảng điều khiển trước khi nó có thể yêu cầu chứng chỉ Let’s Encrypt của họ. Sao chép mẫu và đặt cả hai:
domain.env được gitignored; nó ở địa phương cho mỗi triển khai. Xây dựng kustomize không thành công ồn ào nếu khóa nào bị thiếu.
DNS phải phân giải trước tiên. Bạn không phải chỉ định DNS tại LB ngay bây giờ (chúng không tồn tại cho đến khi Giai đoạn 1.2 hoàn thành), nhưng cấp phát ACME ở bước 3.2 sẽ thử lại cho đến khi mỗi tên máy chủ phân giải thành LoadBalancer của nó. Bạn có thể đặt DNS ngay bây giờ (sử dụng tên máy chủ LB được nắm bắt trong Giai đoạn 1.4) hoặc tiếp tục và thêm các bản ghi trong Giai đoạn 4.

3.2 Áp dụng bản kê khai

Áp dụng cơ sở trực tiếp để cài đặt mới hoặc lớp phủ nếu bạn đã cắt một cho môi trường này (lớp phủ chỉ ghim các thẻ hình ảnh, biến env và giới hạn tài nguyên; chúng kế thừa chứng chỉ và định tuyến cơ sở):
Lớp phủ bao gồm cơ sở tự động; áp dụng một, không phải cả hai.

3.3 Chờ các pod

Chờ được phạm vi cho các pod mặt phẳng dữ liệu cốt lõi. Pod agent (trợ lý AI) và redis tùy chọn xuất hiện bên cạnh chúng; trợ lý ở vô hoạt cho đến khi bạn cung cấp điểm cuối LLM của nó (xem enterprise-docs/assistant.md), và Redis là bộ nhớ đệm tốt nhất, vì vậy không ai cần ở Sẵn sàng để nền tảng phục vụ lưu lượng truy cập. Kiểm tra nó:
Kết quả dự kiến (pod agentredis tùy chọn cũng xuất hiện và đạt Running):
Nếu nó không thành công:
Trạng thái PodNguyên nhân có thểLệnh gỡ lỗi
ImagePullBackOffBí mật kéo hình ảnh xấu hoặc PATkubectl describe pod <name> -n agenteye
CrashLoopBackOffBiến env xấu (ví dụ: DATABASE_URL)kubectl logs <name> -n agenteye
PendingCPU/bộ nhớ không đủ hoặc không có nútkubectl describe pod <name> -n agenteye (kiểm tra Sự kiện)

3.4 Xác minh bộ lưu trữ

Kết quả dự kiến, cả hai có trạng thái Bound:
PVCDung lượngLưng
postgres-data-postgres-050GiKho lưu trữ quan hệ/siêu dữ liệu PostgreSQL
clickhouse-data-clickhouse-0100GiKho lưu trữ phân tích sự kiện + đánh giá ClickHouse
Một PVC redis-data-redis-0 (1Gi) cũng xuất hiện cho bộ nhớ đệm tùy chọn. Nếu nó không thành công: Pending có nghĩa là không có StorageClass nào có thể cấp phát khối lượng. Kiểm tra kubectl get storageclass và đảm bảo tồn tại một mặc định. Để sản xuất, lớp phủ khối lượng ClickHouse lên StorageClass SSD nhanh (ví dụ: gp3 trên AWS, pd-ssd trên GCP); thông lượng nén bị ảnh hưởng trên đĩa chậm.

3.5 Xác minh chứng chỉ

Kết quả dự kiến: 3 chứng chỉ, tất cả Ready: True:
TênCông cộngMục đích
mtls-caselfsignedCA riêng để phát hành chứng chỉ máy khách mTLS (hiệu lực 10 năm)
ingest-tlsletsencrypt-prodChứng chỉ TLS công khai cho điểm cuối tiêu thụ (90 ngày, tự động gia hạn)
dashboard-tlsletsencrypt-prodChứng chỉ TLS công khai cho bảng điều khiển (90 ngày, tự động gia hạn)
Nếu ingest-tls hoặc dashboard-tls không sẵn sàng: kubectl describe certificate <name> -n agenteye và đọc Sự kiện. Các nguyên nhân phổ biến:
  • DNS chưa chỉ đến LB. Let’s Encrypt phân giải tên máy chủ và nhấn cổng 80 để xác thực — INGEST_DOMAIN phải phân giải thành LB công khai, DASHBOARD_DOMAIN thành LB bảng điều khiển. Cho đến khi CNAME/Alias lan rộng, đơn đặt hàng vẫn pending. Khi DNS đúng, cert-manager thử lại tự động (không cần xóa Chứng chỉ).
  • Tên máy chủ không được thay thế. Nếu dnsNames vẫn đọc INGEST_DOMAIN_PLACEHOLDER / DASHBOARD_DOMAIN_PLACEHOLDER, bạn đã bỏ qua bước 3.1 — tạo base/certificates/domain.env và áp dụng lại.
  • Traefik bảng điều khiển không thể phục vụ thử thách (dashboard-tls chỉ). Thực thể Traefik bảng điều khiển phải được cài đặt với tệp giá trị được đóng gói (Giai đoạn 1.2), điều này cho phép nhà cung cấp Ingress được xác định phạm vi phục vụ bộ giải quyết HTTP-01 của cert-manager. Một thực thể được cài đặt mà không có nó để thử thách không có tuyến đường và thứ tự pending mãi mãi.
Nếu mtls-ca không sẵn sàng: cert-manager chính nó không khỏe. Kiểm tra lại các pod cert-manager từ bước 1.1.

3.6 Xác minh CronJob

Kết quả dự kiến:
TênLịchMục đích
agenteye-backup0 3 * * *Sao lưu Postgres + ClickHouse hàng ngày lúc 03:00 UTC
cert-renewal-check0 3,15 * * *Cảnh báo hết hạn chứng chỉ lúc 03:00 và 15:00 UTC

3.7 Xác minh máy chủ khởi động chính xác

Kiểm tra nó: Tìm dòng khởi động cho biết máy chủ đang nghe trên cổng 8080. Không nên có lỗi kết nối cơ sở dữ liệu (máy chủ yêu cầu cả PostgreSQL và ClickHouse có thể truy cập được trước khi nó báo cáo Sẵn sàng). Nếu nó không thành công: Nguyên nhân phổ biến nhất là POSTGRES_PASSWORD chứa các ký tự không an toàn URL mà bảng DATABASE_URL. Xem enterprise-docs/troubleshooting.md.

3.8 Xác minh bảng điều khiển được kết nối với máy chủ

Kiểm tra nó: Tìm Ready trong đầu ra mà không có ECONNREFUSED hoặc các lỗi tương tự. Nếu nó không thành công: Kiểm tra rằng Dịch vụ server tồn tại (kubectl get svc server -n agenteye) và AGENTEYE_SERVER_URL được đặt thành http://server:8080 trong triển khai bảng điều khiển.

Giai đoạn 4 — Quyền truy cập mạng (~5 phút)

4.1 Truy xuất địa chỉ LoadBalancer

Trên AWS EKS, LoadBalancer trả về tên máy chủ thay vì IP. Thay thế .ip bằng .hostname trong các lệnh trên.
Kiểm tra nó:
Cả hai phải không trống.

4.2 Trỏ DNS tại LoadBalancer

Tạo bản ghi DNS để các tên máy chủ từ base/certificates/domain.env phân giải thành LoadBalancer của họ — INGEST_DOMAIN thành LB Traefik công khai, DASHBOARD_DOMAIN thành LB Traefik bảng điều khiển:
  • AWS Route 53: Bản ghi AAlias = Yes, mục tiêu = tên máy chủ LB. Đừng sử dụng A bình thường → IP; IP ELB xoay.
  • Bất kỳ nhà cung cấp nào khác: CNAME từ tên máy chủ đến tên máy chủ LB.
Xác minh:
Nên trả về cùng địa chỉ như $PUBLIC_IP$INTERNAL_IP tương ứng (hoặc, trên EKS, phân giải thành cùng tên máy chủ *.elb.amazonaws.com). Khi DNS phân giải, cert-manager hoàn thành các đơn đặt hàng ACME chưa hoàn thành từ Giai đoạn 3.5 trong vòng một phút. Chạy lại kubectl get certificates -n agenteye cho đến khi cả ingest-tlsdashboard-tls hiển thị Ready: True.

4.3 Tiếp cận điểm cuối tiêu thụ

Điểm cuối tiêu thụ công khai thực thi TLS lẫn nhau, vì vậy mỗi yêu cầu (bao gồm /health) phải trình bày chứng chỉ khách hàng. Bạn phát hành chứng chỉ khách hàng đầu tiên của bạn trong Giai đoạn 5; nếu bạn đã có cái, hãy xác minh khả năng truy cập ngay bây giờ:
Kết quả dự kiến: {"status":"ok"}. Không cần -k — chứng chỉ máy chủ chuỗi đến CA công khai cho INGEST_DOMAIN, vì vậy nó xác thực so với kho tin cậy hệ thống. Tiếp cận điểm cuối tiêu thụ bằng tên máy chủ INGEST_DOMAIN của nó (khớp với chứng chỉ phát hành), không phải bởi IP/tên máy chủ LB thô. Điểm cuối bảng điều khiển được phục vụ trên DASHBOARD_DOMAIN có chứng chỉ được tin cậy công khai và không phải mTLS, vì vậy không cần -k và không cần chứng chỉ khách hàng:
Tiếp cận bảng điều khiển bằng tên máy chủ của nó, không phải địa chỉ LB thô — chứng chỉ bị ràng buộc với DASHBOARD_DOMAIN, vì vậy địa chỉ thô hiển thị sự không khớp về tên chứng chỉ. Nếu nó không thành công: Nếu curl treo, kiểm tra rằng LB có thể truy cập được từ máy của bạn (VPN, nhóm bảo mật, quy tắc tường lửa). Lỗi bắt tay certificate required trên tên máy chủ tiêu thụ có nghĩa là không có chứng chỉ khách hàng được trình bày; hãy hoàn thành Giai đoạn 5 trước. Lỗi xác thực TLS trên tên máy chủ tiêu thụ có nghĩa là chứng chỉ máy chủ chưa hoàn thành phát hành; quay lại Giai đoạn 3.5 và giải quyết vấn đề ở đó.

Giai đoạn 5 — Phát hành chứng chỉ khách hàng mTLS (~10 phút trên cụm)

Trạm thu thập xác thực bằng hai yếu tố: chứng chỉ khách hàng (lớp vận tải, chứng minh yêu cầu đến từ một cụm được ủy quyền) và khóa API (lớp ứng dụng, chứng minh yêu cầu từ trạm thu thập có quyền events:add). Khóa rò rỉ vô dụng mà không có cert; cert bị đánh cắp vô dụng mà không có khóa hợp lệ.

5.1 Phát hành chứng chỉ

Mỗi cụm chạy trạm thu thập cần chứng chỉ khách hàng riêng của nó. Từ thư mục bản kê khai:
Thay thế <cluster-name> bằng một định danh có ý nghĩa (ví dụ: us-east-1-prod, staging). Kiểm tra nó: Tập lệnh in ==> Done! và liệt kê các tệp đầu ra.
Kết quả dự kiến: Ready: True. Tệp đầu ra trong issued/<cluster-name>/:
TệpMục đích
client.crtChứng chỉ khách hàng (hiệu lực 90 ngày)
client.keyKhóa riêng máy khách
ca.crtChứng chỉ CA để xác minh máy chủ
collector-mtls-secret.yamlBí mật Kubernetes sẵn sàng áp dụng cho cụm trạm thu thập

5.1b Phương tiện thay thế: AWS Secrets Manager

Nếu người tiêu dùng cert là một Pod Kubernetes cần client.crtclient.key trên đĩa — trường hợp điển hình khi bạn chạy trạm thu thập agenteye-collector dưới dạng sidecar trong pod ứng dụng của bạn — đẩy bó cert vào AWS Secrets Manager. Pod ứng dụng sau đó gắn nó qua Secrets Store CSI Driver với IRSA, và quay một vòng chứng chỉ hoàn toàn tự động.
Khi chạy lại (gia hạn), tập lệnh gọi PutSecretValue trên cùng một bí mật, vì vậy ARN và tên giữ ổn định. CSI Driver chọn phiên bản mới trên bộ xoay tiếp theo của nó và viết lại các tệp bên trong pod. Điều kiện tiên quyết:
  • aws CLI v2 được xác thực cho tài khoản AWS của bạn.
  • jq cài đặt.
  • Biến môi trường AWS_REGION được đặt.
  • Quyền IAM trên danh tính người gọi của bạn (phạm vi Resource thành arn:aws:secretsmanager:<region>:<account>:secret:agenteye/mtls-client/*):
    • secretsmanager:CreateSecret
    • secretsmanager:DescribeSecret
    • secretsmanager:PutSecretValue
    • secretsmanager:TagResource
Tập lệnh làm gì ở chế độ này:
BướcHành động
1Phát hành / tái trích xuất cert qua cert-manager (giống như chế độ mặc định).
2Gọi DescribeSecret trên agenteye/mtls-client/<cluster-name> để quyết định tạo vs cập nhật.
3Trên lần chạy đầu tiên: CreateSecret với tải trọng JSON ba khóa (client.crt, client.key, ca.crt), được gắn thẻ AgentEyeCluster=<cluster-name>. Trên các lần chạy tiếp theo: PutSecretValue để xuất bản phiên bản mới; thẻ làm mới qua TagResource.
4Xóa issued/<cluster-name>/ chỉ sau khi tải lên thành công. Khi có lỗi, thư mục được bảo tồn để bạn thử lại.
Nếu bí mật được lên lịch xóa, tập lệnh không thành công với lỗi rõ ràng yêu cầu bạn chạy aws secretsmanager restore-secret --secret-id agenteye/mtls-client/<cluster-name> trước khi thử lại. Để dây toàn bộ pod (SecretProviderClass, thiết lập IRSA, hành vi quay một vòng, gỡ lỗi) xem enterprise-docs/single-pod-deployment.md.

5.2 Xác minh chứng chỉ hoạt động

Kiểm tra chứng chỉ phát hành so với mTLS ingress:
Kết quả dự kiến: {"status":"ok"} Nếu nó không thành công:
LỗiNguyên nhânKhắc phục
certificate requiredCert không được trình bàyKiểm tra đường dẫn tệp trong lệnh curl
bad certificateKhông khớp CAXác minh mtls-ca-issuer phát hành cert: kubectl describe certificate mtls-client-<name> -n agenteye
connection refusedTên máy chủ hoặc LB sai không có thể truy cậpKiểm tra /etc/hosts hoặc DNS

5.3 Gửi tới cụm trạm thu thập

Gửi collector-mtls-secret.yaml cho đội vận hành cụm trạm thu thập. Họ áp dụng nó: