Aurora

基于区块链的数字系统套件，支持抽奖、投票、预言机、NFT 和代币。采用 DDD (领域驱动设计) 架构。

功能

🎲 VRF 透明抽奖

• 基于 VRF（可验证随机函数）的抽奖
• 结果上链存证，可验证
• CLI 和 TUI 界面

🗳️ 透明投票系统

• Ed25519 签名验证
• 区块链存证
• 实时计票

🔮 数据预言机

• 通用 HTTP API 数据获取
• 预设模板（BTC/ETH 价格）
• 数据上链存证

🖼️ NFT 系统

• Ed25519 签名转移
• 铸造、转让、查询
• 区块链存证

🪙 FT 代币系统

• ERC-20 风格 Fungible Token
• Mint、Transfer、Burn、Approve
• 完整余额和授权管理

快速开始

安装

# 下载 releases 或编译
go build -o aurora ./cmd/aurora

使用 justfile

just test          # 运行测试
just build        # 构建所有平台
just api          # 构建独立 Web / API 服务器（./aurora-api）
just lint         # 代码检查
just dev          # Docker 开发

CLI 示例

# 抽奖
./aurora lottery create -p "A,B,C,D" -s "seed" -c 3
./aurora lottery history
./aurora lottery stats            # 统计信息
./aurora lottery verify <id或高度> # 验证某次抽奖
./aurora lottery export file.json # 导出记录
./aurora lottery import file.json # 导入记录
./aurora lottery tui
./aurora lottery db-info          # 数据库信息
./aurora lottery reset --confirm  # 清空抽奖记录（需 --confirm）

# 投票
./aurora voting candidate add -n "Name" -p "Party" -m "Program"
./aurora voting voter register -n "Name"
./aurora voting voter list                          # 列出已注册投票者及投票状态
./aurora voting session create -t "Proposal" -d "Desc" -c <cand-id> --start-time <t> --end-time <t>
./aurora voting vote -v <voter-pk> -c <candidate-id> -s <session-id> -k <priv-key>
./aurora voting results -s <session-id>

# 预言机
./aurora oracle source list
./aurora oracle source add --name "btc" --url "https://api.example.com/price" \
                           --path "data.price" --interval 60   # -t/--type、--method/--path/--interval 可选
./aurora oracle source enable --id <source-id>
./aurora oracle source disable --id <source-id>
./aurora oracle source delete --id <source-id> --confirm   # 需 --confirm
./aurora oracle template list
./aurora oracle template add -t <template-name>            # 从预设模板建源
./aurora oracle fetch -i <source-id>            # -i/--id（旧拼写 -s 仍可用）
./aurora oracle data -i <source-id> --limit 10
./aurora oracle latest -i <source-id>
./aurora oracle tui

# NFT
./aurora nft mint -n "My NFT" -d "Description" -c "<creator-pub>" --image <url> -t <token-uri>   # image/uri 可选
./aurora nft transfer --nft <id> --from <owner> --to <to> -k <priv>
./aurora nft get --nft <nft_id>
./aurora nft list --owner <pubkey>
./aurora nft history --nft <nft_id>
./aurora nft burn --nft <nft_id> --owner <pub> -k <priv> --confirm   # 需 --confirm
./aurora nft tui

# Token
./aurora token create -n "MyToken" -s "SYMBOL" --supply 1000000 -d 8   # -d/--decimals，默认 8
./aurora token info -t <token-id>
./aurora token mint -t <token-id> --to <address> --amount 100 -k <priv>
./aurora token transfer -t <token-id> --from <addr> --to <address> --amount 50 -k <priv>
./aurora token balance -t <token-id> --owner <address>
./aurora token history -t <token-id> --owner <address> --limit 50 --offset 0   # 分页
./aurora token approve -t <token-id> --owner <pub> -s <spender-pub> -a <amount> -k <priv>
./aurora token allowance -t <token-id> -o <pub> -s <spender-pub>
./aurora token transfer-from -t <token-id> -o <pub> -s <spender-pub> --to <recipient> -a <amount> -k <spender-priv>
./aurora token burn -t <token-id> --from <pub> -a <amount> -k <priv> --confirm   # 需 --confirm
./aurora token tui

破坏性操作确认门： token burn、nft burn、oracle source delete、 migrate down、backup restore、lottery reset 全部接受 -y/--confirm； lottery reset 也接受旧写法的 --yes。没有确认标志这些命令会直接拒绝执行 （非零退出码），防止误删数据。

运维命令

./aurora version                     # 显示版本与构建信息

# 数据库备份（备份目录含元数据，可校验）
./aurora backup create ./backups/backup-$(date +%Y%m%d)
./aurora backup verify ./backups/backup-$(date +%Y%m%d)
./aurora backup restore ./backups/backup-$(date +%Y%m%d) --confirm   # 覆盖当前库

# 数据库迁移
./aurora migrate status             # 当前 / 已应用 / 待应用
./aurora migrate up                 # 应用全部待迁移
./aurora migrate up 2               # 应用接下来两步（up N 应用 N 步待迁移）
./aurora migrate down --confirm     # 回滚一步（默认 1，需 --confirm）

Web / API 界面

Aurora 提供内置的 REST API 与 Web 界面，由独立的 cmd/api 二进制启动 （./aurora 是纯 CLI/TUI，不带 HTTP 服务）。Web 页面由 API 服务托管在 web/ 目录（默认相对当前工作目录；若非从仓库根目录启动，可在 [server] 配置 webRoot = "/path/to/web" 指定实际路径，TASK-181）。

