项目概述

Spark是一个基于Solana区块链的SPARK代币交易和管理平台，提供完整的用户管理、节点质押、代币交易、收益分配和管理后台功能。

该平台采用中心化架构设计，通过智能合约和自动化执行器实现代币的发行、交易、质押和分红等核心功能，为用户提供安全可靠的数字资产管理服务。

核心功能

  • 用户管理: 支持4种用户类型（项目方、普通用户、大节点、小节点）
  • 推荐系统: 完整的推荐关系管理和奖励计算
  • 节点质押: 大节点和小节点的质押管理
  • 代币交易: SPARK代币的挂单、接单、交易验证
  • 收益分配: 每日收益计算、社区奖励、推荐奖励
  • 管理后台: 完整的Web管理界面
  • 交易执行: 自动化的交易执行器
  • 费用监控: 钱包交易监控和自动转账

技术栈

  • 后端: FastAPI + PostgreSQL + SQLAlchemy
  • 前端: Vue3 + TypeScript + Vite
  • 区块链: Solana主网
  • 执行器: Python + Solana SDK
  • 监控: Python + Telegram Bot

系统架构

整个系统采用分层架构设计，各组件之间通过API接口进行通信，确保系统的可扩展性和维护性。

系统架构图展示了从用户界面到区块链网络的完整数据流：

  • Vue3管理前端负责用户交互和数据显示
  • FastAPI后端提供RESTful API接口
  • PostgreSQL数据库存储用户数据和交易记录
  • 交易执行器负责与Solana区块链交互
  • 费用监控系统确保资金安全

目录结构

项目采用模块化设计，每个功能模块独立开发，便于维护和扩展。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

spark/
├── backend/                    # 后端API系统
│   ├── src/                   # 源代码
│   │   ├── main.py           # 应用入口
│   │   ├── api.py            # API路由
│   │   ├── crud.py           # 数据库操作
│   │   ├── models.py         # 数据模型
│   │   ├── validators.py     # 交易验证器
│   │   └── config.py         # 配置管理
│   ├── config/               # 配置文件
│   │   └── config.toml       # 主配置文件
│   └── scripts/              # 维护脚本
├── ledger/                   # 账本系统
│   ├── manage/              # Vue3管理前端
│   │   ├── src/             # 前端源码
│   │   └── package.json     # 依赖配置
│   ├── sql/                 # 数据库脚本
│   └── dividend/            # 分红脚本
├── executor/                # 交易执行器
│   ├── trade_executor.py    # 交易执行
│   ├── redeem_executor.py   # 赎回执行
│   ├── withdraw_executor.py # 提现执行
│   ├── solana_client.py     # Solana客户端
│   └── config.toml          # 执行器配置
├── fee/                     # 费用监控系统
│   ├── fee.py              # 监控主程序
│   ├── transactions.db      # 交易数据库
│   └── monitor.log         # 监控日志
└── .gitignore              # Git忽略文件

核心组件

后端系统 (backend/)

后端系统基于FastAPI框架构建，提供RESTful API接口，负责用户管理、交易处理、数据验证等核心业务逻辑。

主要文件

  • main.py: FastAPI应用入口，中间件配置，路由注册
  • api.py: API接口定义，用户管理、交易、质押接口
  • crud.py: 数据库CRUD操作，用户管理、交易记录
  • validators.py: 交易验证器，质押验证、交易验证
  • config.py: 配置管理，TOML配置文件读取

配置系统 (config.toml)

系统配置采用TOML格式，支持分层配置和动态加载。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

[database]
url = "postgresql://spark:spark_2024@172.16.3.1:5432/spark"
pool_size = 10
max_overflow = 20

[api]
v1_str = "/v1"
project_name = "Spark Backend API"

[server]
host = "0.0.0.0"
port = 9999

[project]
owner_address = "AT8NgrFgtaHR3Pa4rc1pbqG8jWvLwsGjk6tf8jmqPTfz"

[addresses]
stake = "LWkEoQahcRakgsd6s9xB59pGxgXp59WeSpCTZXmdyw6"
trade = "LWkEoQahcRakgsd6s9xB59pGxgXp59WeSpCTZXmdyw6"

