# Chế độ cách ly mạng

> Chạy DataxLand trong mạng không ra Internet - danh sách máy chủ được gọi, NetworkPolicy bắt buộc, model AI nội bộ, SMTP nội bộ, tính năng bị tắt, nguồn dữ liệu còn dùng được và cách chép ảnh vào registry nội bộ.

Chế độ cách ly mạng dành cho bản cài không được gọi ra Internet. Khi bật, DataxLand chỉ gọi tới các máy chủ bạn liệt kê, tự
tắt những tính năng cần máy chủ bên ngoài và cho biết lý do.

DataxLand không có telemetry gửi về DataxLand, kể cả khi không cách ly. Giấy phép được kiểm offline.

## 1. Bật chế độ và khai báo máy chủ được gọi

```yaml
airgapped:
  enabled: true
  egressAllow:
    - llm.corp.example        # tên chính xác
    - smtp.corp.example
    - "*.db.corp.example"     # mọi máy chủ con của db.corp.example
    - 10.20.0.0/16            # dải địa chỉ (CIDR)
```

Mỗi mục là một trong ba dạng:

| Dạng | Ví dụ | Khớp |
| --- | --- | --- |
| Tên chính xác | `llm.corp.example` | Đúng tên đó |
| `*.hậu-tố` | `*.db.corp.example` | `pg.db.corp.example`, `a.b.db.corp.example`; không khớp chính `db.corp.example` |
| CIDR hoặc IP | `10.20.0.0/16`, `10.20.1.5` | Máy chủ phân giải ra địa chỉ trong dải |

- Địa chỉ metadata của đám mây và link-local (`169.254.0.0/16`) **luôn bị chặn**, kể cả khi nằm trong danh sách.
- Model AI và SMTP được kiểm theo **tên** trong cấu hình lúc khởi động. Ghi tên máy chủ của chúng (hoặc IP nếu cấu hình bằng IP),
  không chỉ dải CIDR.
- Không cách ly, danh sách này vẫn có ích: theo mặc định DataxLand không cho kết nối tới địa chỉ nội bộ (chống SSRF), nên
  database nguồn trong mạng của bạn phải có trong `egressAllow` thì mới kết nối được.

## 2. Chặn ở mức mạng (bắt buộc)

Kiểm tra trong ứng dụng là lớp thứ hai. Tiến trình con của connector không mang chính sách của ứng dụng, nên lớp chính phải là
NetworkPolicy của chart và tường lửa của bạn:

```yaml
networkPolicy:
  enabled: true
  egress:
    restrict: true
    dnsNamespace: kube-system
    allowCIDRs: [10.0.0.0/16, 10.20.0.0/16]   # Postgres, object storage, model AI, SMTP, database nguồn
    allowPorts: [5432, 443, 587, 1433, 3306, 8000]
```

Helm cảnh báo khi `airgapped.enabled` bật mà `networkPolicy.egress.restrict` tắt. Cần CNI hỗ trợ NetworkPolicy.

## 3. Model AI nội bộ

Danh mục model mặc định trong ảnh gọi API của nhà cung cấp bên ngoài. Khi cách ly, mỗi route phải trỏ tới model có máy chủ
nằm trong `egressAllow`; nếu không, ứng dụng báo lỗi cấu hình ngay lúc khởi động, nêu rõ route và máy chủ sai.

Đặt danh mục riêng bằng `llm.modelsYaml`, với model kiểu `openai_compat` (vLLM, Ollama, LM Studio, TGI):

```yaml
llm:
  modelsYaml: |
    models:
      internal-qwen:
        provider: openai_compat
        base_url: http://llm.corp.example:8000/v1     # vLLM
        model: Qwen/Qwen3-32B
        api_key_env: INTERNAL_LLM_API_KEY             # khóa trong Secret dataxland-env; null nếu không cần
        capabilities: [structured_output, tool_use]
        region: local
      internal-ollama:
        provider: openai_compat
        base_url: http://ollama.corp.example:11434/v1 # Ollama
        model: qwen3:32b
        api_key_env: null
        capabilities: [structured_output, tool_use]
        region: local
    routes: {copilot: internal-qwen, agent: internal-qwen}
```

- Route `copilot` (Si phân tích ngữ cảnh) cần model có `structured_output`; route `agent` (Si hỏi đáp) cần `tool_use`.
- Chỉ khai báo khả năng mà model thực sự làm tốt. Chất lượng câu trả lời của Si phụ thuộc model bạn chọn; hãy thử với dữ liệu
  của mình trước khi đưa vào dùng.
- `llm.copilotModel` và `llm.agentModel` chọn model theo tên trong danh mục mà không phải sửa `routes`.

## 4. Email qua SMTP nội bộ

```yaml
deployment:
  extraEnv:
    DX_SMTP_HOST: smtp.corp.example
    DX_SMTP_PORT: "587"
    DX_SMTP_USER: dataxland
    DX_SMTP_FROM: dataxland@corp.example
```

