Bỏ qua để đến nội dung

Gateway Agent

Gateway Agent giúp Fresco BI đọc database nằm trong mạng nội bộ của bạn. Agent chạy trên một máy của bạn, đọc database qua mạng LAN và chỉ gọi ra ngoài tới relay của Fresco BI <relay-host> qua cổng 443. Bạn không phải mở cổng vào nào.

Kiểu kết nối Dùng khi Firewall
Cloud Database truy cập được từ internet (RDS, Azure SQL, máy ảo có IP công khai) Cho phép IP của Fresco BI trên database
On-premises (qua Gateway) Database nằm trong mạng riêng, ví dụ 10.0.0.10:5432 Không mở cổng vào; máy agent gọi ra <relay-host>:443
Tối thiểu Khuyến nghị
CPU 1 vCPU (Ubuntu), 2 vCPU (Windows) 2 vCPU
RAM 2 GB (Ubuntu), 4 GB (Windows) 4 GB (Ubuntu), 8 GB (Windows)
Ổ đĩa trống 2 GB 10 GB
Hệ điều hành Ubuntu 24.04 64-bit (hệ điều hành đã kiểm thử); Windows Server 2019 trở lên, Windows 10 (1809) hoặc Windows 11, x64 Như trên, luôn cập nhật
Mạng Gọi ra HTTPS (443) tới <relay-host>; từ máy agent tới được host và cổng của từng database Tốc độ tải lên <relay-host> từ 10 Mbit/s
  • Mỗi bộ cài tự mang Python riêng và đủ mọi thư viện cần dùng, nên bạn không phải cài sẵn gì, và lúc cài không cần internet (cả Ubuntu lẫn Windows).
  • Máy cần chạy liên tục; muốn dự phòng thì thêm máy thứ hai (xem Nhiều agent).

Các con số dựa trên: agent dùng khoảng 150 MB bộ nhớ khi rảnh. Agent chạy tối đa 4 tác vụ cùng lúc, mỗi tác vụ là một tiến trình riêng khoảng 150 MB; dữ liệu được truyền theo lô khoảng 8 MB và không ghi xuống đĩa, nên bảng lớn chỉ tốn thêm thời gian chứ không thêm bộ nhớ. Mỗi tiến trình tác vụ bị giới hạn 2 GB bộ nhớ. Chương trình đã cài (kèm Python riêng) chiếm khoảng 0,6 GB; khi nâng cấp cần chỗ cho bản thứ hai, cộng thêm log. Phần còn lại dành cho hệ điều hành (Windows cần nhiều hơn Ubuntu).

Tốc độ mạng quyết định thời gian refresh: 1 triệu dòng 5 cột khoảng 100 MB, mất khoảng 80 giây ở 10 Mbit/s.

Nâng cấu hình (thêm RAM và CPU, hoặc thêm máy thứ hai, xem Nhiều agent) khi nhiều refresh chạy cùng lúc (quá 4 tác vụ sẽ phải chờ), khi thường xuyên nhập bảng lớn, hoặc khi báo cáo truy vấn gateway trực tiếp (realtime).

Cả hai cách đều dùng được trên Ubuntu và Windows.

Cách bố trí Host của nguồn dữ liệu cidr trong allow list
(a) Agent trên một máy riêng B, database trên máy A IP nội bộ của A, ví dụ 10.0.0.10 "10.0.0.10/32" (IP của A)
(b) Agent cài ngay trên máy database 127.0.0.1 (hoặc localhost) "127.0.0.1/32"

Cách (b) chỉ cho phép đúng một địa chỉ loopback (127.0.0.1/32 hoặc ::1/128). Một dải loopback như 127.0.0.0/8 bị từ chối ngoài môi trường dev và test.

Agent tự mở mọi kết nối: nó gọi ra relay của Fresco BI và gọi tới các database của bạn. Fresco BI không bao giờ kết nối vào mạng của bạn, nên bạn không mở cổng vào nào, không cần VPN, chuyển tiếp cổng hay IP công khai cho máy agent.

Gửi bảng này cho đội mạng hoặc đội bảo mật. Thay <IP agent> bằng IP nội bộ của máy agent.