[token]
spark_mint = "56of6SDQ8p5ppGGemHRfw2aRsZkwL9UPQGGmqUQiYo6g"

[nodes]
max_major_nodes = 100
max_minor_nodes = 500

[solana]
rpc_url = "https://solana-mainnet.core.chainstack.com/b7269d5dff9f0a3ad823e849e097c2a6"
max_poll_attempts = 30
poll_interval = 2

前端管理系统 (ledger/manage/)

前端系统基于Vue3和TypeScript构建，提供现代化的用户界面和管理功能。

技术栈

  • 框架: Vue 3 + TypeScript
  • 构建工具: Vite
  • 路由: Vue Router 4
  • HTTP客户端: Axios
  • 图表: D3.js

页面组件

  • LoginView.vue: 管理员登录页面
  • SubtreeView.vue: 推荐关系树状图
  • DailyReportView.vue: 每日收益报告
  • SparkPriceView.vue: SPARK价格管理
  • AnnouncementView.vue: 公告管理
  • DiagnosticsView.vue: 系统诊断
  • RootsView.vue: 根节点管理

交易执行器 (executor/)

交易执行器负责与Solana区块链交互，执行代币交易、质押、赎回等操作。

主要组件

  • solana_client.py: Solana RPC客户端，交易构建
  • trade_executor.py: 交易执行，订单匹配
  • redeem_executor.py: 赎回执行，代币转账
  • withdraw_executor.py: 提现执行，SOL转账

配置 (config.toml)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

[database]
url = "postgresql://spark:spark_2024@172.16.3.1:5432/spark"

[solana]
rpc_url = "https://solana-mainnet.core.chainstack.com/b7269d5dff9f0a3ad823e849e097c2a6"

[addresses]
stake = "CCrTZVZUq1zcUuu7BUC6xRGt2J881QDgHsp1MtgNQngN"
trade = "31JLn2VNMMJj1VdpYR9vKRi2JJLZPZUwyHGahi9ndggj"
fee = "42KBY2Tw3B8Ug3QBBTfZAB2MgXC5bS2ugAFNB3zbsnnW"
dividend = "HzN2H7FwU5yTYZ7PtZsANGy4rkGhq9bocPN94XUbEBo7"

[executor]
dry_run = true
loop_interval_seconds = 5

费用监控系统 (fee/)

费用监控系统负责监控指定钱包的交易，确保资金安全和自动化管理。

功能特性

  • 钱包监控: 监控指定钱包的交易
  • 自动转账: 检测到进账后自动转出
  • Telegram通知: 实时交易通知
  • 日志记录: 详细的交易日志

主要文件

  • fee.py: 监控主程序，交易监控逻辑
  • transactions.db: SQLite交易数据库
  • monitor.log: 监控日志

数据库设计

数据库采用PostgreSQL，设计了完整的表结构来支持用户管理、交易记录、收益分配等功能。

核心表结构

1. users - 用户表

用户表存储所有用户的基本信息和资产状态。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

CREATE TABLE public.users (
    address bytea PRIMARY KEY,           -- 钱包地址（二进制）
    asset_type smallint NOT NULL,        -- 资产类型 (0=项目方, 1=普通用户, 2=大节点, 3=小节点)
    created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,

    -- 扩展字段
    node_stake_spark float NOT NULL DEFAULT 0.0,    -- 节点质押SPARK数量
    normal_stake_spark float NOT NULL DEFAULT 0.0,  -- 普通质押SPARK数量
    self_power_spark float NOT NULL DEFAULT 0.0,    -- 自算力SPARK（自动计算）
    withdrawable_spark float NOT NULL DEFAULT 0.0,  -- 可提取SPARK数量
    withdraw_frozen boolean NOT NULL DEFAULT false, -- 提取冻结标志
    earning_frozen boolean NOT NULL DEFAULT false,  -- 收益冻结标志
    redeem_frozen boolean NOT NULL DEFAULT false,   -- 赎回冻结标志
    sell_freeze boolean NOT NULL DEFAULT false      -- 挂卖冻结标志
);

2. user_relation - 推荐关系表

推荐关系表记录用户之间的推荐关系，支持多级推荐奖励计算。

1
2
3
4
5

