⚡ squirrel

下一代 Web3 去中心化交易平台 - 快速、安全、透明

🌟 特性

⚡ 即时合约 - 秒级交易确认
🚀 快速合约 - 智能路由，节省 50% Gas
🌐 多链支持 - Ethereum、BSC、Polygon、Arbitrum、Optimism、Solana
🔐 安全可靠 - 经过审计的智能合约
📱 响应式设计 - 完美适配移动端和桌面端

🚀 快速开始

Docker 部署（推荐）

# 1. 克隆项目
git clone <repository-url>
cd squirrel

# 2. 配置后端环境变量（可选，使用默认配置可跳过）
cp backend/.env.example backend/.env
# 编辑 backend/.env 修改数据库密码等配置

# 3. 启动所有服务（前端 + 后端 + 数据库）
docker compose up -d --build

# 4. 等待数据库就绪
sleep 10

# 5. 运行数据库迁移
docker compose run --rm backend alembic upgrade head

# 6. 验证服务状态
docker compose ps

访问：

前端: http://localhost:3000
数据库: localhost:5432 (用户名: squirrel, 密码: squirrel_password)

本地开发

前端开发

cd frontend
npm install
npm run dev

访问：http://localhost:5173

后端开发

# 启动数据库
docker compose up -d postgres

# 运行迁移
docker compose run --rm backend alembic upgrade head

# 运行测试
docker compose run --rm backend pytest

📋 常用命令

Docker 命令

# 启动所有服务（前端 + 后端 + 数据库）
docker compose up -d --build

# 查看日志
docker compose logs -f

# 查看特定服务日志
docker compose logs -f backend
docker compose logs -f postgres

# 停止服务
docker compose down

# 停止并删除数据卷
docker compose down -v

# 重启服务
docker compose restart

# 查看状态
docker compose ps

前端开发命令

cd frontend

# 启动开发服务器
npm run dev

# 构建生产版本
npm run build

# 代码检查
npm run lint

后端开发命令

# 在 Docker 容器中执行 Python 命令
docker compose run --rm backend python <script.py>

# 进入后端容器 shell
docker compose exec backend bash

# 运行测试
docker compose run --rm backend pytest

# 运行特定测试文件
docker compose run --rm backend pytest tests/test_user_model.py

# 查看测试覆盖率
docker compose run --rm backend pytest --cov=models tests/

数据库迁移命令

# 生成新的迁移脚本（自动检测模型变更）
docker compose run --rm backend alembic revision --autogenerate -m "描述变更内容"

# 应用所有待执行的迁移
docker compose run --rm backend alembic upgrade head

# 回滚到上一个版本
docker compose run --rm backend alembic downgrade -1

# 查看迁移历史
docker compose run --rm backend alembic history

# 查看当前版本
docker compose run --rm backend alembic current

# 回滚到指定版本
docker compose run --rm backend alembic downgrade <revision_id>

# 升级到指定版本
docker compose run --rm backend alembic upgrade <revision_id>

🏗️ 技术栈

前端

框架: React 19 + TypeScript + Vite 7
样式: Tailwind CSS 4
Web3: Ethers.js 6
路由: React Router 7
部署: Docker + Nginx

后端

语言: Python 3.10+
ORM: SQLAlchemy 2.0+ (异步模式)
数据库: PostgreSQL 14+
驱动: asyncpg 0.29+
迁移: Alembic 1.12+
测试: pytest + pytest-asyncio

🗄️ 后端服务

数据库架构

后端使用 PostgreSQL 数据库，包含以下核心模型：

用户模型 (User)

wallet_address: 钱包地址（唯一标识符）
user_level: 用户级别（0 表示新用户不参与分成，1-9 表示参与分成的级别）
referrer_code: 邀请码（支持多级推荐）
created_at / updated_at: 时间戳

级别配置模型 (LevelConfig)

level: 级别编号（0 表示新用户 0% 佣金，1-9 表示参与分成 1%-5%）
commission_rate: 佣金比例（0%-5%）
created_at / updated_at: 时间戳

初始化数据库

首次启动时，需要运行数据库迁移：

# 启动数据库服务
docker compose up -d postgres

# 等待数据库就绪（约 5-10 秒）
sleep 10

# 运行迁移
docker compose run --rm backend alembic upgrade head

数据库管理

# 连接到 PostgreSQL
docker compose exec postgres psql -U squirrel -d squirrel

# 查看所有表
\dt

# 查看用户表结构
\d users

# 查看级别配置表结构
\d level_configs

# 退出
\q

后端测试

# 运行所有测试
docker compose run --rm backend pytest -v

# 运行特定测试
docker compose run --rm backend pytest tests/test_user_model.py -v

# 查看测试覆盖率
docker compose run --rm backend pytest --cov=models --cov-report=html tests/

# 查看覆盖率报告（生成在 htmlcov/ 目录）
open htmlcov/index.html

🌐 支持的网络

