Tự host (Doanh nghiệp)

Cài bằng Helm

Cài DataxLand lên Kubernetes bằng Helm chart, gồm Secret bí mật, Secret giấy phép, values tối thiểu cho production, kiểm tra sau khi cài, bản dùng thử với Postgres và MinIO trong cụm, External Secrets, NetworkPolicy và ServiceMonitor.

Trang này dùng tên bản cài dataxland, namespace dataxland và tên miền dataxland.corp.example. Thay bằng giá trị của bạn.

Trước khi bắt đầu, cần có: hạ tầng theo Yêu cầu và cỡ máy, Helm 3, kubectl trỏ vào cụm, và từ DataxLand: chart, tên kho ảnh, quyền kéo ảnh (hoặc gói ảnh offline) và tệp giấy phép license.json.

1. Namespace

kubectl create namespace dataxland

Mỗi namespace chỉ chứa một bản cài: Service của api luôn tên là api (ảnh web gọi sẵn địa chỉ http://api:8000).

Nếu kho ảnh cần đăng nhập, tạo Secret kéo ảnh rồi khai báo ở imagePullSecrets:

kubectl -n dataxland create secret docker-registry dataxland-pull \
  --docker-server=ghcr.io --docker-username=<tên> --docker-password=<token>

2. Secret bí mật

Chart không chứa giá trị bí mật nào. Tạo một Secret, mỗi khóa trùng tên một biến môi trường:

KhóaBắt buộcNội dung
DX_POSTGRES_URLcóChuỗi kết nối database dx, ví dụ postgresql://dx:<mật khẩu>@pg.corp.example:5432/dx?sslmode=require
DX_DUCKLAKE_CATALOG_PASSWORDcóMật khẩu của user Postgres (dùng cho database dx_lake)
DX_SESSION_SECRETcóChuỗi ngẫu nhiên, ký phiên đăng nhập
DX_SECRET_KEYcóChuỗi ngẫu nhiên, mã hóa bí mật đã lưu (mật khẩu nguồn, token)
DX_DELEGATION_SIGNING_KEYcóChuỗi ngẫu nhiên, ký token ủy quyền ngắn hạn giữa các dịch vụ
DX_BACKUP_ENCRYPTION_KEYcó32 byte, base64 url-safe, mã hóa bản sao lưu
DX_DUCKLAKE_S3_KEY_ID, DX_DUCKLAKE_S3_SECRETcóKhóa object storage
DX_SMTP_PASSWORDkhôngMật khẩu SMTP
DX_BACKUP_S3_KEY_ID, DX_BACKUP_S3_SECRETkhôngKhóa riêng cho bucket sao lưu, nếu khác khóa kho
DX_METRICS_TOKENkhôngBắt buộc token khi đọc /metrics
Khóa API modeltùy modelTên biến theo api_key_env của model. Danh mục mặc định hiện dùng DEEPSEEK_API_KEY
kubectl -n dataxland create secret generic dataxland-env \
  --from-literal=DX_POSTGRES_URL='postgresql://dx:<mật khẩu>@pg.corp.example:5432/dx?sslmode=require' \
  --from-literal=DX_DUCKLAKE_CATALOG_PASSWORD='<mật khẩu>' \
  --from-literal=DX_SESSION_SECRET="$(openssl rand -hex 32)" \
  --from-literal=DX_SECRET_KEY="$(openssl rand -hex 32)" \
  --from-literal=DX_DELEGATION_SIGNING_KEY="$(openssl rand -hex 32)" \
  --from-literal=DX_BACKUP_ENCRYPTION_KEY="$(openssl rand -base64 32 | tr '+/' '-_')" \
  --from-literal=DX_DUCKLAKE_S3_KEY_ID='<key id>' \
  --from-literal=DX_DUCKLAKE_S3_SECRET='<secret>'

Mật khẩu Postgres có ký tự đặc biệt thì phải mã hóa URL trong DX_POSTGRES_URL.

Lưu ngay DX_SECRET_KEY và DX_BACKUP_ENCRYPTION_KEY ra hai nơi (kho bí mật của công ty và một bản ngoại tuyến). Mất DX_SECRET_KEY thì phải nối lại mọi nguồn dữ liệu; mất DX_BACKUP_ENCRYPTION_KEY thì mọi bản sao lưu không giải mã được.

3. Secret giấy phép

kubectl -n dataxland create secret generic dataxland-license --from-file=license.json=./license.json

Chưa có giấy phép thì bản cài vẫn chạy nhưng ở chế độ chỉ đọc. Xem Giấy phép.

4. Values cho production

Tệp values-prod.yaml tối thiểu (ví dụ trên AWS):

image:
  repositoryPrefix: <tên do DataxLand cung cấp>
imagePullSecrets:
  - name: dataxland-pull

deployment:
  publicUrl: https://dataxland.corp.example
  superAdmins: [admin@corp.example]
  extraEnv:
    DX_SMTP_HOST: smtp.corp.example
    DX_SMTP_PORT: "587"
    DX_SMTP_USER: dataxland
    DX_SMTP_FROM: dataxland@corp.example

license:
  existingSecret: dataxland-license

secrets:
  existingSecret: dataxland-env

postgres:
  external:
    host: pg.corp.example
    database: dx
    catalogDatabase: dx_lake
    user: dx

objectStorage:
  endpoint: s3.ap-southeast-1.amazonaws.com
  region: ap-southeast-1
  urlStyle: vhost
  lakeBucket: dx-lake
  tenantKeys: "off"
  backup:
    bucket: dx-backups

persistence:
  storageClass: efs-rwx
  size: 100Gi

ingress:
  className: nginx
  host: dataxland.corp.example
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt

Những khóa hay cần đổi:

KhóaÝ nghĩa
deployment.publicUrlĐịa chỉ người dùng mở, bắt buộc
deployment.superAdminsEmail quản trị toàn bản cài
deployment.signupModeinvite (mặc định), approval hoặc open
deployment.timezoneMúi giờ cho ngày nghiệp vụ và giờ sao lưu, mặc định Asia/Ho_Chi_Minh
deployment.extraEnvBiến môi trường thêm cho api, worker, mcp (SMTP, kênh thông báo)
image.registry, image.repositoryPrefix, image.tagKho ảnh; image.tag trống thì dùng phiên bản của chart
image.digestsGhim ảnh theo digest, ví dụ {api: sha256:..., web: sha256:...}
objectStorage.lakePrefixTiền tố trong bucket kho, khi dùng chung bucket
ingress.tls.secretNameSecret chứa chứng chỉ; trống thì dùng dataxland-tls (cert-manager tạo)
ingress.mcp.enabled, ingress.mcp.hostMở máy chủ MCP ra ngoài, ví dụ mcp.dataxland.corp.example
ingress.api.enabled, ingress.api.hostMở thẳng /v1 của api, chỉ khi cần callback OAuth hoặc webhook
api.autoscaling.enabled, web.autoscaling.enabledBật HPA
mcp.enabledTắt máy chủ MCP nếu không dùng

Object storage trên GCP, Azure hay on-prem: xem bảng ở Yêu cầu và cỡ máy.

5. Cài

helm install dataxland <đường dẫn chart> -n dataxland -f values-prod.yaml
kubectl -n dataxland get pods -w

<đường dẫn chart> là thư mục hoặc tệp .tgz của chart DataxLand cung cấp cùng bản phát hành. Lần cài đầu, các thành phần tự tạo schema Postgres; từ lần nâng cấp sau, Job migrate làm việc này trước khi cuộn bản mới.

Helm in ghi chú sau khi cài, kèm cảnh báo nếu thiếu giấy phép, đang dùng Postgres hoặc MinIO trong cụm, hoặc Secret do chart tự tạo.

6. Kiểm tra và đăng nhập

kubectl -n dataxland port-forward svc/api 8000:8000
curl -s http://localhost:8000/readyz

/readyz kiểm Postgres, catalog và object storage. Khi trả thành công:

  1. Mở https://dataxland.corp.example.
  2. Đăng ký bằng email trong deployment.superAdmins. Email này không cần mã mời và bắt buộc bật xác thực hai lớp.
  3. Vào Quản trị → Vận hành, mục Triển khai và giấy phép: xem trạng thái giấy phép, mức dùng và chế độ cách ly.
  4. Tạo workspace đầu tiên rồi mời người dùng.

Xem trạng thái giấy phép từ dòng lệnh:

kubectl -n dataxland exec deploy/dataxland-worker -- python -m pipelines.cli license-status

Dùng thử với Postgres và MinIO trong cụm

Để thử trên một cụm nhỏ, chart có thể chạy Postgres và MinIO ngay trong cụm. Hai thành phần này chỉ để dùng thử: một bản, không sao lưu, không HA.

# values-trial.yaml
deployment:
  publicUrl: http://localhost:3000
  superAdmins: [admin@corp.example]
license:
  existingSecret: dataxland-license
postgres:
  bundled:
    enabled: true
minio:
  bundled: true
objectStorage:
  tenantKeys: minio
persistence:
  accessMode: ReadWriteOnce
  size: 10Gi
api:
  replicas: 1
web:
  replicas: 1
ingress:
  enabled: false
helm install dataxland <đường dẫn chart> -n dataxland -f values-trial.yaml
kubectl -n dataxland port-forward svc/dataxland-web 3000:3000

Không đặt secrets.existingSecret thì chart tự tạo Secret dataxland-env với khóa ngẫu nhiên, giữ qua các lần nâng cấp. Bản dùng thử vẫn cần tệp giấy phép; không có thì bản cài chỉ đọc.

Bí mật từ External Secrets Operator

Nếu bí mật nằm trong kho bí mật (AWS Secrets Manager, Google Secret Manager, Azure Key Vault, Vault) và cụm đã có External Secrets Operator, chart tạo ExternalSecret thay cho Secret tạo tay. Đích vẫn là Secret dataxland-env.

secrets:
  existingSecret: ""
  externalSecret:
    enabled: true
    secretStoreRef: {name: cloud-secrets, kind: ClusterSecretStore}
    refreshInterval: 1h
    data:
      DX_SECRET_KEY: dataxland/prod/secret-key
      DX_POSTGRES_URL: {key: dataxland-app, property: DX_POSTGRES_URL}

Mỗi khóa trong data là tên biến; giá trị là remoteKey trong kho, hoặc một remoteRef đầy đủ (key, property) khi nhiều biến nằm trong một bí mật JSON. Liệt kê đủ các khóa bắt buộc ở mục 2.

NetworkPolicy

Cần CNI hỗ trợ NetworkPolicy. Bật:

networkPolicy:
  enabled: true
  ingressControllerNamespace: ingress-nginx
  ingressControllerLabels: {app.kubernetes.io/name: ingress-nginx}
  monitoringNamespace: monitoring

Chart chặn mọi kết nối vào, rồi chỉ cho: ingress controller vào web và mcp (và api nếu bật ingress.api), các pod của bản cài gọi nhau, Prometheus trong monitoringNamespace đọc cổng chỉ số 9464 đến 9466.

Giới hạn kết nối ra (bắt buộc khi cách ly mạng):

networkPolicy:
  enabled: true
  egress:
    restrict: true
    dnsNamespace: kube-system
    allowCIDRs: [10.0.0.0/16]
    allowPorts: [5432, 443, 587]

Khi restrict: true, pod chỉ được gọi DNS, các pod cùng bản cài và các dải trong allowCIDRs (Postgres, object storage, model AI, SMTP, database nguồn). allowPorts trống nghĩa là mọi cổng tới các dải đó.

ServiceMonitor

Với Prometheus Operator:

serviceMonitor:
  enabled: true
  interval: 30s
  labels: {release: prometheus}

Chart thu /metrics của api (cổng 9464), worker (9465), mcp (9466). Nếu đặt DX_METRICS_TOKEN, ServiceMonitor của chart không tự gửi token; thêm cấu hình xác thực cho Prometheus của bạn. Bộ luật cảnh báo Prometheus đi kèm bản phát hành; hãy nạp thêm cảnh báo giấy phép sắp hết hạn (xem Giấy phép).

Liên quan

Markdown