# Chiều Nguồn Đích Giao thức / cổng Dùng cho
1 Ra <IP agent> <relay-host> TCP 443 (HTTPS, TLS 1.2 trở lên) Luôn luôn: đăng ký, nhận tác vụ, gửi kết quả và tải bộ cài
2 Ra <IP agent> Host của từng database, ví dụ 10.0.0.10 TCP, cổng của database: PostgreSQL 5432, MySQL 3306, SQL Server 1433, Oracle 1521 Luôn luôn
3 Ra <IP agent> Máy chủ DNS của bạn UDP/TCP 53 Luôn luôn: phân giải <relay-host> và tên host của database
4 Ra <IP agent> Máy chủ NTP của bạn UDP 123 Luôn luôn: đồng hồ lệch không quá 2 phút
5 Vào bất kỳ <IP agent> không có Không bao giờ
  • Nếu firewall hỗ trợ, hãy mở rule 1 theo tên miền (rule FQDN). IP của <relay-host> có thể thay đổi; đừng mở theo một IP cố định.
  • Rule 2 nằm trong mạng LAN. Chỉ mở các database mà agent này cần đọc, và khai báo đúng các host và cổng đó trong allow list (policy.toml). Agent từ chối mọi đích khác, kể cả khi firewall cho phép.
  • Rule 4 rất quan trọng: mỗi yêu cầu gửi relay đều được ký kèm thời gian. Đồng hồ lệch quá 2 phút sẽ bị từ chối (gateway-unauthorized). Trên Ubuntu, timedatectl phải hiện System clock synchronized: yes.
  • Lúc cài không cần internet: bộ cài đã có đủ mọi thứ, kể cả Python. Chỉ cần rule 1 là tải được bộ cài bằng wget (xem Cài trên Ubuntu).
  • Băng thông: nên có từ 10 Mbit/s tải lên từ máy agent tới <relay-host>.
  • Nếu mọi kết nối ra phải đi qua proxy, đặt HTTPS_PROXY=http://proxy.congty.local:3128 cho service (Ubuntu: sudo systemctl edit fresco-gateway, thêm Environment=HTTPS_PROXY=... dưới [Service]; Windows: biến môi trường cấp máy). Proxy phải cho phép CONNECT <relay-host>:443.
  • Tốt nhất: bỏ <relay-host> khỏi danh sách kiểm tra TLS (TLS inspection). Mỗi lần gọi giữ kết nối tới 20 giây (long polling) và gửi kết quả vài MB, một số proxy kiểm tra TLS sẽ cắt ngang.
  • Nếu bắt buộc phải kiểm tra, đăng ký agent với --ca-file /duong/dan/ca-cong-ty.pem (file PEM của CA mà proxy dùng để ký). Khi đó agent chỉ tin file này, không dùng kho chứng chỉ của hệ thống, nên file phải chứa đủ mọi CA cần thiết.

Chạy các lệnh này trước khi đăng ký:

Terminal window
# DNS và HTTPS tới relay: phải ra mã HTTP (401 hoặc 404), không phải timeout hay lỗi TLS
curl -sS -o /dev/null -w '%{http_code}\n' https://<relay-host>/gw/v1/poll -X POST
# Cổng database: phải ra "succeeded"
nc -vz 10.0.0.10 5432
# Đồng hồ
timedatectl | grep synchronized

Trên Windows, dùng Test-NetConnection <relay-host> -Port 443 và Test-NetConnection 10.0.0.10 -Port 1433.

  1. Gateway › Thêm gateway. Nhập tên, ví dụ HQ.
  2. Bấm Lấy token. Nếu Fresco yêu cầu đăng nhập lại, đăng nhập ở tab mới rồi quay lại: token tự hiện.
  3. Hộp thoại hiện token đăng ký dùng một lần (hiệu lực 1 giờ) và các bước cài. Giữ hộp thoại mở.

Máy agent đã gọi được tới <relay-host> ở cổng 443 (rule 1 trong Quy tắc mạng), nên tải bộ cài thẳng trên máy đó. Hộp thoại, tab Ubuntu (systemd), hiện sẵn các lệnh này với đúng phiên bản hiện tại. Nếu tab không có lệnh wget, máy chủ này chưa cho tải từ relay: dùng cách tải bằng trình duyệt ở dưới. Các lệnh:

Terminal window
wget https://<relay-host>/gw/v1/agent/fresco-gateway-agent-<phiên bản>.tar.gz
echo "<SHA-256 trong hộp thoại> fresco-gateway-agent-<phiên bản>.tar.gz" | sha256sum -c -

Lệnh kiểm tra phải in fresco-gateway-agent-<phiên bản>.tar.gz: OK. Lệnh so tệp với SHA-256 hiện trong hộp thoại (nơi bạn đã đăng nhập), không so với mã băm tải từ cùng máy chủ. Nếu in FAILED, đừng cài; hãy tải lại. Mỗi địa chỉ chỉ tải được vài lần mỗi phút, và máy chủ có thể tạm trả 503 khi nhiều máy cùng tải (đợi một phút rồi chạy lại).

Máy chưa được mở mạng ra ngoài? Bấm Tải fresco-gateway-agent-<phiên bản>.tar.gz trong hộp thoại, chép tệp sang máy agent (ví dụ bằng scp), rồi kiểm tra bằng sha256sum fresco-gateway-agent-<phiên bản>.tar.gz so với giá trị trong hộp thoại.

Terminal window
tar -xzf fresco-gateway-agent-<phiên bản>.tar.gz
cd fresco-gateway-agent
sudo ./install.sh

Bộ cài tạo user hệ thống fresco-gw, cài agent vào /opt/fresco-gateway, tạo allow list /etc/fresco-gateway/policy.toml (chỉ lần đầu), tạo thư mục trạng thái /var/lib/fresco-gateway (quyền 0700) và bật service fresco-gateway. Service chỉ chạy sau khi đăng ký. Bộ cài chép gói vào một thư mục riêng chỉ root mở được rồi cài từ bản chép đó; bộ cài từ chối chạy nếu user khác sửa được các tệp đã giải nén (hãy giải nén trong thư mục home của bạn, không dùng thư mục chung). Chạy lại với gói mới hơn để nâng cấp: nếu nâng cấp lỗi, bản cũ được khôi phục và chạy lại.

Cho phép các cổng database (5432, 3306, 1433, 1521 cho PostgreSQL, MySQL, SQL Server, Oracle) trong mạng của chính máy này:

Terminal window
sudo fresco-gateway policy allow-local --restart

Lệnh tự tìm dải mạng của card mạng giữ default route, in ra mục sẽ thêm và hỏi lại trước khi ghi. Hoặc thêm từng database:

Terminal window
sudo fresco-gateway policy allow --host 10.0.0.10 --port 5432 --kind postgres --restart

Hoặc sửa tay /etc/fresco-gateway/policy.toml (xem mục Allow list bên dưới):

Terminal window
sudo nano /etc/fresco-gateway/policy.toml
Terminal window
sudo -u fresco-gw fresco-gateway --state-dir /var/lib/fresco-gateway enroll \
--url https://<relay-host> --token-file - --name "$(hostname)"

Khi thấy dòng Enrollment token, dán token rồi nhấn Enter (token được ẩn khi dán, giống nhập mật khẩu). Lệnh in ra:

Token received (43 characters). Registering...
Registered. Compare this fingerprint with the one shown in Fresco: XXXX-XXXX-…
Terminal window
sudo systemctl start fresco-gateway
systemctl status fresco-gateway

Chạy mọi lệnh trong PowerShell bằng quyền Administrator.

  1. Trong hộp thoại, tab Windows (service), bấm Tải fresco-gateway-agent-windows-<phiên bản>.zip.
  2. Chép tệp sang máy agent.
  3. Kiểm tra SHA-256. Giá trị Hash phải trùng với giá trị trong hộp thoại (không phân biệt hoa thường):
Terminal window
Get-FileHash .\fresco-gateway-agent-windows-<phiên bản>.zip -Algorithm SHA256
Terminal window
Unblock-File .\fresco-gateway-agent-windows-<phiên bản>.zip
Expand-Archive -Path .\fresco-gateway-agent-windows-<phiên bản>.zip -DestinationPath .
cd .\fresco-gateway-agent-windows
powershell -ExecutionPolicy Bypass -File .\install.ps1

