Người vận hành

Người vận hành Private Channels là gì?

Người vận hành là một thực thể đáng tin cậy, được cấp quyền trên chuỗi, đóng vai trò cầu nối giữa Solana Mainnet và mạng kênh riêng tư. Người vận hành được cấp phép bởi quản trị viên phiên bản thông qua AddOperator, lệnh này tạo ra một Operator PDA trên chuỗi; nếu không có điều này, không bên nào có thể gọi ReleaseFunds. Trong thực tế, người vận hành là một tổ chức hoặc nhóm chạy các dịch vụ theo dõi tiền gửi, đúc token phía kênh, phát hiện lệnh rút tiền và quyết toán tiền về Mainnet. Chạy một phiên bản sẽ cung cấp cho người dùng của bạn các giao dịch chuyển khoản riêng tư, khối lượng lớn không hiển thị trên Solana Mainnet, thông lượng tức thì không phí vượt qua TPS Solana gốc, và kiểm soát truy cập thông qua RBAC.

Trước Khi Bắt Đầu

Yêu Cầu Tiên Quyết

Ghim các phiên bản này trên máy chủ để khớp với các Docker image:

• Docker Engine 26+ (macOS Apple Silicon: bật "Docker VMM" trong Settings -> Virtual Machine Options)
• Node.js 24.7.0 và pnpm 10.15.1
• Solana CLI 3.1.13 (Agave)
• Rust 1.91.0
• Một endpoint Yellowstone gRPC cho Devnet (có từ Helius, Triton, QuickNode)

Về yêu cầu mạng và cổng mặc định, xem docs/TECHNICAL_REQUIREMENTS.md trong kho lưu trữ.

Cài đặt chuỗi công cụ Solana đã ghim phiên bản và làm nóng bộ đệm SBF:

make install-toolchain

Các Dịch Vụ

Chạy một phiên bản Private Channels có nghĩa là đảm nhận năm trách nhiệm liên tục, mỗi trách nhiệm được xử lý bởi các container chuyên dụng trong stack Docker Compose:

1. Lập chỉ mục Mainnet để theo dõi tiền gửi - indexer-solana theo dõi Solana Mainnet để tìm các sự kiện Deposit qua Yellowstone gRPC; operator-solana nhận các tiền gửi đã xác nhận và đúc số dư token tương đương trên mạng kênh
2. Lập chỉ mục kênh để theo dõi lệnh rút tiền - indexer-private-channel thăm dò kênh mỗi giây để tìm các sự kiện burn WithdrawFunds và ghi các bản ghi rút tiền đang chờ xử lý vào cơ sở dữ liệu
3. Giải phóng tiền trên Mainnet - operator-private-channel nhận các bản ghi đang chờ xử lý và gọi ReleaseFunds trên Escrow Program với bằng chứng loại trừ SMT hợp lệ
4. Quản lý SMT root - operator-private-channel gọi ResetSmtRoot tự động khi các epoch của cây xoay vòng; kiểm tra verify_smt_exclusion_proof trên chuỗi là hàng phòng thủ cuối cùng chống lại các lệnh rút tiền trái phép
5. Chạy gateway và dịch vụ xác thực - gateway là endpoint công khai duy nhất cho tất cả lưu lượng client; dịch vụ xác thực (tùy chọn) thực thi JWT/RBAC khi JWT_SECRET được thiết lập

Để xem danh sách dịch vụ đầy đủ và phân công cổng, xem Tài liệu tham khảo Cấu hình.

Lưu ý bảo mật: Các cổng write-node và read-node chỉ được liên kết với loopback (127.0.0.1), nhưng một số dịch vụ khác (gateway, auth, operator metrics, Grafana, Prometheus, cAdvisor) được xuất bản tới tất cả giao diện mạng theo mặc định. Xem Tài liệu tham khảo Cấu hình để biết bảng cổng đầy đủ và thiết lập tường lửa trước bất kỳ triển khai công khai nào. RBAC chỉ bảo vệ các phương thức JSON-RPC của gateway, không bảo vệ các dịch vụ khác này.

Kiểm Soát Truy Cập: Mở vs. RBAC

Theo mặc định, gateway chấp nhận tất cả kết nối; không yêu cầu token. Để bật RBAC dựa trên JWT, hãy đặt JWT_SECRET và khởi động stack với --profile auth. Xem Xác Thực & Vai Trò để biết tài liệu tham khảo cấu hình đầy đủ, bao gồm cách cấp phép vai trò operator và đăng ký ví người dùng.

Nếu bật xác thực, hãy thêm các biến này vào môi trường trước khi khởi động stack:

JWT_SECRET=<openssl rand -hex 32>   # must match on gateway and auth service
AUTH_PORT=8903

