III. Koios gRest

1. gRest là gì

gRest là một mã nguồn mở của lớp truy vấn được xây dựng trên dbsync, sử dụng PostgREST và HAProxy. Đây là một phần trong nỗ lực của đội ngũ Koios nhằm hợp nhất các công việc cá nhân của cộng đồng và tạo ra một cấu trúc đồng nhất để truy vấn dbsync, đồng thời áp dụng các tiêu chuẩn hóa cho truy vấn sử dụng các công cụ mã nguồn mở. Ngoài ra, gRest còn cung cấp các tính năng tiện ích như triển khai quy tắc dự phòng, kiểm tra tình trạng hệ thống, thiết lập ưu tiên, ngăn chặn các cuộc tấn công DDoS, cung cấp thời gian chờ, báo cáo thông tin phân tích trong khoảng thời gian dài, v.v. – tất cả đều hữu ích khi thực hiện phân tích trên các phiên bản hệ thống.

a. Lưu ý

Các tập lệnh dưới đây cũng hỗ trợ việc tích hợp Ogmios, nhưng hiện tại, Ogmios không được thiết kế để cung cấp quản lý phiên nâng cao cho kiến trúc server-client khi thiếu một lớp trung gian. Do đó, khả năng giám sát Ogmios từ phiên bản giám sát bị hạn chế nhằm tránh nguy cơ tấn công DDoS vào hệ thống.

b. Các thành phần

PostgREST: PostgREST là một giao diện JSON RPC cho bất kỳ cơ sở dữ liệu PostgreSQL nào (trong trường hợp này là cơ sở dữ liệu được phục vụ qua cardano-db-sync), cung cấp dịch vụ web RESTful. Các endpoint của PostgREST thực chất là các bảng hoặc hàm được định nghĩa trong schema đã chọn thông qua tệp cấu hình gRest. Đây là một giải pháp thay thế dễ dàng vì nó phục vụ trực tiếp cơ sở dữ liệu dưới dạng API, so với thành phần Cardano GraphQL (thường gặp độ trễ). Một số ưu điểm khác của PostgREST so với các dự án dựa trên GraphQL là hiệu suất cao, không lưu trạng thái, hỗ trợ xác thực JWT / xác thực gốc của PostgreSQL cho giao diện Rest.

HAProxy: HAProxy là một cổng proxy dễ sử dụng, tự động cung cấp tính năng dự phòng, bảo vệ cơ bản chống lại tấn công DDoS, quy tắc quản lý cân bằng tải, thiết lập nhiều frontend/backend, hỗ trợ dễ dàng cho TLS dành cho các phiên bản công khai, v.v. Bạn có thể thay đổi cấu hình proxy theo nhu cầu bảo mật (SecOps) của mình. Thành phần này là tùy chọn (ví dụ: nếu bạn muốn public máy chủ PostgREST của mình, bạn có thể thực hiện bằng các bước tương tự).

2. Thiết lập gRest

Để bắt đầu, bạn cần đảm bảo rằng bạn đã hoàn thành cài đặt dbsync

cd $CNODE_HOME/priv
PGPASSFILE=$CNODE_HOME/priv/.pgpass
psql cexplorer

Đảm bảo rằng bạn có thể kết nối với cơ sở dữ liệu Postgres của mình một cách bình thường (hãy thoát khỏi psql sau khi xác thực bằng lệnh \q). Là một phần của việc thực hiện guild-deploy.sh, bạn sẽ tìm thấy tệp setup-grest.sh được cung cấp trong thư mục ${CNODE_HOME}/scripts, tệp này sẽ giúp bạn tự động hóa việc cài đặt PostgREST, HAProxy, cũng như cập nhật các truy vấn/hàm mới nhất do Koios cung cấp cho các phiên bản của bạn.

cd "${CNODE_HOME}"/scripts
./setup-grest.sh -h
#
# Usage: setup-grest.sh [-f] [-i [p][r][m][c][d]] [-u] [-b <branch>]
# 
# Install and setup haproxy, PostgREST, polling services and create systemd services for haproxy, postgREST and dbsync
# 
# -f    Force overwrite of all files including normally saved user config sections
# -i    Set-up Components individually. If this option is not specified, components will only be installed if found missing (eg: -i prcd)
#     p    Install/Update PostgREST binaries by downloading latest release from github.
#     r    (Re-)Install Reverse Proxy Monitoring Layer (haproxy) binaries and config
#     m    Install/Update Monitoring agent scripts
#     c    Overwrite haproxy, postgREST configs
#     d    Overwrite systemd definitions
# -u    Skip update check for setup script itself
# -q    Run all DB Queries to update on postgres (includes creating grest schema, and re-creating views/genesis table/functions/triggers and setting up cron jobs)
# -b    Use alternate branch of scripts to download - only recommended for testing/development (Default: master)
#

Để chạy thiết lập và ghi đè tất cả các nhiệm vụ triển khai tiêu chuẩn từ một nhánh (ví dụ: nhánh koios-1.0.9), bạn có thể muốn sử dụng:

./setup-grest.sh -f -i prmcd -r -q -b koios-1.0.9

Tương tự, nếu bạn muốn cài đặt lại tất cả các thành phần và buộc ghi đè tất cả các cấu hình nhưng không đặt lại các bảng bộ nhớ cache, bạn có thể chạy:

./setup-grest.sh -f -i prmcd -q

Một ví dụ khác có thể là bảo toàn cấu hình của bạn, nhưng chỉ cập nhật các truy vấn bằng cách sử dụng một nhánh thay thế (ví dụ: giả sử bạn muốn thử nhánh alpha trước khi có một phiên bản được gán nhãn). Để thực hiện điều này, bạn có thể chạy:

./setup-grest.sh -q -b alpha

