feat: 添加英文文档，更新中文文档以提升用户体验和使用指南的清晰度

2026-09-10 16:58:08 +00:00 · 2025-09-27 22:46:32 +08:00
parent a998b3d3a1
commit b45539b7c2
3 changed files with 297 additions and 365 deletions
@@ -1,203 +1,154 @@
-# 简明上手指南（给零基础小白）
+# 简明上手指南（零基础）

-这份文档一步一步教你在 Windows 或 macOS 本地把项目跑起来：从下载代码、安装工具、配置环境变量（.env）、获取 Aster API，到运行项目。每一步都尽量写得很直白。
+这份指南面向完全没有开发经验的用户，手把手带你在 Windows、macOS（或 WSL）上运行 **ritmex-bot**。每个步骤都尽量写得直观，出现问题也能快速定位。

 ---

-## 1. 下载代码（两种方式）
+## 0. 你需要准备什么？
+- **Git（推荐）**：从 [git-scm.com](https://git-scm.com/download) 安装；macOS 在终端输入 `git --version` 会提示安装 Xcode Command Line Tools。
+- **VS Code**：前往 [code.visualstudio.com](https://code.visualstudio.com/) 下载。用它编辑 `.env` 与查看文件最方便。
+- **终端/命令行**：
+  - macOS：Spotlight 搜索 “Terminal”
+  - Windows：开始菜单搜索 “PowerShell” 或 “Windows Terminal”
+  - WSL：运行 `wsl` 后进入 Linux 子系统

- 方式 A：使用 Git（推荐）
-  1) 安装 Git：
-     - Windows：到 `https://git-scm.com/download/win` 下载并安装，一路“下一步”。
-     - macOS：打开“终端”（Terminal），输入 `git --version` 看是否已自带。如果提示未安装，会引导你安装 Xcode Command Line Tools，按提示安装即可。
-  2) 打开命令行：
-     - Windows：开始菜单搜索“PowerShell”或“Windows Terminal”→ 打开。
-     - macOS：按 `⌘ + 空格` 搜索“Terminal”→ 打开。
-  3) 在命令行输入（会把代码下载到当前目录下的 ritmex-bot 文件夹）：
-     ```bash
-     git clone https://github.com/discountry/ritmex-bot.git
-     ```
-
- 方式 B：不用 Git，直接下压缩包
-  1) 打开项目页面：`https://github.com/discountry/ritmex-bot`
-  2) 点绿色的 `Code` 按钮 → `Download ZIP`
-  3) 下载后解压到一个好找的位置，例如：
-     - Windows：`C:\Users\你的用户名\Desktop\ritmex-bot`
-     - macOS：`~/Desktop/ritmex-bot`
+如果暂时无法使用 Git，可以在 GitHub 上下载 ZIP，后面步骤相同。

 ---

-## 2. 安装 VS Code（代码编辑器）
- 下载地址：`https://code.visualstudio.com/`
- Windows/macOS 都可以一路“下一步”安装。
- 安装完成后，打开 VS Code，点“文件 → 打开文件夹（Open Folder）”，选中你刚下载/解压的 `ritmex-bot` 文件夹。
-
---
-
-## 3. 安装 Bun（运行环境）
-项目使用 Bun 作为运行环境（类似 Node.js，但更快，命令更简单）。
-
- macOS / Linux：在“终端”输入：
-  ```bash
-  curl -fsSL https://bun.sh/install | bash
-  ```
-  安装后请关闭并重新打开终端，再输入 `bun -v`，能看到版本号就说明成功。
-
- Windows（PowerShell）：
-  ```powershell
-  powershell -c "irm bun.sh/install.ps1 | iex"
-  ```
-  安装后关闭并重新打开 PowerShell，输入 `bun -v` 出现版本号即成功。
-
- 如果上述办法不行，去 Bun 官网查看其他方式：`https://bun.com/get`
-
- 首次进入项目目录后，安装依赖：
-  ```bash
-  bun install
-  ```
-
---
-
-## 4. 找到项目目录，并在命令行跳转过去
- 你需要知道 `ritmex-bot` 文件夹具体在哪。
-  - Windows 常见路径：`C:\Users\你的用户名\Desktop\ritmex-bot`
-  - macOS 常见路径：`~/Desktop/ritmex-bot`
- 命令行使用 `cd` 跳转：
-  ```bash
-  # macOS 示例
-  cd ~/Desktop/ritmex-bot
-
-  # Windows 示例（注意替换“你的用户名”）
-  cd C:\Users\你的用户名\Desktop\ritmex-bot
-  ```
- 成功进入后，输入 `ls`（macOS）或 `dir`（Windows）应能看到 `package.json`、`index.ts` 等文件。
-
---
-
-## 5. 配置环境变量（.env 文件）
-项目运行需要你的 Aster API 密钥，以及一些策略参数。Bun 会自动读取根目录的 `.env` 文件。
-
-1) 在项目根目录创建 `.env` 文件（如果没有的话）。可以先复制下面这份最小示例：
-   ```bash
-   # 复制以下内容到 .env（用记事本/VS Code 打开也可以）
-   ASTER_API_KEY=在这里填你的Key
-   ASTER_API_SECRET=在这里填你的Secret
-
-   # 可选参数（都有默认值，不填也能跑）
-   TRADE_SYMBOL=BTCUSDT
-   TRADE_AMOUNT=0.001
-   LOSS_LIMIT=0.03
-   TRAILING_PROFIT=0.2
-   TRAILING_CALLBACK_RATE=0.2
-   PROFIT_LOCK_TRIGGER_USD=0.1
-   PROFIT_LOCK_OFFSET_USD=0.05
-   PRICE_TICK=0.1
-   QTY_STEP=0.001
-   ```
-
-2) 在 Windows 下怎么编辑 `.env`？
-   - 方法 A：在 VS Code 左侧资源管理器里右键新建文件，命名为 `.env`，然后把上面的内容粘贴进去保存。
-   - 方法 B：在资源管理器勾选“查看 → 显示文件扩展名”，然后新建文本文件，重命名为 `.env`（注意不要叫 `.env.txt`）。用记事本或 VS Code 打开，把内容粘贴进去保存。
-
-3) 这些变量的作用（知道大概即可）：
-   - `ASTER_API_KEY` / `ASTER_API_SECRET`：你在 Aster 交易所申请的 API 凭证（必填）。
-   - `TRADE_SYMBOL`：交易对，默认 `BTCUSDT`。
-   - `TRADE_AMOUNT`：每次下单的数量。
-   - `LOSS_LIMIT`：每笔最大允许亏损（美元计）。
-   - `TRAILING_PROFIT` / `TRAILING_CALLBACK_RATE`：移动止盈的触发值与回撤百分比。
-   - `PROFIT_LOCK_*`：达到一定浮盈后，自动把基础止损往有利方向移动的参数。
-   - `PRICE_TICK` / `QTY_STEP`：该交易对的最小价格变动单位和最小下单步长。
-
-> 进阶：做市策略还有一些 `MAKER_*` 参数（如 `MAKER_PRICE_CHASE`、`MAKER_REFRESH_INTERVAL_MS` 等），需要时可在 `src/config.ts` 查到名称并按需加到 `.env` 重写默认值。
-
---
-
-## 6. 去哪里获取 Aster 的 API Key/Secret？
- 打开 Aster 的 API 管理页面：`https://www.asterdex.com/zh-CN/api-management`
- 登录后创建新的 API，记录下 `API Key` 和 `Secret` 并填入 `.env`。
- 权限仅勾选你需要的，谨慎保管。不要把 `.env` 上传到任何地方。
-
---
-
-## 7. 运行项目（命令）
-确保你已在项目根目录，并且 `.env` 已配置好：
-
+## 1. 获取项目代码
+### 方式 A：Git（推荐）
 ```bash
-bun install       # 第一次运行需要安装依赖
-bun run index.ts  # 启动程序（等同于 npm run start，但我们用 Bun）
+git clone https://github.com/discountry/ritmex-bot.git
+cd ritmex-bot
 ```

-启动后，终端里会出现一个交互界面：
- 使用键盘 ↑ / ↓ 选择“趋势策略”或“做市策略”，回车启动。
- 按 `Esc` 返回菜单。
- 按 `Ctrl + C` 退出程序。
+### 方式 B：下载压缩包
+1. 打开仓库页面：<https://github.com/discountry/ritmex-bot>
+2. 点击绿色的 `Code` → `Download ZIP`
+3. 解压到易于找到的路径，例如：
+   - Windows：`C:\Users\你的用户名\Desktop\ritmex-bot`
+   - macOS：`~/Desktop/ritmex-bot`
+4. 打开终端，使用 `cd` 进入该目录：
+   ```bash
+   cd ~/Desktop/ritmex-bot         # macOS 示例
+   cd C:\Users\你\Desktop\ritmex-bot  # Windows 示例
+   ```