Thiết Lập Môi Trường

.env.devnet đã được theo dõi trong kho lưu trữ với các giá trị mặc định dành riêng cho devnet đã được điền sẵn; hãy chỉnh sửa trực tiếp thay vì tạo lại từ .env.example, vì điều đó sẽ ghi đè các giá trị mặc định đó.

Điền các giá trị còn lại khi bạn thực hiện các bước triển khai bên dưới; một số chỉ có thể lấy được trong quá trình triển khai. Các bí mật đặt trong file .env đã được gitignore; các biến không phải bí mật đặt trong .env.devnet.

Bí mật - hãy đặt ngay lập tức:

POSTGRES_PASSWORD=<openssl rand -hex 32>
POSTGRES_REPLICATION_PASSWORD=<openssl rand -hex 32>

Các biến thu được trong quá trình triển khai:

ESCROW_INSTANCE_ID=<instance address - from Step 3>
ADMIN_PRIVATE_KEY=<operator keypair as u8 array or base58 - from Step 4>
DEVNET_RPC_URL=https://api.devnet.solana.com
DEVNET_YELLOWSTONE_ENDPOINT=<your Yellowstone gRPC endpoint>
INDEXER_YELLOWSTONE_TOKEN=<your Yellowstone auth token>

Để xem tài liệu tham khảo đầy đủ về biến môi trường, xem Cấu hình.

Triển Khai

make docker-devnet-build

cd admin-ui
pnpm install
echo "PRIVATE_CHANNEL_RPC_URL=http://localhost:8899" > .env
pnpm dev   # opens at http://localhost:5173

cargo run --bin create_instance -- https://api.devnet.solana.com ./keypairs/admin.json

solana-keygen new -o operator-keypair.json -s --no-bip39-passphrase
solana-keygen pubkey operator-keypair.json

make docker-devnet-up

docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet --env-file .env --profile auth up -d

cargo run --bin add_operator -- \
  https://api.devnet.solana.com \
  ./keypairs/admin.json \
  <INSTANCE_ID> \
  <OPERATOR_PUBKEY>

Vận Hành

Các Lệnh Hữu Ích

# View logs (all services)
make docker-devnet-logs

# View logs (specific service)
docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-solana

# Stop services
make docker-devnet-down

# Stop and wipe all state (volumes)
make docker-devnet-clean

Khả Năng Quan Sát

Stack bao gồm Prometheus, Grafana và cAdvisor để theo dõi số liệu và container. Grafana có thể truy cập trên cổng 37429.

Xử Lý Sự Cố

Số dư kênh không cập nhật sau khi gửi tiền

1. Xác nhận giao dịch gửi tiền Mainnet đã được ghi nhận trên Mainnet explorer
2. Xác minh indexer-solana đang chạy: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-solana
3. Xác minh operator-solana đang chạy: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f operator-solana
4. Kiểm tra xem endpoint Yellowstone gRPC của bạn có thể truy cập được và token hợp lệ (DEVNET_YELLOWSTONE_ENDPOINT, INDEXER_YELLOWSTONE_TOKEN)
5. Cho phép tối đa 30 giây sau khi xác nhận trên chuỗi, vì indexer áp dụng độ trễ an toàn tính chung cuộc trước khi ghi nhận tiền

Lệnh rút tiền không quyết toán về Mainnet

1. Xác minh indexer-private-channel đang chạy: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f indexer-private-channel
2. Xác minh operator-private-channel đang chạy: docker compose -f docker-compose.devnet.yml --env-file versions.env --env-file .env.devnet logs -f operator-private-channel
3. Xác nhận keypair operator trong ADMIN_PRIVATE_KEY khớp với khóa đã đăng ký với AddOperator trên chuỗi
4. Nếu log hiển thị "SMT root mismatch", dịch vụ sẽ tắt thay vì gửi bằng chứng không hợp lệ. Dừng stack, khôi phục từ trạng thái nhất quán và khởi động lại

Lỗi xác thực JWT (401 trên tất cả các yêu cầu)

1. Xác nhận JWT_SECRET giống hệt nhau trên cả container gateway và auth service
2. Xác nhận stack được khởi động với --profile auth
3. Token hết hạn sau 24 giờ; hãy xác thực lại để lấy token mới

Lần xây dựng đầu tiên mất quá lâu

Điều này là bình thường. Lần đầu chạy make docker-devnet-build sẽ biên dịch tất cả các dịch vụ Rust và có thể mất 30-60 phút trên phần cứng thông thường. Các lần xây dựng tiếp theo sử dụng bộ đệm layer Docker và nhanh hơn đáng kể.

Các Bước Tiếp Theo