Vui lòng đảm bảo làm theo các hướng dẫn trên màn hình, nếu có (ví dụ: khởi động lại các dịch vụ đã triển khai, hoặc cập nhật cấu hình để chỉ định đúng URL postgres mục tiêu / kích hoạt TLS / thêm peers, v.v. trong ${CNODE_HOME}/priv/grest.conf và ${CNODE_HOME}/files/haproxy.cfg).

Các cổng mặc định được sử dụng sẽ làm cho phiên bản HAProxy có sẵn tại cổng 8053 hoặc 8453 nếu TLS được kích hoạt (bạn có thể muốn kích hoạt quy tắc tường lửa để mở cổng này cho các dịch vụ mà bạn muốn truy cập). Nếu bạn muốn ngăn chặn việc truy cập không xác thực vào schema grest, hãy bỏ dấu comment dòng jwt-secret và chỉ định một mã thông báo bí mật tùy chỉnh.

3. Bật TLS trên HAProxy

Để bật SSL trên HAProxy của bạn, tất cả những gì bạn cần làm là chỉnh sửa tệp ${CNODE_HOME}/files/haproxy.cfg và cập nhật phần frontend app bằng cách bỏ chú thích dòng ssl bind (và thêm chú thích cho dòng normal bind).

Nếu bạn không quen với cách cấu hình TLS hoặc không muốn mua một chứng chỉ, bạn có thể tìm các mẹo để tạo chứng chỉ TLS miễn phí thông qua LetsEncrypt bằng cách tham khảo các hướng dẫn tại đây. Sau khi bạn đã tạo được chứng chỉ TLS, bạn cần liên kết khóa riêng và chứng chỉ full chain lại với nhau trong một tệp /etc/ssl/server.pem mà sau đó có thể được tham chiếu như sau:

frontend app
#bind 0.0.0.0:8053
## If using SSL, comment line above and uncomment line below
bind :8453 ssl crt /etc/ssl/server.pem no-sslv3
http-request set-log-level silent
acl srv_down nbsrv(grest_postgrest) eq 0
acl is_wss hdr(Upgrade) -i websocket
…

Khởi động lại dịch vụ HAProxy để các thay đổi có hiệu lực.

sudo systemctl restart cnode-haproxy.service

4. Validation

Với cấu hình này, bạn cũng có một script checkstatus.sh, script này sẽ truy vấn instance Postgres DB thông qua HAProxy (thông qua postgREST), và chỉ hiển thị instance hoạt động nếu block mới nhất trong instance DB của bạn nằm trong khoảng 180 giây.

Nếu bạn đang sử dụng guild network, bạn có thể thực hiện một vài kiểm tra cơ bản để đảm bảo tính ổn định như sau:

a. Để truy vấn stake hoạt động cho pool pool1z2ry6kxywgvdxv26g06mdywynvs7jj3uemnxv273mr5esukljsr trong epoch 122, chúng ta có thể thực thi lệnh dưới đây:

curl -d _pool_bech32=pool1z2ry6kxywgvdxv26g06mdywynvs7jj3uemnxv273mr5esukljsr -d _epoch_no=122 -s http://localhost:8053/rpc/pool_active_stake
## {"active_stake_sum" : 19409732875}

b. Để kiểm tra khóa chủ sở hữu mới nhất cho pool pool1z2ry6kxywgvdxv26g06mdywynvs7jj3uemnxv273mr5esukljsr, bạn có thể thực thi lệnh dưới đây:

curl -d _pool_bech32=pool1z2ry6kxywgvdxv26g06mdywynvs7jj3uemnxv273mr5esukljsr -s http://localhost:8050/rpc/pool_owners
## [{"owner" : "stake_test1upx5p04dn3t6dvhfh27744su35vvasgaaq565jdxwlxfq5sdjwksw"}, {"owner" : "stake_test1uqak99cgtrtpean8wqwp7d9taaqkt9gkkxga05m5azcg27chnzfry"}]

Bạn có thể muốn khám phá tất cả các endpoint có sẵn và thử nghiệm chúng. Để làm điều này, hãy tham khảo tài liệu API cho tài liệu OpenAPI3. Mỗi endpoint có một ví dụ được điền sẵn cho mainnet và mặc định kết nối với endpoint chính của Koios, cho phép bạn thử nghiệm các endpoint và nếu cần, lấy các lệnh curl để bắt đầu thử nghiệm với các instance cục bộ hoặc từ xa của bạn.

5. Tham gia Cụm Koios với tư cách là Nhà cung cấp Instance

Nếu bạn muốn tham gia vào hạ tầng phi tập trung bằng cách cung cấp một instance, có một vài bước bổ sung mà bạn cần thực hiện:

a. Mở cổng cho instance HAProxy của bạn (mặc định: 8053), dịch vụ gRest Exporter (mặc định: 8059) và (tùy chọn) instance API submit (mặc định: 8090) đối với instance giám sát (không cần mở các cổng này ra internet) của mạng tương ứng.

b. Đảm bảo rằng mỗi dịch vụ trên đang lắng nghe trên địa chỉ IP công cộng của bạn (ví dụ, submitapi.sh có thể cần được chỉnh sửa để thay đổi HOSTADDR thành 0.0.0.0 và khởi động lại).

c. Tạo một yêu cầu PR chỉ định thông tin kết nối đến cổng HAProxy của bạn tại đây.

d. Đảm bảo tham gia nhóm thảo luận trên Telegram để tham gia vào các thảo luận, hành động, cuộc thăm dò cho các tính năng mới, v.v. Hãy thoải mái gửi thông điệp trong nhóm nếu bạn gặp khó khăn trong việc thực hiện bất kỳ điều gì ở trên.

Nguồn: https://cardano-community.github.io/guild-operators/Build/grest/