Mật khẩu đặt ở khóa `DX_SMTP_PASSWORD` của Secret. Khi cách ly, máy chủ SMTP không có trong `egressAllow` thì email bị tắt.

## 5. Tính năng bị tắt

Khi cách ly, các tính năng sau tự tắt nếu máy chủ chúng cần không có trong `egressAllow`:

| Tính năng | Máy chủ cần |
| --- | --- |
| Đăng nhập Google | `accounts.google.com`, `oauth2.googleapis.com` |
| CAPTCHA Turnstile | `challenges.cloudflare.com` |
| Kết nối sàn Shopee, TikTok Shop, Lazada | Máy chủ API và đăng nhập của sàn |
| Kênh Telegram | `api.telegram.org` |
| Kênh Slack | `slack.com`, `hooks.slack.com` |
| Kênh Microsoft Teams | `login.microsoftonline.com`, `login.botframework.com`, `smba.trafficmanager.net` |
| Google Sheets | `sheets.googleapis.com`, `oauth2.googleapis.com` |
| Email | Máy chủ SMTP của bạn |
| Gửi trace (OTLP) | Máy chủ nhận trace |

Mọi kết nối OAuth (sàn TMĐT và thư viện connector) **tắt mặc định** khi cách ly. Muốn bật, liệt kê chúng trong
`DX_OAUTH_PROVIDERS` ở `deployment.extraEnv`; sàn vẫn bị tắt nếu máy chủ của sàn không có trong `egressAllow`.

Xem danh sách thực tế của bản cài ở **Quản trị → Vận hành**, mục **Triển khai và giấy phép**: máy chủ được gọi ra và từng
tính năng bị tắt kèm lý do. Hoặc:

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

## 6. Nguồn dữ liệu

Mặc định khi cách ly chỉ còn các nguồn có sẵn trong ảnh và nối tới máy chủ do bạn nhập: **Excel**, **PostgreSQL**, **MySQL**,
**SQL Server**. Máy chủ database phải có trong `egressAllow` và được NetworkPolicy cho phép.

BigQuery, thư viện connector và các runtime Singer, dlt, Airbyte chỉ bật khi đặt `DX_SOURCE_CONNECTORS` trong
`deployment.extraEnv`, và từng kết nối vẫn bị chặn nếu máy chủ không được phép. Connector Airbyte kiểu cài từ PyPI lúc chạy,
hoặc kiểu manifest chưa có trong bộ đệm, không chạy được khi cách ly.

## 7. Chép ảnh vào registry nội bộ

Các thành phần sau **đã nằm trong ảnh `api`**, không phải tải lúc chạy: mô hình embedding, extension DuckDB, runtime connector
Singer, dlt và Airbyte. Bạn chỉ cần chép ảnh.

Trên máy có Internet và có [skopeo](https://github.com/containers/skopeo), từ bộ mã nguồn DataxLand cung cấp cùng bản phát hành:

```bash
# Xem danh sách ảnh
python -m tools.mirror_images list --tag <phiên bản> --owner <chủ kho ảnh>

# Cách 1: registry nội bộ nối được từ máy này
python -m tools.mirror_images mirror --tag <phiên bản> --owner <chủ kho ảnh> --to registry.corp.example/dataxland

# Cách 2: đóng gói để mang vào mạng kín
python -m tools.mirror_images bundle --tag <phiên bản> --owner <chủ kho ảnh> --out ./dx-bundle
```

- Danh sách gồm ảnh `api` (dùng chung cho `worker`, `mcp` và các Job), `web`, `site`, cùng các ảnh phụ trong chart (Postgres và
  MinIO dùng thử, s3proxy). `--with-build` thêm các ảnh nền nếu bạn muốn tự build ảnh trong mạng kín.
- Ảnh được chép với cả hai kiến trúc amd64 và arm64. `--dry-run` chỉ in lệnh `skopeo`.
- `bundle` ghi mỗi ảnh một tệp `oci-archive`, kèm `images.txt` (tệp, ảnh gốc, tên đích) và `SHA256SUMS`. Trong mạng kín, kiểm
  `SHA256SUMS` rồi nạp từng tệp:

```bash
skopeo copy oci-archive:<tệp>.tar docker://registry.corp.example/dataxland/<tên>:<tag>
```

Sau đó trỏ chart vào registry nội bộ:

```yaml
image:
  registry: registry.corp.example
  repositoryPrefix: dataxland
```

Nếu dùng s3proxy hoặc Postgres, MinIO dùng thử, đặt thêm `s3proxy.image`, `postgres.bundled.image`, `minio.image` theo tên đích
trong `images.txt`.

## Liên quan

- [Cài bằng Helm](/vi/docs/self-host/helm)
- [Yêu cầu và cỡ máy](/vi/docs/self-host/requirements)
- [Giấy phép](/vi/docs/self-host/license)