网络	Chain ID	符号	状态
Ethereum	0x1	ETH	✅
BSC	0x38	BNB	✅
Polygon	0x89	MATIC	✅
Arbitrum	0xa4b1	ETH	✅
Optimism	0xa	ETH	✅
Solana	-	SOL	🔄
Sepolia	0xaa36a7	ETH	✅

📁 项目结构

squirrel/
├── frontend/              # 前端应用
│   ├── src/
│   │   ├── components/   # 组件
│   │   ├── contexts/     # Context
│   │   ├── hooks/        # Hooks
│   │   ├── pages/        # 页面
│   │   ├── services/     # 服务
│   │   ├── types/        # 类型
│   │   ├── utils/        # 工具
│   │   └── constants/    # 常量
│   ├── Dockerfile        # Docker 配置
│   ├── nginx.conf        # Nginx 配置
│   └── package.json
├── backend/               # 后端应用
│   ├── models/           # ORM 模型
│   │   ├── base.py       # 基础模型类
│   │   ├── user.py       # 用户模型
│   │   └── level_config.py  # 级别配置模型
│   ├── alembic/          # 数据库迁移
│   │   ├── versions/     # 迁移版本
│   │   └── env.py        # Alembic 环境配置
│   ├── tests/            # 测试文件
│   ├── database.py       # 数据库配置
│   ├── alembic.ini       # Alembic 配置
│   ├── requirements.txt  # Python 依赖
│   ├── Dockerfile        # Docker 配置
│   └── .env.example      # 环境变量示例
├── token-vault/          # 智能合约
│   ├── contracts/        # Solidity 合约
│   ├── scripts/          # 部署脚本
│   └── test/             # 合约测试
├── docker-compose.yml    # Docker Compose
└── README.md

🔧 生产环境部署

使用自定义端口

编辑 docker-compose.yml：

services:
  frontend:
    ports:
      - "8080:80"  # 改为你想要的端口

配置 HTTPS（使用 Nginx 反向代理）

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

环境变量配置

前端环境变量

编辑 frontend/.env.production：

VITE_APP_NAME=squirrel
VITE_APP_VERSION=2.0.0
VITE_API_URL=https://api.your-domain.com

后端环境变量

复制并编辑 backend/.env（基于 backend/.env.example）：

# 数据库配置
DATABASE_URL=postgresql+asyncpg://squirrel:your_password@postgres:5432/squirrel

# 数据库连接池配置
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10
DB_POOL_PRE_PING=true

# 开发环境配置
ENVIRONMENT=development
DEBUG=true
SQL_ECHO=true

# 生产环境配置（生产环境使用）
# ENVIRONMENT=production
# DEBUG=false
# SQL_ECHO=false

重要提示：

生产环境请修改默认密码
不要将 .env 文件提交到版本控制系统
使用强密码保护数据库

🐛 故障排查

端口被占用

# 查看占用端口的进程
lsof -i :3000

# 或修改 docker-compose.yml 中的端口

构建失败

# 清理缓存重新构建
docker compose build --no-cache

容器无法启动

# 查看详细日志
docker compose logs frontend

# 检查 nginx 配置
docker compose exec frontend nginx -t

页面无法访问

# 检查容器状态
docker compose ps

# 检查健康状态
curl http://localhost:3000/health

数据库连接问题

# 检查 PostgreSQL 容器状态
docker compose ps postgres

# 查看数据库日志
docker compose logs postgres

# 测试数据库连接
docker compose exec postgres pg_isready -U squirrel

# 检查后端环境变量
docker compose exec backend env | grep DATABASE_URL

迁移失败

# 查看当前迁移状态
docker compose run --rm backend alembic current

# 查看迁移历史
docker compose run --rm backend alembic history

# 如果迁移卡住，可以手动标记版本
docker compose run --rm backend alembic stamp head

# 重置数据库（警告：会删除所有数据）
docker compose down -v
docker compose up -d postgres
sleep 10
docker compose run --rm backend alembic upgrade head

测试失败

# 查看详细测试输出
docker compose run --rm backend pytest -vv

# 运行单个测试并显示打印输出
docker compose run --rm backend pytest tests/test_user_model.py -s

# 进入容器调试
docker compose run --rm backend bash

🔄 更新部署

# 拉取最新代码
git pull

# 重新构建并启动
docker compose down
docker compose up -d --build

# 运行数据库迁移（如果有新的迁移）
docker compose run --rm backend alembic upgrade head

🤝 贡献

欢迎贡献！

Fork 项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📝 许可证

本项目采用 MIT 许可证

🗺️ 路线图

v2.0.0 ✅ 多链支持、余额管理、Web3 UI、Docker 部署
v2.1.0 ✅ 后端用户系统、PostgreSQL 数据库、用户级别管理、邀请关系追踪
v2.2.0 🔄 交易历史 API、代币管理、Gas 预估
v2.3.0 📋 即时合约功能增强、跨链桥接

Built with ❤️ for Web3 Community

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
admin-frontend		admin-frontend
backend		backend
trading_bot		trading_bot
.gitignore		.gitignore
README.md		README.md
docker-compose.yml		docker-compose.yml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation