mirror of
https://github.com/NoFxAiOS/nofx.git
synced 2026-07-05 12:00:59 +08:00
Merge branch 'NoFxAiOS:dev' into dev-fix
This commit is contained in:
darkedge
152
.github/ISSUE_TEMPLATE/bug_report.md
vendored
152
.github/ISSUE_TEMPLATE/bug_report.md
vendored
@@ -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`
|
||||
|
||||
322
.github/PR_TITLE_GUIDE.md
vendored
Normal file
322
.github/PR_TITLE_GUIDE.md
vendored
Normal file
@@ -0,0 +1,322 @@
|
||||
# PR 标题指南
|
||||
|
||||
## 📋 概述
|
||||
|
||||
我们使用 **Conventional Commits** 格式来保持 PR 标题的一致性，但这是**建议性的**，不会阻止你的 PR 被合并。
|
||||
|
||||
## ✅ 推荐格式
|
||||
|
||||
```
|
||||
type(scope): description
|
||||
```
|
||||
|
||||
### 示例
|
||||
|
||||
```
|
||||
feat(trader): add new trading strategy
|
||||
fix(api): resolve authentication issue
|
||||
docs: update README
|
||||
chore(deps): update dependencies
|
||||
ci(workflow): improve GitHub Actions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📖 详细说明
|
||||
|
||||
### Type（类型）- 必需
|
||||
|
||||
描述这次变更的类型：
|
||||
|
||||
| Type | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| `feat` | 新功能 | `feat(trader): add stop-loss feature` |
|
||||
| `fix` | Bug 修复 | `fix(api): handle null response` |
|
||||
| `docs` | 文档变更 | `docs: update installation guide` |
|
||||
| `style` | 代码格式（不影响代码运行） | `style: format code with prettier` |
|
||||
| `refactor` | 重构（既不是新功能也不是修复） | `refactor(exchange): simplify connection logic` |
|
||||
| `perf` | 性能优化 | `perf(ai): optimize prompt processing` |
|
||||
| `test` | 添加或修改测试 | `test(trader): add unit tests` |
|
||||
| `chore` | 构建过程或辅助工具的变动 | `chore: update dependencies` |
|
||||
| `ci` | CI/CD 相关变更 | `ci: add test coverage report` |
|
||||
| `security` | 安全相关修复 | `security: update vulnerable dependencies` |
|
||||
| `build` | 构建系统或外部依赖项变更 | `build: upgrade webpack to v5` |
|
||||
|
||||
### Scope（范围）- 可选
|
||||
|
||||
描述这次变更影响的范围：
|
||||
|
||||
| Scope | 说明 |
|
||||
|-------|------|
|
||||
| `exchange` | 交易所相关 |
|
||||
| `trader` | 交易员/交易策略 |
|
||||
| `ai` | AI 模型相关 |
|
||||
| `api` | API 接口 |
|
||||
| `ui` | 用户界面 |
|
||||
| `frontend` | 前端代码 |
|
||||
| `backend` | 后端代码 |
|
||||
| `security` | 安全相关 |
|
||||
| `deps` | 依赖项 |
|
||||
| `workflow` | GitHub Actions workflows |
|
||||
| `github` | GitHub 配置 |
|
||||
| `actions` | GitHub Actions |
|
||||
| `config` | 配置文件 |
|
||||
| `docker` | Docker 相关 |
|
||||
| `build` | 构建相关 |
|
||||
| `release` | 发布相关 |
|
||||
|
||||
**注意：** 如果变更影响多个范围，可以省略 scope 或选择最主要的。
|
||||
|
||||
### Description（描述）- 必需
|
||||
|
||||
- 使用现在时态（"add" 而不是 "added"）
|
||||
- 首字母小写
|
||||
- 结尾不加句号
|
||||
- 简洁明了地描述变更内容
|
||||
|
||||
---
|
||||
|
||||
## 🎯 完整示例
|
||||
|
||||
### ✅ 好的 PR 标题
|
||||
|
||||
```
|
||||
feat(trader): add risk management system
|
||||
fix(exchange): resolve connection timeout issue
|
||||
docs: add API documentation for trading endpoints
|
||||
style: apply consistent code formatting
|
||||
refactor(ai): simplify prompt processing logic
|
||||
perf(backend): optimize database queries
|
||||
test(api): add integration tests for auth
|
||||
chore(deps): update TypeScript to 5.0
|
||||
ci(workflow): add automated security scanning
|
||||
security(api): fix SQL injection vulnerability
|
||||
build(docker): optimize Docker image size
|
||||
```
|
||||
|
||||
### ⚠️ 需要改进的标题
|
||||
|
||||
| 不好的标题 | 问题 | 改进后 |
|
||||
|-----------|------|--------|
|
||||
| `update code` | 太模糊 | `refactor(trader): simplify order execution logic` |
|
||||
| `Fixed bug` | 首字母大写，不够具体 | `fix(api): handle edge case in login` |
|
||||
| `Add new feature.` | 有句号，不够具体 | `feat(ui): add dark mode toggle` |
|
||||
| `changes` | 完全不符合格式 | `chore: update dependencies` |
|
||||
| `feat: Added new trading algo` | 时态错误 | `feat(trader): add new trading algorithm` |
|
||||
|
||||
---
|
||||
|
||||
## 🤖 自动检查行为
|
||||
|
||||
### 当 PR 标题不符合格式时
|
||||
|
||||
1. **不会阻止合并** ✅
|
||||
- 检查会标记为"建议"
|
||||
- PR 仍然可以被审查和合并
|
||||
|
||||
2. **会收到友好提示** 💬
|
||||
- 机器人会在 PR 中留言
|
||||
- 提供格式说明和示例
|
||||
- 建议如何改进标题
|
||||
|
||||
3. **可以随时更新** 🔄
|
||||
- 更新 PR 标题后会重新检查
|
||||
- 无需关闭和重新打开 PR
|
||||
|
||||
### 示例评论
|
||||
|
||||
如果你的 PR 标题是 `update workflow`，你会收到这样的评论：
|
||||
|
||||
```markdown
|
||||
## ⚠️ PR Title Format Suggestion
|
||||
|
||||
Your PR title doesn't follow the Conventional Commits format,
|
||||
but this won't block your PR from being merged.
|
||||
|
||||
**Current title:** `update workflow`
|
||||
|
||||
**Recommended format:** `type(scope): description`
|
||||
|
||||
### Valid types:
|
||||
feat, fix, docs, style, refactor, perf, test, chore, ci, security, build
|
||||
|
||||
### Common scopes (optional):
|
||||
exchange, trader, ai, api, ui, frontend, backend, security, deps,
|
||||
workflow, github, actions, config, docker, build, release
|
||||
|
||||
### Examples:
|
||||
- feat(trader): add new trading strategy
|
||||
- fix(api): resolve authentication issue
|
||||
- docs: update README
|
||||
- chore(deps): update dependencies
|
||||
- ci(workflow): improve GitHub Actions
|
||||
|
||||
**Note:** This is a suggestion to improve consistency.
|
||||
Your PR can still be reviewed and merged.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔧 配置详情
|
||||
|
||||
### 支持的 Types
|
||||
|
||||
在 `.github/workflows/pr-checks.yml` 中配置：
|
||||
|
||||
```yaml
|
||||
types: |
|
||||
feat
|
||||
fix
|
||||
docs
|
||||
style
|
||||
refactor
|
||||
perf
|
||||
test
|
||||
chore
|
||||
ci
|
||||
security
|
||||
build
|
||||
```
|
||||
|
||||
### 支持的 Scopes
|
||||
|
||||
```yaml
|
||||
scopes: |
|
||||
exchange
|
||||
trader
|
||||
ai
|
||||
api
|
||||
ui
|
||||
frontend
|
||||
backend
|
||||
security
|
||||
deps
|
||||
workflow
|
||||
github
|
||||
actions
|
||||
config
|
||||
docker
|
||||
build
|
||||
release
|
||||
```
|
||||
|
||||
### 添加新的 Scope
|
||||
|
||||
如果你需要添加新的 scope，请：
|
||||
|
||||
1. 在 `.github/workflows/pr-checks.yml` 的 `scopes` 部分添加
|
||||
2. 在 `.github/workflows/pr-checks-run.yml` 更新正则表达式（可选）
|
||||
3. 更新本文档
|
||||
|
||||
---
|
||||
|
||||
## 📚 为什么使用 Conventional Commits？
|
||||
|
||||
### 优点
|
||||
|
||||
1. **自动化 Changelog** 📝
|
||||
- 可以自动生成版本更新日志
|
||||
- 清晰地分类各种变更
|
||||
|
||||
2. **语义化版本** 🔢
|
||||
- `feat` → MINOR 版本（1.1.0）
|
||||
- `fix` → PATCH 版本（1.0.1）
|
||||
- `BREAKING CHANGE` → MAJOR 版本（2.0.0）
|
||||
|
||||
3. **更好的可读性** 👀
|
||||
- 一眼看出 PR 的目的
|
||||
- 更容易浏览 Git 历史
|
||||
|
||||
4. **团队协作** 🤝
|
||||
- 统一的提交风格
|
||||
- 降低沟通成本
|
||||
|
||||
### 示例：自动生成的 Changelog
|
||||
|
||||
```markdown
|
||||
## v1.2.0 (2025-11-02)
|
||||
|
||||
### Features
|
||||
- **trader**: add risk management system (#123)
|
||||
- **ui**: add dark mode toggle (#125)
|
||||
|
||||
### Bug Fixes
|
||||
- **api**: resolve authentication issue (#124)
|
||||
- **exchange**: fix connection timeout (#126)
|
||||
|
||||
### Documentation
|
||||
- update API documentation (#127)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎓 学习资源
|
||||
|
||||
- **Conventional Commits 官网:** https://www.conventionalcommits.org/
|
||||
- **Angular Commit Guidelines:** https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit
|
||||
- **Semantic Versioning:** https://semver.org/
|
||||
|
||||
---
|
||||
|
||||
## ❓ FAQ
|
||||
|
||||
### Q: 我必须遵循这个格式吗？
|
||||
|
||||
**A:** 不必须。这是建议性的，不会阻止你的 PR 被合并。但遵循格式可以提高项目的可维护性。
|
||||
|
||||
### Q: 如果我忘记了怎么办？
|
||||
|
||||
**A:** 机器人会在 PR 中提醒你，你可以随时更新标题。
|
||||
|
||||
### Q: 我可以在一个 PR 中做多种类型的变更吗？
|
||||
|
||||
**A:** 可以，但建议：
|
||||
- 选择最主要的类型
|
||||
- 或者考虑拆分成多个 PR（更易于审查）
|
||||
|
||||
### Q: Scope 可以省略吗？
|
||||
|
||||
**A:** 可以。`requireScope: false` 表示 scope 是可选的。
|
||||
|
||||
示例：`docs: update README` （没有 scope 也可以）
|
||||
|
||||
### Q: 我想添加新的 type 或 scope，怎么做？
|
||||
|
||||
**A:** 提一个 PR 修改 `.github/workflows/pr-checks.yml`，并在本文档中说明新增项的用途。
|
||||
|
||||
### Q: Breaking Changes 怎么表示？
|
||||
|
||||
**A:** 在描述中添加 `BREAKING CHANGE:` 或在 type 后加 `!`：
|
||||
|
||||
```
|
||||
feat!: remove deprecated API
|
||||
feat(api)!: change authentication method
|
||||
|
||||
BREAKING CHANGE: The old /auth endpoint is removed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 统计
|
||||
|
||||
想看项目的 commit 类型分布？运行：
|
||||
|
||||
```bash
|
||||
git log --oneline --no-merges | \
|
||||
grep -oE '^[a-f0-9]+ (feat|fix|docs|style|refactor|perf|test|chore|ci|security|build)' | \
|
||||
cut -d' ' -f2 | sort | uniq -c | sort -rn
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ 快速检查清单
|
||||
|
||||
在提交 PR 前，检查你的标题是否：
|
||||
|
||||
- [ ] 包含有效的 type（feat, fix, docs 等）
|
||||
- [ ] 使用小写字母开头
|
||||
- [ ] 使用现在时态（"add" 而不是 "added"）
|
||||
- [ ] 简洁明了（最好在 50 字符内）
|
||||
- [ ] 准确描述了变更内容
|
||||
|
||||
**记住：** 这些都是建议，不是强制要求！
|
||||
279
.github/PULL_REQUEST_TEMPLATE.md
vendored
279
.github/PULL_REQUEST_TEMPLATE.md
vendored
@@ -1,153 +1,288 @@
|
||||
# Pull Request
|
||||
# Pull Request | PR 提交
|
||||
|
||||
## 📝 Description
|
||||
> **💡 提示 Tip:** 推荐 PR 标题格式 Recommended PR title format: `type(scope): description`
|
||||
> 例如 Examples: `feat(trader): add new strategy` | `fix(api): resolve auth issue`
|
||||
> 详情 Details: [PR Title Guide](./PR_TITLE_GUIDE.md)
|
||||
|
||||
---
|
||||
|
||||
## 📝 Description | 描述
|
||||
|
||||
<!-- Provide a brief summary of your changes -->
|
||||
<!-- 简要描述你的变更 -->
|
||||
|
||||
## 🎯 Type of Change
|
||||
**English:**
|
||||
|
||||
**中文：**
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Type of Change | 变更类型
|
||||
|
||||
<!-- Mark the relevant option with an "x" -->
|
||||
<!-- 在相关选项上打"x" -->
|
||||
|
||||
- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
|
||||
- [ ] ✨ New feature (non-breaking change which adds functionality)
|
||||
- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
|
||||
- [ ] 📝 Documentation update
|
||||
- [ ] 🎨 Code style update (formatting, renaming)
|
||||
- [ ] ♻️ Refactoring (no functional changes)
|
||||
- [ ] ⚡ Performance improvement
|
||||
- [ ] ✅ Test update
|
||||
- [ ] 🔧 Build/config change
|
||||
- [ ] 🐛 Bug fix | 修复 Bug（不影响现有功能的修复）
|
||||
- [ ] ✨ New feature | 新功能（不影响现有功能的新增）
|
||||
- [ ] 💥 Breaking change | 破坏性变更（会导致现有功能无法正常工作的修复或功能）
|
||||
- [ ] 📝 Documentation update | 文档更新
|
||||
- [ ] 🎨 Code style update | 代码样式更新（格式化、重命名等）
|
||||
- [ ] ♻️ Refactoring | 重构（无功能变更）
|
||||
- [ ] ⚡ Performance improvement | 性能优化
|
||||
- [ ] ✅ Test update | 测试更新
|
||||
- [ ] 🔧 Build/config change | 构建/配置变更
|
||||
- [ ] 🔒 Security fix | 安全修复
|
||||
|
||||
## 🔗 Related Issues
|
||||
---
|
||||
|
||||
## 🔗 Related Issues | 相关 Issue
|
||||
|
||||
<!-- Link related issues below. Use "Closes #123" to auto-close issues when PR is merged -->
|
||||
<!-- 在下方关联相关 issue。使用 "Closes #123" 可以在 PR 合并时自动关闭 issue -->
|
||||
|
||||
- Closes #
|
||||
- Related to #
|
||||
- Closes # | 关闭 #
|
||||
- Related to # | 相关 #
|
||||
|
||||
## 📋 Changes Made
|
||||
---
|
||||
|
||||
## 📋 Changes Made | 具体变更
|
||||
|
||||
<!-- List the specific changes you made -->
|
||||
<!-- 列出你做的具体变更 -->
|
||||
|
||||
**English:**
|
||||
- Change 1
|
||||
- Change 2
|
||||
- Change 3
|
||||
|
||||
## 🧪 Testing
|
||||
**中文：**
|
||||
- 变更 1
|
||||
- 变更 2
|
||||
- 变更 3
|
||||
|
||||
### Manual Testing
|
||||
---
|
||||
|
||||
## 🧪 Testing | 测试
|
||||
|
||||
### Manual Testing | 手动测试
|
||||
|
||||
<!-- Describe how you tested your changes -->
|
||||
<!-- 描述你如何测试你的变更 -->
|
||||
|
||||
- [ ] Tested locally (manual verification)
|
||||
- [ ] Tested on testnet (for exchange integrations)
|
||||
- [ ] Tested with different configurations
|
||||
- [ ] Verified no existing functionality broke
|
||||
- [ ] Tested locally | 本地测试通过
|
||||
- [ ] Tested on testnet | 测试网测试通过（交易所集成相关）
|
||||
- [ ] Tested with different configurations | 测试了不同配置
|
||||
- [ ] Verified no existing functionality broke | 确认没有破坏现有功能
|
||||
|
||||
### Test Environment
|
||||
### Test Environment | 测试环境
|
||||
|
||||
- **OS:** [e.g. macOS, Ubuntu]
|
||||
- **Go Version:** [e.g. 1.21.5]
|
||||
- **Exchange:** [if applicable]
|
||||
- **OS | 操作系统:** [e.g. macOS, Ubuntu, Windows]
|
||||
- **Go Version | Go 版本:** [e.g. 1.21.5]
|
||||
- **Node Version | Node 版本:** [e.g. 18.x] (if applicable | 如适用)
|
||||
- **Exchange | 交易所:** [if applicable | 如适用]
|
||||
|
||||
### Test Results
|
||||
### Test Results | 测试结果
|
||||
|
||||
<!-- Paste relevant test output or describe results -->
|
||||
<!-- 粘贴相关测试输出或描述结果 -->
|
||||
|
||||
```
|
||||
Test output here
|
||||
Test output here | 测试输出
|
||||
```
|
||||
|
||||
## 📸 Screenshots / Demo
|
||||
---
|
||||
|
||||
## 📸 Screenshots / Demo | 截图/演示
|
||||
|
||||
<!-- If applicable, add screenshots or video demo -->
|
||||
<!-- 如适用，添加截图或视频演示 -->
|
||||
|
||||
<!-- For UI changes, include before/after screenshots -->
|
||||
<!-- 对于 UI 变更，包含变更前后的截图 -->
|
||||
|
||||
**Before:**
|
||||
**Before | 变更前:**
|
||||
|
||||
|
||||
**After:**
|
||||
**After | 变更后:**
|
||||
|
||||
|
||||
## ✅ Checklist
|
||||
---
|
||||
|
||||
## ✅ Checklist | 检查清单
|
||||
|
||||
<!-- Mark completed items with an "x" -->
|
||||
<!-- 在已完成的项目上打"x" -->
|
||||
|
||||
### Code Quality
|
||||
### Code Quality | 代码质量
|
||||
|
||||
- [ ] My code follows the project's code style ([Contributing Guide](../CONTRIBUTING.md))
|
||||
- [ ] I have performed a self-review of my code
|
||||
- [ ] I have commented my code, particularly in hard-to-understand areas
|
||||
- [ ] My changes generate no new warnings or errors
|
||||
- [ ] Code compiles successfully (`go build` / `npm run build`)
|
||||
- [ ] I have run `go fmt` (for Go code)
|
||||
- [ ] My code follows the project's code style | 我的代码遵循项目代码风格 ([Contributing Guide](../CONTRIBUTING.md))
|
||||
- [ ] I have performed a self-review of my code | 我已进行代码自查
|
||||
- [ ] I have commented my code, particularly in hard-to-understand areas | 我已添加代码注释，特别是难以理解的部分
|
||||
- [ ] My changes generate no new warnings or errors | 我的变更没有产生新的警告或错误
|
||||
- [ ] Code compiles successfully | 代码编译成功 (`go build` / `npm run build`)
|
||||
- [ ] I have run `go fmt` (for Go code) | 我已运行 `go fmt`（Go 代码）
|
||||
- [ ] I have run `npm run lint` (for frontend code) | 我已运行 `npm run lint`（前端代码）
|
||||
|
||||
### Testing
|
||||
### Testing | 测试
|
||||
|
||||
- [ ] I have added tests that prove my fix is effective or that my feature works
|
||||
- [ ] New and existing unit tests pass locally
|
||||
- [ ] I have tested on testnet (for trading/exchange changes)
|
||||
- [ ] I have added tests that prove my fix is effective or that my feature works | 我已添加证明修复有效或功能正常的测试
|
||||
- [ ] New and existing unit tests pass locally | 新旧单元测试在本地通过
|
||||
- [ ] I have tested on testnet (for trading/exchange changes) | 我已在测试网测试（交易/交易所变更）
|
||||
- [ ] Integration tests pass | 集成测试通过
|
||||
|
||||
### Documentation
|
||||
### Documentation | 文档
|
||||
|
||||
- [ ] I have updated the documentation accordingly
|
||||
- [ ] I have updated the README if needed
|
||||
- [ ] I have added inline code comments where necessary
|
||||
- [ ] I have updated type definitions (for TypeScript changes)
|
||||
- [ ] I have updated the documentation accordingly | 我已相应更新文档
|
||||
- [ ] I have updated the README if needed | 我已更新 README（如需要）
|
||||
- [ ] I have added inline code comments where necessary | 我已在必要处添加代码注释
|
||||
- [ ] I have updated type definitions (for TypeScript changes) | 我已更新类型定义（TypeScript 变更）
|
||||
- [ ] I have updated API documentation (if applicable) | 我已更新 API 文档（如适用）
|
||||
|
||||
### Git
|
||||
|
||||
- [ ] My commits follow the conventional commits format (`feat:`, `fix:`, etc.)
|
||||
- [ ] I have rebased my branch on the latest `dev` branch
|
||||
- [ ] There are no merge conflicts
|
||||
- [ ] My commits follow the conventional commits format | 我的提交遵循 Conventional Commits 格式 (`feat:`, `fix:`, etc.)
|
||||
- [ ] I have rebased my branch on the latest `dev` branch | 我已将分支 rebase 到最新的 `dev` 分支
|
||||
- [ ] There are no merge conflicts | 没有合并冲突
|
||||
- [ ] Commit messages are clear and descriptive | 提交信息清晰明确
|
||||
|
||||
## 🔒 Security Considerations
|
||||
---
|
||||
|
||||
## 🔒 Security Considerations | 安全考虑
|
||||
|
||||
<!-- Answer these questions for security-sensitive changes -->
|
||||
<!-- 对于安全敏感的变更，请回答以下问题 -->
|
||||
|
||||
- [ ] No API keys or secrets are hardcoded
|
||||
- [ ] User inputs are properly validated
|
||||
- [ ] No SQL injection vulnerabilities introduced
|
||||
- [ ] Authentication/authorization properly handled
|
||||
- [ ] N/A (not security-related)
|
||||
- [ ] No API keys or secrets are hardcoded | 没有硬编码 API 密钥或密钥
|
||||
- [ ] User inputs are properly validated | 用户输入已正确验证
|
||||
- [ ] No SQL injection vulnerabilities introduced | 未引入 SQL 注入漏洞
|
||||
- [ ] No XSS vulnerabilities introduced | 未引入 XSS 漏洞
|
||||
- [ ] Authentication/authorization properly handled | 认证/授权已正确处理
|
||||
- [ ] Sensitive data is encrypted | 敏感数据已加密
|
||||
- [ ] N/A (not security-related) | 不适用（非安全相关）
|
||||
|
||||
## ⚡ Performance Impact
|
||||
---
|
||||
|
||||
## ⚡ Performance Impact | 性能影响
|
||||
|
||||
<!-- Describe any performance implications -->
|
||||
<!-- 描述任何性能影响 -->
|
||||
|
||||
- [ ] No significant performance impact
|
||||
- [ ] Performance improved
|
||||
- [ ] Performance may be impacted (explain below)
|
||||
- [ ] No significant performance impact | 无显著性能影响
|
||||
- [ ] Performance improved | 性能提升
|
||||
- [ ] Performance may be impacted (explain below) | 性能可能受影响（请在下方说明）
|
||||
|
||||
<!-- If performance impacted, explain: -->
|
||||
<!-- 如果性能受影响，请说明： -->
|
||||
|
||||
## 📚 Additional Notes
|
||||
**English:**
|
||||
|
||||
**中文：**
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Internationalization | 国际化
|
||||
|
||||
<!-- For UI/documentation changes -->
|
||||
<!-- 对于 UI/文档变更 -->
|
||||
|
||||
- [ ] All user-facing text supports i18n | 所有面向用户的文本支持国际化
|
||||
- [ ] Both English and Chinese versions provided | 提供了中英文版本
|
||||
- [ ] N/A | 不适用
|
||||
|
||||
---
|
||||
|
||||
## 📚 Additional Notes | 补充说明
|
||||
|
||||
<!-- Any additional information for reviewers -->
|
||||
<!-- 给审查者的任何补充信息 -->
|
||||
|
||||
**English:**
|
||||
|
||||
**中文：**
|
||||
|
||||
---
|
||||
|
||||
## For Bounty Claims
|
||||
## 💰 For Bounty Claims | 赏金申请
|
||||
|
||||
<!-- Fill this section only if claiming a bounty -->
|
||||
<!-- 仅在申请赏金时填写此部分 -->
|
||||
|
||||
- [ ] This PR is for bounty issue #
|
||||
- [ ] All acceptance criteria from the bounty issue are met
|
||||
- [ ] I have included a demo video/screenshots
|
||||
- [ ] I am ready for payment upon merge
|
||||
- [ ] This PR is for bounty issue # | 此 PR 用于赏金 issue #
|
||||
- [ ] All acceptance criteria from the bounty issue are met | 满足赏金 issue 的所有验收标准
|
||||
- [ ] I have included a demo video/screenshots | 我已包含演示视频/截图
|
||||
- [ ] I am ready for payment upon merge | 我准备好在合并后接收付款
|
||||
|
||||
**Payment Details:** <!-- Discuss privately with maintainers -->
|
||||
**Payment Details | 付款详情:** <!-- Discuss privately with maintainers | 与维护者私下讨论 -->
|
||||
|
||||
---
|
||||
|
||||
## 🙏 Reviewer Notes
|
||||
## 🙏 Reviewer Notes | 审查者注意事项
|
||||
|
||||
<!-- Optional: anything specific you want reviewers to focus on? -->
|
||||
<!-- 可选：你希望审查者关注的特定内容？ -->
|
||||
|
||||
**English:**
|
||||
|
||||
**中文：**
|
||||
|
||||
---
|
||||
|
||||
## 📋 PR Size Estimate | PR 大小估计
|
||||
|
||||
<!-- This helps reviewers plan their time -->
|
||||
<!-- 这有助于审查者安排时间 -->
|
||||
|
||||
- [ ] 🟢 Small (< 100 lines) | 小（< 100 行）
|
||||
- [ ] 🟡 Medium (100-500 lines) | 中（100-500 行）
|
||||
- [ ] 🔴 Large (> 500 lines) | 大（> 500 行）
|
||||
|
||||
<!-- For large PRs, consider: -->
|
||||
<!-- 对于大型 PR，考虑： -->
|
||||
<!-- - Breaking into smaller, focused PRs | 拆分为更小、更专注的 PR -->
|
||||
<!-- - Providing a detailed explanation | 提供详细说明 -->
|
||||
<!-- - Highlighting the most important changes | 突出最重要的变更 -->
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Review Focus Areas | 审查重点
|
||||
|
||||
<!-- Help reviewers know where to focus their attention -->
|
||||
<!-- 帮助审查者了解重点关注的地方 -->
|
||||
|
||||
Please pay special attention to:
|
||||
请特别注意：
|
||||
|
||||
- [ ] Logic changes | 逻辑变更
|
||||
- [ ] Security implications | 安全影响
|
||||
- [ ] Performance optimization | 性能优化
|
||||
- [ ] API changes | API 变更
|
||||
- [ ] Database schema changes | 数据库架构变更
|
||||
- [ ] UI/UX changes | UI/UX 变更
|
||||
|
||||
---
|
||||
|
||||
**By submitting this PR, I confirm that:**
|
||||
- [ ] I have read the [Contributing Guidelines](../CONTRIBUTING.md)
|
||||
- [ ] I agree to the [Code of Conduct](../CODE_OF_CONDUCT.md)
|
||||
- [ ] My contribution is licensed under the MIT License
|
||||
**提交此 PR，我确认：**
|
||||
|
||||
- [ ] I have read the [Contributing Guidelines](../CONTRIBUTING.md) | 我已阅读[贡献指南](../CONTRIBUTING.md)
|
||||
- [ ] I agree to the [Code of Conduct](../CODE_OF_CONDUCT.md) | 我同意[行为准则](../CODE_OF_CONDUCT.md)
|
||||
- [ ] My contribution is licensed under the MIT License | 我的贡献遵循 MIT 许可证
|
||||
- [ ] I understand this is a voluntary contribution | 我理解这是自愿贡献
|
||||
- [ ] I have the right to submit this code | 我有权提交此代码
|
||||
|
||||
---
|
||||
|
||||
<!--
|
||||
🌟 感谢你的贡献！Thank you for your contribution!
|
||||
|
||||
贡献者来自世界各地，我们重视每一份贡献。
|
||||
Contributors come from all around the world, and we value every contribution.
|
||||
|
||||
如果你是首次贡献，欢迎加入我们的社区！
|
||||
If this is your first contribution, welcome to our community!
|
||||
|
||||
💬 需要帮助？Feel free to ask questions in:
|
||||
- GitHub Discussions
|
||||
- Discord: [链接 Link]
|
||||
- Telegram: [链接 Link]
|
||||
-->
|
||||
|
||||
176
.github/workflows/README.md
vendored
Normal file
176
.github/workflows/README.md
vendored
Normal file
@@ -0,0 +1,176 @@
|
||||
# GitHub Actions Workflows
|
||||
|
||||
This directory contains the GitHub Actions workflows for the NOFX project.
|
||||
|
||||
## 📚 Documentation Index
|
||||
|
||||
- **[README.md](./README.md)** - This file, overview of all workflows
|
||||
- **[PERMISSIONS.md](./PERMISSIONS.md)** - Detailed permission analysis and security model
|
||||
- **[TRIGGERS.md](./TRIGGERS.md)** - Comparison of event triggers (pull_request vs pull_request_target vs workflow_run)
|
||||
- **[FORK_PR_FLOW.md](./FORK_PR_FLOW.md)** - Complete analysis of what happens when a fork PR is submitted
|
||||
- **[FLOW_DIAGRAM.md](./FLOW_DIAGRAM.md)** - Visual flow diagrams and quick reference
|
||||
- **[SECRETS_SCANNING.md](./SECRETS_SCANNING.md)** - Secrets scanning solutions and TruffleHog setup
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
**Want to understand how fork PRs work?** → Read [FLOW_DIAGRAM.md](./FLOW_DIAGRAM.md)
|
||||
|
||||
**Need security details?** → Read [PERMISSIONS.md](./PERMISSIONS.md)
|
||||
|
||||
**Confused about triggers?** → Read [TRIGGERS.md](./TRIGGERS.md)
|
||||
|
||||
## PR Check Workflows
|
||||
|
||||
We use a **two-workflow pattern** to safely handle PR checks from both internal and fork PRs:
|
||||
|
||||
### 1. `pr-checks-run.yml` - Execute Checks
|
||||
|
||||
**Trigger:** On pull request (opened, synchronize, reopened)
|
||||
|
||||
**Permissions:** Read-only
|
||||
|
||||
**Purpose:** Executes all PR checks with read-only permissions, making it safe for fork PRs.
|
||||
|
||||
**What it does:**
|
||||
- ✅ Checks PR title format (Conventional Commits)
|
||||
- ✅ Calculates PR size
|
||||
- ✅ Runs backend checks (Go formatting, vet, tests)
|
||||
- ✅ Runs frontend checks (linting, type checking, build)
|
||||
- ✅ Saves all results as artifacts
|
||||
|
||||
**Security:** Safe for fork PRs because it only has read permissions and cannot access secrets or modify the repository.
|
||||
|
||||
### 2. `pr-checks-comment.yml` - Post Results
|
||||
|
||||
**Trigger:** When `pr-checks-run.yml` completes (workflow_run)
|
||||
|
||||
**Permissions:** Write (pull-requests, issues)
|
||||
|
||||
**Purpose:** Posts check results as PR comments, running in the main repository context.
|
||||
|
||||
**What it does:**
|
||||
- ✅ Downloads artifacts from `pr-checks-run.yml`
|
||||
- ✅ Reads check results
|
||||
- ✅ Posts a comprehensive comment to the PR
|
||||
|
||||
**Security:** Safe because:
|
||||
- Runs in the main repository context (not fork context)
|
||||
- Has write permissions but doesn't execute untrusted code
|
||||
- Only reads pre-generated results from artifacts
|
||||
|
||||
### 3. `pr-checks.yml` - Strict Checks
|
||||
|
||||
**Trigger:** On pull request
|
||||
|
||||
**Permissions:** Read + conditional write
|
||||
|
||||
**Purpose:** Runs mandatory checks that must pass before PR can be merged.
|
||||
|
||||
**What it does:**
|
||||
- ✅ Validates PR title (blocks merge if invalid)
|
||||
- ✅ Auto-labels PR based on size and files changed (non-fork only)
|
||||
- ✅ Runs backend tests (Go)
|
||||
- ✅ Runs frontend tests (React/TypeScript)
|
||||
- ✅ Security scanning (Trivy, Gitleaks)
|
||||
|
||||
**Security:**
|
||||
- Fork PRs: Only runs read-only operations (tests, security scans)
|
||||
- Non-fork PRs: Can add labels and comments
|
||||
- Uses `continue-on-error` for operations that may fail on forks
|
||||
|
||||
## Why Two Workflows for PR Checks?
|
||||
|
||||
### The Problem
|
||||
|
||||
When a PR comes from a forked repository:
|
||||
- GitHub restricts `GITHUB_TOKEN` permissions for security
|
||||
- Fork PRs cannot write comments, add labels, or access secrets
|
||||
- This prevents malicious contributors from:
|
||||
- Stealing repository secrets
|
||||
- Modifying workflow files to execute malicious code
|
||||
- Spamming issues/PRs with automated comments
|
||||
|
||||
### The Solution
|
||||
|
||||
**Two-Workflow Pattern:**
|
||||
|
||||
```
|
||||
Fork PR Submitted
|
||||
↓
|
||||
[pr-checks-run.yml]
|
||||
- Runs with read-only permissions
|
||||
- Executes all checks safely
|
||||
- Saves results to artifacts
|
||||
↓
|
||||
[pr-checks-comment.yml]
|
||||
- Triggered by workflow_run
|
||||
- Runs in main repo context (has write permissions)
|
||||
- Downloads artifacts
|
||||
- Posts comment with results
|
||||
```
|
||||
|
||||
This approach:
|
||||
- ✅ Allows fork PRs to run checks
|
||||
- ✅ Safely posts results as comments
|
||||
- ✅ Prevents security vulnerabilities
|
||||
- ✅ Follows GitHub's best practices
|
||||
|
||||
### Can workflow_run Comment on Fork PRs?
|
||||
|
||||
**Yes! ✅ The permissions are sufficient.**
|
||||
|
||||
**Key Understanding:**
|
||||
- `workflow_run` executes in the **base repository** context
|
||||
- Fork PRs exist in the **base repository** (not in the fork)
|
||||
- The base repository's `GITHUB_TOKEN` has write permissions
|
||||
- Therefore, `workflow_run` can comment on fork PRs
|
||||
|
||||
**Security:**
|
||||
- Fork PR code runs in isolated environment (read-only)
|
||||
- Comment workflow doesn't execute fork code
|
||||
- Only reads pre-generated artifact data
|
||||
|
||||
**For detailed permission analysis, see:** [PERMISSIONS.md](./PERMISSIONS.md)
|
||||
|
||||
## Workflow Comparison
|
||||
|
||||
| Workflow | Fork PRs | Write Access | Blocks Merge | Purpose |
|
||||
|----------|----------|--------------|--------------|---------|
|
||||
| `pr-checks-run.yml` | ✅ Yes | ❌ No | ❌ No | Advisory checks |
|
||||
| `pr-checks-comment.yml` | ✅ Yes | ✅ Yes* | ❌ No | Post results |
|
||||
| `pr-checks.yml` | ✅ Yes | ⚠️ Partial | ✅ Yes | Mandatory checks |
|
||||
|
||||
\* Write access only in main repo context, not available to fork PR code
|
||||
|
||||
## File History
|
||||
|
||||
- `pr-checks-advisory.yml.old` - Old advisory workflow that failed on fork PRs (deprecated)
|
||||
- Now replaced by the two-workflow pattern (`pr-checks-run.yml` + `pr-checks-comment.yml`)
|
||||
|
||||
## Testing the Workflows
|
||||
|
||||
### Test with a Fork PR
|
||||
|
||||
1. Fork the repository
|
||||
2. Make changes in your fork
|
||||
3. Create a PR to the main repository
|
||||
4. Observe:
|
||||
- `pr-checks-run.yml` runs successfully with read-only access
|
||||
- `pr-checks-comment.yml` posts results as a comment
|
||||
- `pr-checks.yml` runs tests but skips labeling
|
||||
|
||||
### Test with a Branch PR
|
||||
|
||||
1. Create a branch in the main repository
|
||||
2. Make changes
|
||||
3. Create a PR
|
||||
4. Observe:
|
||||
- All workflows run with full permissions
|
||||
- Labels are added automatically
|
||||
- Comments are posted
|
||||
|
||||
## References
|
||||
|
||||
- [GitHub Actions: Keeping your GitHub Actions and workflows secure Part 1](https://securitylab.github.com/research/github-actions-preventing-pwn-requests/)
|
||||
- [Safely posting comments from untrusted workflows](https://securitylab.github.com/research/github-actions-building-blocks/)
|
||||
- [GitHub Actions: workflow_run trigger](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_run)
|
||||
@@ -9,7 +9,7 @@ on:
|
||||
# Results will be posted as comments to help contributors improve their PRs
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
contents: write
|
||||
pull-requests: write
|
||||
checks: write
|
||||
issues: write
|
||||
248
.github/workflows/pr-checks-comment.yml
vendored
Normal file
248
.github/workflows/pr-checks-comment.yml
vendored
Normal file
@@ -0,0 +1,248 @@
|
||||
name: PR Checks - Comment
|
||||
|
||||
# This workflow posts ADVISORY check results as comments
|
||||
# Runs in the main repo context with write permissions (SAFE)
|
||||
# Triggered after pr-checks-run.yml completes
|
||||
#
|
||||
# NOTE: PR title and size checks are handled by pr-checks.yml (no duplication)
|
||||
# This workflow only posts backend/frontend advisory check results
|
||||
|
||||
on:
|
||||
workflow_run:
|
||||
workflows: ["PR Checks - Run"]
|
||||
types: [completed]
|
||||
|
||||
# Write permissions - SAFE because runs in main repo context
|
||||
# This token has write access to the base repository
|
||||
# Fork PRs exist in the base repo, so we can comment on them
|
||||
permissions:
|
||||
pull-requests: write
|
||||
issues: write
|
||||
actions: read # Needed to download artifacts
|
||||
|
||||
jobs:
|
||||
comment:
|
||||
name: Post Advisory Check Results
|
||||
runs-on: ubuntu-latest
|
||||
# Only run if the workflow was triggered by a pull_request event
|
||||
if: github.event.workflow_run.event == 'pull_request'
|
||||
steps:
|
||||
- name: Download artifacts
|
||||
id: download-artifacts
|
||||
continue-on-error: true
|
||||
uses: actions/download-artifact@v4
|
||||
with:
|
||||
github-token: ${{ secrets.GITHUB_TOKEN }}
|
||||
run-id: ${{ github.event.workflow_run.id }}
|
||||
path: artifacts
|
||||
|
||||
- name: Debug workflow run info
|
||||
run: |
|
||||
echo "=== Workflow Run Debug Info ==="
|
||||
echo "Workflow Run ID: ${{ github.event.workflow_run.id }}"
|
||||
echo "Workflow Run Event: ${{ github.event.workflow_run.event }}"
|
||||
echo "Workflow Run Conclusion: ${{ github.event.workflow_run.conclusion }}"
|
||||
echo "Workflow Run Head SHA: ${{ github.event.workflow_run.head_sha }}"
|
||||
|
||||
- name: List downloaded artifacts
|
||||
run: |
|
||||
echo "=== Checking downloaded artifacts ==="
|
||||
ls -la artifacts/ || echo "⚠️ No artifacts directory found"
|
||||
find artifacts/ -type f || echo "⚠️ No files found in artifacts"
|
||||
echo ""
|
||||
echo "Artifact download result: ${{ steps.download-artifacts.outcome }}"
|
||||
|
||||
- name: Read backend results
|
||||
id: backend
|
||||
continue-on-error: true
|
||||
run: |
|
||||
if [ -f artifacts/backend-results/backend-results.json ]; then
|
||||
echo "=== Backend Results JSON ==="
|
||||
cat artifacts/backend-results/backend-results.json
|
||||
echo "pr_number=$(jq -r '.pr_number' artifacts/backend-results/backend-results.json)" >> $GITHUB_OUTPUT
|
||||
echo "fmt_status=$(jq -r '.fmt_status' artifacts/backend-results/backend-results.json)" >> $GITHUB_OUTPUT
|
||||
echo "vet_status=$(jq -r '.vet_status' artifacts/backend-results/backend-results.json)" >> $GITHUB_OUTPUT
|
||||
echo "test_status=$(jq -r '.test_status' artifacts/backend-results/backend-results.json)" >> $GITHUB_OUTPUT
|
||||
|
||||
# Read output files
|
||||
if [ -f artifacts/backend-results/fmt-files.txt ]; then
|
||||
echo "fmt_files<<EOF" >> $GITHUB_OUTPUT
|
||||
cat artifacts/backend-results/fmt-files.txt >> $GITHUB_OUTPUT
|
||||
echo "EOF" >> $GITHUB_OUTPUT
|
||||
fi
|
||||
if [ -f artifacts/backend-results/vet-output-short.txt ]; then
|
||||
echo "vet_output<<EOF" >> $GITHUB_OUTPUT
|
||||
cat artifacts/backend-results/vet-output-short.txt >> $GITHUB_OUTPUT
|
||||
echo "EOF" >> $GITHUB_OUTPUT
|
||||
fi
|
||||
if [ -f artifacts/backend-results/test-output-short.txt ]; then
|
||||
echo "test_output<<EOF" >> $GITHUB_OUTPUT
|
||||
cat artifacts/backend-results/test-output-short.txt >> $GITHUB_OUTPUT
|
||||
echo "EOF" >> $GITHUB_OUTPUT
|
||||
fi
|
||||
else
|
||||
echo "pr_number=0" >> $GITHUB_OUTPUT
|
||||
echo "⚠️ Backend results artifact not found"
|
||||
fi
|
||||
|
||||
- name: Read frontend results
|
||||
id: frontend
|
||||
continue-on-error: true
|
||||
run: |
|
||||
if [ -f artifacts/frontend-results/frontend-results.json ]; then
|
||||
echo "=== Frontend Results JSON ==="
|
||||
cat artifacts/frontend-results/frontend-results.json
|
||||
echo "build_status=$(jq -r '.build_status' artifacts/frontend-results/frontend-results.json)" >> $GITHUB_OUTPUT
|
||||
|
||||
# Read output files
|
||||
if [ -f artifacts/frontend-results/build-output-short.txt ]; then
|
||||
echo "build_output<<EOF" >> $GITHUB_OUTPUT
|
||||
cat artifacts/frontend-results/build-output-short.txt >> $GITHUB_OUTPUT
|
||||
echo "EOF" >> $GITHUB_OUTPUT
|
||||
fi
|
||||
else
|
||||
echo "⚠️ Frontend results artifact not found"
|
||||
fi
|
||||
|
||||
- name: Post advisory results comment
|
||||
if: steps.backend.outputs.pr_number != '0'
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
script: |
|
||||
const prNumber = ${{ steps.backend.outputs.pr_number }};
|
||||
|
||||
let comment = '## 🤖 Advisory Check Results\n\n';
|
||||
comment += 'These are **advisory** checks to help improve code quality. They won\'t block your PR from being merged.\n\n';
|
||||
comment += '> **Note:** PR title and size checks are handled by the main workflow and may appear in a separate comment.\n\n';
|
||||
|
||||
// Backend checks
|
||||
const fmtStatus = '${{ steps.backend.outputs.fmt_status }}';
|
||||
const vetStatus = '${{ steps.backend.outputs.vet_status }}';
|
||||
const testStatus = '${{ steps.backend.outputs.test_status }}';
|
||||
|
||||
if (fmtStatus || vetStatus || testStatus) {
|
||||
comment += '\n### 🔧 Backend Checks\n\n';
|
||||
|
||||
if (fmtStatus) {
|
||||
comment += '**Go Formatting:** ' + fmtStatus + '\n';
|
||||
const fmtFiles = `${{ steps.backend.outputs.fmt_files }}`;
|
||||
if (fmtFiles && fmtFiles.trim()) {
|
||||
comment += '<details><summary>Files needing formatting</summary>\n\n```\n' + fmtFiles + '\n```\n</details>\n\n';
|
||||
}
|
||||
}
|
||||
|
||||
if (vetStatus) {
|
||||
comment += '**Go Vet:** ' + vetStatus + '\n';
|
||||
const vetOutput = `${{ steps.backend.outputs.vet_output }}`;
|
||||
if (vetOutput && vetOutput.trim()) {
|
||||
comment += '<details><summary>Issues found</summary>\n\n```\n' + vetOutput.substring(0, 1000) + '\n```\n</details>\n\n';
|
||||
}
|
||||
}
|
||||
|
||||
if (testStatus) {
|
||||
comment += '**Tests:** ' + testStatus + '\n';
|
||||
const testOutput = `${{ steps.backend.outputs.test_output }}`;
|
||||
if (testOutput && testOutput.trim()) {
|
||||
comment += '<details><summary>Test output</summary>\n\n```\n' + testOutput.substring(0, 1000) + '\n```\n</details>\n\n';
|
||||
}
|
||||
}
|
||||
|
||||
comment += '\n**Fix locally:**\n';
|
||||
comment += '```bash\n';
|
||||
comment += 'go fmt ./... # Format code\n';
|
||||
comment += 'go vet ./... # Check for issues\n';
|
||||
comment += 'go test ./... # Run tests\n';
|
||||
comment += '```\n';
|
||||
}
|
||||
|
||||
// Frontend checks
|
||||
const buildStatus = '${{ steps.frontend.outputs.build_status }}';
|
||||
|
||||
if (buildStatus) {
|
||||
comment += '\n### ⚛️ Frontend Checks\n\n';
|
||||
|
||||
comment += '**Build & Type Check:** ' + buildStatus + '\n';
|
||||
const buildOutput = `${{ steps.frontend.outputs.build_output }}`;
|
||||
if (buildOutput && buildOutput.trim()) {
|
||||
comment += '<details><summary>Build output</summary>\n\n```\n' + buildOutput.substring(0, 1000) + '\n```\n</details>\n\n';
|
||||
}
|
||||
|
||||
comment += '\n**Fix locally:**\n';
|
||||
comment += '```bash\n';
|
||||
comment += 'cd web\n';
|
||||
comment += 'npm run build # Test build (includes type checking)\n';
|
||||
comment += '```\n';
|
||||
}
|
||||
|
||||
comment += '\n---\n\n';
|
||||
comment += '### 📖 Resources\n\n';
|
||||
comment += '- [Contributing Guidelines](https://github.com/tinkle-community/nofx/blob/dev/CONTRIBUTING.md)\n';
|
||||
comment += '- [Migration Guide](https://github.com/tinkle-community/nofx/blob/dev/docs/community/MIGRATION_ANNOUNCEMENT.md)\n\n';
|
||||
comment += '**Questions?** Feel free to ask in the comments! 🙏\n\n';
|
||||
comment += '---\n\n';
|
||||
comment += '*These checks are advisory and won\'t block your PR from being merged. This comment is automatically generated from [pr-checks-run.yml](https://github.com/tinkle-community/nofx/blob/dev/.github/workflows/pr-checks-run.yml).*';
|
||||
|
||||
// Post comment
|
||||
await github.rest.issues.createComment({
|
||||
issue_number: prNumber,
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
body: comment
|
||||
});
|
||||
|
||||
- name: Post fallback comment if no results
|
||||
if: steps.backend.outputs.pr_number == '0'
|
||||
uses: actions/github-script@v7
|
||||
with:
|
||||
script: |
|
||||
// Try to get PR number from the workflow_run event
|
||||
const pulls = await github.rest.pulls.list({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
state: 'open',
|
||||
head: `${context.repo.owner}:${{ github.event.workflow_run.head_branch }}`
|
||||
});
|
||||
|
||||
if (pulls.data.length === 0) {
|
||||
console.log('⚠️ Could not find PR for this workflow run');
|
||||
return;
|
||||
}
|
||||
|
||||
const prNumber = pulls.data[0].number;
|
||||
|
||||
const comment = [
|
||||
'## ⚠️ Advisory Checks - Results Unavailable',
|
||||
'',
|
||||
'The advisory checks workflow completed, but results could not be retrieved.',
|
||||
'',
|
||||
'### Possible reasons:',
|
||||
'- Artifacts were not uploaded successfully',
|
||||
'- Artifacts expired (retention: 1 day)',
|
||||
'- Permission issues',
|
||||
'',
|
||||
'### What to do:',
|
||||
'1. Check the [PR Checks - Run workflow](${{ github.event.workflow_run.html_url }}) logs',
|
||||
'2. Ensure your code passes local checks:',
|
||||
'```bash',
|
||||
'# Backend',
|
||||
'go fmt ./...',
|
||||
'go vet ./...',
|
||||
'go build',
|
||||
'go test ./...',
|
||||
'',
|
||||
'# Frontend (if applicable)',
|
||||
'cd web',
|
||||
'npm run build',
|
||||
'```',
|
||||
'',
|
||||
'---',
|
||||
'',
|
||||
'*This is an automated fallback message. The advisory checks ran but results are not available.*'
|
||||
].join('\n');
|
||||
|
||||
await github.rest.issues.createComment({
|
||||
issue_number: prNumber,
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
body: comment
|
||||
});
|
||||
160
.github/workflows/pr-checks-run.yml
vendored
Normal file
160
.github/workflows/pr-checks-run.yml
vendored
Normal file
@@ -0,0 +1,160 @@
|
||||
name: PR Checks - Run
|
||||
|
||||
# This workflow runs advisory PR checks with read-only permissions
|
||||
# Safe for fork PRs - results are saved as artifacts
|
||||
# Companion workflow (pr-checks-comment.yml) will post comments
|
||||
#
|
||||
# NOTE: This workflow provides ADVISORY checks (non-blocking)
|
||||
# Main blocking checks are in pr-checks.yml
|
||||
# PR title and size checks are handled by pr-checks.yml (no duplication)
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
types: [opened, synchronize, reopened]
|
||||
branches: [main, dev]
|
||||
|
||||
# Read-only permissions - safe for fork PRs
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
# Backend advisory checks
|
||||
# Different from pr-checks.yml: these use continue-on-error and generate reports
|
||||
backend-checks:
|
||||
name: Backend Checks
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Go
|
||||
uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: '1.21'
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y libta-lib-dev || true
|
||||
go mod download || true
|
||||
|
||||
- name: Check Go formatting
|
||||
id: go-fmt
|
||||
continue-on-error: true
|
||||
run: |
|
||||
UNFORMATTED=$(gofmt -l . 2>/dev/null || echo "")
|
||||
if [ -n "$UNFORMATTED" ]; then
|
||||
echo "status=⚠️ Needs formatting" >> $GITHUB_OUTPUT
|
||||
echo "$UNFORMATTED" | head -10 > fmt-files.txt
|
||||
else
|
||||
echo "status=✅ Good" >> $GITHUB_OUTPUT
|
||||
echo "" > fmt-files.txt
|
||||
fi
|
||||
|
||||
- name: Run go vet
|
||||
id: go-vet
|
||||
continue-on-error: true
|
||||
run: |
|
||||
if go vet ./... 2>&1 | tee vet-output.txt; then
|
||||
echo "status=✅ Good" >> $GITHUB_OUTPUT
|
||||
else
|
||||
echo "status=⚠️ Issues found" >> $GITHUB_OUTPUT
|
||||
cat vet-output.txt | head -20 > vet-output-short.txt
|
||||
fi
|
||||
|
||||
- name: Run tests
|
||||
id: go-test
|
||||
continue-on-error: true
|
||||
run: |
|
||||
if go test ./... -v 2>&1 | tee test-output.txt; then
|
||||
echo "status=✅ Passed" >> $GITHUB_OUTPUT
|
||||
else
|
||||
echo "status=⚠️ Failed" >> $GITHUB_OUTPUT
|
||||
cat test-output.txt | tail -30 > test-output-short.txt
|
||||
fi
|
||||
|
||||
- name: Save backend results
|
||||
if: always()
|
||||
run: |
|
||||
cat > backend-results.json <<EOF
|
||||
{
|
||||
"pr_number": ${{ github.event.pull_request.number }},
|
||||
"fmt_status": "${{ steps.go-fmt.outputs.status }}",
|
||||
"vet_status": "${{ steps.go-vet.outputs.status }}",
|
||||
"test_status": "${{ steps.go-test.outputs.status }}"
|
||||
}
|
||||
EOF
|
||||
|
||||
- name: Upload backend results
|
||||
if: always()
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: backend-results
|
||||
path: |
|
||||
backend-results.json
|
||||
fmt-files.txt
|
||||
vet-output-short.txt
|
||||
test-output-short.txt
|
||||
retention-days: 1
|
||||
|
||||
# Frontend advisory checks
|
||||
# Different from pr-checks.yml: these use continue-on-error and generate reports
|
||||
frontend-checks:
|
||||
name: Frontend Checks
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Node.js
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '18'
|
||||
|
||||
- name: Check if web directory exists
|
||||
id: check-web
|
||||
run: |
|
||||
if [ -d "web" ]; then
|
||||
echo "exists=true" >> $GITHUB_OUTPUT
|
||||
else
|
||||
echo "exists=false" >> $GITHUB_OUTPUT
|
||||
fi
|
||||
|
||||
- name: Install dependencies
|
||||
if: steps.check-web.outputs.exists == 'true'
|
||||
working-directory: ./web
|
||||
continue-on-error: true
|
||||
run: npm ci
|
||||
|
||||
- name: Build and Type Check
|
||||
if: steps.check-web.outputs.exists == 'true'
|
||||
id: build
|
||||
working-directory: ./web
|
||||
continue-on-error: true
|
||||
run: |
|
||||
# build script includes: tsc && vite build
|
||||
if npm run build 2>&1 | tee build-output.txt; then
|
||||
echo "status=✅ Success" >> $GITHUB_OUTPUT
|
||||
else
|
||||
echo "status=⚠️ Failed" >> $GITHUB_OUTPUT
|
||||
cat build-output.txt | tail -30 > build-output-short.txt
|
||||
fi
|
||||
|
||||
- name: Save frontend results
|
||||
if: always() && steps.check-web.outputs.exists == 'true'
|
||||
working-directory: ./web
|
||||
run: |
|
||||
cat > frontend-results.json <<EOF
|
||||
{
|
||||
"pr_number": ${{ github.event.pull_request.number }},
|
||||
"build_status": "${{ steps.build.outputs.status }}"
|
||||
}
|
||||
EOF
|
||||
|
||||
- name: Upload frontend results
|
||||
if: always() && steps.check-web.outputs.exists == 'true'
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: frontend-results
|
||||
path: |
|
||||
web/frontend-results.json
|
||||
web/build-output-short.txt
|
||||
retention-days: 1
|
||||
203
.github/workflows/pr-checks.yml
vendored
203
.github/workflows/pr-checks.yml
vendored
@@ -7,13 +7,24 @@ on:
|
||||
- dev
|
||||
- main
|
||||
|
||||
# Default permissions for all jobs
|
||||
# Note: Fork PRs won't have write access for security
|
||||
# Advisory checks use separate workflow (pr-checks-run.yml + pr-checks-comment.yml)
|
||||
permissions:
|
||||
contents: read # Read repository contents
|
||||
pull-requests: write # Manage PRs (labels, comments) - only works for non-fork PRs
|
||||
issues: write # Manage issues (PRs are issues) - only works for non-fork PRs
|
||||
|
||||
jobs:
|
||||
# Validate PR title and description
|
||||
validate-pr:
|
||||
name: Validate PR Format
|
||||
runs-on: ubuntu-latest
|
||||
# Inherits workflow-level permissions (contents: read, pull-requests: write, issues: write)
|
||||
steps:
|
||||
- name: Check PR title format
|
||||
id: semantic-pr
|
||||
continue-on-error: true # Don't block PR if title format is invalid
|
||||
uses: amannn/action-semantic-pull-request@v5
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
@@ -29,6 +40,7 @@ jobs:
|
||||
chore
|
||||
ci
|
||||
security
|
||||
build
|
||||
scopes: |
|
||||
exchange
|
||||
trader
|
||||
@@ -39,10 +51,70 @@ jobs:
|
||||
backend
|
||||
security
|
||||
deps
|
||||
workflow
|
||||
github
|
||||
actions
|
||||
config
|
||||
docker
|
||||
build
|
||||
release
|
||||
requireScope: false
|
||||
|
||||
- name: Comment on invalid PR title
|
||||
if: steps.semantic-pr.outcome == 'failure'
|
||||
uses: actions/github-script@v7
|
||||
continue-on-error: true # Don't fail for fork PRs
|
||||
with:
|
||||
script: |
|
||||
const prTitle = context.payload.pull_request.title;
|
||||
const isFork = context.payload.pull_request.head.repo.full_name !== context.payload.pull_request.base.repo.full_name;
|
||||
|
||||
const comment = [
|
||||
'## ⚠️ PR Title Format Suggestion',
|
||||
'',
|
||||
"Your PR title doesn't follow the Conventional Commits format, but **this won't block your PR from being merged**.",
|
||||
'',
|
||||
`**Current title:** \`${prTitle}\``,
|
||||
'',
|
||||
'**Recommended format:** `type(scope): description`',
|
||||
'',
|
||||
'### Valid types:',
|
||||
'`feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci`, `security`, `build`',
|
||||
'',
|
||||
'### Common scopes (optional):',
|
||||
'`exchange`, `trader`, `ai`, `api`, `ui`, `frontend`, `backend`, `security`, `deps`, `workflow`, `github`, `actions`, `config`, `docker`, `build`, `release`',
|
||||
'',
|
||||
'### Examples:',
|
||||
'- `feat(trader): add new trading strategy`',
|
||||
'- `fix(api): resolve authentication issue`',
|
||||
'- `docs: update README`',
|
||||
'- `chore(deps): update dependencies`',
|
||||
'- `ci(workflow): improve GitHub Actions`',
|
||||
'',
|
||||
'**Note:** This is a suggestion to improve consistency. Your PR can still be reviewed and merged.',
|
||||
'',
|
||||
'---',
|
||||
'*This is an automated comment. You can update the PR title anytime.*'
|
||||
].join('\n');
|
||||
|
||||
if (!isFork) {
|
||||
try {
|
||||
await github.rest.issues.createComment({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: context.payload.pull_request.number,
|
||||
body: comment
|
||||
});
|
||||
} catch (error) {
|
||||
console.log('Could not post comment (expected for fork PRs):', error.message);
|
||||
}
|
||||
} else {
|
||||
console.log('Fork PR - comment will be posted by pr-checks-comment.yml');
|
||||
}
|
||||
|
||||
- name: Check PR size
|
||||
uses: actions/github-script@v7
|
||||
continue-on-error: true # Don't fail for fork PRs
|
||||
with:
|
||||
script: |
|
||||
const pr = context.payload.pull_request;
|
||||
@@ -50,6 +122,9 @@ jobs:
|
||||
const deletions = pr.deletions;
|
||||
const total = additions + deletions;
|
||||
|
||||
// Check if this is a fork PR
|
||||
const isFork = pr.head.repo.full_name !== pr.base.repo.full_name;
|
||||
|
||||
let label = '';
|
||||
let comment = '';
|
||||
|
||||
@@ -64,28 +139,39 @@ jobs:
|
||||
comment = '🚨 This PR is **large** (>' + total + ' lines changed). Please consider breaking it into smaller, focused PRs for easier review.';
|
||||
}
|
||||
|
||||
// Add size label
|
||||
await github.rest.issues.addLabels({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: pr.number,
|
||||
labels: [label]
|
||||
});
|
||||
// Only add labels/comments for non-fork PRs (fork PRs don't have write permission)
|
||||
if (!isFork) {
|
||||
try {
|
||||
// Add size label
|
||||
await github.rest.issues.addLabels({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: pr.number,
|
||||
labels: [label]
|
||||
});
|
||||
|
||||
// Add comment for large PRs
|
||||
if (total >= 1000) {
|
||||
await github.rest.issues.createComment({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: pr.number,
|
||||
body: comment
|
||||
});
|
||||
// Add comment for large PRs
|
||||
if (total >= 1000) {
|
||||
await github.rest.issues.createComment({
|
||||
owner: context.repo.owner,
|
||||
repo: context.repo.repo,
|
||||
issue_number: pr.number,
|
||||
body: comment
|
||||
});
|
||||
}
|
||||
} catch (error) {
|
||||
console.log('Failed to add label/comment (expected for fork PRs):', error.message);
|
||||
}
|
||||
} else {
|
||||
console.log('Fork PR detected - skipping label/comment (will be handled by pr-checks-comment.yml)');
|
||||
}
|
||||
|
||||
# Backend tests
|
||||
backend-tests:
|
||||
name: Backend Tests (Go)
|
||||
# Backend checks (simplified - no TA-Lib required)
|
||||
backend-checks:
|
||||
name: Backend Code Quality (Go)
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read # Only need read access for testing
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
@@ -95,11 +181,6 @@ jobs:
|
||||
with:
|
||||
go-version: '1.21'
|
||||
|
||||
- name: Install TA-Lib
|
||||
run: |
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y libta-lib-dev
|
||||
|
||||
- name: Cache Go modules
|
||||
uses: actions/cache@v4
|
||||
with:
|
||||
@@ -112,32 +193,32 @@ jobs:
|
||||
run: go mod download
|
||||
|
||||
- name: Run go fmt
|
||||
continue-on-error: true # Don't block PR if formatting issues found
|
||||
run: |
|
||||
if [ "$(gofmt -s -l . | wc -l)" -gt 0 ]; then
|
||||
echo "Please run 'go fmt' on your code"
|
||||
echo "⚠️ Code formatting issues found. Please run 'go fmt ./...' locally."
|
||||
echo ""
|
||||
echo "Files needing formatting:"
|
||||
gofmt -s -l .
|
||||
echo ""
|
||||
echo "This is a warning and won't block your PR from being merged."
|
||||
exit 1
|
||||
else
|
||||
echo "✅ All Go files are properly formatted"
|
||||
fi
|
||||
|
||||
- name: Run go vet
|
||||
run: go vet ./...
|
||||
|
||||
- name: Run tests
|
||||
run: go test -v -race -coverprofile=coverage.out ./...
|
||||
|
||||
- name: Build
|
||||
run: go build -v -o nofx
|
||||
|
||||
- name: Upload coverage
|
||||
uses: codecov/codecov-action@v4
|
||||
with:
|
||||
file: ./coverage.out
|
||||
flags: backend
|
||||
|
||||
# Frontend tests
|
||||
frontend-tests:
|
||||
name: Frontend Tests (React/TypeScript)
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read # Only need read access for testing
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
@@ -159,24 +240,21 @@ jobs:
|
||||
working-directory: ./web
|
||||
run: npm ci
|
||||
|
||||
- name: Run linter
|
||||
working-directory: ./web
|
||||
run: npm run lint
|
||||
|
||||
- name: Run type check
|
||||
working-directory: ./web
|
||||
run: npm run type-check || true # Don't fail on type errors for now
|
||||
|
||||
- name: Build
|
||||
- name: Build and Type Check
|
||||
working-directory: ./web
|
||||
run: npm run build
|
||||
# Note: build script runs "tsc && vite build" which includes type checking
|
||||
|
||||
# Auto-label based on files changed
|
||||
auto-label:
|
||||
name: Auto Label PR
|
||||
runs-on: ubuntu-latest
|
||||
# Only run for non-fork PRs (fork PRs don't have write permission)
|
||||
if: github.event.pull_request.head.repo.full_name == github.repository
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: write
|
||||
issues: write # Required: PRs are issues, labeler needs to modify issue labels
|
||||
steps:
|
||||
- uses: actions/labeler@v5
|
||||
with:
|
||||
@@ -187,6 +265,9 @@ jobs:
|
||||
security-check:
|
||||
name: Security Scan
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read
|
||||
security-events: write # Required: Upload SARIF results to GitHub Security
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
@@ -209,29 +290,51 @@ jobs:
|
||||
secrets-check:
|
||||
name: Check for Secrets
|
||||
runs-on: ubuntu-latest
|
||||
permissions:
|
||||
contents: read # Only need read access for scanning
|
||||
steps:
|
||||
- name: Checkout code
|
||||
uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Run Gitleaks
|
||||
uses: gitleaks/gitleaks-action@v2
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
- name: Run TruffleHog OSS
|
||||
uses: trufflesecurity/trufflehog@main
|
||||
with:
|
||||
path: ./
|
||||
base: ${{ github.event.pull_request.base.sha }}
|
||||
head: ${{ github.event.pull_request.head.sha }}
|
||||
extra_args: --debug --only-verified
|
||||
|
||||
# All checks passed
|
||||
all-checks:
|
||||
name: All Checks Passed
|
||||
runs-on: ubuntu-latest
|
||||
needs: [validate-pr, backend-tests, frontend-tests, security-check, secrets-check]
|
||||
needs: [validate-pr, backend-checks, frontend-tests, security-check, secrets-check]
|
||||
if: always()
|
||||
permissions:
|
||||
contents: read # Only need read access for status checking
|
||||
steps:
|
||||
- name: Check all jobs
|
||||
run: |
|
||||
if [ "${{ contains(needs.*.result, 'failure') }}" == "true" ]; then
|
||||
echo "Some checks failed"
|
||||
# Note: validate-pr uses continue-on-error, so it won't block even if title format is invalid
|
||||
# We only care about actual test failures
|
||||
echo "validate-pr: ${{ needs.validate-pr.result }}"
|
||||
echo "backend-checks: ${{ needs.backend-checks.result }}"
|
||||
echo "frontend-tests: ${{ needs.frontend-tests.result }}"
|
||||
echo "security-check: ${{ needs.security-check.result }}"
|
||||
echo "secrets-check: ${{ needs.secrets-check.result }}"
|
||||
|
||||
# Check if any critical checks failed (excluding validate-pr which is advisory)
|
||||
if [[ "${{ needs.backend-checks.result }}" == "failure" ]] || \
|
||||
[[ "${{ needs.frontend-tests.result }}" == "failure" ]] || \
|
||||
[[ "${{ needs.security-check.result }}" == "failure" ]] || \
|
||||
[[ "${{ needs.secrets-check.result }}" == "failure" ]]; then
|
||||
echo "❌ Critical checks failed"
|
||||
exit 1
|
||||
else
|
||||
echo "All checks passed!"
|
||||
echo "✅ All critical checks passed!"
|
||||
if [[ "${{ needs.validate-pr.result }}" != "success" ]]; then
|
||||
echo "ℹ️ Note: PR title format check is advisory only and doesn't block merging"
|
||||
fi
|
||||
fi
|
||||
|
||||
@@ -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
|
||||
|
||||
612
docs/guides/TROUBLESHOOTING.md
Normal file
612
docs/guides/TROUBLESHOOTING.md
Normal file
@@ -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
|
||||
612
docs/guides/TROUBLESHOOTING.zh-CN.md
Normal file
612
docs/guides/TROUBLESHOOTING.zh-CN.md
Normal file
@@ -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
|
||||
@@ -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
|
||||
|
||||
@@ -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