CREATE TABLE public.user_relation (
    referred bytea PRIMARY KEY,           -- 被推荐人钱包地址（二进制）
    referrer bytea NOT NULL,              -- 推荐人钱包地址（二进制）
    created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP
);

3. node - 节点表

节点表记录用户的节点质押信息，包括大节点和小节点。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

CREATE TABLE public.node (
    tx_hash bytea PRIMARY KEY,            -- 交易哈希作为主键
    address bytea NOT NULL,               -- 钱包地址
    type smallint NOT NULL,               -- 节点类型（1=大节点，2=小节点）
    validated smallint NOT NULL DEFAULT 0, -- 交易状态（-1=失败，0=待验证，1=成功）
    tx_num float NOT NULL DEFAULT 0,      -- 交易数量
    created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
    verified_at timestamp with time zone, -- 验证时间
    updated_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP
);

4. spark_order - SPARK交易订单表

交易订单表记录SPARK代币的买卖订单信息。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

CREATE TABLE public.spark_order (
    id bigint PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    seller_address bytea NOT NULL,        -- 卖家地址
    posted_spark numeric(38,6) NOT NULL,  -- 挂单SPARK数量
    sellable_spark numeric(38,6) NOT NULL, -- 可卖SPARK数量
    burn_spark numeric(38,6) NOT NULL,    -- 销毁SPARK数量
    dividend_spark numeric(38,6) NOT NULL, -- 分红SPARK数量
    seller_deposit_tx text,               -- 卖家存款交易哈希
    status smallint NOT NULL DEFAULT 1,   -- 订单状态
    created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
    updated_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
    posted_verified_at timestamp with time zone -- 挂单验证时间
);

5. earnings_daily - 每日收益表

每日收益表记录用户每天的收益分配情况。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

CREATE TABLE public.earnings_daily (
    earn_date date NOT NULL,              -- 收益日期
    address bytea NOT NULL,               -- 用户地址
    pledge_power numeric(38,6) DEFAULT 0, -- 质押算力
    minor_power numeric(38,6) DEFAULT 0,  -- 小节点算力
    big_area_power numeric(38,6) DEFAULT 0, -- 大区算力
    community_power numeric(38,6) DEFAULT 0, -- 社区算力
    base_spark numeric(38,6) DEFAULT 0,   -- 基础SPARK
    minor_spark numeric(38,6) DEFAULT 0,  -- 小节点SPARK
    big_area_spark numeric(38,6) DEFAULT 0, -- 大区SPARK
    community_spark numeric(38,6) DEFAULT 0, -- 社区SPARK
    total_spark numeric(38,6) DEFAULT 0,  -- 总SPARK
    created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (earn_date, address)
);

API接口

系统提供完整的RESTful API接口，支持用户管理、交易操作、质押管理等核心功能。

主要端点

用户管理接口

  • GET /v1/users - 获取用户列表
  • POST /v1/relationship - 绑定推荐关系
  • GET /v1/relationship - 获取推荐关系

交易接口

  • POST /v1/spark/sell - 挂卖SPARK
  • POST /v1/spark/take - 接单购买
  • GET /v1/spark/orders - 获取订单列表
  • GET /v1/spark/sell_orders - 获取挂单列表

质押接口

  • POST /v1/stake - 质押操作
  • POST /v1/redeem - 赎回操作
  • GET /v1/stake_records - 获取质押记录

管理后台接口

  • POST /_admin/login - 管理员登录
  • POST /_admin/spark_price - 设置SPARK价格
  • POST /_admin/daily_settlement - 每日结算
  • GET /_admin/subtree - 获取推荐关系树

响应格式

所有API接口采用统一的响应格式，便于前端处理。

1
2
3
4
5

{
  "code": 1,        // 1=成功, 0=失败
  "msg": "消息",     // 响应消息
  "data": {}        // 响应数据
}

部署指南

系统支持在Linux环境下部署，包括Ubuntu和Arch Linux等发行版。

环境要求

  • 操作系统: Linux (Ubuntu 20.04+ 或 Arch Linux)
  • Python: 3.8+
  • Node.js: 16+
  • PostgreSQL: 12+
  • Solana CLI: 最新版本

1. 系统准备

首先更新系统并安装基础工具。

1
2
3
4
5
6
7