-如果你更喜欢用脚本，也可以：
+进入项目后，执行 `ls`（macOS/Linux）或 `dir`（Windows）应能看到 `package.json`、`index.ts` 等文件。
+
+---
+
+## 2. 安装 Bun（项目运行环境）
+### macOS / Linux
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+安装完关闭并重新打开终端，输入 `bun -v`，出现版本号表示成功。
+
+### Windows PowerShell
+```powershell
+powershell -c "irm bun.sh/install.ps1 | iex"
+```
+同样重新打开 PowerShell，确认 `bun -v` 正常。
+
+> 其他安装方式详见 [bun.com/get](https://bun.com/get)。
+
+---
+
+## 3. 安装依赖
+在项目目录执行：
+```bash
+bun install
+```
+首次运行会下载所有依赖包。
+
+---
+
+## 4. 配置环境变量（.env）
+### 复制模板
+```bash
+cp .env.example .env
+```
+若在 Windows 无法使用 `cp`，可以在资源管理器中复制 `.env.example` 并重命名为 `.env`。
+
+### 编辑 `.env`
+用 VS Code 或记事本打开 `.env`，至少填入：
+```bash
+ASTER_API_KEY=你的AsterKey
+ASTER_API_SECRET=你的AsterSecret
+```
+其他常用参数已有默认值，需要个性化时修改即可：
+- `TRADE_SYMBOL` / `TRADE_AMOUNT`
+- `LOSS_LIMIT`、`TRAILING_PROFIT`、`TRAILING_CALLBACK_RATE`
+- `PROFIT_LOCK_TRIGGER_USD` / `PROFIT_LOCK_OFFSET_USD`
+- `BOLLINGER_LENGTH` / `BOLLINGER_STD_MULTIPLIER` / `MIN_BOLLINGER_BANDWIDTH`
+- `PRICE_TICK` / `QTY_STEP`
+- `MAKER_*` 系列（若要启用做市策略）
+
+如需切换到 GRVT，请将 `EXCHANGE=grvt` 并补充 `GRVT_API_KEY`、`GRVT_API_SECRET`、`GRVT_SUB_ACCOUNT_ID` 等变量，详细说明见 `.env.example`。
+
+### 获取 GRVT API Key/Secret
+1. 打开 <https://grvt.io/exchange/account/api-keys>
+2. 点击 **Generate** 创建新的 API 组合，保存系统生成的 **API Key** 与 **钱包密钥（Wallet Secret）**
+3. 页面同时会显示 **Trading Account ID**，请一并记录备用（填入 `GRVT_SUB_ACCOUNT_ID`）
+4. 将上述值写入 `.env`，并妥善保管：
+   ```bash
+   EXCHANGE=grvt
+   GRVT_API_KEY=你的GRVTKey
+   GRVT_API_SECRET=你的GRVT钱包密钥
+   GRVT_SUB_ACCOUNT_ID=你的TradingAccountID
+   ```
+5. 仍需保留 `TRADE_SYMBOL`、`PRICE_TICK` 等核心参数，确保与 GRVT 合约规则一致
+
+> GRVT 的 API Key 和钱包密钥生成后只显示一次，请立即保存。Trading Account ID 用于区分子账户。
+
+> 保存 `.env` 后无需手动刷新，只要重新运行命令即可生效。
+
+---
+
+## 5. 获取 Aster API Key/Secret
+1. 打开 <https://www.asterdex.com/zh-CN/api-management>
+2. 登录后创建新的 API，记录 `API Key` 与 `Secret`
+3. 仅勾选必要权限，并将值填入 `.env`
+
+切记：不要把 `.env` 上传或分享给他人。
+
+---
+
+## 6. 启动程序
+确保仍在项目根目录：
+```bash
+bun run index.ts
+```
+- 上下方向键选择“趋势策略”或“做市策略”
+- `Enter` 启动策略，`Esc` 返回菜单
+- `Ctrl + C` 结束程序
+
+常用别名：
 ```bash
 bun run start
-# 或
 bun run dev
 ```

 ---

-## 8. 常见问题（简单排查）
- 运行时报错“缺少 ASTER_API_KEY/SECRET”：说明 `.env` 没正确配置或没被读取。确认 `.env` 在项目根目录，变量名拼写无误。
- 终端显示连不上：检查你的网络是否能访问 `wss://fstream.asterdex.com/ws` 和 `https://fapi.asterdex.com`。
- 显示权限错误/下单失败：到 Aster 后台检查 API 权限，确认已开启合约交易相关权限。
- 界面卡着没反应：请在“真”终端里运行（Windows Terminal、PowerShell、macOS Terminal），不要在只读的输出窗口里运行。
+## 7. 常见问题与排查
+- **提示缺少 ASTER_API_KEY/SECRET**：`.env` 未生效。确认文件在项目根目录且变量无额外空格或中文字符。
+- **签名或时间戳错误**：同步电脑时间。
+  - macOS：系统设置 → 通用 → 日期与时间 → 开启自动设置
+  - Windows：设置 → 时间和语言 → 日期和时间 → 开启自动同步并“立即同步”
+- **网络连接失败**：检查能否访问 `https://fapi.asterdex.com` 与 `wss://fstream.asterdex.com/ws`。如需代理，先在终端设置 `HTTP_PROXY` / `HTTPS_PROXY`。
+- **订单被拒绝（精度/步长）**：调整 `PRICE_TICK`、`QTY_STEP` 与交易所规则一致。
+- **终端界面无反应**：请在真实终端中运行，不要在只读输出窗口执行。

- API 填写错误（Key/Secret 格式问题）：
-   - 确认 `.env` 中没有多余空格、引号或换行。示例：
-     ```bash
-     ASTER_API_KEY=你的Key
-     ASTER_API_SECRET=你的Secret
-     ```
-   - 避免中文标点或全角字符；从网页复制后，先粘到纯文本再粘回。
-   - 修改 `.env` 后，重新打开终端或重新运行命令以生效。
+更多细节请参考主仓库的 [README](README.md)。

- 本地时间与交易所时间不同步（签名/时间戳错误）：
-   - 现象：HTTP 4xx 提示 `timestamp expired` / `invalid signature`。
-   - macOS：系统设置 → 通用 → 日期与时间 → 开启“自动设置日期与时间”。
-   - Windows：设置 → 时间和语言 → 日期和时间 → 开启“自动设置时间”，并点击“立即同步”。
-   - 命令行快速同步（可选）：
-     - macOS：
-       ```bash
-       sudo sntp -sS time.apple.com
-       ```
-     - Windows（管理员 PowerShell）：
-       ```powershell
-       w32tm /resync
-       ```
-     - Linux：
-       ```bash
-       sudo timedatectl set-ntp true
-       ```
-
- 无法访问外网/需要代理：
-   - 现象：`curl https://bun.sh` 超时、连接 `fapi.asterdex.com` / `fstream.asterdex.com` 失败。
-   - 临时为当前终端配置代理（按本地代理端口调整 7890/1080 等）：
-     - macOS / Linux：
-       ```bash
-       export HTTP_PROXY=http://127.0.0.1:7890
-       export HTTPS_PROXY=http://127.0.0.1:7890
-       ```
-     - Windows PowerShell：
-       ```powershell
-       $env:HTTP_PROXY="http://127.0.0.1:7890"
-       $env:HTTPS_PROXY="http://127.0.0.1:7890"
-       ```
-   - 验证连通性：
-     ```bash
-     curl -I https://fapi.asterdex.com
-     ```
-   - 公司/校园网络可能屏蔽 WebSocket（wss://）；必要时切换到个人网络或 VPN。
-
- 下单精度/步长或交易对不匹配：
-   - 现象：下单被拒，提示精度/步长错误。
-   - 处理：在 `.env` 中调整 `TRADE_SYMBOL`、`PRICE_TICK`、`QTY_STEP` 与交易所规则一致。
 ---

-## 9. 风险提示
+## 8. 继续深入
+- 高级策略说明：`legacy/docs/`
+- 英文文档：`README_en.md`
+- 社区支持：Telegram 群组 <https://t.me/+4fdo0quY87o4Mjhh>

-量化策略并非稳赚不赔。请从小额开始，先在仿真或小资金环境验证，逐步加大。务必妥善保管 API 密钥，并只开启必要权限。
+祝你部署顺利，交易安全！