10分钟快速入门

欢迎使用 Zanbara！本指南将帮助您在 10 分钟内快速搭建本地开发环境并运行 Zanbara。

前置要求

在开始之前，请确保您的系统已安装以下工具：

必需工具

工具	版本要求	安装验证
Rust	1.75+	rustc --version
Node.js	18+	node --version
npm/pnpm	9+ / 8+	npm --version 或 pnpm --version
Solana CLI	1.17+	solana --version
Anchor	0.31+	anchor --version
Docker	20+	docker --version
Docker Compose	2.0+	docker-compose --version

可选工具

• PostgreSQL 16+ (或使用 Docker)

• Redis 7+ (或使用 Docker)

• Git 2.30+

安装步骤

1. 克隆项目

git clone https://github.com/your-org/newZanbara.git
cd newZanbara

2. 安装系统依赖

macOS (使用 Homebrew)

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 安装 Solana CLI
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

# 安装 Anchor
cargo install --git https://github.com/coral-xyz/anchor avm --force
avm install 0.31.1
avm use 0.31.1

# 安装 Node.js (如果未安装)
brew install node@18

# 安装 pnpm (推荐)
npm install -g pnpm

# 安装 Docker Desktop
# 请从 https://www.docker.com/products/docker-desktop 下载安装

Linux (Ubuntu/Debian)

# 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# 安装 Solana CLI
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

# 安装 Anchor
cargo install --git https://github.com/coral-xyz/anchor avm --force
avm install 0.31.1
avm use 0.31.1

# 安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

# 安装 pnpm
npm install -g pnpm

# 安装 Docker
sudo apt-get update
sudo apt-get install docker.io docker-compose

3. 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑环境变量
nano .env  # 或使用您喜欢的编辑器

关键环境变量配置

# Solana 配置
SOLANA_RPC_URL=https://api.devnet.solana.com
ANCHOR_PROVIDER_URL=https://api.devnet.solana.com
ANCHOR_WALLET=~/.config/solana/id.json

# 数据库配置
DATABASE_URL=postgresql://zanbara:zanbara_dev_password@localhost:5432/zanbara
REDIS_URL=redis://localhost:6379

# API 配置
API_HOST=0.0.0.0
API_PORT=8080
WEBSOCKET_PORT=8081

# Oracle 配置
PYTH_PROGRAM_ID=gSbePebfvPy7tRqimPoVecS2UsBvYv46ynrzWocc92s

4. 生成 Solana 钱包

# 生成开发钱包
solana-keygen new --outfile ~/.config/solana/devnet-wallet.json

# 设置为默认钱包
solana config set --keypair ~/.config/solana/devnet-wallet.json

# 切换到 Devnet
solana config set --url https://api.devnet.solana.com

# 获取测试 SOL（每次最多 2 SOL）
solana airdrop 2

5. 启动数据库服务

# 使用 Docker Compose 启动 PostgreSQL 和 Redis
./scripts/setup/start-databases.sh

# 或手动启动
docker-compose -f infrastructure/docker/docker-compose.db.yml up -d

# 验证数据库连接
psql -h localhost -U zanbara -d zanbara  # 密码: zanbara_dev_password

6. 运行数据库迁移

# 执行数据库 schema 初始化
./scripts/setup/run-migrations.sh

# 或使用 sqlx
cd backend/matching-engine
sqlx migrate run

启动开发环境

方式 1: 使用 Makefile（推荐）

# 一键启动所有服务
make dev

# 或分步启动
make build-contracts    # 编译智能合约
make build-backend      # 编译后端服务
make dev-frontend       # 启动前端开发服务器

方式 2: 手动启动各个服务

步骤 1: 编译和部署智能合约

cd contracts
anchor build

# 部署到 Devnet
anchor deploy

# 记录 Program ID (需要更新到 .env)
# 示例: Program ID: 8JqL5vKzF9V7YQ8...

步骤 2: 启动后端服务

# 启动 Matching Engine
cd backend/matching-engine
SQLX_OFFLINE=true cargo run --release

# 启动 API Gateway (新终端)
cd backend/api-gateway
SQLX_OFFLINE=true cargo run --release

# 启动 Liquidation Keeper (新终端)
cd backend/keeper
SQLX_OFFLINE=true cargo run --release

# 启动 Oracle Adapter (新终端)
cd backend/oracle-adapter
cargo run --release

步骤 3: 启动前端

cd frontend/trading-interface

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

验证安装

1. 访问前端界面

打开浏览器访问: http://localhost:3000

您应该看到 Zanbara 交易界面。

2. 检查后端服务

# 检查 API Gateway 健康状态
curl http://localhost:8080/health

# 预期响应:
# {"status":"ok","timestamp":1696890000}

# 检查 WebSocket 连接
curl http://localhost:8081/ws/health

3. 测试订单提交

# 使用 curl 提交测试订单
curl -X POST http://localhost:8080/api/v1/orders \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-USDT",
    "side": "buy",
    "price": 50000,
    "quantity": 0.1,
    "order_type": "limit"
  }'

4. 验证智能合约

# 检查程序是否成功部署
solana program show <PROGRAM_ID>

# 检查账户余额
solana balance

常见问题排查

问题 1: Anchor build 失败

# 确保 Anchor 版本正确
anchor --version  # 应该是 0.31.1

# 清理并重新构建
anchor clean
anchor build

问题 2: 数据库连接失败

# 检查数据库是否运行
docker ps | grep postgres

# 重启数据库服务
docker-compose -f infrastructure/docker/docker-compose.db.yml restart

# 检查端口是否被占用
lsof -i :5432

问题 3: 前端启动失败

# 清理依赖
rm -rf node_modules pnpm-lock.yaml
pnpm install

# 检查 Node.js 版本
node --version  # 应该是 18+

# 清理缓存
pnpm store prune

问题 4: Solana 余额不足

# 重新申请 airdrop
solana airdrop 2

# 如果 airdrop 失败，尝试:
# 1. 切换 RPC 端点
solana config set --url https://api.devnet.solana.com

# 2. 使用 Solana Faucet 网页版
# 访问: https://faucet.solana.com/

下一步

恭喜！您已经成功搭建了 Zanbara 开发环境。接下来您可以：

1. 📖 了解核心概念 - 理解永续合约和保证金交易

2. 👨‍💻 查看用户指南 - 学习如何使用 Zanbara 进行交易

3. 🏗️ 阅读架构文档 - 深入了解系统设计

4. 🔧 探索 API 文档 - 开始集成开发

获取帮助

如果您遇到问题，可以通过以下方式获取帮助：

• 💬 Discord 社区

• 📧 GitHub Issues

• 📚 常见问题

• 📖 故障排查指南

---

提示: 建议先在本地 Devnet 环境充分测试后，再考虑部署到生产环境。