just api                      # 或 go build -o aurora-api ./cmd/api
./aurora-api --help           # 查看启动参数；--version 查看构建版本
AURORA_API_KEY="your-strong-key" ./aurora-api
# 默认监听 0.0.0.0:8080；然后浏览器访问 http://localhost:8080

监听地址的优先级链是 flag > 环境变量 > 配置文件 > 默认，任一层都 可覆盖默认的 0.0.0.0:8080：

./aurora-api --host 127.0.0.1 --port 9090   # 命令行覆盖（-H / -p 短别名）
AURORA_SERVER_HOST=127.0.0.1 AURORA_SERVER_PORT=9090 ./aurora-api  # 环境变量
# 或 config/aurora.toml 的 [server].host / [server].port（TASK-273, ISS-269）

aurora-api 支持最小参数面：--help/-h 打印用法， --version/-v 打印构建标识（版本、构建时间、Go 工具链， 由 just api 注入真实的 git 引用），-H/--host 与 -p/--port 覆盖监听地址（端口范围 1-65535，越界在启动前即拒绝），未知参数会在 启动服务器前直接拒绝并提示用法（TASK-267）。

• 鉴权：API 通过 X-API-Key 请求头校验密钥。密钥来自 AURORA_API_KEY 环境变量或配置项 api.key；开发模式下未设置时会生成 一个随机密钥并在启动日志打印。Web 页面会自动把密钥注入 window.AURORA_API_KEY，同源浏览器请求无需手动带 key。
• 端到端：API 服务同时启动预言机定时调度器（按源的 interval 拉取）与 审计事件 outbox 补偿循环，SIGINT/SIGTERM 优雅停机（15s 超时）。
• 可观测：/metrics（Prometheus 文本）暴露请求计数器与按模块计数； /metrics/oracle 暴露各预言机源的抓取健康统计。
• 安全：API 支持请求体大小上限（4 MiB）、速率限制（按客户端）、CORS 白名单，生产环境拒绝弱 API key（ErrInsecureAPIKey）。Web 页面响应带 严格的 nonce 化 Content-Security-Policy（connect-src 'self' / script-src 'self' 'nonce-…'），内嵌的 window.AURORA_API_KEY 只以带 nonce 的 bootstrap 脚本执行——即使注入脚本也无法外联或远程加载， 防止 key 被 XSS 外带（round-151）。

项目结构 (DDD 架构)

cmd/aurora/              # CLI 入口
cmd/api/                 # REST API + Web 服务入口（go build ./cmd/api）
web/                     # Web 前端（HTML + Alpine.js，由 cmd/api 托管）
internal/
├── domain/               # 领域层 - 实体、服务、仓储接口
│   ├── blockchain/       # 区块链核心 (Block, BlockChain)
│   ├── lottery/         # 抽奖领域 (LotteryRecord, VRF Service)
│   ├── voting/          # 投票领域 (Vote, Voter, Candidate)
│   ├── nft/             # NFT 领域 (NFT, Operation)
│   ├── token/           # 代币领域 (Token, Amount, Approval)
│   └── oracle/          # 预言机领域 (OracleData, DataSource)
│
├── infra/               # 基础设施层 - 存储实现
│   ├── sqlite/          # SQLite 持久化
│   └── http/            # HTTP 客户端
│
├── app/                 # 应用层 - 用例
│   ├── lottery/         # CreateLotteryUseCase
│   ├── voting/          # CastVoteUseCase, RegisterVoterUseCase
│   ├── nft/            # MintNFTUseCase, TransferNFTUseCase
│   ├── token/          # CreateTokenUseCase, MintTokenUseCase
│   └── oracle/          # FetchDataUseCase
│
├── ui/                  # 表示层 - TUI 界面
│   ├── lottery/
│   ├── nft/
│   ├── token/
│   └── oracle/
│
├── i18n/                # 国际化
├── logger/               # 日志
└── utils/                # 工具
e2e/                     # E2E 测试
.github/workflows/        # CI/CD

DDD 分层说明

层	职责	示例
domain	核心业务逻辑、实体、领域服务、仓储接口	LotteryRecord, VRFService, Repository 接口
app	用例编排、DTO 转换	CreateLotteryUseCase
infra	外部依赖实现	SQLiteRepository, HTTPFetcher
ui	用户界面	Bubble Tea TUI

技术栈

• Go 1.26+
• Cobra (CLI)
• Viper (配置)
• Zerolog (日志)
• Ed25519 (签名)
• Bubble Tea v2 (TUI)
• SQLite (持久化)

开发

# 测试
go test ./...           # 所有测试
go test ./... -cover   # 带覆盖率

# 代码检查
go vet ./...
golangci-lint run ./...

# 构建
just build
go build -o aurora ./cmd/aurora

# Docker
just dev      # 构建并启动（CLI 工具箱容器，见 compose.yml 说明）
just start    # 启动容器
just stop     # 停止容器

Docker 镜像只包含 CLI（cmd/aurora），没有 HTTP 监听器；Web UI 由独立的 cmd/api 二进制提供（见上），不包含在镜像中，因此 compose/k8s 清单没有端口 映射——用 docker compose run --rm aurora <命令> 执行一次性 CLI 任务。

测试覆盖率

模块	Domain	App
Lottery	92.8%	85.7%
Voting	87.5%	87.8%
NFT	90.3%	89.2%
Token	91.1%	91.8%
Oracle	89.3%	88.9%
SQLite	-	85.0%

覆盖率为 go test -cover 实测（2026-08-29，-count=1）。

贡献

欢迎提交 Issue 和 PR！

许可证

MIT