# 更新系统
sudo pacman -Syu  # Arch Linux
# 或
sudo apt update && sudo apt upgrade  # Ubuntu

# 安装基础工具
sudo pacman -S git curl wget vim htop

2. 安装Python环境

安装Python和必要的依赖包。

1
2
3
4
5
6
7
8
9

# 安装Python
sudo pacman -S python python-pip

# 创建虚拟环境
python -m venv spark_env
source spark_env/bin/activate

# 安装依赖
pip install -r backend/src/requirements.txt

3. 安装Node.js

安装Node.js用于前端开发。

1
2
3
4
5
6

# 安装Node.js
sudo pacman -S nodejs npm

# 验证安装
node --version
npm --version

4. 安装PostgreSQL

安装和配置PostgreSQL数据库。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 安装PostgreSQL
sudo pacman -S postgresql

# 初始化数据库
sudo -u postgres initdb -D /var/lib/postgres/data

# 启动服务
sudo systemctl enable postgresql
sudo systemctl start postgresql

# 创建数据库和用户
sudo -u postgres psql
CREATE DATABASE spark;
CREATE USER spark WITH PASSWORD 'spark_2024';
GRANT ALL PRIVILEGES ON DATABASE spark TO spark;
\q

5. 安装Solana CLI

安装Solana命令行工具。

1
2
3
4
5
6
7
8

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

# 添加到PATH
export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"

# 验证安装
solana --version

6. 配置项目

克隆项目并配置相关设置。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 克隆项目
git clone <repository_url>
cd spark

# 配置后端
cp backend/config/config.toml.example backend/config/config.toml
vim backend/config/config.toml

# 配置执行器
cp executor/config.toml.example executor/config.toml
vim executor/config.toml

7. 初始化数据库

执行数据库初始化脚本。

1
2
3

# 执行数据库初始化脚本
cd ledger/sql
psql -h localhost -U spark -d spark -f 819.sql

8. 启动服务

启动各个服务组件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 启动后端服务
cd backend/src
python main.py

# 启动前端开发服务器
cd ledger/manage
npm install
npm run dev

# 启动执行器（可选）
cd executor
python trade_executor.py
python redeem_executor.py
python withdraw_executor.py

使用说明

系统提供完整的管理员和用户操作界面，支持各种业务场景。

1. 管理员操作

登录管理后台

  1. 访问前端管理界面
  2. 使用管理员账号登录：
    • 用户名: `spark@hk`
    • 密码: `spark_2025@hk`

设置SPARK价格

  1. 进入"价格管理"页面
  2. 输入新的SPARK价格
  3. 点击"设置价格"

发布公告

  1. 进入"公告管理"页面
  2. 输入公告内容
  3. 点击"发布公告"

查看推荐关系

  1. 进入"推荐关系"页面
  2. 查看用户推荐树状图
  3. 点击节点查看详细信息

每日结算

  1. 进入"每日报告"页面
  2. 点击"执行结算"
  3. 等待结算完成

2. 用户操作

质押SPARK

  1. 将SPARK转入质押地址
  2. 等待验证器确认
  3. 查看质押状态

挂卖SPARK

  1. 调用 `/v1/spark/sell` API
  2. 将SPARK转入交易地址
  3. 等待验证器确认

购买SPARK

  1. 调用 `/v1/spark/take` API
  2. 支付相应SOL
  3. 等待交易完成

查看收益

  1. 调用 `/v1/earnings` API
  2. 查看每日收益详情
  3. 查看可提取余额

3. 分红发放

使用分红脚本

分红脚本支持自动查找和处理分红文件。

1
2
3
4
5
6
7
8

# 进入分红目录
cd ledger/dividend

# 自动查找今天的CSV文件
./transfer_dividend.sh

# 或手动指定文件
./transfer_dividend.sh dividends_20250828_103388.7.csv

操作选项

  • `y` - 转账当前节点
  • `g` - 批量转账同类型节点
  • `a` - 转账当前节点并自动处理剩余所有节点
  • `n` - 跳过当前节点

4. 监控系统

费用监控

启动费用监控系统。

1
2
3

# 启动费用监控
cd fee
python fee.py

查看日志

查看各个组件的运行日志。

1
2
3
4
5
6
7
8

# 查看后端日志
tail -f backend/logs/app.log

