Cài đặt

Đang tìm phiên bản beta? Xem Cài đặt Beta để biết thông tin về Docker images và kora-cli@2.2.0-beta.7.

Bắt đầu với Kora bằng cách cài đặt công cụ CLI để vận hành node Kora hoặc TypeScript SDK cho các ứng dụng client tương tác với node Kora.

Yêu cầu hệ thống

Cho CLI (Server)

Rust: Phiên bản 1.86 trở lên (không bắt buộc nếu dùng Docker)

Cho TypeScript SDK (Client)

Node.js: Phiên bản LTS trở lên
TypeScript: phiên bản mới nhất

Phụ thuộc tùy chọn

Solana CLI: Hữu ích cho việc tạo khóa và kiểm thử
Docker: Cho triển khai container hóa

Kora CLI

Kora CLI là cách chính để chạy và quản lý các node Kora. Chọn phương thức cài đặt mà bạn ưa thích:

Lựa chọn 1: Cài đặt từ Cargo

Cài đặt trực tiếp từ crates.io bằng Cargo:

cargo install kora-cli

Lựa chọn 2: Build từ mã nguồn

Clone và build phiên bản ổn định mới nhất từ mã nguồn:

git clone https://github.com/solana-foundation/kora.git
cd kora
git checkout v2.0.5
just install

Lưu ý: Nhánh main của Kora là nhánh tích hợp và có thể chứa các thay đổi chưa phát hành hoặc đang ở giai đoạn beta. Luôn checkout thẻ phát hành ổn định mới nhất. Xem trang phát hành để biết phiên bản ổn định mới nhất.

Lệnh này sẽ build và cài đặt tệp nhị phân kora vào thư mục Cargo bin cục bộ của bạn.

Lựa chọn 3: Docker

Pull Docker image chính thức từ GitHub Container Registry:

docker pull ghcr.io/solana-foundation/kora:latest

Chạy với các tệp cấu hình được mount:

docker run -v $(pwd)/kora.toml:/app/kora.toml \
  -v $(pwd)/signers.toml:/app/signers.toml \
  -p 8080:8080 \
  ghcr.io/solana-foundation/kora:latest \
  rpc start --signers-config /app/signers.toml

Xác Minh Cài Đặt

Xác minh Kora CLI đã được cài đặt chính xác:

kora --version

TypeScript SDK

Cài đặt Kora TypeScript SDK cho các ứng dụng client:

pnpm add @solana/kora

Peer Dependencies

Kora yêu cầu @solana/kit và một số gói plugin Kit làm peer dependencies. Hầu hết các trình quản lý gói (pnpm v7+, npm v7+) tự động cài đặt peer dependencies, vì vậy thông thường bạn chỉ cần:

pnpm add @solana/kora @solana/kit

Nếu trình quản lý gói của bạn không tự động cài đặt peers, hãy cài đặt chúng theo cách thủ công:

pnpm add @solana/kit @solana-program/token @solana-program/compute-budget \
  @solana/kit-plugin-instruction-plan @solana/kit-plugin-payer @solana/kit-plugin-rpc

Yêu Cầu Phiên Bản

KoraClient (độc lập): Hoạt động với @solana/kit v5.0+
koraPlugin() (có thể kết hợp): Yêu cầu @solana/kit v5.4+ cho mẫu createEmptyClient().use()
createKitKoraClient() (Kit client): Yêu cầu @solana/kit v6.1+ để kết hợp plugin đầy đủ

Xem Tổng Quan JSON-RPC API để biết các ví dụ sử dụng client chi tiết.

Xác Minh Cài Đặt SDK

Xác minh cài đặt SDK của bạn bằng một bài kiểm tra kết nối đơn giản:

import { KoraClient } from "@solana/kora";

async function testConnection() {
  const client = new KoraClient({ rpcUrl: "http://localhost:8080" }); // Replace with your Kora server URL

  try {
    const config = await client.getConfig();
    console.log("✅ Successfully connected to Kora server");
  } catch (error) {
    console.error("❌ Connection failed:", error.message);
  }
}

testConnection();

Xử Lý Sự Cố

Vấn Đề CLI

"kora: command not found": Đảm bảo ~/.cargo/bin nằm trong PATH của bạn:

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Build thất bại: Cập nhật Rust lên phiên bản stable mới nhất:

rustup update stable

Vấn Đề SDK

Cảnh báo về peer dependency: Cài đặt các dependency Solana bắt buộc được liệt kê ở trên.

Lỗi TypeScript: Đảm bảo phiên bản TypeScript của bạn là 4.5+ và cài đặt các định nghĩa kiểu:

pnpm add -D @types/node

Kết nối bị từ chối: Đảm bảo máy chủ Kora của bạn đang chạy và có thể truy cập được tại endpoint đã chỉ định.

Mục lục