mirror of
https://github.com/laoxong/nofx.git
synced 2026-06-04 09:58:22 +08:00
Merge pull request #226 from xqliu/docs/enhance-bug-report-template
docs: Enhance bug report template and add troubleshooting guide
This commit is contained in:
Luna Martinez
GitHub
@@ -6,42 +6,162 @@ labels: bug
|
||||
assignees: ''
|
||||
---
|
||||
|
||||
> **⚠️ Before submitting:** Please check the [Troubleshooting Guide](../../docs/guides/TROUBLESHOOTING.md) ([中文版](../../docs/guides/TROUBLESHOOTING.zh-CN.md)) to see if your issue can be resolved quickly.
|
||||
|
||||
## 🐛 Bug Description
|
||||
<!-- A clear and concise description of what the bug is -->
|
||||
|
||||
|
||||
## 🔍 Bug Category
|
||||
<!-- Check the category that best describes this bug -->
|
||||
- [ ] Trading execution (orders not executing, wrong position size, etc.)
|
||||
- [ ] AI decision issues (unexpected decisions, only opening one direction, etc.)
|
||||
- [ ] Exchange connection (API errors, authentication failures, etc.)
|
||||
- [ ] UI/Frontend (display issues, buttons not working, data not updating, etc.)
|
||||
- [ ] Backend/API (server errors, crashes, performance issues, etc.)
|
||||
- [ ] Configuration (settings not saving, database errors, etc.)
|
||||
- [ ] Other: _________________
|
||||
|
||||
## 📋 Steps to Reproduce
|
||||
1. Go to '...'
|
||||
2. Click on '...'
|
||||
3. Run command '...'
|
||||
2. Click on '...' / Run command '...'
|
||||
3. Configure '...'
|
||||
4. See error
|
||||
|
||||
## ✅ Expected Behavior
|
||||
<!-- What you expected to happen -->
|
||||
|
||||
|
||||
## ❌ Actual Behavior
|
||||
<!-- What actually happened -->
|
||||
|
||||
## 📸 Screenshots / Logs
|
||||
<!-- If applicable, add screenshots or error logs to help explain your problem -->
|
||||
|
||||
## 📸 Screenshots & Logs
|
||||
|
||||
### Frontend Error (if applicable)
|
||||
<!-- How to capture frontend errors: -->
|
||||
<!-- 1. Open browser DevTools (F12 or Right-click → Inspect) -->
|
||||
<!-- 2. Go to "Console" tab to see JavaScript errors -->
|
||||
<!-- 3. Screenshot the error messages -->
|
||||
<!-- 4. Check "Network" tab for failed API requests (show status code & response) -->
|
||||
|
||||
**Browser Console Screenshot:**
|
||||
<!-- Paste screenshot here -->
|
||||
|
||||
**Network Tab (failed requests):**
|
||||
<!-- Paste screenshot of failed API calls here -->
|
||||
|
||||
### Backend Logs (if applicable)
|
||||
<!-- How to capture backend logs: -->
|
||||
|
||||
**Docker users:**
|
||||
```bash
|
||||
# View backend logs
|
||||
docker compose logs backend --tail=100
|
||||
|
||||
# OR continuously follow logs
|
||||
docker compose logs -f backend
|
||||
```
|
||||
Paste logs here
|
||||
|
||||
**Manual/PM2 users:**
|
||||
```bash
|
||||
# Terminal output where you ran: ./nofx
|
||||
# OR PM2 logs:
|
||||
pm2 logs nofx --lines 100
|
||||
```
|
||||
|
||||
**Backend Log Output:**
|
||||
```
|
||||
Paste backend logs here (last 50-100 lines around the error)
|
||||
```
|
||||
|
||||
### Trading/Decision Logs (if trading issue)
|
||||
<!-- Decision logs are saved in: decision_logs/{trader_id}/ -->
|
||||
<!-- Find the latest JSON file and paste relevant parts -->
|
||||
|
||||
**Decision Log Path:** `decision_logs/{trader_id}/{timestamp}.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"paste relevant decision log here if applicable"
|
||||
}
|
||||
```
|
||||
|
||||
## 💻 Environment
|
||||
|
||||
**System:**
|
||||
- **OS:** [e.g. macOS 13, Ubuntu 22.04, Windows 11]
|
||||
- **Go Version:** [e.g. 1.21.5]
|
||||
- **Node.js Version:** [e.g. 18.17.0]
|
||||
- **NOFX Version/Commit:** [e.g. v3.0.0 or commit hash]
|
||||
- **Deployment Method:** [Docker / Manual / PM2]
|
||||
- **Deployment:** [Docker / Manual / PM2]
|
||||
|
||||
**Backend:**
|
||||
- **Go Version:** [run: `go version`]
|
||||
- **NOFX Version:** [run: `git log -1 --oneline` or check release tag]
|
||||
|
||||
**Frontend:**
|
||||
- **Browser:** [e.g. Chrome 120, Firefox 121, Safari 17]
|
||||
- **Node.js Version:** [run: `node -v`]
|
||||
|
||||
**Trading Setup:**
|
||||
- **Exchange:** [Binance / Hyperliquid / Aster]
|
||||
- **Account Type:** [Main Account / Subaccount]
|
||||
- **Position Mode:** [Hedge Mode (Dual) / One-way Mode] ← **Important for trading bugs!**
|
||||
- **AI Model:** [DeepSeek / Qwen / Custom]
|
||||
- **Number of Traders:** [e.g. 1, 2, etc.]
|
||||
|
||||
## 🔧 Additional Context
|
||||
<!-- Add any other context about the problem here -->
|
||||
## 🔧 Configuration (if relevant)
|
||||
<!-- Only include non-sensitive parts of your config -->
|
||||
<!-- ⚠️ NEVER paste API keys or private keys! -->
|
||||
|
||||
- Does this happen consistently or intermittently?
|
||||
- Did it work before? When did it break?
|
||||
- Any recent configuration changes?
|
||||
**Leverage Settings:**
|
||||
```json
|
||||
{
|
||||
"btc_eth_leverage": 5,
|
||||
"altcoin_leverage": 5
|
||||
}
|
||||
```
|
||||
|
||||
## ✋ Possible Solution
|
||||
<!-- Optional: If you have ideas on how to fix this -->
|
||||
**Any custom settings:**
|
||||
<!-- e.g. modified scan_interval, custom coin list, etc. -->
|
||||
|
||||
|
||||
## 📊 Additional Context
|
||||
|
||||
**Frequency:**
|
||||
- [ ] Happens every time
|
||||
- [ ] Happens randomly
|
||||
- [ ] Happened once
|
||||
|
||||
**Timeline:**
|
||||
- Did this work before? [ ] Yes [ ] No
|
||||
- When did it break? [e.g. after upgrade to v3.0.0, after changing config, etc.]
|
||||
- Recent changes? [e.g. updated dependencies, changed exchange, etc.]
|
||||
|
||||
**Impact:**
|
||||
- [ ] System cannot start
|
||||
- [ ] Trading stopped/broken
|
||||
- [ ] UI broken but trading works
|
||||
- [ ] Minor visual issue
|
||||
- [ ] Other: _________________
|
||||
|
||||
## 💡 Possible Solution
|
||||
<!-- Optional: If you have ideas on how to fix this, or workarounds you've tried -->
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 📝 Quick Tips for Faster Resolution
|
||||
|
||||
**For Trading Issues:**
|
||||
1. ✅ Check Binance position mode: Go to Futures → ⚙️ Preferences → Position Mode → Must be **Hedge Mode**
|
||||
2. ✅ Verify API permissions: Futures trading must be enabled
|
||||
3. ✅ Check decision logs in `decision_logs/{trader_id}/` for AI reasoning
|
||||
|
||||
**For Connection Issues:**
|
||||
4. ✅ Test API connectivity: `curl http://localhost:8080/api/health`
|
||||
5. ✅ Check API rate limits on exchange
|
||||
6. ✅ Verify API keys are not expired
|
||||
|
||||
**For UI Issues:**
|
||||
7. ✅ Hard refresh: Ctrl+Shift+R (or Cmd+Shift+R on Mac)
|
||||
8. ✅ Check browser console (F12) for errors
|
||||
9. ✅ Verify backend is running: `docker compose ps` or `ps aux | grep nofx`
|
||||
|
||||
@@ -1170,6 +1170,8 @@ GET /api/health # Health check
|
||||
|
||||
## 🛠️ Common Issues
|
||||
|
||||
> 📖 **For detailed troubleshooting:** See the comprehensive [Troubleshooting Guide](docs/guides/TROUBLESHOOTING.md) ([中文版](docs/guides/TROUBLESHOOTING.zh-CN.md))
|
||||
|
||||
### 1. Compilation error: TA-Lib not found
|
||||
|
||||
**Solution**: Install TA-Lib library
|
||||
|
||||
@@ -0,0 +1,612 @@
|
||||
# 🔧 Troubleshooting Guide
|
||||
|
||||
This guide helps you diagnose and fix common issues before submitting a bug report.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Quick Diagnostic Checklist
|
||||
|
||||
Before reporting a bug, please check:
|
||||
|
||||
1. ✅ **Backend is running**: `docker compose ps` or `ps aux | grep nofx`
|
||||
2. ✅ **Frontend is accessible**: Open http://localhost:3000 in browser
|
||||
3. ✅ **API is responding**: `curl http://localhost:8080/api/health`
|
||||
4. ✅ **Check logs for errors**: See [How to Capture Logs](#how-to-capture-logs) below
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Common Issues & Solutions
|
||||
|
||||
### 1. Trading Issues
|
||||
|
||||
#### ❌ Only Opening Short Positions (Issue #202)
|
||||
|
||||
**Symptom:** AI only opens short positions, never long positions, even when market is bullish.
|
||||
|
||||
**Root Cause:** Binance account is in **One-way Mode** instead of **Hedge Mode**.
|
||||
|
||||
**Solution:**
|
||||
1. Login to [Binance Futures](https://www.binance.com/futures/BTCUSDT)
|
||||
2. Click **⚙️ Preferences** (top right)
|
||||
3. Select **Position Mode**
|
||||
4. Switch to **Hedge Mode** (双向持仓)
|
||||
5. ⚠️ **Important:** Close all positions before switching
|
||||
|
||||
**Why this happens:**
|
||||
- Code uses `PositionSide(LONG)` and `PositionSide(SHORT)` parameters
|
||||
- These only work in Hedge Mode
|
||||
- In One-way Mode, orders fail or only one direction works
|
||||
|
||||
**For Subaccounts:**
|
||||
- Some Binance subaccounts may not have permission to change position mode
|
||||
- Use main account or contact Binance support to enable this permission
|
||||
|
||||
---
|
||||
|
||||
#### ❌ Order Error: `code=-4061` Position Side Mismatch
|
||||
|
||||
**Error Message:** `Order's position side does not match user's setting`
|
||||
|
||||
**Solution:** Same as above - switch to Hedge Mode.
|
||||
|
||||
---
|
||||
|
||||
#### ❌ Leverage Error: `Subaccounts restricted to 5x leverage`
|
||||
|
||||
**Symptom:** Orders fail with leverage error when trying to use >5x leverage.
|
||||
|
||||
**Solution:**
|
||||
1. Open Web UI → Trader Settings
|
||||
2. Set leverage to 5x or lower:
|
||||
```json
|
||||
{
|
||||
"btc_eth_leverage": 5,
|
||||
"altcoin_leverage": 5
|
||||
}
|
||||
```
|
||||
3. Or use main account (supports up to 50x BTC/ETH, 20x altcoins)
|
||||
|
||||
---
|
||||
|
||||
#### ❌ Positions Not Executing
|
||||
|
||||
**Check these:**
|
||||
1. **API Permissions**:
|
||||
- Go to Binance → API Management
|
||||
- Verify "Enable Futures" is checked
|
||||
- Check IP whitelist (if enabled)
|
||||
|
||||
2. **Account Balance**:
|
||||
- Ensure sufficient USDT in Futures wallet
|
||||
- Check margin usage is not at 100%
|
||||
|
||||
3. **Symbol Status**:
|
||||
- Verify trading pair is active on exchange
|
||||
- Check if symbol is in maintenance mode
|
||||
|
||||
4. **Decision Logs**:
|
||||
```bash
|
||||
# Check latest decision
|
||||
ls -lt decision_logs/your_trader_id/ | head -5
|
||||
cat decision_logs/your_trader_id/latest_file.json
|
||||
```
|
||||
- Look for AI decision: was it "wait", "hold", or actual trade?
|
||||
- Check if position_size_usd is within limits
|
||||
|
||||
---
|
||||
|
||||
### 2. AI Decision Issues
|
||||
|
||||
#### ❌ AI Always Says "Wait" / "Hold"
|
||||
|
||||
**Possible Causes:**
|
||||
1. **Market Conditions**: AI may genuinely see no good opportunities
|
||||
2. **Risk Limits**: Account equity too low, margin usage too high
|
||||
3. **Historical Performance**: AI being cautious after losses
|
||||
|
||||
**How to Check:**
|
||||
```bash
|
||||
# View latest decision reasoning
|
||||
cat decision_logs/your_trader_id/$(ls -t decision_logs/your_trader_id/ | head -1)
|
||||
```
|
||||
|
||||
Look at the AI's Chain-of-Thought reasoning section.
|
||||
|
||||
**Solutions:**
|
||||
- Wait for better market conditions
|
||||
- Check if all candidate coins have low liquidity
|
||||
- Verify `use_default_coins: true` or coin pool API is working
|
||||
|
||||
---
|
||||
|
||||
#### ❌ AI Making Bad Decisions
|
||||
|
||||
**Remember:** AI trading is experimental and not guaranteed to be profitable.
|
||||
|
||||
**Things to Check:**
|
||||
1. **Decision Interval**: Is it too short? (Recommended: 3-5 minutes)
|
||||
2. **Leverage Settings**: Too aggressive?
|
||||
3. **Historical Feedback**: Check performance logs to see if AI is learning
|
||||
4. **Market Volatility**: High volatility = higher risk
|
||||
|
||||
**Adjustments:**
|
||||
- Reduce leverage for more conservative trading
|
||||
- Increase decision interval to reduce over-trading
|
||||
- Use smaller initial balance for testing
|
||||
|
||||
---
|
||||
|
||||
### 3. Connection & API Issues
|
||||
|
||||
#### ❌ Docker Image Pull Failed (China Mainland)
|
||||
|
||||
**Error:** `ERROR [internal] load metadata for docker.io/library/...`
|
||||
|
||||
**Symptoms:**
|
||||
- `docker compose build` or `docker compose up` hangs
|
||||
- Timeout errors: `timeout`, `connection refused`
|
||||
- Cannot pull images from Docker Hub
|
||||
|
||||
**Root Cause:**
|
||||
Access to Docker Hub is restricted or extremely slow in mainland China.
|
||||
|
||||
**Solution 1: Configure Docker Registry Mirror (Recommended)**
|
||||
|
||||
1. **Edit Docker configuration file:**
|
||||
```bash
|
||||
# Linux
|
||||
sudo nano /etc/docker/daemon.json
|
||||
|
||||
# macOS (Docker Desktop)
|
||||
# Settings → Docker Engine
|
||||
```
|
||||
|
||||
2. **Add China registry mirrors:**
|
||||
```json
|
||||
{
|
||||
"registry-mirrors": [
|
||||
"https://docker.m.daocloud.io",
|
||||
"https://docker.1panel.live",
|
||||
"https://hub.rat.dev",
|
||||
"https://dockerpull.com",
|
||||
"https://dockerhub.icu"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
3. **Restart Docker:**
|
||||
```bash
|
||||
# Linux
|
||||
sudo systemctl restart docker
|
||||
|
||||
# macOS/Windows
|
||||
# Restart Docker Desktop
|
||||
```
|
||||
|
||||
4. **Rebuild:**
|
||||
```bash
|
||||
docker compose build --no-cache
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
**Solution 2: Use VPN**
|
||||
|
||||
1. Connect to VPN (Taiwan nodes recommended)
|
||||
2. Ensure **global mode** instead of rule-based mode
|
||||
3. Re-run `docker compose build`
|
||||
|
||||
**Solution 3: Offline Image Download**
|
||||
|
||||
If above methods don't work:
|
||||
|
||||
1. **Use image proxy websites:**
|
||||
- https://proxy.vvvv.ee/images.html (offline download available)
|
||||
- https://github.com/dongyubin/DockerHub (mirror list)
|
||||
|
||||
2. **Manually import images:**
|
||||
```bash
|
||||
# After downloading image files
|
||||
docker load -i golang-1.25-alpine.tar
|
||||
docker load -i node-20-alpine.tar
|
||||
docker load -i nginx-alpine.tar
|
||||
```
|
||||
|
||||
3. **Verify images are loaded:**
|
||||
```bash
|
||||
docker images | grep golang
|
||||
docker images | grep node
|
||||
docker images | grep nginx
|
||||
```
|
||||
|
||||
**Verify registry mirror is working:**
|
||||
```bash
|
||||
# Check Docker info
|
||||
docker info | grep -A 10 "Registry Mirrors"
|
||||
|
||||
# Should show your configured mirrors
|
||||
```
|
||||
|
||||
**Related Issue:** [#168](https://github.com/tinkle-community/nofx/issues/168)
|
||||
|
||||
---
|
||||
|
||||
#### ❌ Backend Won't Start
|
||||
|
||||
**Error:** `port 8080 already in use`
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Find what's using the port
|
||||
lsof -i :8080
|
||||
# OR
|
||||
netstat -tulpn | grep 8080
|
||||
|
||||
# Kill the process or change port in .env
|
||||
NOFX_BACKEND_PORT=8081
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### ❌ Frontend Can't Connect to Backend
|
||||
|
||||
**Symptoms:**
|
||||
- UI shows "Loading..." forever
|
||||
- Browser console shows 404 or network errors
|
||||
|
||||
**Solutions:**
|
||||
1. **Check backend is running:**
|
||||
```bash
|
||||
docker compose ps # Should show backend as "Up"
|
||||
# OR
|
||||
curl http://localhost:8080/api/health # Should return {"status":"ok"}
|
||||
```
|
||||
|
||||
2. **Check port configuration:**
|
||||
- Backend default: 8080
|
||||
- Frontend default: 3000
|
||||
- Verify `.env` settings match
|
||||
|
||||
3. **CORS Issues:**
|
||||
- If running frontend and backend on different ports/domains
|
||||
- Check browser console for CORS errors
|
||||
- Backend should allow frontend origin
|
||||
|
||||
---
|
||||
|
||||
#### ❌ Exchange API Errors
|
||||
|
||||
**Common Errors:**
|
||||
- `code=-1021, msg=Timestamp for this request is outside of the recvWindow`
|
||||
- `invalid signature`
|
||||
- `timestamp` errors
|
||||
|
||||
**Root Cause:**
|
||||
System time is inaccurate, differing from Binance server time by more than allowed range (typically 5 seconds).
|
||||
|
||||
**Solution 1: Sync System Time (Recommended)**
|
||||
|
||||
```bash
|
||||
# Method 1: Use ntpdate (most common)
|
||||
sudo ntpdate pool.ntp.org
|
||||
|
||||
# Method 2: Use other NTP servers
|
||||
sudo ntpdate -s time.nist.gov
|
||||
sudo ntpdate -s ntp.aliyun.com # Aliyun NTP (fast in China)
|
||||
|
||||
# Method 3: Enable automatic time sync (Linux)
|
||||
sudo timedatectl set-ntp true
|
||||
|
||||
# Verify time is correct
|
||||
date
|
||||
# Should show current accurate time
|
||||
```
|
||||
|
||||
**Docker Environment Special Note:**
|
||||
|
||||
If using Docker, container time may be out of sync with host:
|
||||
|
||||
```bash
|
||||
# Check container time
|
||||
docker exec nofx-backend date
|
||||
|
||||
# If time is wrong, restart Docker service
|
||||
sudo systemctl restart docker
|
||||
|
||||
# Or add timezone in docker-compose.yml
|
||||
environment:
|
||||
- TZ=Asia/Shanghai # or your timezone
|
||||
```
|
||||
|
||||
**Solution 2: Verify API Keys**
|
||||
|
||||
If errors persist after time sync:
|
||||
|
||||
1. **Check API Keys:**
|
||||
- Not expired
|
||||
- Have correct permissions (Futures enabled)
|
||||
- IP whitelist includes your server IP
|
||||
|
||||
2. **Regenerate API Keys:**
|
||||
- Login to Binance → API Management
|
||||
- Delete old key
|
||||
- Create new key
|
||||
- Update NOFX configuration
|
||||
|
||||
**Solution 3: Check Rate Limits**
|
||||
|
||||
Binance has strict API rate limits:
|
||||
|
||||
- **Requests per minute limit**
|
||||
- Reduce number of traders
|
||||
- Increase decision interval (e.g., from 1min to 3-5min)
|
||||
|
||||
**Related Issue:** [#60](https://github.com/tinkle-community/nofx/issues/60)
|
||||
|
||||
---
|
||||
|
||||
### 4. Frontend Issues
|
||||
|
||||
#### ❌ UI Not Updating / Showing Old Data
|
||||
|
||||
**Solutions:**
|
||||
1. **Hard Refresh:**
|
||||
- Chrome/Firefox: `Ctrl+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac)
|
||||
- Safari: `Cmd+Option+R`
|
||||
|
||||
2. **Clear Browser Cache:**
|
||||
- Settings → Privacy → Clear browsing data
|
||||
- Or open in Incognito/Private mode
|
||||
|
||||
3. **Check SWR Polling:**
|
||||
- Frontend uses SWR with 5-10s intervals
|
||||
- Data should auto-refresh
|
||||
- Check browser console for fetch errors
|
||||
|
||||
---
|
||||
|
||||
#### ❌ Charts Not Rendering
|
||||
|
||||
**Possible Causes:**
|
||||
1. No historical data yet (system just started)
|
||||
2. JavaScript errors in console
|
||||
3. Browser compatibility issues
|
||||
|
||||
**Solutions:**
|
||||
- Wait 5-10 minutes for data to accumulate
|
||||
- Check browser console (F12) for errors
|
||||
- Try different browser (Chrome recommended)
|
||||
- Ensure backend API endpoints are returning data
|
||||
|
||||
---
|
||||
|
||||
### 5. Database Issues
|
||||
|
||||
#### ❌ `database is locked` Error
|
||||
|
||||
**Cause:** SQLite database being accessed by multiple processes.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Stop all NOFX processes
|
||||
docker compose down
|
||||
# OR
|
||||
pkill nofx
|
||||
|
||||
# Restart
|
||||
docker compose up -d
|
||||
# OR
|
||||
./nofx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### ❌ Trader Configuration Not Saving
|
||||
|
||||
**Check:**
|
||||
1. **Permissions:**
|
||||
```bash
|
||||
ls -l config.db trading.db
|
||||
# Should be writable by current user
|
||||
```
|
||||
|
||||
2. **Disk Space:**
|
||||
```bash
|
||||
df -h # Ensure disk not full
|
||||
```
|
||||
|
||||
3. **Database Integrity:**
|
||||
```bash
|
||||
sqlite3 config.db "PRAGMA integrity_check;"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 How to Capture Logs
|
||||
|
||||
### Backend Logs
|
||||
|
||||
**Docker:**
|
||||
```bash
|
||||
# View last 100 lines
|
||||
docker compose logs backend --tail=100
|
||||
|
||||
# Follow live logs
|
||||
docker compose logs -f backend
|
||||
|
||||
# Save to file
|
||||
docker compose logs backend --tail=500 > backend_logs.txt
|
||||
```
|
||||
|
||||
**Manual/PM2:**
|
||||
```bash
|
||||
# Terminal where you ran ./nofx shows logs
|
||||
|
||||
# PM2:
|
||||
pm2 logs nofx --lines 100
|
||||
|
||||
# Save to file
|
||||
pm2 logs nofx --lines 500 > backend_logs.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Frontend Logs (Browser Console)
|
||||
|
||||
1. **Open DevTools:**
|
||||
- Press `F12` or Right-click → Inspect
|
||||
|
||||
2. **Console Tab:**
|
||||
- See JavaScript errors and warnings
|
||||
- Look for red error messages
|
||||
|
||||
3. **Network Tab:**
|
||||
- Filter by "XHR" or "Fetch"
|
||||
- Look for failed requests (red status codes)
|
||||
- Click on failed request → Preview/Response to see error details
|
||||
|
||||
4. **Capture Screenshot:**
|
||||
- Windows: `Win+Shift+S`
|
||||
- Mac: `Cmd+Shift+4`
|
||||
- Or use browser DevTools screenshot feature
|
||||
|
||||
---
|
||||
|
||||
### Decision Logs (Trading Issues)
|
||||
|
||||
```bash
|
||||
# List recent decision logs
|
||||
ls -lt decision_logs/your_trader_id/ | head -10
|
||||
|
||||
# View latest decision
|
||||
cat decision_logs/your_trader_id/$(ls -t decision_logs/your_trader_id/ | head -1) | jq .
|
||||
|
||||
# Search for specific symbol
|
||||
grep -r "BTCUSDT" decision_logs/your_trader_id/
|
||||
|
||||
# Find decisions that resulted in trades
|
||||
grep -r '"action": "open_' decision_logs/your_trader_id/
|
||||
```
|
||||
|
||||
**What to look for in decision logs:**
|
||||
- `chain_of_thought`: AI's reasoning process
|
||||
- `user_prompt`: Market data AI received
|
||||
- `decision`: Final decision (action, symbol, leverage, etc.)
|
||||
- `account_state`: Account balance, margin, positions at decision time
|
||||
- `execution_result`: Whether trade succeeded or failed
|
||||
|
||||
---
|
||||
|
||||
## 🔍 Diagnostic Commands
|
||||
|
||||
### System Health Check
|
||||
|
||||
```bash
|
||||
# Backend health
|
||||
curl http://localhost:8080/api/health
|
||||
|
||||
# List all traders
|
||||
curl http://localhost:8080/api/traders
|
||||
|
||||
# Check specific trader status
|
||||
curl http://localhost:8080/api/status?trader_id=your_trader_id
|
||||
|
||||
# Get account info
|
||||
curl http://localhost:8080/api/account?trader_id=your_trader_id
|
||||
```
|
||||
|
||||
### Docker Status
|
||||
|
||||
```bash
|
||||
# Check all containers
|
||||
docker compose ps
|
||||
|
||||
# Check resource usage
|
||||
docker stats
|
||||
|
||||
# Restart specific service
|
||||
docker compose restart backend
|
||||
docker compose restart frontend
|
||||
```
|
||||
|
||||
### Database Queries
|
||||
|
||||
```bash
|
||||
# Check traders in database
|
||||
sqlite3 config.db "SELECT id, name, ai_model_id, exchange_id, is_running FROM traders;"
|
||||
|
||||
# Check AI models
|
||||
sqlite3 config.db "SELECT id, name, model_type, enabled FROM ai_models;"
|
||||
|
||||
# Check system config
|
||||
sqlite3 config.db "SELECT key, value FROM system_config;"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 Still Having Issues?
|
||||
|
||||
If you've tried all the above and still have problems:
|
||||
|
||||
1. **Gather Information:**
|
||||
- Backend logs (last 100 lines)
|
||||
- Frontend console screenshot
|
||||
- Decision logs (if trading issue)
|
||||
- Your environment details
|
||||
|
||||
2. **Submit Bug Report:**
|
||||
- Use the [Bug Report Template](../../.github/ISSUE_TEMPLATE/bug_report.md)
|
||||
- Include all logs and screenshots
|
||||
- Describe what you've already tried
|
||||
|
||||
3. **Join Community:**
|
||||
- [Telegram Developer Community](https://t.me/nofx_dev_community)
|
||||
- [GitHub Discussions](https://github.com/tinkle-community/nofx/discussions)
|
||||
|
||||
---
|
||||
|
||||
## 🆘 Emergency: System Completely Broken
|
||||
|
||||
**Complete Reset (⚠️ Will lose trading history):**
|
||||
|
||||
```bash
|
||||
# Stop everything
|
||||
docker compose down
|
||||
|
||||
# Backup databases (just in case)
|
||||
cp config.db config.db.backup
|
||||
cp trading.db trading.db.backup
|
||||
|
||||
# Remove databases (fresh start)
|
||||
rm config.db trading.db
|
||||
|
||||
# Restart
|
||||
docker compose up -d --build
|
||||
|
||||
# Reconfigure through web UI
|
||||
open http://localhost:3000
|
||||
```
|
||||
|
||||
**Partial Reset (Keep configuration, clear logs):**
|
||||
|
||||
```bash
|
||||
# Clear decision logs
|
||||
rm -rf decision_logs/*
|
||||
|
||||
# Clear Docker cache and rebuild
|
||||
docker compose down
|
||||
docker compose build --no-cache
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
- **[FAQ](faq.en.md)** - Frequently Asked Questions
|
||||
- **[Getting Started](../getting-started/README.md)** - Setup guide
|
||||
- **[Architecture Docs](../architecture/README.md)** - How the system works
|
||||
- **[CLAUDE.md](../../CLAUDE.md)** - Developer documentation
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-11-02
|
||||
@@ -0,0 +1,612 @@
|
||||
# 🔧 故障排查指南
|
||||
|
||||
本指南帮助您在提交 bug 报告前自行诊断和修复常见问题。
|
||||
|
||||
---
|
||||
|
||||
## 📋 快速诊断清单
|
||||
|
||||
提交 bug 前，请检查：
|
||||
|
||||
1. ✅ **后端正在运行**: `docker compose ps` 或 `ps aux | grep nofx`
|
||||
2. ✅ **前端可访问**: 在浏览器打开 http://localhost:3000
|
||||
3. ✅ **API 正常响应**: `curl http://localhost:8080/api/health`
|
||||
4. ✅ **检查日志中的错误**: 参见下方 [如何捕获日志](#如何捕获日志)
|
||||
|
||||
---
|
||||
|
||||
## 🐛 常见问题与解决方案
|
||||
|
||||
### 1. 交易问题
|
||||
|
||||
#### ❌ 只开空单，不开多单 (Issue #202)
|
||||
|
||||
**症状:** AI 只开空仓，从不开多仓，即使市场看涨。
|
||||
|
||||
**根本原因:** 币安账户处于**单向持仓模式**而非**双向持仓模式**。
|
||||
|
||||
**解决方案:**
|
||||
1. 登录 [币安合约交易](https://www.binance.com/zh-CN/futures/BTCUSDT)
|
||||
2. 点击右上角 **⚙️ 偏好设置**
|
||||
3. 选择 **持仓模式**
|
||||
4. 切换为 **双向持仓** (Hedge Mode)
|
||||
5. ⚠️ **重要:** 切换前必须先平掉所有持仓
|
||||
|
||||
**为什么会这样:**
|
||||
- 代码使用 `PositionSide(LONG)` 和 `PositionSide(SHORT)` 参数
|
||||
- 这些参数只在双向持仓模式下有效
|
||||
- 在单向持仓模式下，订单会失败或只有一个方向有效
|
||||
|
||||
**关于子账户:**
|
||||
- 部分币安子账户可能没有权限更改持仓模式
|
||||
- 使用主账户或联系币安客服开通此权限
|
||||
|
||||
---
|
||||
|
||||
#### ❌ 订单错误: `code=-4061` 持仓方向不匹配
|
||||
|
||||
**错误信息:** `Order's position side does not match user's setting`
|
||||
|
||||
**解决方案:** 同上 - 切换到双向持仓模式。
|
||||
|
||||
---
|
||||
|
||||
#### ❌ 杠杆错误: `子账户限制最高5倍杠杆`
|
||||
|
||||
**症状:** 尝试使用 >5倍杠杆时订单失败。
|
||||
|
||||
**解决方案:**
|
||||
1. 打开 Web 界面 → 交易员设置
|
||||
2. 将杠杆设置为 5倍或更低:
|
||||
```json
|
||||
{
|
||||
"btc_eth_leverage": 5,
|
||||
"altcoin_leverage": 5
|
||||
}
|
||||
```
|
||||
3. 或使用主账户（支持最高 50倍 BTC/ETH，20倍山寨币）
|
||||
|
||||
---
|
||||
|
||||
#### ❌ 持仓无法执行
|
||||
|
||||
**检查以下内容:**
|
||||
1. **API 权限**:
|
||||
- 进入币安 → API 管理
|
||||
- 确认"启用合约"已勾选
|
||||
- 检查 IP 白名单（如果启用）
|
||||
|
||||
2. **账户余额**:
|
||||
- 确保合约钱包中有足够的 USDT
|
||||
- 检查保证金使用率未达到 100%
|
||||
|
||||
3. **交易对状态**:
|
||||
- 确认交易对在交易所处于活跃状态
|
||||
- 检查交易对是否处于维护模式
|
||||
|
||||
4. **决策日志**:
|
||||
```bash
|
||||
# 检查最新决策
|
||||
ls -lt decision_logs/your_trader_id/ | head -5
|
||||
cat decision_logs/your_trader_id/latest_file.json
|
||||
```
|
||||
- 查看 AI 决策：是"wait"、"hold"还是实际交易？
|
||||
- 检查 position_size_usd 是否在限制范围内
|
||||
|
||||
---
|
||||
|
||||
### 2. AI 决策问题
|
||||
|
||||
#### ❌ AI 总是说"等待"/"持有"
|
||||
|
||||
**可能原因:**
|
||||
1. **市场情况**: AI 可能确实没看到好的机会
|
||||
2. **风险限制**: 账户净值太低、保证金使用率太高
|
||||
3. **历史表现**: AI 在亏损后变得谨慎
|
||||
|
||||
**如何检查:**
|
||||
```bash
|
||||
# 查看最新决策推理
|
||||
cat decision_logs/your_trader_id/$(ls -t decision_logs/your_trader_id/ | head -1)
|
||||
```
|
||||
|
||||
查看 AI 的思维链（Chain-of-Thought）推理部分。
|
||||
|
||||
**解决方案:**
|
||||
- 等待更好的市场条件
|
||||
- 检查候选币种是否流动性都太低
|
||||
- 确认 `use_default_coins: true` 或币种池 API 正常工作
|
||||
|
||||
---
|
||||
|
||||
#### ❌ AI 做出错误决策
|
||||
|
||||
**请记住:** AI 交易是实验性的，不保证盈利。
|
||||
|
||||
**需要检查的事项:**
|
||||
1. **决策间隔**: 是否太短？（推荐: 3-5分钟）
|
||||
2. **杠杆设置**: 是否过于激进？
|
||||
3. **历史反馈**: 查看表现日志，看 AI 是否在学习
|
||||
4. **市场波动**: 高波动 = 更高风险
|
||||
|
||||
**调整建议:**
|
||||
- 降低杠杆以实现更保守的交易
|
||||
- 增加决策间隔以减少过度交易
|
||||
- 使用较小的初始余额进行测试
|
||||
|
||||
---
|
||||
|
||||
### 3. 连接和 API 问题
|
||||
|
||||
#### ❌ Docker 镜像下载失败 (中国大陆)
|
||||
|
||||
**错误:** `ERROR [internal] load metadata for docker.io/library/...`
|
||||
|
||||
**症状:**
|
||||
- `docker compose build` 或 `docker compose up` 卡住
|
||||
- 超时错误: `timeout`、`connection refused`
|
||||
- 无法从 Docker Hub 拉取镜像
|
||||
|
||||
**根本原因:**
|
||||
中国大陆访问 Docker Hub 受限或速度极慢。
|
||||
|
||||
**解决方案 1: 配置 Docker 镜像加速器（推荐）**
|
||||
|
||||
1. **编辑 Docker 配置文件:**
|
||||
```bash
|
||||
# Linux
|
||||
sudo nano /etc/docker/daemon.json
|
||||
|
||||
# macOS (Docker Desktop)
|
||||
# Settings → Docker Engine
|
||||
```
|
||||
|
||||
2. **添加国内镜像源:**
|
||||
```json
|
||||
{
|
||||
"registry-mirrors": [
|
||||
"https://docker.m.daocloud.io",
|
||||
"https://docker.1panel.live",
|
||||
"https://hub.rat.dev",
|
||||
"https://dockerpull.com",
|
||||
"https://dockerhub.icu"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
3. **重启 Docker:**
|
||||
```bash
|
||||
# Linux
|
||||
sudo systemctl restart docker
|
||||
|
||||
# macOS/Windows
|
||||
# 重启 Docker Desktop
|
||||
```
|
||||
|
||||
4. **重新构建:**
|
||||
```bash
|
||||
docker compose build --no-cache
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
**解决方案 2: 使用 VPN**
|
||||
|
||||
1. 连接 VPN（推荐台湾节点）
|
||||
2. 确保使用**全局模式**而非规则模式
|
||||
3. 重新运行 `docker compose build`
|
||||
|
||||
**解决方案 3: 离线下载镜像**
|
||||
|
||||
如果上述方法都不行:
|
||||
|
||||
1. **使用镜像代理网站下载:**
|
||||
- https://proxy.vvvv.ee/images.html （可离线下载）
|
||||
- https://github.com/dongyubin/DockerHub （镜像加速列表）
|
||||
|
||||
2. **手动导入镜像:**
|
||||
```bash
|
||||
# 下载镜像文件后
|
||||
docker load -i golang-1.25-alpine.tar
|
||||
docker load -i node-20-alpine.tar
|
||||
docker load -i nginx-alpine.tar
|
||||
```
|
||||
|
||||
3. **验证镜像已加载:**
|
||||
```bash
|
||||
docker images | grep golang
|
||||
docker images | grep node
|
||||
docker images | grep nginx
|
||||
```
|
||||
|
||||
**验证镜像加速器是否生效:**
|
||||
```bash
|
||||
# 查看 Docker 信息
|
||||
docker info | grep -A 10 "Registry Mirrors"
|
||||
|
||||
# 应该显示你配置的镜像源
|
||||
```
|
||||
|
||||
**相关 Issue:** [#168](https://github.com/tinkle-community/nofx/issues/168)
|
||||
|
||||
---
|
||||
|
||||
#### ❌ 后端无法启动
|
||||
|
||||
**错误:** `port 8080 already in use`
|
||||
|
||||
**解决方案:**
|
||||
```bash
|
||||
# 查找占用端口的进程
|
||||
lsof -i :8080
|
||||
# 或
|
||||
netstat -tulpn | grep 8080
|
||||
|
||||
# 杀死进程或在 .env 中更改端口
|
||||
NOFX_BACKEND_PORT=8081
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### ❌ 前端无法连接后端
|
||||
|
||||
**症状:**
|
||||
- UI 显示"加载中..."一直不结束
|
||||
- 浏览器控制台显示 404 或网络错误
|
||||
|
||||
**解决方案:**
|
||||
1. **检查后端是否运行:**
|
||||
```bash
|
||||
docker compose ps # 应显示 backend 为 "Up"
|
||||
# 或
|
||||
curl http://localhost:8080/api/health # 应返回 {"status":"ok"}
|
||||
```
|
||||
|
||||
2. **检查端口配置:**
|
||||
- 后端默认: 8080
|
||||
- 前端默认: 3000
|
||||
- 确认 `.env` 设置匹配
|
||||
|
||||
3. **CORS 问题:**
|
||||
- 如果前端和后端运行在不同端口/域名
|
||||
- 检查浏览器控制台的 CORS 错误
|
||||
- 后端应允许前端来源
|
||||
|
||||
---
|
||||
|
||||
#### ❌ 交易所 API 错误
|
||||
|
||||
**常见错误:**
|
||||
- `code=-1021, msg=Timestamp for this request is outside of the recvWindow`
|
||||
- `invalid signature`
|
||||
- `timestamp` 错误
|
||||
|
||||
**根本原因:**
|
||||
系统时间不准确，与币安服务器时间相差超过允许范围（通常是 5 秒）。
|
||||
|
||||
**解决方案 1: 同步系统时间（推荐）**
|
||||
|
||||
```bash
|
||||
# 方法 1: 使用 ntpdate (最常用)
|
||||
sudo ntpdate pool.ntp.org
|
||||
|
||||
# 方法 2: 使用其他 NTP 服务器
|
||||
sudo ntpdate -s time.nist.gov
|
||||
sudo ntpdate -s ntp.aliyun.com # 阿里云 NTP (中国大陆快)
|
||||
|
||||
# 方法 3: 启用自动时间同步 (Linux)
|
||||
sudo timedatectl set-ntp true
|
||||
|
||||
# 验证时间是否正确
|
||||
date
|
||||
# 应该显示正确的当前时间
|
||||
```
|
||||
|
||||
**Docker 环境特别注意:**
|
||||
|
||||
如果使用 Docker，容器时间可能与宿主机不同步：
|
||||
|
||||
```bash
|
||||
# 检查容器时间
|
||||
docker exec nofx-backend date
|
||||
|
||||
# 如果时间错误，重启 Docker 服务
|
||||
sudo systemctl restart docker
|
||||
|
||||
# 或在 docker-compose.yml 中添加时区设置
|
||||
environment:
|
||||
- TZ=Asia/Shanghai # 或您的时区
|
||||
```
|
||||
|
||||
**解决方案 2: 验证 API 密钥**
|
||||
|
||||
如果时间同步后仍有错误：
|
||||
|
||||
1. **检查 API 密钥:**
|
||||
- 未过期
|
||||
- 有正确权限（已启用合约）
|
||||
- IP 白名单包含您的服务器 IP
|
||||
|
||||
2. **重新生成 API 密钥:**
|
||||
- 登录币安 → API 管理
|
||||
- 删除旧密钥
|
||||
- 创建新密钥
|
||||
- 更新 NOFX 配置
|
||||
|
||||
**解决方案 3: 检查速率限制**
|
||||
|
||||
币安有严格的 API 速率限制：
|
||||
|
||||
- **每分钟请求数限制**
|
||||
- 减少交易员数量
|
||||
- 增加决策间隔时间（例如从 1 分钟改为 3-5 分钟）
|
||||
|
||||
**相关 Issue:** [#60](https://github.com/tinkle-community/nofx/issues/60)
|
||||
|
||||
---
|
||||
|
||||
### 4. 前端问题
|
||||
|
||||
#### ❌ UI 不更新 / 显示旧数据
|
||||
|
||||
**解决方案:**
|
||||
1. **强制刷新:**
|
||||
- Chrome/Firefox: `Ctrl+Shift+R` (Windows/Linux) 或 `Cmd+Shift+R` (Mac)
|
||||
- Safari: `Cmd+Option+R`
|
||||
|
||||
2. **清除浏览器缓存:**
|
||||
- 设置 → 隐私 → 清除浏览数据
|
||||
- 或在无痕/隐私模式下打开
|
||||
|
||||
3. **检查 SWR 轮询:**
|
||||
- 前端使用 5-10秒间隔的 SWR
|
||||
- 数据应自动刷新
|
||||
- 检查浏览器控制台是否有 fetch 错误
|
||||
|
||||
---
|
||||
|
||||
#### ❌ 图表不渲染
|
||||
|
||||
**可能原因:**
|
||||
1. 暂无历史数据（系统刚启动）
|
||||
2. 控制台中有 JavaScript 错误
|
||||
3. 浏览器兼容性问题
|
||||
|
||||
**解决方案:**
|
||||
- 等待 5-10 分钟让数据积累
|
||||
- 检查浏览器控制台（F12）是否有错误
|
||||
- 尝试不同浏览器（推荐 Chrome）
|
||||
- 确保后端 API 端点正在返回数据
|
||||
|
||||
---
|
||||
|
||||
### 5. 数据库问题
|
||||
|
||||
#### ❌ `database is locked` 错误
|
||||
|
||||
**原因:** SQLite 数据库被多个进程访问。
|
||||
|
||||
**解决方案:**
|
||||
```bash
|
||||
# 停止所有 NOFX 进程
|
||||
docker compose down
|
||||
# 或
|
||||
pkill nofx
|
||||
|
||||
# 重启
|
||||
docker compose up -d
|
||||
# 或
|
||||
./nofx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### ❌ 交易员配置无法保存
|
||||
|
||||
**检查:**
|
||||
1. **权限:**
|
||||
```bash
|
||||
ls -l config.db trading.db
|
||||
# 应该对当前用户可写
|
||||
```
|
||||
|
||||
2. **磁盘空间:**
|
||||
```bash
|
||||
df -h # 确保磁盘未满
|
||||
```
|
||||
|
||||
3. **数据库完整性:**
|
||||
```bash
|
||||
sqlite3 config.db "PRAGMA integrity_check;"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 如何捕获日志
|
||||
|
||||
### 后端日志
|
||||
|
||||
**Docker:**
|
||||
```bash
|
||||
# 查看最后 100 行
|
||||
docker compose logs backend --tail=100
|
||||
|
||||
# 实时跟踪日志
|
||||
docker compose logs -f backend
|
||||
|
||||
# 保存到文件
|
||||
docker compose logs backend --tail=500 > backend_logs.txt
|
||||
```
|
||||
|
||||
**手动/PM2:**
|
||||
```bash
|
||||
# 运行 ./nofx 的终端会显示日志
|
||||
|
||||
# PM2:
|
||||
pm2 logs nofx --lines 100
|
||||
|
||||
# 保存到文件
|
||||
pm2 logs nofx --lines 500 > backend_logs.txt
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 前端日志（浏览器控制台）
|
||||
|
||||
1. **打开开发者工具:**
|
||||
- 按 `F12` 或右键 → 检查
|
||||
|
||||
2. **Console（控制台）标签:**
|
||||
- 查看 JavaScript 错误和警告
|
||||
- 寻找红色错误消息
|
||||
|
||||
3. **Network（网络）标签:**
|
||||
- 按"XHR"或"Fetch"筛选
|
||||
- 查找失败的请求（红色状态码）
|
||||
- 点击失败的请求 → Preview/Response 查看错误详情
|
||||
|
||||
4. **捕获截图:**
|
||||
- Windows: `Win+Shift+S`
|
||||
- Mac: `Cmd+Shift+4`
|
||||
- 或使用浏览器开发者工具截图功能
|
||||
|
||||
---
|
||||
|
||||
### 决策日志（交易问题）
|
||||
|
||||
```bash
|
||||
# 列出最近的决策日志
|
||||
ls -lt decision_logs/your_trader_id/ | head -10
|
||||
|
||||
# 查看最新决策
|
||||
cat decision_logs/your_trader_id/$(ls -t decision_logs/your_trader_id/ | head -1) | jq .
|
||||
|
||||
# 搜索特定交易对
|
||||
grep -r "BTCUSDT" decision_logs/your_trader_id/
|
||||
|
||||
# 查找执行交易的决策
|
||||
grep -r '"action": "open_' decision_logs/your_trader_id/
|
||||
```
|
||||
|
||||
**决策日志中要查看的内容:**
|
||||
- `chain_of_thought`: AI 的推理过程
|
||||
- `user_prompt`: AI 收到的市场数据
|
||||
- `decision`: 最终决策（动作、交易对、杠杆等）
|
||||
- `account_state`: 决策时的账户余额、保证金、持仓
|
||||
- `execution_result`: 交易是否成功
|
||||
|
||||
---
|
||||
|
||||
## 🔍 诊断命令
|
||||
|
||||
### 系统健康检查
|
||||
|
||||
```bash
|
||||
# 后端健康状态
|
||||
curl http://localhost:8080/api/health
|
||||
|
||||
# 列出所有交易员
|
||||
curl http://localhost:8080/api/traders
|
||||
|
||||
# 检查特定交易员状态
|
||||
curl http://localhost:8080/api/status?trader_id=your_trader_id
|
||||
|
||||
# 获取账户信息
|
||||
curl http://localhost:8080/api/account?trader_id=your_trader_id
|
||||
```
|
||||
|
||||
### Docker 状态
|
||||
|
||||
```bash
|
||||
# 检查所有容器
|
||||
docker compose ps
|
||||
|
||||
# 检查资源使用
|
||||
docker stats
|
||||
|
||||
# 重启特定服务
|
||||
docker compose restart backend
|
||||
docker compose restart frontend
|
||||
```
|
||||
|
||||
### 数据库查询
|
||||
|
||||
```bash
|
||||
# 检查数据库中的交易员
|
||||
sqlite3 config.db "SELECT id, name, ai_model_id, exchange_id, is_running FROM traders;"
|
||||
|
||||
# 检查 AI 模型
|
||||
sqlite3 config.db "SELECT id, name, model_type, enabled FROM ai_models;"
|
||||
|
||||
# 检查系统配置
|
||||
sqlite3 config.db "SELECT key, value FROM system_config;"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 仍有问题？
|
||||
|
||||
如果尝试了上述所有方法仍有问题:
|
||||
|
||||
1. **收集信息:**
|
||||
- 后端日志（最后 100 行）
|
||||
- 前端控制台截图
|
||||
- 决策日志（如果是交易问题）
|
||||
- 您的环境详情
|
||||
|
||||
2. **提交 Bug 报告:**
|
||||
- 使用 [Bug 报告模板](../../.github/ISSUE_TEMPLATE/bug_report.md)
|
||||
- 包含所有日志和截图
|
||||
- 描述您已尝试的方法
|
||||
|
||||
3. **加入社区:**
|
||||
- [Telegram 开发者社区](https://t.me/nofx_dev_community)
|
||||
- [GitHub Discussions](https://github.com/tinkle-community/nofx/discussions)
|
||||
|
||||
---
|
||||
|
||||
## 🆘 紧急情况：系统完全损坏
|
||||
|
||||
**完全重置 (⚠️ 将丢失交易历史):**
|
||||
|
||||
```bash
|
||||
# 停止所有服务
|
||||
docker compose down
|
||||
|
||||
# 备份数据库（以防万一）
|
||||
cp config.db config.db.backup
|
||||
cp trading.db trading.db.backup
|
||||
|
||||
# 删除数据库（全新开始）
|
||||
rm config.db trading.db
|
||||
|
||||
# 重启
|
||||
docker compose up -d --build
|
||||
|
||||
# 通过 Web UI 重新配置
|
||||
open http://localhost:3000
|
||||
```
|
||||
|
||||
**部分重置（保留配置，清除日志）:**
|
||||
|
||||
```bash
|
||||
# 清除决策日志
|
||||
rm -rf decision_logs/*
|
||||
|
||||
# 清除 Docker 缓存并重建
|
||||
docker compose down
|
||||
docker compose build --no-cache
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📚 其他资源
|
||||
|
||||
- **[FAQ](faq.zh-CN.md)** - 常见问题
|
||||
- **[快速开始](../getting-started/README.zh-CN.md)** - 安装指南
|
||||
- **[架构文档](../architecture/README.zh-CN.md)** - 系统工作原理
|
||||
- **[CLAUDE.md](../../CLAUDE.md)** - 开发者文档
|
||||
|
||||
---
|
||||
|
||||
**最后更新:** 2025-11-02
|
||||
+202
-21
@@ -1,25 +1,206 @@
|
||||
# Frequently Asked Questions
|
||||
# Frequently Asked Questions (FAQ)
|
||||
|
||||
## 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.
|
||||
Quick answers to common questions. For detailed troubleshooting, see [Troubleshooting Guide](TROUBLESHOOTING.md).
|
||||
|
||||
---
|
||||
|
||||
For more issues, check [GitHub Issues](https://github.com/tinkle-community/nofx/issues)
|
||||
## General Questions
|
||||
|
||||
### What is NOFX?
|
||||
NOFX is an AI-powered cryptocurrency trading bot that uses large language models (LLMs) to make trading decisions on futures markets.
|
||||
|
||||
### Which exchanges are supported?
|
||||
- ✅ Binance Futures
|
||||
- ✅ Hyperliquid
|
||||
- 🚧 More exchanges coming soon
|
||||
|
||||
### Is NOFX profitable?
|
||||
AI trading is **experimental** and **not guaranteed** to be profitable. Always start with small amounts and never invest more than you can afford to lose.
|
||||
|
||||
### Can I run multiple traders simultaneously?
|
||||
Yes! NOFX supports running multiple traders with different configurations, AI models, and trading strategies.
|
||||
|
||||
---
|
||||
|
||||
## Setup & Configuration
|
||||
|
||||
### What are the system requirements?
|
||||
- **OS**: Linux, macOS, or Windows (Docker recommended)
|
||||
- **RAM**: 2GB minimum, 4GB recommended
|
||||
- **Disk**: 1GB for application + logs
|
||||
- **Network**: Stable internet connection
|
||||
|
||||
### Do I need coding experience?
|
||||
No! NOFX has a web UI for all configuration. However, basic command line knowledge helps with setup and troubleshooting.
|
||||
|
||||
### How do I get API keys?
|
||||
1. **Binance**: Account → API Management → Create API → Enable Futures
|
||||
2. **Hyperliquid**: Visit [Hyperliquid App](https://app.hyperliquid.xyz/) → API Settings
|
||||
|
||||
### Should I use a subaccount?
|
||||
**Recommended**: Yes, use a subaccount dedicated to NOFX for better risk isolation. However, note that some subaccounts have restrictions (e.g., 5x max leverage on Binance).
|
||||
|
||||
---
|
||||
|
||||
## Trading Questions
|
||||
|
||||
### Why isn't my trader making any trades?
|
||||
Common reasons:
|
||||
- AI decided to "wait" due to market conditions
|
||||
- Insufficient balance or margin
|
||||
- Position limits reached (default: max 3 positions)
|
||||
- See detailed diagnostics in [Troubleshooting Guide](TROUBLESHOOTING.md#-ai-always-says-wait--hold)
|
||||
|
||||
### How often does the AI make decisions?
|
||||
Configurable! Default is every **3-5 minutes**. Too frequent = overtrading, too slow = missed opportunities.
|
||||
|
||||
### Can I customize the trading strategy?
|
||||
Yes! You can:
|
||||
- Adjust leverage settings
|
||||
- Modify coin selection pool
|
||||
- Change decision intervals
|
||||
- Customize system prompts (advanced)
|
||||
|
||||
### What's the maximum number of concurrent positions?
|
||||
Default: **3 positions**. This is a soft limit defined in the AI prompt, not hard-coded. See `decision/engine.go:266`.
|
||||
|
||||
---
|
||||
|
||||
## Technical Issues
|
||||
|
||||
### Binance Position Mode Error (code=-4061)
|
||||
|
||||
**Error**: `Order's position side does not match user's setting`
|
||||
|
||||
**Solution**: Switch to **Hedge Mode** (双向持仓)
|
||||
1. Login to [Binance Futures](https://www.binance.com/en/futures/BTCUSDT)
|
||||
2. Click **⚙️ Preferences** (top right)
|
||||
3. Select **Position Mode** → **Hedge Mode**
|
||||
4. ⚠️ Close all positions first
|
||||
|
||||
**Why**: NOFX uses `PositionSide(LONG/SHORT)` which requires Hedge Mode.
|
||||
|
||||
See [Issue #202](https://github.com/tinkle-community/nofx/issues/202) and [Troubleshooting Guide](TROUBLESHOOTING.md#-only-opening-short-positions-issue-202).
|
||||
|
||||
---
|
||||
|
||||
### Backend won't start / Port already in use
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check what's using port 8080
|
||||
lsof -i :8080
|
||||
|
||||
# Change port in .env
|
||||
NOFX_BACKEND_PORT=8081
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Frontend shows "Loading..." forever
|
||||
|
||||
**Quick Check**:
|
||||
```bash
|
||||
# Is backend running?
|
||||
curl http://localhost:8080/api/health
|
||||
|
||||
# Should return: {"status":"ok"}
|
||||
```
|
||||
|
||||
If not, check [Troubleshooting Guide](TROUBLESHOOTING.md#-frontend-cant-connect-to-backend).
|
||||
|
||||
---
|
||||
|
||||
### Database locked error
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Stop all NOFX processes
|
||||
docker compose down
|
||||
# OR
|
||||
pkill nofx
|
||||
|
||||
# Restart
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AI & Model Questions
|
||||
|
||||
### Which AI models are supported?
|
||||
- **DeepSeek** (recommended for cost/performance)
|
||||
- **Qwen** (Alibaba Cloud Tongyi Qianwen)
|
||||
- **Custom OpenAI-compatible APIs** (can be used for OpenAI, Claude via proxy, or other providers)
|
||||
|
||||
### How much do API calls cost?
|
||||
Depends on your model and decision frequency:
|
||||
- **DeepSeek**: ~$0.10-0.50 per day (1 trader, 5min intervals)
|
||||
- **Qwen**: ~$0.20-0.80 per day
|
||||
- **Custom API** (e.g., OpenAI GPT-4): ~$2-5 per day
|
||||
|
||||
*Estimates based on typical usage. Actual costs vary by provider and usage.*
|
||||
|
||||
### Can I use multiple AI models?
|
||||
Yes! Each trader can use a different AI model. You can even A/B test different models.
|
||||
|
||||
### Does the AI learn from its mistakes?
|
||||
Yes, to some extent. NOFX provides historical performance feedback in each decision prompt, allowing the AI to adjust its strategy.
|
||||
|
||||
---
|
||||
|
||||
## Data & Privacy
|
||||
|
||||
### Where is my data stored?
|
||||
All data is stored **locally** on your machine in SQLite databases:
|
||||
- `config.db` - Trader configurations
|
||||
- `trading.db` - Trade history
|
||||
- `decision_logs/` - AI decision records
|
||||
|
||||
### Is my API key secure?
|
||||
API keys are stored in local databases. Never share your databases or `.env` files. We recommend using API keys with IP whitelist restrictions.
|
||||
|
||||
### Can I export my trading history?
|
||||
Yes! Trading data is in SQLite format. You can query it directly:
|
||||
```bash
|
||||
sqlite3 trading.db "SELECT * FROM trades;"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Where can I find detailed troubleshooting?
|
||||
See the comprehensive [Troubleshooting Guide](TROUBLESHOOTING.md) for:
|
||||
- Step-by-step diagnostics
|
||||
- Log collection methods
|
||||
- Common error solutions
|
||||
- Emergency reset procedures
|
||||
|
||||
### How do I report a bug?
|
||||
1. Check [Troubleshooting Guide](TROUBLESHOOTING.md) first
|
||||
2. Search [existing issues](https://github.com/tinkle-community/nofx/issues)
|
||||
3. If not found, use our [Bug Report Template](../../.github/ISSUE_TEMPLATE/bug_report.md)
|
||||
|
||||
### Where can I get help?
|
||||
- [GitHub Discussions](https://github.com/tinkle-community/nofx/discussions)
|
||||
- [Telegram Community](https://t.me/nofx_dev_community)
|
||||
- [GitHub Issues](https://github.com/tinkle-community/nofx/issues)
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
### Can I contribute to NOFX?
|
||||
Yes! We welcome contributions:
|
||||
- Bug fixes and features
|
||||
- Documentation improvements
|
||||
- Translations
|
||||
- See [Contributing Guide](../CONTRIBUTING.md)
|
||||
|
||||
### How do I suggest new features?
|
||||
Open a [Feature Request](https://github.com/tinkle-community/nofx/issues/new/choose) with your idea!
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-11-02
|
||||
|
||||
+202
-21
@@ -1,25 +1,206 @@
|
||||
# 常见问题
|
||||
# 常见问题（FAQ）
|
||||
|
||||
## 币安持仓模式错误 (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. 确认切换
|
||||
|
||||
**注意**：切换前必须先平掉所有持仓。
|
||||
快速解答常见问题。详细故障排查请参考[故障排查指南](TROUBLESHOOTING.zh-CN.md)。
|
||||
|
||||
---
|
||||
|
||||
更多问题请查看 [GitHub Issues](https://github.com/tinkle-community/nofx/issues)
|
||||
## 基础问题
|
||||
|
||||
### NOFX 是什么？
|
||||
NOFX 是一个 AI 驱动的加密货币交易机器人，使用大语言模型（LLM）在期货市场进行交易决策。
|
||||
|
||||
### 支持哪些交易所？
|
||||
- ✅ 币安合约（Binance Futures）
|
||||
- ✅ Hyperliquid
|
||||
- 🚧 更多交易所开发中
|
||||
|
||||
### NOFX 能盈利吗？
|
||||
AI 交易是**实验性**的，**不保证盈利**。请始终用小额资金测试，不要投入超过您承受能力的资金。
|
||||
|
||||
### 可以同时运行多个交易员吗？
|
||||
可以！NOFX 支持运行多个交易员，每个可配置不同的 AI 模型和交易策略。
|
||||
|
||||
---
|
||||
|
||||
## 安装与配置
|
||||
|
||||
### 系统要求是什么？
|
||||
- **操作系统**：Linux、macOS 或 Windows（推荐 Docker）
|
||||
- **内存**：最低 2GB，推荐 4GB
|
||||
- **硬盘**：应用 + 日志需要 1GB
|
||||
- **网络**：稳定的互联网连接
|
||||
|
||||
### 需要编程经验吗？
|
||||
不需要！NOFX 有 Web 界面进行所有配置。但基础的命令行知识有助于安装和故障排查。
|
||||
|
||||
### 如何获取 API 密钥？
|
||||
1. **币安**：账户 → API 管理 → 创建 API → 启用合约
|
||||
2. **Hyperliquid**：访问 [Hyperliquid App](https://app.hyperliquid.xyz/) → API 设置
|
||||
|
||||
### 应该使用子账户吗？
|
||||
**推荐**：是的，使用专门的子账户运行 NOFX 可以更好地隔离风险。但请注意，某些子账户有限制（例如币安子账户最高 5 倍杠杆）。
|
||||
|
||||
---
|
||||
|
||||
## 交易问题
|
||||
|
||||
### 为什么我的交易员不开仓？
|
||||
常见原因：
|
||||
- AI 根据市场情况决定"等待"
|
||||
- 余额或保证金不足
|
||||
- 达到持仓上限（默认最多 3 个仓位）
|
||||
- 详细诊断请查看[故障排查指南](TROUBLESHOOTING.zh-CN.md#-ai-总是说等待持有)
|
||||
|
||||
### AI 多久做一次决策？
|
||||
可配置！默认是每 **3-5 分钟**。太频繁 = 过度交易，太慢 = 错过机会。
|
||||
|
||||
### 可以自定义交易策略吗？
|
||||
可以！您可以：
|
||||
- 调整杠杆设置
|
||||
- 修改币种选择池
|
||||
- 更改决策间隔
|
||||
- 自定义系统提示词（高级）
|
||||
|
||||
### 最多可以同时持有多少个仓位？
|
||||
默认：**3 个仓位**。这是 AI 提示词中的软限制，不是硬编码。参见 `decision/engine.go:266`。
|
||||
|
||||
---
|
||||
|
||||
## 技术问题
|
||||
|
||||
### 币安持仓模式错误 (code=-4061)
|
||||
|
||||
**错误信息**：`Order's position side does not match user's setting`
|
||||
|
||||
**解决方法**：切换为**双向持仓**模式
|
||||
1. 登录[币安合约](https://www.binance.com/zh-CN/futures/BTCUSDT)
|
||||
2. 点击右上角 **⚙️ 偏好设置**
|
||||
3. 选择 **持仓模式** → **双向持仓**
|
||||
4. ⚠️ 先平掉所有持仓
|
||||
|
||||
**原因**：NOFX 使用 `PositionSide(LONG/SHORT)`，需要双向持仓模式。
|
||||
|
||||
参见 [Issue #202](https://github.com/tinkle-community/nofx/issues/202) 和[故障排查指南](TROUBLESHOOTING.zh-CN.md#-只开空单-issue-202)。
|
||||
|
||||
---
|
||||
|
||||
### 后端无法启动 / 端口被占用
|
||||
|
||||
**解决方法**：
|
||||
```bash
|
||||
# 查看占用端口的进程
|
||||
lsof -i :8080
|
||||
|
||||
# 修改 .env 中的端口
|
||||
NOFX_BACKEND_PORT=8081
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 前端一直显示"加载中..."
|
||||
|
||||
**快速检查**：
|
||||
```bash
|
||||
# 后端是否运行？
|
||||
curl http://localhost:8080/api/health
|
||||
|
||||
# 应该返回：{"status":"ok"}
|
||||
```
|
||||
|
||||
如果不是，查看[故障排查指南](TROUBLESHOOTING.zh-CN.md#-前端无法连接后端)。
|
||||
|
||||
---
|
||||
|
||||
### 数据库锁定错误
|
||||
|
||||
**解决方法**：
|
||||
```bash
|
||||
# 停止所有 NOFX 进程
|
||||
docker compose down
|
||||
# 或
|
||||
pkill nofx
|
||||
|
||||
# 重启
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## AI 与模型问题
|
||||
|
||||
### 支持哪些 AI 模型？
|
||||
- **DeepSeek**（推荐性价比）
|
||||
- **Qwen**（阿里云通义千问）
|
||||
- **自定义 OpenAI 兼容 API**（可用于 OpenAI、通过代理的 Claude 或其他提供商）
|
||||
|
||||
### API 调用成本是多少？
|
||||
取决于您的模型和决策频率：
|
||||
- **DeepSeek**：每天约 $0.10-0.50（1 个交易员，5 分钟间隔）
|
||||
- **Qwen**：每天约 $0.20-0.80
|
||||
- **自定义 API**（例如 OpenAI GPT-4）：每天约 $2-5
|
||||
|
||||
*基于典型使用的估算。实际成本因提供商和使用量而异。*
|
||||
|
||||
### 可以使用多个 AI 模型吗？
|
||||
可以！每个交易员可以使用不同的 AI 模型。您甚至可以 A/B 测试不同模型。
|
||||
|
||||
### AI 会从错误中学习吗？
|
||||
会的，在一定程度上。NOFX 在每次决策提示中提供历史表现反馈，允许 AI 调整策略。
|
||||
|
||||
---
|
||||
|
||||
## 数据与隐私
|
||||
|
||||
### 我的数据存储在哪里？
|
||||
所有数据都**本地存储**在您的机器上，使用 SQLite 数据库：
|
||||
- `config.db` - 交易员配置
|
||||
- `trading.db` - 交易历史
|
||||
- `decision_logs/` - AI 决策记录
|
||||
|
||||
### API 密钥安全吗？
|
||||
API 密钥存储在本地数据库中。永远不要分享您的数据库或 `.env` 文件。我们建议使用带 IP 白名单限制的 API 密钥。
|
||||
|
||||
### 可以导出交易历史吗？
|
||||
可以！交易数据是 SQLite 格式。您可以直接查询：
|
||||
```bash
|
||||
sqlite3 trading.db "SELECT * FROM trades;"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 在哪里可以找到详细的故障排查？
|
||||
查看全面的[故障排查指南](TROUBLESHOOTING.zh-CN.md)，包含：
|
||||
- 分步诊断方法
|
||||
- 日志收集方法
|
||||
- 常见错误解决方案
|
||||
- 紧急重置步骤
|
||||
|
||||
### 如何报告 Bug？
|
||||
1. 先查看[故障排查指南](TROUBLESHOOTING.zh-CN.md)
|
||||
2. 搜索[现有 Issues](https://github.com/tinkle-community/nofx/issues)
|
||||
3. 如果没找到，使用我们的 [Bug 报告模板](../../.github/ISSUE_TEMPLATE/bug_report.md)
|
||||
|
||||
### 在哪里可以获得帮助？
|
||||
- [GitHub Discussions](https://github.com/tinkle-community/nofx/discussions)
|
||||
- [Telegram 社区](https://t.me/nofx_dev_community)
|
||||
- [GitHub Issues](https://github.com/tinkle-community/nofx/issues)
|
||||
|
||||
---
|
||||
|
||||
## 贡献
|
||||
|
||||
### 可以为 NOFX 贡献代码吗？
|
||||
可以！我们欢迎贡献：
|
||||
- Bug 修复和新功能
|
||||
- 文档改进
|
||||
- 翻译
|
||||
- 查看[贡献指南](../CONTRIBUTING.md)
|
||||
|
||||
### 如何建议新功能？
|
||||
提交 [Feature Request](https://github.com/tinkle-community/nofx/issues/new/choose) 说明您的想法！
|
||||
|
||||
---
|
||||
|
||||
**最后更新：** 2025-11-02
|
||||
|
||||
Reference in New Issue
Block a user