# 查看监控日志
tail -f fee/monitor.log

# 查看执行器日志
tail -f executor/*.log

维护和监控

系统提供完整的维护和监控功能，确保稳定运行。

1. 日常维护

数据库备份

定期备份数据库，防止数据丢失。

1
2
3
4
5
6

# 使用备份脚本
cd backend/scripts
./backup_db.py

# 或手动备份
pg_dump -h localhost -U spark spark > backup_$(date +%Y%m%d_%H%M%S).sql

日志清理

清理旧的日志文件，释放磁盘空间。

1
2
3

# 清理旧日志
find backend/logs -name "*.log" -mtime +30 -delete
find fee -name "*.log" -mtime +7 -delete

系统监控

监控系统运行状态和资源使用情况。

1
2
3
4
5
6
7
8
9

# 检查服务状态
systemctl status postgresql
ps aux | grep python

# 检查磁盘空间
df -h

# 检查内存使用
free -h

2. 性能优化

数据库优化

优化数据库性能，提高查询效率。

1
2
3
4
5
6
7

-- 分析表统计信息
ANALYZE users;
ANALYZE user_relation;
ANALYZE node;

-- 重建索引
REINDEX INDEX idx_users_asset_type;

应用优化

  • 调整数据库连接池大小
  • 优化查询语句
  • 添加缓存机制

3. 安全维护

定期更新

保持系统和依赖包的最新版本。

1
2
3
4
5
6
7
8
9

# 更新系统包
sudo pacman -Syu

# 更新Python依赖
pip install --upgrade -r backend/src/requirements.txt

# 更新Node.js依赖
cd ledger/manage
npm update

安全检查

  • 定期检查日志中的异常
  • 监控异常访问
  • 更新密钥和证书

故障排除

提供常见问题的解决方案和故障排除指南。

1. 常见问题

数据库连接失败

检查PostgreSQL服务状态和连接配置。

1
2
3
4
5
6
7
8

# 检查PostgreSQL服务状态
sudo systemctl status postgresql

# 检查连接配置
vim backend/config/config.toml

# 测试连接
psql -h localhost -U spark -d spark

API服务无法启动

检查端口占用和依赖安装情况。

1
2
3
4
5
6
7
8

# 检查端口占用
netstat -tlnp | grep 9999

# 检查日志
tail -f backend/logs/app.log

# 检查依赖
pip list | grep fastapi

前端无法访问

检查Node.js服务和端口配置。

1
2
3
4
5
6
7
8
9

# 检查Node.js服务
cd ledger/manage
npm run dev

# 检查端口占用
netstat -tlnp | grep 5173

# 检查构建
npm run build

Solana交易失败

检查Solana CLI配置和网络连接。

1
2
3
4
5
6
7
8

# 检查Solana CLI配置
solana config get

# 检查RPC连接
solana cluster-version

# 检查账户余额
solana balance

2. 日志分析

后端日志

分析后端服务的运行日志。

1
2
3
4
5
6
7
8

# 查看错误日志
grep ERROR backend/logs/app.log

# 查看API访问日志
grep "API Request" backend/logs/app.log

# 查看交易验证日志
grep "validator" backend/logs/app.log

监控日志

分析监控系统的运行日志。

1
2
3
4
5

# 查看交易监控日志
tail -f fee/monitor.log

# 查看Telegram通知日志
grep "Telegram" fee/monitor.log

3. 恢复操作

数据库恢复

从备份文件恢复数据库。

1
2
3
4

# 从备份恢复
psql -h localhost -U spark -d postgres -c "DROP DATABASE IF EXISTS spark;"
psql -h localhost -U spark -d postgres -c "CREATE DATABASE spark;"
psql -h localhost -U spark -d spark < backup_20250828_143000.sql

服务重启

重启所有服务组件。

1
2
3
4
5
6

# 重启所有服务
sudo systemctl restart postgresql
cd backend/src && python main.py &
cd ledger/manage && npm run dev &
cd executor && python trade_executor.py &
cd fee && python fee.py &

联系信息

  • 项目维护者: Spark开发团队
  • 技术支持: 通过GitHub Issues
  • 文档更新: 定期更新README.org

最后更新时间: 2025-08-28