liuyu/nofx
1
0
Fork 0
mirror of https://github.com/NoFxAiOS/nofx.git synced 2026-06-06 05:51:19 +08:00
Code Issues Packages Projects Releases Wiki Activity

Feat: Update docs

Browse Source 
- 重构文档结构
- 更新文档内容
- 制定roadmap
- 提供中/EN 双语文档
This commit is contained in:
zbhan
2025-11-01 15:05:24 -04:00
parent ba35d29eee
commit fcacfbd79d
36 changed files with 5756 additions and 1149 deletions
Download Patch File Download Diff File Expand all files Collapse all files

242
docs/MIGRATION_GUIDE.md Normal file
View File

@@ -0,0 +1,242 @@
# 📦 Documentation Migration Guide
## What Changed?
NOFX documentation has been reorganized into a structured `docs/` directory for better organization and navigation.
## 🗺️ File Locations (Old → New)
### Deployment Guides
- `DOCKER_DEPLOY.en.md` → `docs/getting-started/docker-deploy.en.md`
- `DOCKER_DEPLOY.md` → `docs/getting-started/docker-deploy.zh-CN.md`
- `PM2_DEPLOYMENT.md` → `docs/getting-started/pm2-deploy.md`
- `CUSTOM_API.md` → `docs/getting-started/custom-api.md`
### Community Docs
- `HOW_TO_POST_BOUNTY.md` → `docs/community/bounty-guide.md`
- `INTEGRATION_BOUNTY_HYPERLIQUID.md` → `docs/community/bounty-hyperliquid.md`
- `INTEGRATION_BOUNTY_ASTER.md` → `docs/community/bounty-aster.md`
### Internationalization
- `README.zh-CN.md` → `docs/i18n/zh-CN/README.md`
- `README.ru.md` → `docs/i18n/ru/README.md`
- `README.uk.md` → `docs/i18n/uk/README.md`
- `常见问题.md` → `docs/guides/faq.zh-CN.md`
### Root Directory (Unchanged)
These stay in the root for GitHub recognition:
- `README.md` ✅ (stays in root)
- `LICENSE` ✅ (stays in root)
- `CONTRIBUTING.md` ✅ (stays in root)
- `CODE_OF_CONDUCT.md` ✅ (stays in root)
- `SECURITY.md` ✅ (stays in root)
## 🎯 Why This Change?
### Before (❌ Problems)
```
nofx/
├── README.md
├── README.zh-CN.md
├── README.ru.md
├── README.uk.md
├── DOCKER_DEPLOY.md
├── DOCKER_DEPLOY.en.md
├── PM2_DEPLOYMENT.md
├── CUSTOM_API.md
├── HOW_TO_POST_BOUNTY.md
├── INTEGRATION_BOUNTY_HYPERLIQUID.md
├── INTEGRATION_BOUNTY_ASTER.md
├── 常见问题.md
└── ... (15+ markdown files in root!)
```
**Issues:**
- 😵 Too cluttered (15+ files in root)
- 🔍 Hard to find specific docs
- 🌍 Mixed languages
- 📚 No clear organization
### After (✅ Benefits)
```
nofx/
├── README.md # Project homepage
├── LICENSE # Legal (GitHub needs it here)
├── CONTRIBUTING.md # GitHub auto-links
├── CODE_OF_CONDUCT.md # GitHub auto-links
├── SECURITY.md # GitHub auto-links
│
└── docs/ # 📚 Documentation hub
├── README.md # Documentation home
├── getting-started/ # 🚀 Setup guides
├── guides/ # 📘 User guides
├── community/ # 👥 Contribution docs
├── i18n/ # 🌍 Translations
└── architecture/ # 🏗️ Technical docs
```
**Benefits:**
- ✅ Clean root directory
- ✅ Logical categorization
- ✅ Easy navigation
- ✅ Scalable structure
- ✅ Professional appearance
## 📚 New Documentation Structure
### Root Level
Files GitHub needs to see:
- `README.md` - Main project page
- `LICENSE` - Open source license
- `CONTRIBUTING.md` - Contributor guide
- `CODE_OF_CONDUCT.md` - Community standards
- `SECURITY.md` - Security policy
### docs/ Level
**Navigation:**
- `docs/README.md` - **Start here!** Main documentation hub
**Categories:**
1. **`getting-started/`** - Deployment and setup
- Docker deployment (EN/中文)
- PM2 deployment
- Custom API configuration
2. **`guides/`** - Usage guides and tutorials
- FAQ (中文)
- Troubleshooting (planned)
- Configuration examples (planned)
3. **`community/`** - Contribution and bounties
- Bounty guide
- Active bounty tasks
- Contributor recognition
4. **`i18n/`** - International translations
- `zh-CN/` - Simplified Chinese
- `ru/` - Russian
- `uk/` - Ukrainian
5. **`architecture/`** - Technical documentation
- System design (planned)
- API reference (planned)
- Database schema (planned)
## 🔗 Updating Your Links
### If you bookmarked old links:
| Old Link | New Link |
|----------|----------|
| `DOCKER_DEPLOY.en.md` | `docs/getting-started/docker-deploy.en.md` |
| `README.zh-CN.md` | `docs/i18n/zh-CN/README.md` |
| `HOW_TO_POST_BOUNTY.md` | `docs/community/bounty-guide.md` |
### If you linked in your own docs:
**Update relative links:**
```markdown
<!-- Old -->
[Docker Deployment](DOCKER_DEPLOY.en.md)
<!-- New -->
[Docker Deployment](docs/getting-started/docker-deploy.en.md)
```
**GitHub URLs automatically redirect!**
- Old: `github.com/tinkle-community/nofx/blob/main/DOCKER_DEPLOY.en.md`
- Will redirect to: `github.com/.../docs/getting-started/docker-deploy.en.md`
## 🛠️ For Contributors
### Cloning/Pulling Latest
```bash
# Pull latest changes
git pull origin dev
# Your old bookmarks still work!
# Git tracked the file moves (git mv)
```
### Finding Documentation
**Use the navigation hub:**
1. Start at [docs/README.md](README.md)
2. Browse by category
3. Use the quick navigation section
**Or search:**
```bash
# Find all markdown docs
find docs -name "*.md"
# Search content
grep -r "keyword" docs/
```
### Adding New Documentation
**Follow the structure:**
```bash
# Getting started guides
docs/getting-started/your-guide.md
# User guides
docs/guides/your-tutorial.md
# Community docs
docs/community/your-doc.md
# Translations
docs/i18n/ja/README.md # Japanese example
```
**Update navigation:**
- Add link in relevant category README
- Add to `docs/README.md` main hub
## 📝 Commit Messages
This reorganization was committed as:
```
docs: reorganize documentation into structured docs/ directory
- Move deployment guides to docs/getting-started/
- Move community docs to docs/community/
- Move translations to docs/i18n/
- Create navigation hub at docs/README.md
- Update all internal links in README.md
- Add GitHub issue/PR templates
BREAKING CHANGE: Direct links to moved files will need updating
(though GitHub redirects should work)
Closes #XXX
```
## 🆘 Need Help?
**Can't find a document?**
1. Check [docs/README.md](README.md) navigation hub
2. Search GitHub repo
3. Ask in [Telegram](https://t.me/nofx_dev_community)
**Link broken?**
- Report in [GitHub Issues](https://github.com/tinkle-community/nofx/issues)
- We'll fix it ASAP!
**Want to contribute docs?**
- See [Contributing Guide](../CONTRIBUTING.md)
- Check [docs/community/](community/README.md)
---
**Migration Date:** 2025-11-01
**Maintainers:** Tinkle Community
[← Back to Documentation Home](README.md)

192
docs/README.md Normal file
View File

@@ -0,0 +1,192 @@
# 📚 NOFX Documentation Center / 文档中心
Welcome to the NOFX documentation! This page helps you find the right documentation quickly.
欢迎来到 NOFX 文档中心！本页面帮助您快速找到所需文档。
---
## 🚀 Getting Started / 快速开始
**New to NOFX? Start here!**
| Document | Description | 描述 |
|----------|-------------|------|
| [Main README](../README.md) | Project overview, features, quick start | 项目概述、功能、快速入门 |
| [Getting Started Index (EN)](getting-started/README.md) | All deployment options | 所有部署选项 |
| [Getting Started Index (中文)](getting-started/README.zh-CN.md) | 所有部署选项 | All deployment options |
| [Docker Deployment (EN)](getting-started/docker-deploy.en.md) | Deploy with Docker (recommended) | Docker 部署（推荐） |
| [Docker Deployment (中文)](getting-started/docker-deploy.zh-CN.md) | Docker 部署指南（中文） | Docker deployment guide |
| [PM2 Deployment (EN)](getting-started/pm2-deploy.en.md) | Deploy with PM2 process manager | PM2 进程管理器部署 |
| [PM2 Deployment (中文)](getting-started/pm2-deploy.md) | PM2 部署指南（中文） | PM2 deployment guide |
| [Custom API (EN)](getting-started/custom-api.en.md) | Connect custom AI API providers | 连接自定义 AI API |
| [Custom API (中文)](getting-started/custom-api.md) | 连接自定义 AI API 提供商 | Custom AI provider guide |
**Quick Links:**
- 📖 See all options → [Getting Started](getting-started/README.md) / [快速开始](getting-started/README.zh-CN.md)
- 🐳 Want easiest setup? → [Docker (EN)](getting-started/docker-deploy.en.md) / [Docker (中文)](getting-started/docker-deploy.zh-CN.md)
- 🔧 Advanced user? → [PM2 (EN)](getting-started/pm2-deploy.en.md) / [PM2 (中文)](getting-started/pm2-deploy.md)
- 🤖 Custom AI model? → [Custom API (EN)](getting-started/custom-api.en.md) / [自定义 API](getting-started/custom-api.md)
---
## 📘 User Guides / 使用指南
**Learn how to use NOFX effectively**
| Document | Description | 描述 |
|----------|-------------|------|
| [User Guides Index (EN)](guides/README.md) | All usage guides and tips | 所有使用指南和技巧 |
| [User Guides Index (中文)](guides/README.zh-CN.md) | 所有使用指南和技巧 | All usage guides and tips |
| [FAQ (English)](guides/faq.en.md) | Frequently asked questions | 常见问题解答 |
| [FAQ (中文)](guides/faq.zh-CN.md) | 常见问题解答 | Frequently asked questions |
| Troubleshooting *(coming soon)* | Common issues and solutions | 故障排查 |
| Configuration Guide *(coming soon)* | Advanced configuration options | 高级配置选项 |
| Trading Strategies *(coming soon)* | AI trading strategy examples | AI 交易策略示例 |
---
## 👥 Community & Contributing / 社区与贡献
**Join the community and contribute!**
| Document | Description | 描述 |
|----------|-------------|------|
| [Code of Conduct](../CODE_OF_CONDUCT.md) | Community guidelines | 社区行为准则 |
| [Security Policy](../SECURITY.md) | Report security vulnerabilities | 报告安全漏洞 |
| [Bounty Guide](community/bounty-guide.md) | How to post bounty tasks | 如何发布悬赏任务 |
| [Hyperliquid Bounty](community/bounty-hyperliquid.md) | Hyperliquid integration bounty | Hyperliquid 集成悬赏 |
| [Aster Bounty](community/bounty-aster.md) | Aster DEX integration bounty | Aster DEX 集成悬赏 |
**Get Involved:**
- 💬 [Telegram Community](https://t.me/nofx_dev_community)
- 🐦 [Twitter @nofx_ai](https://x.com/nofx_ai)
- 🐛 [Report Issues](https://github.com/tinkle-community/nofx/issues)
---
## 🌍 International / 国际化文档
**Documentation in other languages**
| Language | Main README | Status |
|----------|-------------|--------|
| 🇨🇳 Chinese (中文) | [README.md](i18n/zh-CN/README.md) | ✅ Complete |
| 🇷🇺 Russian (Русский) | [README.md](i18n/ru/README.md) | ✅ Complete |
| 🇺🇦 Ukrainian (Українська) | [README.md](i18n/uk/README.md) | ✅ Complete |
| 🇬🇧 English | [README.md](../README.md) | ✅ Complete |
---
## 🏗️ Architecture & Development / 架构与开发
**For developers who want to understand the internals**
| Document | Description | 描述 |
|----------|-------------|------|
| [Architecture Overview (EN)](architecture/README.md) | System architecture, modules, and design | 系统架构、模块和设计 |
| [Architecture Overview (中文)](architecture/README.zh-CN.md) | 系统架构、模块和设计 | System architecture overview |
| API Reference *(coming soon)* | HTTP API documentation | HTTP API 文档 |
| Database Schema *(coming soon)* | SQLite database structure | SQLite 数据库结构 |
| Testing Guide *(coming soon)* | How to write tests | 如何编写测试 |
---
## 🗺️ Roadmap / 路线图
**NOFX's strategic development plan and market expansion**
| Document | Description | 描述 |
|----------|-------------|------|
| [Roadmap (EN)](roadmap/README.md) | Short-term and long-term roadmap, feature timeline | 短期和长期路线图、功能时间表 |
| [Roadmap (中文)](roadmap/README.zh-CN.md) | 短期和长期路线图、功能时间表 | Strategic development plan |
**Roadmap Highlights:**
- 📈 **Short-term (Q2-Q3 2025)**: Advanced risk management, multi-AI ensemble, new exchange integrations
- 🚀 **Long-term (2026)**: Universal market expansion (stocks, futures, options, forex), reinforcement learning, enterprise features
---
## 📄 Legal & Policies / 法律与政策
| Document | Description | 描述 |
|----------|-------------|------|
| [License (MIT)](../LICENSE) | Open source license | 开源许可证 |
| [Changelog (EN)](../CHANGELOG.md) | Version history and updates | 版本历史和更新 |
| [Changelog (中文)](../CHANGELOG.zh-CN.md) | 版本历史和更新 | Version history and updates |
| [Security Policy](../SECURITY.md) | Vulnerability disclosure | 漏洞披露政策 |
| [Code of Conduct](../CODE_OF_CONDUCT.md) | Community standards | 社区标准 |
---
## 🔍 Quick Navigation / 快速导航
**Find what you need fast:**
### I want to...
- 🚀 **Get started quickly** → [Getting Started](getting-started/README.md) / [快速开始](getting-started/README.zh-CN.md)
- 🐛 **Report a bug** → [GitHub Issues](https://github.com/tinkle-community/nofx/issues/new)
- 💡 **Suggest a feature** → [Feature Request](https://github.com/tinkle-community/nofx/issues/new?template=feature_request.md)
- 🔒 **Report security issue** → [Security Policy](../SECURITY.md)
- 💰 **Claim a bounty** → [Bounty Guide](community/bounty-guide.md)
- 🤝 **Contribute code** → [Contributing Guide](../CONTRIBUTING.md)
- 💬 **Ask questions** → [Telegram Community](https://t.me/nofx_dev_community)
### I'm looking for...
- 🏗️ **System architecture** → [Architecture (EN)](architecture/README.md) / [架构文档](architecture/README.zh-CN.md)
- 🗺️ **Product roadmap** → [Roadmap (EN)](roadmap/README.md) / [路线图](roadmap/README.zh-CN.md)
- 📊 **API documentation** → Coming soon
- 🧪 **Testing guide** → Coming soon
- 🔧 **Configuration examples** → [Custom API (EN)](getting-started/custom-api.en.md) / [自定义 API](getting-started/custom-api.md)
- 🌐 **Multi-language docs** → [International section](#-international--国际化文档)
---
## 📚 Documentation Status
| Category | Status | Last Updated |
|----------|--------|--------------|
| Getting Started | ✅ Complete | 2025-11-01 |
| User Guides | ✅ Complete | 2025-11-01 |
| Community | ✅ Complete | 2025-11-01 |
| Architecture | ✅ Complete | 2025-11-01 |
| Roadmap | ✅ Complete | 2025-11-01 |
| API Reference | 📋 Planned | - |
**Legend:**
- ✅ Complete - Documentation is ready
- 🚧 In Progress - Being written
- 📋 Planned - On the roadmap
- ⚠️ Outdated - Needs update
---
## 🆘 Need Help?
**Can't find what you're looking for?**
1. **Search GitHub Issues** - Someone might have asked already
2. **Join Telegram** - [NOFX Developer Community](https://t.me/nofx_dev_community)
3. **Ask on Twitter** - Mention [@nofx_ai](https://x.com/nofx_ai)
4. **Create an Issue** - [New Issue](https://github.com/tinkle-community/nofx/issues/new)
---
## 🤝 Contributing to Documentation
Found an error or want to improve the docs?
1. **Small fixes** - Click "Edit" on GitHub and submit PR
2. **New documentation** - Create an issue first to discuss
3. **Translations** - See [Contributing Guide](../CONTRIBUTING.md)
**Documentation Contributors:**
- All documentation follows [Markdown Guide](https://www.markdownguide.org/)
- Use clear, concise language
- Include code examples where helpful
- Add screenshots for UI-related docs
---
**Last Updated:** 2025-11-01
**Maintained by:** [Tinkle Community](https://github.com/tinkle-community)

570
docs/architecture/README.md Normal file
View File

@@ -0,0 +1,570 @@
# 🏗️ NOFX Architecture Documentation
**Language:** [English](README.md) | [中文](README.zh-CN.md)
Technical documentation for developers who want to understand NOFX internals.
---
## 📋 Overview
NOFX is a full-stack AI trading platform with:
- **Backend:** Go (Gin framework, SQLite)
- **Frontend:** React/TypeScript (Vite, TailwindCSS)
- **Architecture:** Microservice-inspired modular design
---
## 📁 Project Structure
```
nofx/
├── main.go # Program entry (multi-trader manager)
├── config.json # ~~Multi-trader config~~ (Now via web interface)
├── trading.db # SQLite database (traders, models, exchanges)
│
├── api/ # HTTP API service
│ └── server.go # Gin framework, RESTful API
│
├── trader/ # Trading core
│ ├── auto_trader.go # Auto trading main controller
│ ├── interface.go # Unified trader interface
│ ├── binance_futures.go # Binance API wrapper
│ ├── hyperliquid_trader.go # Hyperliquid DEX wrapper
│ └── aster_trader.go # Aster DEX wrapper
│
├── manager/ # Multi-trader management
│ └── trader_manager.go # Manages multiple trader instances
│
├── config/ # Configuration & database
│ └── database.go # SQLite operations and schema
│
├── auth/ # Authentication
│ └── jwt.go # JWT token management & 2FA
│
├── mcp/ # Model Context Protocol - AI communication
│ └── client.go # AI API client (DeepSeek/Qwen/Custom)
│
├── decision/ # AI decision engine
│ ├── engine.go # Decision logic with historical feedback
│ └── prompt_manager.go # Prompt template system
│
├── market/ # Market data fetching
│ └── data.go # Market data & technical indicators (TA-Lib)
│
├── pool/ # Coin pool management
│ └── coin_pool.go # AI500 + OI Top merged pool
│
├── logger/ # Logging system
│ └── decision_logger.go # Decision recording + performance analysis
│
├── decision_logs/ # Decision log storage (JSON files)
│ ├── {trader_id}/ # Per-trader logs
│ └── {timestamp}.json # Individual decisions
│
└── web/ # React frontend
├── src/
│ ├── components/ # React components
│ │ ├── EquityChart.tsx # Equity curve chart
│ │ ├── ComparisonChart.tsx # Multi-AI comparison chart
│ │ └── CompetitionPage.tsx # Competition leaderboard
│ ├── lib/api.ts # API call wrapper
│ ├── types/index.ts # TypeScript types
│ ├── stores/ # Zustand state management
│ ├── index.css # Binance-style CSS
│ └── App.tsx # Main app
├── package.json # Frontend dependencies
└── vite.config.ts # Vite configuration
```
---
## 🔧 Core Dependencies
### Backend (Go)
| Package | Purpose | Version |
|---------|---------|---------|
| `github.com/gin-gonic/gin` | HTTP API framework | v1.9+ |
| `github.com/adshao/go-binance/v2` | Binance API client | v2.4+ |
| `github.com/markcheno/go-talib` | Technical indicators (TA-Lib) | Latest |
| `github.com/mattn/go-sqlite3` | SQLite database driver | v1.14+ |
| `github.com/golang-jwt/jwt/v5` | JWT authentication | v5.0+ |
| `github.com/pquerna/otp` | 2FA/TOTP support | v1.4+ |
| `golang.org/x/crypto` | Password hashing (bcrypt) | Latest |
### Frontend (React + TypeScript)
| Package | Purpose | Version |
|---------|---------|---------|
| `react` + `react-dom` | UI framework | 18.3+ |
| `typescript` | Type safety | 5.8+ |
| `vite` | Build tool | 6.0+ |
| `recharts` | Charts (equity, comparison) | 2.15+ |
| `swr` | Data fetching & caching | 2.2+ |
| `zustand` | State management | 5.0+ |
| `tailwindcss` | CSS framework | 3.4+ |
| `lucide-react` | Icon library | Latest |
---
## 🗂️ System Architecture
### High-Level Overview
```
┌──────────────────────────────────────────────────────────────────┐
│ PRESENTATION LAYER │
│ React SPA (Vite + TypeScript + TailwindCSS) │
│ - Competition dashboard, trader management UI │
│ - Real-time charts (Recharts), authentication pages │
└──────────────────────────────────────────────────────────────────┘
↓ HTTP/JSON API
┌──────────────────────────────────────────────────────────────────┐
│ API LAYER (Gin Router) │
│ /api/traders, /api/status, /api/positions, /api/decisions │
│ Authentication middleware (JWT), CORS handling │
└──────────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────────┐
│ BUSINESS LOGIC LAYER │
│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────┐ │
│ │ TraderManager │ │ DecisionEngine │ │ MarketData │ │
│ │ - Multi-trader │ │ - AI reasoning │ │ - K-lines │ │
│ │ orchestration │ │ - Risk control │ │ - Indicators │ │
│ └──────────────────┘ └──────────────────┘ └────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────────┐
│ DATA ACCESS LAYER │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ SQLite DB │ │ File Logger │ │ External APIs │ │
│ │ - Traders │ │ - Decisions │ │ - Binance │ │
│ │ - Models │ │ - Performance│ │ - Hyperliquid │ │
│ │ - Exchanges │ │ analysis │ │ - Aster │ │
│ └──────────────┘ └──────────────┘ └────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```
### Component Diagram
*(Coming soon: detailed component interaction diagram)*
---
## 📚 Core Modules
### 1. Trader System (`trader/`)
**Purpose:** Trading execution layer with multi-exchange support
**Key Files:**
- `auto_trader.go` - Main trading orchestrator (100+ lines)
- `interface.go` - Unified trader interface
- `binance_futures.go` - Binance API wrapper
- `hyperliquid_trader.go` - Hyperliquid DEX wrapper
- `aster_trader.go` - Aster DEX wrapper
**Design Pattern:** Strategy pattern with interface-based abstraction
**Example:**
```go
type ExchangeClient interface {
GetAccount() (*AccountInfo, error)
GetPositions() ([]*Position, error)
CreateOrder(*OrderParams) (*Order, error)
// ... more methods
}
```
---
### 2. Decision Engine (`decision/`)
**Purpose:** AI-powered trading decision making
**Key Files:**
- `engine.go` - Decision logic with historical feedback
- `prompt_manager.go` - Template system for AI prompts
**Features:**
- Chain-of-Thought reasoning
- Historical performance analysis
- Risk-aware decision making
- Multi-model support (DeepSeek, Qwen, custom)
**Flow:**
```
Historical Data → Prompt Generation → AI API Call →
Decision Parsing → Risk Validation → Execution
```
---
### 3. Market Data System (`market/`)
**Purpose:** Fetch and analyze market data
**Key Files:**
- `data.go` - Market data fetching and technical indicators
**Features:**
- Multi-timeframe K-line data (3min, 4hour)
- Technical indicators via TA-Lib:
- EMA (20, 50)
- MACD
- RSI (7, 14)
- ATR (volatility)
- Open Interest tracking
---
### 4. Manager (`manager/`)
**Purpose:** Multi-trader orchestration
**Key Files:**
- `trader_manager.go` - Manages multiple trader instances
**Responsibilities:**
- Trader lifecycle (start, stop, restart)
- Resource allocation
- Concurrent execution coordination
---
### 5. API Server (`api/`)
**Purpose:** HTTP API for frontend communication
**Key Files:**
- `server.go` - Gin framework RESTful API
**Endpoints:**
```
GET /api/traders # List all traders
POST /api/traders # Create trader
POST /api/traders/:id/start # Start trader
GET /api/status # System status
GET /api/positions # Current positions
GET /api/decisions/latest # Recent decisions
```
---
### 6. Database Layer (`config/`)
**Purpose:** SQLite data persistence
**Key Files:**
- `database.go` - Database operations and schema
**Tables:**
- `users` - User accounts (with 2FA support)
- `ai_models` - AI model configurations
- `exchanges` - Exchange credentials
- `traders` - Trader instances
- `equity_history` - Performance tracking
- `system_config` - Application settings
---
### 7. Authentication (`auth/`)
**Purpose:** User authentication and authorization
**Features:**
- JWT token-based auth
- 2FA with TOTP (Google Authenticator)
- Bcrypt password hashing
- Admin mode (simplified single-user)
---
## 🔄 Request Flow Examples
### Example 1: Create New Trader
```
User Action (Frontend)
↓
POST /api/traders
↓
API Server (auth middleware)
↓
Database.CreateTrader()
↓
TraderManager.StartTrader()
↓
AutoTrader.Run() → goroutine
↓
Response: {trader_id, status}
```
### Example 2: Trading Decision Cycle
```
AutoTrader (every 3-5 min)
↓
1. FetchAccountStatus()
↓
2. GetOpenPositions()
↓
3. FetchMarketData() → TA-Lib indicators
↓
4. AnalyzeHistory() → last 20 trades
↓
5. GeneratePrompt() → full context
↓
6. CallAI() → DeepSeek/Qwen
↓
7. ParseDecision() → structured output
↓
8. ValidateRisk() → position limits, margin
↓
9. ExecuteOrders() → exchange API
↓
10. LogDecision() → JSON file + database
```
---
## 📊 Data Flow
### Market Data Flow
```
Exchange API
↓
market.FetchKlines()
↓
TA-Lib.Calculate(EMA, MACD, RSI)
↓
DecisionEngine (as context)
↓
AI Model (reasoning)
```
### Decision Logging Flow
```
AI Response
↓
decision_logger.go
↓
JSON file: decision_logs/{trader_id}/{timestamp}.json
↓
Database: performance tracking
↓
Frontend: /api/decisions/latest
```
---
## 🗄️ Database Schema
### Core Tables
**users**
```sql
- id (INTEGER PRIMARY KEY)
- username (TEXT UNIQUE)
- password_hash (TEXT)
- totp_secret (TEXT)
- is_admin (BOOLEAN)
- created_at (DATETIME)
```
**ai_models**
```sql
- id (INTEGER PRIMARY KEY)
- name (TEXT)
- model_type (TEXT) -- deepseek, qwen, custom
- api_key (TEXT)
- api_url (TEXT)
- enabled (BOOLEAN)
```
**traders**
```sql
- id (TEXT PRIMARY KEY)
- name (TEXT)
- ai_model_id (INTEGER FK)
- exchange_id (INTEGER FK)
- initial_balance (REAL)
- current_equity (REAL)
- status (TEXT) -- running, stopped
- created_at (DATETIME)
```
*(More details: database-schema.md - coming soon)*
---
## 🔌 API Reference
### Authentication
**POST /api/auth/login**
```json
Request: {
"username": "string",
"password": "string",
"totp_code": "string" // optional
}
Response: {
"token": "jwt_token",
"user": {...}
}
```
### Trader Management
**GET /api/traders**
```json
Response: {
"traders": [
{
"id": "string",
"name": "string",
"status": "running|stopped",
"balance": 1000.0,
"roi": 5.2
}
]
}
```
*(Full API reference: api-reference.md - coming soon)*
---
## 🧪 Testing Architecture
### Current State
- ⚠️ No unit tests yet
- ⚠️ Manual testing only
- ⚠️ Testnet verification
### Planned Testing Strategy
**Unit Tests (Priority 1)**
```
trader/binance_futures_test.go
- Mock API responses
- Test precision handling
- Validate order construction
```
**Integration Tests (Priority 2)**
```
- End-to-end trading flow (testnet)
- Multi-trader scenarios
- Database operations
```
**Frontend Tests (Priority 3)**
```
- Component tests (Vitest + React Testing Library)
- API integration tests
- E2E tests (Playwright)
```
*(Testing guide: testing-guide.md - coming soon)*
---
## 🔧 Development Tools
### Build & Run
```bash
# Backend
go build -o nofx
./nofx
# Frontend
cd web
npm run dev
# Docker
docker compose up --build
```
### Code Quality
```bash
# Format Go code
go fmt ./...
# Lint (if configured)
golangci-lint run
# Type check TypeScript
cd web && npm run build
```
---
## 📈 Performance Considerations
### Backend
- **Concurrency:** Each trader runs in separate goroutine
- **Database:** SQLite (good for <100 traders)
- **API Rate Limits:** Handled per exchange
- **Memory:** ~50-100MB per trader
### Frontend
- **Data Fetching:** SWR with 5-10s polling
- **State:** Zustand (lightweight)
- **Bundle Size:** ~500KB (gzipped)
---
## 🔮 Future Architecture Plans
### Planned Improvements
1. **Microservices Split** (if scaling needed)
- Separate decision engine service
- Market data service
- Execution service
2. **Database Migration**
- Mysql for production (>100 traders)
- Redis for caching
3. **Event-Driven Architecture**
- WebSocket for real-time updates
- Message queue (RabbitMQ/NATS)
4. **Kubernetes Deployment**
- Helm charts
- Auto-scaling
- High availability
---
## 🆘 For Developers
**Want to contribute?**
- Read [Contributing Guide](../../CONTRIBUTING.md)
- Check [Open Issues](https://github.com/tinkle-community/nofx/issues)
- Join [Telegram Community](https://t.me/nofx_dev_community)
**Need clarification?**
- Open a [GitHub Discussion](https://github.com/tinkle-community/nofx/discussions)
- Ask in Telegram
---
## 📚 Related Documentation
- [Getting Started](../getting-started/README.md) - Setup and deployment
- [Contributing](../../CONTRIBUTING.md) - How to contribute
- [Community](../community/README.md) - Bounties and recognition
---
[← Back to Documentation Home](../README.md)

570
docs/architecture/README.zh-CN.md Normal file
View File

@@ -0,0 +1,570 @@
# 🏗️ NOFX 架构文档
**语言:** [English](README.md) | [中文](README.zh-CN.md)
为希望了解 NOFX 内部实现的开发者提供的技术文档。
---
## 📋 概述
NOFX 是一个全栈 AI 交易平台：
- **后端：** Go (Gin 框架, SQLite)
- **前端：** React/TypeScript (Vite, TailwindCSS)
- **架构：** 微服务启发的模块化设计
---
## 📁 项目结构
```
nofx/
├── main.go # 程序入口（多交易员管理器）
├── config.json # ~~多交易员配置~~ (现通过Web界面)
├── trading.db # SQLite 数据库（交易员、模型、交易所）
│
├── api/ # HTTP API 服务
│ └── server.go # Gin 框架，RESTful API
│
├── trader/ # 交易核心
│ ├── auto_trader.go # 自动交易主控制器
│ ├── interface.go # 统一交易员接口
│ ├── binance_futures.go # Binance API 包装器
│ ├── hyperliquid_trader.go # Hyperliquid DEX 包装器
│ └── aster_trader.go # Aster DEX 包装器
│
├── manager/ # 多交易员管理
│ └── trader_manager.go # 管理多个交易员实例
│
├── config/ # 配置与数据库
│ └── database.go # SQLite 操作和模式
│
├── auth/ # 认证
│ └── jwt.go # JWT token 管理 & 2FA
│
├── mcp/ # Model Context Protocol - AI 通信
│ └── client.go # AI API 客户端（DeepSeek/Qwen/自定义）
│
├── decision/ # AI 决策引擎
│ ├── engine.go # 带历史反馈的决策逻辑
│ └── prompt_manager.go # 提示词模板系统
│
├── market/ # 市场数据获取
│ └── data.go # 市场数据与技术指标（TA-Lib）
│
├── pool/ # 币种池管理
│ └── coin_pool.go # AI500 + OI Top 合并池
│
├── logger/ # 日志系统
│ └── decision_logger.go # 决策记录 + 性能分析
│
├── decision_logs/ # 决策日志存储（JSON 文件）
│ ├── {trader_id}/ # 每个交易员的日志
│ └── {timestamp}.json # 单个决策
│
└── web/ # React 前端
├── src/
│ ├── components/ # React 组件
│ │ ├── EquityChart.tsx # 权益曲线图表
│ │ ├── ComparisonChart.tsx # 多 AI 对比图表
│ │ └── CompetitionPage.tsx # 竞赛排行榜
│ ├── lib/api.ts # API 调用包装器
│ ├── types/index.ts # TypeScript 类型
│ ├── stores/ # Zustand 状态管理
│ ├── index.css # Binance 风格样式
│ └── App.tsx # 主应用
├── package.json # 前端依赖
└── vite.config.ts # Vite 配置
```
---
## 🔧 核心依赖
### 后端 (Go)
| 包 | 用途 | 版本 |
|---------|---------|---------|
| `github.com/gin-gonic/gin` | HTTP API 框架 | v1.9+ |
| `github.com/adshao/go-binance/v2` | Binance API 客户端 | v2.4+ |
| `github.com/markcheno/go-talib` | 技术指标（TA-Lib） | 最新 |
| `github.com/mattn/go-sqlite3` | SQLite 数据库驱动 | v1.14+ |
| `github.com/golang-jwt/jwt/v5` | JWT 认证 | v5.0+ |
| `github.com/pquerna/otp` | 2FA/TOTP 支持 | v1.4+ |
| `golang.org/x/crypto` | 密码哈希（bcrypt） | 最新 |
### 前端 (React + TypeScript)
| 包 | 用途 | 版本 |
|---------|---------|---------|
| `react` + `react-dom` | UI 框架 | 18.3+ |
| `typescript` | 类型安全 | 5.8+ |
| `vite` | 构建工具 | 6.0+ |
| `recharts` | 图表（权益、对比） | 2.15+ |
| `swr` | 数据获取与缓存 | 2.2+ |
| `zustand` | 状态管理 | 5.0+ |
| `tailwindcss` | CSS 框架 | 3.4+ |
| `lucide-react` | 图标库 | 最新 |
---
## 🗂️ 系统架构
### 高层架构概览
```
┌──────────────────────────────────────────────────────────────────┐
│ 表现层 │
│ React SPA (Vite + TypeScript + TailwindCSS) │
│ - 竞赛仪表板、交易员管理 UI │
│ - 实时图表 (Recharts)、认证页面 │
└──────────────────────────────────────────────────────────────────┘
↓ HTTP/JSON API
┌──────────────────────────────────────────────────────────────────┐
│ API 层 (Gin Router) │
│ /api/traders, /api/status, /api/positions, /api/decisions │
│ 认证中间件 (JWT)、CORS 处理 │
└──────────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────────┐
│ 业务逻辑层 │
│ ┌──────────────────┐ ┌──────────────────┐ ┌────────────────┐ │
│ │ TraderManager │ │ DecisionEngine │ │ MarketData │ │
│ │ - 多交易员 │ │ - AI 推理 │ │ - K线数据 │ │
│ │ 编排 │ │ - 风险控制 │ │ - 技术指标 │ │
│ └──────────────────┘ └──────────────────┘ └────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
↓
┌──────────────────────────────────────────────────────────────────┐
│ 数据访问层 │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────────────┐ │
│ │ SQLite DB │ │ 文件日志 │ │ 外部 APIs │ │
│ │ - Traders │ │ - Decisions │ │ - Binance │ │
│ │ - Models │ │ - Performance│ │ - Hyperliquid │ │
│ │ - Exchanges │ │ analysis │ │ - Aster │ │
│ └──────────────┘ └──────────────┘ └────────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
```
### 组件图
*（即将推出：详细的组件交互图）*
---
## 📚 核心模块
### 1. 交易系统 (`trader/`)
**用途：** 支持多交易所的交易执行层
**关键文件：**
- `auto_trader.go` - 主交易编排器（100+ 行）
- `interface.go` - 统一的交易员接口
- `binance_futures.go` - Binance API 包装器
- `hyperliquid_trader.go` - Hyperliquid DEX 包装器
- `aster_trader.go` - Aster DEX 包装器
**设计模式：** 基于接口抽象的策略模式
**示例：**
```go
type ExchangeClient interface {
GetAccount() (*AccountInfo, error)
GetPositions() ([]*Position, error)
CreateOrder(*OrderParams) (*Order, error)
// ... 更多方法
}
```
---
### 2. 决策引擎 (`decision/`)
**用途：** AI 驱动的交易决策制定
**关键文件：**
- `engine.go` - 带历史反馈的决策逻辑
- `prompt_manager.go` - AI 提示词模板系统
**特性：**
- 思维链推理
- 历史表现分析
- 风险感知决策
- 多模型支持（DeepSeek、Qwen、自定义）
**流程：**
```
历史数据 → 提示词生成 → AI API 调用 →
决策解析 → 风险验证 → 执行
```
---
### 3. 市场数据系统 (`market/`)
**用途：** 获取和分析市场数据
**关键文件：**
- `data.go` - 市场数据获取和技术指标
**特性：**
- 多时间周期 K线数据（3分钟、4小时）
- 通过 TA-Lib 计算技术指标：
- EMA (20, 50)
- MACD
- RSI (7, 14)
- ATR（波动率）
- 持仓量跟踪
---
### 4. 管理器 (`manager/`)
**用途：** 多交易员编排
**关键文件：**
- `trader_manager.go` - 管理多个交易员实例
**职责：**
- 交易员生命周期（启动、停止、重启）
- 资源分配
- 并发执行协调
---
### 5. API 服务器 (`api/`)
**用途：** 前端通信的 HTTP API
**关键文件：**
- `server.go` - Gin 框架 RESTful API
**端点：**
```
GET /api/traders # 列出所有交易员
POST /api/traders # 创建交易员
POST /api/traders/:id/start # 启动交易员
GET /api/status # 系统状态
GET /api/positions # 当前持仓
GET /api/decisions/latest # 最近决策
```
---
### 6. 数据库层 (`config/`)
**用途：** SQLite 数据持久化
**关键文件：**
- `database.go` - 数据库操作和模式
**表：**
- `users` - 用户账户（支持 2FA）
- `ai_models` - AI 模型配置
- `exchanges` - 交易所凭证
- `traders` - 交易员实例
- `equity_history` - 绩效跟踪
- `system_config` - 应用程序设置
---
### 7. 认证 (`auth/`)
**用途：** 用户认证和授权
**特性：**
- 基于 JWT token 的认证
- 使用 TOTP 的 2FA（Google Authenticator）
- Bcrypt 密码哈希
- 管理员模式（简化的单用户模式）
---
## 🔄 请求流程示例
### 示例 1：创建新交易员
```
用户操作（前端）
↓
POST /api/traders
↓
API 服务器（认证中间件）
↓
Database.CreateTrader()
↓
TraderManager.StartTrader()
↓
AutoTrader.Run() → goroutine
↓
响应: {trader_id, status}
```
### 示例 2：交易决策周期
```
AutoTrader（每 3-5 分钟）
↓
1. FetchAccountStatus()
↓
2. GetOpenPositions()
↓
3. FetchMarketData() → TA-Lib 指标
↓
4. AnalyzeHistory() → 最近 20 笔交易
↓
5. GeneratePrompt() → 完整上下文
↓
6. CallAI() → DeepSeek/Qwen
↓
7. ParseDecision() → 结构化输出
↓
8. ValidateRisk() → 仓位限制、保证金
↓
9. ExecuteOrders() → 交易所 API
↓
10. LogDecision() → JSON 文件 + 数据库
```
---
## 📊 数据流
### 市场数据流
```
交易所 API
↓
market.FetchKlines()
↓
TA-Lib.Calculate(EMA, MACD, RSI)
↓
DecisionEngine（作为上下文）
↓
AI 模型（推理）
```
### 决策日志流
```
AI 响应
↓
decision_logger.go
↓
JSON 文件: decision_logs/{trader_id}/{timestamp}.json
↓
数据库: 绩效跟踪
↓
前端: /api/decisions/latest
```
---
## 🗄️ 数据库架构
### 核心表
**users**
```sql
- id (INTEGER PRIMARY KEY)
- username (TEXT UNIQUE)
- password_hash (TEXT)
- totp_secret (TEXT)
- is_admin (BOOLEAN)
- created_at (DATETIME)
```
**ai_models**
```sql
- id (INTEGER PRIMARY KEY)
- name (TEXT)
- model_type (TEXT) -- deepseek, qwen, custom
- api_key (TEXT)
- api_url (TEXT)
- enabled (BOOLEAN)
```
**traders**
```sql
- id (TEXT PRIMARY KEY)
- name (TEXT)
- ai_model_id (INTEGER FK)
- exchange_id (INTEGER FK)
- initial_balance (REAL)
- current_equity (REAL)
- status (TEXT) -- running, stopped
- created_at (DATETIME)
```
*（更多详情：database-schema.md - 即将推出）*
---
## 🔌 API 参考
### 认证
**POST /api/auth/login**
```json
请求: {
"username": "string",
"password": "string",
"totp_code": "string" // 可选
}
响应: {
"token": "jwt_token",
"user": {...}
}
```
### 交易员管理
**GET /api/traders**
```json
响应: {
"traders": [
{
"id": "string",
"name": "string",
"status": "running|stopped",
"balance": 1000.0,
"roi": 5.2
}
]
}
```
*（完整 API 参考：api-reference.md - 即将推出）*
---
## 🧪 测试架构
### 当前状态
- ⚠️ 尚无单元测试
- ⚠️ 仅手动测试
- ⚠️ 测试网验证
### 计划的测试策略
**单元测试（优先级 1）**
```
trader/binance_futures_test.go
- 模拟 API 响应
- 测试精度处理
- 验证订单构造
```
**集成测试（优先级 2）**
```
- 端到端交易流程（测试网）
- 多交易员场景
- 数据库操作
```
**前端测试（优先级 3）**
```
- 组件测试（Vitest + React Testing Library）
- API 集成测试
- E2E 测试（Playwright）
```
*（测试指南：testing-guide.md - 即将推出）*
---
## 🔧 开发工具
### 构建与运行
```bash
# 后端
go build -o nofx
./nofx
# 前端
cd web
npm run dev
# Docker
docker compose up --build
```
### 代码质量
```bash
# 格式化 Go 代码
go fmt ./...
# Lint（如果配置）
golangci-lint run
# TypeScript 类型检查
cd web && npm run build
```
---
## 📈 性能考虑
### 后端
- **并发：** 每个交易员在独立的 goroutine 中运行
- **数据库：** SQLite（适用于 <100 个交易员）
- **API 速率限制：** 按交易所处理
- **内存：** 每个交易员 ~50-100MB
### 前端
- **数据获取：** SWR，5-10 秒轮询
- **状态：** Zustand（轻量级）
- **包大小：** ~500KB（gzipped）
---
## 🔮 未来架构计划
### 计划改进
1. **微服务拆分**（如需扩展）
- 独立的决策引擎服务
- 市场数据服务
- 执行服务
2. **数据库迁移**
- 生产环境使用 Mysql (>100 个交易员）
- Redis 缓存
3. **事件驱动架构**
- WebSocket 实时更新
- 消息队列（RabbitMQ/NATS）
4. **Kubernetes 部署**
- Helm charts
- 自动扩展
- 高可用性
---
## 🆘 开发者资源
**想要贡献？**
- 阅读[贡献指南](../../CONTRIBUTING.md)
- 查看[开放问题](https://github.com/tinkle-community/nofx/issues)
- 加入 [Telegram 社区](https://t.me/nofx_dev_community)
**需要澄清？**
- 开启 [GitHub 讨论](https://github.com/tinkle-community/nofx/discussions)
- 在 Telegram 提问
---
## 📚 相关文档
- [快速开始](../getting-started/README.zh-CN.md) - 设置和部署
- [贡献指南](../../CONTRIBUTING.md) - 如何贡献
- [社区](../community/README.md) - 悬赏和认可
---
[← 返回文档首页](../README.md)

233
docs/community/README.md Normal file
View File

@@ -0,0 +1,233 @@
# 👥 NOFX Community
Welcome to the NOFX community! This section contains everything you need to contribute and participate.
---
## 🤝 How to Contribute
### Getting Started
1. **Read the Guides**
- [Contributing Guide](../../CONTRIBUTING.md) - Complete contribution workflow
- [Code of Conduct](../../CODE_OF_CONDUCT.md) - Community standards
- [Security Policy](../../SECURITY.md) - Report vulnerabilities
2. **Find Something to Work On**
- Browse [GitHub Issues](https://github.com/tinkle-community/nofx/issues)
- Look for `good first issue` label
- Check out [bounty tasks](#-bounty-program)
3. **Join the Community**
- 💬 [Telegram Developer Community](https://t.me/nofx_dev_community)
- 🐦 [Twitter @nofx_ai](https://x.com/nofx_ai)
- 🐙 [GitHub Discussions](https://github.com/tinkle-community/nofx/discussions)
---
## 💰 Bounty Program
### Active Bounties
NOFX offers bounties for valuable contributions:
| Category | Reward Range | Examples |
|----------|--------------|----------|
| 🥇 Major Features | $500-1000 | Exchange integration, core architecture |
| 🥈 Medium Features | $200-500 | WebSocket support, new AI models |
| 🥉 Small Features | $50-200 | Bug fixes, UI improvements, documentation |
### How to Claim Bounties
**📖 Complete Guide:** [bounty-guide.md](bounty-guide.md)
**Quick Steps:**
1. Find issue tagged `[BOUNTY]`
2. Comment with your proposal
3. Wait for approval
4. Work on the task
5. Submit PR with demo
6. Get paid after merge!
### Current Bounty Tasks
| Task | Reward | Difficulty | Status |
|------|--------|------------|--------|
| [Hyperliquid Integration](bounty-hyperliquid.md) | TBD | Hard | 🟡 Open |
| [Aster DEX Integration](bounty-aster.md) | TBD | Medium | ✅ Completed |
---
## 🏆 Recognition
### Ways to Get Recognized
**Contributor Levels:**
- 🌟 **Active Contributor** - Submit quality PRs
- ⭐ **Trusted Contributor** - 3+ merged PRs, given review rights
- 💎 **Core Team** - Top contributors, invited by maintainers
**Benefits:**
- Listed in README and release notes
- Direct access to maintainer discussions
- Priority support for your issues
- Invitation to private roadmap planning
### Hall of Fame
**Top Contributors:**
- Coming soon! Be the first! 🚀
---
## 📋 Contribution Types
### Code Contributions
- New exchange integrations
- AI model adapters
- Bug fixes and improvements
- Performance optimizations
**Required:**
- ✅ Code compiles and runs
- ✅ Follows code style guidelines
- ✅ Includes basic tests (preferred)
- ✅ Updates documentation if needed
### Documentation
- Tutorial writing
- Translation (中文, Русский, Українська)
- FAQ updates
- Video guides
**Rewards:**
- $50-200 for comprehensive guides
- Recognition in docs
- Contributor badge
### Testing & QA
- Bug reports with reproduction steps
- Security vulnerability reports (see [Security Policy](../../SECURITY.md))
- Testnet verification
- Performance testing
**Rewards:**
- $50-500 for critical bug finds
- Up to $1000 for security vulnerabilities
- Recognition in security hall of fame
---
## 🌍 Community Channels
### Primary Channels
| Platform | Purpose | Link |
|----------|---------|------|
| 💬 Telegram | Real-time chat, questions | [Join](https://t.me/nofx_dev_community) |
| 🐙 GitHub | Issues, PRs, discussions | [Visit](https://github.com/tinkle-community/nofx) |
| 🐦 Twitter | Announcements, updates | [@nofx_ai](https://x.com/nofx_ai) |
### Core Team
- **Tinkle** - [@Web3Tinkle](https://x.com/Web3Tinkle)
- **Zack** - [@0x_ZackH](https://x.com/0x_ZackH)
**Contact:**
- Technical questions → Telegram or GitHub Issues
- Business inquiries → Twitter DM to core team
- Security reports → [SECURITY.md](../../SECURITY.md)
---
## 📅 Community Events
### Regular Activities
- **Weekly Updates** - Development progress (Telegram)
- **Monthly AMA** - Ask maintainers anything
- **Quarterly Roadmap** - Future plans discussion
### Upcoming Events
- *No scheduled events yet*
**Want to organize an event?**
- Contact core team on Telegram
- Propose in GitHub Discussions
- Tweet and tag @nofx_ai
---
## 🎓 Learning Resources
### For Contributors
**Understanding NOFX:**
- [System Architecture](../architecture/README.md) *(coming soon)*
- [API Reference](../architecture/api-reference.md) *(coming soon)*
- [Database Schema](../architecture/database-schema.md) *(coming soon)*
**Learning Materials:**
- Go programming: [Tour of Go](https://go.dev/tour/)
- React/TypeScript: [React Docs](https://react.dev/)
- Trading basics: [Binance Academy](https://academy.binance.com/)
### Recommended Reading
1. **Before Contributing:**
- [Contributing Guide](../../CONTRIBUTING.md)
- [Code of Conduct](../../CODE_OF_CONDUCT.md)
2. **For Exchange Integration:**
- [Hyperliquid Bounty](bounty-hyperliquid.md)
- [Aster Bounty](bounty-aster.md)
- Existing code: `trader/binance_futures.go`
3. **For AI Features:**
- [Custom API Guide](../getting-started/custom-api.md)
- MCP client code: `mcp/client.go`
- Decision engine: `decision/engine.go`
---
## 🛡️ Community Guidelines
### Our Values
- **Respect** - Treat everyone with courtesy
- **Transparency** - Open communication and decisions
- **Quality** - High standards for contributions
- **Collaboration** - Work together, help each other
### Not Acceptable
- ❌ Harassment or discrimination
- ❌ Spam or self-promotion
- ❌ Sharing malicious code
- ❌ Violating [Code of Conduct](../../CODE_OF_CONDUCT.md)
**Violations will result in:**
1. Warning
2. Temporary ban
3. Permanent ban (serious cases)
---
## 📊 Community Stats
| Metric | Count |
|--------|-------|
| GitHub Stars | Check [repo](https://github.com/tinkle-community/nofx) |
| Contributors | 21+ |
| Open Issues | Check [issues](https://github.com/tinkle-community/nofx/issues) |
| Merged PRs | Check [pulls](https://github.com/tinkle-community/nofx/pulls?q=is%3Apr+is%3Amerged) |
---
## 🚀 Quick Links
- **Want to contribute code?** → [Contributing Guide](../../CONTRIBUTING.md)
- **Want to claim bounty?** → [Bounty Guide](bounty-guide.md)
- **Found a security issue?** → [Security Policy](../../SECURITY.md)
- **Have questions?** → [Telegram Community](https://t.me/nofx_dev_community)
---
[← Back to Documentation Home](../README.md)

157
docs/community/bounty-aster.md Normal file
View File

@@ -0,0 +1,157 @@
# 🚀 [BOUNTY] Integrate Aster Exchange Support
## 💰 Bounty Reward
**To be discussed** - Open to proposals from contributors
## 📋 Overview
We're looking for contributors to add Aster exchange support to NOFX AI Trading System. Currently supports Binance Futures, seeking to expand to Aster perpetual contracts.
## 🎯 Task Requirements
### Core Features to Implement
#### 1. **Aster API Integration**
- [ ] Account management (balance, positions, margin)
- [ ] Market data fetching (K-lines, order book, trades)
- [ ] Order execution (market/limit orders)
- [ ] Position management (open, close, modify)
- [ ] Websocket real-time data stream (if available)
#### 2. **Adapter Layer**
- [ ] Create `trader/aster_perpetual.go` adapter
- [ ] Implement unified interface compatible with existing `BinanceFuturesClient`
- [ ] Handle Aster-specific features (if any)
#### 3. **Configuration Support**
```json
{
"traders": [
{
"id": "aster_trader",
"name": "Aster AI Trader",
"exchange": "aster", // NEW
"aster_api_key": "xxx",
"aster_secret_key": "xxx",
"ai_model": "deepseek",
"initial_balance": 1000.0
}
]
}
```
#### 4. **Risk Control Adaptation**
- [ ] Adapt position limits for Aster specs
- [ ] Handle leverage rules (may differ from Binance)
- [ ] Implement liquidation price calculation
- [ ] Funding rate integration (if applicable)
#### 5. **Testing & Documentation**
- [ ] Unit tests for API wrapper
- [ ] Integration tests with testnet (if available)
- [ ] Update README with Aster setup guide
- [ ] Add Aster-specific troubleshooting docs
## 📚 Technical References
**Aster Resources:**
- Official Website: [Add Aster exchange URL]
- API Documentation: [Add Aster API docs URL]
- SDK/Libraries: [Add if available]
**NOFX Architecture:**
- See `trader/binance_futures.go` as reference implementation
- Main trading logic: `trader/auto_trader.go`
- Configuration: `config.json` structure
## 🔧 Implementation Guidelines
### File Structure
```
trader/
├── binance_futures.go (existing reference)
├── aster_perpetual.go (NEW - to implement)
└── exchange_interface.go (NEW - unified interface)
config/
└── config.go (UPDATE - add Aster config)
```
### Interface to Implement
```go
type ExchangeClient interface {
// Account
GetAccount() (*AccountInfo, error)
GetPositions() ([]*Position, error)
// Market Data
GetKlines(symbol, interval string, limit int) ([]*Kline, error)
GetTicker(symbol string) (*Ticker, error)
// Trading
CreateOrder(params *OrderParams) (*Order, error)
ClosePosition(symbol, side string) error
// Risk Management
SetLeverage(symbol string, leverage int) error
GetLiquidationPrice(position *Position) (float64, error)
}
```
## ✅ Acceptance Criteria
**Minimum Requirements:**
- [ ] Can connect to Aster testnet/mainnet
- [ ] Fetch real-time account balance and positions
- [ ] Execute market orders successfully
- [ ] Close positions correctly
- [ ] Calculate accurate P/L
- [ ] No breaking changes to existing Binance integration
**Bonus Points:**
- [ ] Websocket streaming for real-time data
- [ ] Support for limit orders and stop-loss/take-profit
- [ ] Multi-exchange competition mode (Binance vs Aster)
- [ ] Performance comparison dashboard
## 📝 How to Contribute
1. **Comment on this issue** to express interest
2. **Fork the repository** and create a feature branch
3. **Implement the integration** following guidelines above
4. **Test thoroughly** on testnet before mainnet
5. **Submit a Pull Request** with:
- Code changes
- Tests
- Documentation updates
- Demo video/screenshots
## 🤝 Support & Questions
- Ask questions in this issue's comments
- Join our Telegram: [NOFX Developer Community](https://t.me/nofx_dev_community)
- Reference existing code: `trader/binance_futures.go`
## ⚠️ Important Notes
- **Test on testnet first** - Do NOT test with real funds initially
- **Maintain backward compatibility** - Existing Binance users should not be affected
- **Code quality** - Follow existing code style and patterns
- **Security** - Handle API keys securely, no hardcoded credentials
## 🔍 Research Needed
**Before starting, please investigate:**
- [ ] Does Aster provide a public API? (REST/Websocket)
- [ ] Is there an official SDK or code examples?
- [ ] Does Aster support testnet for development?
- [ ] What are the API rate limits?
- [ ] What symbols/markets are available?
- [ ] Are there any unique features or limitations?
**Share your findings in the comments!**
---
**Ready to contribute?** Comment below or start working and submit a PR!
**Questions?** Feel free to ask in the comments or on Telegram.

224
docs/community/bounty-guide.md Normal file
View File

@@ -0,0 +1,224 @@
# 📝 如何在 GitHub 发布集成任务 (Bounty)
## 🎯 发布步骤
### 方法 1: 直接创建 GitHub Issue（推荐）
1. **访问项目 Issues 页面**
```
https://github.com/tinkle-community/nofx/issues
```
2. **点击 "New Issue" 按钮**
3. **选择 "Feature Request" 模板**（如果可用）
4. **填写 Issue 内容**
#### Hyperliquid 集成 Issue：
```markdown
标题：[BOUNTY] Integrate Hyperliquid Exchange Support 🚀
内容：复制 INTEGRATION_BOUNTY_HYPERLIQUID.md 的全部内容
```
#### Aster 集成 Issue：
```markdown
标题：[BOUNTY] Integrate Aster Exchange Support 🚀
内容：复制 INTEGRATION_BOUNTY_ASTER.md 的全部内容
```
5. **添加标签 (Labels)**
- `enhancement` - 新功能
- `bounty` - 悬赏任务
- `help wanted` - 寻求帮助
- `good first issue` - 适合新手（如果适用）
6. **点击 "Submit new issue"**
---
### 方法 2: 使用 GitHub CLI（适合命令行用户）
```bash
# 安装 GitHub CLI (如果还没安装)
brew install gh # macOS
# 或访问 https://cli.github.com/
# 登录
gh auth login
# 创建 Hyperliquid 集成 Issue
gh issue create \
--title "[BOUNTY] Integrate Hyperliquid Exchange Support 🚀" \
--body-file INTEGRATION_BOUNTY_HYPERLIQUID.md \
--label "enhancement,bounty,help wanted"
# 创建 Aster 集成 Issue
gh issue create \
--title "[BOUNTY] Integrate Aster Exchange Support 🚀" \
--body-file INTEGRATION_BOUNTY_ASTER.md \
--label "enhancement,bounty,help wanted"
```
---
## 💰 设置悬赏金额
### 选项 1: 直接在 GitHub Issue 说明
在 Issue 开头写明：
```markdown
## 💰 Bounty Reward
- **$500 USD** for complete Hyperliquid integration
- **Bonus $200** for websocket real-time data support
- **Bonus $100** for comprehensive tests and docs
```
### 选项 2: 使用悬赏平台
**Gitcoin Bounties**
- 网站：https://gitcoin.co/
- 支持加密货币支付
- 步骤：
1. 创建 Gitcoin 账户
2. 点击 "Post a Bounty"
3. 链接到你的 GitHub Issue
4. 设置奖金金额和条件
**Bountysource**
- 网站：https://www.bountysource.com/
- 支持法币和加密货币
- 步骤：
1. 导入 GitHub Issue
2. 设置悬赏金额
3. 托管资金直到完成
**IssueHunt**
- 网站：https://issuehunt.io/
- 专注于开源项目
- 步骤：
1. 连接 GitHub 仓库
2. 为特定 Issue 设置悬赏
3. 贡献者完成后自动支付
---
## 📢 推广你的 Bounty
### 1. 社交媒体宣传
**Twitter/X:**
```
🚀 $500 Bounty! 🚀
Looking for devs to integrate Hyperliquid exchange into NOFX AI Trading System
✅ Add perpetual contracts support
✅ Unified API interface
✅ Full testing & docs
Issue: [GitHub链接]
Details: [详情链接]
#Bounty #OpenSource #Crypto #Trading
```
**Telegram:**
- 在 NOFX 开发者社区发布：https://t.me/nofx_dev_community
- 在相关的开发者群组分享
### 2. 开发者社区
**Reddit:**
- r/CryptoCurrency
- r/algotrading
- r/opensource
- r/forhire
**Discord:**
- 相关的加密货币交易社区
- 开发者频道
### 3. 开发者平台
**Dev.to / Hashnode:**
写一篇博客：
- 介绍项目
- 说明集成需求
- 展示悬赏奖励
- 链接到 GitHub Issue
---
## 📋 Issue 管理最佳实践
### 1. 及时回复
- 在24小时内回复所有问题
- 提供清晰的技术指导
- 鼓励潜在贡献者
### 2. 更新进度
定期更新 Issue，说明：
- 当前进展
- 已有贡献者
- 剩余工作
- 截止日期（如果有）
### 3. 设置里程碑
```markdown
## 📅 Milestones
**Phase 1 (Week 1-2):** API Wrapper
- [ ] Basic API integration
- [ ] Account & position fetching
**Phase 2 (Week 3):** Trading Functions
- [ ] Order execution
- [ ] Position management
**Phase 3 (Week 4):** Testing & Docs
- [ ] Comprehensive tests
- [ ] Documentation updates
```
### 4. 评审 PR
当有人提交 Pull Request：
- 快速进行代码审查
- 提供建设性反馈
- 测试功能是否正常
- 合并后及时支付赏金
---
## ⚠️ 注意事项
### 法律 & 合规
- ✅ 明确说明这是开源贡献，不是雇佣关系
- ✅ 确保贡献者同意 MIT License
- ✅ 保留最终合并决定权
### 资金管理
- ✅ 使用托管服务（Gitcoin、Bountysource）
- ✅ 在 Issue 中明确支付条件
- ✅ 完成后及时支付
### 质量控制
- ✅ 要求代码审查
- ✅ 必须有测试覆盖
- ✅ 必须有文档更新
- ✅ 不破坏现有功能
---
## 📞 需要帮助？
- **GitHub Issues**: https://github.com/tinkle-community/nofx/issues
- **Telegram**: https://t.me/nofx_dev_community
- **Twitter/X**: [@Web3Tinkle](https://x.com/Web3Tinkle)
---
**祝你成功招募到优秀的开发者！** 🎉

145
docs/community/bounty-hyperliquid.md Normal file
View File

@@ -0,0 +1,145 @@
# 🚀 [BOUNTY] Integrate Hyperliquid Exchange Support
## 💰 Bounty Reward
**To be discussed** - Open to proposals from contributors
## 📋 Overview
We're looking for contributors to add Hyperliquid exchange support to NOFX AI Trading System. Currently supports Binance Futures, seeking to expand to Hyperliquid perpetual contracts.
## 🎯 Task Requirements
### Core Features to Implement
#### 1. **Hyperliquid API Integration**
- [ ] Account management (balance, positions, margin)
- [ ] Market data fetching (K-lines, order book, trades)
- [ ] Order execution (market/limit orders)
- [ ] Position management (open, close, modify)
- [ ] Websocket real-time data stream
#### 2. **Adapter Layer**
- [ ] Create `trader/hyperliquid_perpetual.go` adapter
- [ ] Implement unified interface compatible with existing `BinanceFuturesClient`
- [ ] Handle Hyperliquid-specific features (if any)
#### 3. **Configuration Support**
```json
{
"traders": [
{
"id": "hyperliquid_trader",
"name": "Hyperliquid AI Trader",
"exchange": "hyperliquid", // NEW
"hyperliquid_api_key": "xxx",
"hyperliquid_secret_key": "xxx",
"ai_model": "deepseek",
"initial_balance": 1000.0
}
]
}
```
#### 4. **Risk Control Adaptation**
- [ ] Adapt position limits for Hyperliquid specs
- [ ] Handle leverage rules (may differ from Binance)
- [ ] Implement liquidation price calculation
- [ ] Funding rate integration
#### 5. **Testing & Documentation**
- [ ] Unit tests for API wrapper
- [ ] Integration tests with testnet
- [ ] Update README with Hyperliquid setup guide
- [ ] Add Hyperliquid-specific troubleshooting docs
## 📚 Technical References
**Hyperliquid Resources:**
- Official Docs: https://hyperliquid.gitbook.io/hyperliquid-docs
- API Documentation: https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api
- SDK Examples: https://github.com/hyperliquid-dex
**NOFX Architecture:**
- See `trader/binance_futures.go` as reference implementation
- Main trading logic: `trader/auto_trader.go`
- Configuration: `config.json` structure
## 🔧 Implementation Guidelines
### File Structure
```
trader/
├── binance_futures.go (existing reference)
├── hyperliquid_perpetual.go (NEW - to implement)
└── exchange_interface.go (NEW - unified interface)
config/
└── config.go (UPDATE - add Hyperliquid config)
```
### Interface to Implement
```go
type ExchangeClient interface {
// Account
GetAccount() (*AccountInfo, error)
GetPositions() ([]*Position, error)
// Market Data
GetKlines(symbol, interval string, limit int) ([]*Kline, error)
GetTicker(symbol string) (*Ticker, error)
// Trading
CreateOrder(params *OrderParams) (*Order, error)
ClosePosition(symbol, side string) error
// Risk Management
SetLeverage(symbol string, leverage int) error
GetLiquidationPrice(position *Position) (float64, error)
}
```
## ✅ Acceptance Criteria
**Minimum Requirements:**
- [ ] Can connect to Hyperliquid testnet/mainnet
- [ ] Fetch real-time account balance and positions
- [ ] Execute market orders successfully
- [ ] Close positions correctly
- [ ] Calculate accurate P/L
- [ ] No breaking changes to existing Binance integration
**Bonus Points:**
- [ ] Websocket streaming for real-time data
- [ ] Support for limit orders and stop-loss/take-profit
- [ ] Multi-exchange competition mode (Binance vs Hyperliquid)
- [ ] Performance comparison dashboard
## 📝 How to Contribute
1. **Comment on this issue** to express interest
2. **Fork the repository** and create a feature branch
3. **Implement the integration** following guidelines above
4. **Test thoroughly** on testnet before mainnet
5. **Submit a Pull Request** with:
- Code changes
- Tests
- Documentation updates
- Demo video/screenshots
## 🤝 Support & Questions
- Ask questions in this issue's comments
- Join our Telegram: [NOFX Developer Community](https://t.me/nofx_dev_community)
- Reference existing code: `trader/binance_futures.go`
## ⚠️ Important Notes
- **Test on testnet first** - Do NOT test with real funds initially
- **Maintain backward compatibility** - Existing Binance users should not be affected
- **Code quality** - Follow existing code style and patterns
- **Security** - Handle API keys securely, no hardcoded credentials
---
**Ready to contribute?** Comment below or start working and submit a PR!
**Questions?** Feel free to ask in the comments or on Telegram.

127
docs/getting-started/README.md Normal file
View File

@@ -0,0 +1,127 @@
# 🚀 Getting Started with NOFX
**Language:** [English](README.md) | [中文](README.zh-CN.md)
This section contains all the documentation you need to get NOFX up and running.
## 📋 Deployment Options
Choose the method that best fits your needs:
### 🐳 Docker Deployment (Recommended)
**Best for:** Beginners, quick setup, production deployments
- **English:** [docker-deploy.en.md](docker-deploy.en.md)
- **中文:** [docker-deploy.zh-CN.md](docker-deploy.zh-CN.md)
**Pros:**
- ✅ One-command setup
- ✅ All dependencies included
- ✅ Easy to update and manage
- ✅ Isolated environment
**Quick Start:**
```bash
cp config.example.jsonc config.json
./start.sh start --build
```
---
### 🔧 PM2 Deployment
**Best for:** Advanced users, development, custom setups
- **English:** [pm2-deploy.en.md](pm2-deploy.en.md)
- **中文:** [pm2-deploy.md](pm2-deploy.md)
**Pros:**
- ✅ Direct process control
- ✅ Better for development
- ✅ Lower resource usage
- ✅ More flexible
**Quick Start:**
```bash
go build -o nofx
cd web && npm install && npm run build
pm2 start ecosystem.config.js
```
---
## 🤖 AI Configuration
### Custom AI Providers
- **English:** [custom-api.en.md](custom-api.en.md)
- **中文:** [custom-api.md](custom-api.md)
Use custom AI models or third-party OpenAI-compatible APIs:
- Custom DeepSeek endpoints
- Self-hosted models
- Other LLM providers
---
## 🔑 Prerequisites
Before starting, ensure you have:
### For Docker Method:
- ✅ Docker 20.10+
- ✅ Docker Compose V2
### For Manual Method:
- ✅ Go 1.21+
- ✅ Node.js 18+
- ✅ TA-Lib library
- ✅ PM2 (optional)
---
## 📚 Next Steps
After deployment:
1. **Configure AI Models** → Web interface at http://localhost:3000
2. **Set Up Exchange** → Add Binance/Hyperliquid credentials
3. **Create Traders** → Combine AI models with exchanges
4. **Start Trading** → Monitor performance in dashboard
---
## ⚠️ Important Notes
**Before Trading:**
- ⚠️ Test on testnet first
- ⚠️ Start with small amounts
- ⚠️ Understand the risks
- ⚠️ Read [Security Policy](../../SECURITY.md)
**API Keys:**
- 🔑 Never commit API keys to git
- 🔑 Use environment variables
- 🔑 Restrict IP access
- 🔑 Enable 2FA on exchanges
---
## 🆘 Troubleshooting
**Common Issues:**
1. **Docker build fails** → Check Docker version, update to 20.10+
2. **TA-Lib not found** → `brew install ta-lib` (macOS) or `apt-get install libta-lib0-dev` (Ubuntu)
3. **Port 8080 in use** → Change `API_PORT` in .env file
4. **Frontend won't connect** → Check backend is running on port 8080
**Need more help?**
- 📖 [FAQ](../guides/faq.zh-CN.md)
- 💬 [Telegram Community](https://t.me/nofx_dev_community)
- 🐛 [GitHub Issues](https://github.com/tinkle-community/nofx/issues)
---
[← Back to Documentation Home](../README.md)

125
docs/getting-started/README.zh-CN.md Normal file
View File

@@ -0,0 +1,125 @@
# 🚀 NOFX 快速开始
本节包含让 NOFX 运行起来所需的所有文档。
## 📋 部署选项
选择最适合您的方式：
### 🐳 Docker 部署（推荐）
**适合：** 初学者、快速部署、生产环境
- **中文文档：** [docker-deploy.zh-CN.md](docker-deploy.zh-CN.md)
- **English:** [docker-deploy.en.md](docker-deploy.en.md)
**优势：**
- ✅ 一键启动
- ✅ 包含所有依赖
- ✅ 易于更新和管理
- ✅ 隔离环境
**快速开始：**
```bash
cp config.example.jsonc config.json
./start.sh start --build
```
---
### 🔧 PM2 部署
**适合：** 进阶用户、开发环境、自定义设置
- **中文文档：** [pm2-deploy.md](pm2-deploy.md)
- **English:** [pm2-deploy.en.md](pm2-deploy.en.md)
**优势：**
- ✅ 直接进程控制
- ✅ 更适合开发
- ✅ 资源占用更低
- ✅ 更灵活
**快速开始：**
```bash
go build -o nofx
cd web && npm install && npm run build
pm2 start ecosystem.config.js
```
---
## 🤖 AI 配置
### 自定义 AI 提供商
- **中文文档：** [custom-api.md](custom-api.md)
- **English:** [custom-api.en.md](custom-api.en.md)
使用自定义 AI 模型或第三方 OpenAI 兼容 API：
- 自定义 DeepSeek 端点
- 本地部署的模型
- 其他 LLM 提供商
---
## 🔑 环境要求
开始之前，请确保已安装：
### Docker 方式：
- ✅ Docker 20.10+
- ✅ Docker Compose V2
### 手动部署方式：
- ✅ Go 1.21+
- ✅ Node.js 18+
- ✅ TA-Lib 库
- ✅ PM2（可选）
---
## 📚 下一步
部署完成后：
1. **配置 AI 模型** → 访问 Web 界面 http://localhost:3000
2. **设置交易所** → 添加 Binance/Hyperliquid 凭证
3. **创建交易员** → 将 AI 模型与交易所结合
4. **开始交易** → 在仪表板中监控表现
---
## ⚠️ 重要提示
**交易前：**
- ⚠️ 先在测试网测试
- ⚠️ 从小金额开始
- ⚠️ 了解风险
- ⚠️ 阅读[安全策略](../../SECURITY.md)
**API 密钥：**
- 🔑 永远不要提交 API 密钥到 git
- 🔑 使用环境变量
- 🔑 限制 IP 访问
- 🔑 在交易所启用 2FA
---
## 🆘 故障排除
**常见问题：**
1. **Docker 构建失败** → 检查 Docker 版本，更新到 20.10+
2. **找不到 TA-Lib** → `brew install ta-lib` (macOS) 或 `apt-get install libta-lib0-dev` (Ubuntu)
3. **端口 8080 被占用** → 在 .env 文件中更改 `API_PORT`
4. **前端无法连接** → 检查后端是否在端口 8080 上运行
**需要更多帮助？**
- 📖 [常见问题](../guides/faq.zh-CN.md)
- 💬 [Telegram 社区](https://t.me/nofx_dev_community)
- 🐛 [GitHub Issues](https://github.com/tinkle-community/nofx/issues)
---
[← 返回文档首页](../README.md)

207
docs/getting-started/custom-api.en.md Normal file
View File

@@ -0,0 +1,207 @@
# Custom AI API Usage Guide
## Features
NOFX now supports using any OpenAI-compatible API format, including:
- OpenAI official API (gpt-4o, gpt-4-turbo, etc.)
- OpenRouter (access to multiple models)
- Locally deployed models (Ollama, LM Studio, etc.)
- Other OpenAI-compatible API services
## Configuration Method
~~Add trader using custom API in `config.json` (deprecated):~~
*Note: Custom APIs and traders are now configured through the Web interface. config.json only retains basic settings.*
```json
{
"traders": [
{
"id": "trader_custom",
"name": "My Custom AI Trader",
"ai_model": "custom",
"exchange": "binance",
"binance_api_key": "your_binance_api_key",
"binance_secret_key": "your_binance_secret_key",
"custom_api_url": "https://api.openai.com/v1",
"custom_api_key": "sk-your-openai-api-key",
"custom_model_name": "gpt-4o",
"initial_balance": 1000,
"scan_interval_minutes": 3
}
]
}
```
## Configuration Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ai_model` | string | ✅ | Set to `"custom"` to enable custom API |
| `custom_api_url` | string | ✅ | API Base URL (without `/chat/completions`). Special usage: If ending with `#`, use full URL (no auto path append) |
| `custom_api_key` | string | ✅ | API key |
| `custom_model_name` | string | ✅ | Model name (e.g. `gpt-4o`, `claude-3-5-sonnet`, etc.) |
## Usage Examples
### 1. OpenAI Official API
```json
{
"ai_model": "custom",
"custom_api_url": "https://api.openai.com/v1",
"custom_api_key": "sk-proj-xxxxx",
"custom_model_name": "gpt-4o"
}
```
### 2. OpenRouter
```json
{
"ai_model": "custom",
"custom_api_url": "https://openrouter.ai/api/v1",
"custom_api_key": "sk-or-xxxxx",
"custom_model_name": "anthropic/claude-3.5-sonnet"
}
```
### 3. Local Ollama
```json
{
"ai_model": "custom",
"custom_api_url": "http://localhost:11434/v1",
"custom_api_key": "ollama",
"custom_model_name": "llama3.1:70b"
}
```
### 4. Azure OpenAI
```json
{
"ai_model": "custom",
"custom_api_url": "https://your-resource.openai.azure.com/openai/deployments/your-deployment",
"custom_api_key": "your-azure-api-key",
"custom_model_name": "gpt-4"
}
```
### 5. Using Full Custom Path (append #)
For certain special API endpoints that already include the full path (including `/chat/completions` or other custom paths), you can append `#` at the end of the URL to force using the full URL:
```json
{
"ai_model": "custom",
"custom_api_url": "https://api.example.com/v2/ai/chat/completions#",
"custom_api_key": "your-api-key",
"custom_model_name": "custom-model"
}
```
**Note**: The `#` will be automatically removed, and the actual request will be sent to `https://api.example.com/v2/ai/chat/completions`
## Compatibility Requirements
Custom APIs must:
1. Support OpenAI Chat Completions format
2. Accept `POST` requests to `/chat/completions` endpoint (or append `#` at URL end for custom path)
3. Support `Authorization: Bearer {api_key}` authentication
4. Return standard OpenAI response format
## Important Notes
1. **URL Format**: `custom_api_url` should be the Base URL, system will auto-append `/chat/completions`
- ✅ Correct: `https://api.openai.com/v1`
- ❌ Wrong: `https://api.openai.com/v1/chat/completions`
- 🔧 **Special usage**: If you need to use a full custom path (without auto-appending `/chat/completions`), append `#` at the URL end
- Example: `https://api.example.com/custom/path/chat/completions#`
- System will automatically remove `#` and use the full URL directly
2. **Model Name**: Ensure `custom_model_name` exactly matches the model name supported by your API provider
3. **API Key**: Some locally deployed models may not require a real API key, you can fill in any string
4. **Timeout Settings**: Default timeout is 120 seconds, may need adjustment if model response is slow
## Multi-AI Comparison Trading
You can configure multiple traders with different AIs for comparison:
```json
{
"traders": [
{
"id": "deepseek_trader",
"ai_model": "deepseek",
"deepseek_key": "sk-xxxxx",
...
},
{
"id": "gpt4_trader",
"ai_model": "custom",
"custom_api_url": "https://api.openai.com/v1",
"custom_api_key": "sk-xxxxx",
"custom_model_name": "gpt-4o",
...
},
{
"id": "claude_trader",
"ai_model": "custom",
"custom_api_url": "https://openrouter.ai/api/v1",
"custom_api_key": "sk-or-xxxxx",
"custom_model_name": "anthropic/claude-3.5-sonnet",
...
}
]
}
```
## Troubleshooting
### Issue: Configuration Validation Failed
**Error Message**: `使用自定义API时必须配置custom_api_url` (custom_api_url must be configured when using custom API)
**Solution**: After setting `ai_model: "custom"`, ensure you also configure:
- `custom_api_url`
- `custom_api_key`
- `custom_model_name`
### Issue: API Call Failed
**Possible Causes**:
1. URL format error
- Normal usage: Should not include `/chat/completions` (system will auto-append)
- Special usage: If full path is needed, remember to append `#` at URL end
2. Invalid API key
3. Incorrect model name
4. Network connection issues
**Debug Method**: Check error messages in logs, usually includes HTTP status code and error details
## Backward Compatibility
Existing `deepseek` and `qwen` configurations are unaffected and can continue to be used:
```json
{
"ai_model": "deepseek",
"deepseek_key": "sk-xxxxx"
}
```
Or
```json
{
"ai_model": "qwen",
"qwen_key": "sk-xxxxx"
}
```

207
docs/getting-started/custom-api.md Normal file
View File

@@ -0,0 +1,207 @@
# 自定义 AI API 使用指南
## 功能说明
现在 NOFX 支持使用任何 OpenAI 格式兼容的 API，包括：
- OpenAI 官方 API (gpt-4o, gpt-4-turbo 等)
- OpenRouter (可访问多种模型)
- 本地部署的模型 (Ollama, LM Studio 等)
- 其他兼容 OpenAI 格式的 API 服务
## 配置方式
在 `config.json` 中添加使用自定义 API 的 trader（~~已弃用~~）：
*注意：现在通过Web界面配置自定义API和交易员，config.json仅保留基础设置*
```json
{
"traders": [
{
"id": "trader_custom",
"name": "My Custom AI Trader",
"ai_model": "custom",
"exchange": "binance",
"binance_api_key": "your_binance_api_key",
"binance_secret_key": "your_binance_secret_key",
"custom_api_url": "https://api.openai.com/v1",
"custom_api_key": "sk-your-openai-api-key",
"custom_model_name": "gpt-4o",
"initial_balance": 1000,
"scan_interval_minutes": 3
}
]
}
```
## 配置字段说明
| 字段 | 类型 | 必需 | 说明 |
|-----|------|------|------|
| `ai_model` | string | ✅ | 设置为 `"custom"` 启用自定义 API |
| `custom_api_url` | string | ✅ | API 的 Base URL (不含 `/chat/completions`)。特殊用法：如果以 `#` 结尾，则使用完整 URL（不自动添加路径） |
| `custom_api_key` | string | ✅ | API 密钥 |
| `custom_model_name` | string | ✅ | 模型名称 (如 `gpt-4o`, `claude-3-5-sonnet` 等) |
## 使用示例
### 1. OpenAI 官方 API
```json
{
"ai_model": "custom",
"custom_api_url": "https://api.openai.com/v1",
"custom_api_key": "sk-proj-xxxxx",
"custom_model_name": "gpt-4o"
}
```
### 2. OpenRouter
```json
{
"ai_model": "custom",
"custom_api_url": "https://openrouter.ai/api/v1",
"custom_api_key": "sk-or-xxxxx",
"custom_model_name": "anthropic/claude-3.5-sonnet"
}
```
### 3. 本地 Ollama
```json
{
"ai_model": "custom",
"custom_api_url": "http://localhost:11434/v1",
"custom_api_key": "ollama",
"custom_model_name": "llama3.1:70b"
}
```
### 4. Azure OpenAI
```json
{
"ai_model": "custom",
"custom_api_url": "https://your-resource.openai.azure.com/openai/deployments/your-deployment",
"custom_api_key": "your-azure-api-key",
"custom_model_name": "gpt-4"
}
```
### 5. 使用完整自定义路径（末尾添加 #）
对于某些特殊的 API 端点，如果已经包含完整路径（包括 `/chat/completions` 或其他自定义路径），可以在 URL 末尾添加 `#` 来强制使用完整 URL：
```json
{
"ai_model": "custom",
"custom_api_url": "https://api.example.com/v2/ai/chat/completions#",
"custom_api_key": "your-api-key",
"custom_model_name": "custom-model"
}
```
**注意**：`#` 会被自动去除，实际请求会发送到 `https://api.example.com/v2/ai/chat/completions`
## 兼容性要求
自定义 API 必须：
1. 支持 OpenAI Chat Completions 格式
2. 接受 `POST` 请求到 `/chat/completions` 端点（或在 URL 末尾添加 `#` 以使用自定义路径）
3. 支持 `Authorization: Bearer {api_key}` 认证
4. 返回标准的 OpenAI 响应格式
## 注意事项
1. **URL 格式**：`custom_api_url` 应该是 Base URL，系统会自动添加 `/chat/completions`
- ✅ 正确：`https://api.openai.com/v1`
- ❌ 错误：`https://api.openai.com/v1/chat/completions`
- 🔧 **特殊用法**：如果需要使用完整的自定义路径（不自动添加 `/chat/completions`），可以在 URL 末尾添加 `#`
- 例如：`https://api.example.com/custom/path/chat/completions#`
- 系统会自动去掉 `#` 并直接使用该完整 URL
2. **模型名称**：确保 `custom_model_name` 与 API 提供商支持的模型名称完全一致
3. **API 密钥**：某些本地部署的模型可能不需要真实的 API 密钥，可以填写任意字符串
4. **超时设置**：默认超时时间为 120 秒，如果模型响应较慢可能需要调整
## 多 AI 对比交易
你可以同时配置多个不同 AI 的 trader 进行对比：
```json
{
"traders": [
{
"id": "deepseek_trader",
"ai_model": "deepseek",
"deepseek_key": "sk-xxxxx",
...
},
{
"id": "gpt4_trader",
"ai_model": "custom",
"custom_api_url": "https://api.openai.com/v1",
"custom_api_key": "sk-xxxxx",
"custom_model_name": "gpt-4o",
...
},
{
"id": "claude_trader",
"ai_model": "custom",
"custom_api_url": "https://openrouter.ai/api/v1",
"custom_api_key": "sk-or-xxxxx",
"custom_model_name": "anthropic/claude-3.5-sonnet",
...
}
]
}
```
## 故障排除
### 问题：配置验证失败
**错误信息**：`使用自定义API时必须配置custom_api_url`
**解决方案**：确保设置了 `ai_model: "custom"` 后，同时配置了：
- `custom_api_url`
- `custom_api_key`
- `custom_model_name`
### 问题：API 调用失败
**可能原因**：
1. URL 格式错误
- 普通用法：不应包含 `/chat/completions`（系统会自动添加）
- 特殊用法：如果需要完整路径，记得在 URL 末尾添加 `#`
2. API 密钥无效
3. 模型名称错误
4. 网络连接问题
**调试方法**：查看日志中的错误信息，通常会包含 HTTP 状态码和错误详情
## 向后兼容性
现有的 `deepseek` 和 `qwen` 配置完全不受影响，可以继续使用：
```json
{
"ai_model": "deepseek",
"deepseek_key": "sk-xxxxx"
}
```
或
```json
{
"ai_model": "qwen",
"qwen_key": "sk-xxxxx"
}
```

473
docs/getting-started/docker-deploy.en.md Normal file
View File

@@ -0,0 +1,473 @@
# 🐳 Docker One-Click Deployment Guide
This guide will help you quickly deploy the NOFX AI Trading Competition System using Docker.
## 📋 Prerequisites
Before you begin, ensure your system has:
- **Docker**: Version 20.10 or higher
- **Docker Compose**: Version 2.0 or higher
### Installing Docker
#### macOS / Windows
Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop/)
#### Linux (Ubuntu/Debian)
> #### Docker Compose Version Notes
>
> **New User Recommendation:**
> - **Use Docker Desktop**: Automatically includes latest Docker Compose, no separate installation needed
> - Simple installation, one-click setup, provides GUI management
> - Supports macOS, Windows, and some Linux distributions
>
> **Upgrading User Note:**
> - **Deprecating standalone docker-compose**: No longer recommended to download the independent Docker Compose binary
> - **Use built-in version**: Docker 20.10+ includes `docker compose` command (with space)
> - If still using old `docker-compose`, please upgrade to new syntax
*Recommended: Use Docker Desktop (if available) or Docker CE with built-in Compose*
```bash
# Install Docker (includes compose)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker
# Verify installation (new command)
docker --version
docker compose --version # Docker 24+ includes this, no separate installation needed
```
## 🚀 Quick Start (3 Steps)
### Step 1: Prepare Configuration File
```bash
# Copy configuration template
cp config.example.jsonc config.json
# Edit configuration file with your API keys
nano config.json # or use any other editor
⚠️ **Note**: Basic config.json is still needed for some settings, but ~~trader configurations~~ are now done through the web interface.
```
**Required fields:**
```json
{
"traders": [
{
"id": "my_trader",
"name": "My AI Trader",
"ai_model": "deepseek",
"binance_api_key": "YOUR_BINANCE_API_KEY", // ← Your Binance API Key
"binance_secret_key": "YOUR_BINANCE_SECRET_KEY", // ← Your Binance Secret Key
"deepseek_key": "YOUR_DEEPSEEK_API_KEY", // ← Your DeepSeek API Key
"initial_balance": 1000.0,
"scan_interval_minutes": 3
}
],
"use_default_coins": true,
"api_server_port": 8080
}
```
### Step 2: One-Click Start
```bash
# Build and start all services (first run)
docker compose up -d --build
# Subsequent starts (without rebuilding)
docker compose up -d
```
**Startup options:**
- `--build`: Build Docker images (use on first run or after code updates)
- `-d`: Run in detached mode (background)
### Step 3: Access the System
Once deployed, open your browser and visit:
- **Web Interface**: http://localhost:3000
- **API Health Check**: http://localhost:8080/api/health
## 📊 Service Management
### View Running Status
```bash
# View all container status
docker compose ps
# View service health status
docker compose ps --format json | jq
```
### View Logs
```bash
# View all service logs
docker compose logs -f
# View backend logs only
docker compose logs -f backend
# View frontend logs only
docker compose logs -f frontend
# View last 100 lines
docker compose logs --tail=100
```
### Stop Services
```bash
# Stop all services (keep data)
docker compose stop
# Stop and remove containers (keep data)
docker compose down
# Stop and remove containers and volumes (clear all data)
docker compose down -v
```
### Restart Services
```bash
# Restart all services
docker compose restart
# Restart backend only
docker compose restart backend
# Restart frontend only
docker compose restart frontend
```
### Update Services
```bash
# Pull latest code
git pull
# Rebuild and restart
docker compose up -d --build
```
## 🔧 Advanced Configuration
### Change Ports
Edit `docker-compose.yml` to modify port mappings:
```yaml
services:
backend:
ports:
- "8080:8080" # Change to "your_port:8080"
frontend:
ports:
- "3000:80" # Change to "your_port:80"
```
### Resource Limits
Add resource limits in `docker-compose.yml`:
```yaml
services:
backend:
deploy:
resources:
limits:
cpus: '2'
memory: 2G
reservations:
cpus: '1'
memory: 1G
```
### Environment Variables
Create `.env` file to manage environment variables:
```bash
# .env
TZ=Asia/Shanghai
BACKEND_PORT=8080
FRONTEND_PORT=3000
```
Then use in `docker-compose.yml`:
```yaml
services:
backend:
ports:
- "${BACKEND_PORT}:8080"
```
## 📁 Data Persistence
The system automatically persists data to local directories:
- `./decision_logs/`: AI decision logs
- `./coin_pool_cache/`: Coin pool cache
- ~~`./config.json`: Configuration file (mounted)~~ (Deprecated)
**Data locations:**
```bash
# View data directories
ls -la decision_logs/
ls -la coin_pool_cache/
# Backup data
tar -czf backup_$(date +%Y%m%d).tar.gz decision_logs/ coin_pool_cache/ ~~config.json~~ trading.db
# Restore data
tar -xzf backup_20241029.tar.gz
```
## 🐛 Troubleshooting
### Container Won't Start
```bash
# View detailed error messages
docker compose logs backend
docker compose logs frontend
# Check container status
docker compose ps -a
# Rebuild (clear cache)
docker compose build --no-cache
```
### Port Already in Use
```bash
# Find process using the port
lsof -i :8080 # backend port
lsof -i :3000 # frontend port
# Kill the process
kill -9 <PID>
```
### Configuration File Not Found
```bash
# ~~Ensure config.json exists~~
# ~~ls -la config.json~~
# ~~If not exists, copy template~~
# ~~cp config.example.jsonc config.json~~
*Note: Now using SQLite database for configuration storage, no longer need config.json*
```
### Health Check Failing
```bash
# Check health status
docker inspect nofx-backend | jq '.[0].State.Health'
docker inspect nofx-frontend | jq '.[0].State.Health'
# Manually test health endpoints
curl http://localhost:8080/api/health
curl http://localhost:3000/health
```
### Frontend Can't Connect to Backend
```bash
# Check network connectivity
docker compose exec frontend ping backend
# Check if backend service is running
docker compose exec frontend wget -O- http://backend:8080/health
```
### Clean Docker Resources
```bash
# Clean unused images
docker image prune -a
# Clean unused volumes
docker volume prune
# Clean all unused resources (use with caution)
docker system prune -a --volumes
```
## 🔐 Security Recommendations
1. ~~**Don't commit config.json to Git**~~
```bash
# ~~Ensure config.json is in .gitignore~~
# ~~echo "config.json" >> .gitignore~~
```
*Note: Now using trading.db database, ensure not to commit sensitive data*
2. **Use environment variables for sensitive data**
```yaml
# docker-compose.yml
services:
backend:
environment:
- BINANCE_API_KEY=${BINANCE_API_KEY}
- BINANCE_SECRET_KEY=${BINANCE_SECRET_KEY}
```
3. **Restrict API access**
```yaml
# Only allow local access
services:
backend:
ports:
- "127.0.0.1:8080:8080"
```
4. **Regularly update images**
```bash
docker compose pull
docker compose up -d
```
## 🌐 Production Deployment
### Using Nginx Reverse Proxy
```nginx
# /etc/nginx/sites-available/nofx
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
location /api/ {
proxy_pass http://localhost:8080/api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
### Configure HTTPS (Let's Encrypt)
```bash
# Install Certbot
sudo apt-get install certbot python3-certbot-nginx
# Get SSL certificate
sudo certbot --nginx -d your-domain.com
# Auto-renewal
sudo certbot renew --dry-run
```
### Using Docker Swarm (Cluster Deployment)
```bash
# Initialize Swarm
docker swarm init
# Deploy stack
docker stack deploy -c docker-compose.yml nofx
# View service status
docker stack services nofx
# Scale services
docker service scale nofx_backend=3
```
## 📈 Monitoring & Logging
### Log Management
```bash
# Configure log rotation (already configured in docker-compose.yml)
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
# View log statistics
docker compose logs --timestamps | wc -l
```
### Monitoring Tool Integration
Integrate Prometheus + Grafana for monitoring:
```yaml
# docker-compose.yml (add monitoring services)
services:
prometheus:
image: prom/prometheus
ports:
- "9090:9090"
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml
grafana:
image: grafana/grafana
ports:
- "3001:3000"
```
## 🆘 Get Help
- **GitHub Issues**: [Submit an issue](https://github.com/yourusername/open-nofx/issues)
- **Documentation**: Check [README.md](README.md)
- **Community**: Join our Discord/Telegram group
## 📝 Command Cheat Sheet
```bash
# Start
docker compose up -d --build # Build and start
docker compose up -d # Start (without rebuilding)
# Stop
docker compose stop # Stop services
docker compose down # Stop and remove containers
docker compose down -v # Stop and remove containers and data
# View
docker compose ps # View status
docker compose logs -f # View logs
docker compose top # View processes
# Restart
docker compose restart # Restart all services
docker compose restart backend # Restart backend
# Update
git pull && docker compose up -d --build
# Clean
docker compose down -v # Clear all data
docker system prune -a # Clean Docker resources
```
---
🎉 Congratulations! You've successfully deployed the NOFX AI Trading Competition System!
If you encounter any issues, please check the [Troubleshooting](#-troubleshooting) section or submit an issue.

489
docs/getting-started/docker-deploy.zh-CN.md Normal file
View File

@@ -0,0 +1,489 @@
# 🐳 Docker 一键部署教程
本教程将指导你使用 Docker 快速部署 NOFX AI 交易竞赛系统。
## 📋 前置要求
在开始之前，请确保你的系统已安装：
- **Docker**: 版本 20.10 或更高
- **Docker Compose**: 版本 2.0 或更高
### 安装 Docker
> #### 提示：Docker Compose 版本说明
>
> **新用户建议**：
> - **推荐使用 Docker Desktop**：自动包含最新 Docker Compose，无需单独安装
> - 安装简单，一键搞定，提供图形界面管理
> - 支持 macOS、Windows、部分 Linux 发行版
>
> **旧用户提醒**：
> - **弃用独立 docker-compose**：不再推荐下载独立的 Docker Compose 二进制文件
> - **使用内置版**：Docker 20.10+ 自带 `docker compose` 命令（注意是空格）
> - 如果还在使用旧的 `docker-compose`，请升级到新语法
#### macOS / Windows
下载并安装 [Docker Desktop](https://www.docker.com/products/docker-desktop/)
**安装后验证：**
```bash
docker --version
docker compose --version # 注意：使用空格，不再是连字符
```
#### Linux (Ubuntu/Debian)
**推荐方式：使用 Docker Desktop（如果可用）或 Docker CE**
```bash
# 安装 Docker (自动包含 compose)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# 将当前用户加入 docker 组
sudo usermod -aG docker $USER
newgrp docker
# 验证安装（新命令）
docker --version
docker compose --version # Docker 24+ 自带，无需单独安装
```
## 🚀 快速开始（3步完成部署）
### 第 1 步：准备配置文件
```bash
# 复制配置文件模板
cp config.example.jsonc config.json
# 编辑配置文件，填入你的 API 密钥
nano config.json # 或使用其他编辑器
```
**必须配置的字段：**
```json
{
"use_default_coins": true,
"api_server_port": 8081,
"jwt_secret": "YOUR_JWT_SECRET_CHANGE_IN_PRODUCTION" // ← 填入一个长随机字符串作为JWT密钥
}
```
> **⚠️ 重要安全提醒**：
> - `jwt_secret` 字段是用户认证系统的关键安全配置
> - **必须设置一个长度至少32位的随机字符串**
> - 在生产环境中，建议使用64位以上的随机字符串
> - 可以使用命令生成：`openssl rand -base64 64`
**配置说明：**
- 🔐 **用户认证**：系统现在支持用户注册登录，每个用户都有独立的AI模型和交易所配置
- 🚫 **移除traders配置**：不再需要在config.json中预配置交易员，用户可以通过Web界面创建
- 🔑 **JWT密钥**：用于保护用户会话安全，强烈建议在生产环境中设置复杂密钥
### 第 2 步：一键启动
```bash
# 构建并启动所有服务（首次运行）
docker compose up -d --build
# 后续启动（不重新构建）
docker compose up -d
```
**启动过程说明：**
- `--build`: 构建 Docker 镜像（首次运行或代码更新后使用）
- `-d`: 后台运行（detached mode）
### 第 3 步：访问系统
部署成功后，打开浏览器访问：
- **Web 界面**: http://localhost:3000
- **API 文档**: http://localhost:8080/api/health
## 📊 服务管理
### 查看运行状态
```bash
# 查看所有容器状态
docker compose ps
# 查看服务健康状态
docker compose ps --format json | jq
```
### 查看日志
```bash
# 查看所有服务日志
docker compose logs -f
# 只查看后端日志
docker compose logs -f backend
# 只查看前端日志
docker compose logs -f frontend
# 查看最近 100 行日志
docker compose logs --tail=100
```
### 停止服务
```bash
# 停止所有服务（保留数据）
docker compose stop
# 停止并删除容器（保留数据）
docker compose down
# 停止并删除容器和卷（清除所有数据）
docker compose down -v
```
### 重启服务
```bash
# 重启所有服务
docker compose restart
# 只重启后端
docker compose restart backend
# 只重启前端
docker compose restart frontend
```
### 更新服务
```bash
# 拉取最新代码
git pull
# 重新构建并重启
docker compose up -d --build
```
## 🔧 高级配置
### 修改端口
编辑 `docker-compose.yml`，修改端口映射：
```yaml
services:
backend:
ports:
- "8080:8080" # 改为 "你的端口:8080"
frontend:
ports:
- "3000:80" # 改为 "你的端口:80"
```
### 资源限制
在 `docker-compose.yml` 中添加资源限制：
```yaml
services:
backend:
deploy:
resources:
limits:
cpus: '2'
memory: 2G
reservations:
cpus: '1'
memory: 1G
```
### 环境变量
创建 `.env` 文件来管理环境变量：
```bash
# .env
TZ=Asia/Shanghai
BACKEND_PORT=8080
FRONTEND_PORT=3000
```
然后在 `docker-compose.yml` 中使用：
```yaml
services:
backend:
ports:
- "${BACKEND_PORT}:8080"
```
## 📁 数据持久化
系统会自动持久化以下数据到本地目录：
- `./decision_logs/`: AI 决策日志
- `./coin_pool_cache/`: 币种池缓存
- `./config.json`: 配置文件（挂载）
**数据位置：**
```bash
# 查看数据目录
ls -la decision_logs/
ls -la coin_pool_cache/
# 备份数据
tar -czf backup_$(date +%Y%m%d).tar.gz decision_logs/ coin_pool_cache/ config.json
# 恢复数据
tar -xzf backup_20241029.tar.gz
```
## 🐛 故障排查
### 容器无法启动
```bash
# 查看详细错误信息
docker compose logs backend
docker compose logs frontend
# 检查容器状态
docker compose ps -a
# 重新构建（清除缓存）
docker compose build --no-cache
```
### 端口被占用
```bash
# 查找占用端口的进程
lsof -i :8080 # 后端端口
lsof -i :3000 # 前端端口
# 杀死占用端口的进程
kill -9 <PID>
```
### 配置文件未找到
```bash
# 确保 config.json 存在
ls -la config.json
# 如果不存在，复制模板
cp config.example.jsonc config.json
```
### 健康检查失败
```bash
# 检查健康状态
docker inspect nofx-backend | jq '.[0].State.Health'
docker inspect nofx-frontend | jq '.[0].State.Health'
# 手动测试健康端点
curl http://localhost:8080/api/health
curl http://localhost:3000/health
```
### 前端无法连接后端
```bash
# 检查网络连接
docker compose exec frontend ping backend
# 检查后端服务是否正常
docker compose exec frontend wget -O- http://backend:8080/health
```
### 清理 Docker 资源
```bash
# 清理未使用的镜像
docker image prune -a
# 清理未使用的卷
docker volume prune
# 清理所有未使用的资源（慎用）
docker system prune -a --volumes
```
## 🔐 安全建议
1. **JWT密钥安全配置**
```bash
# 生成强随机JWT密钥
openssl rand -base64 64
# 或者使用其他工具生成
head -c 64 /dev/urandom | base64
```
**JWT密钥要求：**
- 长度至少32位，推荐64位以上
- 使用随机生成的字符串
- 在生产环境中绝不使用默认值
- 定期更换（会使现有用户需要重新登录）
2. ~~**不要将 config.json 提交到 Git**~~
```bash
# ~~确保 config.json 在 .gitignore 中~~
# ~~echo "config.json" >> .gitignore~~
```
*注意：现在使用trading.db数据库，请确保不提交敏感数据*
3. **使用环境变量存储敏感信息**
```yaml
# docker-compose.yml
services:
backend:
environment:
- JWT_SECRET=${JWT_SECRET}
# 用户的API密钥现在通过Web界面配置，不再需要环境变量
```
4. **限制 API 访问**
```yaml
# 只允许本地访问
services:
backend:
ports:
- "127.0.0.1:8080:8080"
```
4. **定期更新镜像**
```bash
docker compose pull
docker compose up -d
```
## 🌐 生产环境部署
### 使用 Nginx 反向代理
```nginx
# /etc/nginx/sites-available/nofx
server {
listen 80;
server_name your-domain.com;
location / {
proxy_pass http://localhost:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
location /api/ {
proxy_pass http://localhost:8080/api/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
### 配置 HTTPS (Let's Encrypt)
```bash
# 安装 Certbot
sudo apt-get install certbot python3-certbot-nginx
# 获取 SSL 证书
sudo certbot --nginx -d your-domain.com
# 自动续期
sudo certbot renew --dry-run
```
### 使用 Docker Swarm (集群部署)
```bash
# 初始化 Swarm
docker swarm init
# 部署堆栈
docker stack deploy -c docker-compose.yml nofx
# 查看服务状态
docker stack services nofx
# 扩展服务
docker service scale nofx_backend=3
```
## 📈 监控与日志
### 日志管理
```bash
# 配置日志轮转（已在 docker-compose.yml 中配置）
logging:
driver: "json-file"
options:
max-size: "10m"
max-file: "3"
# 查看日志统计
docker compose logs --timestamps | wc -l
```
### 监控工具集成
可以集成 Prometheus + Grafana 进行监控：
```yaml
# docker-compose.yml (添加监控服务)
services:
prometheus:
image: prom/prometheus
ports:
- "9090:9090"
volumes:
- ./prometheus.yml:/etc/prometheus/prometheus.yml
grafana:
image: grafana/grafana
ports:
- "3001:3000"
```
## 🆘 获取帮助
- **GitHub Issues**: [提交问题](https://github.com/yourusername/open-nofx/issues)
- **文档**: 查看 [README.md](README.md)
- **社区**: 加入我们的 Discord/Telegram 群组
## 📝 常用命令速查表
```bash
# 启动
docker compose up -d --build # 构建并启动
docker compose up -d # 启动（不重新构建）
# 停止
docker compose stop # 停止服务
docker compose down # 停止并删除容器
docker compose down -v # 停止并删除容器和数据
# 查看
docker compose ps # 查看状态
docker compose logs -f # 查看日志
docker compose top # 查看进程
# 重启
docker compose restart # 重启所有服务
docker compose restart backend # 重启后端
# 更新
git pull && docker compose up -d --build
# 清理
docker compose down -v # 清除所有数据
docker system prune -a # 清理 Docker 资源
```
---
🎉 恭喜！你已经成功部署了 NOFX AI 交易竞赛系统！
如有问题，请查看[故障排查](#-故障排查)部分或提交 Issue。

303
docs/getting-started/pm2-deploy.en.md Normal file
View File

@@ -0,0 +1,303 @@
# NoFX Trading Bot - PM2 Deployment Guide
Complete guide for local development and production deployment using PM2.
## 🚀 Quick Start
### 1. Install PM2
```bash
npm install -g pm2
```
### 2. One-Command Launch
```bash
./pm2.sh start
```
That's it! Frontend and backend will start automatically.
---
## 📋 All Commands
### Service Management
```bash
# Start services
./pm2.sh start
# Stop services
./pm2.sh stop
# Restart services
./pm2.sh restart
# View status
./pm2.sh status
# Delete services
./pm2.sh delete
```
### Log Viewing
```bash
# View all logs (live)
./pm2.sh logs
# Backend logs only
./pm2.sh logs backend
# Frontend logs only
./pm2.sh logs frontend
```
### Build & Compile
```bash
# Compile backend
./pm2.sh build
# Recompile backend and restart
./pm2.sh rebuild
```
### Monitoring
```bash
# Open PM2 monitoring dashboard (real-time CPU/Memory)
./pm2.sh monitor
```
---
## 📊 Access URLs
After successful startup:
- **Frontend Web Interface**: http://localhost:3000
- **Backend API**: http://localhost:8080
- **Health Check**: http://localhost:8080/api/health
---
## 🔧 Configuration Files
### pm2.config.js
PM2 configuration file, defines frontend and backend startup parameters:
```javascript
const path = require('path');
module.exports = {
apps: [
{
name: 'nofx-backend',
script: './nofx', // Go binary
cwd: __dirname, // Dynamically get current directory
autorestart: true,
max_memory_restart: '500M'
},
{
name: 'nofx-frontend',
script: 'npm',
args: 'run dev', // Vite dev server
cwd: path.join(__dirname, 'web'), // Dynamically join path
autorestart: true,
max_memory_restart: '300M'
}
]
};
```
**After modifying configuration, restart is required:**
```bash
./pm2.sh restart
```
---
## 📝 Log File Locations
- **Backend Logs**: `./logs/backend-error.log` and `./logs/backend-out.log`
- **Frontend Logs**: `./web/logs/frontend-error.log` and `./web/logs/frontend-out.log`
---
## 🔄 Startup on Boot
Set PM2 to start on boot:
```bash
# 1. Start services
./pm2.sh start
# 2. Save current process list
pm2 save
# 3. Generate startup script
pm2 startup
# 4. Follow the instructions to execute command (requires sudo)
```
**Disable startup on boot:**
```bash
pm2 unstartup
```
---
## 🛠️ Common Operations
### Restart After Code Changes
**Backend changes:**
```bash
./pm2.sh rebuild # Auto compile and restart
```
**Frontend changes:**
```bash
./pm2.sh restart # Vite will auto hot-reload, no restart needed
```
### View Real-time Resource Usage
```bash
./pm2.sh monitor
```
### View Detailed Information
```bash
pm2 info nofx-backend # Backend details
pm2 info nofx-frontend # Frontend details
```
### Clear Logs
```bash
pm2 flush
```
---
## 🐛 Troubleshooting
### Service Startup Failed
```bash
# 1. View detailed errors
./pm2.sh logs
# 2. Check port usage
lsof -i :8080 # Backend port
lsof -i :3000 # Frontend port
# 3. Manual compile test
go build -o nofx
./nofx
```
### Backend Won't Start
```bash
# ~~Check if config.json exists~~
# ~~ls -l config.json~~
# Check if database file exists
ls -l trading.db
# Check permissions
chmod +x nofx
# Run manually to see errors
./nofx
```
### Frontend Not Accessible
```bash
# Check node_modules
cd web && npm install
# Manual start test
npm run dev
```
---
## 🎯 Production Environment Recommendations
### 1. Use Production Mode
Modify `pm2.config.js`:
```javascript
{
name: 'nofx-frontend',
script: 'npm',
args: 'run preview', // Change to preview (requires npm run build first)
env: {
NODE_ENV: 'production'
}
}
```
### 2. Increase Instances (Load Balancing)
```javascript
{
name: 'nofx-backend',
script: './nofx',
instances: 2, // Start 2 instances
exec_mode: 'cluster'
}
```
### 3. Auto Restart Strategy
```javascript
{
autorestart: true,
max_restarts: 10,
min_uptime: '10s',
max_memory_restart: '500M'
}
```
---
## 📦 Comparison with Docker Deployment
| Feature | PM2 Deployment | Docker Deployment |
|---------|---------------|-------------------|
| Startup Speed | ⚡ Fast | 🐌 Slower |
| Resource Usage | 💚 Low | 🟡 Medium |
| Isolation | 🟡 Medium | 💚 High |
| Use Case | Dev/Single-machine | Production/Cluster |
| Configuration Complexity | 💚 Simple | 🟡 Medium |
**Recommendations:**
- **Development Environment**: Use `./pm2.sh`
- **Production Environment**: Use `./start.sh` (Docker)
---
## 🆘 Getting Help
```bash
./pm2.sh help
```
Or check PM2 official documentation: https://pm2.keymetrics.io/
---
## 📄 License
MIT

303
docs/getting-started/pm2-deploy.md Normal file
View File

@@ -0,0 +1,303 @@
# NoFX Trading Bot - PM2 部署指南
使用 PM2 进行本地开发和生产部署的完整指南。
## 🚀 快速开始
### 1. 安装 PM2
```bash
npm install -g pm2
```
### 2. 一键启动
```bash
./pm2.sh start
```
就这么简单！前后端将自动启动。
---
## 📋 所有命令
### 服务管理
```bash
# 启动服务
./pm2.sh start
# 停止服务
./pm2.sh stop
# 重启服务
./pm2.sh restart
# 查看状态
./pm2.sh status
# 删除服务
./pm2.sh delete
```
### 日志查看
```bash
# 查看所有日志（实时）
./pm2.sh logs
# 只看后端日志
./pm2.sh logs backend
# 只看前端日志
./pm2.sh logs frontend
```
### 构建与编译
```bash
# 编译后端
./pm2.sh build
# 重新编译后端并重启
./pm2.sh rebuild
```
### 监控
```bash
# 打开 PM2 监控面板（实时CPU/内存）
./pm2.sh monitor
```
---
## 📊 访问地址
启动成功后：
- **前端 Web 界面**: http://localhost:3000
- **后端 API**: http://localhost:8080
- **健康检查**: http://localhost:8080/api/health
---
## 🔧 配置文件
### pm2.config.js
PM2 配置文件，定义了前后端的启动参数：
```javascript
const path = require('path');
module.exports = {
apps: [
{
name: 'nofx-backend',
script: './nofx', // Go 二进制文件
cwd: __dirname, // 动态获取当前目录
autorestart: true,
max_memory_restart: '500M'
},
{
name: 'nofx-frontend',
script: 'npm',
args: 'run dev', // Vite 开发服务器
cwd: path.join(__dirname, 'web'), // 动态拼接路径
autorestart: true,
max_memory_restart: '300M'
}
]
};
```
**修改配置后需要重启：**
```bash
./pm2.sh restart
```
---
## 📝 日志文件位置
- **后端日志**: `./logs/backend-error.log` 和 `./logs/backend-out.log`
- **前端日志**: `./web/logs/frontend-error.log` 和 `./web/logs/frontend-out.log`
---
## 🔄 开机自启动
设置 PM2 开机自启动：
```bash
# 1. 启动服务
./pm2.sh start
# 2. 保存当前进程列表
pm2 save
# 3. 生成启动脚本
pm2 startup
# 4. 按照提示执行命令（需要 sudo）
```
**取消开机自启动：**
```bash
pm2 unstartup
```
---
## 🛠️ 常见操作
### 修改代码后重启
**后端修改：**
```bash
./pm2.sh rebuild # 自动编译并重启
```
**前端修改：**
```bash
./pm2.sh restart # Vite 会自动热重载，无需重启
```
### 查看实时资源占用
```bash
./pm2.sh monitor
```
### 查看详细信息
```bash
pm2 info nofx-backend # 后端详情
pm2 info nofx-frontend # 前端详情
```
### 清空日志
```bash
pm2 flush
```
---
## 🐛 故障排查
### 服务启动失败
```bash
# 1. 查看详细错误
./pm2.sh logs
# 2. 检查端口占用
lsof -i :8080 # 后端端口
lsof -i :3000 # 前端端口
# 3. 手动编译测试
go build -o nofx
./nofx
```
### 后端无法启动
```bash
# ~~检查 config.json 是否存在~~
# ~~ls -l config.json~~
# 检查数据库文件是否存在
ls -l trading.db
# 检查权限
chmod +x nofx
# 手动运行看报错
./nofx
```
### 前端无法访问
```bash
# 检查 node_modules
cd web && npm install
# 手动启动测试
npm run dev
```
---
## 🎯 生产环境建议
### 1. 使用生产模式
修改 `pm2.config.js`：
```javascript
{
name: 'nofx-frontend',
script: 'npm',
args: 'run preview', // 改为 preview（需先 npm run build）
env: {
NODE_ENV: 'production'
}
}
```
### 2. 增加实例数（负载均衡）
```javascript
{
name: 'nofx-backend',
script: './nofx',
instances: 2, // 启动 2 个实例
exec_mode: 'cluster'
}
```
### 3. 自动重启策略
```javascript
{
autorestart: true,
max_restarts: 10,
min_uptime: '10s',
max_memory_restart: '500M'
}
```
---
## 📦 与 Docker 部署的对比
| 特性 | PM2 部署 | Docker 部署 |
|------|---------|------------|
| 启动速度 | ⚡ 快 | 🐌 较慢 |
| 资源占用 | 💚 低 | 🟡 中等 |
| 隔离性 | 🟡 中等 | 💚 高 |
| 适用场景 | 开发/单机 | 生产/集群 |
| 配置复杂度 | 💚 简单 | 🟡 中等 |
**建议：**
- **开发环境**: 使用 `./pm2.sh`
- **生产环境**: 使用 `./start.sh` (Docker)
---
## 🆘 获取帮助
```bash
./pm2.sh help
```
或查看 PM2 官方文档：https://pm2.keymetrics.io/
---
## 📄 License
MIT

138
docs/guides/README.md Normal file
View File

@@ -0,0 +1,138 @@
# 📘 NOFX User Guides
**Language:** [English](README.md) | [中文](README.zh-CN.md)
Comprehensive guides to help you use NOFX effectively.
---
## 📚 Available Guides
### 🔧 Basic Usage
| Guide | Description | Status |
|-------|-------------|--------|
| [FAQ (English)](faq.en.md) | Frequently asked questions | ✅ Available |
| [FAQ (中文)](faq.zh-CN.md) | 常见问题解答 | ✅ Available |
| Configuration Guide | Advanced settings and options | 🚧 Coming Soon |
| Trading Strategies | AI trading strategy examples | 🚧 Coming Soon |
---
## 🐛 Troubleshooting
### Common Issues
**Issue: TA-Lib not found**
```bash
# macOS
brew install ta-lib
# Ubuntu/Debian
sudo apt-get install libta-lib0-dev
```
**Issue: Precision error**
- System auto-handles LOT_SIZE from exchange
- Check network connection
- Verify exchange API is accessible
**Issue: AI API timeout**
- Check API key validity
- Verify network connection
- Check API balance/credits
- Timeout is set to 120 seconds
**Issue: Frontend can't connect**
- Ensure backend is running (http://localhost:8080)
- Check if port 8080 is available
- Check browser console for errors
---
## 📖 Usage Tips
### Best Practices
**1. Risk Management**
- Start with small amounts (100-500 USDT)
- Use subaccounts for additional safety
- Set reasonable leverage limits
- Monitor daily loss limits
**2. Performance Monitoring**
- Check decision logs regularly
- Analyze win rate and profit factor
- Review AI reasoning (Chain of Thought)
- Track equity curve trends
**3. Configuration**
- Test on testnet first
- Gradually increase trading amounts
- Adjust scan intervals (3-5 minutes recommended)
- Use default coin list for beginners
---
## 🎯 Advanced Topics
### Multi-Trader Competition
Run multiple AI models simultaneously:
- Qwen vs DeepSeek head-to-head
- Compare performance in real-time
- Identify best-performing strategies
### Custom Coin Pools
- Use external API for coin selection
- Combine AI500 + OI Top data
- Filter by liquidity and volume
### Exchange Integration
- Binance Futures (CEX)
- Hyperliquid (DEX)
- Aster DEX (Binance-compatible)
---
## 📊 Understanding Metrics
### Key Performance Indicators
**Win Rate**
- Percentage of profitable trades
- Target: >50% for consistent profit
**Profit Factor**
- Ratio of gross profit to gross loss
- Target: >1.5 (1.5:1 or better)
**Sharpe Ratio**
- Risk-adjusted return measure
- Higher is better (>1.0 is good)
**Maximum Drawdown**
- Largest peak-to-trough decline
- Keep under 20% for safety
---
## 🔗 Related Documentation
- [Getting Started (EN)](../getting-started/README.md) - Initial setup
- [Getting Started (中文)](../getting-started/README.zh-CN.md) - 初始设置
- [Community](../community/README.md) - Contributing and bounties
- [FAQ (English)](faq.en.md) - Common questions
- [FAQ (中文)](faq.zh-CN.md) - 常见问题
---
## 🆘 Need Help?
**Can't find what you need?**
- 💬 [Telegram Community](https://t.me/nofx_dev_community)
- 🐛 [GitHub Issues](https://github.com/tinkle-community/nofx/issues)
- 🐦 [Twitter @nofx_ai](https://x.com/nofx_ai)
---
[← Back to Documentation Home](../README.md)

137
docs/guides/README.zh-CN.md Normal file
View File

@@ -0,0 +1,137 @@
# 📘 NOFX 使用指南
**语言:** [English](README.md) | [中文](README.zh-CN.md)
帮助您有效使用 NOFX 的综合指南。
---
## 📚 可用指南
### 🔧 基础使用
| 指南 | 描述 | 状态 |
|------|------|------|
| [FAQ (中文)](faq.zh-CN.md) | 常见问题解答 | ✅ 可用 |
| [FAQ (English)](faq.en.md) | Frequently asked questions | ✅ 可用 |
| 配置指南 | 高级设置和选项 | 🚧 即将推出 |
| 交易策略 | AI 交易策略示例 | 🚧 即将推出 |
---
## 🐛 故障排除
### 常见问题
**问题：找不到 TA-Lib**
```bash
# macOS
brew install ta-lib
# Ubuntu/Debian
sudo apt-get install libta-lib0-dev
```
**问题：精度错误**
- 系统自动处理交易所的 LOT_SIZE
- 检查网络连接
- 验证交易所 API 可访问
**问题：AI API 超时**
- 检查 API 密钥有效性
- 验证网络连接
- 检查 API 余额/额度
- 超时设置为 120 秒
**问题：前端无法连接**
- 确保后端正在运行 (http://localhost:8080)
- 检查端口 8080 是否可用
- 检查浏览器控制台错误
---
## 📖 使用技巧
### 最佳实践
**1. 风险管理**
- 从小金额开始（100-500 USDT）
- 使用子账户增加安全性
- 设置合理的杠杆限制
- 监控每日亏损限制
**2. 性能监控**
- 定期检查决策日志
- 分析胜率和盈利因子
- 审查 AI 推理（思维链）
- 跟踪权益曲线趋势
**3. 配置**
- 先在测试网测试
- 逐步增加交易金额
- 调整扫描间隔（推荐 3-5 分钟）
- 初学者使用默认币种列表
---
## 🎯 进阶主题
### 多交易员竞赛
同时运行多个 AI 模型：
- Qwen vs DeepSeek 对决
- 实时比较性能
- 识别表现最佳的策略
### 自定义币种池
- 使用外部 API 进行币种选择
- 结合 AI500 + OI Top 数据
- 按流动性和交易量过滤
### 交易所集成
- Binance Futures（中心化交易所）
- Hyperliquid（去中心化交易所）
- Aster DEX（兼容 Binance）
---
## 📊 理解指标
### 关键性能指标
**胜率（Win Rate）**
- 盈利交易的百分比
- 目标：>50% 以获得稳定盈利
**盈利因子（Profit Factor）**
- 总盈利与总亏损的比率
- 目标：>1.5（1.5:1 或更好）
**夏普比率（Sharpe Ratio）**
- 风险调整后的收益衡量
- 越高越好（>1.0 为良好）
**最大回撤（Maximum Drawdown）**
- 从峰值到谷值的最大跌幅
- 为安全起见保持在 20% 以下
---
## 🔗 相关文档
- [快速开始](../getting-started/README.zh-CN.md) - 初始设置
- [社区](../community/README.md) - 贡献和悬赏
- [FAQ 中文](faq.zh-CN.md) - 常见问题
- [FAQ English](faq.en.md) - Common questions
---
## 🆘 需要帮助？
**找不到您需要的内容？**
- 💬 [Telegram 社区](https://t.me/nofx_dev_community)
- 🐛 [GitHub Issues](https://github.com/tinkle-community/nofx/issues)
- 🐦 [Twitter @nofx_ai](https://x.com/nofx_ai)
---
[← 返回文档首页](../README.md)

25
docs/guides/faq.en.md Normal file
View File

@@ -0,0 +1,25 @@
# Frequently Asked Questions
## Binance Position Mode Error (code=-4061)
**Error Message**: `Order's position side does not match user's setting`
**Cause**: The system requires Hedge Mode (dual position), but your Binance account is set to One-way Mode.
### Solution
1. Login to [Binance Futures Trading Platform](https://www.binance.com/en/futures/BTCUSDT)
2. Click **⚙️ Preferences** in the top right corner
3. Select **Position Mode**
4. Switch to **Hedge Mode** (Dual Position)
5. Confirm the change
**Note**: You must close all open positions before switching modes.
---
For more issues, check [GitHub Issues](https://github.com/tinkle-community/nofx/issues)

25
docs/guides/faq.zh-CN.md Normal file
View File

@@ -0,0 +1,25 @@
# 常见问题
## 币安持仓模式错误 (code=-4061)
**错误信息**：`Order's position side does not match user's setting`
**原因**：系统需要使用双向持仓模式，但您的币安账户设置为单向持仓。
### 解决方法
1. 登录 [币安合约交易平台](https://www.binance.com/zh-CN/futures/BTCUSDT)
2. 点击右上角的 **⚙️ 偏好设置**
3. 选择 **持仓模式**
4. 切换为 **双向持仓** (Hedge Mode)
5. 确认切换
**注意**：切换前必须先平掉所有持仓。
---
更多问题请查看 [GitHub Issues](https://github.com/tinkle-community/nofx/issues)

231
docs/i18n/README.md Normal file
View File

@@ -0,0 +1,231 @@
# 🌍 International Documentation / 国际化文档
NOFX documentation is available in multiple languages.
NOFX 文档提供多种语言版本。
---
## 📚 Available Languages / 可用语言
| Language | Main README | Status | Maintainers |
|----------|-------------|--------|-------------|
| 🇬🇧 **English** | [README.md](../../README.md) | ✅ Complete | Core Team |
| 🇨🇳 **Chinese (中文)** | [README.md](zh-CN/README.md) | ✅ Complete | Community |
| 🇷🇺 **Russian (Русский)** | [README.md](ru/README.md) | ✅ Complete | Community |
| 🇺🇦 **Ukrainian (Українська)** | [README.md](uk/README.md) | ✅ Complete | Community |
---
## 🔗 Quick Access / 快速访问
### English 🇬🇧
- **Main README:** [../../README.md](../../README.md)
- **Contributing:** [../../CONTRIBUTING.md](../../CONTRIBUTING.md)
- **Security:** [../../SECURITY.md](../../SECURITY.md)
### 中文 🇨🇳
- **主 README:** [zh-CN/README.md](zh-CN/README.md)
- **贡献指南:** [../../CONTRIBUTING.md](../../CONTRIBUTING.md#中文)
- **安全政策:** [../../SECURITY.md](../../SECURITY.md#中文)
- **常见问题:** [../guides/faq.zh-CN.md](../guides/faq.zh-CN.md)
### Русский 🇷🇺
- **Основной README:** [ru/README.md](ru/README.md)
- **Руководство по участию:** [../../CONTRIBUTING.md](../../CONTRIBUTING.md)
- **Политика безопасности:** [../../SECURITY.md](../../SECURITY.md)
### Українська 🇺🇦
- **Головний README:** [uk/README.md](uk/README.md)
- **Посібник із внесків:** [../../CONTRIBUTING.md](../../CONTRIBUTING.md)
- **Політика безпеки:** [../../SECURITY.md](../../SECURITY.md)
---
## 🤝 Help with Translations / 帮助翻译
### Want to Contribute Translations? / 想要贡献翻译？
We welcome translation contributions! / 我们欢迎翻译贡献！
**What needs translation? / 需要翻译什么？**
- ✅ Main README (complete for 4 languages)
- 🚧 Deployment guides (partial)
- 📋 User guides (needed)
- 📋 Contributing guide (needed for RU/UK)
**How to contribute translations? / 如何贡献翻译？**
1. **Check existing translations / 检查现有翻译**
- Browse this directory
- See what's missing
2. **Claim a translation task / 认领翻译任务**
- Open a GitHub Issue
- Title: `[TRANSLATION] Document name to Language`
- Example: `[TRANSLATION] CONTRIBUTING.md to Chinese`
3. **Submit translation / 提交翻译**
- Follow [Contributing Guide](../../CONTRIBUTING.md)
- Place file in appropriate language folder
- Keep formatting and structure consistent
4. **Get recognized / 获得认可**
- Listed as translator in credits
- Eligible for contributor badges
- Possible bounty rewards ($50-200)
---
## 📝 Translation Guidelines / 翻译指南
### File Naming Convention / 文件命名规范
**Pattern:** `document-name.{language-code}.md`
**Examples:**
```
README.md → en (default)
docker-deploy.zh-CN.md → Chinese
docker-deploy.ru.md → Russian
faq.zh-CN.md → Chinese FAQ
```
**Language Codes:**
- `en` - English (default, no suffix needed)
- `zh-CN` - Simplified Chinese
- `ru` - Russian
- `uk` - Ukrainian
- `ja` - Japanese *(future)*
- `ko` - Korean *(future)*
### Quality Standards / 质量标准
**Must have / 必须具备:**
- ✅ Accurate technical terms
- ✅ Natural, fluent language
- ✅ Consistent terminology
- ✅ Preserved formatting (markdown)
- ✅ Working internal links
**Avoid / 避免:**
- ❌ Machine translation without review
- ❌ Inconsistent terminology
- ❌ Broken links or formatting
- ❌ Cultural insensitivity
### Technical Terms / 技术术语
**Keep in English (don't translate):**
- API, HTTP, REST, JSON
- Docker, Kubernetes
- GitHub, Git, Pull Request
- Specific tool names (Binance, Hyperliquid)
**Example - Chinese:**
- ✅ "启动 Docker 容器" (start Docker container)
- ❌ "启动 多克 容器" (transliterated Docker)
---
## 🌐 Request a New Language / 请求新语言
### Want NOFX in your language? / 希望 NOFX 支持你的语言？
**Steps / 步骤:**
1. **Check if it's planned / 检查是否已计划**
- See list below
- Search GitHub Issues
2. **Create a request / 创建请求**
- Open GitHub Issue
- Title: `[TRANSLATION REQUEST] Language name`
- Explain: Number of potential users, your willingness to help
3. **Volunteer to help / 志愿帮助**
- Offer to translate
- Find other speakers to review
- Commit to maintaining updates
### Planned Languages / 计划中的语言
| Language | Status | Need Volunteers? |
|----------|--------|------------------|
| 🇯🇵 Japanese | 📋 Planned | ✅ Yes |
| 🇰🇷 Korean | 📋 Planned | ✅ Yes |
| 🇪🇸 Spanish | 📋 Planned | ✅ Yes |
| 🇫🇷 French | 📋 Planned | ✅ Yes |
| 🇩🇪 German | 📋 Planned | ✅ Yes |
---
## 👥 Translation Team / 翻译团队
### Current Translators / 当前翻译者
| Language | Translators | Status |
|----------|-------------|--------|
| 🇨🇳 Chinese | Community | Active |
| 🇷🇺 Russian | Community | Active |
| 🇺🇦 Ukrainian | Community | Active |
**Want to join the team? / 想加入团队？**
- Contact on [Telegram](https://t.me/nofx_dev_community)
- Open an issue on GitHub
- DM [@nofx_ai](https://x.com/nofx_ai) on Twitter
---
## 📊 Translation Progress / 翻译进度
### Document Coverage / 文档覆盖率
| Document | EN | 中文 | РУ | УК |
|----------|----|----|----|----|
| Main README | ✅ | ✅ | ✅ | ✅ |
| CONTRIBUTING | ✅ | ✅ | 🚧 | 🚧 |
| CODE_OF_CONDUCT | ✅ | ✅ | 🚧 | 🚧 |
| SECURITY | ✅ | ✅ | 🚧 | 🚧 |
| Docker Deploy | ✅ | ✅ | ❌ | ❌ |
| FAQ | ✅ | ✅ | ❌ | ❌ |
**Legend / 图例:**
- ✅ Complete / 完成
- 🚧 In Progress / 进行中
- ❌ Not Started / 未开始
---
## 🎯 Priority Translations / 优先翻译
**High Priority / 高优先级:**
1. CONTRIBUTING.md (all languages)
2. Docker deployment guides
3. FAQ sections
**Medium Priority / 中优先级:**
1. User guides
2. Troubleshooting docs
3. API reference
**Low Priority / 低优先级:**
1. Architecture docs (technical, less urgent)
2. Advanced configuration guides
---
## 🆘 Translation Help / 翻译帮助
**Questions? / 有问题？**
- 💬 Ask in [Telegram Community](https://t.me/nofx_dev_community)
- 🐙 Open a [GitHub Issue](https://github.com/tinkle-community/nofx/issues)
- 📧 Contact maintainers
**Resources / 资源:**
- [Contributing Guide](../../CONTRIBUTING.md) - How to submit
- [Markdown Guide](https://www.markdownguide.org/) - Formatting reference
---
[← Back to Documentation Home](../README.md)

1128
docs/i18n/ru/README.md Normal file
View File

File diff suppressed because it is too large Load Diff

1100
docs/i18n/uk/README.md Normal file
View File

File diff suppressed because it is too large Load Diff

1307
docs/i18n/zh-CN/README.md Normal file
View File

File diff suppressed because it is too large Load Diff

292
docs/roadmap/README.md Normal file
View File

@@ -0,0 +1,292 @@
# 🗺️ NOFX Roadmap
**Language:** [English](README.md) | [中文](README.zh-CN.md)
Strategic plan for NOFX development and universal market expansion.
---
## 📋 Overview
NOFX is on a mission to become the **Universal AI Trading Operating System** for all financial markets. Our proven infrastructure on crypto markets is being extended to stocks, futures, options, forex, and beyond.
**Vision:** Same architecture. Same agent framework. All markets.
---
## 🎯 Short-Term Roadmap
### Phase 1: Core Infrastructure Enhancement
#### 1.1 Security Enhancements
**Goal:** Protect sensitive data and reduce security vulnerabilities
- **Credential Management**
- [ ] Implement AES-256 encryption for API keys in database
- [ ] Add encryption for private keys (Hyperliquid, Aster)
- [ ] Use hardware security module (HSM) support for production
- [ ] Implement key rotation mechanism
- [ ] Add audit logging for all credential access
- **Application Security**
- [ ] Input validation and sanitization (prevent SQL injection, XSS)
- [ ] Rate limiting for API endpoints
- [ ] CORS policy configuration
- [ ] JWT token expiration and refresh mechanism
- [ ] Implement RBAC (Role-Based Access Control) for multi-user support
- [ ] Add IP whitelisting for API access
- [ ] Security headers (CSP, HSTS, X-Frame-Options)
- **Operational Security**
- [ ] Secure password hashing (bcrypt with salt)
- [ ] 2FA enhancement (backup codes, multiple TOTP devices)
- [ ] Session management (auto-logout, concurrent session limits)
- [ ] Secrets management (environment variables, vault integration)
- [ ] Regular dependency vulnerability scanning
#### 1.2 Enhanced AI Capabilities
**Goal:** Richer prompts, flexible configuration, support for more AI models
- **Prompt System Overhaul**
- [ ] Template engine for dynamic prompt generation
- [ ] Multi-language prompt support (chain-of-thought, few-shot, zero-shot)
- [ ] Market condition-based prompt switching (bull, bear, sideways)
- [ ] Historical performance feedback integration in prompts
- [ ] Prompt versioning and A/B testing framework
- [ ] User-customizable prompt templates via web interface
- **AI Model Integration**
- [ ] OpenAI GPT-4/GPT-4 Turbo support
- [ ] Anthropic Claude 3 (Opus, Sonnet, Haiku) integration
- [ ] Google Gemini Pro support
- [ ] Local LLM support (Llama, Mistral via Ollama)
- [ ] Multi-model ensemble (voting, weighted average)
- [ ] Model performance tracking and auto-selection
- [ ] Fallback mechanism when primary model fails
- **AI Decision Engine**
- [ ] Confidence scoring for each decision
- [ ] Explanation generation (why this trade?)
- [ ] Risk assessment integration in AI reasoning
- [ ] Market regime detection (trend, mean-reversion, high volatility)
- [ ] Cross-validation with technical indicators
#### 1.3 Exchange Integration Expansion
**Goal:** Support more CEX and popular perp-DEX, both spot and futures
- **Centralized Exchanges (CEX)**
- [ ] **OKX** - Futures + Spot trading
- [ ] **Bybit** - Futures + Spot trading
- [ ] **Bitget** - Futures + Spot trading
- [ ] **Gate.io** - Futures + Spot trading
- [ ] **KuCoin** - Futures + Spot trading
- [ ] Unified CEX interface for easy addition of new exchanges
- **Decentralized Perpetual Exchanges (Perp-DEX)**
- [x] **Hyperliquid** (Ethereum L1) - High-performance orderbook DEX (✅ Supported)
- [x] **Aster** (Multi-chain) - Binance-compatible API DEX (✅ Supported)
- [ ] **Lighter** (Arbitrum) - Gasless orderbook DEX with off-chain matching
- [ ] **EdgeX** (Multi-chain) - Professional derivatives DEX
- [ ] Unified DEX interface for consistent integration
- [ ] Enhanced Hyperliquid integration (testnet support, advanced order types)
- [ ] Enhanced Aster integration (cross-chain support, wallet management)
- **Spot + Futures Support**
- [ ] Dual-mode trading (spot arbitrage, futures hedging)
- [ ] Cross-exchange arbitrage detection
- [ ] Unified position tracking across spot and futures
- [ ] Auto-conversion between spot and perpetual strategies
- **Exchange Infrastructure**
- [ ] **Trading Data Analysis API Integration** (In-house developed)
- [ ] AI500 integration - In-house AI-powered coin selection model
- [ ] OI (Open Interest) Analysis - Real-time open interest tracking and anomaly detection
- [ ] NetFlow Analysis - On-chain fund flow analysis for market sentiment
- [ ] Market sentiment aggregator - Combine multiple data sources for enhanced AI decision making
- [ ] Custom indicator API - Support for proprietary technical indicators
- [ ] Automatic precision handling (quantity, price decimals)
- [ ] Order type abstraction (market, limit, stop-loss, take-profit)
- [ ] Unified error handling and retry logic
- [ ] WebSocket support for real-time data
- [ ] Rate limit management per exchange
#### 1.4 Project Structure Refactoring
**Goal:** Clear hierarchy, high cohesion, low coupling, easy to extend and maintain
- **Architecture Redesign**
- [ ] Implement layered architecture (Presentation → Business Logic → Data Access)
- [ ] Apply SOLID principles (especially Liskov Substitution Principle for exchange adapters)
- [ ] Extract common interfaces for all exchange implementations
- [ ] Separate concerns: trading logic, data fetching, decision making, execution
- [ ] Implement dependency injection for better testability
- **Code Organization**
- [ ] Refactor monolithic modules into smaller, focused packages
- [ ] Create abstract base classes for traders, exchanges, AI models
- [ ] Implement factory pattern for exchange/AI model creation
- [ ] Standardize error handling and logging across all modules
- [ ] Remove circular dependencies and improve import structure
- **Configuration Management**
- [ ] Centralize all configuration in structured config files
- [ ] Implement hot-reload for non-critical configuration changes
- [ ] Validate configurations at startup with clear error messages
- [ ] Support environment-specific configs (dev/staging/production)
#### 1.5 User Experience Improvements
**Goal:** Enhanced web interface, better monitoring, and alerting system
- **Web Interface Enhancements**
- [ ] Mobile-responsive design (tablet and phone support)
- [ ] Dark/Light theme toggle with user preference saving
- [ ] Advanced charting with TradingView widget integration
- [ ] Real-time WebSocket updates (replace polling for positions/orders)
- [ ] Drag-and-drop dashboard customization
- [ ] Multi-language support (EN, CN, RU, UK)
- **Configuration Interface**
- [ ] Visual strategy builder (no-code flow diagram)
- [ ] Live configuration preview before saving
- [ ] Configuration templates for common strategies
- [ ] Bulk trader management (start/stop multiple traders)
- [ ] Exchange credential testing (verify before saving)
- [ ] AI model testing interface (test prompts before deployment)
- **Monitoring & Analytics**
- [ ] Real-time performance dashboard with key metrics
- [ ] Equity curve visualization (per trader, per exchange, overall)
- [ ] Drawdown analysis and risk metrics
- [ ] Trade history with filtering and search
- [ ] P&L breakdown by symbol, time period, strategy
- [ ] Comparison view (multiple traders side-by-side)
- [ ] Export functionality (CSV, JSON, PDF reports)
- **Alert & Notification System**
- [ ] Multi-channel alerts (Email, Telegram, Discord, Webhook)
- [ ] Configurable alert rules (profit threshold, loss limit, error detection)
- [ ] Alert priority levels (critical, warning, info)
- [ ] Alert history and acknowledgment tracking
- [ ] Daily/Weekly performance summary emails
- [ ] System health monitoring (API connectivity, database status)
### Phase 2: Testing & Stability
#### 2.1 Quality Assurance
- [ ] Comprehensive unit test coverage (>80%)
- [ ] Integration tests for all exchange adapters
- [ ] Load testing (100+ concurrent traders)
- [ ] Security audit (API key encryption, SQL injection prevention)
#### 2.2 Documentation
- [ ] Complete API reference documentation
- [ ] Video tutorials for beginners
- [ ] Strategy development guide
- [ ] Troubleshooting playbook
#### 2.3 Community Features
- [ ] Public strategy marketplace (share/sell strategies)
- [ ] Leaderboard with verified performance
- [ ] Community forum integration
- [ ] Bug bounty program
---
## 🚀 Long-Term Roadmap
### Phase 3: Universal Market Expansion
**Goal:** Extend the proven crypto trading infrastructure to all major financial markets.
#### 3.1 Stock Markets
- [ ] US Equities (Interactive Brokers, Alpaca Markets)
- [ ] Asian Markets (A-shares, Hong Kong, Japan)
- [ ] Fundamental analysis integration (earnings, P/E, dividends)
- [ ] AI-powered stock screening
#### 3.2 Futures Markets
- [ ] Commodity Futures (Energy, Metals, Agriculture)
- [ ] Index Futures (S&P 500, NASDAQ, Dow Jones, VIX)
- [ ] Rollover management and spread trading
#### 3.3 Options Trading
- [ ] Options chain data and Greeks calculation
- [ ] Equity, Index, and Crypto options
- [ ] Options strategy builder
#### 3.4 Forex Markets
- [ ] Major currency pairs and exotic pairs
- [ ] Interest rate analysis and carry trade support
---
### Phase 4: Advanced AI & Automation
**Goal:** Implement cutting-edge AI technologies for autonomous trading.
- [ ] Multi-Agent orchestration (specialized agents with dynamic coordination)
- [ ] Reinforcement Learning (DQN, PPO, transfer learning)
- [ ] Alternative data integration (social sentiment, news, on-chain analytics)
---
### Phase 5: Enterprise & Scaling
**Goal:** Scale infrastructure for institutional use and high-volume trading.
- [ ] Database migration (PostgreSQL/MySQL, Redis, TimescaleDB)
- [ ] Microservices architecture with Kubernetes deployment
- [ ] Multi-user RBAC and white-label solutions
- [ ] Advanced analytics and compliance reporting
---
## 📊 Key Metrics & Milestones
### Short-Term Targets
- [ ] **100+** supported trading pairs across all exchanges
- [ ] **10,000+** active trader instances
- [ ] **5+** new exchange integrations
- [ ] **80%+** test coverage
- [ ] **99.9%** uptime
### Long-Term Targets
- [ ] **All major asset classes** supported (crypto, stocks, futures, options, forex)
- [ ] **50,000+** active users
- [ ] **Enterprise tier** launched
- [ ] **Institutional partnerships** established
---
## 🤝 Community Involvement
We welcome community contributions to accelerate our roadmap:
- **Vote on Features**: Join our [Telegram community](https://t.me/nofx_dev_community) to vote on priority features
- **Contribute Code**: Check our [Contributing Guide](../../CONTRIBUTING.md)
- **Bug Bounties**: Report issues and earn rewards
- **Strategy Sharing**: Share your successful strategies
---
## 📝 Roadmap Updates
This roadmap is reviewed and updated quarterly based on:
- Community feedback
- Market demands
- Technical feasibility
- Resource availability
**Last Updated:** 2025-11-01
---
## 📚 Related Documentation
- [Architecture Documentation](../architecture/README.md) - Technical architecture details
- [Getting Started](../getting-started/README.md) - Setup and deployment
- [Contributing Guide](../../CONTRIBUTING.md) - How to contribute
- [Changelog](../../CHANGELOG.md) - Version history
---
[← Back to Documentation Home](../README.md)

292
docs/roadmap/README.zh-CN.md Normal file
View File

@@ -0,0 +1,292 @@
# 🗺️ NOFX 路线图
**语言:** [English](README.md) | [中文](README.zh-CN.md)
NOFX 发展和通用市场扩展的战略规划。
---
## 📋 概述
NOFX 的使命是成为所有金融市场的**通用 AI 交易操作系统**。我们在加密货币市场上经过验证的基础设施正在扩展到股票、期货、期权、外汇等领域。
**愿景：** 相同架构。相同智能体框架。所有市场。
---
## 🎯 短期路线图
### 阶段1: 核心基础设施增强
#### 1.1 安全性增强
**目标：** 保护敏感数据，减少安全漏洞
- **凭证管理**
- [ ] 为数据库中的API密钥实现AES-256加密
- [ ] 为私钥（Hyperliquid、Aster）添加加密
- [ ] 为生产环境支持硬件安全模块（HSM）
- [ ] 实现密钥轮换机制
- [ ] 为所有凭证访问添加审计日志
- **应用安全**
- [ ] 输入验证和清理（防止SQL注入、XSS攻击）
- [ ] API端点的速率限制
- [ ] CORS策略配置
- [ ] JWT令牌过期和刷新机制
- [ ] 实现RBAC（基于角色的访问控制）支持多用户
- [ ] 添加API访问的IP白名单
- [ ] 安全头部（CSP、HSTS、X-Frame-Options）
- **运营安全**
- [ ] 安全密码哈希（bcrypt加盐）
- [ ] 2FA增强（备份码、多个TOTP设备）
- [ ] 会话管理（自动登出、并发会话限制）
- [ ] 密钥管理（环境变量、vault集成）
- [ ] 定期依赖项漏洞扫描
#### 1.2 增强AI能力
**目标：** 更丰富的prompts、灵活配置、支持更多AI模型
- **Prompt系统全面改造**
- [ ] 动态prompt生成的模板引擎
- [ ] 多语言prompt支持（思维链、few-shot、zero-shot）
- [ ] 基于市场状况的prompt切换（牛市、熊市、震荡）
- [ ] 在prompts中集成历史绩效反馈
- [ ] Prompt版本控制和A/B测试框架
- [ ] 通过Web界面自定义prompt模板
- **AI模型集成**
- [ ] OpenAI GPT-4/GPT-4 Turbo支持
- [ ] Anthropic Claude 3（Opus、Sonnet、Haiku）集成
- [ ] Google Gemini Pro支持
- [ ] 本地LLM支持（通过Ollama的Llama、Mistral）
- [ ] 多模型集成（投票、加权平均）
- [ ] 模型性能跟踪和自动选择
- [ ] 主模型失败时的降级机制
- **AI决策引擎**
- [ ] 每个决策的置信度评分
- [ ] 解释生成（为什么做这笔交易？）
- [ ] AI推理中的风险评估集成
- [ ] 市场状态检测（趋势、均值回归、高波动）
- [ ] 与技术指标的交叉验证
#### 1.3 交易所集成扩展
**目标：** 支持更多CEX和流行的perp-DEX，现货和合约
- **中心化交易所（CEX）**
- [ ] **OKX** - 合约 + 现货交易
- [ ] **Bybit** - 合约 + 现货交易
- [ ] **Bitget** - 合约 + 现货交易
- [ ] **Gate.io** - 合约 + 现货交易
- [ ] **KuCoin** - 合约 + 现货交易
- [ ] 统一的CEX接口，便于添加新交易所
- **去中心化永续交易所（Perp-DEX）**
- [x] **Hyperliquid**（Ethereum L1）- 高性能订单簿DEX（✅ 已支持）
- [x] **Aster**（多链）- Binance兼容API的DEX（✅ 已支持）
- [ ] **Lighter**（Arbitrum）- 无Gas订单簿DEX，链下撮合
- [ ] **EdgeX**（多链）- 专业衍生品DEX
- [ ] 统一的DEX接口，保证集成一致性
- [ ] 增强Hyperliquid集成（测试网支持、高级订单类型）
- [ ] 增强Aster集成（跨链支持、钱包管理）
- **现货 + 合约支持**
- [ ] 双模式交易（现货套利、合约对冲）
- [ ] 跨交易所套利检测
- [ ] 现货和合约的统一持仓跟踪
- [ ] 现货和永续策略之间的自动转换
- **交易所基础设施**
- [ ] **交易数据分析API集成**（自研）
- [ ] AI500集成 - 自研AI选币模型
- [ ] OI（持仓量）分析 - 实时持仓量跟踪和异常检测
- [ ] NetFlow分析 - 链上资金流向分析，用于市场情绪判断
- [ ] 市场情绪聚合器 - 整合多个数据源，增强AI决策能力
- [ ] 自定义指标API - 支持专有技术指标
- [ ] 自动精度处理（数量、价格小数位）
- [ ] 订单类型抽象（市价、限价、止损、止盈）
- [ ] 统一的错误处理和重试逻辑
- [ ] 实时数据的WebSocket支持
- [ ] 每个交易所的速率限制管理
#### 1.4 项目结构重构
**目标：** 清晰层次、高内聚低耦合、易于扩展和维护
- **架构重新设计**
- [ ] 实现分层架构（表现层 → 业务逻辑层 → 数据访问层）
- [ ] 应用SOLID原则（特别是里氏替换原则用于交易所适配器）
- [ ] 为所有交易所实现提取通用接口
- [ ] 分离关注点：交易逻辑、数据获取、决策制定、执行
- [ ] 实现依赖注入以提高可测试性
- **代码组织**
- [ ] 将单体模块重构为更小、更专注的包
- [ ] 为traders、exchanges、AI模型创建抽象基类
- [ ] 实现工厂模式用于交易所/AI模型的创建
- [ ] 标准化所有模块的错误处理和日志记录
- [ ] 消除循环依赖并改进导入结构
- **配置管理**
- [ ] 将所有配置集中到结构化配置文件中
- [ ] 实现非关键配置的热重载
- [ ] 启动时验证配置并提供清晰的错误消息
- [ ] 支持环境特定配置（dev/staging/production）
#### 1.5 用户体验改进
**目标：** 增强Web界面、更好的监控和告警系统
- **Web界面增强**
- [ ] 移动端响应式设计（平板和手机支持）
- [ ] 深色/浅色主题切换并保存用户偏好
- [ ] TradingView小部件集成的高级图表
- [ ] 实时WebSocket更新（替代持仓/订单的轮询）
- [ ] 拖拽式仪表板自定义
- [ ] 多语言支持（EN、CN、RU、UK）
- **配置界面**
- [ ] 可视化策略构建器（无代码流程图）
- [ ] 保存前的实时配置预览
- [ ] 常用策略的配置模板
- [ ] 批量trader管理（启动/停止多个traders）
- [ ] 交易所凭证测试（保存前验证）
- [ ] AI模型测试界面（部署前测试prompts）
- **监控与分析**
- [ ] 实时性能仪表板和关键指标
- [ ] 权益曲线可视化（每个trader、每个交易所、总体）
- [ ] 回撤分析和风险指标
- [ ] 带过滤和搜索的交易历史
- [ ] 按币种、时间段、策略的盈亏分解
- [ ] 比较视图（多个traders并排）
- [ ] 导出功能（CSV、JSON、PDF报告）
- **告警与通知系统**
- [ ] 多渠道告警（Email、Telegram、Discord、Webhook）
- [ ] 可配置的告警规则（利润阈值、亏损限制、错误检测）
- [ ] 告警优先级（严重、警告、信息）
- [ ] 告警历史和确认跟踪
- [ ] 每日/每周性能摘要邮件
- [ ] 系统健康监控（API连接、数据库状态）
### 阶段2: 测试与稳定性
#### 2.1 质量保证
- [ ] 全面的单元测试覆盖率（>80%）
- [ ] 所有交易所适配器的集成测试
- [ ] 负载测试（100+并发交易者）
- [ ] 安全审计（API密钥加密、SQL注入防护）
#### 2.2 文档
- [ ] 完整的API参考文档
- [ ] 新手视频教程
- [ ] 策略开发指南
- [ ] 故障排查手册
#### 2.3 社区功能
- [ ] 公开策略市场（分享/出售策略）
- [ ] 经过验证的绩效排行榜
- [ ] 社区论坛集成
- [ ] 漏洞赏金计划
---
## 🚀 长期路线图
### 阶段3: 通用市场扩展
**目标：** 将经过验证的加密货币交易基础设施扩展到所有主要金融市场。
#### 3.1 股票市场
- [ ] 美股（Interactive Brokers、Alpaca Markets）
- [ ] 亚洲市场（A股、香港、日本）
- [ ] 基本面分析集成（财报、市盈率、股息）
- [ ] AI驱动的股票筛选
#### 3.2 期货市场
- [ ] 商品期货（能源、金属、农产品）
- [ ] 指数期货（标普500、纳斯达克、道琼斯、VIX）
- [ ] 展期管理和价差交易
#### 3.3 期权交易
- [ ] 期权链数据和Greeks计算
- [ ] 股票、指数和加密期权
- [ ] 期权策略构建器
#### 3.4 外汇市场
- [ ] 主要货币对和稀有货币对
- [ ] 利率分析和套息交易支持
---
### 阶段4: 高级AI与自动化
**目标：** 实现前沿AI技术用于自主交易。
- [ ] 多智能体编排（专业化智能体与动态协调）
- [ ] 强化学习（DQN、PPO、迁移学习）
- [ ] 替代数据集成（社交情绪、新闻、链上分析）
---
### 阶段5: 企业级与扩展
**目标：** 扩展基础设施以支持机构使用和高频交易。
- [ ] 数据库迁移（PostgreSQL/MySQL、Redis、TimescaleDB）
- [ ] 微服务架构与Kubernetes部署
- [ ] 多用户RBAC和白标解决方案
- [ ] 高级分析和合规报告
---
## 📊 关键指标与里程碑
### 短期目标
- [ ] 所有交易所支持**100+**交易对
- [ ] **10,000+**活跃交易者实例
- [ ] **5+**新交易所集成
- [ ] **80%+**测试覆盖率
- [ ] **99.9%**正常运行时间
### 长期目标
- [ ] 支持**所有主要资产类别**（加密、股票、期货、期权、外汇）
- [ ] **50,000+**活跃用户
- [ ] **企业级**版本发布
- [ ] 建立**机构合作伙伴关系**
---
## 🤝 社区参与
我们欢迎社区贡献来加速我们的路线图：
- **功能投票**: 加入我们的[Telegram社区](https://t.me/nofx_dev_community)投票优先功能
- **贡献代码**: 查看我们的[贡献指南](../../CONTRIBUTING.md)
- **漏洞赏金**: 报告问题并获得奖励
- **策略分享**: 分享你的成功策略
---
## 📝 路线图更新
本路线图根据以下因素每季度审查和更新：
- 社区反馈
- 市场需求
- 技术可行性
- 资源可用性
**最后更新:** 2025-11-01
---
## 📚 相关文档
- [架构文档](../architecture/README.zh-CN.md) - 技术架构详情
- [快速开始](../getting-started/README.zh-CN.md) - 设置和部署
- [贡献指南](../../CONTRIBUTING.md) - 如何贡献
- [更新日志](../../CHANGELOG.zh-CN.md) - 版本历史
---
[← 返回文档主页](../README.md)