Bộ cài đặt agent và Python riêng của nó vào %ProgramFiles%\FrescoGateway, tạo %ProgramData%\FrescoGateway gồm state (khóa, đăng ký, audit.log), logs và policy.toml (chỉ lần đầu), chỉ SYSTEM, Administrators và service đọc được, rồi đăng ký service FrescoGateway (tài khoản NT SERVICE\FrescoGateway, tự khởi động trễ, tự chạy lại khi lỗi). Service chỉ chạy sau khi đăng ký. Agent từ chối chạy nếu thư mục state mở cho người khác; chạy lại install.ps1 để đặt lại quyền.

Terminal window
& "$env:ProgramFiles\FrescoGateway\fresco-gateway.cmd" policy allow-local --restart

Hoặc thêm từng database (... policy allow --host 10.0.0.11 --port 1433 --kind sqlserver --restart), hoặc sửa tay:

Terminal window
notepad "$env:ProgramData\FrescoGateway\policy.toml"
Terminal window
Read-Host 'Enrollment token' | & "$env:ProgramFiles\FrescoGateway\fresco-gateway.cmd" --state-dir "$env:ProgramData\FrescoGateway\state" enroll `
--url https://<relay-host> --token-file - --name $env:COMPUTERNAME

Dán token vào lời nhắc Enrollment token rồi nhấn Enter (token không lưu vào lịch sử PowerShell). Lệnh in ra fingerprint.

Terminal window
Start-Service FrescoGateway
Get-Service FrescoGateway

Agent chỉ kết nối tới các dải mạng, cổng và loại connector được liệt kê ở đây, bất kể nguồn dữ liệu yêu cầu gì. Danh sách rỗng là chặn tất cả. Giữ mỗi mục thật hẹp: một /32 cho mỗi database.

Chạy bằng quyền root (Linux: sudo; Windows: PowerShell bằng quyền Administrator). Mỗi lệnh in ra mục sẽ thêm và hỏi lại trước khi ghi (--yes để bỏ câu hỏi), không thêm mục đã được cho phép, giữ nguyên ghi chú và các mục cũ, kiểm tra cả tệp trước khi thay. --restart khởi động lại agent để đọc allow list mới.

Lệnh Thêm gì
fresco-gateway policy allow-local Dải mạng của máy này (card mạng giữ default route), tối đa là /24 chứa địa chỉ máy (card mạng /31 hoặc /32, như trên Google Cloud, cũng dùng /24 đó), với cổng 5432, 3306, 1433, 1521 và connector postgres, mysql, sqlserver, oracle. Đổi bằng --ports 5432,6432 và --connectors postgres.
fresco-gateway policy allow --host <IP hoặc tên> --port <cổng> --kind <connector> Một /32 (IPv6 /128) cho mỗi địa chỉ. Tên host được phân giải trên máy này và thêm từng địa chỉ.
fresco-gateway policy show Không thêm gì: in allow list và mã policy mà trang Gateway hiện cho thành viên.

allow-local từ chối mạng public, dải carrier-grade NAT (100.64.0.0/10), địa chỉ loopback hoặc link-local và mọi dải agent luôn chặn: khi đó dùng policy allow --host cho từng database. Mục mẫu 10.0.0.10/32 do bộ cài tạo được xoá ở lần ghi đầu tiên nếu bạn chưa sửa nó.

PostgreSQL:

env = "prod"
[[allow]]
cidr = "10.0.0.10/32"
ports = [5432]
connectors = ["postgres"]

MySQL và SQL Server trên cùng một máy:

[[allow]]
cidr = "10.0.0.20/32"
ports = [3306, 1433]
connectors = ["mysql", "sqlserver"]

Agent cài ngay trên máy database (cách b):

[[allow]]
cidr = "127.0.0.1/32"
ports = [5432]
connectors = ["postgres"]

connectors nhận loại connector của nguồn dữ liệu: postgres, mysql, mariadb, sqlserver…

Dải rộng hơn /24 (IPv4) hoặc /64 (IPv6) bị từ chối, trừ khi bạn thêm i_understand_broad = true:

[[allow]]
cidr = "10.20.0.0/16"
ports = [5432]
connectors = ["postgres"]
i_understand_broad = true

Luôn bị chặn: địa chỉ link-local và metadata của cloud (169.254.0.0/16…), multicast, dải dành riêng, và mọi dải loopback rộng hơn một địa chỉ (127.0.0.0/8). Giới hạn tùy chọn:

[limits]
max_rows = 1000000
timeout_s = 225

Agent đọc tệp này khi khởi động: sau khi sửa, khởi động lại service (sudo systemctl restart fresco-gateway, hoặc Restart-Service FrescoGateway).

  1. Quay lại hộp thoại, agent hiện ra với tên, host, phiên bản và fingerprint.
  2. So sánh với fingerprint in trên máy agent. Để in lại:
Terminal window
sudo -u fresco-gw fresco-gateway --state-dir /var/lib/fresco-gateway fingerprint
Terminal window
& "$env:ProgramFiles\FrescoGateway\fresco-gateway.cmd" --state-dir "$env:ProgramData\FrescoGateway\state" fingerprint
  1. Đánh dấu Tôi đã so sánh fingerprint, rồi bấm Phê duyệt. Nếu không khớp, bấm Từ chối.
  1. Workspace › Nguồn › Nguồn mới, chọn connector.
  2. Kiểu kết nối: On-premises (qua Gateway), chọn cụm gateway.
  3. Nhập host của database theo cách máy agent nhìn thấy: IP nội bộ của A (cách a, ví dụ 10.0.0.10) hoặc 127.0.0.1 (cách b). Rồi cổng, tài khoản, mật khẩu.
  4. Kiểm tra kết nối, rồi Lưu.
  • Trang Gateway: trạng thái cụm (Online, Suy giảm, Offline), heartbeat, phiên bản của từng thành viên, số mục allow list và mã policy.
  • Ubuntu: systemctl status fresco-gateway và journalctl -u fresco-gateway -f.
  • Windows: Get-Service FrescoGateway; Event Viewer › Windows Logs › Application, nguồn FrescoGateway (cảnh báo và lỗi); Get-Content "$env:ProgramData\FrescoGateway\logs\gateway.log" -Tail 50 -Wait.
  • Mỗi tác vụ agent chạy được ghi vào audit.log trong thư mục trạng thái (thời gian, tác vụ, connector, kết quả; không có dữ liệu, không có mật khẩu).

Cài agent lên máy thứ hai và đăng ký vào cùng gateway: mở Gateway, chọn gateway, bấm Thêm thành viên, đăng nhập lại nếu được yêu cầu, rồi làm theo các bước như trên với token mới. Tác vụ được giao cho bất kỳ thành viên nào đang online; một máy dừng thì máy kia vẫn chạy. Dùng cùng một allow list cho mọi thành viên: trang Gateway cảnh báo khi policy khác nhau.

Tải gói mới từ hộp thoại, kiểm tra SHA-256, rồi chạy lại bộ cài. Allow list và thông tin đăng ký được giữ nguyên, service khởi động lại với phiên bản mới.

  • Ubuntu: giải nén, rồi sudo ./install.sh.
  • Windows: giải nén, rồi powershell -ExecutionPolicy Bypass -File .\install.ps1. Lệnh dừng service, thay tệp chương trình, giữ policy, khóa và log, rồi chạy lại service.

Chạy lệnh gỡ cài đặt trên máy agent. Lệnh này trước tiên báo cho Fresco BI rằng máy rời gateway (ký bằng khóa của chính máy đó, không cần người dùng đăng nhập), nên Fresco BI sẽ không bao giờ chấp nhận máy này nữa và gateway có thể xóa ngay. Sau đó lệnh dừng và gỡ service, khóa và thông tin đăng ký, allow list và tệp chương trình, rồi in một dòng xác nhận.

Ubuntu:

Terminal window
sudo /opt/fresco-gateway/uninstall.sh

Windows (PowerShell quyền Administrator):

Terminal window
powershell -ExecutionPolicy Bypass -File "$env:ProgramFiles\FrescoGateway\install.ps1" -Uninstall

Nếu máy không tới được relay, lệnh dừng lại và không thay đổi gì. Thêm --force (Ubuntu) hoặc -Force (Windows) để vẫn gỡ agent: khi đó Fresco BI coi thành viên là có thể còn kết nối cho đến khi không có heartbeat trong 24 giờ.

Trong Gateway, mở gateway và bấm Xóa. Chỉ xóa được khi:

  • chưa thiết lập xong (chưa thành viên nào được duyệt), hoặc
  • mọi thành viên đã ngắt hẳn: đã gỡ bằng lệnh trên, đã bị thu hồi, hoặc không có heartbeat ít nhất 24 giờ,

và không nguồn dữ liệu nào đang dùng gateway. Nếu chưa đủ điều kiện, hộp thoại cho biết lý do: các nguồn dữ liệu đang dùng gateway và trạng thái từng thành viên. Khi xóa, bạn cần đăng nhập lại và gõ tên gateway.

Gateway chuyển vào Cài đặt > Thùng rác trong 30 ngày. Các thành viên bị thu hồi và yêu cầu đăng ký đang mở bị hủy. Khôi phục đưa gateway trở lại nhưng thành viên vẫn bị thu hồi: hãy đăng ký agent lại (Tiếp tục thiết lập).

Để dừng một máy mà chưa gỡ cài đặt, mở gateway và bấm Thu hồi ở thành viên đó. Agent bị thu hồi sẽ dừng và không tự chạy lại; sau đó hãy gỡ cài đặt trên máy.

Agent trên Windows không hỗ trợ SSH tunnel: gateway đã nằm trong mạng của bạn, hãy kết nối thẳng tới database.

Bạn thấy Nghĩa là Cách xử lý
Tải về: “Máy chủ này chưa có gói Gateway Agent để tải” Máy chủ chưa có gói cho hệ điều hành đó Hỏi quản trị Fresco BI
SHA-256 không khớp Tệp tải thiếu hoặc bị thay đổi Tải lại; tuyệt đối không cài
error: the relay refused the request (enrollment-invalid) Token sai, đã dùng hoặc hết hạn Tạo token mới trong hộp thoại
already enrolled: remove the state directory to enroll again Máy này đã là thành viên Thu hồi thành viên cũ, xóa thư mục trạng thái, đăng ký lại
error: … is wider than /24: set i_understand_broad Mục allow list quá rộng Thu hẹp cidr hoặc thêm i_understand_broad = true
error: … overlaps an always-blocked range Dải metadata, link-local hoặc tương tự Bỏ mục đó
gateway-unavailable: “Không có Gateway Agent nào của cụm này đang online” Không thành viên nào online Kiểm tra service và kết nối ra 443 tới <relay-host>
gateway-offline: “Gateway đang offline, không thể kiểm tra kết nối” Như trên, khi kiểm tra kết nối Như trên
gateway-cluster-required Chọn On-premises nhưng chưa chọn cụm Chọn một cụm gateway
gateway-not-supported Connector này chỉ dùng Cloud Dùng Cloud
blocked_address Host không có trong allow list (hoặc bị chặn) Trên máy agent: sudo fresco-gateway policy allow --host <host> --port <cổng> --kind <connector> --restart (hoặc thêm vào policy.toml rồi khởi động lại)
dns_failure Máy agent không phân giải được tên host Dùng IP hoặc sửa DNS trên máy agent
network_unreachable Không có gì lắng nghe ở đó, hoặc firewall giữa agent và database chặn Kiểm tra host, cổng và firewall nội bộ
timeout Database không trả lời kịp Thường do firewall lặng lẽ chặn gói tin
tls_error Chế độ SSL không khớp với máy chủ Kiểm tra chế độ SSL và chứng chỉ CA
auth_failed Sai tài khoản hoặc mật khẩu Sửa thông tin đăng nhập
Thành viên “Đã thu hồi”, service dừng Thành viên đã bị thu hồi Đăng ký lại bằng token mới nếu cần
  • Token đăng ký chỉ dùng được một lần và trong 1 giờ. Token được đọc từ đầu vào chuẩn, không bao giờ qua dòng lệnh, nên không nằm trong lịch sử shell hay danh sách tiến trình. Fresco BI chỉ lưu bản băm của token.
  • Chỉ duyệt thành viên sau khi đã so sánh fingerprint.
  • Khóa và trạng thái nằm trong thư mục chỉ tài khoản service và quản trị viên đọc được (/var/lib/fresco-gateway, quyền 0700; %ProgramData%\FrescoGateway\state, danh sách quyền chỉ gồm SYSTEM, Administrators và NT SERVICE\FrescoGateway).
  • Mật khẩu nguồn dữ liệu được niêm phong cho gateway và chỉ được mở trên máy agent.
  • Allow list thuộc về bạn: Fresco BI không thể thay đổi nó.
  • audit.log ghi lại từng tác vụ agent đã chạy.